@procedures/store 0.0.0-stage → 0.1.0

package/dist/storage/adapter.js

@@ -0,0 +1,214 @@
+/**
+ * Procedure Storage Adapter
+ *
+ * Wraps CollectionStorage<SerializedProcedure> to provide procedure-specific
+ * storage operations with serialization/deserialization.
+ */
+import { pathToKey } from "@procedures/client";
+import { serializeProcedure, deserializeProcedure, getProcedureKey, } from "./serialization.js";
+/**
+ * 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 {
+    storage;
+    handlerLoader;
+    serializeOptions;
+    constructor(storage, options = {}) {
+        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, options) {
+        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) {
+        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) {
+        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) {
+        const key = pathToKey(path);
+        return this.storage.delete(key);
+    }
+    // ===========================================================================
+    // Bulk Operations
+    // ===========================================================================
+    /**
+     * Load all procedures from storage.
+     *
+     * @returns Array of all procedures
+     */
+    async loadAll() {
+        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) {
+        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, options) {
+        const items = 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) {
+        const keys = paths.map(pathToKey);
+        return this.storage.deleteBatch(keys);
+    }
+    /**
+     * Clear all procedures from storage.
+     */
+    async clear() {
+        await this.storage.clear();
+    }
+    // ===========================================================================
+    // Info Operations
+    // ===========================================================================
+    /**
+     * Get the number of stored procedures.
+     */
+    async size() {
+        return this.storage.size();
+    }
+    /**
+     * List all stored procedure paths.
+     *
+     * @returns Array of procedure paths
+     */
+    async listPaths() {
+        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) {
+        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() {
+        return this.storage.getAll();
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    /**
+     * Close the underlying storage.
+     */
+    async close() {
+        await this.storage.close();
+    }
+    /**
+     * Get the underlying storage instance.
+     * Use for advanced operations or testing.
+     */
+    getStorage() {
+        return this.storage;
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/storage/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/storage/adapter.ts"],"names":[],"mappings":"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"}

package/dist/storage/api.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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";
+/**
+ * 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;
+}
+/**
+ * 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 declare class ApiStorage<T> implements CollectionStorage<T> {
+    private client;
+    private options;
+    constructor(client: Client, options: ApiStorageOptions);
+    get(id: string): Promise<T | undefined>;
+    getAll(): Promise<T[]>;
+    find(predicate: (item: T) => boolean): Promise<T[]>;
+    has(id: string): Promise<boolean>;
+    size(): Promise<number>;
+    set(id: string, value: T): Promise<void>;
+    delete(id: string): Promise<boolean>;
+    clear(): Promise<void>;
+    setBatch(items: Array<[string, T]>): Promise<void>;
+    deleteBatch(ids: string[]): Promise<number>;
+    getBatch(ids: string[]): Promise<Map<string, T>>;
+    close(): Promise<void>;
+    getMetadata(): Promise<StorageMetadata>;
+    /**
+     * Make an RPC call via the universal client, with the timeout, the signal and the retries.
+     */
+    private call;
+    /** One attempt: the call ends at the timeout, or when the signal of the options aborts. */
+    private attempt;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/storage/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/storage/api.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAIjD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IAEF;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAEzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,iBAAiB,CAAC,CAAC,CAAC;IACxD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CASb;IAEF,YAAY,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,EA8BrD;IAMK,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAG5C;IAEK,MAAM,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC,CAM3B;IAEK,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAIxD;IAEK,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEtC;IAEK,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAE5B;IAMK,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7C;IAEK,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzC;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;IAMK,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvD;IAEK,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAEhD;IAEK,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CASrD;IAMK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAK3B;IAEK,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC,CAY5C;IAMD;;OAEG;YACW,IAAI;IAqBlB,2FAA2F;IAC3F,OAAO,CAAC,OAAO;CAsBhB"}

package/dist/storage/api.js

@@ -0,0 +1,220 @@
+/**
+ * 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!
+ */
+/** An error that says whether another attempt can succeed (a ClientError does). */
+function isRetryable(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.retryable === true);
+}
+/** A promise that rejects when the signal aborts first. */
+function untilAborted(promise, signal, describe) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(describe());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(describe());
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            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 {
+    client;
+    options;
+    constructor(client, options) {
+        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) {
+        const value = await this.call("get", { id });
+        return value ?? undefined;
+    }
+    async getAll() {
+        const values = await this.call("getAll", {});
+        if (!Array.isArray(values)) {
+            throw new Error(`${this.options.service}.getAll did not return an array`);
+        }
+        return values;
+    }
+    async find(predicate) {
+        // 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) {
+        return (await this.call("has", { id })) === true;
+    }
+    async size() {
+        return Number(await this.call("size", {}));
+    }
+    //
+    // ═══ Write Operations ═══
+    //
+    async set(id, value) {
+        await this.call("set", { id, value });
+    }
+    async delete(id) {
+        return (await this.call("delete", { id })) === true;
+    }
+    async clear() {
+        await this.call("clear", {});
+    }
+    //
+    // ═══ Bulk Operations ═══
+    //
+    async setBatch(items) {
+        // The collection procedure takes objects, not tuples
+        await this.call("setBatch", { items: items.map(([id, value]) => ({ id, value })) });
+    }
+    async deleteBatch(ids) {
+        return Number(await this.call("deleteBatch", { ids }));
+    }
+    async getBatch(ids) {
+        const values = (await this.call("getBatch", { ids })) ?? {};
+        // Convert object to Map
+        const result = new Map();
+        for (const [id, value] of Object.entries(values)) {
+            result.set(id, value);
+        }
+        return result;
+    }
+    //
+    // ═══ Lifecycle & Metadata ═══
+    //
+    async close() {
+        // The client belongs to the caller, unless the caller gave it to this storage
+        if (this.options.closeClient) {
+            await this.client.close();
+        }
+    }
+    async getMetadata() {
+        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.
+     */
+    async call(operation, payload) {
+        const 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(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);
+            }
+        }
+    }
+    /** One attempt: the call ends at the timeout, or when the signal of the options aborts. */
+    attempt(method, payload, label) {
+        const signals = [];
+        if (this.options.signal)
+            signals.push(this.options.signal);
+        const timer = this.options.timeout > 0 ? new AbortController() : undefined;
+        let timeoutHandle;
+        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 = {};
+        if (signal)
+            callOptions.signal = signal;
+        const call = this.client.call(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);
+        });
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/storage/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/storage/api.ts"],"names":[],"mappings":"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"}