@drakkar.software/starfish-client 3.0.0-alpha.5 → 3.0.0-alpha.51

package/dist/kv-cache.d.ts

@@ -0,0 +1,63 @@
+/**
+ * KV-backed {@link PullCache} factory.
+ *
+ * {@link createKvPullCache} adapts any {@link AsyncStateStorage} (or any
+ * object with `getItem`/`setItem`) into a {@link PullCache} that the
+ * `StarfishClient` can use as its offline read-through cache.
+ *
+ * Why this matters: the client's `cache` option is ciphertext-at-rest by
+ * construction — it stores the raw sealed server response and only decrypts
+ * in memory on read. Backing the cache with the platform's own KV (AsyncStorage
+ * on React Native, IndexedDB via `createIndexedDBStorage`, a custom adapter)
+ * gives offline-first reads without exposing plaintext to the OS storage layer.
+ *
+ * @example
+ * ```ts
+ * import AsyncStorage from "@react-native-async-storage/async-storage"
+ * import { StarfishClient } from "@drakkar.software/starfish-client"
+ * import { createKvPullCache } from "@drakkar.software/starfish-client"
+ *
+ * const client = new StarfishClient({
+ *   baseUrl: "https://api.example.com",
+ *   cache: createKvPullCache(AsyncStorage, { prefix: "sf:", maxAgeMs: 30 * 24 * 60 * 60 * 1000 }),
+ * })
+ * ```
+ */
+import type { PullCache } from "./types.js";
+/** A storage backend that `createKvPullCache` can wrap. */
+export interface KvStore {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<unknown> | unknown;
+    removeItem?: (key: string) => Promise<unknown> | unknown;
+}
+/** Options for {@link createKvPullCache}. */
+export interface KvPullCacheOptions {
+    /**
+     * Key prefix for cache entries (default `"starfish.pullcache."`). Change
+     * when sharing a KV store with other data to avoid key collisions.
+     */
+    prefix?: string;
+    /**
+     * Maximum age in milliseconds for a cached snapshot. When set, an entry
+     * older than `maxAgeMs` is returned as `null` (a cache MISS) so the next
+     * pull goes to the network rather than serving arbitrarily stale data.
+     *
+     * Each entry stores a `_cachedAt` wall-clock timestamp; expiry is checked on
+     * every `get`. Omit (default) for entries that never expire — recommended
+     * for offline-first apps where any last-synced data beats none.
+     */
+    maxAgeMs?: number;
+}
+/**
+ * Adapt a KV store into a {@link PullCache} for `StarfishClient`.
+ *
+ * The adapter serialises the cached pull payload (itself a JSON string) into
+ * an outer JSON envelope that tracks the wall-clock write time for optional
+ * max-age expiry. Reading a legacy entry without `_cachedAt` treats it as
+ * fresh (backward-compatible with plain-string caches).
+ *
+ * All `get`/`set` errors are swallowed (the {@link PullCache} contract
+ * requires implementations not to throw) — a failing KV store simply
+ * degrades to "no cache" without crashing the app.
+ */
+export declare function createKvPullCache(kv: KvStore, opts?: KvPullCacheOptions): PullCache;

package/dist/logger.d.ts

@@ -5,6 +5,9 @@ export interface SyncMetrics {
     conflictCount?: number;
     retryCount?: number;
     cacheHit?: boolean;
+    /** Elements an append-log pull dropped under `onElementError: "skip"`
+     *  (failed verification/decryption). Omitted when none were skipped. */
+    skippedCount?: number;
 }
 /** Structured logger for sync operations. */
 export interface SyncLogger {

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.d.ts

@@ -1,5 +1,5 @@
 import type { StoreApi } from "zustand/vanilla";
-import type { StarfishStore } from "./bindings/zustand.js";
+import type { StarfishStore, StarfishLogStore } from "./bindings/zustand.js";
 /**
  * Minimal interface matching React Native's `AppState` module.
  * Pass `AppState` from `react-native` directly.
@@ -69,3 +69,30 @@ export interface MobileLifecycleOptions {
  * @returns A cleanup function that removes all event listeners.
  */
 export declare function createMobileLifecycle(store: StoreApi<StarfishStore>, deps: MobileLifecycleDeps, options?: MobileLifecycleOptions): () => void;
+export interface AppendLogLifecycleOptions {
+    /**
+     * Pull new elements when the app returns to the foreground.
+     * Only pulls if the store is online and not already loading.
+     * Default: `true`.
+     */
+    pullOnForeground?: boolean;
+}
+/**
+ * Wires React Native app lifecycle events to an append-log store
+ * (`createStarfishLog`). A log is read-only, so this only pulls on foreground
+ * (there is nothing to flush on background). NetInfo connectivity changes are
+ * forwarded to `store.getState().setOnline()`.
+ *
+ * ```ts
+ * import { AppState } from "react-native"
+ * import NetInfo from "@react-native-community/netinfo"
+ * import { createStarfishLog, createAppendLogMobileLifecycle } from "@drakkar.software/starfish-client"
+ *
+ * const store = createStarfishLog({ cursor })
+ * const cleanup = createAppendLogMobileLifecycle(store, { appState: AppState, netInfo: NetInfo })
+ * useEffect(() => cleanup, [])
+ * ```
+ *
+ * @returns A cleanup function that removes all event listeners.
+ */
+export declare function createAppendLogMobileLifecycle(store: StoreApi<StarfishLogStore>, deps: MobileLifecycleDeps, options?: AppendLogLifecycleOptions): () => void;

package/dist/mobile-lifecycle.js

@@ -0,0 +1,94 @@
+// ── 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((err) => { console.error("[Starfish] background flush failed:", err); });
+            }
+        }
+        else if (appState === "active" && pullOnForeground) {
+            const { online, syncing } = store.getState();
+            if (online && !syncing) {
+                store.getState().pull().catch((err) => { console.error("[Starfish] foreground pull failed:", err); });
+            }
+        }
+        // "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?.();
+    };
+}
+/**
+ * Wires React Native app lifecycle events to an append-log store
+ * (`createStarfishLog`). A log is read-only, so this only pulls on foreground
+ * (there is nothing to flush on background). NetInfo connectivity changes are
+ * forwarded to `store.getState().setOnline()`.
+ *
+ * ```ts
+ * import { AppState } from "react-native"
+ * import NetInfo from "@react-native-community/netinfo"
+ * import { createStarfishLog, createAppendLogMobileLifecycle } from "@drakkar.software/starfish-client"
+ *
+ * const store = createStarfishLog({ cursor })
+ * const cleanup = createAppendLogMobileLifecycle(store, { appState: AppState, netInfo: NetInfo })
+ * useEffect(() => cleanup, [])
+ * ```
+ *
+ * @returns A cleanup function that removes all event listeners.
+ */
+export function createAppendLogMobileLifecycle(store, deps, options = {}) {
+    const { pullOnForeground = true } = options;
+    const appSub = deps.appState.addEventListener("change", (appState) => {
+        if (appState === "active" && pullOnForeground) {
+            const { online, loading } = store.getState();
+            if (online && !loading) {
+                store.getState().pull().catch((err) => { console.error("[Starfish] foreground log pull failed:", err); });
+            }
+        }
+    });
+    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/mutate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Read-modify-write a document with hash-CAS conflict retry.
+ *
+ * The everyday way to atomically edit a synced document: pull the current
+ * version, apply a pure `mutator` to its data, push the result with the read
+ * hash, and retry on a {@link ConflictError} (a concurrent writer moved the hash)
+ * by re-reading FRESH server state and re-applying the mutator. A missing
+ * document (404) is surfaced to the mutator as `{ data: null, hash: null }` so it
+ * can create the doc on first write.
+ *
+ * This replaces the ad-hoc `for (attempt…) { pull; mutate; try push catch
+ * ConflictError }` loop that applications otherwise hand-roll around every
+ * editable doc. The `mutator` MUST be idempotent — it re-runs on each retry — and
+ * returns `null` to signal a no-op (nothing changed; skip the write).
+ */
+import { StarfishClient } from "./client.js";
+/** The current state handed to a {@link DocMutator}: the document data (or `null`
+ *  when the doc does not exist yet) and the hash to base the next push on. */
+export interface DocState<T> {
+    data: T | null;
+    hash: string | null;
+}
+/**
+ * Pure transform from the current document to the next. Return the full next
+ * document body to write, or `null` for a no-op (the write is skipped). Runs once
+ * per attempt on freshly-pulled state, so it must be idempotent.
+ */
+export type DocMutator<T> = (cur: DocState<T>) => T | null;
+export interface MutateDocOptions {
+    /** Max push attempts before a persistent conflict propagates. Default 3. */
+    maxAttempts?: number;
+}
+/**
+ * Atomically read-modify-write the document at `path`. Returns the document that
+ * was written, or `null` if the mutator signalled a no-op. Throws the underlying
+ * error on a non-conflict failure, or a {@link ConflictError} if every attempt
+ * raced and lost.
+ */
+export declare function mutateDoc<T extends Record<string, unknown> = Record<string, unknown>>(client: StarfishClient, path: string, mutator: DocMutator<T>, options?: MutateDocOptions): Promise<T | null>;

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((err) => { console.error("[Starfish] poll failed:", err); });
+    }, 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((err) => { console.error("[Starfish] adaptive poll failed:", err); });
+    }, intervalMs);
+    return {
+        pause: () => { paused = true; },
+        resume: () => { paused = false; },
+        stop: () => clearInterval(timer),
+    };
+}