@drakkar.software/starfish-client 1.4.1 → 1.6.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/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.d.ts

@@ -30,6 +30,26 @@ export interface CreateStarfishStoreOptions {
     devtools?: boolean | DevtoolsOptions;
     /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */
     produce?: <T>(base: T, recipe: (draft: T) => T | void) => T;
+    /**
+     * Called when remote data arrives via `pull()` — **not** called for local `set()` writes.
+     *
+     * Use this to restore domain stores after a pull without worrying about feedback loops.
+     * The callback fires **after** the Starfish store state is updated, so the store already
+     * reflects the new data when this runs.
+     *
+     * Replaces the manual `isRestoring` flag pattern:
+     * ```ts
+     * createStarfishStore({
+     *   name: "app",
+     *   syncManager,
+     *   onRemoteUpdate: (data) => {
+     *     taskStore.setState({ tasks: data.tasks as Task[] })
+     *     settingsStore.setState({ settings: data.settings as Settings })
+     *   },
+     * })
+     * ```
+     */
+    onRemoteUpdate?: (data: Record<string, unknown>) => void;
 }
 export type { DevtoolsOptions };
 export declare function createStarfishStore(options: CreateStarfishStoreOptions): StoreApi<StarfishStore>;
@@ -48,6 +68,22 @@ export declare function useStarfish(store: StoreApi<StarfishStore>): StarfishSto
 export declare function useStarfishData<T = Record<string, unknown>>(store: StoreApi<StarfishStore>, selector?: (data: Record<string, unknown>) => T): T;
 /** Use the derived sync status (synced | syncing | pending | error | offline). */
 export declare function useSyncStatus(store: StoreApi<StarfishStore>): SyncStatus;
+/**
+ * Subscribe to sync status changes outside of React.
+ *
+ * Framework-agnostic — works in React Native, Node.js, or anywhere hooks are unavailable.
+ * The callback is invoked immediately with the current status and then on every change.
+ *
+ * ```ts
+ * const unsub = subscribeSyncStatus(store, (status) => {
+ *   updateStatusBar(status)
+ * })
+ *
+ * // Later, to stop listening:
+ * unsub()
+ * ```
+ */
+export declare function subscribeSyncStatus(store: StoreApi<StarfishStore>, callback: (status: SyncStatus) => void): () => void;
 /** Sets up cross-tab sync for a Starfish store. Cleans up on unmount. */
 export declare function useCrossTabSync(store: StoreApi<StarfishStore>, name: string): void;
 /** Binds browser online/offline events to the store's setOnline action. Cleans up on unmount. */

package/dist/bindings/zustand.js

@@ -19,7 +19,11 @@ export function createStarfishStore(options) {
                 set({ syncing: true, error: null }, false, "pull/start");
                 try {
                     await syncManager.pull();
-                    set({ data: syncManager.getData(), syncing: false }, false, "pull/success");
+                    const newData = syncManager.getData();
+                    set({ data: newData, syncing: false }, false, "pull/success");
+                    // Fire after state update so domain stores can read the updated Starfish state if needed.
+                    // Calling set() inside onRemoteUpdate does NOT re-enter pull(), so no feedback loop.
+                    options.onRemoteUpdate?.(newData);
                 }
                 catch (err) {
                     set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "pull/error");
@@ -118,6 +122,32 @@ export function useStarfishData(store, selector) {
 export function useSyncStatus(store) {
     return useStore(store, deriveSyncStatus);
 }
+/**
+ * Subscribe to sync status changes outside of React.
+ *
+ * Framework-agnostic — works in React Native, Node.js, or anywhere hooks are unavailable.
+ * The callback is invoked immediately with the current status and then on every change.
+ *
+ * ```ts
+ * const unsub = subscribeSyncStatus(store, (status) => {
+ *   updateStatusBar(status)
+ * })
+ *
+ * // Later, to stop listening:
+ * unsub()
+ * ```
+ */
+export function subscribeSyncStatus(store, callback) {
+    let prev = deriveSyncStatus(store.getState());
+    callback(prev);
+    return store.subscribe((state) => {
+        const next = deriveSyncStatus(state);
+        if (next !== prev) {
+            prev = next;
+            callback(next);
+        }
+    });
+}
 /** Sets up cross-tab sync for a Starfish store. Cleans up on unmount. */
 export function useCrossTabSync(store, name) {
     useEffect(() => {
@@ -209,15 +239,9 @@ export function useSyncInit(config) {
             name: config.storeName ?? "sync",
             syncManager,
             storage: config.storage,
-        });
-        // Subscribe to data changes from pulls (not local sets)
-        let lastDataRef = newStore.getState().data;
-        const unsub = newStore.subscribe((state) => {
-            const data = state.data;
-            // 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) {
-                lastDataRef = data;
+            // onRemoteUpdate fires only for pull() results, never for local set() writes —
+            // so no isRestoring flag is needed.
+            onRemoteUpdate: (data) => {
                 try {
                     onDataRef.current?.(data);
                 }
@@ -226,16 +250,12 @@ export function useSyncInit(config) {
                         error: `onData failed: ${err instanceof Error ? err.message : String(err)}`,
                     });
                 }
-            }
-            else {
-                lastDataRef = data;
-            }
+            },
         });
         setStore(newStore);
         // Initial pull — errors are stored in state.error by the pull() action
         newStore.getState().pull().catch(() => { });
         return () => {
-            unsub();
             setStore(null);
         };
         // Intentionally depend on serializable config values, not the object reference

package/dist/debounced-sync.d.ts

@@ -0,0 +1,66 @@
+import type { StoreApi } from "zustand/vanilla";
+import type { StarfishStore } from "./bindings/zustand.js";
+export interface DebouncedSyncOptions {
+    /**
+     * How long to wait after the last `notify()` call before pushing (default: 2000 ms).
+     * Shorter values reduce latency; longer values batch more edits into a single push.
+     */
+    delayMs?: number;
+    /**
+     * Emit a warning when the estimated encrypted payload exceeds this byte count (default: 900 KB).
+     * The estimate multiplies the JSON size by 1.34 (base64 overhead for encrypted blobs).
+     * Set to `Infinity` to disable.
+     */
+    warnBytes?: number;
+    /**
+     * Block the push when the estimated encrypted payload exceeds this byte count (default: 1 MB).
+     * Prevents cryptic 413 errors from the server. Set to `Infinity` to disable.
+     */
+    maxBytes?: number;
+    /**
+     * Serialize store data to a sync document before pushing.
+     * Called inside the debounce timer, so it always captures the latest state.
+     * If omitted, `store.getState().data` is used as-is.
+     */
+    serialize?: (currentData: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Called when the estimated payload size exceeds `warnBytes` but is still below `maxBytes`.
+     * Use to show a warning in the UI.
+     */
+    onSizeWarning?: (estimatedBytes: number) => void;
+    /**
+     * Called when the estimated payload size exceeds `maxBytes`.
+     * The push is blocked. Use to alert the user that data needs to be pruned.
+     * If omitted, a console error is printed.
+     */
+    onSizeExceeded?: (estimatedBytes: number) => void;
+}
+export interface DebouncedSync {
+    /**
+     * Schedule a push. If called again within `delayMs`, the timer resets.
+     * Safe to call on every domain store mutation.
+     */
+    notify: () => void;
+    /** Cancel any pending debounced push. Does not affect an already-in-flight push. */
+    cancel: () => void;
+}
+/**
+ * Creates a debounced push helper that coalesces rapid mutations into a single sync.
+ *
+ * Designed to be called on every domain store mutation (e.g., every keystroke).
+ * The push is delayed by `delayMs` after the **last** call, so typing quickly
+ * results in one push, not one per character.
+ *
+ * Also estimates the encrypted payload size before pushing and warns / blocks
+ * if it approaches the server's body size limit.
+ *
+ * ```ts
+ * const { notify } = createDebouncedSync(starfishStore, {
+ *   serialize: () => ({ tasks: taskStore.getState().tasks }),
+ * })
+ *
+ * // Call on every domain store mutation:
+ * taskStore.subscribe(() => notify())
+ * ```
+ */
+export declare function createDebouncedSync(store: StoreApi<StarfishStore>, options?: DebouncedSyncOptions): DebouncedSync;

package/dist/debounced-sync.js

@@ -0,0 +1,65 @@
+// ── Implementation ────────────────────────────────────────────────────────────
+const DEFAULT_DELAY_MS = 2000;
+const DEFAULT_WARN_BYTES = 900 * 1024; // 900 KB
+const DEFAULT_MAX_BYTES = 1024 * 1024; // 1 MB
+/**
+ * Creates a debounced push helper that coalesces rapid mutations into a single sync.
+ *
+ * Designed to be called on every domain store mutation (e.g., every keystroke).
+ * The push is delayed by `delayMs` after the **last** call, so typing quickly
+ * results in one push, not one per character.
+ *
+ * Also estimates the encrypted payload size before pushing and warns / blocks
+ * if it approaches the server's body size limit.
+ *
+ * ```ts
+ * const { notify } = createDebouncedSync(starfishStore, {
+ *   serialize: () => ({ tasks: taskStore.getState().tasks }),
+ * })
+ *
+ * // Call on every domain store mutation:
+ * taskStore.subscribe(() => notify())
+ * ```
+ */
+export function createDebouncedSync(store, options = {}) {
+    const { delayMs = DEFAULT_DELAY_MS, warnBytes = DEFAULT_WARN_BYTES, maxBytes = DEFAULT_MAX_BYTES, serialize, onSizeWarning, onSizeExceeded, } = options;
+    let timer = null;
+    function cancel() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function notify() {
+        cancel();
+        timer = setTimeout(() => {
+            timer = null;
+            const current = store.getState().data;
+            const doc = serialize ? serialize(current) : current;
+            // Estimate encrypted payload size. AES-GCM output is similar to input size;
+            // base64 encoding adds ~33% overhead, plus a small IV/tag overhead.
+            const estimatedBytes = Math.ceil(JSON.stringify(doc).length * 1.34);
+            if (estimatedBytes > maxBytes) {
+                if (onSizeExceeded) {
+                    onSizeExceeded(estimatedBytes);
+                }
+                else {
+                    console.error(`[starfish] Push blocked: estimated payload ${(estimatedBytes / 1024).toFixed(0)} KB ` +
+                        `exceeds limit of ${(maxBytes / 1024).toFixed(0)} KB. Prune your data before syncing.`);
+                }
+                return;
+            }
+            if (estimatedBytes > warnBytes) {
+                if (onSizeWarning) {
+                    onSizeWarning(estimatedBytes);
+                }
+                else {
+                    console.warn(`[starfish] Payload approaching limit: estimated ${(estimatedBytes / 1024).toFixed(0)} KB ` +
+                        `(warn threshold: ${(warnBytes / 1024).toFixed(0)} KB).`);
+                }
+            }
+            store.getState().set(() => doc);
+        }, delayMs);
+    }
+    return { notify, cancel };
+}

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/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("");
+}