unikvs 0.0.9 → 0.0.12

package/dist/src/utils.types.d.ts

@@ -1,7 +1,5 @@
 /**
- * オブジェクトのプロパティー値の型のユニオン型を抽出するユーティリティー型です。
- *
- * @template T 対象となるオブジェクトの型です。
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs)
  */
 export type ValueOf<T> = T[keyof T];
 //# sourceMappingURL=utils.types.d.ts.map

package/dist/src/utils.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.types.d.ts","sourceRoot":"","sources":["../../src/utils.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC"}
+{"version":3,"file":"utils.types.d.ts","sourceRoot":"","sources":["../../src/utils.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC"}

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

@@ -1,11 +1,10 @@
 /**
- * 値を非同期に流すための読み取り専用ストリームを定義するインターフェースです。
- *
- * `ReadableStream` を拡張しており、標準的なストリーム操作に加えて非同期イテレーターによる反復処理をサポートします。
- *
- * @template T ストリームを流れるデータの型です。
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#value-stream)
  */
 export interface ValueStream<T = any> extends Omit<ReadableStream, keyof AsyncDisposable | keyof AsyncIterable<unknown>>, AsyncDisposable, AsyncIterable<T, void, unknown> {
-    dispose(): Promise<void>;
+    /**
+     * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#value-stream)
+     */
+    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;;GAEG;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;;OAEG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC"}

package/dist/src/variables.types.d.ts

@@ -0,0 +1,11 @@
+import type { Variables } from "@unikvs/core";
+import type { ValueOf } from "./utils.types.js";
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#variables-and-cancellation)
+ */
+export type VariableEntry = readonly [key: keyof Variables, value: ValueOf<Variables>];
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#variables-and-cancellation)
+ */
+export type VariablesSource = Readonly<Variables> | readonly VariableEntry[];
+//# sourceMappingURL=variables.types.d.ts.map

package/dist/src/variables.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.types.d.ts","sourceRoot":"","sources":["../../src/variables.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,GAAG,EAAE,MAAM,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;AAEvF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,SAAS,CAAC,GAAG,SAAS,aAAa,EAAE,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unikvs",
-  "version": "0.0.9",
-  "description": "unikvs は TypeScript で実装されたモジュラーでポータブルな KVS クライアントです。",
+  "version": "0.0.12",
+  "description": "A modular and portable KVS client implemented in TypeScript.",
   "homepage": "https://github.com/tai-kun/unikvs",
   "license": "MIT",
   "author": "tai-kun",
@@ -12,6 +12,7 @@
     "dist",
     "src",
     "package.json",
+    "README.md",
     "LICENSE"
   ],
   "type": "module",
@@ -25,33 +26,33 @@
     }
   },
   "dependencies": {
-    "@tai-kun/valibot-extra-lab": "^0.0.5",
-    "@unikvs/core": "0.0.9",
-    "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.12",
+    "abort-signal-utils": "0.0.3",
+    "asyncmux": "0.0.10",
+    "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.9",
-    "@unikvs/compression": "0.0.9",
-    "@unikvs/fs.node": "0.0.9",
-    "@unikvs/memory": "0.0.9",
-    "@unikvs/opfs": "0.0.9",
-    "@unikvs/utils": "0.0.9",
-    "@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.6",
+    "@unikvs/checksum": "0.0.12",
+    "@unikvs/compression": "0.0.12",
+    "@unikvs/fs.node": "0.0.12",
+    "@unikvs/memory": "0.0.12",
+    "@unikvs/opfs": "0.0.12",
+    "@unikvs/utils": "0.0.12",
+    "@vitest/browser": "4.1.11",
+    "@vitest/browser-playwright": "4.1.11",
+    "npm-check-updates": "20.0.2",
+    "playwright": "1.63.0",
+    "vite": "8.3.0",
+    "vitest": "4.1.11"
   },
   "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/_merge-variables.ts

@@ -0,0 +1,19 @@
+import { Variables } from "@unikvs/core";
+
+import type { VariablesSource } from "./variables.types.js";
+
+/**
+ * 2 つの Variables オブジェクトを結合します。
+ *
+ * 基本となる Variables に対して、追加または上書きする変数情報を結合し、新しい Variables オブジェクトを生成して返します。追加する変数情報が配列（キーと値のペアの配列）である場合は、オブジェクトに変換した上で結合処理を行います。
+ *
+ * @param a ベースとなる読み取り専用の Variables オブジェクトです。
+ * @param b 結合する読み取り専用の Variables、または VariablesSource、あるいは undefined です。
+ * @returns 結合された新しい Variables オブジェクトです。
+ */
+export default function mergeVariables(
+  a: Readonly<Variables>,
+  b: Readonly<Variables> | VariablesSource | undefined,
+): Variables {
+  return { ...a, ...(Array.isArray(b) ? Object.fromEntries(b) : b) };
+}

package/src/_storage.ts

@@ -1,5 +1,12 @@
-import type { Context, IStorage, ErrorBase, IReadableStream, IWritableStream } from "@unikvs/core";
-
+import type {
+  Variables,
+  IStorage,
+  ErrorBase,
+  IReadableStream,
+  IWritableStream,
+} from "@unikvs/core";
+
+import { isReadableStream, isWritableStream } from "./_streams.js";
 import * as v from "./_valibot.js";
 import {
   type PluginOperationAggregateError,
@@ -8,6 +15,22 @@ import {
   WritableStreamNotSupportedError,
 } from "./errors.js";
 
+/**
+ * `ReadableStream` のインターフェースを満たすかを検証するためのスキーマです。
+ */
+const ReadableStreamSchema = v.custom<IReadableStream>(
+  isReadableStream,
+  "Expected a ReadableStream",
+);
+
+/**
+ * `WritableStream` のインターフェースを満たすかを検証するためのスキーマです。
+ */
+const WritableStreamSchema = v.custom<IWritableStream>(
+  isWritableStream,
+  "Expected a WritableStream",
+);
+
 export default class UniKvsStorage {
   private readonly io: IStorage;
 
@@ -18,29 +41,29 @@ export default class UniKvsStorage {
     this.managed = false;
   }
 
-  public async open(context: Context, signal: AbortSignal): Promise<void> {
+  public async open(vars: Variables, signal: AbortSignal): Promise<void> {
     if (typeof this.io.open !== "function") {
       return;
     }
 
     if (!this.io.isOpen) {
       this.managed = true;
-      await this.io.open({ signal, context });
+      await this.io.open({ vars, signal });
     }
   }
 
-  public async close(context: Context, signal: AbortSignal): Promise<void> {
+  public async close(vars: Variables, signal: AbortSignal): Promise<void> {
     if (typeof this.io.close !== "function") {
       return;
     }
 
     if (this.io.isOpen && this.managed) {
-      await this.io.close({ signal, context });
+      await this.io.close({ vars, signal });
     }
   }
 
   public async write(
-    context: Context,
+    vars: Variables,
     signal: AbortSignal,
     key: IStorage.Key,
     data: unknown,
@@ -49,48 +72,48 @@ export default class UniKvsStorage {
       throw new StorageIsNotOpenError({ name: this.io.name });
     }
 
-    await this.io.write({ key, data, signal, context });
+    await this.io.write({ key, data, vars, signal });
   }
 
-  public async read(context: Context, signal: AbortSignal, key: IStorage.Key): Promise<unknown> {
+  public async read(vars: Variables, signal: AbortSignal, key: IStorage.Key): Promise<unknown> {
     if (!this.io.isOpen) {
       throw new StorageIsNotOpenError({ name: this.io.name });
     }
 
-    const output = await this.io.read({ key, signal, context });
+    const output = await this.io.read({ key, vars, signal });
 
     return output;
   }
 
-  public async exists(context: Context, signal: AbortSignal, key: IStorage.Key): Promise<boolean> {
+  public async exists(vars: Variables, signal: AbortSignal, key: IStorage.Key): Promise<boolean> {
     if (!this.io.isOpen) {
       throw new StorageIsNotOpenError({ name: this.io.name });
     }
 
-    const output = await this.io.exists({ key, signal, context });
+    const output = await this.io.exists({ key, vars, signal });
     const parsed = Boolean(output);
 
     return parsed;
   }
 
-  public async delete(context: Context, signal: AbortSignal, key: IStorage.Key): Promise<void> {
+  public async delete(vars: Variables, signal: AbortSignal, key: IStorage.Key): Promise<void> {
     if (!this.io.isOpen) {
       throw new StorageIsNotOpenError({ name: this.io.name });
     }
 
-    await this.io.delete({ key, signal, context });
+    await this.io.delete({ key, vars, signal });
   }
 
-  public async clear(context: Context, signal: AbortSignal): Promise<void> {
+  public async clear(vars: Variables, signal: AbortSignal): Promise<void> {
     if (!this.io.isOpen) {
       throw new StorageIsNotOpenError({ name: this.io.name });
     }
 
-    await this.io.clear({ signal, context });
+    await this.io.clear({ vars, signal });
   }
 
   public async getReadable(
-    context: Context,
+    vars: Variables,
     signal: AbortSignal,
     key: IStorage.Key,
   ): Promise<IReadableStream> {
@@ -102,14 +125,14 @@ export default class UniKvsStorage {
       throw new ReadableStreamNotSupportedError({ name: this.io.name });
     }
 
-    const output = await this.io.getReadable({ key, signal, context });
-    const parsed = v.parseOutput(v.instance(ReadableStream), output);
+    const output = await this.io.getReadable({ key, vars, signal });
+    const parsed = v.parseOutput(ReadableStreamSchema, output);
 
     return parsed;
   }
 
   public async getWritable(
-    context: Context,
+    vars: Variables,
     signal: AbortSignal,
     key: IStorage.Key,
   ): Promise<IWritableStream> {
@@ -121,14 +144,14 @@ export default class UniKvsStorage {
       throw new WritableStreamNotSupportedError({ name: this.io.name });
     }
 
-    const output = await this.io.getWritable({ key, signal, context });
-    const parsed = v.parseOutput(v.instance(WritableStream), output);
+    const output = await this.io.getWritable({ key, vars, signal });
+    const parsed = v.parseOutput(WritableStreamSchema, output);
 
     return parsed;
   }
 
   public async onOtherWriteError(
-    context: Context,
+    vars: Variables,
     signal: AbortSignal,
     key: IStorage.Key,
     err: PluginOperationAggregateError,
@@ -152,7 +175,7 @@ export default class UniKvsStorage {
         }[];
       }>,
       signal,
-      context,
+      vars,
     });
   }
 }

package/src/_streams.ts

@@ -0,0 +1,47 @@
+import type { IReadableStream, IWritableStream } from "@unikvs/core";
+
+/**
+ * 値が `ReadableStream` のインターフェースを満たすかどうかを判定します。
+ *
+ * ランタイムによっては `ReadableStream` クラスを継承せずに同じインターフェースを備えたオブジェクトが存在するため、`instanceof` ではなく必要なメソッドの有無で判定します。
+ *
+ * @param input 判定する値です。
+ * @returns `ReadableStream` のインターフェースを満たす場合は `true` を返します。
+ */
+export function isReadableStream(input: unknown): input is IReadableStream {
+  if (typeof input !== "object" || input === null) {
+    return false;
+  }
+
+  const stream = input as Partial<IReadableStream>;
+
+  return (
+    typeof stream.getReader === "function" &&
+    typeof stream.pipeThrough === "function" &&
+    typeof stream.pipeTo === "function" &&
+    typeof stream.tee === "function" &&
+    typeof stream.cancel === "function"
+  );
+}
+
+/**
+ * 値が `WritableStream` のインターフェースを満たすかどうかを判定します。
+ *
+ * ランタイムによっては `WritableStream` クラスを継承せずに同じインターフェースを備えたオブジェクトが存在するため、`instanceof` ではなく必要なメソッドの有無で判定します。
+ *
+ * @param input 判定する値です。
+ * @returns `WritableStream` のインターフェースを満たす場合は `true` を返します。
+ */
+export function isWritableStream(input: unknown): input is IWritableStream {
+  if (typeof input !== "object" || input === null) {
+    return false;
+  }
+
+  const stream = input as Partial<IWritableStream>;
+
+  return (
+    typeof stream.getWriter === "function" &&
+    typeof stream.abort === "function" &&
+    typeof stream.close === "function"
+  );
+}

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/_transformer.ts

@@ -1,4 +1,4 @@
-import type { Context, IDecodable, ITransformer, IEncodable } from "@unikvs/core";
+import type { Variables, IDecodable, ITransformer, IEncodable } from "@unikvs/core";
 
 import {
   DecodableStreamNotSupportedError,
@@ -16,48 +16,48 @@ export default class UniKvsTransformer {
     this.managed = false;
   }
 
-  public async open(context: Context, signal: AbortSignal): Promise<void> {
+  public async open(vars: Variables, signal: AbortSignal): Promise<void> {
     if (typeof this.tf.open !== "function") {
       return;
     }
 
     if (!this.tf.isOpen) {
       this.managed = true;
-      await this.tf.open({ signal, context });
+      await this.tf.open({ vars, signal });
     }
   }
 
-  public async close(context: Context, signal: AbortSignal): Promise<void> {
+  public async close(vars: Variables, signal: AbortSignal): Promise<void> {
     if (typeof this.tf.close !== "function") {
       return;
     }
 
     if (this.tf.isOpen && this.managed) {
-      await this.tf.close({ signal, context });
+      await this.tf.close({ vars, signal });
     }
   }
 
-  public async encode(context: Context, signal: AbortSignal, data: any): Promise<unknown> {
+  public async encode(vars: Variables, signal: AbortSignal, data: any): Promise<unknown> {
     if (!this.tf.isOpen) {
       throw new TransformerIsNotOpenError({ name: this.tf.name });
     }
 
-    const output = await this.tf.encode({ data, signal, context });
+    const output = await this.tf.encode({ data, vars, signal });
 
     return output;
   }
 
-  public async decode(context: Context, signal: AbortSignal, data: any): Promise<unknown> {
+  public async decode(vars: Variables, signal: AbortSignal, data: any): Promise<unknown> {
     if (!this.tf.isOpen) {
       throw new TransformerIsNotOpenError({ name: this.tf.name });
     }
 
-    const output = await this.tf.decode({ data, signal, context });
+    const output = await this.tf.decode({ data, vars, signal });
 
     return output;
   }
 
-  public async getEncodable(context: Context, signal: AbortSignal): Promise<IEncodable> {
+  public async getEncodable(vars: Variables, signal: AbortSignal): Promise<IEncodable> {
     if (!this.tf.isOpen) {
       throw new TransformerIsNotOpenError({ name: this.tf.name });
     }
@@ -66,13 +66,13 @@ export default class UniKvsTransformer {
       throw new EncodableStreamNotSupportedError({ name: this.tf.name });
     }
 
-    const output = await this.tf.getEncodable({ signal, context });
+    const output = await this.tf.getEncodable({ vars, signal });
     const parsed = output; // TODO(tai-kun): 要検証
 
     return parsed;
   }
 
-  public async getDecodable(context: Context, signal: AbortSignal): Promise<IDecodable> {
+  public async getDecodable(vars: Variables, signal: AbortSignal): Promise<IDecodable> {
     if (!this.tf.isOpen) {
       throw new TransformerIsNotOpenError({ name: this.tf.name });
     }
@@ -81,7 +81,7 @@ export default class UniKvsTransformer {
       throw new DecodableStreamNotSupportedError({ name: this.tf.name });
     }
 
-    const output = await this.tf.getDecodable({ signal, context });
+    const output = await this.tf.getDecodable({ vars, signal });
     const parsed = output; // TODO(tai-kun): 要検証
 
     return parsed;

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";
 
@@ -9,9 +8,11 @@ import {
   InvalidOutputError,
 } from "./errors.js";
 
-export type { InferInput, InferOutput } from "valibot";
+export type { GenericSchema, InferInput, InferOutput } from "valibot";
 export {
   any,
+  check,
+  custom,
   omit,
   pipe,
   union,
@@ -23,20 +24,21 @@ export {
   minValue,
   optional,
   safeInteger,
+  safeParse,
 } from "valibot";
 
 export { array, tuple, object, record, transform } from "@tai-kun/valibot-extra-lab";
 
 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 +51,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>(