unikvs 0.0.9 → 0.0.12

package/dist/src/unikvs.js

@@ -9,24 +9,68 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _UniKvs_instances, _UniKvs_con, _UniKvs_acSet, _UniKvs_context, _UniKvs_destinations, _UniKvs_transformers, _UniKvs_close;
+var _UniKvs_instances, _UniKvs_con, _UniKvs_acSet, _UniKvs_vars, _UniKvs_destinations, _UniKvs_transformers, _UniKvs_valueSchemaResolver, _UniKvs_resolveValueSchema, _UniKvs_close;
 import { combineSignals } from "abort-signal-utils";
 import { asyncmux, Asyncmux } from "asyncmux";
 import logger from "./_logger.js";
-import mergeContext from "./_merge-context.js";
+import mergeVariables from "./_merge-variables.js";
+import { isReadableStream } from "./_streams.js";
 import toValueStream from "./_to-value-stream.js";
 import * as v from "./_valibot.js";
-import { KeyNotFoundError, UniKvsIsOpenError, PluginOperationAggregateError, UniKvsIsNotOpenError, } from "./errors.js";
+import { KeyNotFoundError, UniKvsIsOpenError, UniKvsIsNotOpenError, PluginOperationAggregateError, } from "./errors.js";
 import UniKvsConfig from "./unikvs-config.js";
 // -------------------------------------------------------------------------------------------------
 //
+// 値の検証
+//
+// -------------------------------------------------------------------------------------------------
+/**
+ * プレーン値専用のスキーマに ReadableStream が渡されたことを報告するためのスキーマです。
+ */
+const PlainValueInputSchema = v.pipe(v.unknown(), v.check((input) => !isReadableStream(input), "Expected a plain value, but received a ReadableStream"));
+/**
+ * ストリーム専用のスキーマにプレーン値が渡されたことを報告するためのスキーマです。
+ */
+const StreamValueInputSchema = v.pipe(v.unknown(), v.check(isReadableStream, "Expected a ReadableStream, but received a plain value"));
+/**
+ * スキーマ情報に基づいて `set` の入力値を検証します。
+ *
+ * プレーン値はその場で検証し、ストリームはチャンクごとに検証するストリームに変換します。
+ *
+ * @param info キーに対応するスキーマ情報です。
+ * @param value 検証する入力値です。
+ * @returns 検証済みの入力値を返します。
+ */
+function parseSetValue(info, value) {
+    if (isReadableStream(value)) {
+        if (info.kind === "plain") {
+            // 必ず検証に失敗するため、InvalidInputError が投げられます。
+            v.parseInput(PlainValueInputSchema, value);
+        }
+        // 入力チャンクを検証し、変換後の値を後続のパイプラインへ流します。
+        return value.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                controller.enqueue(v.parseInput(info.schema, chunk));
+            },
+        }));
+    }
+    if (info.kind === "stream") {
+        // 必ず検証に失敗するため、InvalidInputError が投げられます。
+        v.parseInput(StreamValueInputSchema, value);
+    }
+    return v.parseInput(info.schema, value);
+}
+// -------------------------------------------------------------------------------------------------
+//
 // スキーマ
 //
 // -------------------------------------------------------------------------------------------------
-const ContextKeySchema = v.string();
-const ContextSourceSchema = v.union([
+const VariablesKeySchema = v.string();
+// 配列形式の vars も正当な入力であるため、record スキーマより先に判定する必要があります。
+// record スキーマは配列にもマッチして数値キーのオブジェクトに変換してしまうため、配列形式を先に処理しないと mergeVariables での配列としてのマージが行われません。
+const VariablesSourceSchema = v.union([
+    v.array(v.tuple([VariablesKeySchema, v.unknown()])),
     v.record(v.any(), v.unknown()),
-    v.array(v.tuple([ContextKeySchema, v.unknown()])),
 ]);
 const OpenOptionsSchema = v.object({
     /**
@@ -34,9 +78,9 @@ const OpenOptionsSchema = v.object({
      */
     signal: v.optional(v.instance(AbortSignal)),
     /**
-     * 実行時のコンテキスト情報です。
+     * 実行時の変数です。
      */
-    context: v.optional(ContextSourceSchema),
+    vars: v.optional(VariablesSourceSchema),
 });
 const OpenArgsSchema = v.tuple([v.optional(OpenOptionsSchema)]);
 const CloseOptionsSchema = v.object({
@@ -45,16 +89,16 @@ const CloseOptionsSchema = v.object({
      */
     signal: v.optional(v.instance(AbortSignal)),
     /**
-     * 実行時のコンテキスト情報です。
+     * 実行時の変数です。
      */
-    context: v.optional(ContextSourceSchema),
+    vars: v.optional(VariablesSourceSchema),
 });
 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),
+    vars: v.optional(VariablesSourceSchema),
 });
 const SetArgsSchema = v.union([
     v.tuple([SetOptionsSchema]),
@@ -67,7 +111,7 @@ const SetArgsSchema = v.union([
 const GetOptionsSchema = v.object({
     key: v.string(),
     signal: v.optional(v.instance(AbortSignal)),
-    context: v.optional(ContextSourceSchema),
+    vars: v.optional(VariablesSourceSchema),
 });
 const GetArgsSchema = v.union([
     v.tuple([GetOptionsSchema]),
@@ -76,7 +120,7 @@ const GetArgsSchema = v.union([
 const StreamOptionsSchema = v.object({
     key: v.string(),
     signal: v.optional(v.instance(AbortSignal)),
-    context: v.optional(ContextSourceSchema),
+    vars: v.optional(VariablesSourceSchema),
 });
 const StreamArgsSchema = v.union([
     v.tuple([StreamOptionsSchema]),
@@ -85,7 +129,7 @@ const StreamArgsSchema = v.union([
 const HasOptionsSchema = v.object({
     key: v.string(),
     signal: v.optional(v.instance(AbortSignal)),
-    context: v.optional(ContextSourceSchema),
+    vars: v.optional(VariablesSourceSchema),
 });
 const HasArgsSchema = v.union([
     v.tuple([HasOptionsSchema]),
@@ -94,7 +138,7 @@ const HasArgsSchema = v.union([
 const DeleteOptionsSchema = v.object({
     key: v.string(),
     signal: v.optional(v.instance(AbortSignal)),
-    context: v.optional(ContextSourceSchema),
+    vars: v.optional(VariablesSourceSchema),
 });
 const DeleteArgsSchema = v.union([
     v.tuple([DeleteOptionsSchema]),
@@ -106,9 +150,9 @@ const ClearOptionsSchema = v.object({
      */
     signal: v.optional(v.instance(AbortSignal)),
     /**
-     * 実行時のコンテキスト情報です。
+     * 実行時の変数です。
      */
-    context: v.optional(ContextSourceSchema),
+    vars: v.optional(VariablesSourceSchema),
 });
 const ClearArgsSchema = v.tuple([v.optional(ClearOptionsSchema)]);
 // -------------------------------------------------------------------------------------------------
@@ -121,56 +165,28 @@ const ClearArgsSchema = v.tuple([v.optional(ClearOptionsSchema)]);
  */
 const ioLockRegistry = typeof FinalizationRegistry !== "function"
     ? null
-    : new FinalizationRegistry((lock) => {
-        if (!lock.released) {
-            lock.release();
+    : new FinalizationRegistry((held) => {
+        if (!held.lock.released) {
+            held.lock.release();
         }
+        // valueStream が読み取られないまま GC されたとき、ソースストリームが保持するリソース (S3 レスポンスボディなど) を解放するために破棄します。
+        // dispose は valueStream 自身を参照しないため、これを保持しても valueStream のガベージコレクションを妨げません。
+        // 失敗しても対処できないので無視します。
+        held.dispose().catch((ex) => {
+            logger.error `Failed to dispose value stream: ${ex}`;
+        });
     });
 /**
- * UniKvs メインクラスです。
- *
- * 複数のストレージとトランスフォーマーを統合して KVS 操作を提供します。
- *
- * @template TKeyValueMapping キーと値のマッピング定義です。
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
  */
 export default class UniKvs {
-    /**
-     * 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();
-     * ```
-     */
-    static config() {
-        return new UniKvsConfig(this);
+    static config(options) {
+        return new UniKvsConfig(this, options);
     }
     /**
-     * インスタンスを初期化します。
-     *
-     * @internal UniKvs の設定ビルダー経由で使用します。
-     * @param context コンテキストです。
-     * @param destinations ストレージのリストです。
-     * @param transformers トランスフォーマーのリストです。
+     * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
      */
-    constructor(context, destinations, transformers) {
+    constructor(vars, destinations, transformers, valueSchemaResolver = null) {
         _UniKvs_instances.add(this);
         /**
          * 現在の接続状態です。非接続時は null となります。
@@ -178,27 +194,30 @@ export default class UniKvs {
         _UniKvs_con.set(this, void 0);
         _UniKvs_acSet.set(this, void 0);
         /**
-         * 基本となる実行コンテキスト情報です。
+         * 基本となる実行変数情報です。
          */
-        _UniKvs_context.set(this, void 0);
+        _UniKvs_vars.set(this, void 0);
         /**
-         * データの永続化先となるストレージのリストです。
+         * データの永続化先となるストレージと前段パイプラインのリストです。
          */
         _UniKvs_destinations.set(this, void 0);
         /**
-         * データの変換を行うトランスフォーマーのリストです。
+         * データの変換を行うトランスフォーマーのリストです。open/close の管理用に全件を保持します。
          */
         _UniKvs_transformers.set(this, void 0);
+        /**
+         * キーに対応する値のスキーマ情報を解決するリゾルバーです。スキーマ未設定時は null となります。
+         */
+        _UniKvs_valueSchemaResolver.set(this, void 0);
         __classPrivateFieldSet(this, _UniKvs_con, null, "f");
         __classPrivateFieldSet(this, _UniKvs_acSet, new Set(), "f");
-        __classPrivateFieldSet(this, _UniKvs_context, { ...context }, "f");
+        __classPrivateFieldSet(this, _UniKvs_vars, { ...vars }, "f");
         __classPrivateFieldSet(this, _UniKvs_destinations, destinations, "f");
         __classPrivateFieldSet(this, _UniKvs_transformers, transformers, "f");
+        __classPrivateFieldSet(this, _UniKvs_valueSchemaResolver, valueSchemaResolver, "f");
     }
     /**
-     * UniKvs が利用可能であるかを確認します。
-     *
-     * @returns 利用可能である場合は true、そうでない場合は false を返します。
+     * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
      */
     get isOpen() {
         return __classPrivateFieldGet(this, _UniKvs_con, "f") !== null;
@@ -208,11 +227,11 @@ export default class UniKvs {
             throw new UniKvsIsOpenError();
         }
         const [options = {}] = v.parseInput(OpenArgsSchema, args);
-        const { signal: signalOption, context: contextOption } = options;
+        const { signal: signalOption, vars: varsOption } = options;
         const ac = new AbortController();
         const signal = combineSignals([ac.signal, signalOption]);
-        const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
-        context["unikvs:action"] = "open";
+        const vars = mergeVariables(__classPrivateFieldGet(this, _UniKvs_vars, "f"), varsOption);
+        vars["unikvs:action"] = "open";
         signal.throwIfAborted();
         __classPrivateFieldGet(this, _UniKvs_acSet, "f").add(ac);
         const dispose = [];
@@ -223,13 +242,13 @@ export default class UniKvs {
             }
             const openFns = [];
             // 各ストレージのオープン処理をリストに追加します。
-            for (const storage of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
+            for (const { storage } of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
                 openFns.push([
                     async () => {
-                        await storage.open(context, signal);
+                        await storage.open(vars, signal);
                         dispose.push(async () => {
                             try {
-                                await storage.close(context, signal);
+                                await storage.close(vars, signal);
                             }
                             catch (ex) {
                                 logger.error `Failed to close storage: ${ex}`;
@@ -243,10 +262,10 @@ export default class UniKvs {
             for (const transformer of __classPrivateFieldGet(this, _UniKvs_transformers, "f")) {
                 openFns.push([
                     async () => {
-                        await transformer.open(context, signal);
+                        await transformer.open(vars, signal);
                         dispose.push(async () => {
                             try {
-                                await transformer.close(context, signal);
+                                await transformer.close(vars, signal);
                             }
                             catch (ex) {
                                 logger.error `Failed to close transformer: ${ex}`;
@@ -267,8 +286,15 @@ export default class UniKvs {
                 }
             }));
             if (errors.length > 0) {
+                // 中断以外の失敗が混在しない場合は、abort 理由が集約エラーに埋もれないようにそのまま投げます。
+                if (signal.aborted && errors.every((error) => error.reason === signal.reason)) {
+                    throw signal.reason;
+                }
                 throw new PluginOperationAggregateError({ action: "open", errors });
             }
+            // すべてのプラグインのオープンが成功した後も、待機中に中断されていないか最終確認します。
+            // 中断済みのシグナルを持つ接続を作成すると、isOpen が true でありながら以降のすべての操作が即座に失敗する壊れた状態になります。
+            signal.throwIfAborted();
             __classPrivateFieldSet(this, _UniKvs_con, {
                 ac,
                 io: new Asyncmux(),
@@ -290,9 +316,9 @@ export default class UniKvs {
     close(...args) {
         try {
             const [options = {}] = v.parseInput(CloseArgsSchema, args);
-            const { signal = AbortSignal.timeout(10e3), context: contextOption } = options;
-            const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
-            context["unikvs:action"] = "close";
+            const { signal = AbortSignal.timeout(10e3), vars: varsOption } = options;
+            const vars = mergeVariables(__classPrivateFieldGet(this, _UniKvs_vars, "f"), varsOption);
+            vars["unikvs:action"] = "close";
             if (__classPrivateFieldGet(this, _UniKvs_con, "f") === null) {
                 const acArr = [...__classPrivateFieldGet(this, _UniKvs_acSet, "f")];
                 __classPrivateFieldGet(this, _UniKvs_acSet, "f").clear();
@@ -303,7 +329,8 @@ export default class UniKvs {
                 }
                 throw new UniKvsIsNotOpenError();
             }
-            const { ac } = __classPrivateFieldGet(this, _UniKvs_con, "f");
+            const con = __classPrivateFieldGet(this, _UniKvs_con, "f");
+            const { ac } = con;
             const acArr = [ac, ...__classPrivateFieldGet(this, _UniKvs_acSet, "f")];
             __classPrivateFieldGet(this, _UniKvs_acSet, "f").clear();
             for (const ac of acArr) {
@@ -311,13 +338,34 @@ export default class UniKvs {
                     ac.abort(new UniKvsIsNotOpenError());
                 }
             }
-            return __classPrivateFieldGet(this, _UniKvs_instances, "m", _UniKvs_close).call(this, context, signal, __classPrivateFieldGet(this, _UniKvs_con, "f"));
+            return __classPrivateFieldGet(this, _UniKvs_instances, "m", _UniKvs_close).call(this, vars, signal, con).catch(async (ex) => {
+                // #close が失敗した場合、コネクションの AbortController はすでに abort 済みであり、以降の操作がすべて即座に失敗する壊れた状態になります。
+                // そこで接続を破棄して isOpen=false の一貫した状態にし、ベストエフォートでプラグインのクローズ処理を実行します。
+                if (__classPrivateFieldGet(this, _UniKvs_con, "f") === con) {
+                    __classPrivateFieldSet(this, _UniKvs_con, null, "f");
+                    const disposeSignal = AbortSignal.timeout(10e3);
+                    await Promise.all([...__classPrivateFieldGet(this, _UniKvs_destinations, "f").map((dest) => dest.storage), ...__classPrivateFieldGet(this, _UniKvs_transformers, "f")].map(async (plugin) => {
+                        try {
+                            await plugin.close(vars, disposeSignal);
+                        }
+                        catch (reason) {
+                            logger.error `Failed to close plugin after close failure: ${reason}`;
+                        }
+                    }));
+                }
+                throw ex;
+            });
         }
         catch (ex) {
             return Promise.reject(ex);
         }
     }
-    async [(_UniKvs_con = new WeakMap(), _UniKvs_acSet = new WeakMap(), _UniKvs_context = new WeakMap(), _UniKvs_destinations = new WeakMap(), _UniKvs_transformers = new WeakMap(), _UniKvs_instances = new WeakSet(), _UniKvs_close = async function _UniKvs_close(context, signal, con) {
+    /**
+     * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
+     */
+    async [(_UniKvs_con = new WeakMap(), _UniKvs_acSet = new WeakMap(), _UniKvs_vars = new WeakMap(), _UniKvs_destinations = new WeakMap(), _UniKvs_transformers = new WeakMap(), _UniKvs_valueSchemaResolver = new WeakMap(), _UniKvs_instances = new WeakSet(), _UniKvs_resolveValueSchema = function _UniKvs_resolveValueSchema(key) {
+        return __classPrivateFieldGet(this, _UniKvs_valueSchemaResolver, "f")?.resolve(key);
+    }, _UniKvs_close = async function _UniKvs_close(vars, signal, con) {
         const lock = await asyncmux(this, signal);
         try {
             // ロック待機中に接続状態が変更されていないか再確認します。
@@ -329,10 +377,10 @@ export default class UniKvs {
             try {
                 const closeFns = [];
                 // ストレージのクローズ処理を登録します。
-                for (const plugin of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
+                for (const { storage } of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
                     closeFns.push([
                         async () => {
-                            await plugin.close(context, signal);
+                            await storage.close(vars, signal);
                         },
                         "storage",
                     ]);
@@ -341,7 +389,7 @@ export default class UniKvs {
                 for (const plugin of __classPrivateFieldGet(this, _UniKvs_transformers, "f")) {
                     closeFns.push([
                         async () => {
-                            await plugin.close(context, signal);
+                            await plugin.close(vars, signal);
                         },
                         "transformer",
                     ]);
@@ -381,12 +429,14 @@ export default class UniKvs {
             throw new UniKvsIsNotOpenError();
         }
         const [options] = v.parseInput(SetArgsSchema, args);
-        const { key, value, signal: signalOption, context: contextOption } = options;
+        const { key, signal: signalOption, vars: varsOption } = options;
+        const valueSchema = __classPrivateFieldGet(this, _UniKvs_instances, "m", _UniKvs_resolveValueSchema).call(this, key);
+        const value = valueSchema ? parseSetValue(valueSchema, options.value) : options.value;
         const { ac, io } = __classPrivateFieldGet(this, _UniKvs_con, "f");
         const signal = combineSignals([ac.signal, signalOption]);
-        const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
-        context["unikvs:action"] = "set";
-        context["unikvs:key"] = key;
+        const vars = mergeVariables(__classPrivateFieldGet(this, _UniKvs_vars, "f"), varsOption);
+        vars["unikvs:action"] = "set";
+        vars["unikvs:key"] = key;
         const lock = await asyncmux(this, signal);
         try {
             // ロック待機中に接続状態が変更されていないか再確認します。
@@ -395,28 +445,75 @@ export default class UniKvs {
             }
             const errors = [];
             const errorStorageSet = new Set();
-            if (value instanceof ReadableStream) {
-                // 各トランスフォーマーを通してデータをエンコードストリームへ変換します。
-                let data = value;
-                for (const transformer of __classPrivateFieldGet(this, _UniKvs_transformers, "f")) {
-                    const e = await transformer.getEncodable(context, signal);
-                    data = data.pipeThrough(e);
+            if (isReadableStream(value)) {
+                // 各ストレージ専用の前段パイプラインを通すため、tee で分岐しながらエンコードストリームを構築します。
+                // 最長の前段パイプラインを基準にし、ストレージの登録順に分岐点を作ります。
+                let longest = [];
+                for (const dest of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
+                    if (dest.transformers.length > longest.length) {
+                        longest = dest.transformers;
+                    }
+                }
+                let cur = value;
+                const branches = [];
+                const built = [];
+                try {
+                    let applied = 0;
+                    for (let i = 0; i < __classPrivateFieldGet(this, _UniKvs_destinations, "f").length; i++) {
+                        const dest = __classPrivateFieldGet(this, _UniKvs_destinations, "f")[i];
+                        while (applied < dest.transformers.length) {
+                            const e = await longest[applied].getEncodable(vars, signal);
+                            cur = cur.pipeThrough(e);
+                            applied++;
+                        }
+                        if (i === __classPrivateFieldGet(this, _UniKvs_destinations, "f").length - 1) {
+                            branches[i] = cur;
+                        }
+                        else {
+                            const [branch, rest] = cur.tee();
+                            branches[i] = branch;
+                            built.push(branch);
+                            cur = rest;
+                        }
+                    }
+                }
+                catch (ex) {
+                    // チェーンの構築中に失敗した場合、パイプが保持するソースストリームのリソースを解放するためにキャンセルします。
+                    // キャンセルしないとソースストリームはロックされたままリークします。
+                    try {
+                        await cur.cancel(ex);
+                    }
+                    catch {
+                        // キャンセルに失敗しても元の例外の伝播を優先します。
+                    }
+                    await Promise.all(built.map(async (branch) => {
+                        try {
+                            await branch.cancel(ex);
+                        }
+                        catch {
+                            // キャンセルに失敗しても元の例外の伝播を優先します。
+                        }
+                    }));
+                    throw ex;
                 }
                 const lock = await io.lock({ key, signal });
                 try {
-                    await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async (storage, i) => {
+                    await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async (dest, i) => {
+                        // tee ブランチはキャンセルされるまで健康なブランチの読み取り分のチャンクを保持し続けるため、失敗時に放棄したブランチを確実にキャンセルできるよう参照を保持します。
+                        const branch = branches[i];
                         try {
-                            // 複数のストレージがある場合は、tee メソッドを使用してストリームを分岐させます。
-                            let r = data;
-                            if (i !== __classPrivateFieldGet(this, _UniKvs_destinations, "f").length - 1) {
-                                [r, data] = data.tee();
-                            }
-                            const w = await storage.getWritable(context, signal, key);
-                            await r.pipeTo(w, { signal });
+                            const w = await dest.storage.getWritable(vars, signal, key);
+                            await branch.pipeTo(w, { signal });
                         }
                         catch (reason) {
+                            try {
+                                await branch.cancel(reason);
+                            }
+                            catch {
+                                // キャンセルに失敗してもエラー集約を優先します。
+                            }
                             errors.push({ reason });
-                            errorStorageSet.add(storage);
+                            errorStorageSet.add(dest);
                         }
                     }));
                 }
@@ -425,20 +522,27 @@ export default class UniKvs {
                 }
             }
             else {
-                // 登録されているトランスフォーマーを順番に適用してデータをエンコードします。
-                let data = value;
-                for (const transformer of __classPrivateFieldGet(this, _UniKvs_transformers, "f")) {
-                    data = await transformer.encode(context, signal, data);
+                // 各ストレージ専用の前段パイプラインでデータをエンコードします。共有プレフィックスは使い回します。
+                let longest = [];
+                for (const dest of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
+                    if (dest.transformers.length > longest.length) {
+                        longest = dest.transformers;
+                    }
+                }
+                const prefix = [value];
+                for (const transformer of longest) {
+                    prefix.push(await transformer.encode(vars, signal, prefix[prefix.length - 1]));
                 }
+                const encoded = __classPrivateFieldGet(this, _UniKvs_destinations, "f").map((dest) => prefix[dest.transformers.length]);
                 const lock = await io.lock({ key, signal });
                 try {
-                    await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async (storage) => {
+                    await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async (dest, i) => {
                         try {
-                            await storage.write(context, signal, key, data);
+                            await dest.storage.write(vars, signal, key, encoded[i]);
                         }
                         catch (reason) {
                             errors.push({ reason });
-                            errorStorageSet.add(storage);
+                            errorStorageSet.add(dest);
                         }
                     }));
                 }
@@ -455,12 +559,12 @@ export default class UniKvs {
                 });
                 {
                     const errors = [];
-                    await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async (storage) => {
-                        if (errorStorageSet.has(storage)) {
+                    await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async (dest) => {
+                        if (errorStorageSet.has(dest)) {
                             return;
                         }
                         try {
-                            await storage.onOtherWriteError(context, signal, key, error);
+                            await dest.storage.onOtherWriteError(vars, signal, key, error);
                         }
                         catch (ex) {
                             errors.push(ex);
@@ -482,12 +586,13 @@ export default class UniKvs {
             throw new UniKvsIsNotOpenError();
         }
         const [options] = v.parseInput(GetArgsSchema, args);
-        const { key, signal: signalOption, context: contextOption } = options;
+        const { key, signal: signalOption, vars: varsOption } = options;
+        const valueSchema = __classPrivateFieldGet(this, _UniKvs_instances, "m", _UniKvs_resolveValueSchema).call(this, key);
         const { ac, io } = __classPrivateFieldGet(this, _UniKvs_con, "f");
         const signal = combineSignals([ac.signal, signalOption]);
-        const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
-        context["unikvs:action"] = "get";
-        context["unikvs:key"] = key;
+        const vars = mergeVariables(__classPrivateFieldGet(this, _UniKvs_vars, "f"), varsOption);
+        vars["unikvs:action"] = "get";
+        vars["unikvs:key"] = key;
         const lock = await asyncmux.readonly(this, signal);
         try {
             // ロック待機中に接続状態が変更されていないか再確認します。
@@ -496,27 +601,57 @@ export default class UniKvs {
             }
             const NONE = {};
             let data = NONE;
+            let transformers = [];
+            const errors = [];
             const lock = await io.rLock({ key, signal });
             try {
                 // 各ストレージを巡回し、最初に見つかったデータを取得します。
-                for (const storage of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
-                    if (await storage.exists(context, signal, key)) {
-                        data = await storage.read(context, signal, key);
+                // あるストレージの読み取りに失敗しても、他のストレージからデータを取得できるようにフォールバックします。
+                for (const dest of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
+                    try {
+                        if (!(await dest.storage.exists(vars, signal, key))) {
+                            continue;
+                        }
+                        data = await dest.storage.read(vars, signal, key);
+                        transformers = dest.transformers;
                         break;
                     }
+                    catch (ex) {
+                        if (signal.aborted) {
+                            throw ex;
+                        }
+                        errors.push({ reason: ex });
+                        logger.error `Failed to read from a storage: ${ex}`;
+                    }
                 }
             }
             finally {
                 lock.release();
             }
             if (data === NONE) {
-                throw new KeyNotFoundError({ key });
-            }
-            // トランスフォーマーを逆順に適用してデータをデコードします。
-            if (__classPrivateFieldGet(this, _UniKvs_transformers, "f").length > 0) {
-                for (const transformer of __classPrivateFieldGet(this, _UniKvs_transformers, "f").toReversed()) {
-                    data = await transformer.decode(context, signal, data);
+                const args = { key };
+                switch (errors.length) {
+                    case 0:
+                        break;
+                    case 1:
+                        args.cause = errors[0].reason;
+                        break;
+                    default:
+                        args.cause = new PluginOperationAggregateError({
+                            plugin: "storage",
+                            action: "read",
+                            errors,
+                        });
                 }
+                throw new KeyNotFoundError(args);
+            }
+            // 見つかったストレージ専用の前段パイプラインを逆順に適用してデータをデコードします。
+            for (const transformer of transformers.toReversed()) {
+                data = await transformer.decode(vars, signal, data);
+            }
+            // デコード後のデータを検証します。
+            if (valueSchema) {
+                data = v.parseOutput(valueSchema.schema, data);
             }
             return data;
         }
@@ -529,13 +664,14 @@ export default class UniKvs {
             throw new UniKvsIsNotOpenError();
         }
         const [options] = v.parseInput(StreamArgsSchema, args);
-        const { key, signal: signalOption, context: contextOption } = options;
+        const { key, signal: signalOption, vars: varsOption } = options;
+        const valueSchema = __classPrivateFieldGet(this, _UniKvs_instances, "m", _UniKvs_resolveValueSchema).call(this, key);
         const { ac, io } = __classPrivateFieldGet(this, _UniKvs_con, "f");
         const signal = combineSignals([ac.signal, signalOption]);
-        const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
-        context["unikvs:action"] = "stream";
-        context["unikvs:key"] = key;
-        const lock = await asyncmux(this, signal);
+        const vars = mergeVariables(__classPrivateFieldGet(this, _UniKvs_vars, "f"), varsOption);
+        vars["unikvs:action"] = "stream";
+        vars["unikvs:key"] = key;
+        const lock = await asyncmux.readonly(this, signal);
         try {
             // ロック待機中に接続状態が変更されていないか再確認します。
             if (__classPrivateFieldGet(this, _UniKvs_con, "f") === null) {
@@ -543,31 +679,61 @@ export default class UniKvs {
             }
             const NONE = {};
             let r = NONE;
+            let transformers = [];
+            const errors = [];
             const lock = await io.rLock({ key, signal });
             try {
                 // 各ストレージを巡回し、最初に見つかったデータを取得します。
-                for (const storage of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
-                    if (await storage.exists(context, signal, key)) {
-                        r = await storage.getReadable(context, signal, key);
+                // あるストレージの読み取りに失敗しても、他のストレージからデータを取得できるようにフォールバックします。
+                for (const dest of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
+                    try {
+                        if (!(await dest.storage.exists(vars, signal, key))) {
+                            continue;
+                        }
+                        r = await dest.storage.getReadable(vars, signal, key);
+                        transformers = dest.transformers;
                         break;
                     }
+                    catch (ex) {
+                        if (signal.aborted) {
+                            throw ex;
+                        }
+                        errors.push({ reason: ex });
+                        logger.error `Failed to read from a storage: ${ex}`;
+                    }
                 }
                 if (r === NONE) {
-                    throw new KeyNotFoundError({ key });
-                }
-                // トランスフォーマーを逆順に適用し、デコード用トランスフォームを連結します。
-                if (__classPrivateFieldGet(this, _UniKvs_transformers, "f").length > 0) {
-                    for (const transformer of __classPrivateFieldGet(this, _UniKvs_transformers, "f").toReversed()) {
-                        const d = await transformer.getDecodable(context, signal);
-                        r = r.pipeThrough(d);
+                    const args = { key };
+                    switch (errors.length) {
+                        case 0:
+                            break;
+                        case 1:
+                            args.cause = errors[0].reason;
+                            break;
+                        default:
+                            args.cause = new PluginOperationAggregateError({
+                                plugin: "storage",
+                                action: "read",
+                                errors,
+                            });
                     }
+                    throw new KeyNotFoundError(args);
+                }
+                // 見つかったストレージ専用の前段パイプラインを逆順に適用し、デコード用トランスフォームを連結します。
+                for (const transformer of transformers.toReversed()) {
+                    const d = await transformer.getDecodable(vars, signal);
+                    r = r.pipeThrough(d);
+                }
+                // デコード後のチャンクを検証します。
+                if (valueSchema) {
+                    r = r.pipeThrough(new TransformStream({
+                        transform(chunk, controller) {
+                            controller.enqueue(v.parseOutput(valueSchema.schema, chunk));
+                        },
+                    }));
                 }
                 if (!ioLockRegistry) {
                     return toValueStream(r, async () => {
-                        try {
-                            await r.cancel();
-                        }
-                        catch { }
                         try {
                             lock.release();
                         }
@@ -580,20 +746,26 @@ export default class UniKvs {
                         ioLockRegistry.unregister(unregisterToken);
                     }
                     catch { }
-                    try {
-                        await r.cancel();
-                    }
-                    catch { }
                     try {
                         lock.release();
                     }
                     catch { }
                 });
-                // valueStream が GC されるタイミングでストリームが終了していなければロックを自動解放します。
-                ioLockRegistry.register(valueStream, lock, unregisterToken);
+                // valueStream が GC されるタイミングでストリームが終了していなければロックを自動解放するとともに、ソースストリームが保持するリソース (S3 レスポンスボディなど) を解放できるように dispose を記録します。
+                ioLockRegistry.register(valueStream, {
+                    lock,
+                    dispose: valueStream.dispose,
+                }, unregisterToken);
                 return valueStream;
             }
             catch (ex) {
+                if (r !== NONE) {
+                    // getReadable 成功後のセットアップ中に失敗した場合、ソースストリームが保持するリソース (S3 レスポンスボディなど) を解放するためにキャンセルします。
+                    try {
+                        await r.cancel(ex);
+                    }
+                    catch { }
+                }
                 lock.release();
                 throw ex;
             }
@@ -607,13 +779,15 @@ export default class UniKvs {
             throw new UniKvsIsNotOpenError();
         }
         const [options] = v.parseInput(HasArgsSchema, args);
-        const { key, signal: signalOption, context: contextOption } = options;
+        const { key, signal: signalOption, vars: varsOption } = options;
+        // キーがキースキーマに一致するかを検証します。
+        __classPrivateFieldGet(this, _UniKvs_instances, "m", _UniKvs_resolveValueSchema).call(this, key);
         const { ac, io } = __classPrivateFieldGet(this, _UniKvs_con, "f");
         const signal = combineSignals([ac.signal, signalOption]);
-        const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
-        context["unikvs:action"] = "has";
-        context["unikvs:key"] = key;
-        const lock = await asyncmux(this, signal);
+        const vars = mergeVariables(__classPrivateFieldGet(this, _UniKvs_vars, "f"), varsOption);
+        vars["unikvs:action"] = "has";
+        vars["unikvs:key"] = key;
+        const lock = await asyncmux.readonly(this, signal);
         try {
             // ロック待機中に接続状態が変更されていないか再確認します。
             if (__classPrivateFieldGet(this, _UniKvs_con, "f") === null) {
@@ -622,10 +796,37 @@ export default class UniKvs {
             const lock = await io.rLock({ key, signal });
             try {
                 // いずれかのストレージに存在すれば true を返します。
-                for (const storage of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
-                    if (await storage.exists(context, signal, key)) {
-                        return true;
+                // あるストレージの存在確認に失敗しても、他のストレージで存在を確認できるようにフォールバックします。
+                const errors = [];
+                for (const { storage } of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
+                    try {
+                        if (await storage.exists(vars, signal, key)) {
+                            return true;
+                        }
+                    }
+                    catch (ex) {
+                        if (signal.aborted) {
+                            throw ex;
+                        }
+                        errors.push({ reason: ex });
+                        logger.error `Failed to check existence in a storage: ${ex}`;
+                    }
+                }
+                // すべてのストレージで存在を確認できなかった場合は結果が不明のため、get() と同様にエラーとして報告します。
+                if (errors.length > 0) {
+                    const args = { key };
+                    switch (errors.length) {
+                        case 1:
+                            args.cause = errors[0].reason;
+                            break;
+                        default:
+                            args.cause = new PluginOperationAggregateError({
+                                plugin: "storage",
+                                action: "read",
+                                errors,
+                            });
                     }
+                    throw new KeyNotFoundError(args);
                 }
                 return false;
             }
@@ -642,12 +843,14 @@ export default class UniKvs {
             throw new UniKvsIsNotOpenError();
         }
         const [options] = v.parseInput(DeleteArgsSchema, args);
-        const { key, signal: signalOption, context: contextOption } = options;
+        const { key, signal: signalOption, vars: varsOption } = options;
+        // キーがキースキーマに一致するかを検証します。
+        __classPrivateFieldGet(this, _UniKvs_instances, "m", _UniKvs_resolveValueSchema).call(this, key);
         const { ac, io } = __classPrivateFieldGet(this, _UniKvs_con, "f");
         const signal = combineSignals([ac.signal, signalOption]);
-        const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
-        context["unikvs:action"] = "delete";
-        context["unikvs:key"] = key;
+        const vars = mergeVariables(__classPrivateFieldGet(this, _UniKvs_vars, "f"), varsOption);
+        vars["unikvs:action"] = "delete";
+        vars["unikvs:key"] = key;
         const lock = await asyncmux(this, signal);
         try {
             // ロック待機中に接続状態が変更されていないか再確認します。
@@ -659,10 +862,10 @@ export default class UniKvs {
                 // すべてのストレージから対象データを削除します。
                 // すべての処理を並列に実行し、エラーが発生した場合は集約します。
                 const errors = [];
-                await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async (storage) => {
+                await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async ({ storage }) => {
                     try {
-                        if (await storage.exists(context, signal, key)) {
-                            await storage.delete(context, signal, key);
+                        if (await storage.exists(vars, signal, key)) {
+                            await storage.delete(vars, signal, key);
                         }
                     }
                     catch (reason) {
@@ -686,11 +889,11 @@ export default class UniKvs {
             throw new UniKvsIsNotOpenError();
         }
         const [options = {}] = v.parseInput(ClearArgsSchema, args);
-        const { signal: signalOption, context: contextOption } = options;
+        const { signal: signalOption, vars: varsOption } = options;
         const { ac, io } = __classPrivateFieldGet(this, _UniKvs_con, "f");
         const signal = combineSignals([ac.signal, signalOption]);
-        const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
-        context["unikvs:action"] = "clear";
+        const vars = mergeVariables(__classPrivateFieldGet(this, _UniKvs_vars, "f"), varsOption);
+        vars["unikvs:action"] = "clear";
         const lock = await asyncmux(this, signal);
         try {
             // ロック待機中に接続状態が変更されていないか再確認します。
@@ -702,9 +905,9 @@ export default class UniKvs {
                 // すべてのストレージで一括削除を実行します。
                 // すべての処理を並列に実行し、エラーが発生した場合は集約します。
                 const errors = [];
-                await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async (storage) => {
+                await Promise.all(__classPrivateFieldGet(this, _UniKvs_destinations, "f").map(async ({ storage }) => {
                     try {
-                        await storage.clear(context, signal);
+                        await storage.clear(vars, signal);
                     }
                     catch (reason) {
                         errors.push({ reason });