unikvs 0.0.9 → 0.0.12

package/src/unikvs-config.ts

@@ -1,19 +1,45 @@
 import type {
-  Context,
-  IReadableStreamStorage,
   IStorage,
+  Variables,
+  ITransformer,
+  IReadableStreamStorage,
   IWritableStreamStorage,
   IDecodableStreamTransformer,
   IEncodableStreamTransformer,
-  ITransformer,
 } from "@unikvs/core";
 
 import UniKvsStorage from "./_storage.js";
 import UniKvsTransformer from "./_transformer.js";
-import type { ContextSource } from "./context.types.js";
+import * as v from "./_valibot.js";
+import {
+  type Value,
+  type UniKvsSchema,
+  type $InferPlainValueData,
+  type IValueSchemaResolver,
+  type $InferStreamValueChunkData,
+  UniKvsSchemaSchema,
+  createValueSchemaResolver,
+} from "./_value-schemas.js";
 import { MissingStorageError } from "./errors.js";
 import type UniKvs from "./unikvs.js";
 import type { ValueOf } from "./utils.types.js";
+import type { VariablesSource } from "./variables.types.js";
+
+export {
+  type UniKvsSchema,
+  type ValueSchemaInfo,
+  type UniKvsSchemaRecord,
+  type UniKvsSchemaEntries,
+  type $InferPlainValueData,
+  type IValueSchemaResolver,
+  type $InferKeyValueMapping,
+  type $InferPlainValueInput,
+  type $InferStreamValueChunkData,
+  type $InferStreamValueChunkInput,
+  Value,
+  PlainValue,
+  StreamValue,
+} from "./_value-schemas.js";
 
 /**
  * トランスフォーマーから、デコード時の入力データの型を推論するユーティリティー型です。
@@ -68,81 +94,18 @@ type $InferReadChunkOutput<TStorage extends IStorage> =
   TStorage extends IReadableStreamStorage<infer TReadChunkOutput> ? TReadChunkOutput : never;
 
 /**
- * プレーンな値を識別するための固有のシンボルです。
- */
-declare const PLAIN_VALUE: unique symbol;
-
-/**
- * ストリームではない通常の値を表す型定義です。
- *
- * @template TData 保持するデータの型です。
- */
-export type PlainValue<TData = any> = [Type: typeof PLAIN_VALUE, Data: TData];
-
-/**
- * ストリーム形式の値を識別するための固有のシンボルです。
- */
-declare const STREAM_VALUE: unique symbol;
-
-/**
- * ストリームとして扱われる値を表す型定義です。
- *
- * @template TChunkData ストリームのチャンクデータの型です。
- */
-export type StreamValue<TChunkData = any> = [Type: typeof STREAM_VALUE, ChunkData: TChunkData];
-
-/**
- * UniKvs で扱う値の抽象型です。プレーンな値かストリーム値のいずれかになります。
- *
- * @template TData データまたはチャンクデータの型です。
- */
-export type Value<TData = any> = PlainValue<TData> | StreamValue<TData>;
-
-/**
- * キーと値のマッピングを定義するオブジェクトの型です。
- *
- * @template T マッピングされる値の型です。
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#value-types)
  */
 export type KeyValueMapping<T = any> = { readonly [key: IStorage.Key]: Value<T> };
 
 /**
- * PlainValue 型から内部のデータ型を抽出します。
- *
- * @template TPlainValue 対象となる PlainValue 型です。
- */
-export type $InferPlainValueData<TPlainValue> =
-  TPlainValue extends PlainValue<infer TData> ? TData : never;
-
-/**
- * StreamValue 型から内部のチャンクデータ型を抽出します。
- *
- * @template TStremValue 対象となる StreamValue 型です。
- */
-export type $InferStreamValueChunkData<TStremValue> =
-  TStremValue extends StreamValue<infer TChunkData> ? TChunkData : never;
-
-/**
- * KeyValueMapping から有効なキーの型を抽出します。
- *
- * @template TKeyValueMapping 対象となるマッピング型です。
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#value-types)
  */
 export type KeyofKeyValueMapping<TKeyValueMapping extends KeyValueMapping = KeyValueMapping> =
   Extract<keyof TKeyValueMapping, IStorage.Key>;
 
 /**
- * UniKvs の設定を構築するためのビルダーインターフェースです。
- *
- * トランスフォーマーの追加やストレージの登録を型安全に行うための流れるようなインターフェースを提供します。
- *
- * @template TKeyValueMapping キーと値のマッピング型です。
- * @template TUniKvsDataInput UniKvs への入力データの型です。
- * @template TUniKvsDataOutput UniKvs からの出力データの型です。
- * @template TUniKvsChunkInput UniKvs への入力チャンクデータの型です。
- * @template TUniKvsChunkOutput UniKvs からのストリーム出力チャンクデータの型です。
- * @template TLastTransformerDecodeDataInput 最後に適用されたトランスフォーマーのデコード入力データの型です。
- * @template TLastTransformerEncodeDataOutput 最後に適用されたトランスフォーマーのエンコード出力データの型です。
- * @template TLastTransformerDecodeChunkInput 最後に適用されたトランスフォーマーのデコード入力チャンクデータの型です。
- * @template TLastTransformerEncodeChunkOutput 最後に適用されたトランスフォーマーのエンコード出力チャンクデータの型です。
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
  */
 export interface IUniKvsConfigBuilder<
   TKeyValueMapping extends KeyValueMapping = KeyValueMapping,
@@ -162,21 +125,12 @@ export interface IUniKvsConfigBuilder<
   TLastTransformerEncodeChunkOutput = TUniKvsChunkInput,
 > {
   /**
-   * コンテキスト情報を設定します。
-   *
-   * @param context 設定するコンテキストのソースです。
-   * @returns インスタンス自身を返します。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
-  setContext(context: ContextSource): this;
+  setVariables(vars: VariablesSource): this;
 
   /**
-   * ストレージをパイプラインの終端に追加します。
-   *
-   * ストレージが追加されると、設定はファイナライズ段階に移行します。
-   *
-   * @template TStorage 追加するストレージの型です。
-   * @param storage ストレージのインスタンスです。
-   * @returns ファイナライザーインターフェースを返します。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
   appendStorage<
     TStorage extends IStorage<
@@ -200,17 +154,15 @@ export interface IUniKvsConfigBuilder<
       ? never
       : [$InferReadChunkOutput<TStorage>] extends [never]
         ? never
-        : TLastTransformerDecodeChunkInput
+        : TLastTransformerDecodeChunkInput,
+    TLastTransformerDecodeDataInput,
+    TLastTransformerEncodeDataOutput,
+    TLastTransformerDecodeChunkInput,
+    TLastTransformerEncodeChunkOutput
   >;
 
   /**
-   * トランスフォーマーをパイプラインに追加します。
-   *
-   * データ変換の層を積み重ねることで、シリアライズなどの処理を定義できます。
-   *
-   * @template TTransformer 追加するトランスフォーマーの型です。
-   * @param transformer トランスフォーマーのインスタンスです。
-   * @returns 新しい型情報を持つビルダーを返します。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
   appendTransformer<
     TTransformer extends ITransformer<
@@ -255,13 +207,7 @@ export interface IUniKvsConfigBuilder<
 }
 
 /**
- * UniKvs の設定を完了させるためのファイナライザーインターフェースです。
- *
- * @template TKeyValueMapping キーと値のマッピング型です。
- * @template TWriteDataInput ストレージへの書き込み入力データの型です。
- * @template TReadDataOutput ストレージからの読み込み出力データの型です。
- * @template TWriteChunkInput ストレージへの書き込みチャンクデータの型です。
- * @template TReadChunkOutput ストレージからの読み込みチャンクデータの型です。
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
  */
 export interface IUniKvsConfigFinalizer<
   TKeyValueMapping extends KeyValueMapping = KeyValueMapping,
@@ -269,35 +215,30 @@ export interface IUniKvsConfigFinalizer<
   TReadDataOutput = any,
   TWriteChunkInput = any,
   TReadChunkOutput = any,
+  TLastTransformerDecodeDataInput = TReadDataOutput,
+  TLastTransformerEncodeDataOutput = TWriteDataInput,
+  TLastTransformerDecodeChunkInput = TReadChunkOutput,
+  TLastTransformerEncodeChunkOutput = TWriteChunkInput,
 > {
   /**
-   * 設定に基づいて UniKvs インスタンスを作成します。
-   *
-   * @returns 作成された UniKvs のインスタンスです。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
   create(): UniKvs<TKeyValueMapping>;
 
   /**
-   * コンテキスト情報を設定します。
-   *
-   * @param context 設定するコンテキストのソースです。
-   * @returns インスタンス自身を返します。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
-  setContext(context: ContextSource): this;
+  setVariables(vars: VariablesSource): this;
 
   /**
-   * 追加のストレージを登録します。UniKvs は複数のストレージへのマルチキャスト書き込みをサポートします。
-   *
-   * @template TStorage 追加するストレージの型です。
-   * @param storage ストレージのインスタンスです。
-   * @returns ファイナライザーインターフェースを返します。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
   appendStorage<
     TStorage extends IStorage<
-      [TWriteDataInput] extends [never] ? any : TWriteDataInput,
-      [TReadDataOutput] extends [never] ? any : TReadDataOutput,
-      [TWriteChunkInput] extends [never] ? any : TWriteChunkInput,
-      [TReadChunkOutput] extends [never] ? any : TReadChunkOutput
+      [TLastTransformerEncodeDataOutput] extends [never] ? any : TLastTransformerEncodeDataOutput,
+      [TLastTransformerDecodeDataInput] extends [never] ? any : TLastTransformerDecodeDataInput,
+      [TLastTransformerEncodeChunkOutput] extends [never] ? any : TLastTransformerEncodeChunkOutput,
+      [TLastTransformerDecodeChunkInput] extends [never] ? any : TLastTransformerDecodeChunkInput
     >,
   >(
     storage: TStorage,
@@ -314,14 +255,63 @@ export interface IUniKvsConfigFinalizer<
       ? never
       : [$InferReadChunkOutput<TStorage>] extends [never]
         ? never
-        : TReadChunkOutput
+        : TReadChunkOutput,
+    TLastTransformerDecodeDataInput,
+    TLastTransformerEncodeDataOutput,
+    TLastTransformerDecodeChunkInput,
+    TLastTransformerEncodeChunkOutput
+  >;
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
+   */
+  appendTransformer<
+    TTransformer extends ITransformer<
+      [TLastTransformerEncodeDataOutput] extends [never] ? any : TLastTransformerEncodeDataOutput,
+      any,
+      any,
+      [TLastTransformerDecodeDataInput] extends [never] ? any : TLastTransformerDecodeDataInput,
+      [TLastTransformerEncodeChunkOutput] extends [never] ? any : TLastTransformerEncodeChunkOutput,
+      any,
+      any,
+      [TLastTransformerDecodeChunkInput] extends [never] ? any : TLastTransformerDecodeChunkInput
+    >,
+  >(
+    transformer: TTransformer,
+  ): IUniKvsConfigFinalizer<
+    TKeyValueMapping,
+    TWriteDataInput,
+    TReadDataOutput,
+    TWriteChunkInput,
+    TReadChunkOutput,
+    $InferDecodeDataInput<TTransformer>,
+    $InferEncodeDataOutput<TTransformer>,
+    $InferDecodeChunkInput<TTransformer>,
+    $InferEncodeChunkOutput<TTransformer>
   >;
 }
 
 /**
- * UniKvs の構成を管理する設定クラスです。
- *
- * ビルダーパターンを用いて、コンテキスト、トランスフォーマー、ストレージの順で設定を積み上げます。
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
+ */
+export type UniKvsConfigOptions = {
+  /**
+   * キーと値のスキーマ定義です。指定すると入出力値が検証されます。
+   */
+  readonly schema?: UniKvsSchema | undefined;
+};
+
+const UniKvsConfigOptionsSchema = v.object({
+  /**
+   * キーと値のスキーマ定義です。
+   */
+  schema: v.optional(UniKvsSchemaSchema),
+});
+
+const UniKvsConfigArgsSchema = v.tuple([v.optional(UniKvsConfigOptionsSchema)]);
+
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
  */
 export default class UniKvsConfig implements IUniKvsConfigBuilder, IUniKvsConfigFinalizer {
   /**
@@ -330,95 +320,80 @@ export default class UniKvsConfig implements IUniKvsConfigBuilder, IUniKvsConfig
   readonly #UniKvs: typeof UniKvs;
 
   /**
-   * アプリケーションの実行時情報を保持するコンテキストオブジェクトです。
+   * アプリケーションの実行時情報を保持する変数オブジェクトです。
    */
-  #context: Context;
+  #vars: Variables;
 
   /**
-   * データの永続化先となるストレージのリストです。
+   * データの永続化先となるストレージのリストです。各ストレージは登録時点のトランスフォーマー数を保持します。
    */
-  readonly #destinations: IStorage[];
+  readonly #destinations: { readonly storage: IStorage; readonly transformerCount: number }[];
 
   /**
-   * データを変換するためのトランスフォーマーのリストです。
+   * データを変換するためのトランスフォーマーのリストです。登録順に保持します。
    */
   readonly #transformers: ITransformer[];
 
   /**
-   * UniKvsConfig インスタンスを初期化します。
-   *
-   * @param UniKvsConstructor UniKvs のクラスコンストラクターです。
+   * キーに対応する値のスキーマ情報を解決するリゾルバーです。スキーマ未設定時は null となります。
+   */
+  readonly #valueSchemaResolver: IValueSchemaResolver | null;
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
-  public constructor(UniKvsConstructor: typeof UniKvs) {
+  public constructor(UniKvsConstructor: typeof UniKvs, options?: UniKvsConfigOptions) {
+    const [parsed = {}] = v.parseInput(UniKvsConfigArgsSchema, [options]);
+
     this.#UniKvs = UniKvsConstructor;
-    this.#context = {};
+    this.#vars = {};
     this.#destinations = [];
     this.#transformers = [];
+    this.#valueSchemaResolver = parsed.schema ? createValueSchemaResolver(parsed.schema) : null;
   }
 
   /**
-   * 現在の設定を使用して UniKvs インスタンスを作成します。
-   *
-   * @returns 作成された UniKvs インスタンスです。
-   * @throws ストレージが一つも登録されていない場合にエラーを投げます。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
   public create(): UniKvs {
-    // 登録されたストレージから先頭の要素を取得します。
-    const [dest, ...destinations] = this.#destinations.map((io) => new UniKvsStorage(io));
+    const transformers = this.#transformers.map((tf) => new UniKvsTransformer(tf));
+
+    const [first, ...rest] = this.#destinations.map(({ storage, transformerCount }) => ({
+      storage: new UniKvsStorage(storage),
+      transformers: transformers.slice(0, transformerCount),
+    }));
 
     // ストレージが空の場合は UniKvs として機能できないため、例外を投げます。
-    if (!dest) {
+    if (!first) {
       throw new MissingStorageError();
     }
 
-    // コンテキストの参照を切り離すために浅いコピーを作成して UniKvs を初期化します。
-    // トランスフォーマーの配列もスライスしてコピーを渡し、内部状態の安全性を確保します。
-    return new this.#UniKvs(
-      this.#context,
-      [dest, ...destinations],
-      this.#transformers.map((tf) => new UniKvsTransformer(tf)),
-    );
+    // 変数の参照を切り離すために浅いコピーを作成して UniKvs を初期化します。
+    return new this.#UniKvs(this.#vars, [first, ...rest], transformers, this.#valueSchemaResolver);
   }
 
   /**
-   * コンテキスト情報を設定します。既存のコンテキストは上書きされます。
-   *
-   * @param context 設定するコンテキストのソースデータです。
-   * @returns インスタンス自身を返します。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
-  public setContext(context: ContextSource): this {
-    this.#context = Array.isArray(context) ? Object.fromEntries(context) : { ...context };
+  public setVariables(vars: VariablesSource): this {
+    this.#vars = Array.isArray(vars) ? Object.fromEntries(vars) : { ...vars };
 
     return this;
   }
 
   /**
-   * ストレージを登録リストに追加します。
-   *
-   * @param storage 追加するストレージインスタンスです。
-   * @returns ファイナライザーとして自身を返します。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
-  public appendStorage(storage: IStorage): IUniKvsConfigFinalizer {
-    this.#destinations.push(storage);
+  public appendStorage(storage: IStorage): this {
+    this.#destinations.push({ storage, transformerCount: this.#transformers.length });
 
     return this;
   }
 
   /**
-   * トランスフォーマーを変換パイプラインに追加します。
-   *
-   * ストレージが登録された後には追加できない制約があります。
-   *
-   * @param transformer 追加するトランスフォーマーインスタンスです。
-   * @returns ビルダーとして自身を返します。
-   * @throws すでにストレージが登録されている状態で呼び出された場合にエラーを投げます。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#config-builder)
    */
-  public appendTransformer(transformer: ITransformer): IUniKvsConfigBuilder {
-    // パイプラインの順序を守るため、終端であるストレージが登録済みでないか確認します。
-    if (this.#destinations.length > 0) {
-      throw new TransformStreamDefaultController();
-    }
-
+  public appendTransformer(transformer: ITransformer): this {
     this.#transformers.push(transformer);
 
     return this;