---
title: "@unikvs/cbor"
description: "値を CBOR でシリアライズするミドルウェア @unikvs/cbor の使い方を説明します。"
---

## 概要 [#overview]

値を CBOR でシリアライズするミドルウェアです。Middleware

単発の読み書きでは値をそのまま CBOR のバイト列に変換し、ストリームでは CBOR アイテムを連結したシーケンスとして変換します。

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

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

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

## 使い方 [#usage]

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

```ts
import { Cbor } from "@unikvs/cbor";
```

以下は、オブジェクトを CBOR 化して保存し、読み取り時に元の形へ戻す例です。

```ts
import { Cbor } from "@unikvs/cbor";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ item: unikvs.Value<{ readonly id: number }> }>()
  .use(new Cbor())
  .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` は値を CBOR のバイト列に変換します。
- `decode` は CBOR のバイト列を値に戻します。
- `encodeStream` は入力 1 件ごとに 1 つの CBOR アイテムを出力し、順番に連結します。
- `decodeStream` は受信したバイト列を蓄積し、完成した値から順に出力します。
- 途中で切れたデータは次のチャンクの到着を待ち、終了時に残余がある場合はエラーを投げます。
- 空のチャンクはデコードに影響しないため、このミドルウェアは無視します。

## エラー [#errors]

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

### `CborEncodeError` [#error-cbor-encode]

#### 意味

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

#### 対処方法

`cause` を確認し、CBOR で表現できる値を渡してください。

### `CborDecodeError` [#error-cbor-decode]

#### 意味

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

#### 対処方法

入力が正しい CBOR データであり、ストリームが途中で切れていないか確認してください。