unikvs 0.0.8 → 0.0.10

package/dist/src/unikvs.js

@@ -24,9 +24,11 @@ import UniKvsConfig from "./unikvs-config.js";
 //
 // -------------------------------------------------------------------------------------------------
 const ContextKeySchema = v.string();
+// 配列形式の context も正当な入力であるため、record スキーマより先に判定する必要があります。
+// record スキーマは配列にもマッチして数値キーのオブジェクトに変換してしまうため、配列形式を先に処理しないと mergeContext での配列としてのマージが行われません。
 const ContextSourceSchema = v.union([
-    v.record(v.any(), v.unknown()),
     v.array(v.tuple([ContextKeySchema, v.unknown()])),
+    v.record(v.any(), v.unknown()),
 ]);
 const OpenOptionsSchema = v.object({
     /**
@@ -121,10 +123,16 @@ 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 メインクラスです。
@@ -267,8 +275,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(),
@@ -303,7 +318,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,12 +327,35 @@ 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, context, 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"), ...__classPrivateFieldGet(this, _UniKvs_transformers, "f")].map(async (plugin) => {
+                        try {
+                            await plugin.close(context, disposeSignal);
+                        }
+                        catch (reason) {
+                            logger.error `Failed to close plugin after close failure: ${reason}`;
+                        }
+                    }));
+                }
+                throw ex;
+            });
         }
         catch (ex) {
             return Promise.reject(ex);
         }
     }
+    /**
+     * UniKvs が開いている場合にクローズします。
+     *
+     * `await using` 構文による自動クローズに使用されます。
+     *
+     * @returns 完了を通知する Promise です。
+     */
     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) {
         const lock = await asyncmux(this, signal);
         try {
@@ -398,23 +437,47 @@ export default class UniKvs {
             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);
+                try {
+                    for (const transformer of __classPrivateFieldGet(this, _UniKvs_transformers, "f")) {
+                        const e = await transformer.getEncodable(context, signal);
+                        data = data.pipeThrough(e);
+                    }
+                }
+                catch (ex) {
+                    // チェーンの構築中に失敗した場合、パイプが保持するソースストリームのリソースを解放するためにキャンセルします。
+                    // キャンセルしないとソースストリームはロックされたままリークします。
+                    try {
+                        await data.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) => {
+                        // tee ブランチはキャンセルされるまで健康なブランチの読み取り分のチャンクを保持し続けるため、失敗時に放棄したブランチを確実にキャンセルできるよう参照を保持します。
+                        let branch = null;
                         try {
                             // 複数のストレージがある場合は、tee メソッドを使用してストリームを分岐させます。
                             let r = data;
                             if (i !== __classPrivateFieldGet(this, _UniKvs_destinations, "f").length - 1) {
                                 [r, data] = data.tee();
                             }
+                            branch = r;
                             const w = await storage.getWritable(context, signal, key);
                             await r.pipeTo(w, { signal });
                         }
                         catch (reason) {
+                            if (branch !== null) {
+                                try {
+                                    await branch.cancel(reason);
+                                }
+                                catch {
+                                    // キャンセルに失敗してもエラー集約を優先します。
+                                }
+                            }
                             errors.push({ reason });
                             errorStorageSet.add(storage);
                         }
@@ -496,21 +559,47 @@ export default class UniKvs {
             }
             const NONE = {};
             let data = NONE;
+            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)) {
+                    try {
+                        if (!(await storage.exists(context, signal, key))) {
+                            continue;
+                        }
                         data = await storage.read(context, signal, key);
                         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 });
+                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);
             }
             // トランスフォーマーを逆順に適用してデータをデコードします。
             if (__classPrivateFieldGet(this, _UniKvs_transformers, "f").length > 0) {
@@ -535,7 +624,7 @@ export default class UniKvs {
         const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
         context["unikvs:action"] = "stream";
         context["unikvs:key"] = key;
-        const lock = await asyncmux(this, signal);
+        const lock = await asyncmux.readonly(this, signal);
         try {
             // ロック待機中に接続状態が変更されていないか再確認します。
             if (__classPrivateFieldGet(this, _UniKvs_con, "f") === null) {
@@ -543,31 +632,51 @@ export default class UniKvs {
             }
             const NONE = {};
             let r = NONE;
+            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)) {
+                    try {
+                        if (!(await storage.exists(context, signal, key))) {
+                            continue;
+                        }
                         r = await storage.getReadable(context, signal, key);
                         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 });
+                    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);
                 }
                 // トランスフォーマーを逆順に適用し、デコード用トランスフォームを連結します。
-                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);
-                    }
+                for (const transformer of __classPrivateFieldGet(this, _UniKvs_transformers, "f").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.release();
                         }
@@ -580,20 +689,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;
             }
@@ -613,7 +728,7 @@ export default class UniKvs {
         const context = mergeContext(__classPrivateFieldGet(this, _UniKvs_context, "f"), contextOption);
         context["unikvs:action"] = "has";
         context["unikvs:key"] = key;
-        const lock = await asyncmux(this, signal);
+        const lock = await asyncmux.readonly(this, signal);
         try {
             // ロック待機中に接続状態が変更されていないか再確認します。
             if (__classPrivateFieldGet(this, _UniKvs_con, "f") === null) {
@@ -622,10 +737,37 @@ export default class UniKvs {
             const lock = await io.rLock({ key, signal });
             try {
                 // いずれかのストレージに存在すれば true を返します。
+                // あるストレージの存在確認に失敗しても、他のストレージで存在を確認できるようにフォールバックします。
+                const errors = [];
                 for (const storage of __classPrivateFieldGet(this, _UniKvs_destinations, "f")) {
-                    if (await storage.exists(context, signal, key)) {
-                        return true;
+                    try {
+                        if (await storage.exists(context, 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;
             }

package/dist/src/value-stream.types.d.ts

@@ -6,6 +6,11 @@
  * @template T ストリームを流れるデータの型です。
  */
 export interface ValueStream<T = any> extends Omit<ReadableStream, keyof AsyncDisposable | keyof AsyncIterable<unknown>>, AsyncDisposable, AsyncIterable<T, void, unknown> {
-    dispose(): Promise<void>;
+    /**
+     * ストリームを閉じ、関連するリソースを解放します。
+     *
+     * @returns リソースの解放が完了したときに解決される Promise です。
+     */
+    dispose: (this: void) => Promise<void>;
 }
 //# sourceMappingURL=value-stream.types.d.ts.map

package/dist/src/value-stream.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-stream.types.d.ts","sourceRoot":"","sources":["../../src/value-stream.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,GAAG,CAClC,SACE,IAAI,CAAC,cAAc,EAAE,MAAM,eAAe,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC,EAC1E,eAAe,EACf,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC;IACjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}
+{"version":3,"file":"value-stream.types.d.ts","sourceRoot":"","sources":["../../src/value-stream.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,GAAG,CAClC,SACE,IAAI,CAAC,cAAc,EAAE,MAAM,eAAe,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC,EAC1E,eAAe,EACf,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unikvs",
-  "version": "0.0.8",
-  "description": "",
+  "version": "0.0.10",
+  "description": "unikvs は TypeScript で実装されたモジュラーでポータブルな KVS クライアントです。",
   "homepage": "https://github.com/tai-kun/unikvs",
   "license": "MIT",
   "author": "tai-kun",
@@ -25,33 +25,33 @@
     }
   },
   "dependencies": {
-    "@tai-kun/valibot-extra-lab": "^0.0.5",
-    "@unikvs/core": "0.0.8",
-    "abort-signal-utils": "^0.0.2",
-    "asyncmux": "^0.0.8",
-    "call-fn-once": "^0.0.6",
-    "try-capture-stack-trace": "^0.0.3"
+    "@tai-kun/valibot-extra-lab": "0.0.5",
+    "@unikvs/core": "0.0.10",
+    "abort-signal-utils": "0.0.3",
+    "asyncmux": "0.0.8",
+    "call-fn-once": "0.0.6",
+    "try-capture-stack-trace": "0.0.3"
   },
   "devDependencies": {
-    "@tsconfig/node24": "^24.0.4",
-    "@tsconfig/strictest": "^2.0.8",
-    "@types/node": "^24.12.4",
-    "@unikvs/checksum": "0.0.8",
-    "@unikvs/compression": "0.0.8",
-    "@unikvs/fs.node": "0.0.8",
-    "@unikvs/memory": "0.0.8",
-    "@unikvs/opfs": "0.0.8",
-    "@unikvs/utils": "0.0.8",
-    "@vitest/browser": "^4.1.6",
-    "@vitest/browser-playwright": "^4.1.6",
-    "npm-check-updates": "^20.0.2",
-    "playwright": "^1.60.0",
-    "vite": "^8.0.12",
-    "vitest": "^4.1.6"
+    "@tsconfig/node24": "24.0.5",
+    "@tsconfig/strictest": "2.0.8",
+    "@types/node": "24.13.3",
+    "@unikvs/checksum": "0.0.10",
+    "@unikvs/compression": "0.0.10",
+    "@unikvs/fs.node": "0.0.10",
+    "@unikvs/memory": "0.0.10",
+    "@unikvs/opfs": "0.0.10",
+    "@unikvs/utils": "0.0.10",
+    "@vitest/browser": "4.1.10",
+    "@vitest/browser-playwright": "4.1.10",
+    "npm-check-updates": "20.0.2",
+    "playwright": "1.62.1",
+    "vite": "8.2.1",
+    "vitest": "4.1.10"
   },
   "peerDependencies": {
-    "@logtape/logtape": "^2.0.0",
-    "valibot": "^1.0.0"
+    "@logtape/logtape": "2.0.0",
+    "valibot": "1.0.0"
   },
   "scripts": {
     "build": "tsc --project ./.config/tsconfig.build.json"

package/src/_to-value-stream.ts

@@ -17,17 +17,47 @@ export default function toValueStream<T>(
   onAsyncDispose: () => Promise<void>,
 ): ValueStream<T> {
   const cacheMap = new Map();
+  const reader = readableStream.getReader();
+
   async function disposeValueStream(): Promise<void> {
-    await callAsyncableFnOnce(cacheMap, "dispose", onAsyncDispose);
+    await callAsyncableFnOnce(cacheMap, "dispose", async () => {
+      try {
+        await reader.cancel();
+      } catch (ex) {
+        logger.error`Failed to cancel the source stream: ${ex}`;
+      }
+
+      await onAsyncDispose();
+    });
   }
 
-  return Object.assign(
-    // ReadableStream
-    readableStream.pipeThrough(
-      new TransformStream({
-        flush: disposeValueStream,
-      }),
-    ),
+  // cancel・エラー・早期 break であっても dispose されるように、readable 側のキャンセルを直接フックしたストリームを返します。
+  const valueStream = new ReadableStream<T>({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          // ストリームが正常に完了したことも dispose 対象とし、完了を通知する前に破棄を完了させます。
+          await disposeValueStream();
+          controller.close();
+        } else {
+          controller.enqueue(value);
+        }
+      } catch (ex) {
+        // ソースエラー時も dispose (ロック解放など) を行わないと、ストリームを放棄した consumer に対してキーの I/O ロックがリークします。
+        // dispose 自体が失敗しても元の例外の伝播を壊さないように、失敗はログに残すだけにします。
+        await disposeValueStream().catch((e) => logger.error`Failed to dispose value stream: ${e}`);
+        controller.error(ex);
+      }
+    },
+
+    async cancel() {
+      await disposeValueStream();
+    },
+  });
+
+  const stream = Object.assign(
+    valueStream,
 
     // AsyncDisposable
     {
@@ -63,6 +93,13 @@ export default function toValueStream<T>(
 
           throw ex;
         } finally {
+          // cancel・エラー・早期 break など完了方法に関係なくストリームを破棄し、キーの読み取りロックがリークしないようにします (2 回目以降は no-op)。
+          try {
+            await disposeValueStream();
+          } catch (ex) {
+            logger.error`Failed to dispose value stream: ${ex}`;
+          }
+
           // 最後に必ずリーダーのロックを解放し、ストリームを再利用可能な状態にします。
           try {
             r.releaseLock();
@@ -73,4 +110,6 @@ export default function toValueStream<T>(
       },
     },
   );
+
+  return stream;
 }

package/src/_valibot.ts

@@ -1,4 +1,3 @@
-import type { ErrorOptions } from "@unikvs/core";
 import { tryCaptureStackTrace } from "try-capture-stack-trace";
 import { type InferOutput, safeParse } from "valibot";
 
@@ -29,14 +28,14 @@ export { array, tuple, object, record, transform } from "@tai-kun/valibot-extra-
 
 type BaseSchema = typeof safeParse extends (schema: infer S, ...args: any) => any ? S : never;
 
-export interface ParseInputErrorConstructor {
-  new (args: InvalidInputErrorArgs, options?: ErrorOptions): Error;
+export interface IParseInputErrorConstructor {
+  new (args: InvalidInputErrorArgs): Error;
 }
 
 export function parseInput<const TSchema extends BaseSchema>(
   schema: TSchema,
   value: unknown,
-  Error: ParseInputErrorConstructor = InvalidInputError,
+  Error: IParseInputErrorConstructor = InvalidInputError,
 ): InferOutput<TSchema> {
   const result = safeParse(schema, value);
   if (result.success) {
@@ -49,7 +48,7 @@ export function parseInput<const TSchema extends BaseSchema>(
 }
 
 export interface ParseOutputErrorConstructor {
-  new (args: InvalidOutputErrorArgs, options?: ErrorOptions): Error;
+  new (args: InvalidOutputErrorArgs): Error;
 }
 
 export function parseOutput<const TSchema extends BaseSchema>(