unikvs 0.0.13 → 0.0.14

package/src/errors.ts

@@ -845,6 +845,21 @@ setErrorMessage(
 //
 // -------------------------------------------------------------------------------------------------。
 
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#errors)
+ */
+export class InvalidForkError extends ErrorBase<undefined> {
+  static {
+    this.prototype.name = "UniKvsInvalidForkError";
+  }
+
+  public constructor(options?: ErrorOptions) {
+    super("A forked branch does not reach any storage", options);
+  }
+}
+
+setErrorMessage(InvalidForkError, "ストレージに到達しない分岐があります", "ja");
+
 /**
  * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#errors)
  */
@@ -863,3 +878,22 @@ setErrorMessage(
   "UniKvs を使用するためには最低 1 つのストレージが必要です",
   "ja",
 );
+
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#errors)
+ */
+export class UnterminatedPipelineError extends ErrorBase<undefined> {
+  static {
+    this.prototype.name = "UniKvsUnterminatedPipelineError";
+  }
+
+  public constructor(options?: ErrorOptions) {
+    super("The pipeline does not end with a storage", options);
+  }
+}
+
+setErrorMessage(
+  UnterminatedPipelineError,
+  "パイプラインがストレージで終わっていません。use() の後に persist() または fork() を呼び出してください",
+  "ja",
+);

package/src/index.ts

@@ -34,6 +34,7 @@ export type {
   MiddlewareNextCalledMultipleTimesErrorMeta,
 } from "./errors.js";
 export {
+  InvalidForkError,
   KeyNotFoundError,
   InvalidInputError,
   UniKvsIsOpenError,
@@ -43,6 +44,7 @@ export {
   InvalidUsageErrorBase,
   StorageIsNotOpenError,
   MiddlewareIsNotOpenError,
+  UnterminatedPipelineError,
   MiddlewareNextNotCalledError,
   MiddlewareNextNotAwaitedError,
   PluginOperationAggregateError,

package/src/unikvs-branch.ts

@@ -46,6 +46,13 @@ export interface IUniKvsBranch<
   TLastEncodeChunkOutput = any,
   TBranchHasPersist extends boolean = false,
 > {
+  /**
+   * 分岐したパイプラインを追加します。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#builder-fork)
+   *
+   * @throws 分岐がストレージに到達しない場合に `InvalidForkError` を投げます。
+   */
   fork<
     TSubChunkInput,
     TSubChunkOutput,
@@ -245,21 +252,6 @@ export default class UniKvsBranch<
     });
   }
 
-  /**
-   * この分岐の構築状態を取得します。
-   *
-   * @returns 構築状態を返します。
-   */
-  #branchState(): BranchState {
-    const state = branchStates.get(this);
-
-    if (state === undefined) {
-      throw new Error("分岐の構築状態が見つかりません。");
-    }
-
-    return state;
-  }
-
   public fork<
     TSubChunkInput,
     TSubChunkOutput,
@@ -442,4 +434,19 @@ export default class UniKvsBranch<
 
     return this;
   }
+
+  /**
+   * この分岐の構築状態を取得します。
+   *
+   * @returns 構築状態を返します。
+   */
+  #branchState(): BranchState {
+    const state = branchStates.get(this);
+
+    if (state === undefined) {
+      throw new Error("分岐の構築状態が見つかりません。");
+    }
+
+    return state;
+  }
 }

package/src/unikvs-builder.ts

@@ -19,18 +19,7 @@ import type {
 } from "./_types.js";
 import { appendForkDestinations } from "./_unikvs-branch.js";
 import { VariablesArgsSchema, VariablesInitSchema } from "./_unikvs.schemas.js";
-import type { GenericSchema } from "./_valibot.js";
-import {
-  array,
-  tuple,
-  union,
-  custom,
-  object,
-  record,
-  string,
-  optional,
-  parseInput,
-} from "./_valibot.js";
+import * as v from "./_valibot.js";
 import {
   type ValueSchemaInfo,
   type $InferPlainValueData,
@@ -39,7 +28,7 @@ import {
   VALUE_SCHEMA_BRAND,
   createValueSchemaResolver,
 } from "./_value-schemas.js";
-import { MissingStorageError } from "./errors.js";
+import { MissingStorageError, UnterminatedPipelineError } from "./errors.js";
 import type { IUniKvsBranch, KeyValueMapping } from "./unikvs-branch.js";
 import UniKvs from "./unikvs.js";
 import type { Value } from "./value-schemas.js";
@@ -67,6 +56,13 @@ export interface IUniKvsBuilder<
   TLastMiddlewareDecodeChunkInput = TUniKvsChunkOutput,
   TLastMiddlewareEncodeChunkOutput = TUniKvsChunkInput,
 > {
+  /**
+   * 分岐したパイプラインを追加します。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#builder-fork)
+   *
+   * @throws 分岐がストレージに到達しない場合に `InvalidForkError` を投げます。
+   */
   fork<
     TBranchChunkInput,
     TBranchChunkOutput,
@@ -201,6 +197,16 @@ export interface IUniKvsBuilder<
    * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#base-vars-defaults-vars)
    */
   defaultsVars(vars: VariablesInit): this;
+
+  /**
+   * 現在の構成が有効かどうかを判定します。
+   *
+   * 有効とは、1 件以上のストレージが登録され、パイプラインがストレージで終わっている状態です。
+   * ストレージに到達しない分岐は `fork()` の時点で `InvalidForkError` になるため、分岐の有効性は fork 時に保証されます。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#builder-is-valid)
+   */
+  isValid(): boolean;
 }
 
 /**
@@ -217,6 +223,13 @@ export interface IUniKvsBuilderFinalizer<
   TLastMiddlewareDecodeChunkInput = TReadChunkOutput,
   TLastMiddlewareEncodeChunkOutput = TWriteChunkInput,
 > {
+  /**
+   * 分岐したパイプラインを追加します。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#builder-fork)
+   *
+   * @throws 分岐がストレージに到達しない場合に `InvalidForkError` を投げます。
+   */
   fork<
     TBranchChunkInput,
     TBranchChunkOutput,
@@ -344,7 +357,29 @@ export interface IUniKvsBuilderFinalizer<
    */
   defaultsVars(vars: VariablesInit): this;
 
-  build(): UniKvs<TKeyValueMapping>;
+  /**
+   * 現在の構成が有効かどうかを判定します。
+   *
+   * 有効とは、1 件以上のストレージが登録され、パイプラインがストレージで終わっている状態です。
+   * ストレージに到達しない分岐は `fork()` の時点で `InvalidForkError` になるため、分岐の有効性は fork 時に保証されます。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#builder-is-valid)
+   */
+  isValid(): boolean;
+
+  /**
+   * `UniKvs` クライアントを作成します。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#builder)
+   *
+   * @param options ビルドオプションです。
+   *
+   * @returns 作成したクライアントを返します。
+   *
+   * @throws ストレージが 1 件もない場合に `MissingStorageError` を投げます。
+   * @throws パイプラインがストレージで終わっていない場合に `UnterminatedPipelineError` を投げます。
+   */
+  build(options?: UniKvsBuildOptions): UniKvs<TKeyValueMapping>;
 }
 
 /**
@@ -358,6 +393,25 @@ export type UniKvsBuilderOptions = {
   readonly schema?: UniKvsSchema | undefined;
 };
 
+/**
+ * `build()` のオプションです。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#builder)
+ */
+export type UniKvsBuildOptions = {
+  /**
+   * 既存のすべてのミドルウェアより前に挿入するミドルウェアの配列です。
+   * 先頭ほど手前、末尾ほど後続のミドルウェアに近づくように挿入されます。
+   */
+  readonly beforeAll?: readonly IMiddleware[] | undefined;
+
+  /**
+   * すべてのストレージの直前に挿入するミドルウェアの配列です。
+   * 先頭ほど既存のパイプライン側、末尾ほどストレージ側に近づくように挿入されます。
+   */
+  readonly beforeStorage?: readonly IMiddleware[] | undefined;
+};
+
 /**
  * オブジェクト形式のスキーマ定義です。キーをそのままキーとして扱います。
  */
@@ -366,7 +420,7 @@ export type UniKvsSchemaRecord = Readonly<Record<string, Value>>;
 /**
  * 配列形式のスキーマ定義です。キーのスキーマと値のスキーマの組を並べます。
  */
-export type UniKvsSchemaEntries = readonly (readonly [GenericSchema, Value])[];
+export type UniKvsSchemaEntries = readonly (readonly [v.GenericSchema, Value])[];
 
 /**
  * `new Builder()` の `schema` オプションに指定できるスキーマ定義です。
@@ -379,7 +433,7 @@ export type UniKvsSchema = UniKvsSchemaRecord | UniKvsSchemaEntries;
  * @template TSchema 対象となるスキーマ定義の型です。
  */
 export type $InferKeyValueMapping<TSchema extends UniKvsSchema> =
-  TSchema extends readonly (readonly [GenericSchema, infer TValue extends Value])[]
+  TSchema extends readonly (readonly [v.GenericSchema, infer TValue extends Value])[]
     ? Readonly<Record<string, TValue>>
     : TSchema extends Readonly<Record<string, Value>>
       ? { readonly [TKey in keyof TSchema]: TSchema[TKey] }
@@ -388,7 +442,7 @@ export type $InferKeyValueMapping<TSchema extends UniKvsSchema> =
 /**
  * 値が Valibot のスキーマであるかどうかを判定します。
  */
-function isGenericSchema(input: unknown): input is GenericSchema {
+function isGenericSchema(input: unknown): input is v.GenericSchema {
   return (
     typeof input === "object" &&
     input !== null &&
@@ -410,26 +464,29 @@ function isValueSchemaInfo(input: unknown): input is ValueSchemaInfo {
   );
 }
 
-const UniKvsBuilderOptionsSchema = object({
+const UniKvsBuilderOptionsSchema = v.object({
   /**
    * キーと値のスキーマ定義です。
    */
-  schema: optional(
-    union([
-      array(
-        tuple([custom<GenericSchema>(isGenericSchema), custom<ValueSchemaInfo>(isValueSchemaInfo)]),
+  schema: v.optional(
+    v.union([
+      v.array(
+        v.tuple([
+          v.custom<v.GenericSchema>(isGenericSchema),
+          v.custom<ValueSchemaInfo>(isValueSchemaInfo),
+        ]),
       ),
-      record(string(), custom<ValueSchemaInfo>(isValueSchemaInfo)),
+      v.record(v.string(), v.custom<ValueSchemaInfo>(isValueSchemaInfo)),
     ]),
   ),
 
   /**
    * 基本となる実行時変数です。
    */
-  vars: optional(VariablesInitSchema),
+  vars: v.optional(VariablesInitSchema),
 });
 
-const UniKvsBuilderArgsSchema = tuple([optional(UniKvsBuilderOptionsSchema)]);
+const UniKvsBuilderArgsSchema = v.tuple([v.optional(UniKvsBuilderOptionsSchema)]);
 
 /**
  * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#builder)
@@ -482,6 +539,12 @@ export default class UniKvsBuilder<
    */
   readonly #middlewares: UniKvsMiddleware[];
 
+  /**
+   * 最後の `persist()` または `fork()` 以降に追加されたミドルウェアがあるかどうかです。
+   * `build()` 時にストレージで終わっていないパイプラインを検出するために使用します。
+   */
+  #hasUnboundMiddlewares: boolean;
+
   /**
    * キーに対応する値のスキーマ情報を解決するリゾルバーです。
    */
@@ -496,11 +559,12 @@ export default class UniKvsBuilder<
 
   public constructor(options?: Omit<UniKvsBuilderOptions, "schema"> & { readonly schema?: TInit });
   public constructor(...args: unknown[]) {
-    const [options = {}] = parseInput(UniKvsBuilderArgsSchema, args);
+    const [options = {}] = v.parseInput(UniKvsBuilderArgsSchema, args);
     const { vars, schema } = options;
 
     this.#destinations = [];
     this.#middlewares = [];
+    this.#hasUnboundMiddlewares = false;
     this.#valueSchemaResolver = null;
     this.#vars = new Map(vars);
     if (schema) {
@@ -508,7 +572,7 @@ export default class UniKvsBuilder<
     }
   }
 
-  fork<
+  public fork<
     TBranchChunkInput,
     TBranchChunkOutput,
     TBranchHeadEncodeDataInput,
@@ -572,11 +636,12 @@ export default class UniKvsBuilder<
   >;
   public fork(branch: IUniKvsBranch): IUniKvsBuilder {
     appendForkDestinations(this.#destinations, this.#middlewares, branch);
+    this.#hasUnboundMiddlewares = false;
 
     return this;
   }
 
-  use<
+  public use<
     TMiddleware extends IMiddleware<
       [TLastMiddlewareEncodeDataOutput] extends [never] ? any : TLastMiddlewareEncodeDataOutput,
       any,
@@ -605,11 +670,12 @@ export default class UniKvsBuilder<
   >;
   public use(middleware: IMiddleware): IUniKvsBuilder {
     this.#middlewares.push(UniKvsMiddleware.from(middleware));
+    this.#hasUnboundMiddlewares = true;
 
     return this;
   }
 
-  persist<
+  public persist<
     TStorage extends IStorage<
       [TLastMiddlewareEncodeDataOutput] extends [never] ? any : TLastMiddlewareEncodeDataOutput,
       [TLastMiddlewareDecodeDataInput] extends [never] ? any : TLastMiddlewareDecodeDataInput,
@@ -643,13 +709,14 @@ export default class UniKvsBuilder<
       // 登録時点のチェーンをスナップショットして保持するため、以降の use はこの登録に影響しません。
       middlewares: [...this.#middlewares],
     });
+    this.#hasUnboundMiddlewares = false;
 
     return this;
   }
 
   public setVars(vars: VariablesInit): this;
   public setVars(...args: unknown[]): this {
-    const [vars] = parseInput(VariablesArgsSchema, args);
+    const [vars] = v.parseInput(VariablesArgsSchema, args);
 
     this.#vars.clear();
     for (const [name, value] of vars) {
@@ -661,7 +728,7 @@ export default class UniKvsBuilder<
 
   public assignVars(vars: VariablesInit): this;
   public assignVars(...args: unknown[]): this {
-    const [vars] = parseInput(VariablesArgsSchema, args);
+    const [vars] = v.parseInput(VariablesArgsSchema, args);
 
     const target = this.#vars;
     const source = vars;
@@ -675,7 +742,7 @@ export default class UniKvsBuilder<
 
   public defaultsVars(vars: VariablesInit): this;
   public defaultsVars(...args: unknown[]): this {
-    const [vars] = parseInput(VariablesArgsSchema, args);
+    const [vars] = v.parseInput(VariablesArgsSchema, args);
 
     const target = new Map(vars);
     const source = this.#vars;
@@ -689,17 +756,37 @@ export default class UniKvsBuilder<
     return this;
   }
 
-  public build(): UniKvs<TKeyValueMapping> {
+  public isValid(): boolean {
+    return this.#destinations.length > 0 && !this.#hasUnboundMiddlewares;
+  }
+
+  public build(options: UniKvsBuildOptions = {}): UniKvs<TKeyValueMapping> {
     // ストレージが空の場合は UniKvs として機能できないため、例外を投げます。
     if (this.#destinations.length === 0) {
       throw new MissingStorageError();
     }
 
+    // 最後の persist()/fork() 以降に追加されたミドルウェアはどのストレージにも接続されないため、例外を投げます。
+    if (this.#hasUnboundMiddlewares) {
+      throw new UnterminatedPipelineError();
+    }
+
+    const beforeAll = options.beforeAll?.map((mw) => UniKvsMiddleware.from(mw)) ?? [];
+    const beforeStorage = options.beforeStorage?.map((mw) => UniKvsMiddleware.from(mw)) ?? [];
+    // ビルダーを再利用できるよう、挿入は build ごとの複製に対して行います。
+    const destinations =
+      beforeAll.length === 0 && beforeStorage.length === 0
+        ? this.#destinations
+        : this.#destinations.map((dest) => ({
+            storage: dest.storage,
+            middlewares: [...beforeAll, ...dest.middlewares, ...beforeStorage],
+          }));
+
     return new UniKvs(
       [...this.#vars.entries()],
       // ビルダーを再利用できるよう、build のたびに trie をコンパイルします。コンパイル後の登録内容は変更しません。
       // 同じミドルウェアインスタンスに対するラッパーは共有します。
-      PipelineGraph.compile([...this.#destinations]),
+      PipelineGraph.compile(destinations),
       this.#valueSchemaResolver,
     );
   }