unikvs 0.0.10 → 0.0.13

package/src/_logger.ts

@@ -1,5 +1,7 @@
-import { getLogger } from "@logtape/logtape";
+import { type Logger, getLogger } from "@logtape/logtape";
 
-const logger = getLogger("unikvs");
+// 既定のロガーです。
+export const logger: Logger = getLogger("unikvs");
 
-export default logger;
+// 書き戻しに関する警告専用のロガーです。
+export const repairLogger: Logger = getLogger(["@unikvs/*", "@unikvs/allow-repair"]);

package/src/_middleware.ts

@@ -0,0 +1,207 @@
+import type { IMiddleware } from "@unikvs/core";
+import { asyncmux } from "asyncmux";
+import { callFnOnce } from "call-fn-once";
+
+import { PluginLifecycle } from "./_plugin-lifecycle.js";
+import {
+  MiddlewareIsNotOpenError,
+  StreamDecodingNotSupportedError,
+  StreamEncodingNotSupportedError,
+} from "./errors.js";
+
+/**
+ * 同じオブジェクトに対して同じ `UniKvsMiddleware` インスタンスを返すためのメモです。
+ */
+const instances = /* #__PURE__ */ new WeakMap<IMiddleware, UniKvsMiddleware>();
+
+/**
+ * `IMiddleware` を `UniKvs` 内部から扱うためのラッパーです。
+ *
+ * ミドルウェアを安全に使うための検証などの処理が集約されています。
+ */
+export default class UniKvsMiddleware {
+  /**
+   * ラップするミドルウェアです。
+   */
+  readonly #mw: IMiddleware;
+
+  /**
+   * 参照カウントと実 `close` の再試行を管理します。
+   */
+  readonly #lifecycle: PluginLifecycle<IMiddleware.OpenContext, IMiddleware.CloseContext>;
+
+  /**
+   * ミドルウェアの名前です。
+   */
+  public readonly name: string;
+
+  private constructor(middleware: IMiddleware) {
+    this.#mw = middleware;
+    this.#lifecycle = new PluginLifecycle(middleware);
+    this.name = middleware.name;
+  }
+
+  /**
+   * `IMiddleware` から `UniKvs` 内部から扱うためのミドルウェアを作成します。
+   *
+   * @param middleware 元となるミドルウェアです。
+   *
+   * @returns 検証などの機能が集約されたミドルウェアです。
+   */
+  public static from(middleware: IMiddleware): UniKvsMiddleware {
+    return callFnOnce(instances, middleware, () => new UniKvsMiddleware(middleware));
+  }
+
+  /**
+   * ミドルウェアを開きます。
+   *
+   * @param c オープンコンテキストです。
+   */
+  @asyncmux
+  public async open(c: IMiddleware.OpenContext): Promise<void> {
+    await this.#lifecycle.open(c);
+  }
+
+  /**
+   * ミドルウェアを閉じます。
+   *
+   * @param c クローズコンテキストです。
+   */
+  @asyncmux
+  public async close(c: IMiddleware.CloseContext): Promise<void> {
+    await this.#lifecycle.close(c);
+  }
+
+  /**
+   * 失敗した実 `close` だけを再試行します。
+   *
+   * @param c クローズコンテキストです。
+   */
+  @asyncmux
+  public async retryClose(c: IMiddleware.CloseContext): Promise<void> {
+    await this.#lifecycle.retryClose(c);
+  }
+
+  /**
+   * キーを写像します。
+   *
+   * @param c キー写像コンテキストです。
+   *
+   * @returns 写像後のキーを返します。
+   */
+  public mapKey(c: IMiddleware.MapKeyContext): string {
+    if (!this.#mw.isOpen) {
+      throw new MiddlewareIsNotOpenError({ name: this.name });
+    }
+
+    if (this.#mw.mapKey === undefined) {
+      // 既定ではキーをそのまま似します。
+      return c.key;
+    }
+
+    return this.#mw.mapKey(c);
+  }
+
+  /**
+   * 任意の操作に割り込みます。
+   *
+   * @param c 操作コンテキストです。
+   * @param next 後段の処理です。
+   */
+  public async use(c: IMiddleware.UseContext, next: IMiddleware.INext): Promise<void> {
+    if (!this.#mw.isOpen) {
+      throw new MiddlewareIsNotOpenError({ name: this.name });
+    }
+
+    if (this.#mw.use === undefined) {
+      // 既定では後段の処理を実行します。
+      await next();
+    } else {
+      await this.#mw.use(c, next);
+    }
+  }
+
+  /**
+   * データをエンコードします。
+   *
+   * @param c エンコードコンテキストです。
+   * @param next 後段の処理です。
+   */
+  public async encode(c: IMiddleware.EncodeContext, next: IMiddleware.INext): Promise<void> {
+    if (!this.#mw.isOpen) {
+      throw new MiddlewareIsNotOpenError({ name: this.name });
+    }
+
+    if (this.#mw.encode === undefined) {
+      // 既定ではデータを素通りさせます。
+      c.destination = c.source;
+
+      await next();
+    } else {
+      await this.#mw.encode(c, next);
+    }
+  }
+
+  /**
+   * データをデコードします。
+   *
+   * @param c デコードコンテキストです。
+   * @param next 後段の処理です。
+   */
+  public async decode(c: IMiddleware.DecodeContext, next: IMiddleware.INext): Promise<void> {
+    if (!this.#mw.isOpen) {
+      throw new MiddlewareIsNotOpenError({ name: this.name });
+    }
+
+    if (this.#mw.decode === undefined) {
+      // 既定ではデータを素通りさせます。
+      c.destination = c.source;
+
+      await next();
+    } else {
+      await this.#mw.decode(c, next);
+    }
+  }
+
+  /**
+   * ストリームをエンコードします。
+   *
+   * @param c エンコードストリームコンテキストです。
+   * @param next 後段の処理です。
+   */
+  public async encodeStream(
+    c: IMiddleware.EncodeStreamContext,
+    next: IMiddleware.INext,
+  ): Promise<void> {
+    if (!this.#mw.isOpen) {
+      throw new MiddlewareIsNotOpenError({ name: this.name });
+    }
+
+    if (this.#mw.encodeStream === undefined) {
+      throw new StreamEncodingNotSupportedError({ name: this.name });
+    }
+
+    await this.#mw.encodeStream(c, next);
+  }
+
+  /**
+   * ストリームをデコードします。
+   *
+   * @param c デコードストリームコンテキストです。
+   * @param next 後段の処理です。
+   */
+  public async decodeStream(
+    c: IMiddleware.DecodeStreamContext,
+    next: IMiddleware.INext,
+  ): Promise<void> {
+    if (!this.#mw.isOpen) {
+      throw new MiddlewareIsNotOpenError({ name: this.name });
+    }
+
+    if (this.#mw.decodeStream === undefined) {
+      throw new StreamDecodingNotSupportedError({ name: this.name });
+    }
+
+    await this.#mw.decodeStream(c, next);
+  }
+}

package/src/_pipeline-graph.helpers.ts

@@ -0,0 +1,183 @@
+import { type IReadableStream, type ITransformContext } from "@unikvs/core";
+
+import {
+  type DecodeContext,
+  type EncodeContext,
+  type DecodeStreamContext,
+  type EncodeStreamContext,
+  MapKeyContext,
+} from "./_contexts.js";
+import type UniKvsMiddleware from "./_middleware.js";
+import type {
+  PipelineLeaf,
+  PipelineNode,
+  PipelineEntry,
+  OperationScope,
+  IActiveLeafChecker,
+} from "./_pipeline-graph.types.js";
+import { ReadableStreamSchema } from "./_streams.schemas.js";
+import { parseOutput } from "./_valibot.js";
+import { MiddlewareDestinationFrozenError, MiddlewareDestinationMissingError } from "./errors.js";
+
+/**
+ * 対象判定に通る葉だけを登録順に絞ります。
+ *
+ * 全葉が対象なら複製せず `node.allLeaves` を返します。
+ *
+ * @param node 対象の節です。
+ * @param isActive 書き込み対象とする葉を判定します。
+ *
+ * @returns 対象の葉を登録順に返します。
+ */
+export function activeLeavesOf(
+  node: PipelineNode,
+  isActive: IActiveLeafChecker,
+): readonly PipelineLeaf[] {
+  const active = node.allLeaves.filter(isActive);
+
+  if (active.length === node.allLeaves.length) {
+    return node.allLeaves;
+  }
+
+  return active;
+}
+
+/**
+ * 葉と節を登録順に並べた静的な項目列を作成します。
+ *
+ * 各操作の走査はこの並びをそのまま読みます。
+ * 並べ替え用の順序は項目に保持せず、作成時のローカル変数で解決します。
+ *
+ * @param leaves この節で終端する葉です。
+ * @param children 子の節です。
+ *
+ * @returns 登録順に並べた項目列を返します。
+ */
+export function createEntries(
+  leaves: readonly PipelineLeaf[],
+  children: readonly PipelineNode[],
+): PipelineEntry[] {
+  return [
+    ...leaves.map((leaf) => ({
+      entry: {
+        kind: "leaf" as const,
+        leaf,
+      },
+      order: leaf.index,
+    })),
+    ...children.map((child) => {
+      const [firstLeaf] = child.allLeaves;
+
+      if (firstLeaf === undefined) {
+        throw new Error("子節に葉が存在しません。");
+      }
+
+      return {
+        entry: {
+          kind: "node" as const,
+          node: child,
+        },
+        order: firstLeaf.index,
+      };
+    }),
+  ]
+    .toSorted((a, b) => a.order - b.order)
+    .map((item) => item.entry);
+}
+
+/**
+ * 変換後のデータが設定されていることを検証し、変換後のデータを返します。
+ *
+ * ミドルウェアが `destination` を設定しなかったときに投げます。
+ *
+ * @param middleware 対象のミドルウェアです。
+ * @param ctx 検証するコンテキストです。
+ * @param operation エラーに付与する操作名です。
+ *
+ * @returns 変換後のデータを返します。
+ */
+export function requireDestination(
+  middleware: UniKvsMiddleware,
+  ctx: EncodeContext | DecodeContext | EncodeStreamContext | DecodeStreamContext,
+  operation: "encode" | "decode",
+): unknown {
+  if ("destination" in ctx) {
+    return ctx.destination;
+  }
+
+  throw new MiddlewareDestinationMissingError({
+    name: middleware.name,
+    operation,
+  });
+}
+
+/**
+ * 変換後のストリームが設定されていることを検証し、型を検証したストリームを返します。
+ *
+ * ミドルウェアが `destination` を設定しなかったときに投げます。
+ * ストリームの場合は存在確認に加えて `ReadableStream` の型も検証します。
+ *
+ * @param middleware 対象のミドルウェアです。
+ * @param ctx 検証するコンテキストです。
+ * @param operation エラーに付与する操作名です。
+ *
+ * @returns 変換後のストリームを返します。
+ */
+export function requireStreamDestination(
+  middleware: UniKvsMiddleware,
+  ctx: EncodeStreamContext | DecodeStreamContext,
+  operation: "encode" | "decode",
+): IReadableStream {
+  const destination = requireDestination(middleware, ctx, operation);
+
+  return parseOutput(ReadableStreamSchema, destination);
+}
+
+/**
+ * コンテキストの `destination` を凍結します。
+ *
+ * パイプラインの `next` から同期的に呼び出します。
+ * 凍結後の読み取りはできますが、書き込むと `MiddlewareDestinationFrozenError` を投げます。
+ *
+ * @param ctx 凍結するコンテキストです。
+ */
+export function freezeDestination(ctx: ITransformContext): void {
+  const { destination } = ctx;
+  Object.defineProperty(ctx, "destination", {
+    get() {
+      return destination;
+    },
+    set() {
+      throw new MiddlewareDestinationFrozenError({
+        key: ctx.key,
+        action: ctx.action,
+      });
+    },
+    enumerable: true,
+    configurable: true,
+  });
+}
+
+/**
+ * 単一ミドルウェアの `mapKey` を実行します。
+ *
+ * 共有ストアを参照するため、カスタム変数の下流変更が写像にも見えます。
+ *
+ * @param middleware 対象のミドルウェアです。
+ * @param key 写像前のキーです。
+ * @param scope 操作共通の実行時情報です。
+ *
+ * @returns 写像後のキーを返します。
+ */
+export function applyMapKey(
+  middleware: UniKvsMiddleware,
+  key: string,
+  scope: OperationScope,
+): string {
+  const c = new MapKeyContext({
+    key,
+    store: scope.store,
+  });
+
+  return middleware.mapKey(c);
+}