@unikvs/redis.node

Node.js から Redis にバイト列を保存する @unikvs/redis.node の使い方を説明します。

概要

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

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

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

npm install @unikvs/redis.node

pnpm add @unikvs/redis.node

yarn add @unikvs/redis.node

bun add @unikvs/redis.node

nub add @unikvs/redis.node

aube add @unikvs/redis.node

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

使い方

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

import { Redis } from "@unikvs/redis.node";

Redis

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

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

RedisStorageOptions

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

RedisClusterSpec

クラスターの接続先を指定する型です。v1 では未対応のため、指定するとエラーになります。

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

import { Redis } from "@unikvs/redis.node";
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();

データ型

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

エラー

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

ClusterNotSupportedError

コンストラクターの cluster オプションが指定されたときに投げます。

意味

v1 はスタンドアロンモードのみに対応し、cluster オプションはサポートされていません。

対処方法

cluster オプションを指定せず、スタンドアロンの Redis に接続してください。

InvalidCloseTimeoutError

コンストラクターの closeTimeout が有限の正数ではないときに投げます。

意味

closeTimeout に有限の正数 (ミリ秒) 以外が指定されました。

対処方法

closeTimeout に有限の正数 (ミリ秒) を指定してください。

ConnectTimeoutError

open() 時の接続がタイムアウトしたときに投げます。

意味

Redis への接続が connectTimeout (既定値は 5000 ミリ秒) を超えても確立しませんでした。

対処方法

サーバーの起動状態と接続先 URL を確認し、必要に応じて connectTimeout を延ばしてください。

CloseTimeoutError

close() 時の切断がタイムアウトしたときに投げます。

意味

Redis からの切断処理が closeTimeout を超えても終わりませんでした。接続は切断して掃除します。

対処方法

サーバーの状態を確認し、繰り返す場合は closeTimeout を延ばしてください。

KeyNotFoundError

@unikvs/core の共通エラーです。存在しないキーを読み取ったときに投げます。

意味

指定したキーが存在しません。@unikvs/core の共通エラーです。

対処方法

exists で確認してから読み出してください。

例

以下は、KeyNotFoundError を捕捉する例です。

import { KeyNotFoundError } from "@unikvs/redis.node";

try {
  const data = await kvs.get("missing");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("キーが見つかりません");
  } else {
    throw ex;
  }
}