unikvs 0.0.9 → 0.0.10

package/src/errors.ts

@@ -13,55 +13,115 @@ import type { BaseIssue } from "valibot";
 //
 // -------------------------------------------------------------------------------------------------
 
+/**
+ * 無効な入出力を表すエラーの基底クラスです。
+ *
+ * @template TMeta エラーのメタデータの型です。
+ */
 export class InvalidUsageErrorBase<
   TMeta extends ErrorMeta | undefined = ErrorMeta | undefined,
 > extends ErrorBase<TMeta> {}
 
 // -------------------------------------------------------------------------------------------------
 
+/**
+ * バリデーションの問題を表す valibot のイシューです。
+ */
 export type Issue = BaseIssue<unknown>;
 
+/**
+ * InvalidInputError に付与されるメタデータです。
+ */
 export type InvalidInputErrorMeta = {
+  /**
+   * 検証に失敗した入力値です。
+   */
   readonly input: unknown;
+
+  /**
+   * 検証で検出されたイシューのリストです。
+   */
   readonly issues: readonly [Issue, ...Issue[]];
 };
 
-export type InvalidInputErrorArgs = {
+/**
+ * InvalidInputError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type InvalidInputErrorArgs = ErrorOptions & {
+  /**
+   * 検証の対象となった値です。
+   */
   readonly value: unknown;
+
+  /**
+   * 検証で検出されたイシューのリストです。
+   */
   readonly issues: readonly [Issue, ...Issue[]];
 };
 
+/**
+ * 入力値が期待するスキーマに適合しない場合に投げられるエラーです。
+ */
 export class InvalidInputError extends InvalidUsageErrorBase<InvalidInputErrorMeta> {
   static {
     this.prototype.name = "UniKvsInvalidInputError";
   }
 
-  public constructor(args: InvalidInputErrorArgs, options?: ErrorOptions) {
-    const { value: input, issues } = args;
-    super({ input, issues }, ({ issues }) => issues.map((i) => i.message).join(": "), options);
+  public constructor(args: InvalidInputErrorArgs) {
+    const { value: input, issues, ...options } = args;
+    const meta: InvalidInputErrorMeta = { input, issues };
+    super(meta, ({ issues }) => issues.map((i) => i.message).join(": "), options);
   }
 }
 
 // -------------------------------------------------------------------------------------------------
 
+/**
+ * InvalidOutputError に付与されるメタデータです。
+ */
 export type InvalidOutputErrorMeta = {
+  /**
+   * 検証に失敗した出力値です。
+   */
   readonly output: unknown;
+
+  /**
+   * 検証で検出されたイシューのリストです。
+   */
   readonly issues: readonly [Issue, ...Issue[]];
 };
 
-export type InvalidOutputErrorArgs = {
+/**
+ * InvalidOutputError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type InvalidOutputErrorArgs = ErrorOptions & {
+  /**
+   * 検証の対象となった値です。
+   */
   readonly value: unknown;
+
+  /**
+   * 検証で検出されたイシューのリストです。
+   */
   readonly issues: readonly [Issue, ...Issue[]];
 };
 
+/**
+ * 出力値が期待するスキーマに適合しない場合に投げられるエラーです。
+ */
 export class InvalidOutputError extends InvalidUsageErrorBase<InvalidOutputErrorMeta> {
   static {
     this.prototype.name = "UniKvsInvalidOutputError";
   }
 
-  public constructor(args: InvalidOutputErrorArgs, options?: ErrorOptions) {
-    const { value: output, issues } = args;
-    super({ output, issues }, ({ issues }) => issues.map((i) => i.message).join(": "), options);
+  public constructor(args: InvalidOutputErrorArgs) {
+    const { value: output, issues, ...options } = args;
+    const meta: InvalidOutputErrorMeta = { output, issues };
+    super(meta, ({ issues }) => issues.map((i) => i.message).join(": "), options);
   }
 }
 
@@ -71,6 +131,9 @@ export class InvalidOutputError extends InvalidUsageErrorBase<InvalidOutputError
 //
 // -------------------------------------------------------------------------------------------------
 
+/**
+ * すでに開いている UniKvs に対して再度オープン操作が行われた場合に投げられるエラーです。
+ */
 export class UniKvsIsOpenError extends ErrorBase<undefined> {
   static {
     this.prototype.name = "UniKvsIsOpenError";
@@ -83,6 +146,9 @@ export class UniKvsIsOpenError extends ErrorBase<undefined> {
 
 setErrorMessage(UniKvsIsOpenError, "UniKvs は開いています", "ja");
 
+/**
+ * UniKvs が開かれていない状態で操作が行われた場合に投げられるエラーです。
+ */
 export class UniKvsIsNotOpenError extends ErrorBase<undefined> {
   static {
     this.prototype.name = "UniKvsIsNotOpenError";
@@ -95,19 +161,35 @@ export class UniKvsIsNotOpenError extends ErrorBase<undefined> {
 
 setErrorMessage(UniKvsIsNotOpenError, "UniKvs は開いていません", "ja");
 
+/**
+ * KeyNotFoundError に付与されるメタデータです。
+ */
 export type KeyNotFoundErrorMeta = {
+  /**
+   * 見つからなかったキーです。
+   */
   readonly key: IStorage.Key;
 };
 
-export type KeyNotFoundErrorArgs = KeyNotFoundErrorMeta;
+/**
+ * KeyNotFoundError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type KeyNotFoundErrorArgs = ErrorOptions & KeyNotFoundErrorMeta;
 
+/**
+ * 指定したキーのデータがどのストレージにも存在しない場合に投げられるエラーです。
+ */
 export class KeyNotFoundError extends ErrorBase<KeyNotFoundErrorMeta> {
   static {
     this.prototype.name = "UniKvsKeyNotFoundError";
   }
 
-  public constructor(args: KeyNotFoundErrorArgs, options?: ErrorOptions) {
-    super(args, ({ key }) => `IStorage.Key ${JSON.stringify(key)} not found`, options);
+  public constructor(args: KeyNotFoundErrorArgs) {
+    const { key, ...options } = args;
+    const meta: KeyNotFoundErrorMeta = { key };
+    super(meta, ({ key }) => `IStorage.Key ${JSON.stringify(key)} not found`, options);
   }
 }
 
@@ -141,86 +223,153 @@ setErrorMessage(
 
 // setErrorMessage(StorageIsOpenError, ({ name }) => `ストレージ "${name}" は開いています`, "ja");
 
+/**
+ * StorageIsNotOpenError に付与されるメタデータです。
+ */
 export type StorageIsNotOpenErrorMeta = {
+  /**
+   * 開かれていないストレージの名前です。
+   */
   readonly name: string;
 };
 
-export type StorageIsNotOpenErrorArgs = StorageIsNotOpenErrorMeta;
+/**
+ * StorageIsNotOpenError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type StorageIsNotOpenErrorArgs = ErrorOptions & StorageIsNotOpenErrorMeta;
 
+/**
+ * ストレージが開かれていない状態で操作が行われた場合に投げられるエラーです。
+ */
 export class StorageIsNotOpenError extends ErrorBase<StorageIsNotOpenErrorMeta> {
   static {
     this.prototype.name = "UniKvsStorageIsNotOpenError";
   }
 
-  public constructor(args: StorageIsNotOpenErrorArgs, options?: ErrorOptions) {
-    super(args, ({ name }) => `Storage "${name}" is not open`, options);
+  public constructor(args: StorageIsNotOpenErrorArgs) {
+    const { name, ...options } = args;
+    const meta: StorageIsNotOpenErrorMeta = { name };
+    super(meta, ({ name }) => `Storage "${name}" is not open`, options);
   }
 }
 
 setErrorMessage(StorageIsNotOpenError, ({ name }) => `ストレージ "${name}" は開いていません`, "ja");
 
+/**
+ * WritableStreamNotSupportedError に付与されるメタデータです。
+ */
 export type WritableStreamNotSupportedErrorMeta = {
+  /**
+   * 対象のストレージの名前です。
+   */
   readonly name: string;
 };
 
-export type WritableStreamNotSupportedErrorArgs = WritableStreamNotSupportedErrorMeta;
-
+/**
+ * WritableStreamNotSupportedError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type WritableStreamNotSupportedErrorArgs = ErrorOptions &
+  WritableStreamNotSupportedErrorMeta;
+
+/**
+ * ストレージが書き込み可能なストリームをサポートしていない場合に投げられるエラーです。
+ */
 export class WritableStreamNotSupportedError extends ErrorBase<WritableStreamNotSupportedErrorMeta> {
   static {
     this.prototype.name = "UniKvsWritableStreamNotSupportedError";
   }
 
-  public constructor(args: WritableStreamNotSupportedErrorArgs, options?: ErrorOptions) {
-    super(args, ({ name }) => `Storage "${name}" does not support writable stream`, options);
+  public constructor(args: WritableStreamNotSupportedErrorArgs) {
+    const { name, ...options } = args;
+    const meta: WritableStreamNotSupportedErrorMeta = { name };
+    super(meta, ({ name }) => `Storage "${name}" does not support writable stream`, options);
   }
 }
 
 setErrorMessage(
-  StorageIsNotOpenError,
+  WritableStreamNotSupportedError,
   ({ name }) => `ストレージ "${name}" は書き込み可能なストリームをサポートしていません`,
   "ja",
 );
 
+/**
+ * ReadableStreamNotSupportedError に付与されるメタデータです。
+ */
 export type ReadableStreamNotSupportedErrorMeta = {
+  /**
+   * 対象のストレージの名前です。
+   */
   readonly name: string;
 };
 
-export type ReadableStreamNotSupportedErrorArgs = ReadableStreamNotSupportedErrorMeta;
-
+/**
+ * ReadableStreamNotSupportedError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type ReadableStreamNotSupportedErrorArgs = ErrorOptions &
+  ReadableStreamNotSupportedErrorMeta;
+
+/**
+ * ストレージが読み取り可能なストリームをサポートしていない場合に投げられるエラーです。
+ */
 export class ReadableStreamNotSupportedError extends ErrorBase<ReadableStreamNotSupportedErrorMeta> {
   static {
     this.prototype.name = "UniKvsReadableStreamNotSupportedError";
   }
 
-  public constructor(args: ReadableStreamNotSupportedErrorArgs, options?: ErrorOptions) {
-    super(args, ({ name }) => `Storage "${name}" does not support readable stream`, options);
+  public constructor(args: ReadableStreamNotSupportedErrorArgs) {
+    const { name, ...options } = args;
+    const meta: ReadableStreamNotSupportedErrorMeta = { name };
+    super(meta, ({ name }) => `Storage "${name}" does not support readable stream`, options);
   }
 }
 
 setErrorMessage(
-  StorageIsNotOpenError,
+  ReadableStreamNotSupportedError,
   ({ name }) => `ストレージ "${name}" は読み取り可能なストリームをサポートしていません`,
   "ja",
 );
 
+/**
+ * MultipartWriteNotSupportedError に付与されるメタデータです。
+ */
 export type MultipartWriteNotSupportedErrorMeta = {
+  /**
+   * 対象のストレージの名前です。
+   */
   readonly name: string;
 };
 
-export type MultipartWriteNotSupportedErrorArgs = MultipartWriteNotSupportedErrorMeta;
-
+/**
+ * MultipartWriteNotSupportedError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type MultipartWriteNotSupportedErrorArgs = ErrorOptions &
+  MultipartWriteNotSupportedErrorMeta;
+
+/**
+ * ストレージがマルチパート書き込みをサポートしていない場合に投げられるエラーです。
+ */
 export class MultipartWriteNotSupportedError extends ErrorBase<MultipartWriteNotSupportedErrorMeta> {
   static {
     this.prototype.name = "UniKvsMultipartWriteNotSupportedError";
   }
 
-  public constructor(args: MultipartWriteNotSupportedErrorArgs, options?: ErrorOptions) {
-    super(args, ({ name }) => `Storage "${name}" does not support multipart-write`, options);
+  public constructor(args: MultipartWriteNotSupportedErrorArgs) {
+    const { name, ...options } = args;
+    const meta: MultipartWriteNotSupportedErrorMeta = { name };
+    super(meta, ({ name }) => `Storage "${name}" does not support multipart-write`, options);
   }
 }
 
 setErrorMessage(
-  StorageIsNotOpenError,
+  MultipartWriteNotSupportedError,
   ({ name }) => `ストレージ "${name}" はマルチパート書き込みをサポートしていません`,
   "ja",
 );
@@ -249,19 +398,35 @@ setErrorMessage(
 
 // setErrorMessage(TransformerIsOpenError, ({ name }) => `トランスフォーマー "${name}" は開いています`, "ja");
 
+/**
+ * TransformerIsNotOpenError に付与されるメタデータです。
+ */
 export type TransformerIsNotOpenErrorMeta = {
+  /**
+   * 開かれていないトランスフォーマーの名前です。
+   */
   readonly name: string;
 };
 
-export type TransformerIsNotOpenErrorArgs = TransformerIsNotOpenErrorMeta;
+/**
+ * TransformerIsNotOpenError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type TransformerIsNotOpenErrorArgs = ErrorOptions & TransformerIsNotOpenErrorMeta;
 
+/**
+ * トランスフォーマーが開かれていない状態で操作が行われた場合に投げられるエラーです。
+ */
 export class TransformerIsNotOpenError extends ErrorBase<TransformerIsNotOpenErrorMeta> {
   static {
     this.prototype.name = "UniKvsTransformerIsNotOpenError";
   }
 
-  public constructor(args: TransformerIsNotOpenErrorArgs, options?: ErrorOptions) {
-    super(args, ({ name }) => `Transformer "${name}" is not open`, options);
+  public constructor(args: TransformerIsNotOpenErrorArgs) {
+    const { name, ...options } = args;
+    const meta: TransformerIsNotOpenErrorMeta = { name };
+    super(meta, ({ name }) => `Transformer "${name}" is not open`, options);
   }
 }
 
@@ -271,46 +436,80 @@ setErrorMessage(
   "ja",
 );
 
+/**
+ * EncodableStreamNotSupportedError に付与されるメタデータです。
+ */
 export type EncodableStreamNotSupportedErrorMeta = {
+  /**
+   * 対象のトランスフォーマーの名前です。
+   */
   readonly name: string;
 };
 
-export type EncodableStreamNotSupportedErrorArgs = EncodableStreamNotSupportedErrorMeta;
-
+/**
+ * EncodableStreamNotSupportedError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type EncodableStreamNotSupportedErrorArgs = ErrorOptions &
+  EncodableStreamNotSupportedErrorMeta;
+
+/**
+ * トランスフォーマーがエンコード可能なストリームをサポートしていない場合に投げられるエラーです。
+ */
 export class EncodableStreamNotSupportedError extends ErrorBase<EncodableStreamNotSupportedErrorMeta> {
   static {
     this.prototype.name = "UniKvsEncodableStreamNotSupportedError";
   }
 
-  public constructor(args: EncodableStreamNotSupportedErrorArgs, options?: ErrorOptions) {
-    super(args, ({ name }) => `Transformer "${name}" does not support encodable stream`, options);
+  public constructor(args: EncodableStreamNotSupportedErrorArgs) {
+    const { name, ...options } = args;
+    const meta: EncodableStreamNotSupportedErrorMeta = { name };
+    super(meta, ({ name }) => `Transformer "${name}" does not support encodable stream`, options);
   }
 }
 
 setErrorMessage(
-  TransformerIsNotOpenError,
+  EncodableStreamNotSupportedError,
   ({ name }) => `トランスフォーマー "${name}" はエンコード可能なストリームをサポートしていません`,
   "ja",
 );
 
+/**
+ * DecodableStreamNotSupportedError に付与されるメタデータです。
+ */
 export type DecodableStreamNotSupportedErrorMeta = {
+  /**
+   * 対象のトランスフォーマーの名前です。
+   */
   readonly name: string;
 };
 
-export type DecodableStreamNotSupportedErrorArgs = DecodableStreamNotSupportedErrorMeta;
-
+/**
+ * DecodableStreamNotSupportedError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type DecodableStreamNotSupportedErrorArgs = ErrorOptions &
+  DecodableStreamNotSupportedErrorMeta;
+
+/**
+ * トランスフォーマーがデコード可能なストリームをサポートしていない場合に投げられるエラーです。
+ */
 export class DecodableStreamNotSupportedError extends ErrorBase<DecodableStreamNotSupportedErrorMeta> {
   static {
     this.prototype.name = "UniKvsDecodableStreamNotSupportedError";
   }
 
-  public constructor(args: DecodableStreamNotSupportedErrorArgs, options?: ErrorOptions) {
-    super(args, ({ name }) => `Transformer "${name}" does not support decodable stream`, options);
+  public constructor(args: DecodableStreamNotSupportedErrorArgs) {
+    const { name, ...options } = args;
+    const meta: DecodableStreamNotSupportedErrorMeta = { name };
+    super(meta, ({ name }) => `Transformer "${name}" does not support decodable stream`, options);
   }
 }
 
 setErrorMessage(
-  TransformerIsNotOpenError,
+  DecodableStreamNotSupportedError,
   ({ name }) => `トランスフォーマー "${name}" はデコード可能なストリームをサポートしていません`,
   "ja",
 );
@@ -321,41 +520,97 @@ setErrorMessage(
 //
 // -------------------------------------------------------------------------------------------------
 
+/**
+ * PluginOperationAggregateError に付与されるメタデータです。
+ */
 export type PluginOperationAggregateErrorMeta = {
+  /**
+   * 失敗した操作の対象となったプラグインの種別です。
+   *
+   * - `"plugin"`: 複数の種別のプラグインが混在しています。
+   * - `"storage"`: ストレージです。
+   * - `"transformer"`: トランスフォーマーです。
+   */
   readonly plugin: "plugin" | "storage" | "transformer";
-  readonly action: "open" | "close" | "write" | "delete" | "clear";
+
+  /**
+   * 失敗した操作の種類です。
+   */
+  readonly action: "open" | "close" | "write" | "read" | "delete" | "clear";
+
+  /**
+   * 失敗した各プラグインの操作と原因のリストです。
+   */
   readonly errors: readonly {
+    /**
+     * 失敗したプラグインの種別です。
+     */
     readonly plugin: "storage" | "transformer";
+
+    /**
+     * 操作が失敗した原因です。
+     */
     readonly reason: unknown;
   }[];
 };
 
-export type PluginOperationAggregateErrorArgs = {
+/**
+ * PluginOperationAggregateError のコンストラクター引数です。
+ *
+ * エラーの追加情報 (`cause`) も含みます。
+ */
+export type PluginOperationAggregateErrorArgs = ErrorOptions & {
+  /**
+   * 失敗したプラグインの既定の種別です。
+   *
+   * 個々のエラーで種別が指定されていない場合に使用されます。
+   */
   readonly plugin?: "storage" | "transformer";
-  readonly action: "open" | "close" | "write" | "delete" | "clear";
+
+  /**
+   * 失敗した操作の種類です。
+   */
+  readonly action: "open" | "close" | "write" | "read" | "delete" | "clear";
+
+  /**
+   * 失敗した各プラグインの操作と原因のリストです。
+   */
   readonly errors: readonly {
+    /**
+     * 失敗したプラグインの種別です。
+     */
     readonly plugin?: "storage" | "transformer";
+
+    /**
+     * 操作が失敗した原因です。
+     */
     readonly reason: unknown;
   }[];
 };
 
+/**
+ * 複数のストレージやトランスフォーマーの操作が失敗した場合に投げられる、個々の失敗を集約したエラーです。
+ */
 export class PluginOperationAggregateError extends ErrorBase<PluginOperationAggregateErrorMeta> {
   static {
     this.prototype.name = "UniKvsPluginOperationAggregateError";
   }
 
-  public constructor(args: PluginOperationAggregateErrorArgs, options?: ErrorOptions) {
-    const errors = args.errors.map((error) => ({
-      plugin: error.plugin ?? args.plugin ?? ("" as never),
+  public constructor(args: PluginOperationAggregateErrorArgs) {
+    const { plugin, action, errors, ...options } = args;
+    // 個々のエラーで種別が指定されていない場合は、既定の種別で補完します。
+    const normalizedErrors = errors.map((error) => ({
+      plugin: error.plugin ?? plugin ?? ("" as never),
       reason: error.reason,
     }));
-    const plugins = [...new Set(errors.map((error) => error.plugin))];
+    const plugins = [...new Set(normalizedErrors.map((error) => error.plugin))];
+    const meta: PluginOperationAggregateErrorMeta = {
+      plugin: plugins.length === 1 ? plugins[0]! : "plugin",
+      action,
+      errors: normalizedErrors,
+    };
     super(
-      {
-        plugin: plugins.length === 1 ? plugins[0]! : "plugin",
-        action: args.action,
-        errors,
-      },
+      meta,
       ({ action, errors, plugin }) => `${errors.length} ${plugin}(s) fail ${action} operation`,
       options,
     );
@@ -375,6 +630,9 @@ setErrorMessage(
 //
 // -------------------------------------------------------------------------------------------------
 
+/**
+ * ストレージが一つも登録されていない状態で UniKvs を作成しようとした場合に投げられるエラーです。
+ */
 export class MissingStorageError extends ErrorBase<undefined> {
   static {
     this.prototype.name = "UniKvsMissingStorageError";
@@ -393,6 +651,9 @@ setErrorMessage(
 
 // -------------------------------------------------------------------------------------------------
 
+/**
+ * ストレージが登録された後にトランスフォーマーを追加しようとした場合に投げられるエラーです。
+ */
 export class TransformerRegistrationError extends ErrorBase<undefined> {
   static {
     this.prototype.name = "UniKvsTransformerRegistrationError";
@@ -404,7 +665,7 @@ export class TransformerRegistrationError extends ErrorBase<undefined> {
 }
 
 setErrorMessage(
-  MissingStorageError,
+  TransformerRegistrationError,
   "ストレージが登録された後にトランスフォーマーを追加することはできません",
   "ja",
 );

package/src/unikvs-config.ts

@@ -11,7 +11,7 @@ import type {
 import UniKvsStorage from "./_storage.js";
 import UniKvsTransformer from "./_transformer.js";
 import type { ContextSource } from "./context.types.js";
-import { MissingStorageError } from "./errors.js";
+import { MissingStorageError, TransformerRegistrationError } from "./errors.js";
 import type UniKvs from "./unikvs.js";
 import type { ValueOf } from "./utils.types.js";
 
@@ -416,7 +416,7 @@ export default class UniKvsConfig implements IUniKvsConfigBuilder, IUniKvsConfig
   public appendTransformer(transformer: ITransformer): IUniKvsConfigBuilder {
     // パイプラインの順序を守るため、終端であるストレージが登録済みでないか確認します。
     if (this.#destinations.length > 0) {
-      throw new TransformStreamDefaultController();
+      throw new TransformerRegistrationError();
     }
 
     this.#transformers.push(transformer);