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

package/dist/resolvers.js

@@ -1,223 +0,0 @@
-/** 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

@@ -1,55 +0,0 @@
-/**
- * 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

@@ -1,59 +0,0 @@
-/**
- * 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.js

@@ -1,127 +0,0 @@
-import { deepMerge, stableStringify } from "@drakkar.software/starfish-protocol";
-import { ConflictError } from "./types.js";
-import { createEncryptor } from "./crypto.js";
-import { ValidationError } from "./validate.js";
-export class SyncManager {
-    client;
-    pullPath;
-    pushPath;
-    onConflict;
-    maxRetries;
-    encryptor;
-    signData;
-    logger;
-    loggerName;
-    validate;
-    lastHash = null;
-    lastCheckpoint = 0;
-    localData = {};
-    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.signData = options.signData;
-        this.logger = options.logger;
-        this.loggerName = options.loggerName ?? options.pullPath.split("/").filter(Boolean).pop() ?? options.pullPath;
-        this.validate = options.validate;
-        this.encryptor =
-            options.encryptor ??
-                (options.encryptionSecret && options.encryptionSalt
-                    ? createEncryptor(options.encryptionSecret, options.encryptionSalt, options.encryptionInfo)
-                    : null);
-    }
-    getData() {
-        return { ...this.localData };
-    }
-    getHash() {
-        return this.lastHash;
-    }
-    getCheckpoint() {
-        return this.lastCheckpoint;
-    }
-    async pull() {
-        this.logger?.pullStart(this.loggerName);
-        const start = performance.now();
-        try {
-            const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
-            if (this.encryptor) {
-                const decrypted = await this.encryptor.decrypt(result.data);
-                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.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 payload = this.encryptor
-                    ? await this.encryptor.encrypt(pendingData)
-                    : pendingData;
-                const sig = this.signData
-                    ? await this.signData(stableStringify(payload))
-                    : undefined;
-                const result = await this.client.push(this.pushPath, payload, this.lastHash, sig);
-                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 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);
-                    const remoteData = this.encryptor
-                        ? await this.encryptor.decrypt(remote.data)
-                        : remote.data;
-                    this.lastHash = remote.hash;
-                    this.lastCheckpoint = remote.timestamp;
-                    pendingData = this.onConflict(pendingData, remoteData);
-                }
-                catch (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);
-    }
-}

package/dist/types.js

@@ -1,18 +0,0 @@
-/** Push conflict error (HTTP 409). */
-export class ConflictError extends Error {
-    constructor() {
-        super("hash_mismatch");
-        this.name = "ConflictError";
-    }
-}
-/** HTTP error from the Starfish server. */
-export class StarfishHttpError extends Error {
-    status;
-    body;
-    constructor(status, body) {
-        super(`HTTP ${status}: ${body}`);
-        this.status = status;
-        this.body = body;
-        this.name = "StarfishHttpError";
-    }
-}

package/dist/validate.js

@@ -1,28 +0,0 @@
-/** Error thrown when pre-push validation fails. */
-export class ValidationError extends Error {
-    errors;
-    constructor(errors) {
-        super(`Validation failed: ${errors.join("; ")}`);
-        this.errors = errors;
-        this.name = "ValidationError";
-    }
-}
-/**
- * Creates a validator from a JSON Schema object.
- * Requires an Ajv-compatible validate function.
- *
- * @example
- * ```ts
- * import Ajv from "ajv"
- * const ajv = new Ajv()
- * const validator = createSchemaValidator(ajv, mySchema)
- * ```
- */
-export function createSchemaValidator(ajv, schema) {
-    const validate = ajv.compile(schema);
-    return (data) => {
-        if (validate(data))
-            return true;
-        return [ajv.errorsText(validate.errors)];
-    };
-}