@drakkar.software/starfish-client 3.0.0-alpha.4 → 3.0.0-alpha.40

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));
+        },
+    };
+}

package/dist/sync.d.ts

@@ -70,14 +70,97 @@ export declare class SyncManager {
     private lastCheckpoint;
     private localData;
     private aborted;
+    private lastFromCache;
+    /** True once {@link seedFromCache} has successfully seeded localData from the cache. */
+    private seeded;
     constructor(options: SyncManagerOptions);
     abort(): void;
     get isAborted(): boolean;
     getData(): Record<string, unknown>;
+    /**
+     * Returns true when `pull()` / `ingest()` should merge against the current
+     * `localData` rather than replace it wholesale.
+     *
+     * Two situations establish a merge baseline:
+     * - A successful prior pull/ingest advanced `lastCheckpoint` beyond 0 (the
+     *   normal steady-state case, unchanged since alpha.36).
+     * - A cache seed painted `localData` via {@link seedFromCache} AND the store
+     *   uses a custom conflict resolver (i.e. NOT the default `deepMerge`). For a
+     *   union/custom resolver the seeded snapshot is a real baseline that must not
+     *   be clobbered by a short first live response (a cache-fallback on 429/5xx
+     *   or a momentarily-short concurrent server snapshot). For the default
+     *   `deepMerge` resolver we keep the pre-fix wholesale-replace behaviour so
+     *   non-union stores are byte-identical to alpha.36.
+     */
+    private hasMergeBaseline;
+    /**
+     * Merge a remote snapshot with local (optimistic) data using this manager's
+     * conflict resolver — the same resolver the push-conflict path uses. A plain
+     * {@link pull} overwrites the store's data with the server snapshot, which
+     * would drop un-pushed local writes (they live only in the store, never in
+     * `localData` until a push succeeds). The zustand binding calls this on pull
+     * while the store is dirty so those writes survive. `local` wins by the same
+     * rules as a push conflict.
+     */
+    resolve(local: Record<string, unknown>, remote: Record<string, unknown>): Record<string, unknown>;
     getHash(): string | null;
     /** Set the last-known server hash. Used by persistence layers to restore state across restarts. */
     setHash(hash: string | null): void;
+    /**
+     * Whether the most recent {@link pull} (or {@link seedFromCache}) was served
+     * from the client's offline read-through cache rather than a live server
+     * response. The binding surfaces this as a `stale` flag so the UI can show an
+     * offline indicator without treating a cache hit as "reachable". Reset to
+     * false by the next successful network pull.
+     */
+    getLastPullFromCache(): boolean;
+    /**
+     * Cache-first paint: seed `localData` from the client's read-through cache
+     * WITHOUT touching the network, decrypting in memory for E2E collections.
+     * Returns whether anything was seeded (false on a miss, an expired entry, or
+     * a decrypt failure — e.g. keyring skew). Call once on store creation before
+     * the initial live {@link pull}.
+     *
+     * `lastCheckpoint` is intentionally left at 0 so the first live pull sends a
+     * full (re)sync request to the server, not a delta. However, for stores with
+     * a custom conflict resolver (e.g. `createUnionMerge`) the seeded snapshot is
+     * treated as a merge baseline: {@link hasMergeBaseline} returns true, so the
+     * first pull/ingest merges against the seed rather than replacing it wholesale.
+     * This closes the bootstrap window where a short first-pull response (a cache-
+     * fallback on 429/5xx or a momentarily-short concurrent snapshot) would
+     * silently drop items the resolver was configured to preserve. For the default
+     * `deepMerge` resolver the first pull still takes the snapshot wholesale —
+     * behaviour is byte-identical to alpha.36.
+     *
+     * Requires the client to have been built with a `cache`.
+     */
+    seedFromCache(): Promise<boolean>;
     getCheckpoint(): number;
+    /**
+     * Apply a freshly-fetched `PullResult` to this manager's state WITHOUT
+     * firing a network request. Used by the zustand binding's `mergeResult`
+     * action to absorb a background revalidation result (delivered via
+     * {@link StarfishClientOptions.onRevalidated}) into the store.
+     *
+     * Like {@link pull}, `ingest` conflict-merges the snapshot against the
+     * established baseline via `this.onConflict` when a merge baseline exists
+     * ({@link hasMergeBaseline}) — so a union-merge store does not lose array
+     * items when a revalidation result (e.g. a stale cache-fallback on 429/5xx)
+     * is a shorter snapshot. The baseline is established by either a prior
+     * pull/ingest that advanced `lastCheckpoint`, or by a successful
+     * {@link seedFromCache} for a store with a custom resolver. The first ingest
+     * without such a baseline takes the snapshot wholesale (default `deepMerge`
+     * stores are byte-identical to alpha.36). Sets `lastFromCache = false` (a
+     * revalidation is a live response) so the binding can clear its `stale` flag.
+     *
+     * **Staleness guard**: if a `push()` advanced `lastCheckpoint` between the
+     * time the revalidation request was sent and the time it resolves, the
+     * result is from an older document version. Ingesting it would clobber the
+     * user's just-saved edit and reset `lastHash` to a stale server hash
+     * (causing a spurious 409 on the next push). We silently drop the result in
+     * that case — the store's post-push state is already correct.
+     */
+    ingest(result: PullResult): Promise<void>;
     pull(): Promise<PullResult>;
     push(data: Record<string, unknown>): Promise<{
         hash: string;

package/dist/sync.js

@@ -0,0 +1,181 @@
+import { AUTHOR_PUBKEY_FIELD, AUTHOR_SIGNATURE_FIELD, deepMerge, docAuthorCanonicalInput, getBase64, } from "@drakkar.software/starfish-protocol";
+import { ConflictError } from "./types.js";
+import { stripPushPrefix } from "./client.js";
+import { ValidationError } from "./validate.js";
+export class AbortError extends Error {
+    constructor() {
+        super("SyncManager was aborted");
+        this.name = "AbortError";
+    }
+}
+export class SyncManager {
+    client;
+    pullPath;
+    pushPath;
+    onConflict;
+    maxRetries;
+    encryptor;
+    signer;
+    logger;
+    loggerName;
+    validate;
+    lastHash = null;
+    lastCheckpoint = 0;
+    localData = {};
+    aborted = false;
+    constructor(options) {
+        this.client = options.client;
+        this.pullPath = options.pullPath;
+        this.pushPath = options.pushPath;
+        this.onConflict = options.onConflict ?? deepMerge;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.signer = options.signer;
+        this.logger = options.logger;
+        this.loggerName = options.loggerName ?? options.pullPath.split("/").filter(Boolean).pop() ?? options.pullPath;
+        this.validate = options.validate;
+        this.encryptor = options.encryptor ?? null;
+    }
+    abort() {
+        this.aborted = true;
+    }
+    get isAborted() {
+        return this.aborted;
+    }
+    getData() {
+        return { ...this.localData };
+    }
+    getHash() {
+        return this.lastHash;
+    }
+    /** Set the last-known server hash. Used by persistence layers to restore state across restarts. */
+    setHash(hash) {
+        this.lastHash = hash;
+    }
+    getCheckpoint() {
+        return this.lastCheckpoint;
+    }
+    async pull() {
+        if (this.aborted)
+            throw new AbortError();
+        this.logger?.pullStart(this.loggerName);
+        const start = performance.now();
+        try {
+            // NOTE: `SyncManager.pull` does NOT auto-enable `withKeyring`. Clients
+            // that drive the keyring helpers from `recipients.ts` and want to save
+            // the cold-start round-trip should call `client.pull(path, {withKeyring: true})`
+            // directly. We keep `SyncManager` keyring-agnostic so it stays usable
+            // for collections that don't use delegated encryption.
+            const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
+            if (this.aborted)
+                throw new AbortError();
+            if (this.encryptor) {
+                const decrypted = await this.encryptor.decrypt(result.data);
+                if (this.aborted)
+                    throw new AbortError();
+                this.localData = decrypted;
+                result.data = decrypted;
+            }
+            else if (this.lastCheckpoint > 0) {
+                this.localData = deepMerge(this.localData, result.data);
+                result.data = this.localData;
+            }
+            else {
+                this.localData = result.data;
+            }
+            this.lastHash = result.hash;
+            this.lastCheckpoint = result.timestamp;
+            this.logger?.pullSuccess(this.loggerName, Math.round(performance.now() - start));
+            return result;
+        }
+        catch (err) {
+            this.logger?.pullError(this.loggerName, err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    }
+    async push(data) {
+        if (this.aborted)
+            throw new AbortError();
+        if (this.validate) {
+            const result = this.validate(data);
+            if (result !== true)
+                throw new ValidationError(result);
+        }
+        this.logger?.pushStart(this.loggerName);
+        const start = performance.now();
+        let attempt = 0;
+        let pendingData = data;
+        while (attempt <= this.maxRetries) {
+            try {
+                const sealed = this.encryptor
+                    ? await this.encryptor.encrypt(pendingData)
+                    : pendingData;
+                if (this.aborted)
+                    throw new AbortError();
+                // v3.0 signer path: sign the document author proof over the doc-author
+                // canonical input (domain-tagged, bound to documentKey) and pass it as
+                // top-level body siblings of `data` (NOT inside `data`), where the server
+                // verifies it and stores the raw author pubkey.
+                let author;
+                if (this.signer) {
+                    const { devEdPubHex, sign } = await this.signer.getSigner();
+                    if (this.aborted)
+                        throw new AbortError();
+                    const documentKey = stripPushPrefix(this.pushPath);
+                    const canonical = docAuthorCanonicalInput(documentKey, sealed);
+                    const sigBytes = await sign(new TextEncoder().encode(canonical));
+                    if (this.aborted)
+                        throw new AbortError();
+                    author = {
+                        [AUTHOR_PUBKEY_FIELD]: devEdPubHex,
+                        [AUTHOR_SIGNATURE_FIELD]: getBase64().encode(sigBytes),
+                    };
+                }
+                const result = await this.client.push(this.pushPath, sealed, this.lastHash, author);
+                if (this.aborted)
+                    throw new AbortError();
+                this.lastHash = result.hash;
+                this.lastCheckpoint = result.timestamp;
+                this.localData = pendingData;
+                this.logger?.pushSuccess(this.loggerName, Math.round(performance.now() - start));
+                return result;
+            }
+            catch (err) {
+                if (err instanceof AbortError)
+                    throw err;
+                if (!(err instanceof ConflictError) || attempt >= this.maxRetries) {
+                    this.logger?.pushError(this.loggerName, err instanceof Error ? err.message : String(err));
+                    throw err;
+                }
+                this.logger?.conflict(this.loggerName, attempt + 1);
+                try {
+                    const remote = await this.client.pull(this.pullPath);
+                    if (this.aborted)
+                        throw new AbortError();
+                    const remoteData = this.encryptor
+                        ? await this.encryptor.decrypt(remote.data)
+                        : remote.data;
+                    if (this.aborted)
+                        throw new AbortError();
+                    this.lastHash = remote.hash;
+                    this.lastCheckpoint = remote.timestamp;
+                    pendingData = this.onConflict(pendingData, remoteData);
+                }
+                catch (resolveErr) {
+                    if (resolveErr instanceof AbortError)
+                        throw resolveErr;
+                    const msg = resolveErr instanceof Error ? resolveErr.message : String(resolveErr);
+                    this.logger?.pushError(this.loggerName, `Conflict resolution failed (attempt ${attempt + 1}): ${msg}`);
+                    throw resolveErr;
+                }
+                await new Promise(resolve => setTimeout(resolve, Math.min(100 * Math.pow(2, attempt), 2000) + Math.random() * 100));
+                attempt++;
+            }
+        }
+        throw new ConflictError();
+    }
+    async update(modifier) {
+        await this.pull();
+        const updated = modifier(this.localData);
+        return this.push(updated);
+    }
+}