@procedures/client 0.0.0-stage → 0.2.0

package/dist/collections/storage/hybrid.js

@@ -0,0 +1,416 @@
+/**
+ * Hybrid Storage Implementation
+ *
+ * Combines local cache (InMemoryStorage) with remote persistence (ApiStorage).
+ * Provides fast local reads with remote backup and sync.
+ *
+ * Features:
+ * - Local cache for fast reads
+ * - Write-through or write-back strategies
+ * - Automatic sync on initialization
+ * - Conflict resolution
+ * - Offline operation queue
+ */
+import { InMemoryStorage } from "./memory.js";
+/**
+ * Hybrid storage combining local cache with remote persistence.
+ *
+ * @example
+ * ```typescript
+ * const client = new Client({
+ *   transport: new HttpTransport({ baseUrl: "https://api.example.com" })
+ * });
+ *
+ * const remote = new ApiStorage(client, { service: "users" });
+ * const hybrid = new HybridStorage(remote, {
+ *   writeStrategy: "write-through",
+ *   conflictResolution: "remote",
+ *   syncInterval: 5000
+ * });
+ *
+ * // Fast local reads
+ * const user = hybrid.get("123"); // From cache
+ *
+ * // Writes go to both local and remote
+ * await hybrid.set("123", { name: "John" });
+ * ```
+ */
+export class HybridStorage {
+    local;
+    remote;
+    options;
+    offlineOps = [];
+    syncTimer = null;
+    isOnline = true;
+    stats = {
+        cacheHits: 0,
+        cacheMisses: 0,
+        syncCount: 0,
+        conflicts: 0,
+    };
+    constructor(remote, options = {}) {
+        this.local = new InMemoryStorage();
+        this.remote = remote;
+        this.options = {
+            writeStrategy: options.writeStrategy ?? "write-through",
+            conflictResolution: options.conflictResolution ?? "remote",
+            ...(options.mergeFn !== undefined && { mergeFn: options.mergeFn }),
+            syncInterval: options.syncInterval ?? 5000,
+            syncOnInit: options.syncOnInit ?? true,
+            maxOfflineOps: options.maxOfflineOps ?? 1000,
+            offlineQueue: options.offlineQueue ?? true,
+        };
+        // Initialize with remote data
+        if (this.options.syncOnInit) {
+            this.syncFromRemote().catch((err) => {
+                console.error("Failed to sync on init:", err);
+            });
+        }
+        // Start periodic sync for write-back mode
+        if (this.options.writeStrategy === "write-back" &&
+            this.options.syncInterval > 0) {
+            this.startPeriodicSync();
+        }
+    }
+    //
+    // ═══ Read Operations ═══
+    //
+    async get(id) {
+        // Try local cache first
+        const cached = await this.local.get(id);
+        if (cached !== undefined) {
+            this.stats.cacheHits++;
+            return cached;
+        }
+        this.stats.cacheMisses++;
+        return undefined;
+    }
+    async getAll() {
+        // Return local cache
+        return this.local.getAll();
+    }
+    async find(predicate) {
+        // Search local cache
+        return this.local.find(predicate);
+    }
+    async has(id) {
+        return this.local.has(id);
+    }
+    async size() {
+        return this.local.size();
+    }
+    //
+    // ═══ Write Operations ═══
+    //
+    async set(id, value) {
+        // Always write to local immediately
+        await this.local.set(id, value);
+        if (this.options.writeStrategy === "write-through") {
+            // Write-through: sync to remote immediately
+            try {
+                await this.remote.set(id, value);
+            }
+            catch (error) {
+                this.handleRemoteFailure("set", { id, value });
+                throw error;
+            }
+        }
+        else {
+            // Write-back: queue for later sync
+            this.queueOperation({
+                type: "set",
+                data: { id, value },
+                timestamp: Date.now(),
+            });
+        }
+    }
+    async delete(id) {
+        const existed = await this.local.delete(id);
+        if (this.options.writeStrategy === "write-through") {
+            try {
+                await this.remote.delete(id);
+            }
+            catch (error) {
+                this.handleRemoteFailure("delete", { id });
+                throw error;
+            }
+        }
+        else {
+            this.queueOperation({
+                type: "delete",
+                data: { id },
+                timestamp: Date.now(),
+            });
+        }
+        return existed;
+    }
+    async clear() {
+        await this.local.clear();
+        if (this.options.writeStrategy === "write-through") {
+            try {
+                await this.remote.clear();
+            }
+            catch (error) {
+                this.handleRemoteFailure("clear", {});
+                throw error;
+            }
+        }
+        else {
+            this.queueOperation({
+                type: "clear",
+                data: {},
+                timestamp: Date.now(),
+            });
+        }
+    }
+    //
+    // ═══ Bulk Operations ═══
+    //
+    async setBatch(items) {
+        await this.local.setBatch(items);
+        if (this.options.writeStrategy === "write-through") {
+            try {
+                await this.remote.setBatch(items);
+            }
+            catch (error) {
+                this.handleRemoteFailure("setBatch", { items });
+                throw error;
+            }
+        }
+        else {
+            this.queueOperation({
+                type: "setBatch",
+                data: { items },
+                timestamp: Date.now(),
+            });
+        }
+    }
+    async deleteBatch(ids) {
+        const deleted = await this.local.deleteBatch(ids);
+        if (this.options.writeStrategy === "write-through") {
+            try {
+                await this.remote.deleteBatch(ids);
+            }
+            catch (error) {
+                this.handleRemoteFailure("deleteBatch", { ids });
+                throw error;
+            }
+        }
+        else {
+            this.queueOperation({
+                type: "deleteBatch",
+                data: { ids },
+                timestamp: Date.now(),
+            });
+        }
+        return deleted;
+    }
+    getBatch(ids) {
+        return this.local.getBatch(ids);
+    }
+    //
+    // ═══ Sync Operations ═══
+    //
+    /**
+     * Sync all data from remote to local.
+     * Handles conflicts according to conflict resolution strategy.
+     */
+    async syncFromRemote() {
+        try {
+            const remoteData = await this.remote.getAll();
+            for (const item of remoteData) {
+                // Assume items have an 'id' field for indexing
+                const id = item.id;
+                if (!id) {
+                    console.warn("Item missing id field, skipping:", item);
+                    continue;
+                }
+                const localItem = await this.local.get(id);
+                if (localItem === undefined) {
+                    // No local version - just store remote
+                    await this.local.set(id, item);
+                }
+                else {
+                    // Conflict - resolve according to strategy
+                    const resolved = this.resolveConflict(localItem, item);
+                    await this.local.set(id, resolved);
+                    this.stats.conflicts++;
+                }
+            }
+            this.stats.syncCount++;
+            this.isOnline = true;
+        }
+        catch (error) {
+            this.isOnline = false;
+            throw error;
+        }
+    }
+    /**
+     * Sync all pending offline operations to remote.
+     * Processes queued operations in order.
+     */
+    async syncToRemote() {
+        if (this.offlineOps.length === 0) {
+            return;
+        }
+        const opsToSync = [...this.offlineOps];
+        this.offlineOps = [];
+        try {
+            for (const op of opsToSync) {
+                await this.executeOperation(op);
+            }
+            this.isOnline = true;
+        }
+        catch (error) {
+            // Re-queue failed operations
+            this.offlineOps = [...opsToSync, ...this.offlineOps];
+            this.isOnline = false;
+            throw error;
+        }
+    }
+    /**
+     * Force a full sync (both directions).
+     */
+    async sync() {
+        await this.syncToRemote();
+        await this.syncFromRemote();
+    }
+    //
+    // ═══ Lifecycle & Metadata ═══
+    //
+    async close() {
+        // Stop periodic sync
+        if (this.syncTimer) {
+            clearInterval(this.syncTimer);
+            this.syncTimer = null;
+        }
+        // Sync pending operations before closing
+        if (this.offlineOps.length > 0) {
+            try {
+                await this.syncToRemote();
+            }
+            catch (error) {
+                console.error("Failed to sync before close:", error);
+            }
+        }
+        // Close remote storage
+        await this.remote.close();
+    }
+    async getMetadata() {
+        const totalOps = this.stats.cacheHits + this.stats.cacheMisses;
+        const hitRate = totalOps > 0 ? (this.stats.cacheHits / totalOps) * 100 : 0;
+        const currentSize = await this.local.size();
+        return {
+            type: "hybrid",
+            size: currentSize,
+            stats: {
+                hitRate: Math.round(hitRate * 100) / 100,
+                cacheHits: this.stats.cacheHits,
+                cacheMisses: this.stats.cacheMisses,
+                syncCount: this.stats.syncCount,
+                conflicts: this.stats.conflicts,
+                pendingOps: this.offlineOps.length,
+                isOnline: this.isOnline,
+                writeStrategy: this.options.writeStrategy,
+                conflictResolution: this.options.conflictResolution,
+            },
+        };
+    }
+    //
+    // ═══ Internal Helpers ═══
+    //
+    /**
+     * Resolve conflict between local and remote versions.
+     */
+    resolveConflict(local, remote) {
+        switch (this.options.conflictResolution) {
+            case "local":
+                return local;
+            case "remote":
+                return remote;
+            case "merge":
+                if (!this.options.mergeFn) {
+                    throw new Error("Merge function required for conflict resolution strategy 'merge'");
+                }
+                return this.options.mergeFn(local, remote);
+            case "error":
+                throw new Error(`Conflict detected between local and remote versions`);
+            default:
+                return remote;
+        }
+    }
+    /**
+     * Queue operation for later sync.
+     */
+    queueOperation(op) {
+        if (!this.options.offlineQueue) {
+            return;
+        }
+        this.offlineOps.push(op);
+        // Enforce max queue size
+        if (this.offlineOps.length > this.options.maxOfflineOps) {
+            this.offlineOps.shift(); // Remove oldest
+        }
+    }
+    /**
+     * Execute a queued operation against remote storage.
+     */
+    async executeOperation(op) {
+        const data = op.data;
+        switch (op.type) {
+            case "set":
+                await this.remote.set(data.id, data.value);
+                break;
+            case "delete":
+                await this.remote.delete(data.id);
+                break;
+            case "setBatch":
+                await this.remote.setBatch(data.items);
+                break;
+            case "deleteBatch":
+                await this.remote.deleteBatch(data.ids);
+                break;
+            case "clear":
+                await this.remote.clear();
+                break;
+        }
+    }
+    /**
+     * Handle remote operation failure.
+     */
+    handleRemoteFailure(operation, data) {
+        console.error(`Remote ${operation} failed, marking offline`);
+        this.isOnline = false;
+        // Queue operation if offline queue enabled
+        if (this.options.offlineQueue) {
+            this.queueOperation({
+                type: operation,
+                data,
+                timestamp: Date.now(),
+            });
+        }
+    }
+    /**
+     * Start periodic background sync.
+     */
+    startPeriodicSync() {
+        this.syncTimer = setInterval(() => {
+            this.syncToRemote().catch((err) => {
+                console.error("Periodic sync failed:", err);
+            });
+        }, this.options.syncInterval);
+    }
+    /**
+     * Get current online status.
+     */
+    isRemoteOnline() {
+        return this.isOnline;
+    }
+    /**
+     * Get pending offline operations count.
+     */
+    getPendingOpsCount() {
+        return this.offlineOps.length;
+    }
+}
+//# sourceMappingURL=hybrid.js.map

package/dist/collections/storage/hybrid.js.map

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

package/dist/collections/storage/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Collection Storage Backends
+ *
+ * Abstract storage layer enabling collections to be backed by:
+ * - In-memory (fast, volatile)
+ * - Remote API (persistent, shared)
+ * - Hybrid (local cache + remote sync)
+ */
+export type { CollectionStorage, StorageMetadata } from "./interface.js";
+export { normalizeStorageResult } from "./interface.js";
+export { InMemoryStorage } from "./memory.js";
+export { ApiStorage } from "./api.js";
+export type { ApiStorageOptions } from "./api.js";
+export { HybridStorage } from "./hybrid.js";
+export type { HybridStorageOptions, ConflictResolution, WriteStrategy } from "./hybrid.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/collections/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/collections/storage/index.js

@@ -0,0 +1,13 @@
+/**
+ * Collection Storage Backends
+ *
+ * Abstract storage layer enabling collections to be backed by:
+ * - In-memory (fast, volatile)
+ * - Remote API (persistent, shared)
+ * - Hybrid (local cache + remote sync)
+ */
+export { normalizeStorageResult } from "./interface.js";
+export { InMemoryStorage } from "./memory.js";
+export { ApiStorage } from "./api.js";
+export { HybridStorage } from "./hybrid.js";
+//# sourceMappingURL=index.js.map

package/dist/collections/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/collections/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/collections/storage/interface.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Collection Storage Interface
+ *
+ * Abstract storage layer for collections, enabling different backends:
+ * - InMemoryStorage: Fast, volatile storage using Map
+ * - ApiStorage: Remote persistence via universal client
+ * - HybridStorage: Local cache + remote sync with conflict resolution
+ * - SyncedStorage: Periodic background sync with offline support
+ *
+ * IMPORTANT: All methods return Promise to ensure client code is
+ * transport-agnostic (cannot distinguish local from remote storage).
+ */
+/**
+ * Storage backend interface for collections.
+ *
+ * All methods return Promise<T> to ensure consistent async behavior.
+ * This guarantees client code remains agnostic to the storage backend,
+ * enabling seamless switching between local and remote storage.
+ */
+export interface CollectionStorage<T> {
+    /**
+     * Get item by ID.
+     *
+     * @param id - Item identifier
+     * @returns Promise resolving to item or undefined if not found
+     */
+    get(id: string): Promise<T | undefined>;
+    /**
+     * Get all items in collection.
+     *
+     * @returns Promise resolving to array of all items
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Find items matching predicate.
+     *
+     * @param predicate - Filter function
+     * @returns Promise resolving to array of matching items
+     */
+    find(predicate: (item: T) => boolean): Promise<T[]>;
+    /**
+     * Check if item exists.
+     *
+     * @param id - Item identifier
+     * @returns Promise resolving to true if item exists
+     */
+    has(id: string): Promise<boolean>;
+    /**
+     * Get number of items in collection.
+     *
+     * @returns Promise resolving to count of items
+     */
+    size(): Promise<number>;
+    /**
+     * Set/update item by ID.
+     *
+     * @param id - Item identifier
+     * @param value - Item to store
+     * @returns Promise resolving when operation completes
+     */
+    set(id: string, value: T): Promise<void>;
+    /**
+     * Delete item by ID.
+     *
+     * @param id - Item identifier
+     * @returns Promise resolving to true if item was deleted, false if not found
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Clear all items from collection.
+     *
+     * @returns Promise resolving when operation completes
+     */
+    clear(): Promise<void>;
+    /**
+     * Set multiple items at once (more efficient than individual sets).
+     *
+     * @param items - Array of [id, value] tuples
+     * @returns Promise resolving when operation completes
+     */
+    setBatch(items: Array<[string, T]>): Promise<void>;
+    /**
+     * Delete multiple items at once.
+     *
+     * @param ids - Array of item identifiers
+     * @returns Promise resolving to number of items actually deleted
+     */
+    deleteBatch(ids: string[]): Promise<number>;
+    /**
+     * Get multiple items by ID at once.
+     *
+     * @param ids - Array of item identifiers
+     * @returns Promise resolving to Map of found items (missing IDs are omitted)
+     */
+    getBatch(ids: string[]): Promise<Map<string, T>>;
+    /**
+     * Close storage and cleanup resources.
+     * Should be called when collection is no longer needed.
+     *
+     * @returns Promise resolving when cleanup completes
+     */
+    close(): Promise<void>;
+    /**
+     * Get storage metadata/stats (optional).
+     * Useful for monitoring and debugging.
+     *
+     * @returns Promise resolving to storage-specific metadata
+     */
+    getMetadata?(): Promise<StorageMetadata>;
+}
+/**
+ * Optional storage metadata for monitoring.
+ */
+export interface StorageMetadata {
+    /** Storage backend type */
+    type: "memory" | "api" | "hybrid" | "synced" | "custom";
+    /** Number of items */
+    size: number;
+    /** Storage-specific stats */
+    stats?: {
+        /** Cache hit rate (for hybrid/synced storage) */
+        hitRate?: number;
+        /** Last sync timestamp (for synced storage) */
+        lastSync?: number;
+        /** Pending sync operations (for synced storage) */
+        pendingOps?: number;
+        /** Memory usage in bytes (for memory storage) */
+        memoryUsage?: number;
+        /** Custom stats */
+        [key: string]: unknown;
+    };
+}
+/**
+ * @deprecated All storage methods now return Promise.
+ * This helper is kept for backward compatibility but is no longer needed.
+ *
+ * @param value - Promise value
+ * @returns The same Promise
+ */
+export declare function normalizeStorageResult<T>(value: Promise<T>): Promise<T>;
+//# sourceMappingURL=interface.d.ts.map

package/dist/collections/storage/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../../src/collections/storage/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAKlC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAExC;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAElC;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAMxB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErC;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAMvB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAMjD;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAExD,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,KAAK,CAAC,EAAE;QACN,iDAAiD;QACjD,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,+CAA+C;QAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;QAElB,mDAAmD;QACnD,UAAU,CAAC,EAAE,MAAM,CAAC;QAEpB,iDAAiD;QACjD,WAAW,CAAC,EAAE,MAAM,CAAC;QAErB,mBAAmB;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEvE"}

package/dist/collections/storage/interface.js

@@ -0,0 +1,23 @@
+/**
+ * Collection Storage Interface
+ *
+ * Abstract storage layer for collections, enabling different backends:
+ * - InMemoryStorage: Fast, volatile storage using Map
+ * - ApiStorage: Remote persistence via universal client
+ * - HybridStorage: Local cache + remote sync with conflict resolution
+ * - SyncedStorage: Periodic background sync with offline support
+ *
+ * IMPORTANT: All methods return Promise to ensure client code is
+ * transport-agnostic (cannot distinguish local from remote storage).
+ */
+/**
+ * @deprecated All storage methods now return Promise.
+ * This helper is kept for backward compatibility but is no longer needed.
+ *
+ * @param value - Promise value
+ * @returns The same Promise
+ */
+export function normalizeStorageResult(value) {
+    return value;
+}
+//# sourceMappingURL=interface.js.map

package/dist/collections/storage/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../../src/collections/storage/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA8JH;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAI,KAAiB;IACzD,OAAO,KAAK,CAAC;AACf,CAAC"}