@procedures/store 0.0.0-stage → 0.1.0

package/src/storage/adapter.ts

@@ -0,0 +1,273 @@
+/**
+ * Procedure Storage Adapter
+ *
+ * Wraps CollectionStorage<SerializedProcedure> to provide procedure-specific
+ * storage operations with serialization/deserialization.
+ */
+
+import type { CollectionStorage } from "@procedures/collections";
+import type { AnyProcedure, ProcedurePath } from "@procedures/client";
+import { pathToKey } from "@procedures/client";
+import type { SerializedProcedure, HandlerLoader } from "./types.js";
+import {
+  serializeProcedure,
+  deserializeProcedure,
+  getProcedureKey,
+  type SerializeOptions,
+} from "./serialization.js";
+
+// =============================================================================
+// Procedure Storage Adapter
+// =============================================================================
+
+/**
+ * Options for ProcedureStorageAdapter.
+ */
+export interface ProcedureStorageAdapterOptions {
+  /** Handler loader for restoring handlers from references */
+  handlerLoader?: HandlerLoader | undefined;
+
+  /** Default serialization options */
+  serializeOptions?: SerializeOptions | undefined;
+}
+
+/**
+ * Adapter that wraps CollectionStorage for procedure-specific operations.
+ *
+ * Handles serialization/deserialization of procedures and provides
+ * convenience methods for common operations.
+ *
+ * @example
+ * ```typescript
+ * const storage = new InMemoryStorage<SerializedProcedure>();
+ * const adapter = new ProcedureStorageAdapter(storage, {
+ *   handlerLoader: createDynamicHandlerLoader(),
+ * });
+ *
+ * // Store a procedure
+ * await adapter.store(myProcedure);
+ *
+ * // Load a procedure
+ * const proc = await adapter.load(['lib', 'scan']);
+ * ```
+ */
+export class ProcedureStorageAdapter {
+  private readonly storage: CollectionStorage<SerializedProcedure>;
+  private readonly handlerLoader: HandlerLoader | undefined;
+  private readonly serializeOptions: SerializeOptions;
+
+  constructor(
+    storage: CollectionStorage<SerializedProcedure>,
+    options: ProcedureStorageAdapterOptions = {}
+  ) {
+    this.storage = storage;
+    this.handlerLoader = options.handlerLoader;
+    this.serializeOptions = options.serializeOptions ?? {};
+  }
+
+  // ===========================================================================
+  // Single Item Operations
+  // ===========================================================================
+
+  /**
+   * Store a procedure.
+   *
+   * @param procedure - Procedure to store
+   * @param options - Override default serialization options
+   * @returns The record that the storage got
+   */
+  async store(procedure: AnyProcedure, options?: SerializeOptions): Promise<SerializedProcedure> {
+    const key = getProcedureKey(procedure);
+    const serialized = serializeProcedure(procedure, {
+      ...this.serializeOptions,
+      ...options,
+    });
+    await this.storage.set(key, serialized);
+    return serialized;
+  }
+
+  /**
+   * Load a procedure by path.
+   *
+   * @param path - Procedure path
+   * @returns Procedure or undefined if not found
+   */
+  async load(path: ProcedurePath): Promise<AnyProcedure | undefined> {
+    const key = pathToKey(path);
+    const data = await this.storage.get(key);
+    if (!data) return undefined;
+
+    return deserializeProcedure(data, {
+      handlerLoader: this.handlerLoader,
+    });
+  }
+
+  /**
+   * Check if a procedure exists in storage.
+   *
+   * @param path - Procedure path
+   * @returns True if procedure exists
+   */
+  async has(path: ProcedurePath): Promise<boolean> {
+    const key = pathToKey(path);
+    return this.storage.has(key);
+  }
+
+  /**
+   * Remove a procedure from storage.
+   *
+   * @param path - Procedure path
+   * @returns True if procedure was removed
+   */
+  async remove(path: ProcedurePath): Promise<boolean> {
+    const key = pathToKey(path);
+    return this.storage.delete(key);
+  }
+
+  // ===========================================================================
+  // Bulk Operations
+  // ===========================================================================
+
+  /**
+   * Load all procedures from storage.
+   *
+   * @returns Array of all procedures
+   */
+  async loadAll(): Promise<AnyProcedure[]> {
+    const items = await this.storage.getAll();
+    return Promise.all(
+      items.map((item) =>
+        deserializeProcedure(item, { handlerLoader: this.handlerLoader })
+      )
+    );
+  }
+
+  /**
+   * Load procedures matching a path prefix.
+   *
+   * @param prefix - Path prefix to match
+   * @returns Array of matching procedures
+   *
+   * @example
+   * ```typescript
+   * // Load all lib.* procedures
+   * const libProcedures = await adapter.loadByPrefix(['lib']);
+   * ```
+   */
+  async loadByPrefix(prefix: ProcedurePath): Promise<AnyProcedure[]> {
+    const prefixKey = pathToKey(prefix);
+    const items = await this.storage.find((item) => {
+      const itemKey = pathToKey(item.path);
+      return itemKey === prefixKey || itemKey.startsWith(prefixKey + ".");
+    });
+
+    return Promise.all(
+      items.map((item) =>
+        deserializeProcedure(item, { handlerLoader: this.handlerLoader })
+      )
+    );
+  }
+
+  /**
+   * Store multiple procedures.
+   *
+   * @param procedures - Procedures to store
+   * @param options - Override default serialization options, or a function that gives the
+   *   options of each procedure (for example, its handler reference)
+   * @returns The records that the storage got
+   */
+  async storeAll(
+    procedures: AnyProcedure[],
+    options?: SerializeOptions | ((procedure: AnyProcedure) => SerializeOptions | undefined)
+  ): Promise<SerializedProcedure[]> {
+    const items: Array<[string, SerializedProcedure]> = procedures.map((proc) => [
+      getProcedureKey(proc),
+      serializeProcedure(proc, {
+        ...this.serializeOptions,
+        ...(typeof options === "function" ? options(proc) : options),
+      }),
+    ]);
+    await this.storage.setBatch(items);
+    return items.map(([, serialized]) => serialized);
+  }
+
+  /**
+   * Remove multiple procedures.
+   *
+   * @param paths - Procedure paths to remove
+   * @returns Number of procedures removed
+   */
+  async removeAll(paths: ProcedurePath[]): Promise<number> {
+    const keys = paths.map(pathToKey);
+    return this.storage.deleteBatch(keys);
+  }
+
+  /**
+   * Clear all procedures from storage.
+   */
+  async clear(): Promise<void> {
+    await this.storage.clear();
+  }
+
+  // ===========================================================================
+  // Info Operations
+  // ===========================================================================
+
+  /**
+   * Get the number of stored procedures.
+   */
+  async size(): Promise<number> {
+    return this.storage.size();
+  }
+
+  /**
+   * List all stored procedure paths.
+   *
+   * @returns Array of procedure paths
+   */
+  async listPaths(): Promise<ProcedurePath[]> {
+    const items = await this.storage.getAll();
+    return items.map((item) => item.path);
+  }
+
+  /**
+   * Get the raw serialized data for a procedure.
+   * Useful for debugging or custom processing.
+   *
+   * @param path - Procedure path
+   * @returns Serialized procedure data or undefined
+   */
+  async getRaw(path: ProcedurePath): Promise<SerializedProcedure | undefined> {
+    const key = pathToKey(path);
+    return this.storage.get(key);
+  }
+
+  /**
+   * Get all raw serialized data.
+   * Useful for debugging or backup.
+   *
+   * @returns Array of serialized procedures
+   */
+  async getAllRaw(): Promise<SerializedProcedure[]> {
+    return this.storage.getAll();
+  }
+
+  // ===========================================================================
+  // Lifecycle
+  // ===========================================================================
+
+  /**
+   * Close the underlying storage.
+   */
+  async close(): Promise<void> {
+    await this.storage.close();
+  }
+
+  /**
+   * Get the underlying storage instance.
+   * Use for advanced operations or testing.
+   */
+  getStorage(): CollectionStorage<SerializedProcedure> {
+    return this.storage;
+  }
+}

package/src/storage/api.ts

@@ -0,0 +1,335 @@
+/**
+ * API Storage Implementation
+ *
+ * Remote storage backed by universal client.
+ * Enables collections to be persisted on a server.
+ *
+ * This is the KEY integration between Collections and Universal Client!
+ */
+
+import type { CollectionStorage, StorageMetadata } from "@procedures/collections";
+import type { Client } from "@procedures/client";
+import type { Method } from "@procedures/client";
+import type { CallOptions } from "@procedures/client/client";
+
+/**
+ * API storage configuration options.
+ */
+export interface ApiStorageOptions {
+  /**
+   * The collection of the core collection procedures. The calls go to
+   * `collections.<collection>.<operation>`, as `createCollectionProcedures(collection)` registers them.
+   * @example "users", "procedures"
+   */
+  collection?: string;
+
+  /**
+   * Service name for RPC calls. The default is `collections.<collection>`. Give a service only
+   * for a server with other paths.
+   * @example "users", "orders", "products"
+   */
+  service?: string;
+
+  /**
+   * Optional API version
+   * @example "v1", "v2"
+   */
+  version?: string;
+
+  /**
+   * Custom operation names (override defaults)
+   */
+  operations?: {
+    get?: string;
+    getAll?: string;
+    find?: string;
+    has?: string;
+    size?: string;
+    set?: string;
+    delete?: string;
+    clear?: string;
+    setBatch?: string;
+    deleteBatch?: string;
+    getBatch?: string;
+  };
+
+  /**
+   * Request timeout in milliseconds. A call that takes longer fails. 0: no timeout.
+   * @default 30000 (30 seconds)
+   */
+  timeout?: number;
+
+  /**
+   * Retry a call that fails with a retryable error: true (3 attempts), false (1 attempt), or the
+   * number of attempts.
+   * @default true
+   */
+  retry?: boolean | number;
+
+  /**
+   * The first delay between attempts in milliseconds. Each later delay is two times longer.
+   * @default 100
+   */
+  retryDelay?: number;
+
+  /**
+   * AbortSignal for cancelling requests
+   */
+  signal?: AbortSignal;
+
+  /**
+   * True: `close()` closes the client. The default is false: the client belongs to the caller.
+   * @default false
+   */
+  closeClient?: boolean;
+}
+
+/** An error that says whether another attempt can succeed (a ClientError does). */
+function isRetryable(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { retryable?: unknown }).retryable === true
+  );
+}
+
+/** A promise that rejects when the signal aborts first. */
+function untilAborted<T>(promise: Promise<T>, signal: AbortSignal | undefined, describe: () => Error): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(describe());
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(describe());
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    );
+  });
+}
+
+/**
+ * API storage backed by universal client.
+ *
+ * Maps collection operations to the core collection procedures
+ * (`createCollectionProcedures`), which take and return raw values:
+ * - get(id) → `collections.<collection>.get` with `{ id }`
+ * - set(id, value) → `collections.<collection>.set` with `{ id, value }`
+ * - setBatch(items) → `collections.<collection>.setBatch` with `{ items: [{ id, value }] }`
+ * - etc.
+ *
+ * Before, the class expected a `{ data }` envelope and called `<service>.get`: no core
+ * procedure matched, and every read was undefined (deep dive CORE-9, DATA-9).
+ *
+ * @example
+ * ```typescript
+ * // Create API storage
+ * const client = new Client({
+ *   transport: new HttpTransport({ baseUrl: "https://api.example.com" })
+ * });
+ *
+ * const storage = new ApiStorage(client, { collection: "users" });
+ *
+ * // Operations are automatically sent to server
+ * await storage.set("123", { name: "John" });
+ * const user = await storage.get("123"); // Fetched from server
+ * ```
+ */
+export class ApiStorage<T> implements CollectionStorage<T> {
+  private client: Client;
+  private options: {
+    service: string;
+    version?: string;
+    operations: Required<NonNullable<ApiStorageOptions["operations"]>>;
+    timeout: number;
+    attempts: number;
+    retryDelay: number;
+    signal?: AbortSignal;
+    closeClient: boolean;
+  };
+
+  constructor(client: Client, options: ApiStorageOptions) {
+    const service = options.service ?? (options.collection !== undefined ? `collections.${options.collection}` : undefined);
+    if (!service) {
+      throw new Error("ApiStorage requires a collection or a service");
+    }
+    this.client = client;
+    this.options = {
+      service,
+      ...(options.version !== undefined && { version: options.version }),
+      operations: {
+        get: "get",
+        getAll: "getAll",
+        find: "find",
+        has: "has",
+        size: "size",
+        set: "set",
+        delete: "delete",
+        clear: "clear",
+        setBatch: "setBatch",
+        deleteBatch: "deleteBatch",
+        getBatch: "getBatch",
+        ...options.operations,
+      },
+      timeout: options.timeout ?? 30000,
+      attempts:
+        options.retry === false ? 1 : options.retry === true || options.retry === undefined ? 3 : Math.max(1, options.retry),
+      retryDelay: options.retryDelay ?? 100,
+      ...(options.signal !== undefined && { signal: options.signal }),
+      closeClient: options.closeClient ?? false,
+    };
+  }
+
+  //
+  // ═══ Read Operations ═══
+  //
+
+  async get(id: string): Promise<T | undefined> {
+    const value = await this.call<T | null | undefined>("get", { id });
+    return value ?? undefined;
+  }
+
+  async getAll(): Promise<T[]> {
+    const values = await this.call<T[]>("getAll", {});
+    if (!Array.isArray(values)) {
+      throw new Error(`${this.options.service}.getAll did not return an array`);
+    }
+    return values;
+  }
+
+  async find(predicate: (item: T) => boolean): Promise<T[]> {
+    // A predicate cannot go over the network: read all items, then filter here
+    const all = await this.getAll();
+    return all.filter(predicate);
+  }
+
+  async has(id: string): Promise<boolean> {
+    return (await this.call<boolean>("has", { id })) === true;
+  }
+
+  async size(): Promise<number> {
+    return Number(await this.call<number>("size", {}));
+  }
+
+  //
+  // ═══ Write Operations ═══
+  //
+
+  async set(id: string, value: T): Promise<void> {
+    await this.call("set", { id, value });
+  }
+
+  async delete(id: string): Promise<boolean> {
+    return (await this.call<boolean>("delete", { id })) === true;
+  }
+
+  async clear(): Promise<void> {
+    await this.call("clear", {});
+  }
+
+  //
+  // ═══ Bulk Operations ═══
+  //
+
+  async setBatch(items: Array<[string, T]>): Promise<void> {
+    // The collection procedure takes objects, not tuples
+    await this.call("setBatch", { items: items.map(([id, value]) => ({ id, value })) });
+  }
+
+  async deleteBatch(ids: string[]): Promise<number> {
+    return Number(await this.call<number>("deleteBatch", { ids }));
+  }
+
+  async getBatch(ids: string[]): Promise<Map<string, T>> {
+    const values = (await this.call<Record<string, T> | null>("getBatch", { ids })) ?? {};
+
+    // Convert object to Map
+    const result = new Map<string, T>();
+    for (const [id, value] of Object.entries(values)) {
+      result.set(id, value);
+    }
+    return result;
+  }
+
+  //
+  // ═══ Lifecycle & Metadata ═══
+  //
+
+  async close(): Promise<void> {
+    // The client belongs to the caller, unless the caller gave it to this storage
+    if (this.options.closeClient) {
+      await this.client.close();
+    }
+  }
+
+  async getMetadata(): Promise<StorageMetadata> {
+    const storageSize = await this.size();
+
+    return {
+      type: "api",
+      size: storageSize,
+      stats: {
+        service: this.options.service,
+        version: this.options.version,
+        timeout: this.options.timeout,
+      },
+    };
+  }
+
+  //
+  // ═══ Internal Helpers ═══
+  //
+
+  /**
+   * Make an RPC call via the universal client, with the timeout, the signal and the retries.
+   */
+  private async call<TRes>(operation: keyof Required<ApiStorageOptions>["operations"], payload: unknown): Promise<TRes> {
+    const method: Method = {
+      service: this.options.service,
+      operation: this.options.operations[operation] ?? operation,
+      ...(this.options.version !== undefined && { version: this.options.version }),
+    };
+    const label = `${method.service}.${method.operation}`;
+
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await this.attempt<TRes>(method, payload, label);
+      } catch (error) {
+        if (attempt >= this.options.attempts || !isRetryable(error) || this.options.signal?.aborted) {
+          throw error;
+        }
+        const delay = this.options.retryDelay * 2 ** (attempt - 1);
+        await untilAborted(new Promise((resolve) => setTimeout(resolve, delay)), this.options.signal, () => error as Error);
+      }
+    }
+  }
+
+  /** One attempt: the call ends at the timeout, or when the signal of the options aborts. */
+  private attempt<TRes>(method: Method, payload: unknown, label: string): Promise<TRes> {
+    const signals: AbortSignal[] = [];
+    if (this.options.signal) signals.push(this.options.signal);
+    const timer = this.options.timeout > 0 ? new AbortController() : undefined;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    if (timer) {
+      timeoutHandle = setTimeout(() => timer.abort(), this.options.timeout);
+      signals.push(timer.signal);
+    }
+    const signal = signals.length === 0 ? undefined : signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+
+    // The signal goes in the call options, so the transport can stop the request too. (Before,
+    // it went into the metadata, and the timeout was dropped: deep dive CORE-9.)
+    const callOptions: CallOptions<unknown> = {};
+    if (signal) callOptions.signal = signal;
+    const call = this.client.call<unknown, TRes>(method, payload, callOptions);
+    return untilAborted(call, signal, () =>
+      timer?.signal.aborted ? new Error(`${label} timed out after ${this.options.timeout} ms`) : new Error(`${label} was aborted`)
+    ).finally(() => {
+      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+    });
+  }
+}