@unikvs/core

全パッケージで共有する型と共通エラーを提供する @unikvs/core の概要です。

概要

@unikvs/core は、UniKVS の全パッケージで共有する型と共通エラーのパッケージです。ストレージとトランスフォーマーのインターフェース、実行時変数、エラーの基底クラスをまとめています。

自作プラグインを作る場合を除き、直接触る必要はありません。

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

npm install @unikvs/core

pnpm add @unikvs/core

yarn add @unikvs/core

bun add @unikvs/core

nub add @unikvs/core

aube add @unikvs/core

ストレージ

ストレージはデータを保存する先です。単発の読み書き（write・read・exists・delete・clear）と、大容量データ向けのストリーム読み書き（getWritable・getReadable）を提供します。ストリーム対応は任意で、対応していないストレージではそのメソッドを省略できます。

すべての操作はキャンセル用の signal と実行時設定用の vars を受け付けます。

自作する場合は IStorage を実装します。詳細なシグネチャーは API リファレンスを参照してください。

トランスフォーマー

トランスフォーマーはデータを透過的に変換します。単発の変換（encode・decode）は必須で、ストリーム変換（getEncodable・getDecodable）は任意です。

すべての操作は signal によるキャンセルと vars の受け渡しに対応します。

自作する場合は ITransformer を実装します。詳細なシグネチャーは API リファレンスを参照してください。

変数

操作の挙動を切り替える実行時コンテキストを変数として渡せます。ビルダーの setVariables() で初期値を設定し、操作ごとの vars で上書きできます。

import type { Variables } from "@unikvs/core";

const vars: Variables = {
  locale: "ja",
  retryCount: 3,
};

エラー

UniKVS のエラーはすべて ErrorBase を継承し、日本語と英語のメッセージに対応しています。instanceof で種類を判別できます。

共通エラー

エラークラス	説明
`KeyNotFoundError`	キーが見つかりません。存在しないキーの読み取りなどで発生します。各ストレージパッケージから再エクスポートされています。
`UnsupportedRuntimeError`	対応ランタイム以外で使われました。Bun 専用ストレージを Node.js で開く場合などに発生します。
`InvalidPartSizeError`	マルチパートアップロードのパートサイズ指定が不正です。
`StorageAbortedError`	中断済みのシグナルで書き込みストリームを要求しました。
`RepairNotAllowedError`	書き戻しが許可されていないストレージへの書き戻しです。
`InvalidUsageErrorBase`	使い方の誤りを示すエラーの基底クラスです。

import { KeyNotFoundError } from "@unikvs/core";

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

自作プラグインでのエラー定義

ErrorBase か InvalidUsageErrorBase を継承します。使い方の誤りには InvalidUsageErrorBase を使います。
必要ならメタ情報の型を指定します。
setErrorMessage で言語ごとのメッセージを登録します。

import { ErrorBase, setErrorMessage } from "@unikvs/core";

type MyMeta = {
  readonly key: string;
};

export class MyStorageError extends ErrorBase<MyMeta> {}

setErrorMessage(MyStorageError, (meta) => `キー ${meta.key} の書き込みに失敗しました。`, "ja");
setErrorMessage(MyStorageError, (meta) => `Failed to write key ${meta.key}.`, "en");