@drakkar.software/starfish-client 1.4.0 → 1.5.0

package/dist/background-sync.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Background Sync API integration for pending changes.
+ * Uses the Web Background Sync API to retry failed sync operations
+ * when connectivity is restored, even if the app is closed.
+ */
+export interface BackgroundSyncOptions {
+    /** Sync event tag. Default: "starfish-sync" */
+    tag?: string;
+}
+/** Check if the Background Sync API is supported in the current environment. */
+export declare function isBackgroundSyncSupported(): boolean;
+/**
+ * Register a background sync event with the active service worker.
+ * Returns true if registration succeeded, false if not supported or no active SW.
+ */
+export declare function registerBackgroundSync(opts?: BackgroundSyncOptions): Promise<boolean>;

package/dist/background-sync.js

@@ -0,0 +1,29 @@
+/**
+ * Background Sync API integration for pending changes.
+ * Uses the Web Background Sync API to retry failed sync operations
+ * when connectivity is restored, even if the app is closed.
+ */
+/** Check if the Background Sync API is supported in the current environment. */
+export function isBackgroundSyncSupported() {
+    return (typeof navigator !== "undefined" &&
+        "serviceWorker" in navigator &&
+        "SyncManager" in globalThis);
+}
+/**
+ * Register a background sync event with the active service worker.
+ * Returns true if registration succeeded, false if not supported or no active SW.
+ */
+export async function registerBackgroundSync(opts) {
+    if (!isBackgroundSyncSupported())
+        return false;
+    const tag = opts?.tag ?? "starfish-sync";
+    try {
+        const registration = await navigator.serviceWorker.ready;
+        // @ts-expect-error - SyncManager types may not be available
+        await registration.sync.register(tag);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/bindings/legend.js

@@ -18,7 +18,7 @@ export function createStarfishObservable(options) {
             state.dirty.set(false);
         }
         catch (err) {
-            state.error.set(err.message);
+            state.error.set(err instanceof Error ? err.message : String(err));
         }
         finally {
             state.syncing.set(false);
@@ -32,7 +32,7 @@ export function createStarfishObservable(options) {
             state.data.set(options.syncManager.getData());
         }
         catch (err) {
-            state.error.set(err.message);
+            state.error.set(err instanceof Error ? err.message : String(err));
         }
         finally {
             state.syncing.set(false);
@@ -48,16 +48,16 @@ export function createStarfishObservable(options) {
             state.dirty.set(true);
             state.error.set(null);
             if (state.online.get())
-                flush();
+                flush().catch(() => { });
         }
         catch (err) {
-            state.error.set(err.message);
+            state.error.set(err instanceof Error ? err.message : String(err));
         }
     };
     const setOnline = (online) => {
         state.online.set(online);
         if (online && state.dirty.get())
-            flush();
+            flush().catch(() => { });
     };
     return { state, pull, set, flush, setOnline };
 }

package/dist/bindings/suspense.d.ts

@@ -0,0 +1,25 @@
+/**
+ * React Suspense integration for Starfish sync data.
+ * Creates resources that throw Promises while loading (Suspense protocol).
+ */
+interface SuspenseResource<T> {
+    /** Read the resource value. Throws a Promise while pending (Suspense protocol). */
+    read(): T;
+}
+/**
+ * Create a Suspense-compatible resource from an async fetcher.
+ * The first call to `read()` triggers the fetch. While loading, `read()` throws
+ * a Promise (which React Suspense catches to show a fallback). Once resolved,
+ * `read()` returns the value synchronously.
+ *
+ * @example
+ * ```tsx
+ * const resource = createSuspenseResource(() => syncManager.pull())
+ * function MyComponent() {
+ *   const data = resource.read() // throws while loading, returns data when ready
+ *   return <div>{JSON.stringify(data)}</div>
+ * }
+ * ```
+ */
+export declare function createSuspenseResource<T>(fetcher: () => Promise<T>): SuspenseResource<T>;
+export {};

package/dist/bindings/suspense.js

@@ -0,0 +1,49 @@
+/**
+ * React Suspense integration for Starfish sync data.
+ * Creates resources that throw Promises while loading (Suspense protocol).
+ */
+/**
+ * Create a Suspense-compatible resource from an async fetcher.
+ * The first call to `read()` triggers the fetch. While loading, `read()` throws
+ * a Promise (which React Suspense catches to show a fallback). Once resolved,
+ * `read()` returns the value synchronously.
+ *
+ * @example
+ * ```tsx
+ * const resource = createSuspenseResource(() => syncManager.pull())
+ * function MyComponent() {
+ *   const data = resource.read() // throws while loading, returns data when ready
+ *   return <div>{JSON.stringify(data)}</div>
+ * }
+ * ```
+ */
+export function createSuspenseResource(fetcher) {
+    let status = "pending";
+    let result;
+    let error;
+    let promise = null;
+    function init() {
+        if (promise)
+            return promise;
+        promise = fetcher().then((value) => {
+            status = "resolved";
+            result = value;
+        }, (err) => {
+            status = "rejected";
+            error = err;
+        });
+        return promise;
+    }
+    return {
+        read() {
+            switch (status) {
+                case "pending":
+                    throw init();
+                case "resolved":
+                    return result;
+                case "rejected":
+                    throw error;
+            }
+        },
+    };
+}

package/dist/bindings/zustand.js

@@ -22,7 +22,7 @@ export function createStarfishStore(options) {
                     set({ data: syncManager.getData(), syncing: false }, false, "pull/success");
                 }
                 catch (err) {
-                    set({ syncing: false, error: err.message }, false, "pull/error");
+                    set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "pull/error");
                 }
             },
             set: (modifier) => {
@@ -32,10 +32,10 @@ export function createStarfishStore(options) {
                         : modifier(get().data);
                     set({ data: next, dirty: true, error: null }, false, "set");
                     if (get().online)
-                        get().flush();
+                        get().flush().catch(() => { });
                 }
                 catch (err) {
-                    set({ error: err.message }, false, "set/error");
+                    set({ error: err instanceof Error ? err.message : String(err) }, false, "set/error");
                 }
             },
             restore: (data) => {
@@ -50,13 +50,13 @@ export function createStarfishStore(options) {
                     set({ data: syncManager.getData(), syncing: false, dirty: false }, false, "flush/success");
                 }
                 catch (err) {
-                    set({ syncing: false, error: err.message }, false, "flush/error");
+                    set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "flush/error");
                 }
             },
             setOnline: (online) => {
                 set({ online }, false, "setOnline");
                 if (online && get().dirty)
-                    get().flush();
+                    get().flush().catch(() => { });
             },
         };
     };
@@ -217,15 +217,23 @@ export function useSyncInit(config) {
             // Only call onData when data changes and store is not dirty
             // (dirty = false means data came from a pull, not a local set)
             if (data !== lastDataRef && !state.dirty) {
-                onDataRef.current?.(data);
+                lastDataRef = data;
+                try {
+                    onDataRef.current?.(data);
+                }
+                catch (err) {
+                    newStore.setState({
+                        error: `onData failed: ${err instanceof Error ? err.message : String(err)}`,
+                    });
+                }
+            }
+            else {
+                lastDataRef = data;
             }
-            lastDataRef = data;
         });
         setStore(newStore);
-        // Initial pull — errors are stored in state.error; log if logger provided
-        newStore.getState().pull().catch((err) => {
-            config.logger?.pullError(config.storeName ?? "sync", err.message);
-        });
+        // Initial pull — errors are stored in state.error by the pull() action
+        newStore.getState().pull().catch(() => { });
         return () => {
             unsub();
             setStore(null);

package/dist/broadcast.js

@@ -7,8 +7,11 @@ export function setupBroadcastSync(store, name) {
     const channel = new BroadcastChannel(`starfish-${name}`);
     let lastReceivedData = null;
     channel.onmessage = (event) => {
-        lastReceivedData = event.data.data;
-        store.setState({ data: event.data.data, dirty: event.data.dirty });
+        const payload = event.data;
+        if (!payload || typeof payload !== "object" || !payload.data || typeof payload.data !== "object")
+            return;
+        lastReceivedData = payload.data;
+        store.setState({ data: payload.data, dirty: !!payload.dirty });
     };
     const unsub = store.subscribe((state, prev) => {
         if (state.data === lastReceivedData)
@@ -43,8 +46,10 @@ export function setupStorageFallback(store, name) {
         catch {
             return;
         }
+        if (!payload || typeof payload !== "object" || !payload.data || typeof payload.data !== "object")
+            return;
         lastReceivedData = payload.data;
-        store.setState({ data: payload.data, dirty: payload.dirty });
+        store.setState({ data: payload.data, dirty: !!payload.dirty });
     };
     globalThis.addEventListener("storage", onStorage);
     const unsub = store.subscribe((state, prev) => {

package/dist/client.d.ts

@@ -3,7 +3,8 @@ import type { StarfishClientOptions } from "./types.js";
 /** Result of pulling a binary blob from the server. */
 export interface BlobPullResult {
     data: ArrayBuffer;
-    hash: string;
+    /** Content hash from the ETag header. Null if the server didn't include an ETag. */
+    hash: string | null;
     contentType: string;
 }
 /** Result of pushing a binary blob to the server. */

package/dist/client.js

@@ -82,7 +82,7 @@ export class StarfishClient {
         if (!res.ok) {
             throw new StarfishHttpError(res.status, await res.text());
         }
-        const etag = res.headers.get("ETag")?.replace(/"/g, "") ?? "";
+        const etag = res.headers.get("ETag")?.replace(/"/g, "") ?? null;
         const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
         const data = await res.arrayBuffer();
         return { data, hash: etag, contentType };

package/dist/dedup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Request deduplication: prevents multiple concurrent identical GET requests.
+ * If a GET request is in-flight for a URL, subsequent identical GET requests
+ * return the same Promise. POST/PUT/DELETE/PATCH are never deduped.
+ */
+export declare function createDedupFetch(baseFetch?: typeof globalThis.fetch): typeof globalThis.fetch;

package/dist/dedup.js

@@ -0,0 +1,35 @@
+/**
+ * Request deduplication: prevents multiple concurrent identical GET requests.
+ * If a GET request is in-flight for a URL, subsequent identical GET requests
+ * return the same Promise. POST/PUT/DELETE/PATCH are never deduped.
+ */
+export function createDedupFetch(baseFetch = globalThis.fetch.bind(globalThis)) {
+    const inflightGets = new Map();
+    return (async (input, init) => {
+        const method = (init?.method ?? "GET").toUpperCase();
+        // Only dedup GET requests
+        if (method !== "GET") {
+            return baseFetch(input, init);
+        }
+        const url = typeof input === "string"
+            ? input
+            : input instanceof URL
+                ? input.toString()
+                : input.url;
+        const existing = inflightGets.get(url);
+        if (existing) {
+            // Return a clone — the original is reserved for cloning only
+            return existing.then((res) => res.clone());
+        }
+        // Store a promise that resolves to a response we keep solely for cloning.
+        // The first caller also gets a clone, ensuring the "master" body is never consumed.
+        const promise = baseFetch(input, init)
+            .then((res) => res)
+            .finally(() => {
+            inflightGets.delete(url);
+        });
+        inflightGets.set(url, promise);
+        // First caller also gets a clone so the cached response body stays unconsumed
+        return promise.then((res) => res.clone());
+    });
+}

package/dist/export.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Data export/import helpers for Starfish sync data.
+ * Supports JSON and CSV formats.
+ */
+export interface ExportOptions {
+    /** Output format. Default: "json" */
+    format?: "json" | "csv";
+    /** Pretty-print JSON output. Default: false */
+    pretty?: boolean;
+}
+/**
+ * Export data to a string representation.
+ * JSON: serializes the full object.
+ * CSV: flattens top-level keys into columns. Array values are JSON-encoded.
+ */
+export declare function exportData(data: Record<string, unknown>, opts?: ExportOptions): string;
+/**
+ * Import data from a string representation.
+ */
+export declare function importData(raw: string, format?: "json" | "csv"): Record<string, unknown>;
+/**
+ * Export data to a Blob suitable for download.
+ */
+export declare function exportToBlob(data: Record<string, unknown>, opts?: ExportOptions): Blob;

package/dist/export.js

@@ -0,0 +1,115 @@
+/**
+ * Data export/import helpers for Starfish sync data.
+ * Supports JSON and CSV formats.
+ */
+/**
+ * Export data to a string representation.
+ * JSON: serializes the full object.
+ * CSV: flattens top-level keys into columns. Array values are JSON-encoded.
+ */
+export function exportData(data, opts) {
+    const format = opts?.format ?? "json";
+    if (format === "json") {
+        return opts?.pretty
+            ? JSON.stringify(data, null, 2)
+            : JSON.stringify(data);
+    }
+    // CSV export: each top-level key becomes a column
+    return toCsv(data);
+}
+/**
+ * Import data from a string representation.
+ */
+export function importData(raw, format = "json") {
+    if (format === "json") {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("Expected a JSON object");
+        }
+        return parsed;
+    }
+    return fromCsv(raw);
+}
+/**
+ * Export data to a Blob suitable for download.
+ */
+export function exportToBlob(data, opts) {
+    const format = opts?.format ?? "json";
+    const content = exportData(data, opts);
+    const mimeType = format === "csv" ? "text/csv;charset=utf-8" : "application/json;charset=utf-8";
+    return new Blob([content], { type: mimeType });
+}
+function toCsv(data) {
+    const keys = Object.keys(data);
+    const header = keys.map(escapeCsvField).join(",");
+    const values = keys.map((k) => {
+        const v = data[k];
+        if (v === null || v === undefined)
+            return "";
+        if (typeof v === "object")
+            return escapeCsvField(JSON.stringify(v));
+        return escapeCsvField(String(v));
+    });
+    return `${header}\n${values.join(",")}`;
+}
+function fromCsv(raw) {
+    const lines = raw.trim().split("\n");
+    if (lines.length < 2) {
+        throw new Error("CSV must have at least a header row and a data row");
+    }
+    const headers = parseCsvLine(lines[0]);
+    const values = parseCsvLine(lines[1]);
+    const result = {};
+    for (let i = 0; i < headers.length; i++) {
+        const key = headers[i];
+        const val = values[i] ?? "";
+        // Try to parse JSON values
+        try {
+            result[key] = JSON.parse(val);
+        }
+        catch {
+            result[key] = val;
+        }
+    }
+    return result;
+}
+function escapeCsvField(field) {
+    if (field.includes(",") || field.includes('"') || field.includes("\n")) {
+        return `"${field.replace(/"/g, '""')}"`;
+    }
+    return field;
+}
+function parseCsvLine(line) {
+    const result = [];
+    let current = "";
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"' && line[i + 1] === '"') {
+                current += '"';
+                i++;
+            }
+            else if (ch === '"') {
+                inQuotes = false;
+            }
+            else {
+                current += ch;
+            }
+        }
+        else {
+            if (ch === '"') {
+                inQuotes = true;
+            }
+            else if (ch === ",") {
+                result.push(current);
+                current = "";
+            }
+            else {
+                current += ch;
+            }
+        }
+    }
+    result.push(current);
+    return result;
+}

package/dist/fetch.js

@@ -2,6 +2,10 @@
 export function classifyError(err) {
     if (err instanceof Response || (err && typeof err === "object" && "status" in err)) {
         const status = err.status;
+        if (typeof status !== "number" || isNaN(status))
+            return "unknown";
+        if (status === 0)
+            return "network";
         if (status === 401 || status === 403)
             return "auth";
         if (status === 409)
@@ -35,11 +39,11 @@ export function createRetryFetch(options) {
                 const category = classifyError(res);
                 if (category !== "rate-limited" && category !== "server")
                     return res;
-                const retryAfter = res.headers.get("Retry-After");
+                const retryAfter = res.headers.get("Retry-After")?.trim();
                 let delay;
                 if (retryAfter) {
                     const seconds = Number(retryAfter);
-                    if (!isNaN(seconds)) {
+                    if (retryAfter !== "" && !isNaN(seconds)) {
                         delay = Math.min(seconds * 1000, maxDelay);
                     }
                     else {
@@ -115,15 +119,20 @@ export function createCompressedFetch(inner) {
         const bodyText = typeof init.body === "string" ? init.body : null;
         if (!bodyText)
             return baseFetch(input, init);
-        const stream = new Blob([bodyText]).stream().pipeThrough(new CompressionStream("gzip"));
-        const compressed = await new Response(stream).arrayBuffer();
-        const normalized = Object.fromEntries(new Headers(init.headers).entries());
-        normalized["content-encoding"] = "gzip";
-        return baseFetch(input, {
-            ...init,
-            body: compressed,
-            headers: normalized,
-        });
+        try {
+            const stream = new Blob([bodyText]).stream().pipeThrough(new CompressionStream("gzip"));
+            const compressed = await new Response(stream).arrayBuffer();
+            const normalized = Object.fromEntries(new Headers(init.headers).entries());
+            normalized["content-encoding"] = "gzip";
+            return baseFetch(input, {
+                ...init,
+                body: compressed,
+                headers: normalized,
+            });
+        }
+        catch {
+            return baseFetch(input, init);
+        }
     };
 }
 /**
@@ -135,16 +144,17 @@ export function createResilientFetch(retryOptions, breakerOptions) {
     const retryFetch = createRetryFetch(retryOptions);
     const resilientFetch = async (input, init) => {
         if (breaker.isOpen()) {
-            throw new Error(`Circuit breaker is open (${breaker.getState()}, cooldown ${breakerOptions?.cooldownMs ?? 30_000}ms)`);
+            const cooldown = Math.ceil((breakerOptions?.cooldownMs ?? 30_000) / 1000);
+            throw new Error(`Request blocked: too many consecutive failures. Retry in ${cooldown}s.`);
         }
         try {
             const res = await retryFetch(input, init);
-            if (res.ok) {
-                breaker.recordSuccess();
-            }
-            else if (res.status >= 500) {
+            if (res.status >= 500) {
                 breaker.recordFailure();
             }
+            else {
+                breaker.recordSuccess();
+            }
             return res;
         }
         catch (err) {

package/dist/hash.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Deterministic JSON serialization with sorted keys (recursive).
+ * Must produce identical output to the server's stableStringify.
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * Compute SHA-256 hex digest of the stable-stringified data.
+ * Works in both browser (crypto.subtle) and Node.js environments.
+ */
+export declare function computeHash(data: Record<string, unknown>): Promise<string>;

package/dist/hash.js

@@ -0,0 +1,34 @@
+import { getCrypto } from "./platform.js";
+/**
+ * Deterministic JSON serialization with sorted keys (recursive).
+ * Must produce identical output to the server's stableStringify.
+ */
+export function stableStringify(value) {
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value === "boolean" || typeof value === "number")
+        return JSON.stringify(value);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map(v => stableStringify(v)).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const pairs = keys.map(k => JSON.stringify(k) + ":" + stableStringify(obj[k]));
+        return "{" + pairs.join(",") + "}";
+    }
+    return "null";
+}
+/**
+ * Compute SHA-256 hex digest of the stable-stringified data.
+ * Works in both browser (crypto.subtle) and Node.js environments.
+ */
+export async function computeHash(data) {
+    const encoded = new TextEncoder().encode(stableStringify(data));
+    const buf = await getCrypto().subtle.digest("SHA-256", encoded);
+    return Array.from(new Uint8Array(buf))
+        .map(b => b.toString(16).padStart(2, "0"))
+        .join("");
+}

package/dist/history.d.ts

@@ -16,7 +16,7 @@ export declare class SnapshotHistory {
     constructor(options?: SnapshotHistoryOptions);
     /** Take a labeled snapshot of the given data. */
     take(label: string, data: Record<string, unknown>): void;
-    /** Restore data from a snapshot at the given index. Returns undefined if index is invalid. */
+    /** Restore data from a snapshot at the given index. Returns undefined if index is invalid or data is corrupt. */
     restore(index: number): Record<string, unknown> | undefined;
     /** List available snapshots (metadata only, no data payload). */
     list(): Array<{

package/dist/history.js

@@ -8,8 +8,11 @@ export class SnapshotHistory {
         if (this.storageKey) {
             try {
                 const raw = localStorage.getItem(this.storageKey);
-                if (raw)
-                    this.snapshots = JSON.parse(raw);
+                if (raw) {
+                    const parsed = JSON.parse(raw);
+                    if (Array.isArray(parsed))
+                        this.snapshots = parsed;
+                }
             }
             catch { /* corrupted or unavailable — start fresh */ }
         }
@@ -26,12 +29,17 @@ export class SnapshotHistory {
         }
         this.persist();
     }
-    /** Restore data from a snapshot at the given index. Returns undefined if index is invalid. */
+    /** Restore data from a snapshot at the given index. Returns undefined if index is invalid or data is corrupt. */
     restore(index) {
         const snapshot = this.snapshots[index];
         if (!snapshot)
             return undefined;
-        return JSON.parse(snapshot.data);
+        try {
+            return JSON.parse(snapshot.data);
+        }
+        catch {
+            return undefined;
+        }
     }
     /** List available snapshots (metadata only, no data payload). */
     list() {

package/dist/index.d.ts

@@ -10,16 +10,27 @@ export { createEncryptor, ENCRYPTED_KEY } from "./crypto.js";
 export type { Encryptor } from "./crypto.js";
 export { ConflictError, StarfishHttpError, } from "./types.js";
 export type { StarfishClientOptions, AuthProvider, ConflictResolver, } from "./types.js";
-export { consoleSyncLogger, noopSyncLogger } from "./logger.js";
-export type { SyncLogger } from "./logger.js";
+export { consoleSyncLogger, noopSyncLogger, createMetricsCollector } from "./logger.js";
+export type { SyncLogger, SyncMetrics, MetricsCollector } from "./logger.js";
 export { createMigrator } from "./migrate.js";
 export type { MigrationFn, MigrationConfig } from "./migrate.js";
 export { ValidationError, createSchemaValidator } from "./validate.js";
 export type { Validator, ValidationResult } from "./validate.js";
 export { classifyError } from "./fetch.js";
 export type { ErrorCategory } from "./fetch.js";
-export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, } from "./resolvers.js";
+export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, withConflictMeta, } from "./resolvers.js";
+export type { ConflictMeta, ConflictResolverWithMeta } from "./resolvers.js";
 export { SnapshotHistory } from "./history.js";
 export type { Snapshot, SnapshotHistoryOptions } from "./history.js";
 export { startPolling, startAdaptivePolling } from "./polling.js";
 export type { PollableState, AdaptivePollingOptions, AdaptivePollingControls } from "./polling.js";
+export { createDedupFetch } from "./dedup.js";
+export { createIndexedDBStorage } from "./storage/indexeddb.js";
+export type { IndexedDBStorageOptions, AsyncStateStorage } from "./storage/indexeddb.js";
+export { exportData, importData, exportToBlob } from "./export.js";
+export type { ExportOptions } from "./export.js";
+export { isBackgroundSyncSupported, registerBackgroundSync } from "./background-sync.js";
+export type { BackgroundSyncOptions } from "./background-sync.js";
+export { isServiceWorkerSupported, registerServiceWorker, unregisterServiceWorkers } from "./service-worker.js";
+export type { ServiceWorkerOptions } from "./service-worker.js";
+export { createSuspenseResource } from "./bindings/suspense.js";