自作プラグイン

Storage と Transformer の自作方法と実装時の注意点を説明します。

インターフェースの全体像

プラグインは @unikvs/core の型に従って作ります。ストレージは保存先、トランスフォーマーは透過的な変換を担当します。

詳細なシグネチャーは @unikvs/core を参照してください。

ストレージの実装

1. write・read・exists・delete・clear を正確に実装します。
2. 存在しないキーの read・delete ではキー未検出エラーを投げます。
3. 必要なら open・close・isOpen を実装します。不要なら常時オープン扱いにできます。メモリーは常時オープンの例です。
4. ストリーム保存が必要なら書き込み用と読み込み用の取得処理を追加し、バイト列以外を受け取った場合の扱いを決めます。
5. ファイル名やキーに制約がある場合は、@unikvs/utils の検証関数を再利用します。

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

export default class MyStorage implements IStorage {
  public readonly name = "MyStorage";

  public get isOpen(): boolean {
    return true;
  }

  public write(args: Pick<IStorage.WriteArgs<any>, "key" | "data">): void {
    // 保存処理を実装します
  }

  public read(args: Pick<IStorage.ReadArgs, "key">): unknown {
    // 取得処理を実装します
  }

  public exists(args: Pick<IStorage.ExistsArgs, "key">): boolean {
    // 存在確認を実装します
    return false;
  }

  public delete(args: Pick<IStorage.DeleteArgs, "key">): void {
    // 削除処理を実装します
  }

  public clear(): void {
    // 全削除処理を実装します
  }
}

上記は構造の例です。引数と戻り値の詳細はコアの型定義に従ってください。

トランスフォーマーの実装

1. エンコードとデコードの対応を明確にし、往復で元に戻ることを単体テストで確認します。
2. ストリーム変換の対応可否を明確にし、未対応なら対応するエラーを投げます。
3. 追加情報が必要なら実行時変数で受け取ります。チェックサムのハッシュ指定がその例です。
4. 必要なら open・close を実装します。

エラー定義

ErrorBase を継承し、説明・原因・解決方法を含むメッセージを定義します。i18n 対応できます。InvalidFilenameError やチェックサム不一致エラーが参考になります。

テストの観点

• 保存して取得した値が一致することを確認します。
• 未検出キー、空データ、大容量データの境界を確認します。
• ストリーム対応がある場合は、複数チャンクの結合と中断時の挙動を確認します。
• 複数ストレージ構成での動作を確認します。