@drakkar.software/starfish-client 1.3.1 → 1.4.0

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,39 @@ 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);
+            }
+            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.message);
+            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,12 +88,15 @@ 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.message);
                     throw err;
                 }
+                this.logger?.conflict(this.loggerName, attempt + 1);
                 const remote = await this.client.pull(this.pullPath);
                 this.lastHash = remote.hash;
                 this.lastCheckpoint = remote.timestamp;

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.1",
+  "version": "1.4.0",
   "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,25 +54,34 @@
     },
     "@legendapp/state": {
       "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "workspace:*"
-  },
-  "scripts": {
-    "build": "tsc --build",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "@drakkar.software/starfish-protocol": "1.4.0"
   },
   "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"
   },
   "files": [
     "dist"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}