@procedures/client 0.0.0-stage → 0.1.0

package/dist/collections/interfaces/set.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Set interfaces that mirror Java's Set interface hierarchy.
+ *
+ * Sets are collections that contain no duplicate elements.
+ * They provide efficient membership testing.
+ */
+import type { Collection, ReadonlyCollection } from "./collection.js";
+import type { Compare } from "../core/traits.js";
+/**
+ * ReadonlySet<T> - Readonly set with no duplicates.
+ */
+export interface ReadonlySet<T> extends ReadonlyCollection<T> {
+    /**
+     * Returns true if this set contains the specified element.
+     */
+    contains(element: T): boolean;
+    /**
+     * Returns true if this set contains all elements in the specified collection.
+     */
+    containsAll(other: Iterable<T>): boolean;
+}
+/**
+ * Set<T> - Mutable set with no duplicates.
+ *
+ * Mirrors java.util.Set.
+ * Elements are unique based on the set's equality function.
+ */
+export interface Set<T> extends ReadonlySet<T>, Collection<T> {
+    /**
+     * Adds the specified element to this set if it is not already present.
+     *
+     * @returns true if this set did not already contain the element
+     */
+    add(element: T): boolean;
+    /**
+     * Removes the specified element from this set if it is present.
+     *
+     * @returns true if this set contained the element
+     */
+    remove(element: T): boolean;
+    /**
+     * Adds all elements in the specified collection to this set.
+     * This is a union operation.
+     *
+     * @returns true if this set changed
+     */
+    addAll(other: Iterable<T>): boolean;
+    /**
+     * Removes from this set all of its elements that are contained in the specified collection.
+     * This is a difference operation.
+     *
+     * @returns true if this set changed
+     */
+    removeAll(other: Iterable<T>): boolean;
+    /**
+     * Retains only the elements in this set that are contained in the specified collection.
+     * This is an intersection operation.
+     *
+     * @returns true if this set changed
+     */
+    retainAll(other: Iterable<T>): boolean;
+}
+/**
+ * SortedSet<T> - Set that maintains elements in sorted order.
+ *
+ * Mirrors java.util.SortedSet.
+ */
+export interface SortedSet<T> extends Set<T> {
+    /**
+     * Returns the comparator used to order elements in this set.
+     */
+    readonly comparator: Compare<T>;
+    /**
+     * Returns the first (lowest) element in this set.
+     *
+     * @throws Error if set is empty
+     */
+    first(): T;
+    /**
+     * Returns the last (highest) element in this set.
+     *
+     * @throws Error if set is empty
+     */
+    last(): T;
+    /**
+     * Returns a view of the portion of this set whose elements are strictly less than toElement.
+     */
+    headSet(toElement: T): SortedSet<T>;
+    /**
+     * Returns a view of the portion of this set whose elements are greater than or equal to fromElement.
+     */
+    tailSet(fromElement: T): SortedSet<T>;
+    /**
+     * Returns a view of the portion of this set whose elements range from fromElement to toElement.
+     */
+    subSet(fromElement: T, toElement: T): SortedSet<T>;
+}
+/**
+ * NavigableSet<T> - Extended sorted set with navigation methods.
+ *
+ * Mirrors java.util.NavigableSet.
+ */
+export interface NavigableSet<T> extends SortedSet<T> {
+    /**
+     * Returns the greatest element less than or equal to the given element, or undefined if none.
+     */
+    floor(element: T): T | undefined;
+    /**
+     * Returns the least element greater than or equal to the given element, or undefined if none.
+     */
+    ceiling(element: T): T | undefined;
+    /**
+     * Returns the greatest element strictly less than the given element, or undefined if none.
+     */
+    lower(element: T): T | undefined;
+    /**
+     * Returns the least element strictly greater than the given element, or undefined if none.
+     */
+    higher(element: T): T | undefined;
+    /**
+     * Retrieves and removes the first (lowest) element, or returns undefined if empty.
+     */
+    pollFirst(): T | undefined;
+    /**
+     * Retrieves and removes the last (highest) element, or returns undefined if empty.
+     */
+    pollLast(): T | undefined;
+    /**
+     * Returns a reverse order view of this set.
+     */
+    descendingSet(): NavigableSet<T>;
+    /**
+     * Returns a reverse order iterator over the elements in this set.
+     */
+    descendingIterator(): Iterator<T>;
+}
+//# sourceMappingURL=set.d.ts.map

package/dist/collections/interfaces/set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../../src/collections/interfaces/set.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,CAAE,SAAQ,kBAAkB,CAAC,CAAC,CAAC;IAC3D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC;IAE9B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAC3D;;;;OAIG;IACH,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC;IAEzB;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC;IAE5B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAEpC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAEvC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,CAAE,SAAQ,GAAG,CAAC,CAAC,CAAC;IAC1C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEhC;;;;OAIG;IACH,KAAK,IAAI,CAAC,CAAC;IAEX;;;;OAIG;IACH,IAAI,IAAI,CAAC,CAAC;IAEV;;OAEG;IACH,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAEpC;;OAEG;IACH,OAAO,CAAC,WAAW,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAEtC;;OAEG;IACH,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,CAAE,SAAQ,SAAS,CAAC,CAAC,CAAC;IACnD;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAEjC;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAEnC;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAEjC;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAElC;;OAEG;IACH,SAAS,IAAI,CAAC,GAAG,SAAS,CAAC;IAE3B;;OAEG;IACH,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC;IAE1B;;OAEG;IACH,aAAa,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IAEjC;;OAEG;IACH,kBAAkB,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;CACnC"}

package/dist/collections/interfaces/set.js

@@ -0,0 +1,8 @@
+/**
+ * Set interfaces that mirror Java's Set interface hierarchy.
+ *
+ * Sets are collections that contain no duplicate elements.
+ * They provide efficient membership testing.
+ */
+export {};
+//# sourceMappingURL=set.js.map

package/dist/collections/interfaces/set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set.js","sourceRoot":"","sources":["../../../src/collections/interfaces/set.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

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

@@ -0,0 +1,109 @@
+/**
+ * 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 "./interface.js";
+import type { Client } from "../../client/client.js";
+/**
+ * API storage configuration options.
+ */
+export interface ApiStorageOptions {
+    /**
+     * Service name for RPC calls
+     * @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
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Enable automatic retry on failures
+     * @default true
+     */
+    retry?: boolean;
+    /**
+     * AbortSignal for cancelling requests
+     */
+    signal?: AbortSignal;
+}
+/**
+ * API storage backed by universal client.
+ *
+ * Maps collection operations to RPC calls:
+ * - get(id) → client.call({ service, operation: "get" }, { id })
+ * - set(id, value) → client.call({ service, operation: "set" }, { id, value })
+ * - etc.
+ *
+ * Features:
+ * - Remote persistence via any transport (HTTP, WebSocket, gRPC)
+ * - Automatic retry and timeout (via client middleware)
+ * - Type-safe with full TypeScript inference
+ * - Async operations (all return Promises)
+ *
+ * @example
+ * ```typescript
+ * // Create API storage
+ * const client = new Client({
+ *   transport: new HttpTransport({ baseUrl: "https://api.example.com" })
+ * });
+ *
+ * const storage = new ApiStorage(client, { service: "users" });
+ *
+ * // Use with collection
+ * const users = createCollection(storage);
+ *
+ * // Operations are automatically sent to server
+ * await users.set("123", { name: "John" });
+ * const user = await users.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 RPC call via universal client.
+     */
+    private call;
+}
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/collections/storage/api.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGrD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;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;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,iBAAiB,CAAC,CAAC,CAAC;IACxD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAOb;gBAEU,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB;IA6BhD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAOvC,MAAM,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAKtB,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAanD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOjC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IASvB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlD,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ3C,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAkBhD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAkB7C;;OAEG;YACW,IAAI;CAkCnB"}

package/dist/collections/storage/api.js

@@ -0,0 +1,182 @@
+/**
+ * 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!
+ */
+/**
+ * API storage backed by universal client.
+ *
+ * Maps collection operations to RPC calls:
+ * - get(id) → client.call({ service, operation: "get" }, { id })
+ * - set(id, value) → client.call({ service, operation: "set" }, { id, value })
+ * - etc.
+ *
+ * Features:
+ * - Remote persistence via any transport (HTTP, WebSocket, gRPC)
+ * - Automatic retry and timeout (via client middleware)
+ * - Type-safe with full TypeScript inference
+ * - Async operations (all return Promises)
+ *
+ * @example
+ * ```typescript
+ * // Create API storage
+ * const client = new Client({
+ *   transport: new HttpTransport({ baseUrl: "https://api.example.com" })
+ * });
+ *
+ * const storage = new ApiStorage(client, { service: "users" });
+ *
+ * // Use with collection
+ * const users = createCollection(storage);
+ *
+ * // Operations are automatically sent to server
+ * await users.set("123", { name: "John" });
+ * const user = await users.get("123"); // Fetched from server
+ * ```
+ */
+export class ApiStorage {
+    client;
+    options;
+    constructor(client, options) {
+        this.client = client;
+        this.options = {
+            service: 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,
+            retry: options.retry ?? true,
+            ...(options.signal !== undefined && { signal: options.signal }),
+        };
+    }
+    //
+    // ═══ Read Operations ═══
+    //
+    async get(id) {
+        const response = await this.call("get", {
+            id,
+        });
+        return response.data ?? undefined;
+    }
+    async getAll() {
+        const response = await this.call("getAll", {});
+        return response.data;
+    }
+    async find(predicate) {
+        // Note: Predicate functions can't be serialized over network
+        // Options:
+        // 1. Fetch all and filter client-side (simple but inefficient)
+        // 2. Use query language (e.g., MongoDB query, GraphQL)
+        // 3. Pre-defined server-side filters
+        // For now: Fetch all and filter client-side
+        // TODO: Consider adding query language support
+        const all = await this.getAll();
+        return all.filter(predicate);
+    }
+    async has(id) {
+        const response = await this.call("has", {
+            id,
+        });
+        return response.data;
+    }
+    async size() {
+        const response = await this.call("size", {});
+        return response.data;
+    }
+    //
+    // ═══ Write Operations ═══
+    //
+    async set(id, value) {
+        await this.call("set", {
+            id,
+            value,
+        });
+    }
+    async delete(id) {
+        const response = await this.call("delete", { id });
+        return response.data;
+    }
+    async clear() {
+        await this.call("clear", {});
+    }
+    //
+    // ═══ Bulk Operations ═══
+    //
+    async setBatch(items) {
+        await this.call("setBatch", { items });
+    }
+    async deleteBatch(ids) {
+        const response = await this.call("deleteBatch", { ids });
+        return response.data;
+    }
+    async getBatch(ids) {
+        const response = await this.call("getBatch", { ids });
+        // Convert object to Map
+        const result = new Map();
+        for (const [id, value] of Object.entries(response.data)) {
+            result.set(id, value);
+        }
+        return result;
+    }
+    //
+    // ═══ Lifecycle & Metadata ═══
+    //
+    async close() {
+        // Close underlying client transport
+        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 RPC call via universal client.
+     */
+    async call(operation, payload) {
+        const operationName = this.options.operations?.[operation] ?? operation;
+        const method = {
+            service: this.options.service,
+            operation: operationName,
+            ...(this.options.version !== undefined && { version: this.options.version }),
+        };
+        const metadata = {};
+        if (this.options.timeout) {
+            metadata["timeout"] = {
+                overall: this.options.timeout,
+            };
+        }
+        if (this.options.signal) {
+            metadata["signal"] = this.options.signal;
+        }
+        // Call via universal client (uses configured transport and middleware)
+        const response = await this.client.call(method, payload, metadata);
+        return response;
+    }
+}
+//# sourceMappingURL=api.js.map

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

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

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

@@ -0,0 +1,164 @@
+/**
+ * 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 type { CollectionStorage, StorageMetadata } from "./interface.js";
+import type { ApiStorage } from "./api.js";
+/**
+ * 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;
+    /**
+     * 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, { 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 declare class HybridStorage<T> implements CollectionStorage<T> {
+    private local;
+    private remote;
+    private options;
+    private offlineOps;
+    private syncTimer;
+    private isOnline;
+    private stats;
+    constructor(remote: ApiStorage<T>, options?: HybridStorageOptions);
+    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.
+     */
+    syncFromRemote(): Promise<void>;
+    /**
+     * Sync all pending offline operations to remote.
+     * Processes queued operations in order.
+     */
+    syncToRemote(): Promise<void>;
+    /**
+     * Force a full sync (both directions).
+     */
+    sync(): Promise<void>;
+    close(): Promise<void>;
+    getMetadata(): Promise<StorageMetadata>;
+    /**
+     * 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/collections/storage/hybrid.d.ts.map

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