unikvs 0.0.3 → 0.0.4

package/src/unikvs.ts

@@ -0,0 +1,1171 @@
+import type { Context, IReadableStream, Key } from "@unikvs/core";
+import { asyncmux, Asyncmux, type AsyncmuxLock } from "asyncmux";
+import * as v from "valibot";
+
+import combineSignals from "./_combine-signals.js";
+import logger from "./_logger.js";
+import mergeContext from "./_merge-context.js";
+import { UniKvsStorage } from "./_storage.js";
+import toValueStream from "./_to-value-stream.js";
+import UniKvsTransformer from "./_transformer.js";
+import { parse } from "./_valibot.js";
+import type { ContextSource } from "./context.types.js";
+import {
+  KeyNotFoundError,
+  PluginOperationAggregateError,
+  UniKvsIsNotOpenError,
+  UniKvsIsOpenError,
+} from "./errors.js";
+import UniKvsConfig, {
+  type $InferPlainValueData,
+  type $InferStreamValueChunkData,
+  type IUniKvsConfigBuilder,
+  type KeyofKeyValueMapping,
+  type KeyValueMapping,
+  type PlainValue,
+  type StreamValue,
+  type Value,
+} from "./unikvs-config.js";
+import type { ValueOf } from "./utils.types.js";
+import type { ValueStream } from "./value-stream.types.js";
+
+// -------------------------------------------------------------------------------------------------
+//
+// ユーティリテー
+//
+// -------------------------------------------------------------------------------------------------
+
+/**
+ * 設定可能な値の型定義です。
+ *
+ * @template TValue 値の型定義です。
+ */
+export type SetValue<TValue extends Value> =
+  | $InferPlainValueData<TValue>
+  | (TValue extends StreamValue<infer TChunkData> ? ReadableStream<TChunkData> : never);
+
+/**
+ * プレーンな値を持つキーのみを抽出する型定義です。
+ *
+ * @template TKeyValueMapping キーと値のマッピング定義です。
+ */
+export type KeyofKeyValueMappingHasPlainValue<TKeyValueMapping extends KeyValueMapping> = ValueOf<{
+  [TKey in KeyofKeyValueMapping<TKeyValueMapping>]: PlainValue extends TKeyValueMapping[TKey]
+    ? TKey
+    : never;
+}>;
+
+/**
+ * ストリーム形式の値を持つキーのみを抽出する型定義です。
+ *
+ * @template TKeyValueMapping キーと値のマッピング定義です。
+ */
+export type KeyofKeyValueMappingHasStreamValue<TKeyValueMapping extends KeyValueMapping> = ValueOf<{
+  [TKey in KeyofKeyValueMapping<TKeyValueMapping>]: StreamValue extends TKeyValueMapping[TKey]
+    ? TKey
+    : never;
+}>;
+
+// -------------------------------------------------------------------------------------------------
+//
+// 型定義
+//
+// -------------------------------------------------------------------------------------------------
+
+/**
+ * オープン操作時のオプションです。
+ */
+export type OpenOptions = {
+  /**
+   * 処理の中断を通知するためのシグナルです。
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * 実行時のコンテキスト情報です。
+   */
+  readonly context?: ContextSource | undefined;
+};
+
+/**
+ * クローズ操作時のオプションです。
+ */
+export type CloseOptions = {
+  /**
+   * 処理の中断を通知するためのシグナルです。
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * 実行時のコンテキスト情報です。
+   */
+  readonly context?: ContextSource | undefined;
+};
+
+/**
+ * 保存操作時のオプションです。
+ *
+ * @template TKeyValueMapping キーと値のマッピング定義です。
+ * @template TKey 対象となるキーの型です。
+ */
+export type SetOptions<
+  TKeyValueMapping extends KeyValueMapping = KeyValueMapping,
+  TKey extends KeyofKeyValueMapping<TKeyValueMapping> = KeyofKeyValueMapping<TKeyValueMapping>,
+> = {
+  /**
+   * 操作対象を識別するためのキーです。
+   */
+  readonly key: TKey;
+
+  /**
+   * 保存する値です。
+   */
+  readonly value: SetValue<TKeyValueMapping[TKey]>;
+
+  /**
+   * 処理の中断を通知するためのシグナルです。
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * 実行時のコンテキスト情報です。
+   */
+  readonly context?: ContextSource | undefined;
+};
+
+/**
+ * 取得操作時のオプションです。
+ *
+ * @template TKey 対象となるキーの型です。
+ */
+export type GetOptions<TKey = Key> = {
+  /**
+   * 操作対象を識別するためのキーです。
+   */
+  readonly key: TKey;
+
+  /**
+   * 処理の中断を通知するためのシグナルです。
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * 実行時のコンテキスト情報です。
+   */
+  readonly context?: ContextSource | undefined;
+};
+
+/**
+ * ストリーム取得操作時のオプションです。
+ *
+ * @template TKey 対象となるキーの型です。
+ */
+export type StreamOptions<TKey = Key> = {
+  /**
+   * 操作対象を識別するためのキーです。
+   */
+  readonly key: TKey;
+
+  /**
+   * 処理の中断を通知するためのシグナルです。
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * 実行時のコンテキスト情報です。
+   */
+  readonly context?: ContextSource | undefined;
+};
+
+/**
+ * 存在確認操作時のオプションです。
+ *
+ * @template TKey 対象となるキーの型です。
+ */
+export type HasOptions<TKey = Key> = {
+  /**
+   * 操作対象を識別するためのキーです。
+   */
+  readonly key: TKey;
+
+  /**
+   * 処理の中断を通知するためのシグナルです。
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * 実行時のコンテキスト情報です。
+   */
+  readonly context?: ContextSource | undefined;
+};
+
+/**
+ * 削除操作時のオプションです。
+ *
+ * @template TKey 対象となるキーの型です。
+ */
+export type DeleteOptions<TKey = Key> = {
+  /**
+   * 操作対象を識別するためのキーです。
+   */
+  readonly key: TKey;
+
+  /**
+   * 処理の中断を通知するためのシグナルです。
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * 実行時のコンテキスト情報です。
+   */
+  readonly context?: ContextSource | undefined;
+};
+
+/**
+ * 全削除操作時のオプションです。
+ */
+export type ClearOptions = {
+  /**
+   * 処理の中断を通知するためのシグナルです。
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * 実行時のコンテキスト情報です。
+   */
+  readonly context?: ContextSource | undefined;
+};
+
+// -------------------------------------------------------------------------------------------------
+//
+// スキーマ
+//
+// -------------------------------------------------------------------------------------------------
+
+const ContextKeySchema = v.union([v.string(), v.symbol(), v.number()]);
+
+const ContextSourceSchema = v.union([
+  v.record(v.any(), v.unknown()),
+  v.array(v.tuple([ContextKeySchema, v.unknown()])),
+]);
+
+const OpenOptionsSchema = v.object({
+  signal: v.optional(v.instance(AbortSignal)),
+  context: v.optional(ContextSourceSchema),
+});
+
+const OpenArgsSchema = v.tuple([v.optional(OpenOptionsSchema)]);
+
+const CloseOptionsSchema = v.object({
+  signal: v.optional(v.instance(AbortSignal)),
+  context: v.optional(ContextSourceSchema),
+});
+
+const CloseArgsSchema = v.tuple([v.optional(CloseOptionsSchema)]);
+
+const SetOptionsSchema = v.object({
+  key: v.string(),
+  value: v.unknown(),
+  signal: v.optional(v.instance(AbortSignal)),
+  context: v.optional(ContextSourceSchema),
+});
+
+const SetArgsSchema = v.union([
+  v.tuple([SetOptionsSchema]),
+  v.pipe(
+    v.tuple([
+      SetOptionsSchema.entries.key,
+      SetOptionsSchema.entries.value,
+      v.optional(v.omit(SetOptionsSchema, ["key", "value"])),
+    ]),
+    v.transform(([key, value, options]) => [{ ...options, key, value }]),
+  ),
+]);
+
+const GetOptionsSchema = v.object({
+  key: v.string(),
+  signal: v.optional(v.instance(AbortSignal)),
+  context: v.optional(ContextSourceSchema),
+});
+
+const GetArgsSchema = v.union([
+  v.tuple([GetOptionsSchema]),
+  v.pipe(
+    v.tuple([GetOptionsSchema.entries.key, v.optional(v.omit(GetOptionsSchema, ["key"]))]),
+    v.transform(([key, options]) => [{ ...options, key }]),
+  ),
+]);
+
+const StreamOptionsSchema = v.object({
+  key: v.string(),
+  signal: v.optional(v.instance(AbortSignal)),
+  context: v.optional(ContextSourceSchema),
+});
+
+const StreamArgsSchema = v.union([
+  v.tuple([StreamOptionsSchema]),
+  v.pipe(
+    v.tuple([StreamOptionsSchema.entries.key, v.optional(v.omit(StreamOptionsSchema, ["key"]))]),
+    v.transform(([key, options]) => [{ ...options, key }]),
+  ),
+]);
+
+const HasOptionsSchema = v.object({
+  key: v.string(),
+  signal: v.optional(v.instance(AbortSignal)),
+  context: v.optional(ContextSourceSchema),
+});
+
+const HasArgsSchema = v.union([
+  v.tuple([HasOptionsSchema]),
+  v.pipe(
+    v.tuple([HasOptionsSchema.entries.key, v.optional(v.omit(HasOptionsSchema, ["key"]))]),
+    v.transform(([key, options]) => [{ ...options, key }]),
+  ),
+]);
+
+const DeleteOptionsSchema = v.object({
+  key: v.string(),
+  signal: v.optional(v.instance(AbortSignal)),
+  context: v.optional(ContextSourceSchema),
+});
+
+const DeleteArgsSchema = v.union([
+  v.tuple([DeleteOptionsSchema]),
+  v.pipe(
+    v.tuple([DeleteOptionsSchema.entries.key, v.optional(v.omit(DeleteOptionsSchema, ["key"]))]),
+    v.transform(([key, options]) => [{ ...options, key }]),
+  ),
+]);
+
+const ClearOptionsSchema = v.object({
+  signal: v.optional(v.instance(AbortSignal)),
+  context: v.optional(ContextSourceSchema),
+});
+
+const ClearArgsSchema = v.tuple([v.optional(ClearOptionsSchema)]);
+
+// -------------------------------------------------------------------------------------------------
+//
+// UniKvs
+//
+// -------------------------------------------------------------------------------------------------
+
+/**
+ * ストリームの読み取りロックを自動解放するための FinalizationRegistry です。
+ */
+const ioLockRegistry: FinalizationRegistry<AsyncmuxLock> | null =
+  typeof FinalizationRegistry !== "function"
+    ? null
+    : new FinalizationRegistry((lock) => {
+        try {
+          lock.unlock();
+        } catch {}
+      });
+
+/**
+ * 接続状態を管理する内部オブジェクトです。
+ */
+type Connection = {
+  /**
+   * 接続全体を管理する AbortController です。
+   */
+  readonly conAc: AbortController;
+
+  /**
+   * I/O の多重化を制御する Asyncmux インスタンスです。
+   */
+  readonly ioMux: Asyncmux;
+};
+
+/**
+ * UniKvs メインクラスです。
+ *
+ * 複数のストレージとトランスフォーマーを統合して KVS 操作を提供します。
+ *
+ * @template TKeyValueMapping キーと値のマッピング定義です。
+ */
+export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueMapping> {
+  /**
+   * UniKvs の設定ビルダーを作成します。
+   *
+   * @template TKeyValueMapping マッピング定義です。
+   * @returns 設定ビルダーのインスタンスです。
+   * @example
+   * ```typescript
+   * import { Compression } from "@unikvs/compression";
+   * import { FileSystem } from "@unikvs/fs.node";
+   * import { UniKvs, type Value } from "unikvs";
+   *
+   * const kvs = UniKvs.config<{
+   *   foo: Value<Uint8Array<ArrayBuffer>>;
+   * }>()
+   *   .appendTransformer(new Compression("gzip"))
+   *   .appendStorage(new FileSystem(".tmp"))
+   *   .create();
+   *
+   * await kvs.open();
+   *
+   * await kvs.set("foo", Uint8Array.from([0, 1, 2]));
+   *
+   * await kvs.close();
+   * ```
+   */
+  public static config<
+    TKeyValueMapping extends KeyValueMapping,
+  >(): IUniKvsConfigBuilder<TKeyValueMapping> {
+    return new UniKvsConfig(this);
+  }
+
+  /**
+   * 現在の接続状態です。非接続時は null となります。
+   */
+  #con: Connection | null;
+
+  /**
+   * 基本となる実行コンテキスト情報です。
+   */
+  readonly #context: Readonly<Context>;
+
+  /**
+   * データの永続化先となるストレージのリストです。
+   */
+  readonly #destinations: readonly [UniKvsStorage, ...UniKvsStorage[]];
+
+  /**
+   * データの変換を行うトランスフォーマーのリストです。
+   */
+  readonly #transformers: readonly UniKvsTransformer[];
+
+  /**
+   * インスタンスを初期化します。
+   *
+   * @internal UniKvs の設定ビルダー経由で使用します。
+   * @param context コンテキストです。
+   * @param destinations ストレージのリストです。
+   * @param transformers トランスフォーマーのリストです。
+   */
+  public constructor(
+    context: Readonly<Context>,
+    destinations: readonly [UniKvsStorage, ...UniKvsStorage[]],
+    transformers: readonly UniKvsTransformer[],
+  ) {
+    this.#con = null;
+    this.#context = {
+      ...context,
+      "unikvs:instance": this,
+    };
+    this.#destinations = destinations;
+    this.#transformers = transformers;
+  }
+
+  /**
+   * UniKvs が利用可能であるかを確認します。
+   *
+   * @returns 利用可能である場合は true、そうでない場合は false を返します。
+   */
+  public get isOpen(): boolean {
+    return !!this.#con;
+  }
+
+  /**
+   * すべてのストレージとトランスフォーマーを初期化します。
+   *
+   * @param options オープン時のオプションです。
+   * @returns 完了を通知する Promise です。
+   */
+  public open(options?: OpenOptions): Promise<void>;
+
+  public async open(...args: any): Promise<void> {
+    if (this.#con) {
+      throw new UniKvsIsOpenError();
+    }
+
+    this.#con = {
+      conAc: new AbortController(),
+      ioMux: new Asyncmux(),
+    };
+    try {
+      const [options = {}] = parse(OpenArgsSchema, args);
+      const { signal: signalOption, context: contextOption } = options;
+
+      const { conAc } = this.#con;
+      const signal = combineSignals([conAc.signal, signalOption]);
+
+      const context = mergeContext(this.#context, contextOption);
+      context["unikvs:action"] = "open";
+
+      const openFns: [() => Promise<void>, plugin: "storage" | "transformer"][] = [];
+      const dispose: (() => Promise<void>)[] = [];
+      const lock = await asyncmux(this, signal);
+      try {
+        // ロック待機中に接続状態が変更されていないか再確認します。
+        if (this.#con.conAc !== conAc) {
+          throw new UniKvsIsOpenError();
+        }
+
+        // 各ストレージのオープン処理をリストに追加します。
+        for (const storage of this.#destinations) {
+          openFns.push([
+            async () => {
+              await storage.open(context, signal);
+
+              dispose.push(async () => {
+                try {
+                  await storage.close(context, signal);
+                } catch (ex) {
+                  logger.error`Failed to close storage: ${ex}`;
+                }
+              });
+            },
+            "storage",
+          ]);
+        }
+
+        // 各トランスフォーマーのオープン処理をリストに追加します。
+        for (const transformer of this.#transformers) {
+          openFns.push([
+            async () => {
+              await transformer.open(context, signal);
+
+              dispose.push(async () => {
+                try {
+                  await transformer.close(context, signal);
+                } catch (ex) {
+                  logger.error`Failed to close transformer: ${ex}`;
+                }
+              });
+            },
+            "transformer",
+          ]);
+        }
+
+        // すべての処理を並列に実行し、エラーが発生した場合は集約します。
+        const errors: { plugin: "storage" | "transformer"; reason: unknown }[] = [];
+        await Promise.all(
+          openFns.map(async ([f, plugin]) => {
+            try {
+              await f();
+            } catch (reason) {
+              errors.push({ plugin, reason });
+            }
+          }),
+        );
+        if (errors.length > 0) {
+          throw new PluginOperationAggregateError({ action: "open", errors });
+        }
+      } catch (ex) {
+        this.#con = null; // unlock の前に null に戻します。
+
+        if (dispose.length > 0) {
+          await Promise.all(
+            dispose.map(async (f) => {
+              await f();
+            }),
+          );
+        }
+
+        throw ex;
+      } finally {
+        lock.unlock();
+      }
+    } catch (ex) {
+      this.#con = null;
+      throw ex;
+    }
+  }
+
+  /**
+   * ストレージをクローズします。
+   *
+   * @param options クローズ時のオプションです。
+   * @returns 完了を通知する Promise です。
+   */
+  public close(options?: CloseOptions): Promise<void>;
+
+  public async close(...args: any): Promise<void> {
+    if (!this.#con) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options = {}] = parse(CloseArgsSchema, args);
+    const { signal = AbortSignal.timeout(10e3), context: contextOption } = options;
+
+    const context = mergeContext(this.#context, contextOption);
+    context["unikvs:action"] = "close";
+
+    const { conAc, ioMux } = this.#con;
+    conAc.abort(new UniKvsIsNotOpenError()); // 実行中の他の操作をすべて中断させるために signal を発火させます。
+
+    const lock = await asyncmux(this, signal);
+    try {
+      // ロック待機中に接続状態が変更されていないか再確認します。
+      if (!this.#con) {
+        throw new UniKvsIsNotOpenError();
+      }
+
+      const lock = await ioMux.lock({ signal });
+      try {
+        const closeFns: [() => Promise<void>, plugin: "storage" | "transformer"][] = [];
+
+        // ストレージのクローズ処理を登録します。
+        for (const plugin of this.#destinations) {
+          closeFns.push([
+            async () => {
+              await plugin.close(context, signal);
+            },
+            "storage",
+          ]);
+        }
+
+        // トランスフォーマーのクローズ処理を登録します。
+        for (const plugin of this.#transformers) {
+          closeFns.push([
+            async () => {
+              await plugin.close(context, signal);
+            },
+            "transformer",
+          ]);
+        }
+
+        // すべての処理を並列に実行し、エラーが発生した場合は集約します。
+        const errors: { plugin: "storage" | "transformer"; reason: unknown }[] = [];
+        await Promise.all(
+          closeFns.map(async ([f, plugin]) => {
+            try {
+              await f();
+            } catch (reason) {
+              errors.push({ plugin, reason });
+            }
+          }),
+        );
+        if (errors.length > 0) {
+          throw new PluginOperationAggregateError({ action: "close", errors });
+        }
+      } finally {
+        lock.unlock();
+      }
+    } finally {
+      this.#con = null;
+      lock.unlock();
+    }
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    if (!this.isOpen) {
+      return;
+    }
+
+    await this.close({
+      signal: AbortSignal.timeout(10e3),
+    });
+  }
+
+  /**
+   * 指定したキーに値を保存します。
+   *
+   * @template TKey 対象キーの型定義です。
+   * @param key 操作対象を識別するためのキーです。
+   * @param value 保存する値です。
+   * @param options 追加のオプションです。
+   * @returns 完了を通知する Promise です。
+   */
+  public set<const TKey extends KeyofKeyValueMapping<TKeyValueMapping>>(
+    key: TKey,
+    value: SetValue<TKeyValueMapping[TKey]>,
+    options?: Omit<SetOptions, "key" | "value">,
+  ): Promise<void>;
+
+  /**
+   * 指定したオプションで値を保存します。
+   *
+   * @template TKey 対象キーの型定義です。
+   * @param options セット操作のオプション一式です。
+   * @returns 完了を通知する Promise です。
+   */
+  public set<const TKey extends KeyofKeyValueMapping<TKeyValueMapping>>(
+    options: SetOptions<TKeyValueMapping, TKey>,
+  ): Promise<void>;
+
+  public async set(...args: any): Promise<void> {
+    if (!this.#con) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options] = parse(SetArgsSchema, args);
+    const { key, value, signal: signalOption, context: contextOption } = options;
+
+    const { conAc, ioMux } = this.#con;
+    const signal = combineSignals([conAc.signal, signalOption]);
+
+    const context = mergeContext(this.#context, contextOption);
+    context["unikvs:action"] = "set";
+    context["unikvs:key"] = key;
+
+    const lock = await asyncmux(this, signal);
+    try {
+      // ロック待機中に接続状態が変更されていないか再確認します。
+      if (!this.#con) {
+        throw new UniKvsIsNotOpenError();
+      }
+
+      const errors: { reason: unknown }[] = [];
+      const errorStorageSet = new Set<UniKvsStorage>();
+      if (value instanceof ReadableStream) {
+        // 各トランスフォーマーを通してデータをエンコードストリームへ変換します。
+        let data = value;
+        for (const transformer of this.#transformers) {
+          const e = await transformer.getEncodable(context, signal);
+          data = data.pipeThrough(e);
+        }
+
+        const lock = await ioMux.lock({ key, signal });
+        try {
+          await Promise.all(
+            this.#destinations.map(async (storage, i) => {
+              try {
+                // 複数のストレージがある場合は、tee メソッドを使用してストリームを分岐させます。
+                let r = data;
+                if (i !== this.#destinations.length - 1) {
+                  [r, data] = data.tee();
+                }
+
+                const w = await storage.getWritable(context, signal, key);
+                await r.pipeTo(w, { signal });
+              } catch (reason) {
+                errors.push({ reason });
+                errorStorageSet.add(storage);
+              }
+            }),
+          );
+        } finally {
+          lock.unlock();
+        }
+      } else {
+        // 登録されているトランスフォーマーを順番に適用してデータをエンコードします。
+        let data = value;
+        for (const transformer of this.#transformers) {
+          data = await transformer.encode(context, signal, data);
+        }
+
+        const lock = await ioMux.lock({ key, signal });
+        try {
+          await Promise.all(
+            this.#destinations.map(async (storage) => {
+              try {
+                await storage.write(context, signal, key, data);
+              } catch (reason) {
+                errors.push({ reason });
+                errorStorageSet.add(storage);
+              }
+            }),
+          );
+        } finally {
+          lock.unlock();
+        }
+      }
+
+      // エラーが発生した場合は集約します。
+      if (errors.length > 0) {
+        const error = new PluginOperationAggregateError({
+          plugin: "storage",
+          action: "write",
+          errors,
+        });
+        {
+          const errors: unknown[] = [];
+          await Promise.all(
+            this.#destinations.map(async (storage) => {
+              if (errorStorageSet.has(storage)) {
+                return;
+              }
+
+              try {
+                await storage.onOtherWriteError(context, signal, key, error);
+              } catch (ex) {
+                errors.push(ex);
+              }
+            }),
+          );
+          if (errors.length > 0) {
+            logger.error(new AggregateError(errors, "Failed to handle error"));
+          }
+        }
+
+        throw error;
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * 指定したキーから値を取得します。
+   *
+   * @template TKey 対象キーの型定義です。
+   * @param key 操作対象を識別するためのキーです。
+   * @param options 追加のオプションです。
+   * @returns 取得した値を返します。
+   */
+  public get<const TKey extends KeyofKeyValueMappingHasPlainValue<TKeyValueMapping>>(
+    key: TKey,
+    options?: Omit<GetOptions, "key">,
+  ): Promise<$InferPlainValueData<TKeyValueMapping[TKey]>>;
+
+  /**
+   * 指定したオプションで値を取得します。
+   *
+   * @template TKey 対象キーの型定義です。
+   * @param options 取得操作のオプション一式です。
+   * @returns 取得した値を返します。
+   */
+  public get<const TKey extends KeyofKeyValueMappingHasPlainValue<TKeyValueMapping>>(
+    options: GetOptions<TKey>,
+  ): Promise<$InferPlainValueData<TKeyValueMapping[TKey]>>;
+
+  public async get(...args: any): Promise<unknown> {
+    if (!this.#con) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options] = parse(GetArgsSchema, args);
+    const { key, signal: signalOption, context: contextOption } = options;
+
+    const { conAc, ioMux } = this.#con;
+    const signal = combineSignals([conAc.signal, signalOption]);
+
+    const context = mergeContext(this.#context, contextOption);
+    context["unikvs:action"] = "get";
+    context["unikvs:key"] = key;
+
+    const lock = await asyncmux.readonly(this, signal);
+    try {
+      // ロック待機中に接続状態が変更されていないか再確認します。
+      if (!this.#con) {
+        throw new UniKvsIsNotOpenError();
+      }
+
+      const NONE = {};
+      let data = NONE;
+
+      const lock = await ioMux.rLock({ key, signal });
+      try {
+        // 各ストレージを巡回し、最初に見つかったデータを取得します。
+        for (const storage of this.#destinations) {
+          if (await storage.exists(context, signal, key)) {
+            data = await storage.read(context, signal, key);
+            break;
+          }
+        }
+      } finally {
+        lock.unlock();
+      }
+
+      if (data === NONE) {
+        throw new KeyNotFoundError({ key });
+      }
+
+      // トランスフォーマーを逆順に適用してデータをデコードします。
+      if (this.#transformers.length > 0) {
+        for (const transformer of this.#transformers.toReversed()) {
+          data = await transformer.decode(context, signal, data);
+        }
+      }
+
+      return data;
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * 指定したキーからストリームを取得します。
+   *
+   * @template TKey 対象キーの型定義です。
+   * @param key 操作対象を識別するためのキーです。
+   * @param options 追加のオプションです。
+   * @returns 取得したストリームを返します。
+   */
+  public stream<const TKey extends KeyofKeyValueMappingHasStreamValue<TKeyValueMapping>>(
+    key: TKey,
+    options?: Omit<StreamOptions, "key">,
+  ): Promise<ValueStream<$InferStreamValueChunkData<TKeyValueMapping[TKey]>>>;
+
+  /**
+   * 指定したオプションでストリームを取得します。
+   *
+   * @template TKey 対象キーの型定義です。
+   * @param options ストリーム取得操作のオプション一式です。
+   * @returns 取得したストリームを返します。
+   */
+  public stream<const TKey extends KeyofKeyValueMappingHasStreamValue<TKeyValueMapping>>(
+    options: StreamOptions<TKey>,
+  ): Promise<ValueStream<$InferStreamValueChunkData<TKeyValueMapping[TKey]>>>;
+
+  public async stream(...args: any): Promise<ValueStream> {
+    if (!this.#con) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options] = parse(StreamArgsSchema, args);
+    const { key, signal: signalOption, context: contextOption } = options;
+
+    const { conAc, ioMux } = this.#con;
+    const signal = combineSignals([conAc.signal, signalOption]);
+
+    const context = mergeContext(this.#context, contextOption);
+    context["unikvs:action"] = "stream";
+    context["unikvs:key"] = key;
+
+    const lock = await asyncmux(this, signal);
+    try {
+      // ロック待機中に接続状態が変更されていないか再確認します。
+      if (!this.#con) {
+        throw new UniKvsIsNotOpenError();
+      }
+
+      const NONE: any = {};
+      let r: IReadableStream = NONE;
+
+      const lock = await ioMux.rLock({ key, signal });
+      try {
+        // 各ストレージを巡回し、最初に見つかったデータを取得します。
+        for (const storage of this.#destinations) {
+          if (await storage.exists(context, signal, key)) {
+            r = await storage.getReadable(context, signal, key);
+            break;
+          }
+        }
+
+        if (r === NONE) {
+          throw new KeyNotFoundError({ key });
+        }
+
+        // トランスフォーマーを逆順に適用し、デコード用トランスフォームを連結します。
+        if (this.#transformers.length > 0) {
+          for (const transformer of this.#transformers.toReversed()) {
+            const d = await transformer.getDecodable(context, signal);
+            r = r.pipeThrough(d);
+          }
+        }
+
+        if (!ioLockRegistry) {
+          return toValueStream(r, async () => {
+            try {
+              await r.cancel();
+            } catch {}
+            try {
+              lock.unlock();
+            } catch {}
+          });
+        }
+
+        const unregisterToken = {};
+        const valueStream = toValueStream(r, async () => {
+          try {
+            ioLockRegistry.unregister(unregisterToken);
+          } catch {}
+          try {
+            await r.cancel();
+          } catch {}
+          try {
+            lock.unlock();
+          } catch {}
+        });
+
+        // valueStream が GC されるタイミングでストリームが終了していなければロックを自動解放します。
+        ioLockRegistry.register(valueStream, lock, unregisterToken);
+
+        return valueStream;
+      } catch (ex) {
+        lock.unlock();
+        throw ex;
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * 指定したキーが存在するかを確認します。
+   *
+   * @param key 操作対象を識別するためのキーです。
+   * @param options 追加のオプションです。
+   * @returns 存在する場合は true、そうでない場合は false を返します。
+   */
+  public has(
+    key: KeyofKeyValueMapping<TKeyValueMapping>,
+    options?: Omit<HasOptions, "key">,
+  ): Promise<boolean>;
+
+  /**
+   * 指定したオプションでキーの存在を確認します。
+   *
+   * @param options 存在確認操作のオプションです。
+   * @returns 存在する場合は true、そうでない場合は false を返します。
+   */
+  public has(options: HasOptions<KeyofKeyValueMapping<TKeyValueMapping>>): Promise<boolean>;
+
+  public async has(...args: any): Promise<boolean> {
+    if (!this.#con) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options] = parse(HasArgsSchema, args);
+    const { key, signal: signalOption, context: contextOption } = options;
+
+    const { conAc, ioMux } = this.#con;
+    const signal = combineSignals([conAc.signal, signalOption]);
+
+    const context = mergeContext(this.#context, contextOption);
+    context["unikvs:action"] = "has";
+    context["unikvs:key"] = key;
+
+    const lock = await asyncmux(this, signal);
+    try {
+      // ロック待機中に接続状態が変更されていないか再確認します。
+      if (!this.#con) {
+        throw new UniKvsIsNotOpenError();
+      }
+
+      const lock = await ioMux.rLock({ key, signal });
+      try {
+        // いずれかのストレージに存在すれば true を返します。
+        for (const storage of this.#destinations) {
+          if (await storage.exists(context, signal, key)) {
+            return true;
+          }
+        }
+
+        return false;
+      } finally {
+        lock.unlock();
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * 指定したキーを削除します。
+   *
+   * @param key 操作対象を識別するためのキーです。
+   * @param options 追加のオプションです。
+   * @returns 完了を通知する Promise です。
+   */
+  public delete(
+    key: KeyofKeyValueMapping<TKeyValueMapping>,
+    options?: Omit<DeleteOptions, "key">,
+  ): Promise<void>;
+
+  /**
+   * 指定したオプションでキーを削除します。
+   *
+   * @param options 削除操作のオプションです。
+   * @returns 完了を通知する Promise です。
+   */
+  public delete(options: DeleteOptions<KeyofKeyValueMapping<TKeyValueMapping>>): Promise<void>;
+
+  public async delete(...args: any): Promise<void> {
+    if (!this.#con) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options] = parse(DeleteArgsSchema, args);
+    const { key, signal: signalOption, context: contextOption } = options;
+
+    const { conAc, ioMux } = this.#con;
+    const signal = combineSignals([conAc.signal, signalOption]);
+
+    const context = mergeContext(this.#context, contextOption);
+    context["unikvs:action"] = "delete";
+    context["unikvs:key"] = key;
+
+    const lock = await asyncmux(this, signal);
+    try {
+      // ロック待機中に接続状態が変更されていないか再確認します。
+      if (!this.#con) {
+        throw new UniKvsIsNotOpenError();
+      }
+
+      const lock = await ioMux.lock({ key, signal });
+      try {
+        // すべてのストレージから対象データを削除します。
+        // すべての処理を並列に実行し、エラーが発生した場合は集約します。
+        const errors: { reason: unknown }[] = [];
+        await Promise.all(
+          this.#destinations.map(async (storage) => {
+            try {
+              if (await storage.exists(context, signal, key)) {
+                await storage.delete(context, signal, key);
+              }
+            } catch (reason) {
+              errors.push({ reason });
+            }
+          }),
+        );
+        if (errors.length > 0) {
+          throw new PluginOperationAggregateError({ plugin: "storage", action: "delete", errors });
+        }
+      } finally {
+        lock.unlock();
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * すべてのストレージ内のデータを全削除します。
+   *
+   * @param options クリア操作のオプションです。
+   * @returns 完了を通知する Promise です。
+   */
+  public async clear(options?: ClearOptions): Promise<void>;
+
+  public async clear(...args: any): Promise<void> {
+    if (!this.#con) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const [options = {}] = parse(ClearArgsSchema, args);
+    const { signal: signalOption, context: contextOption } = options;
+
+    const { conAc, ioMux } = this.#con;
+    const signal = combineSignals([conAc.signal, signalOption]);
+
+    const context = mergeContext(this.#context, contextOption);
+    context["unikvs:action"] = "clear";
+
+    const lock = await asyncmux(this, signal);
+    try {
+      // ロック待機中に接続状態が変更されていないか再確認します。
+      if (!this.#con) {
+        throw new UniKvsIsNotOpenError();
+      }
+
+      const lock = await ioMux.lock({ signal });
+      try {
+        // すべてのストレージで一括削除を実行します。
+        // すべての処理を並列に実行し、エラーが発生した場合は集約します。
+        const errors: { reason: unknown }[] = [];
+        await Promise.all(
+          this.#destinations.map(async (storage) => {
+            try {
+              await storage.clear(context, signal);
+            } catch (reason) {
+              errors.push({ reason });
+            }
+          }),
+        );
+        if (errors.length > 0) {
+          throw new PluginOperationAggregateError({ plugin: "storage", action: "clear", errors });
+        }
+      } finally {
+        lock.unlock();
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+}