@procedures/client 0.0.0-stage → 0.1.0

package/dist/procedures/storage/hybrid.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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, with a remote read on a miss
+ * - Write-through or write-back strategies
+ * - Automatic sync on initialization
+ * - Conflict resolution
+ * - Offline operation queue
+ */
+import type { CollectionStorage, StorageMetadata } from "@mark1russell7/client-collections";
+/**
+ * Conflict resolution strategy.
+ */
+export type ConflictResolution = "local" | "remote" | "merge" | "error";
+/**
+ * Write strategy for hybrid storage.
+ */
+export type WriteStrategy = "write-through" | "write-back";
+/**
+ * Hybrid storage configuration options.
+ */
+export interface HybridStorageOptions {
+    /**
+     * Write strategy
+     * - write-through: Write to both local and remote immediately
+     * - write-back: Write to local immediately, sync to remote later
+     * @default "write-through"
+     */
+    writeStrategy?: WriteStrategy;
+    /**
+     * Conflict resolution strategy
+     * - local: Local changes win
+     * - remote: Remote changes win
+     * - merge: Custom merge function (requires mergeFn)
+     * - error: Throw error on conflict
+     * @default "remote"
+     */
+    conflictResolution?: ConflictResolution;
+    /**
+     * Custom merge function for conflict resolution.
+     * Only used when conflictResolution is "merge".
+     *
+     * @param local - Local version
+     * @param remote - Remote version
+     * @returns Merged value
+     */
+    mergeFn?: <T>(local: T, remote: T) => T;
+    /**
+     * The key of a remote item, for the local cache. The default reads a string `id` field. Give
+     * a function for items with another key, for example `getSerializedKey` for procedure records.
+     */
+    keyOf?: (item: any) => string | undefined;
+    /**
+     * Automatic sync interval in milliseconds (for write-back mode).
+     * Set to 0 to disable automatic sync.
+     * @default 5000 (5 seconds)
+     */
+    syncInterval?: number;
+    /**
+     * Initialize by syncing from remote on construction.
+     * @default true
+     */
+    syncOnInit?: boolean;
+    /**
+     * Maximum offline operations to queue.
+     * @default 1000
+     */
+    maxOfflineOps?: number;
+    /**
+     * Enable offline operation queue.
+     * When remote is unavailable, operations are queued and retried.
+     * @default true
+     */
+    offlineQueue?: boolean;
+}
+/**
+ * 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, { collection: "users" });
+ * const hybrid = new HybridStorage(remote, {
+ *   writeStrategy: "write-through",
+ *   conflictResolution: "remote",
+ *   syncInterval: 5000
+ * });
+ *
+ * // Fast local reads
+ * const user = await hybrid.get("123"); // From cache, or from the remote on a miss
+ *
+ * // Writes go to both local and remote
+ * await hybrid.set("123", { name: "John" });
+ * ```
+ */
+export declare class HybridStorage<T> implements CollectionStorage<T> {
+    private local;
+    private remote;
+    private options;
+    private offlineOps;
+    private syncTimer;
+    private isOnline;
+    /** A counter of local writes for each id, so a sync does not restore an older remote value */
+    private readonly writeVersions;
+    private clearVersion;
+    /** The running sync: syncs run one at a time */
+    private syncChain;
+    private stats;
+    constructor(remote: CollectionStorage<T>, options?: HybridStorageOptions);
+    /**
+     * The local item, or else the remote item (which the cache then keeps). When the remote
+     * cannot answer, the storage is offline and the result is undefined.
+     */
+    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>>;
+    /**
+     * Sync all data from remote to local.
+     * Handles conflicts according to conflict resolution strategy.
+     *
+     * - Each remote item goes into the cache under `keyOf(item)`.
+     * - A local item that the remote does not have is removed, unless a queued local operation
+     *   changes it (the remote deleted it).
+     * - An id that a local write changed during the sync keeps the local value: the remote value
+     *   is older.
+     * - Syncs run one at a time.
+     */
+    syncFromRemote(): Promise<void>;
+    /**
+     * Sync all pending offline operations to remote.
+     * Processes queued operations in order. When one fails, it and the later operations stay in
+     * the queue: the operations that reached the remote are not sent again.
+     */
+    syncToRemote(): Promise<void>;
+    /**
+     * Force a full sync (both directions).
+     */
+    sync(): Promise<void>;
+    close(): Promise<void>;
+    getMetadata(): Promise<StorageMetadata>;
+    private pullRemote;
+    private pushQueue;
+    /** Run syncs one at a time. */
+    private serialize;
+    private localIds;
+    private bump;
+    private versionOf;
+    private hasPendingOp;
+    /**
+     * Resolve conflict between local and remote versions.
+     */
+    private resolveConflict;
+    /**
+     * Queue operation for later sync.
+     */
+    private queueOperation;
+    /**
+     * Execute a queued operation against remote storage.
+     */
+    private executeOperation;
+    /**
+     * Handle remote operation failure.
+     */
+    private handleRemoteFailure;
+    /**
+     * Start periodic background sync.
+     */
+    private startPeriodicSync;
+    /**
+     * Get current online status.
+     */
+    isRemoteOnline(): boolean;
+    /**
+     * Get pending offline operations count.
+     */
+    getPendingOpsCount(): number;
+}
+//# sourceMappingURL=hybrid.d.ts.map

package/dist/procedures/storage/hybrid.d.ts.map

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