@sync-subscribe/client 0.3.2

package/dist/types.d.ts

@@ -0,0 +1,131 @@
+import type { SyncRecord, SyncPatch, SyncToken, SubscriptionFilter, Subscription, StreamEvent } from "@sync-subscribe/core";
+export type SubscriptionStatus = "pending_gap_fill" | "active";
+export interface ClientSubscriptionOptions {
+    filter: SubscriptionFilter;
+    /** Stable client-side name for this subscription. Used to persist and restore state across sessions. */
+    name?: string;
+    /**
+     * If provided, the new subscription replaces the existing one with this ID.
+     * Used locally only — no server call is made. Triggers gap/eviction analysis.
+     */
+    previousSubscriptionId?: string;
+}
+export interface ClientSubscription extends Subscription {
+    /** Stable client-side name, if one was given when subscribing. */
+    name?: string;
+    status?: SubscriptionStatus;
+    gapSubscriptionId?: string;
+}
+/** Subscription state persisted to the local store, keyed by name. */
+export interface PersistedSubscription extends Subscription {
+    name?: string;
+    /**
+     * Omitted or "active" — subscription participates in pull and stream normally.
+     * "pending_gap_fill" — a gap sub is in progress; only the gap sub is pulled,
+     * and this subscription is excluded from the stream until it transitions to active.
+     */
+    status?: SubscriptionStatus;
+    /**
+     * Set when status === "pending_gap_fill". The subscriptionId of the gap subscription
+     * that is filling in records not covered by any existing subscription.
+     */
+    gapSubscriptionId?: string;
+}
+/** One entry sent in a pull or stream request. key is echoed back in syncTokens responses. */
+export interface SyncSubscriptionRequest {
+    key: string;
+    filter: SubscriptionFilter;
+    syncToken: SyncToken;
+}
+/** Minimal HTTP transport interface — swap in fetch, axios, etc. */
+export interface SyncTransport {
+    /**
+     * Pull patches for all active subscriptions in a single request.
+     * Returns deduplicated patches and one sync token per affected subscription key.
+     */
+    pull(subscriptions: SyncSubscriptionRequest[]): Promise<{
+        patches: SyncPatch<SyncRecord>[];
+        syncTokens: Record<string, SyncToken>;
+    }>;
+    /**
+     * Push locally-mutated records to the server.
+     * Returns serverUpdatedAt on success so the client can stamp local copies.
+     */
+    push(records: SyncRecord[]): Promise<{
+        ok: true;
+        serverUpdatedAt: number;
+    } | {
+        conflict: true;
+        serverRecord: SyncRecord;
+    }>;
+    /**
+     * Optional POST-based SSE streaming for all active subscriptions.
+     * Returns a cleanup function that closes the connection.
+     */
+    stream?(subscriptions: SyncSubscriptionRequest[], onMessage: (event: StreamEvent) => void, onError?: (err: Error) => void): () => void;
+}
+/**
+ * Async interface for local record storage.
+ * Both InMemoryStore and IdbLocalStore implement this.
+ */
+export interface ILocalStore<T extends SyncRecord> {
+    /**
+     * Apply a batch of patches from the server.
+     * On upsert, copies `record.updatedAt` into `record.serverUpdatedAt` before storing
+     * (the server's clock is authoritative).
+     * Returns the patches that were actually applied (conflict resolution may drop some).
+     */
+    applyPatches(patches: SyncPatch<T>[]): Promise<SyncPatch<T>[]>;
+    write(record: T): Promise<void>;
+    getAll(): Promise<T[]>;
+    query(filter: SubscriptionFilter<T>): Promise<T[]>;
+    count(filter: SubscriptionFilter<T>): Promise<number>;
+    delete(fiter: SubscriptionFilter<T>): Promise<void>;
+    getById(recordId: string): Promise<T | undefined>;
+    /** Remove all records — called by SyncClient.reset(). */
+    clear(): Promise<void>;
+    /**
+     * Removes items from our local store that match the filter.
+     * Does not delete them from other stores/devices.
+     */
+    evict(evictFilter: SubscriptionFilter<T>): Promise<void>;
+    /**
+     * Scan local records matching filter, find the max (serverUpdatedAt, revisionCount, recordId),
+     * and return encodeSyncToken(that record). Returns EMPTY_SYNC_TOKEN if no records have
+     * serverUpdatedAt set (i.e. none have been confirmed by the server yet).
+     */
+    reconstructSyncToken(filter: SubscriptionFilter<T>): Promise<SyncToken>;
+    /**
+     * Stamp a server-authoritative timestamp on a local record after a successful push.
+     * This keeps reconstructSyncToken accurate without a full record rewrite.
+     */
+    setServerUpdatedAt(recordId: string, serverUpdatedAt: number): Promise<void>;
+    /** Persist the latest sync token for an unnamed subscription across sessions. */
+    setSyncToken(subscriptionId: string, token: SyncToken): Promise<void>;
+    getSyncToken(subscriptionId: string): Promise<SyncToken | undefined>;
+    /** Persist full subscription state under a stable client-side name (or subscriptionId). */
+    setSubscription(name: string, sub: PersistedSubscription): Promise<void>;
+    getSubscription(name: string): Promise<PersistedSubscription | undefined>;
+    getSubscriptionById(id: string): Promise<PersistedSubscription | undefined>;
+    removeSubscription(name: string): Promise<void>;
+    listSubscriptions(): Promise<PersistedSubscription[]>;
+    /** Remove all persisted subscriptions — called by SyncClient.reset(). */
+    clearSubscriptions(): Promise<void>;
+}
+/** Called whenever the local store changes due to incoming patches. */
+export type PatchListener<T extends SyncRecord> = (patches: SyncPatch<T>[]) => void;
+export interface QueryEntries<T extends SyncRecord> {
+    data: T[];
+    loading: boolean;
+}
+/**
+ * A reactive handle to a filtered view of the local store.
+ * Follows the Svelte store contract — subscribe(run) returns unsubscribe.
+ *
+ * `loading` is true until the first local read (or first pull for liveQuery) completes.
+ * Compatible with Svelte's `$store` syntax and React's `useSyncExternalStore`.
+ */
+export interface SyncQuery<T extends SyncRecord> {
+    subscribe(run: (value: QueryEntries<T>) => void, invalidate?: () => void): () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACZ,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,GAAG,QAAQ,CAAC;AAE/D,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,wGAAwG;IACxG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAsB,SAAQ,YAAY;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,8FAA8F;AAC9F,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,kBAAkB,CAAC;IAC3B,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,aAAa,EAAE,uBAAuB,EAAE,GAAG,OAAO,CAAC;QACtD,OAAO,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;QACjC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;KACvC,CAAC,CAAC;IAEH;;;OAGG;IACH,IAAI,CACF,OAAO,EAAE,UAAU,EAAE,GACpB,OAAO,CACN;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,GACrC;QAAE,QAAQ,EAAE,IAAI,CAAC;QAAC,YAAY,EAAE,UAAU,CAAA;KAAE,CAC/C,CAAC;IAEF;;;OAGG;IACH,MAAM,CAAC,CACL,aAAa,EAAE,uBAAuB,EAAE,EACxC,SAAS,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,EACvC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAC7B,MAAM,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,UAAU;IAC/C;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/D,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACvB,KAAK,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACnD,KAAK,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,MAAM,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAClD,yDAAyD;IACzD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;OAIG;IACH,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACxE;;;OAGG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,iFAAiF;IACjF,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IACrE,2FAA2F;IAC3F,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;IAC1E,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;IAC5E,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,iBAAiB,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IACtD,yEAAyE;IACzE,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,uEAAuE;AACvE,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,UAAU,IAAI,CAChD,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,KACpB,IAAI,CAAC;AAEV,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,UAAU;IAChD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,UAAU;IAC7C,SAAS,CACP,GAAG,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,EACrC,UAAU,CAAC,EAAE,MAAM,IAAI,GACtB,MAAM,IAAI,CAAC;CACf"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@sync-subscribe/client",
+  "version": "0.3.2",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@sync-subscribe/core": "0.3.2"
+  },
+  "devDependencies": {
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}