@drakkar.software/starfish-client 1.3.2 → 1.4.1

package/dist/resolvers.js

@@ -0,0 +1,166 @@
+/** 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/sync.d.ts

@@ -1,6 +1,8 @@
 import type { PullResult } from "@drakkar.software/starfish-protocol";
 import type { ConflictResolver } from "./types.js";
 import { StarfishClient } from "./client.js";
+import type { SyncLogger } from "./logger.js";
+import type { Validator } from "./validate.js";
 export interface SyncManagerOptions {
     client: StarfishClient;
     pullPath: string;
@@ -13,6 +15,12 @@ export interface SyncManagerOptions {
     encryptionSalt?: string;
     encryptionInfo?: string;
     signData?: (data: string) => Promise<string>;
+    /** Structured logger for sync events. */
+    logger?: SyncLogger;
+    /** Name passed to logger methods (default: derived from pullPath). */
+    loggerName?: string;
+    /** Validate data before push. Throws ValidationError on failure. */
+    validate?: Validator;
 }
 export declare class SyncManager {
     private readonly client;
@@ -22,6 +30,9 @@ export declare class SyncManager {
     private readonly maxRetries;
     private readonly encryptor;
     private readonly signData?;
+    private readonly logger?;
+    private readonly loggerName;
+    private readonly validate?;
     private lastHash;
     private lastCheckpoint;
     private localData;

package/dist/sync.js

@@ -1,6 +1,7 @@
 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;
@@ -9,6 +10,9 @@ export class SyncManager {
     maxRetries;
     encryptor;
     signData;
+    logger;
+    loggerName;
+    validate;
     lastHash = null;
     lastCheckpoint = 0;
     localData = {};
@@ -19,6 +23,9 @@ export class SyncManager {
         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.encryptionSecret && options.encryptionSalt
                 ? createEncryptor(options.encryptionSecret, options.encryptionSalt, options.encryptionInfo)
@@ -34,23 +41,40 @@ export class SyncManager {
         return this.lastCheckpoint;
     }
     async pull() {
-        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);
+        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;
         }
-        else {
-            this.localData = result.data;
+        catch (err) {
+            this.logger?.pullError(this.loggerName, err instanceof Error ? err.message : String(err));
+            throw err;
         }
-        this.lastHash = result.hash;
-        this.lastCheckpoint = result.timestamp;
-        return result;
     }
     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) {
@@ -65,19 +89,29 @@ export class SyncManager {
                 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;
                 }
-                const remote = await this.client.pull(this.pullPath);
-                this.lastHash = remote.hash;
-                this.lastCheckpoint = remote.timestamp;
-                const remoteData = this.encryptor
-                    ? await this.encryptor.decrypt(remote.data)
-                    : remote.data;
-                pendingData = this.onConflict(pendingData, remoteData);
+                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++;
             }

package/dist/testing.d.ts

@@ -0,0 +1,47 @@
+import type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
+import { StarfishClient } from "./client.js";
+type PullFn = (path: string, checkpoint?: number) => Promise<PullResult>;
+type PushFn = (path: string, data: Record<string, unknown>, baseHash: string | null, sig?: string) => Promise<PushSuccess>;
+/**
+ * Creates a mock StarfishClient for testing.
+ * Override individual methods or use the defaults (returns static data).
+ *
+ * @example
+ * ```ts
+ * const client = createMockClient({
+ *   pull: async () => ({ data: { key: "value" }, hash: "h1", timestamp: 100 }),
+ * })
+ * const sync = new SyncManager({ client, pullPath: "/pull/test", pushPath: "/push/test" })
+ * ```
+ */
+export declare function createMockClient(overrides?: {
+    pull?: PullFn;
+    push?: PushFn;
+}): StarfishClient & {
+    pullCalls: Array<{
+        path: string;
+        checkpoint?: number;
+    }>;
+    pushCalls: Array<{
+        path: string;
+        data: Record<string, unknown>;
+        baseHash: string | null;
+    }>;
+};
+/**
+ * Creates a mock fetch that returns predefined responses.
+ * Useful for testing StarfishClient directly.
+ *
+ * @example
+ * ```ts
+ * const fetch = createMockFetch({ data: { key: "value" }, hash: "h1", timestamp: 100 })
+ * const client = new StarfishClient({ baseUrl: "https://example.com", fetch })
+ * ```
+ */
+export declare function createMockFetch(pullResponse?: PullResult, pushResponse?: PushSuccess): typeof globalThis.fetch;
+/**
+ * Creates a mock fetch that simulates a conflict (409) on the first push,
+ * then succeeds on retry. Useful for testing conflict resolution.
+ */
+export declare function createConflictFetch(conflictPullResponse: PullResult, successPushResponse?: PushSuccess): typeof globalThis.fetch;
+export {};

package/dist/testing.js

@@ -0,0 +1,86 @@
+/**
+ * Creates a mock StarfishClient for testing.
+ * Override individual methods or use the defaults (returns static data).
+ *
+ * @example
+ * ```ts
+ * const client = createMockClient({
+ *   pull: async () => ({ data: { key: "value" }, hash: "h1", timestamp: 100 }),
+ * })
+ * const sync = new SyncManager({ client, pullPath: "/pull/test", pushPath: "/push/test" })
+ * ```
+ */
+export function createMockClient(overrides) {
+    const pullCalls = [];
+    const pushCalls = [];
+    const pull = overrides?.pull ?? (async () => ({
+        data: {},
+        hash: "mock-hash",
+        timestamp: Date.now(),
+    }));
+    const push = overrides?.push ?? (async () => ({
+        hash: "mock-push-hash",
+        timestamp: Date.now(),
+    }));
+    return {
+        pull: async (path, checkpoint) => {
+            pullCalls.push({ path, checkpoint });
+            return pull(path, checkpoint);
+        },
+        push: async (path, data, baseHash, sig) => {
+            pushCalls.push({ path, data, baseHash });
+            return push(path, data, baseHash, sig);
+        },
+        pullCalls,
+        pushCalls,
+    };
+}
+/**
+ * Creates a mock fetch that returns predefined responses.
+ * Useful for testing StarfishClient directly.
+ *
+ * @example
+ * ```ts
+ * const fetch = createMockFetch({ data: { key: "value" }, hash: "h1", timestamp: 100 })
+ * const client = new StarfishClient({ baseUrl: "https://example.com", fetch })
+ * ```
+ */
+export function createMockFetch(pullResponse, pushResponse) {
+    return async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        if (url.includes("/pull/")) {
+            return new Response(JSON.stringify(pullResponse ?? { data: {}, hash: "h", timestamp: 1 }), {
+                status: 200,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        return new Response(JSON.stringify(pushResponse ?? { hash: "h", timestamp: 1 }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        });
+    };
+}
+/**
+ * Creates a mock fetch that simulates a conflict (409) on the first push,
+ * then succeeds on retry. Useful for testing conflict resolution.
+ */
+export function createConflictFetch(conflictPullResponse, successPushResponse) {
+    let pushCount = 0;
+    return async (input, init) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        if (url.includes("/pull/")) {
+            return new Response(JSON.stringify(conflictPullResponse), {
+                status: 200,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        pushCount++;
+        if (pushCount === 1) {
+            return new Response(JSON.stringify({ error: "hash_mismatch" }), { status: 409 });
+        }
+        return new Response(JSON.stringify(successPushResponse ?? { hash: "resolved", timestamp: Date.now() }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        });
+    };
+}

package/dist/validate.d.ts

@@ -0,0 +1,27 @@
+/** Validation result: true if valid, or an array of error messages. */
+export type ValidationResult = true | string[];
+/** A function that validates data before push. */
+export type Validator = (data: Record<string, unknown>) => ValidationResult;
+/** Error thrown when pre-push validation fails. */
+export declare class ValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * 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 declare function createSchemaValidator(ajv: {
+    compile: (schema: object) => {
+        (data: unknown): boolean;
+        errors?: unknown;
+    };
+    errorsText: (errors?: unknown) => string;
+}, schema: object): Validator;

package/dist/validate.js

@@ -0,0 +1,28 @@
+/** 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)];
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -25,12 +25,25 @@
     "./legend": {
       "types": "./dist/bindings/legend.d.ts",
       "import": "./dist/bindings/legend.js"
+    },
+    "./fetch": {
+      "types": "./dist/fetch.d.ts",
+      "import": "./dist/fetch.js"
+    },
+    "./broadcast": {
+      "types": "./dist/broadcast.d.ts",
+      "import": "./dist/broadcast.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
     }
   },
   "peerDependencies": {
-    "zustand": ">=4.0.0",
+    "@legendapp/state": ">=2.0.0",
     "immer": ">=9.0.0",
-    "@legendapp/state": ">=2.0.0"
+    "react": ">=18.0.0",
+    "zustand": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "zustand": {
@@ -41,15 +54,24 @@
     },
     "@legendapp/state": {
       "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "1.3.2"
+    "@drakkar.software/starfish-protocol": "1.4.1"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "hono": "^4.12.7",
     "immer": "^11.1.4",
+    "jsdom": "^29.0.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "typescript": "^5.5.0",
     "vitest": "^3.0.0",
     "zustand": "^5.0.11"