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

## 概要 [#overview]

バイト列を 16 進文字列化して返すミドルウェアです。Middleware

このミドルウェアはエンコード時は小文字で出力し、デコード時は大文字と小文字のどちらも受け付けます。

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

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

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

## 使い方 [#usage]

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

```ts
import { Hex } from "@unikvs/hex";
```

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

| Prop | Type | Default | Description |
| - | - | - | - |
| `encoder?` | `[#hex-encoder] FastUtf8` | - | 文字列のバイト列化に使う実体です。省略時は既定値を使います。 |
| `decoder?` | `[#hex-decoder] FastUtf8` | - | バイト列の文字列化に使う実体です。省略時は既定値を使います。 |

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

```ts
import { Hex } from "@unikvs/hex";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

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

await kvs.open();
await kvs.set("file", new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
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` はバイト列を小文字の 16 進文字列に変換し、UTF-8 でバイト列化します。
- `decode` は 16 進文字列化されたバイト列を元のバイト列に戻します。
- デコード時は大文字と小文字のどちらも受け付けます。
- `encodeStream` はチャンクごとに変換し、順番に連結します。
- 空のチャンクはエンコードに影響しないため、このミドルウェアは無視します。
- `decodeStream` は 2 文字単位で復元し、奇数量の末尾 1 文字を次回に持ち越します。
- ストリームの終了時に残りがある場合は、このミドルウェアはエラーを投げます。

## エラー [#errors]

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

### `HexDecodeError` [#error-hex-decode]

#### 意味

このミドルウェアは入力を 16 進文字列として解釈できないときに、このエラーを投げます。奇数長の入力や、16 進数以外の文字を含む入力が対象です。

#### 対処方法

入力が偶数長の 16 進文字列か確認してください。

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