---
title: "@unikvs/v8-serde"
description: "値を node:v8 でシリアライズする Node.js 専用ミドルウェア @unikvs/v8-serde の使い方を説明します。"
---

## 概要 [#overview]

値を `node:v8` のシリアライザーで変換するミドルウェアです。Middleware Node.js 専用

単発の読み書きでは値をそのままシリアライズし、ストリームでは 4 バイトのビッグエンディアン長と本体からなるフレームを連結して変換します。

- `name` は `"V8Serde"` です。
- `isOpen` は `open()` の完了後に `true` になります。
- `node:v8` が使えない環境では `open()` が失敗します。

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

```package-install
npm install @unikvs/v8-serde
```

## 使い方 [#usage]

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

```ts
import { V8Serde } from "@unikvs/v8-serde";
```

以下は、オブジェクトをシリアライズして保存し、読み取り時に元の形へ戻す例です。

```ts
import { V8Serde } from "@unikvs/v8-serde";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ item: unikvs.Value<{ readonly id: number }> }>()
  .use(new V8Serde())
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("item", { id: 1 });
const item = await kvs.get("item");
await kvs.close();
```

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

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

- `encode` は値を `v8.serialize` でバイト列化します。使う前に `open()` を呼ぶ必要があります。
- `decode` はバイト列を `v8.deserialize` で値に戻します。使う前に `open()` を呼ぶ必要があります。
- `encodeStream` は入力 1 件ごとに長さ付きフレーム (4 バイトのビッグエンディアン長と本体) を出力し、順番に連結します。
- `decodeStream` は受信したバイト列を蓄積し、フレームがそろった値から順に出力します。
- 途中で切れたフレームは次のチャンクの到着を待ち、終了時に残余がある場合はエラーを投げます。
- 空のチャンクはデコードに影響しないため、このミドルウェアは無視します。

## エラー [#errors]

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

### `V8SerdeEncodeError` [#error-v8-serde-encode]

#### 意味

値の `v8.serialize` エンコードに失敗したときに、このエラーが投げられます。失敗の原因は `cause` に保持されます。

#### 対処方法

`cause` を確認し、`v8.serialize` で扱える値を渡してください。

### `V8SerdeDecodeError` [#error-v8-serde-decode]

#### 意味

データの `v8.deserialize` デコードに失敗したときに、このエラーが投げられます。破損した入力や、ストリーム終端に残った未完成のフレームが対象です。失敗の原因は `cause` に保持されます。

#### 対処方法

入力が `v8.serialize` で作られた正しいデータであり、ストリームが途中で切れていないか確認してください。

### `UnsupportedRuntimeError` [#error-unsupported-runtime]

#### 意味

`node:v8` が使えない環境で `open()` したときに、このエラーが投げられます。[`@unikvs/core` の共通エラー](/unikvs/packages/core/errors#error-unsupported-runtime)です。

#### 対処方法

Node.js 環境で使ってください。