URL Encoder の設計

URL に日本語や特殊文字が含まれる場合、それをそのまま使用するとサーバーや ブラウザによって予期しない解釈がされることがあります。 HTTP仕様では、URL に使用できる文字は ASCII の一部に限定されており、 それ以外の文字はパーセントエンコーディング（%XX 形式）に 変換する必要があります。

APIを開発する際のクエリパラメータの組み立て、Webスクレイピング時のURL加工、 SNSシェアリンクの生成など、エンコード/デコードの需要は多岐にわたります。 ブラウザのアドレスバーに貼り付けるだけで自動エンコードされる場合でも、 プログラムから直接HTTPリクエストを送る場合は手動でのエンコードが必要です。

encodeUrl(input: string): UrlConvertOutput とdecodeUrl(input: string): UrlConvertOutput の2関数で構成されます。 どちらも UrlConvertOutput（Success | Error の Union型）を返し、 例外を外部に漏らさない設計です。

decodeUrl() はブラウザ標準の decodeURIComponent() をラップしており、 不正な % シーケンス（例: %GH）が入力された場合にURIError がthrowされます。 これを catch でキャッチしてエラーオブジェクトとして返すことで、 Layer 2（Client Component）は try-catch を書かずに 型安全にエラー状態を扱えます。

エンコードは encodeURIComponent() を直接使用します。 この関数は RFC 3986 で定義された非予約文字（英数字 A-Z a-z 0-9 と - _ . ~）以外の文字を すべて %XX 形式に変換します。

例えば、日本語の「こんにちは」は UTF-8 でエンコードされた後にパーセント表記され、%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF のような文字列になります。 スペースは %20、& は %26 に変換されます。

デコードは decodeURIComponent() の逆変換です。%E3%81%93 → こ のように、 UTF-8バイト列を対応するUnicode文字に復元します。 不正なシーケンス（% 単独や %GH など）はURIError としてキャッチされ、ユーザーにエラーメッセージを返します。

src/lib/tools/__tests__/url-encoder.test.ts に Vitest による単体テストを実装しています。

• 日本語エンコード/デコード: 日本語文字列を往復変換して 元の値に戻ることを確認。
• 特殊文字: &・=・+・# などのURLで特別な意味を持つ文字の正確なエンコードを確認。
• 不正シーケンス: %GH・%（末尾のみ）などの 不正な入力でエラーが返ることを確認。
• 空文字列: 空入力で適切なエラーメッセージが返ることを確認。