---
title: "@unikvs/base64url"
description: "バイト列を base64url 化するミドルウェア @unikvs/base64url の使い方を説明します。"
---

## 概要 [#overview]

バイト列を URL セーフな base64url 文字列化して返すミドルウェアです。Middleware

このミドルウェアは `+` と `/` を使わないため、URL やファイル名に埋め込む用途に向いています。パディングありとなしの両形式に対応し、デコード時はどちらも受け付けます。

- `name` は `"Base64Url"` です。
- `isOpen` はつねに `true` です。

インストールは次のコマンドで行います。

```package-install
npm install @unikvs/base64url
```

## 使い方 [#usage]

Base64Url は IMiddleware を実装しています。UniKvs には use() で渡します。

```ts
import { Base64Url } from "@unikvs/base64url";
```

コンストラクターの引数は次のとおりです。

| Prop | Type | Default | Description |
| - | - | - | - |
| `encoder?` | `[#base64url-encoder] FastUtf8` | - | 文字列のバイト列化に使う実体です。省略時は既定値を使います。 |
| `decoder?` | `[#base64url-decoder] FastUtf8` | - | バイト列の文字列化に使う実体です。省略時は既定値を使います。 |
| `padding?` | `[#base64url-padding] boolean` | - | エンコード時に `=` を付与するかどうかです。省略時は `false` です。 |

以下は、バイト列を base64url 化して保存し、読み取り時に元のバイト列へ戻す例です。

```ts
import { Base64Url } from "@unikvs/base64url";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .use(new Base64Url())
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("file", new Uint8Array([0x01, 0x02, 0x03]));
const file = await kvs.get("file");
await kvs.close();
```

## データ型 [#data-types]

| メソッド       | 入力                      | 出力                      |
| -------------- | ------------------------- | ------------------------- |
| `encode`       | `Uint8Array<ArrayBuffer>` | `Uint8Array<ArrayBuffer>` |
| `decode`       | `Uint8Array<ArrayBuffer>` | `Uint8Array<ArrayBuffer>` |
| `encodeStream` | `Uint8Array<ArrayBuffer>` | `Uint8Array<ArrayBuffer>` |
| `decodeStream` | `Uint8Array<ArrayBuffer>` | `Uint8Array<ArrayBuffer>` |

- `encode` はバイト列を base64url 文字列に変換し、UTF-8 でバイト列化します。
- `decode` は base64url 化されたバイト列を元のバイト列に戻します。
- デコード時はパディングありとなしのどちらの形式も受け付けます。
- `encodeStream` は 3 バイト単位で区切り、チャンクをまたいだ余りを次回に持ち越します。
- エンコード時の余りはストリームの終了時に確定します。
- `decodeStream` は 4 文字単位で復元し、余りを次回に持ち越します。
- パディングを含む末尾はストリームの終了時に検証して復元します。

## エラー [#errors]

このパッケージが投げるエラーは次のとおりです。

### `Base64UrlDecodeError` [#error-base64url-decode]

#### 意味

このミドルウェアは入力を base64url として解釈できないときに、このエラーを投げます。不正な文字や誤った `=` の配置、長さの余りが 1 になる入力が対象です。

#### 対処方法

入力が正しい base64url か確認してください。

なお、ストリーム終端で UTF-8 の途中バイトが残った場合は、`TypeError` がそのまま伝播します。

### `Base64UrlInvalidPaddingError` [#error-base64url-invalid-padding]

`padding` オプションに真偽値以外を指定すると、このエラーが投げられます。

| Prop | Type | Default | Description |
| - | - | - | - |
| `actual` | `[#base64url-invalid-padding-actual] unknown` | - | 指定された `padding` の値です。 |

#### 意味

使い方の誤りのため、`InvalidUsageErrorBase` を継承します。`meta.actual` に指定値をそのまま保持します。

#### 対処方法

`padding` に `true` か `false` を指定してください。省略時は `false` です。