---
title: "@unikvs/redis.bun"
description: "Bun から Redis にバイト列を保存する @unikvs/redis.bun の使い方を説明します。"
---

## 概要 [#overview]

`@unikvs/redis.bun` は Redis にバイト列を保存するストレージプラグインです。Bun 専用 複数ノードで共有するキャッシュや一時データの保存に使います。

- `name` は `"Redis"` で、`isOpen` で開閉状態を確認します。
- `open()` で接続し、使い終わったら `close()` で切断します。
- このストレージは、キーに既定で `"unikvs:"` の接頭辞を付与し、`clear()` の削除範囲を限定します。
- 接続先 URL を省略した場合は、クライアントが環境変数（`REDIS_URL`、`VALKEY_URL`）から解決します。

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

```package-install
npm install @unikvs/redis.bun
```

別途 Redis サーバーが必要です。

## 使い方 [#usage]

Redis は IStorage を実装しています。UniKvs には persist() で渡します。

```ts
import { Redis } from "@unikvs/redis.bun";
```

### Redis [#redis]

Redis に保存するストレージです。利用者は `open()` で開き、使い終わったら `close()` で閉じます。

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

| Prop | Type | Default | Description |
| - | - | - | - |
| `url?` | `[#redis-url] string \| undefined` | - | 接続先 URL です。省略時はクライアントが環境変数から解決します。 |
| `options?` | `[#redis-options] RedisStorageOptions` | - | クライアントと本パッケージの動作を設定するオプションです。 |

### RedisStorageOptions [#redisstorageoptions]

Bun の `RedisOptions` に本パッケージ固有の項目を加えた設定型です。Bun の項目はそのまま透過します。

| Prop | Type | Default | Description |
| - | - | - | - |
| `keyPrefix?` | `[#redisstorageoptions-keyprefix] string` | - | すべてのキーに付与する接頭辞です。既定値は `"unikvs:"` です。空文字を指定するとキーをそのまま使います。 |

以下は、値を保存して読み戻す例です。

```ts
import { Redis } from "@unikvs/redis.bun";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new Redis("redis://127.0.0.1:6379"))
  .build();

await kvs.open();

await kvs.set("file", new Uint8Array([0, 1, 2]));

const data = await kvs.get("file");
console.log(data); // Uint8Array(3) [0, 1, 2]

await kvs.close();
```

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

| 操作                                    | 対応するデータ型          |
| --------------------------------------- | ------------------------- |
| `write`・`read`                         | `Uint8Array<ArrayBuffer>` |
| `getWritable`・`getReadable` のチャンク | `Uint8Array<ArrayBuffer>` |

- `write`・`read` にはバイト列 (`Uint8Array<ArrayBuffer>`) を使います。
- ストリームの読み書きに対応し、チャンクは `Uint8Array<ArrayBuffer>` です。
- 書き込みストリームは一時キーへ追記し、完了時にリネームで原子的に置き換えます。
- 読み取りストリームは取得したバイト列を単一のチャンクとして送出します。

## エラー [#errors]

このパッケージ固有のエラーはありません。存在しないキーの読み取りは `@unikvs/core` の共通エラー `KeyNotFoundError` を投げ、Bun 以外のランタイムで開こうとすると共通エラー `UnsupportedRuntimeError` を投げます。