@drakkar.software/starfish-client 3.0.0-alpha.0 → 3.0.0-alpha.2

package/dist/logger.js

@@ -0,0 +1,80 @@
+/** Console-based sync logger with structured output. */
+export const consoleSyncLogger = {
+    pullStart: (s) => console.log(`[starfish:${s}] pull started`),
+    pullSuccess: (s, ms, m) => {
+        let msg = `[starfish:${s}] pull OK (${ms}ms)`;
+        if (m?.bytesTransferred)
+            msg += ` ${m.bytesTransferred}B`;
+        if (m?.cacheHit)
+            msg += ` (cache hit)`;
+        console.log(msg);
+    },
+    pullError: (s, err) => console.error(`[starfish:${s}] pull failed: ${err}`),
+    pushStart: (s) => console.log(`[starfish:${s}] push started`),
+    pushSuccess: (s, ms, m) => {
+        let msg = `[starfish:${s}] push OK (${ms}ms)`;
+        if (m?.bytesTransferred)
+            msg += ` ${m.bytesTransferred}B`;
+        console.log(msg);
+    },
+    pushError: (s, err) => console.error(`[starfish:${s}] push failed: ${err}`),
+    conflict: (s, n) => console.warn(`[starfish:${s}] conflict (attempt ${n})`),
+};
+/** Silent sync logger (no output). */
+export const noopSyncLogger = {
+    pullStart: () => { },
+    pullSuccess: () => { },
+    pullError: () => { },
+    pushStart: () => { },
+    pushSuccess: () => { },
+    pushError: () => { },
+    conflict: () => { },
+};
+/** Create a metrics collector that accumulates sync statistics. */
+export function createMetricsCollector() {
+    const stores = new Map();
+    function ensureStore(name) {
+        let s = stores.get(name);
+        if (!s) {
+            s = { totalPulls: 0, totalPushes: 0, totalDurationMs: 0, totalBytes: 0, totalConflicts: 0 };
+            stores.set(name, s);
+        }
+        return s;
+    }
+    return {
+        recordPull(name, durationMs, metrics) {
+            const s = ensureStore(name);
+            s.totalPulls++;
+            s.totalDurationMs += durationMs;
+            if (metrics?.bytesTransferred)
+                s.totalBytes += metrics.bytesTransferred;
+        },
+        recordPush(name, durationMs, metrics) {
+            const s = ensureStore(name);
+            s.totalPushes++;
+            s.totalDurationMs += durationMs;
+            if (metrics?.bytesTransferred)
+                s.totalBytes += metrics.bytesTransferred;
+        },
+        recordConflict(name) {
+            ensureStore(name).totalConflicts++;
+        },
+        getSummary() {
+            const result = {};
+            for (const [name, s] of stores) {
+                const totalOps = s.totalPulls + s.totalPushes;
+                result[name] = {
+                    totalPulls: s.totalPulls,
+                    totalPushes: s.totalPushes,
+                    avgDurationMs: totalOps > 0 ? Math.round(s.totalDurationMs / totalOps) : 0,
+                    totalBytes: s.totalBytes,
+                    totalConflicts: s.totalConflicts,
+                };
+            }
+            return result;
+        },
+        reset() {
+            stores.clear();
+        },
+    };
+}

package/dist/migrate.js

@@ -0,0 +1,38 @@
+/**
+ * Creates a migration runner that upgrades documents to the current schema version.
+ *
+ * Given a document with `_schemaVersion`, applies each migration in sequence
+ * until the document reaches `currentVersion`. Throws if the document version
+ * is ahead of the app (forward compatibility guard).
+ */
+export function createMigrator(config) {
+    // Eagerly validate the migration chain
+    for (let v = 1; v < config.currentVersion; v++) {
+        if (!config.migrations[v]) {
+            throw new Error(`Missing migration for version ${v} -> ${v + 1}`);
+        }
+    }
+    return (data) => {
+        const version = typeof data._schemaVersion === "number" ? data._schemaVersion : 1;
+        if (version > config.currentVersion) {
+            throw new Error(`Document schema version ${version} is newer than app version ${config.currentVersion}. Update the app.`);
+        }
+        if (version === config.currentVersion)
+            return data;
+        let result = { ...data };
+        for (let v = version; v < config.currentVersion; v++) {
+            const fn = config.migrations[v];
+            if (!fn) {
+                throw new Error(`Missing migration for version ${v} -> ${v + 1}`);
+            }
+            try {
+                result = fn(result);
+            }
+            catch (err) {
+                throw new Error(`Migration from version ${v} to ${v + 1} failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+        }
+        result._schemaVersion = config.currentVersion;
+        return result;
+    };
+}

package/dist/mobile-lifecycle.js

@@ -0,0 +1,55 @@
+// ── Implementation ────────────────────────────────────────────────────────────
+/**
+ * Wires React Native app lifecycle events to a Starfish store.
+ *
+ * - **Background**: flushes pending changes before the OS suspends the app.
+ * - **Foreground**: pulls remote changes when the user returns to the app.
+ * - **NetInfo**: forwards connectivity changes to `store.getState().setOnline()`.
+ *
+ * Uses dependency injection so no `react-native` or `netinfo` imports are needed
+ * in this package. Pass the modules directly:
+ *
+ * ```ts
+ * import { AppState } from "react-native"
+ * import NetInfo from "@react-native-community/netinfo"
+ * import { createMobileLifecycle } from "@drakkar.software/starfish-client"
+ *
+ * // Call once, after the store is created:
+ * const cleanup = createMobileLifecycle(
+ *   store,
+ *   { appState: AppState, netInfo: NetInfo },
+ * )
+ *
+ * // In a React component (e.g. root layout):
+ * useEffect(() => cleanup, [])
+ * ```
+ *
+ * @returns A cleanup function that removes all event listeners.
+ */
+export function createMobileLifecycle(store, deps, options = {}) {
+    const { pullOnForeground = true, flushOnBackground = true } = options;
+    const appSub = deps.appState.addEventListener("change", (appState) => {
+        if (appState === "background" && flushOnBackground) {
+            if (store.getState().dirty) {
+                store.getState().flush().catch(() => { });
+            }
+        }
+        else if (appState === "active" && pullOnForeground) {
+            const { online, syncing } = store.getState();
+            if (online && !syncing) {
+                store.getState().pull().catch(() => { });
+            }
+        }
+        // "inactive" (iOS transition) and other states are intentionally ignored
+    });
+    let netUnsub = null;
+    if (deps.netInfo) {
+        netUnsub = deps.netInfo.addEventListener(({ isConnected }) => {
+            store.getState().setOnline(!!isConnected);
+        });
+    }
+    return () => {
+        appSub.remove();
+        netUnsub?.();
+    };
+}

package/dist/multi-store.js

@@ -0,0 +1,92 @@
+// ── Types ─────────────────────────────────────────────────────────────────────
+// ── Implementation ────────────────────────────────────────────────────────────
+/**
+ * Creates a multi-store sync coordinator.
+ *
+ * Collects multiple application stores into a single Starfish sync document,
+ * with versioned schema migrations for backward compatibility.
+ *
+ * ```ts
+ * const multiSync = createMultiStoreSync({
+ *   slices: {
+ *     tasks: {
+ *       serialize: () => taskStore.getState().tasks,
+ *       restore: (tasks) => taskStore.setState({ tasks }),
+ *     },
+ *     settings: {
+ *       serialize: () => settingsStore.getState().settings,
+ *       restore: (settings) => settingsStore.setState({ settings }),
+ *     },
+ *   },
+ *   version: 2,
+ *   migrations: {
+ *     // data from version 1 → upgrade to version 2
+ *     1: (data) => ({ ...data, settings: { ...(data.settings as object), darkMode: false } }),
+ *   },
+ * })
+ *
+ * // Push:
+ * starfishStore.getState().set(() => multiSync.serialize())
+ *
+ * // Restore on pull (pass as onRemoteUpdate to createStarfishStore):
+ * createStarfishStore({
+ *   name: "app",
+ *   syncManager,
+ *   onRemoteUpdate: (doc) => multiSync.restore(doc as BackupDocument),
+ * })
+ * ```
+ */
+export function createMultiStoreSync(options) {
+    const { slices, version, migrations = {} } = options;
+    // Validate migration chain at construction time (fail fast)
+    for (const fromVersion of Object.keys(migrations)) {
+        const v = Number(fromVersion);
+        if (isNaN(v) || v < 1) {
+            throw new Error(`Migration key must be a positive integer, got: "${fromVersion}"`);
+        }
+    }
+    function serialize() {
+        const data = {};
+        for (const key of Object.keys(slices)) {
+            data[key] = slices[key].serialize();
+        }
+        return { version, timestamp: Date.now(), data };
+    }
+    function restore(doc) {
+        if (typeof doc !== "object" || doc === null) {
+            throw new Error("restore: expected a BackupDocument object");
+        }
+        const docVersion = doc.version ?? 1;
+        if (typeof docVersion !== "number" || !Number.isInteger(docVersion) || docVersion < 1) {
+            throw new Error(`restore: invalid document version: ${String(doc.version)}`);
+        }
+        if (docVersion > version) {
+            throw new Error(`restore: document version ${docVersion} is newer than current version ${version}. ` +
+                `Update the app to restore this backup.`);
+        }
+        // Run migrations sequentially from docVersion up to current version
+        let data = typeof doc.data === "object" && doc.data !== null
+            ? { ...doc.data }
+            : {};
+        for (let v = docVersion; v < version; v++) {
+            const migration = migrations[v];
+            if (!migration)
+                continue;
+            try {
+                data = migration(data);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`restore: migration from version ${v} to ${v + 1} failed: ${msg}`);
+            }
+        }
+        // Restore each slice
+        for (const key of Object.keys(slices)) {
+            const sliceData = data[key];
+            if (sliceData !== undefined) {
+                slices[key].restore(sliceData);
+            }
+        }
+    }
+    return { serialize, restore, version };
+}

package/dist/polling.js

@@ -0,0 +1,52 @@
+const DEFAULT_INTERVALS = {
+    "slow-2g": 120_000,
+    "2g": 60_000,
+    "3g": 30_000,
+    "4g": 10_000,
+};
+const DEFAULT_FALLBACK_MS = 15_000;
+/**
+ * Start periodic pulling at a fixed interval.
+ * Skips pulls when offline or already syncing.
+ * Returns a cleanup function that stops polling.
+ */
+export function startPolling(pullFn, getState, intervalMs = 30_000) {
+    const timer = setInterval(() => {
+        const { online, syncing } = getState();
+        if (online && !syncing)
+            pullFn().catch(() => { });
+    }, intervalMs);
+    return () => clearInterval(timer);
+}
+/**
+ * Start polling with adaptive intervals based on network quality.
+ * Uses the Network Information API (`navigator.connection.effectiveType`) when available.
+ * Returns controls to pause, resume, or stop polling.
+ */
+export function startAdaptivePolling(pullFn, getState, options) {
+    let intervalMs;
+    if (options?.intervalMs != null) {
+        intervalMs = options.intervalMs;
+    }
+    else {
+        const intervals = options?.intervals ?? DEFAULT_INTERVALS;
+        let effectiveType;
+        if (typeof navigator !== "undefined" && "connection" in navigator) {
+            effectiveType = navigator.connection.effectiveType;
+        }
+        intervalMs = (effectiveType != null ? intervals[effectiveType] : undefined) ?? DEFAULT_FALLBACK_MS;
+    }
+    let paused = false;
+    const timer = setInterval(() => {
+        if (paused)
+            return;
+        const { online, syncing } = getState();
+        if (online && !syncing)
+            pullFn().catch(() => { });
+    }, intervalMs);
+    return {
+        pause: () => { paused = true; },
+        resume: () => { paused = false; },
+        stop: () => clearInterval(timer),
+    };
+}

package/dist/resolvers.js

@@ -0,0 +1,223 @@
+/** Shallow structural comparison of two values. Handles objects, arrays, and primitives. */
+function shallowEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return a === b;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => shallowEqual(v, b[i]));
+    }
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((k) => shallowEqual(aObj[k], bObj[k]));
+}
+/**
+ * Wrap a standard ConflictResolver to also return metadata about which fields conflicted.
+ * Compares local and remote keys to detect differing fields.
+ */
+export function withConflictMeta(resolver) {
+    return (local, remote) => {
+        const conflictedFields = [];
+        const allKeys = new Set([...Object.keys(local), ...Object.keys(remote)]);
+        for (const key of allKeys) {
+            const lv = local[key];
+            const rv = remote[key];
+            if (!shallowEqual(lv, rv)) {
+                conflictedFields.push(key);
+            }
+        }
+        const data = resolver(local, remote);
+        // Determine how it was resolved using structural comparison
+        let resolvedBy = "merged";
+        if (shallowEqual(data, local))
+            resolvedBy = "local";
+        else if (shallowEqual(data, remote))
+            resolvedBy = "remote";
+        return {
+            data,
+            meta: {
+                conflictedFields,
+                resolvedBy,
+                timestamp: Date.now(),
+            },
+        };
+    };
+}
+/** Compare two timestamp values. Handles both numeric (epoch) and string (ISO-8601) timestamps. */
+function compareTimestamps(a, b) {
+    if (typeof a === "number" && typeof b === "number")
+        return a >= b;
+    return String(a ?? "") >= String(b ?? "");
+}
+/**
+ * Creates a conflict resolver that merges arrays by ID with per-item
+ * timestamp comparison, and uses document-level timestamp for scalars.
+ *
+ * For arrays: builds a union of both sets keyed by `idKey`. When both
+ * sides have the same item, the one with the newer `timestampKey` wins.
+ * For scalars: the document with the newer `documentTimestampKey` wins.
+ *
+ * @example
+ * ```ts
+ * const merge = createUnionMerge()
+ * const sync = new SyncManager({ ..., onConflict: merge })
+ * ```
+ */
+export function createUnionMerge(options) {
+    const idKey = options?.idKey ?? "id";
+    const tsKey = options?.timestampKey ?? "updatedAt";
+    const docTsKey = options?.documentTimestampKey ?? "timestamp";
+    return (local, remote) => {
+        const result = {};
+        const localNewer = compareTimestamps(local[docTsKey], remote[docTsKey]);
+        const allKeys = new Set([...Object.keys(local), ...Object.keys(remote)]);
+        for (const key of allKeys) {
+            const lv = local[key];
+            const rv = remote[key];
+            // Both sides have arrays — attempt ID-based union
+            if (Array.isArray(lv) && Array.isArray(rv)) {
+                const map = new Map();
+                // Seed with remote items
+                for (const item of rv) {
+                    if (item && typeof item === "object" && idKey in item) {
+                        map.set(item[idKey], item);
+                    }
+                    else {
+                        map.set(Symbol(), item);
+                    }
+                }
+                // Overlay local items (per-item timestamp wins)
+                for (const item of lv) {
+                    if (item && typeof item === "object" && idKey in item) {
+                        const localItem = item;
+                        const id = localItem[idKey];
+                        const remoteItem = map.get(id);
+                        if (!remoteItem) {
+                            map.set(id, localItem);
+                        }
+                        else {
+                            if (compareTimestamps(localItem[tsKey], remoteItem[tsKey])) {
+                                map.set(id, localItem);
+                            }
+                        }
+                    }
+                    else {
+                        map.set(Symbol(), item);
+                    }
+                }
+                result[key] = [...map.values()];
+            }
+            else if (lv !== undefined && rv !== undefined) {
+                // Scalar: document-level timestamp wins
+                result[key] = localNewer ? lv : rv;
+            }
+            else {
+                // Only one side has the key
+                result[key] = lv ?? rv;
+            }
+        }
+        return result;
+    };
+}
+/**
+ * Creates a conflict resolver that handles soft-deleted items (tombstones).
+ * Extends union merge with tombstone awareness: if an item exists on one side
+ * with a `deletedAtKey` set, that deletion is respected even if the other side
+ * still has the item alive — as long as the deletion timestamp is newer.
+ */
+export function createSoftDeleteResolver(options) {
+    const idKey = options?.idKey ?? "id";
+    const tsKey = options?.timestampKey ?? "updatedAt";
+    const deletedAtKey = options?.deletedAtKey ?? "_deletedAt";
+    const baseMerge = createUnionMerge(options);
+    return (local, remote) => {
+        const merged = baseMerge(local, remote);
+        // Build a tombstone map from both sides: id → deletedAt timestamp
+        const tombstones = new Map();
+        for (const source of [local, remote]) {
+            for (const key of Object.keys(source)) {
+                const arr = source[key];
+                if (!Array.isArray(arr))
+                    continue;
+                for (const item of arr) {
+                    if (item && typeof item === "object" && idKey in item && deletedAtKey in item) {
+                        const rec = item;
+                        const id = rec[idKey];
+                        const deletedAt = rec[deletedAtKey];
+                        if (typeof deletedAt === "number" || typeof deletedAt === "string") {
+                            const existing = tombstones.get(id);
+                            if (existing == null || compareTimestamps(deletedAt, existing))
+                                tombstones.set(id, deletedAt);
+                        }
+                    }
+                }
+            }
+        }
+        // For merged arrays, ensure tombstoned items stay deleted
+        // (don't resurrect an item if its tombstone is newer than its updatedAt)
+        for (const key of Object.keys(merged)) {
+            const value = merged[key];
+            if (!Array.isArray(value))
+                continue;
+            merged[key] = value.filter((item) => {
+                if (!item || typeof item !== "object" || !(idKey in item))
+                    return true;
+                const rec = item;
+                const id = rec[idKey];
+                const deletedAt = tombstones.get(id);
+                if (deletedAt == null)
+                    return true;
+                // Keep the item if it has a deletedAt (it's the tombstone itself)
+                if (rec[deletedAtKey] != null)
+                    return true;
+                // Filter out alive items that have a newer tombstone
+                return compareTimestamps(rec[tsKey], deletedAt) && rec[tsKey] !== deletedAt;
+            });
+        }
+        return merged;
+    };
+}
+/**
+ * Simple resolver: the document with the newer timestamp wins entirely.
+ * No per-field or per-item merging.
+ */
+export function timestampWinner(timestampKey = "timestamp") {
+    return (local, remote) => {
+        return compareTimestamps(local[timestampKey], remote[timestampKey])
+            ? local
+            : remote;
+    };
+}
+/**
+ * Remove expired tombstones from an array of items.
+ * Items with a `deletedAtKey` older than `ttlMs` are pruned.
+ *
+ * @param items - Array of items, some with a deletedAt timestamp
+ * @param ttlMs - Time-to-live in ms for tombstones (default: 30 days)
+ * @param deletedAtKey - Key marking deletion timestamp (default: "_deletedAt")
+ */
+export function pruneTombstones(items, ttlMs = 30 * 24 * 60 * 60 * 1000, deletedAtKey = "_deletedAt") {
+    const cutoff = Date.now() - ttlMs;
+    return items.filter((item) => {
+        const deletedAt = item[deletedAtKey];
+        if (deletedAt == null)
+            return true;
+        if (typeof deletedAt === "number")
+            return deletedAt > cutoff;
+        if (typeof deletedAt === "string")
+            return new Date(deletedAt).getTime() > cutoff;
+        return false;
+    });
+}

package/dist/service-worker.js

@@ -0,0 +1,55 @@
+/**
+ * Service Worker utilities for offline support and PWA functionality.
+ */
+/** Check if service workers are supported in the current environment. */
+export function isServiceWorkerSupported() {
+    return typeof navigator !== "undefined" && "serviceWorker" in navigator;
+}
+/**
+ * Register a service worker for offline support.
+ * Returns the registration, or null if not supported.
+ */
+export async function registerServiceWorker(scriptUrl, opts) {
+    if (!isServiceWorkerSupported())
+        return null;
+    try {
+        const registration = await navigator.serviceWorker.register(scriptUrl, {
+            scope: opts?.scope,
+        });
+        if (opts?.onUpdate) {
+            registration.onupdatefound = () => {
+                const installingWorker = registration.installing;
+                if (installingWorker) {
+                    installingWorker.onstatechange = () => {
+                        if (installingWorker.state === "installed" &&
+                            navigator.serviceWorker.controller) {
+                            opts.onUpdate(registration);
+                        }
+                    };
+                }
+            };
+        }
+        return registration;
+    }
+    catch {
+        return null;
+    }
+}
+/** Unregister all service worker registrations. Returns true if any were unregistered. */
+export async function unregisterServiceWorkers() {
+    if (!isServiceWorkerSupported())
+        return false;
+    try {
+        const registrations = await navigator.serviceWorker.getRegistrations();
+        let unregistered = false;
+        for (const registration of registrations) {
+            const result = await registration.unregister();
+            if (result)
+                unregistered = true;
+        }
+        return unregistered;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/storage/indexeddb.js

@@ -0,0 +1,59 @@
+/**
+ * IndexedDB-based storage adapter for Zustand persistence.
+ * Implements the same interface as Zustand's StateStorage (getItem/setItem/removeItem).
+ * Supports larger data than localStorage (typically 50MB+).
+ */
+function openDB(dbName, storeName) {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(dbName, 1);
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            if (!db.objectStoreNames.contains(storeName)) {
+                db.createObjectStore(storeName);
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+function idbRequest(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+export function createIndexedDBStorage(opts) {
+    const dbName = opts?.dbName ?? "starfish";
+    const storeName = opts?.storeName ?? "state";
+    let dbPromise = null;
+    function getDB() {
+        if (!dbPromise) {
+            dbPromise = openDB(dbName, storeName).catch((err) => {
+                dbPromise = null; // Reset so next call retries
+                throw err;
+            });
+        }
+        return dbPromise;
+    }
+    return {
+        async getItem(name) {
+            const db = await getDB();
+            const tx = db.transaction(storeName, "readonly");
+            const store = tx.objectStore(storeName);
+            const result = await idbRequest(store.get(name));
+            return result ?? null;
+        },
+        async setItem(name, value) {
+            const db = await getDB();
+            const tx = db.transaction(storeName, "readwrite");
+            const store = tx.objectStore(storeName);
+            await idbRequest(store.put(value, name));
+        },
+        async removeItem(name) {
+            const db = await getDB();
+            const tx = db.transaction(storeName, "readwrite");
+            const store = tx.objectStore(storeName);
+            await idbRequest(store.delete(name));
+        },
+    };
+}