unikvs 0.0.10 → 0.0.13

package/src/_storage.ts

@@ -1,6 +1,10 @@
-import type { Context, IStorage, ErrorBase, IReadableStream, IWritableStream } from "@unikvs/core";
+import type { IStorage, IReadableStream, IWritableStream } from "@unikvs/core";
+import { asyncmux } from "asyncmux";
+import { callFnOnce } from "call-fn-once";
 
-import * as v from "./_valibot.js";
+import { PluginLifecycle } from "./_plugin-lifecycle.js";
+import { ReadableStreamSchema, WritableStreamSchema } from "./_streams.schemas.js";
+import { parseOutput } from "./_valibot.js";
 import {
   type PluginOperationAggregateError,
   StorageIsNotOpenError,
@@ -8,151 +12,224 @@ import {
   WritableStreamNotSupportedError,
 } from "./errors.js";
 
-export default class UniKvsStorage {
-  private readonly io: IStorage;
-
-  private managed: boolean;
+/**
+ * 同じオブジェクトに対して同じ `UniKvsStorage` インスタンスを返すためのメモです。
+ */
+const instances = /* #__PURE__ */ new WeakMap<IStorage, UniKvsStorage>();
 
-  public constructor(io: IStorage) {
-    this.io = io;
-    this.managed = false;
+/**
+ * `IStorage` を `UniKvs` 内部から扱うためのラッパーです。
+ *
+ * ストレージを安全に使うための検証などの処理が集約されています。
+ */
+export default class UniKvsStorage {
+  /**
+   * ラップするストレージです。
+   */
+  readonly #io: IStorage;
+
+  /**
+   * 参照カウントと実 `close` の再試行を管理します。
+   */
+  readonly #lifecycle: PluginLifecycle<IStorage.OpenContext, IStorage.CloseContext>;
+
+  /**
+   * ストレージの名前です。
+   */
+  public readonly name: string;
+
+  private constructor(storage: IStorage) {
+    this.#io = storage;
+    this.#lifecycle = new PluginLifecycle(storage);
+    this.name = storage.name;
   }
 
-  public async open(context: Context, signal: AbortSignal): Promise<void> {
-    if (typeof this.io.open !== "function") {
-      return;
-    }
+  /**
+   * `IStorage` から `UniKvs` 内部から扱うためのストレージを作成します。
+   *
+   * @param storage 元となるストレージです。
+   *
+   * @returns 検証などの機能が集約されたストレージです。
+   */
+  public static from(storage: IStorage): UniKvsStorage {
+    return callFnOnce(instances, storage, () => new UniKvsStorage(storage));
+  }
 
-    if (!this.io.isOpen) {
-      this.managed = true;
-      await this.io.open({ signal, context });
-    }
+  /**
+   * ストレージを開きます。
+   *
+   * @param c オープンコンテキストです。
+   */
+  @asyncmux
+  public async open(c: IStorage.OpenContext): Promise<void> {
+    await this.#lifecycle.open(c);
   }
 
-  public async close(context: Context, signal: AbortSignal): Promise<void> {
-    if (typeof this.io.close !== "function") {
-      return;
-    }
+  /**
+   * ストレージを閉じます。
+   *
+   * @param c クローズコンテキストです。
+   */
+  @asyncmux
+  public async close(c: IStorage.CloseContext): Promise<void> {
+    await this.#lifecycle.close(c);
+  }
 
-    if (this.io.isOpen && this.managed) {
-      await this.io.close({ signal, context });
-    }
+  /**
+   * 失敗した実 `close` だけを再試行します。
+   *
+   * @param c クローズコンテキストです。
+   */
+  @asyncmux
+  public async retryClose(c: IStorage.CloseContext): Promise<void> {
+    await this.#lifecycle.retryClose(c);
   }
 
-  public async write(
-    context: Context,
-    signal: AbortSignal,
-    key: IStorage.Key,
-    data: unknown,
-  ): Promise<void> {
-    if (!this.io.isOpen) {
-      throw new StorageIsNotOpenError({ name: this.io.name });
+  /**
+   * データを書き込みます。
+   *
+   * @param c 書き込みコンテキストです。
+   * @param data 書き込むデータです。
+   */
+  public async write(c: IStorage.WriteContext, data: unknown): Promise<void> {
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
     }
 
-    await this.io.write({ key, data, signal, context });
+    await this.#io.write(c, data);
   }
 
-  public async read(context: Context, signal: AbortSignal, key: IStorage.Key): Promise<unknown> {
-    if (!this.io.isOpen) {
-      throw new StorageIsNotOpenError({ name: this.io.name });
+  /**
+   * データを読み取ります。
+   *
+   * @param c 読み取りコンテキストです。
+   *
+   * @returns 読み取ったデータを返します。
+   */
+  public async read(c: IStorage.ReadContext): Promise<unknown> {
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
     }
 
-    const output = await this.io.read({ key, signal, context });
-
-    return output;
+    return await this.#io.read(c);
   }
 
-  public async exists(context: Context, signal: AbortSignal, key: IStorage.Key): Promise<boolean> {
-    if (!this.io.isOpen) {
-      throw new StorageIsNotOpenError({ name: this.io.name });
+  /**
+   * データの存在を確認します。
+   *
+   * @param c 存在確認コンテキストです。
+   *
+   * @returns 存在する場合は `true` を返します。
+   */
+  public async exists(c: IStorage.ExistsContext): Promise<boolean> {
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
     }
 
-    const output = await this.io.exists({ key, signal, context });
-    const parsed = Boolean(output);
+    const output = await this.#io.exists(c);
 
-    return parsed;
+    return output;
   }
 
-  public async delete(context: Context, signal: AbortSignal, key: IStorage.Key): Promise<void> {
-    if (!this.io.isOpen) {
-      throw new StorageIsNotOpenError({ name: this.io.name });
+  /**
+   * データを削除します。
+   *
+   * @param c 削除コンテキストです。
+   */
+  public async delete(c: IStorage.DeleteContext): Promise<void> {
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
     }
 
-    await this.io.delete({ key, signal, context });
+    await this.#io.delete(c);
   }
 
-  public async clear(context: Context, signal: AbortSignal): Promise<void> {
-    if (!this.io.isOpen) {
-      throw new StorageIsNotOpenError({ name: this.io.name });
+  /**
+   * データをすべて削除します。
+   *
+   * @param c クリアコンテキストです。
+   */
+  public async clear(c: IStorage.ClearContext): Promise<void> {
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
     }
 
-    await this.io.clear({ signal, context });
+    await this.#io.clear(c);
   }
 
-  public async getReadable(
-    context: Context,
-    signal: AbortSignal,
-    key: IStorage.Key,
-  ): Promise<IReadableStream> {
-    if (!this.io.isOpen) {
-      throw new StorageIsNotOpenError({ name: this.io.name });
+  /**
+   * 読み取り用のストリームを取得します。
+   *
+   * @param c ストリーム取得コンテキストです。
+   *
+   * @returns 読み取り用のストリームを返します。
+   */
+  public async getReadable(c: IStorage.GetReadableContext): Promise<IReadableStream> {
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
     }
 
-    if (typeof this.io.getReadable !== "function") {
-      throw new ReadableStreamNotSupportedError({ name: this.io.name });
+    if (this.#io.getReadable === undefined) {
+      throw new ReadableStreamNotSupportedError({ name: this.name });
     }
 
-    const output = await this.io.getReadable({ key, signal, context });
-    const parsed = v.parseOutput(v.instance(ReadableStream), output);
+    const output = await this.#io.getReadable(c);
 
-    return parsed;
+    return parseOutput(ReadableStreamSchema, output);
   }
 
-  public async getWritable(
-    context: Context,
-    signal: AbortSignal,
-    key: IStorage.Key,
-  ): Promise<IWritableStream> {
-    if (!this.io.isOpen) {
-      throw new StorageIsNotOpenError({ name: this.io.name });
+  /**
+   * 書き込み用のストリームを取得します。
+   *
+   * @param c ストリーム取得コンテキストです。
+   *
+   * @returns 書き込み用のストリームを返します。
+   */
+  public async getWritable(c: IStorage.GetWritableContext): Promise<IWritableStream> {
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
     }
 
-    if (typeof this.io.getWritable !== "function") {
-      throw new WritableStreamNotSupportedError({ name: this.io.name });
+    if (this.#io.getWritable === undefined) {
+      throw new WritableStreamNotSupportedError({ name: this.name });
     }
 
-    const output = await this.io.getWritable({ key, signal, context });
-    const parsed = v.parseOutput(v.instance(WritableStream), output);
+    const output = await this.#io.getWritable(c);
 
-    return parsed;
+    return parseOutput(WritableStreamSchema, output);
   }
 
+  /**
+   * 他のストレージへの書き込み失敗を通知します。
+   *
+   * @param c 書き込み失敗通知コンテキストです。
+   * @param err 集約エラーです。
+   */
   public async onOtherWriteError(
-    context: Context,
-    signal: AbortSignal,
-    key: IStorage.Key,
+    c: IStorage.OtherWriteErrorHandlerContext,
     err: PluginOperationAggregateError,
   ): Promise<void> {
-    if (!this.io.isOpen) {
-      throw new StorageIsNotOpenError({ name: this.io.name });
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
     }
 
-    if (typeof this.io.onOtherWriteError !== "function") {
+    if (this.#io.onOtherWriteError === undefined) {
       return;
     }
 
-    await this.io.onOtherWriteError({
-      key,
-      error: err as ErrorBase<{
-        readonly plugin: "storage";
-        readonly action: "write";
-        readonly errors: readonly {
-          readonly plugin: "storage";
-          readonly reason: unknown;
-        }[];
-      }>,
-      signal,
-      context,
-    });
+    await this.#io.onOtherWriteError(c, [
+      {
+        errors: (
+          err.meta.errors as readonly {
+            readonly plugin: "storage";
+            readonly reason: unknown;
+          }[]
+        ).map((error) => ({
+          plugin: "storage" as const,
+          reason: error.reason,
+        })),
+        plugin: "storage",
+      },
+    ]);
   }
 }

package/src/_streams.schemas.ts

@@ -0,0 +1,21 @@
+import type { IReadableStream, IWritableStream } from "@unikvs/core";
+import type { CustomIssue, CustomSchema, ErrorMessage } from "valibot";
+
+import { isReadableStream, isWritableStream } from "./_streams.js";
+import { custom } from "./_valibot.js";
+
+/**
+ * `ReadableStream` のインターフェースを満たすかを検証するためのスキーマです。
+ */
+export const ReadableStreamSchema: CustomSchema<
+  IReadableStream,
+  ErrorMessage<CustomIssue> | undefined
+> = custom<IReadableStream>(isReadableStream, "Expected a ReadableStream");
+
+/**
+ * `WritableStream` のインターフェースを満たすかを検証するためのスキーマです。
+ */
+export const WritableStreamSchema: CustomSchema<
+  IWritableStream,
+  ErrorMessage<CustomIssue> | undefined
+> = custom<IWritableStream>(isWritableStream, "Expected a WritableStream");

package/src/_streams.ts

@@ -0,0 +1,73 @@
+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.tee === "function" &&
+    typeof stream.cancel === "function" &&
+    typeof stream.pipeTo === "function" &&
+    typeof stream.getReader === "function" &&
+    typeof stream.pipeThrough === "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.abort === "function" &&
+    typeof stream.close === "function" &&
+    typeof stream.getWriter === "function"
+  );
+}
+
+/**
+ * ストリームの重複を除いてキャンセルします。
+ *
+ * 個々のキャンセルに失敗しても無視し、元の例外を優先して伝えます。
+ *
+ * @param streams キャンセルするストリームです。
+ * @param reason キャンセル理由です。
+ */
+export async function cancelStreams(
+  streams: Iterable<IReadableStream>,
+  reason: unknown,
+): Promise<void> {
+  // 同じ参照は 1 回だけキャンセルします。
+  await Promise.all(
+    [...new Set(streams)].map(async (stream) => {
+      try {
+        await stream.cancel(reason);
+      } catch {
+        // キャンセルに失敗しても元の例外の伝播を優先します。
+      }
+    }),
+  );
+}

package/src/_to-value-stream.ts

@@ -1,27 +1,33 @@
 import type { IReadableStream } from "@unikvs/core";
 import { callAsyncableFnOnce } from "call-fn-once";
 
-import logger from "./_logger.js";
-import type { ValueStream } from "./value-stream.types.js";
+import { logger } from "./_logger.js";
+import type { IValueStream } from "./types.js";
 
 /**
- * 与えられた `IReadableStream` を `ValueStream` に変換します。
+ * 与えられた `IReadableStream` を `IValueStream` に変換します。
  *
  * @template T ストリームが保持する値の型です。
+ *
  * @param readableStream 変換対象となる `IReadableStream` インスタンスです。
  * @param onAsyncDispose ストリーム破棄時の処理です。
+ * @param onBeforeDispose ソースストリームをキャンセルする前に呼ばれる処理です。
+ *
  * @returns 非同期イテレーターが付与された `ValueStream` インスタンスを返します。
  */
 export default function toValueStream<T>(
   readableStream: IReadableStream<T>,
   onAsyncDispose: () => Promise<void>,
-): ValueStream<T> {
+  onBeforeDispose?: () => void,
+): IValueStream<T> {
   const cacheMap = new Map();
   const reader = readableStream.getReader();
 
   async function disposeValueStream(): Promise<void> {
     await callAsyncableFnOnce(cacheMap, "dispose", async () => {
       try {
+        // ソースストリームのキャンセルが他の分岐の解放を待つ場合、先に分岐を中断しないと破棄が停止します。
+        onBeforeDispose?.();
         await reader.cancel();
       } catch (ex) {
         logger.error`Failed to cancel the source stream: ${ex}`;
@@ -33,9 +39,10 @@ export default function toValueStream<T>(
 
   // cancel・エラー・早期 break であっても dispose されるように、readable 側のキャンセルを直接フックしたストリームを返します。
   const valueStream = new ReadableStream<T>({
-    async pull(controller) {
+    async pull(controller): Promise<void> {
       try {
         const { done, value } = await reader.read();
+
         if (done) {
           // ストリームが正常に完了したことも dispose 対象とし、完了を通知する前に破棄を完了させます。
           await disposeValueStream();
@@ -46,12 +53,14 @@ export default function toValueStream<T>(
       } catch (ex) {
         // ソースエラー時も dispose (ロック解放など) を行わないと、ストリームを放棄した consumer に対してキーの I/O ロックがリークします。
         // dispose 自体が失敗しても元の例外の伝播を壊さないように、失敗はログに残すだけにします。
-        await disposeValueStream().catch((e) => logger.error`Failed to dispose value stream: ${e}`);
+        await disposeValueStream().catch((disposeError) => {
+          logger.error`Failed to dispose value stream: ${disposeError}`;
+        });
         controller.error(ex);
       }
     },
 
-    async cancel() {
+    async cancel(): Promise<void> {
       await disposeValueStream();
     },
   });
@@ -59,7 +68,7 @@ export default function toValueStream<T>(
   const stream = Object.assign(
     valueStream,
 
-    // AsyncDisposable
+    // AsyncDisposable。
     {
       [Symbol.asyncDispose]: disposeValueStream,
     },
@@ -69,14 +78,16 @@ export default function toValueStream<T>(
       dispose: disposeValueStream,
     },
 
-    // AsyncIterable<T, void, unknown>
+    // AsyncIterable<T, void, unknown>。
     {
       async *[Symbol.asyncIterator](this: ReadableStream<T>) {
         const r = this.getReader();
+
         try {
           // ストリームが終了するまでループを回し、チャンクを読み取ります。
           while (true) {
             const { done, value } = await r.read();
+
             if (done) {
               break;
             }
@@ -87,8 +98,8 @@ export default function toValueStream<T>(
           // エラーが発生した場合は、リーダーのキャンセルを試みます。
           try {
             await r.cancel(ex);
-          } catch (ex) {
-            logger.error`Failed to cancel reader: ${ex}`;
+          } catch (cancelError) {
+            logger.error`Failed to cancel reader: ${cancelError}`;
           }
 
           throw ex;