unikvs 0.0.14 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unikvs",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "A modular and portable KVS client implemented in TypeScript.",
   "homepage": "https://tai-kun.github.io/unikvs/",
   "license": "MIT",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@tai-kun/valibot-extra-lab": "^0.0.5",
-    "@unikvs/core": "0.0.14",
+    "@unikvs/core": "0.0.16",
     "abort-signal-utils": "^0.0.6",
     "asyncmux": "^0.0.12",
     "call-fn-once": "^0.0.12",
@@ -35,14 +35,14 @@
   "devDependencies": {
     "@babel/plugin-proposal-decorators": "^8.0.2",
     "@rolldown/plugin-babel": "^0.2.4",
-    "@unikvs/allow-repair": "0.0.14",
-    "@unikvs/checksum": "0.0.14",
-    "@unikvs/compression": "0.0.14",
-    "@unikvs/fs.node": "0.0.14",
-    "@unikvs/memory": "0.0.14",
-    "@unikvs/opfs": "0.0.14",
+    "@unikvs/allow-repair": "0.0.16",
+    "@unikvs/checksum": "0.0.16",
+    "@unikvs/compression": "0.0.16",
+    "@unikvs/fs.node": "0.0.16",
+    "@unikvs/memory": "0.0.16",
+    "@unikvs/opfs": "0.0.16",
     "@unikvs/testing": "0.0.0",
-    "@unikvs/utils": "0.0.14",
+    "@unikvs/utils": "0.0.16",
     "@vitest/browser-playwright": "5.0.5",
     "@vitest/coverage-istanbul": "5.0.5",
     "@vitest/coverage-v8": "5.0.5",

package/src/_contexts.ts

@@ -2,6 +2,8 @@ import {
   type IGetContext,
   type IHasContext,
   type ISetContext,
+  type ICopyContext,
+  type IMoveContext,
   type IOpenContext,
   type IClearContext,
   type ICloseContext,
@@ -15,6 +17,7 @@ import {
   type IPipelineContext,
   type ILifecycleContext,
   type ITransformContext,
+  type VariablesSnapshot,
   type IKeyedActionContext,
   type IDecodeStreamContext,
   type IEncodeStreamContext,
@@ -196,6 +199,15 @@ class PipelineContext implements IPipelineContext {
 
     return this;
   }
+
+  /**
+   * 現在の実行時変数の浅いコピーを作成します。
+   *
+   * @returns 実行時変数のスナップショットを返します。
+   */
+  public snapshot(): VariablesSnapshot {
+    return new Map(this.#data);
+  }
 }
 
 /**
@@ -723,6 +735,81 @@ export class DeleteContext extends KeyedActionContext<"delete"> implements IDele
   }
 }
 
+/**
+ * コピー・移動系コンテキストの初期値です。
+ */
+type TransferContextInit<TAction extends "copy" | "move"> = KeyedActionContextInit<TAction> & {
+  /**
+   * コピー先または移動先のキーです。
+   */
+  readonly destinationKey: string;
+};
+
+/**
+ * コピー・移動で共通のコンテキストです。
+ */
+class TransferContext<TAction extends "copy" | "move"> extends KeyedActionContext<TAction> {
+  /**
+   * コピー先または移動先のキーです。
+   */
+  public readonly destinationKey: string;
+
+  /**
+   * コンテキストを作成します。
+   *
+   * @param init 初期値です。
+   */
+  public constructor(init: TransferContextInit<TAction>) {
+    const { destinationKey, ...superInit } = init;
+    super(superInit);
+    this.destinationKey = destinationKey;
+  }
+}
+
+/**
+ * `CopyContext` の初期値です。
+ */
+type CopyContextInit = Omit<TransferContextInit<"copy">, "action">;
+
+/**
+ * コピー処理のコンテキストです。
+ */
+export class CopyContext extends TransferContext<"copy"> implements ICopyContext {
+  /**
+   * コンテキストを作成します。
+   *
+   * @param init 初期値です。
+   */
+  public constructor(init: CopyContextInit) {
+    super({
+      ...init,
+      action: "copy",
+    });
+  }
+}
+
+/**
+ * `MoveContext` の初期値です。
+ */
+type MoveContextInit = Omit<TransferContextInit<"move">, "action">;
+
+/**
+ * 移動処理のコンテキストです。
+ */
+export class MoveContext extends TransferContext<"move"> implements IMoveContext {
+  /**
+   * コンテキストを作成します。
+   *
+   * @param init 初期値です。
+   */
+  public constructor(init: MoveContextInit) {
+    super({
+      ...init,
+      action: "move",
+    });
+  }
+}
+
 /**
  * `ClearContext` の初期値です。
  */

package/src/_storage.ts

@@ -157,6 +157,32 @@ export default class UniKvsStorage {
     await this.#io.clear(c);
   }
 
+  /**
+   * データを別のキーへ複製します。
+   *
+   * @param c コピー元とコピー先のキーを持つコンテキストです。
+   */
+  public async copy(c: IStorage.CopyContext): Promise<void> {
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
+    }
+
+    await this.#io.copy(c);
+  }
+
+  /**
+   * データを別のキーへ移動します。
+   *
+   * @param c 移動元と移動先のキーを持つコンテキストです。
+   */
+  public async move(c: IStorage.MoveContext): Promise<void> {
+    if (!this.#io.isOpen) {
+      throw new StorageIsNotOpenError({ name: this.name });
+    }
+
+    await this.#io.move(c);
+  }
+
   /**
    * 読み取り用のストリームを取得します。
    *

package/src/_unikvs.schemas.ts

@@ -413,6 +413,130 @@ export const DeleteArgsSchema: GenericSchema<
   ),
 ]);
 
+export const CopyOptionsSchema: ObjectSchema<
+  {
+    readonly key: StringSchema<undefined>;
+    readonly vars: OptionalSchema<typeof VariablesInitSchema, undefined>;
+    readonly signal: OptionalSchema<InstanceSchema<typeof AbortSignal, undefined>, undefined>;
+    readonly destinationKey: StringSchema<undefined>;
+  },
+  undefined
+> = v.object({
+  key: v.string(),
+  vars: v.optional(VariablesInitSchema),
+  signal: v.optional(v.instance(AbortSignal)),
+  destinationKey: v.string(),
+});
+
+export const CopyArgsSchema: GenericSchema<
+  any,
+  readonly [
+    {
+      readonly key: string;
+      readonly vars?: readonly VariablesEntry[] | undefined;
+      readonly signal?: AbortSignal | undefined;
+      readonly destinationKey: string;
+    },
+  ]
+> = v.union([
+  v.tuple([CopyOptionsSchema]),
+  v.pipe(
+    v.tuple([
+      CopyOptionsSchema.entries.key,
+      CopyOptionsSchema.entries.destinationKey,
+      v.optional(v.omit(CopyOptionsSchema, ["key", "destinationKey"])),
+    ]),
+    v.transform(
+      ([key, destinationKey, options]: [
+        string,
+        string,
+        (
+          | {
+              vars?: readonly VariablesEntry[] | undefined;
+              signal?: AbortSignal | undefined;
+            }
+          | undefined
+        ),
+      ]): [
+        {
+          key: string;
+          vars?: readonly VariablesEntry[] | undefined;
+          signal?: AbortSignal | undefined;
+          destinationKey: string;
+        },
+      ] => [
+        {
+          ...options,
+          key,
+          destinationKey,
+        },
+      ],
+    ),
+  ),
+]);
+
+export const MoveOptionsSchema: ObjectSchema<
+  {
+    readonly key: StringSchema<undefined>;
+    readonly vars: OptionalSchema<typeof VariablesInitSchema, undefined>;
+    readonly signal: OptionalSchema<InstanceSchema<typeof AbortSignal, undefined>, undefined>;
+    readonly destinationKey: StringSchema<undefined>;
+  },
+  undefined
+> = v.object({
+  key: v.string(),
+  vars: v.optional(VariablesInitSchema),
+  signal: v.optional(v.instance(AbortSignal)),
+  destinationKey: v.string(),
+});
+
+export const MoveArgsSchema: GenericSchema<
+  any,
+  readonly [
+    {
+      readonly key: string;
+      readonly vars?: readonly VariablesEntry[] | undefined;
+      readonly signal?: AbortSignal | undefined;
+      readonly destinationKey: string;
+    },
+  ]
+> = v.union([
+  v.tuple([MoveOptionsSchema]),
+  v.pipe(
+    v.tuple([
+      MoveOptionsSchema.entries.key,
+      MoveOptionsSchema.entries.destinationKey,
+      v.optional(v.omit(MoveOptionsSchema, ["key", "destinationKey"])),
+    ]),
+    v.transform(
+      ([key, destinationKey, options]: [
+        string,
+        string,
+        (
+          | {
+              vars?: readonly VariablesEntry[] | undefined;
+              signal?: AbortSignal | undefined;
+            }
+          | undefined
+        ),
+      ]): [
+        {
+          key: string;
+          vars?: readonly VariablesEntry[] | undefined;
+          signal?: AbortSignal | undefined;
+          destinationKey: string;
+        },
+      ] => [
+        {
+          ...options,
+          key,
+          destinationKey,
+        },
+      ],
+    ),
+  ),
+]);
+
 export const ClearOptionsSchema: ObjectSchema<
   {
     readonly vars: OptionalSchema<typeof VariablesInitSchema, undefined>;

package/src/errors.ts

@@ -715,7 +715,7 @@ export type PluginOperationAggregateErrorMeta = {
   /**
    * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#errors)
    */
-  readonly action: "open" | "close" | "write" | "read" | "delete" | "clear";
+  readonly action: "open" | "close" | "write" | "read" | "delete" | "copy" | "move" | "clear";
 
   /**
    * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#errors)
@@ -755,7 +755,7 @@ export type PluginOperationAggregateErrorArgs = ErrorOptions & {
   /**
    * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#errors)
    */
-  readonly action: "open" | "close" | "write" | "read" | "delete" | "clear";
+  readonly action: "open" | "close" | "write" | "read" | "delete" | "copy" | "move" | "clear";
 
   /**
    * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#errors)

package/src/unikvs.ts

@@ -9,6 +9,8 @@ import {
   GetContext,
   HasContext,
   SetContext,
+  CopyContext,
+  MoveContext,
   OpenContext,
   ClearContext,
   CloseContext,
@@ -26,6 +28,8 @@ import {
   GetArgsSchema,
   HasArgsSchema,
   SetArgsSchema,
+  CopyArgsSchema,
+  MoveArgsSchema,
   OpenArgsSchema,
   ClearArgsSchema,
   CloseArgsSchema,
@@ -58,6 +62,8 @@ import type {
   GetOptions,
   HasOptions,
   SetOptions,
+  CopyOptions,
+  MoveOptions,
   OpenOptions,
   ClearOptions,
   CloseOptions,
@@ -1222,6 +1228,56 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
     }
   }
 
+  /**
+   * キーの値を別のキーへ複製します。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
+   *
+   * @param options コピー元とコピー先のキーを持つオプションです。
+   *
+   * @returns コピーが完了したら解決します。
+   */
+  public copy<const TKey extends KeyofKeyValueMapping<TKeyValueMapping>>(
+    options: CopyOptions<TKey>,
+  ): Promise<void>;
+  public copy<
+    const TSourceKey extends KeyofKeyValueMapping<TKeyValueMapping>,
+    const TDestinationKey extends KeyofKeyValueMapping<TKeyValueMapping>,
+  >(
+    key: TSourceKey,
+    destinationKey: TDestinationKey,
+    options?: Omit<CopyOptions<TSourceKey | TDestinationKey>, "key" | "destinationKey">,
+  ): Promise<void>;
+  public async copy(...args: any): Promise<void> {
+    const [options] = v.parseInput(CopyArgsSchema, args);
+    await this.#transfer("copy", options);
+  }
+
+  /**
+   * キーの値を別のキーへ移動します。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
+   *
+   * @param options 移動元と移動先のキーを持つオプションです。
+   *
+   * @returns 移動が完了したら解決します。
+   */
+  public move<const TKey extends KeyofKeyValueMapping<TKeyValueMapping>>(
+    options: MoveOptions<TKey>,
+  ): Promise<void>;
+  public move<
+    const TSourceKey extends KeyofKeyValueMapping<TKeyValueMapping>,
+    const TDestinationKey extends KeyofKeyValueMapping<TKeyValueMapping>,
+  >(
+    key: TSourceKey,
+    destinationKey: TDestinationKey,
+    options?: Omit<MoveOptions<TSourceKey | TDestinationKey>, "key" | "destinationKey">,
+  ): Promise<void>;
+  public async move(...args: any): Promise<void> {
+    const [options] = v.parseInput(MoveArgsSchema, args);
+    await this.#transfer("move", options);
+  }
+
   public async clear(options?: ClearOptions): Promise<void>;
   public async clear(...args: any): Promise<void> {
     if (this.#con === null) {
@@ -1280,6 +1336,187 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
     }
   }
 
+  /**
+   * コピーまたは移動を実行します。
+   *
+   * @param action 実行する操作です。
+   * @param options コピー元・移動元とコピー先・移動先のキーを持つオプションです。
+   *
+   * @returns 操作が完了したら解決します。
+   */
+  async #transfer(
+    action: "copy" | "move",
+    options: {
+      readonly key: string;
+      readonly vars?: readonly VariablesEntry[] | undefined;
+      readonly signal?: AbortSignal | undefined;
+      readonly destinationKey: string;
+    },
+  ): Promise<void> {
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const { key, destinationKey } = options;
+
+    // コピー元・移動元とコピー先・移動先の両方がスキーマに適合するか検証します。
+    this.#resolveValueSchema(key);
+    this.#resolveValueSchema(destinationKey);
+
+    const { ac, io } = this.#con;
+    const signal = combineSignals([ac.signal, options.signal]);
+    const store = this.#createOperationStore(options.vars);
+
+    using _lock = await asyncmux.readonly(this, signal);
+    // ロック待機中に接続状態が変更されていないか再確認します。
+    if (this.#con === null) {
+      throw new UniKvsIsNotOpenError();
+    }
+
+    const useContext =
+      action === "copy"
+        ? new CopyContext({
+            key,
+            store,
+            signal,
+            destinationKey,
+          })
+        : new MoveContext({
+            key,
+            store,
+            signal,
+            destinationKey,
+          });
+    await this.#use(action, useContext);
+
+    throwIfAborted(signal);
+
+    const sourceResolver = this.#pipeline.createResolver({
+      key,
+      store,
+      signal,
+    });
+    const destinationResolver =
+      key === destinationKey
+        ? sourceResolver
+        : this.#pipeline.createResolver({
+            key: destinationKey,
+            store,
+            signal,
+          });
+
+    if (key === destinationKey) {
+      // 同一キーへのコピー・移動は存在確認だけを行います。
+      using _ioLock = await io.lock({
+        key,
+        signal,
+      });
+
+      await this.#transferLeaves(action, key, store, signal, sourceResolver, destinationResolver);
+
+      return;
+    }
+
+    // デッドロックを避けるため、キーを常に同じ順序でロックします。
+    const firstLockKey = key < destinationKey ? key : destinationKey;
+    const secondLockKey = key < destinationKey ? destinationKey : key;
+    using _firstLock = await io.lock({
+      key: firstLockKey,
+      signal,
+    });
+    using _secondLock = await io.lock({
+      key: secondLockKey,
+      signal,
+    });
+
+    await this.#transferLeaves(action, key, store, signal, sourceResolver, destinationResolver);
+  }
+
+  /**
+   * 各ストレージへコピーまたは移動を適用します。
+   *
+   * @param action 実行する操作です。
+   * @param key コピー元または移動元の論理キーです。
+   * @param store 操作内で共有される変数ストアです。
+   * @param signal 中断シグナルです。
+   * @param sourceResolver コピー元・移動元のキーを解決するリゾルバーです。
+   * @param destinationResolver コピー先・移動先のキーを解決するリゾルバーです。
+   *
+   * @returns 操作が完了したら解決します。
+   */
+  async #transferLeaves(
+    action: "copy" | "move",
+    key: string,
+    store: VariablesStore,
+    signal: AbortSignal,
+    sourceResolver: ReturnType<PipelineGraph["createResolver"]>,
+    destinationResolver: ReturnType<PipelineGraph["createResolver"]>,
+  ): Promise<void> {
+    const errors: PluginErrorRecord[] = [];
+    let found = 0;
+    await Promise.all(
+      this.#pipeline.leaves.map(async (leaf) => {
+        const sourceKey = sourceResolver.resolve(leaf).key;
+        const destinationKey = destinationResolver.resolve(leaf).key;
+
+        try {
+          const existsContext = new HasContext({
+            key: sourceKey,
+            store,
+            signal,
+          });
+
+          if (!(await leaf.storage.exists(existsContext))) {
+            return;
+          }
+
+          found += 1;
+
+          if (action === "copy") {
+            const c = new CopyContext({
+              key: sourceKey,
+              store,
+              signal,
+              destinationKey,
+            });
+            await leaf.storage.copy(c);
+          } else {
+            const c = new MoveContext({
+              key: sourceKey,
+              store,
+              signal,
+              destinationKey,
+            });
+            await leaf.storage.move(c);
+          }
+        } catch (ex) {
+          if (signal.aborted) {
+            throw ex;
+          }
+
+          errors.push({
+            name: leaf.name,
+            index: leaf.index,
+            reason: ex,
+          });
+          logger.error`Failed to ${action} in a storage: ${ex}`;
+        }
+      }),
+    );
+
+    if (found === 0) {
+      throw this.#notFound(key, errors, action);
+    }
+
+    if (errors.length > 0) {
+      throw new PluginOperationAggregateError({
+        action,
+        errors,
+        plugin: "storage",
+      });
+    }
+  }
+
   /**
    * 基本変数と操作固有変数を結合した実行時変数マップを作成します。
    *
@@ -1328,10 +1565,15 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
    *
    * @param key 読み取ったキーです。
    * @param errors 収集した失敗です。
+   * @param action 失敗を集約する操作です。
    *
    * @returns `KeyNotFoundError` を返します。
    */
-  #notFound(key: string, errors: readonly PluginErrorRecord[]): KeyNotFoundError {
+  #notFound(
+    key: string,
+    errors: readonly PluginErrorRecord[],
+    action: "read" | "copy" | "move" = "read",
+  ): KeyNotFoundError {
     const args: KeyNotFoundErrorArgs = { key };
 
     switch (errors.length) {
@@ -1351,7 +1593,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
 
       default: {
         args.cause = new PluginOperationAggregateError({
-          action: "read",
+          action,
           errors,
           plugin: "storage",
         });
@@ -1543,7 +1785,7 @@ export default class UniKvs<TKeyValueMapping extends KeyValueMapping = KeyValueM
    * @param c 共有の `use` コンテキストです。
    */
   async #use(
-    action: "read" | "write" | "delete" | "clear",
+    action: "read" | "write" | "delete" | "copy" | "move" | "clear",
     c: IMiddleware.UseContext,
   ): Promise<void> {
     throwIfAborted(c.signal);

package/src/unikvs.types.ts

@@ -188,6 +188,56 @@ export type DeleteOptions<TKey = string> = {
   readonly vars?: VariablesInit | undefined;
 };
 
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
+ */
+export type CopyOptions<TKey = string> = {
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
+   */
+  readonly key: TKey;
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
+   */
+  readonly destinationKey: TKey;
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#variables-and-cancellation)
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#variables-and-cancellation)
+   */
+  readonly vars?: VariablesInit | undefined;
+};
+
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
+ */
+export type MoveOptions<TKey = string> = {
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
+   */
+  readonly key: TKey;
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
+   */
+  readonly destinationKey: TKey;
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#variables-and-cancellation)
+   */
+  readonly signal?: AbortSignal | undefined;
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#variables-and-cancellation)
+   */
+  readonly vars?: VariablesInit | undefined;
+};
+
 /**
  * [API Reference](https://tai-kun.github.io/unikvs/packages/unikvs#client-operations)
  */