@drakkar.software/starfish-client 1.6.0 → 1.7.0

package/dist/debounced-sync.d.ts

@@ -1,5 +1,6 @@
 import type { StoreApi } from "zustand/vanilla";
 import type { StarfishStore } from "./bindings/zustand.js";
+import type { SyncManager } from "./sync.js";
 export interface DebouncedSyncOptions {
     /**
      * How long to wait after the last `notify()` call before pushing (default: 2000 ms).
@@ -44,6 +45,48 @@ export interface DebouncedSync {
     /** Cancel any pending debounced push. Does not affect an already-in-flight push. */
     cancel: () => void;
 }
+export interface DebouncedPushOptions {
+    /**
+     * How long to wait after the last `notify()` call before pushing (default: 2000 ms).
+     */
+    delayMs?: number;
+    /**
+     * Required: provides the document to push when the debounce timer fires.
+     * Called inside the timer so it always captures the latest state.
+     */
+    serialize: () => Record<string, unknown>;
+    /**
+     * Emit a warning when the estimated encrypted payload exceeds this byte count (default: 900 KB).
+     * Set to `Infinity` to disable.
+     */
+    warnBytes?: number;
+    /**
+     * Block the push when the estimated encrypted payload exceeds this byte count (default: 1 MB).
+     * Set to `Infinity` to disable.
+     */
+    maxBytes?: number;
+    /**
+     * Called when the estimated payload size exceeds `warnBytes` but is below `maxBytes`.
+     */
+    onSizeWarning?: (estimatedBytes: number) => void;
+    /**
+     * Called when the estimated payload size exceeds `maxBytes`. The push is blocked.
+     * If omitted, a console error is printed.
+     */
+    onSizeExceeded?: (estimatedBytes: number) => void;
+    /**
+     * Called when `syncManager.push()` throws. Default: `console.warn`.
+     */
+    onError?: (err: unknown) => void;
+}
+export interface DebouncedPush {
+    /**
+     * Schedule a push. If called again within `delayMs`, the timer resets.
+     */
+    notify: () => void;
+    /** Cancel any pending debounced push. Does not affect an already-in-flight push. */
+    cancel: () => void;
+}
 /**
  * Creates a debounced push helper that coalesces rapid mutations into a single sync.
  *
@@ -64,3 +107,25 @@ export interface DebouncedSync {
  * ```
  */
 export declare function createDebouncedSync(store: StoreApi<StarfishStore>, options?: DebouncedSyncOptions): DebouncedSync;
+/**
+ * Creates a debounced push helper that calls `syncManager.push()` directly,
+ * without requiring a Zustand store.
+ *
+ * Use this for one-way publishing workflows: public pages, derived snapshots,
+ * or any case where you want to push data without a full `createStarfishStore` setup.
+ *
+ * ```ts
+ * const syncManager = new SyncManager({ client, pullPath, pushPath })
+ *
+ * const { notify, cancel } = createDebouncedPush(syncManager, {
+ *   serialize: () => buildPublicPageDocument(),
+ * })
+ *
+ * // Push after every relevant store mutation:
+ * planningStore.subscribe(() => notify())
+ *
+ * // Clean up on teardown:
+ * cancel()
+ * ```
+ */
+export declare function createDebouncedPush(syncManager: SyncManager, options: DebouncedPushOptions): DebouncedPush;

package/dist/debounced-sync.js

@@ -2,6 +2,32 @@
 const DEFAULT_DELAY_MS = 2000;
 const DEFAULT_WARN_BYTES = 900 * 1024; // 900 KB
 const DEFAULT_MAX_BYTES = 1024 * 1024; // 1 MB
+/** Returns true if the push should be blocked. */
+function checkPayloadSize(doc, opts) {
+    // Estimate encrypted payload size. AES-GCM output is similar to input size;
+    // base64 encoding adds ~33% overhead, plus a small IV/tag overhead.
+    const estimatedBytes = Math.ceil(JSON.stringify(doc).length * 1.34);
+    if (estimatedBytes > opts.maxBytes) {
+        if (opts.onSizeExceeded) {
+            opts.onSizeExceeded(estimatedBytes);
+        }
+        else {
+            console.error(`[starfish] Push blocked: estimated payload ${(estimatedBytes / 1024).toFixed(0)} KB ` +
+                `exceeds limit of ${(opts.maxBytes / 1024).toFixed(0)} KB. Prune your data before syncing.`);
+        }
+        return true;
+    }
+    if (estimatedBytes > opts.warnBytes) {
+        if (opts.onSizeWarning) {
+            opts.onSizeWarning(estimatedBytes);
+        }
+        else {
+            console.warn(`[starfish] Payload approaching limit: estimated ${(estimatedBytes / 1024).toFixed(0)} KB ` +
+                `(warn threshold: ${(opts.warnBytes / 1024).toFixed(0)} KB).`);
+        }
+    }
+    return false;
+}
 /**
  * Creates a debounced push helper that coalesces rapid mutations into a single sync.
  *
@@ -36,29 +62,58 @@ export function createDebouncedSync(store, options = {}) {
             timer = null;
             const current = store.getState().data;
             const doc = serialize ? serialize(current) : current;
-            // Estimate encrypted payload size. AES-GCM output is similar to input size;
-            // base64 encoding adds ~33% overhead, plus a small IV/tag overhead.
-            const estimatedBytes = Math.ceil(JSON.stringify(doc).length * 1.34);
-            if (estimatedBytes > maxBytes) {
-                if (onSizeExceeded) {
-                    onSizeExceeded(estimatedBytes);
-                }
-                else {
-                    console.error(`[starfish] Push blocked: estimated payload ${(estimatedBytes / 1024).toFixed(0)} KB ` +
-                        `exceeds limit of ${(maxBytes / 1024).toFixed(0)} KB. Prune your data before syncing.`);
-                }
+            if (checkPayloadSize(doc, { warnBytes, maxBytes, onSizeWarning, onSizeExceeded }))
+                return;
+            store.getState().set(() => doc);
+        }, delayMs);
+    }
+    return { notify, cancel };
+}
+/**
+ * Creates a debounced push helper that calls `syncManager.push()` directly,
+ * without requiring a Zustand store.
+ *
+ * Use this for one-way publishing workflows: public pages, derived snapshots,
+ * or any case where you want to push data without a full `createStarfishStore` setup.
+ *
+ * ```ts
+ * const syncManager = new SyncManager({ client, pullPath, pushPath })
+ *
+ * const { notify, cancel } = createDebouncedPush(syncManager, {
+ *   serialize: () => buildPublicPageDocument(),
+ * })
+ *
+ * // Push after every relevant store mutation:
+ * planningStore.subscribe(() => notify())
+ *
+ * // Clean up on teardown:
+ * cancel()
+ * ```
+ */
+export function createDebouncedPush(syncManager, options) {
+    const { delayMs = DEFAULT_DELAY_MS, warnBytes = DEFAULT_WARN_BYTES, maxBytes = DEFAULT_MAX_BYTES, serialize, onSizeWarning, onSizeExceeded, onError, } = options;
+    let timer = null;
+    function cancel() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function notify() {
+        cancel();
+        timer = setTimeout(() => {
+            timer = null;
+            const doc = serialize();
+            if (checkPayloadSize(doc, { warnBytes, maxBytes, onSizeWarning, onSizeExceeded }))
                 return;
-            }
-            if (estimatedBytes > warnBytes) {
-                if (onSizeWarning) {
-                    onSizeWarning(estimatedBytes);
+            syncManager.push(doc).catch((err) => {
+                if (onError) {
+                    onError(err);
                 }
                 else {
-                    console.warn(`[starfish] Payload approaching limit: estimated ${(estimatedBytes / 1024).toFixed(0)} KB ` +
-                        `(warn threshold: ${(warnBytes / 1024).toFixed(0)} KB).`);
+                    console.warn("[starfish] Push failed:", err);
                 }
-            }
-            store.getState().set(() => doc);
+            });
         }, delayMs);
     }
     return { notify, cancel };

package/dist/index.d.ts

@@ -34,7 +34,9 @@ export type { BackgroundSyncOptions } from "./background-sync.js";
 export { isServiceWorkerSupported, registerServiceWorker, unregisterServiceWorkers } from "./service-worker.js";
 export type { ServiceWorkerOptions } from "./service-worker.js";
 export { createSuspenseResource } from "./bindings/suspense.js";
-export { createDebouncedSync } from "./debounced-sync.js";
-export type { DebouncedSyncOptions, DebouncedSync } from "./debounced-sync.js";
+export { createDebouncedSync, createDebouncedPush } from "./debounced-sync.js";
+export type { DebouncedSyncOptions, DebouncedSync, DebouncedPushOptions, DebouncedPush } from "./debounced-sync.js";
+export { createMobileLifecycle } from "./mobile-lifecycle.js";
+export type { AppStateModule, NetInfoModule, MobileLifecycleDeps, MobileLifecycleOptions } from "./mobile-lifecycle.js";
 export { createMultiStoreSync } from "./multi-store.js";
 export type { StoreSlice, BackupDocument, MultiStoreMigrationFn, MultiStoreSyncOptions, MultiStoreSync, } from "./multi-store.js";

package/dist/index.js

@@ -17,5 +17,6 @@ export { exportData, importData, exportToBlob } from "./export.js";
 export { isBackgroundSyncSupported, registerBackgroundSync } from "./background-sync.js";
 export { isServiceWorkerSupported, registerServiceWorker, unregisterServiceWorkers } from "./service-worker.js";
 export { createSuspenseResource } from "./bindings/suspense.js";
-export { createDebouncedSync } from "./debounced-sync.js";
+export { createDebouncedSync, createDebouncedPush } from "./debounced-sync.js";
+export { createMobileLifecycle } from "./mobile-lifecycle.js";
 export { createMultiStoreSync } from "./multi-store.js";

package/dist/mobile-lifecycle.d.ts

@@ -0,0 +1,71 @@
+import type { StoreApi } from "zustand/vanilla";
+import type { StarfishStore } from "./bindings/zustand.js";
+/**
+ * Minimal interface matching React Native's `AppState` module.
+ * Pass `AppState` from `react-native` directly.
+ */
+export interface AppStateModule {
+    addEventListener: (type: "change", listener: (state: string) => void) => {
+        remove: () => void;
+    };
+}
+/**
+ * Minimal interface matching `@react-native-community/netinfo`'s default export.
+ * Pass `NetInfo` from `@react-native-community/netinfo` directly.
+ */
+export interface NetInfoModule {
+    addEventListener: (listener: (state: {
+        isConnected: boolean | null;
+    }) => void) => () => void;
+}
+export interface MobileLifecycleDeps {
+    /** React Native `AppState` module. */
+    appState: AppStateModule;
+    /**
+     * Optional: NetInfo module from `@react-native-community/netinfo`.
+     * When provided, connectivity changes are forwarded to `store.getState().setOnline()`.
+     */
+    netInfo?: NetInfoModule;
+}
+export interface MobileLifecycleOptions {
+    /**
+     * Pull remote changes when the app returns to the foreground.
+     * Only pulls if the store is online and not already syncing.
+     * Default: `true`.
+     */
+    pullOnForeground?: boolean;
+    /**
+     * Flush dirty data when the app transitions to the background.
+     * Only flushes if the store has unsaved changes.
+     * Default: `true`.
+     */
+    flushOnBackground?: boolean;
+}
+/**
+ * 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 declare function createMobileLifecycle(store: StoreApi<StarfishStore>, deps: MobileLifecycleDeps, options?: MobileLifecycleOptions): () => void;

package/dist/mobile-lifecycle.js

@@ -0,0 +1,55 @@
+// ── 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(() => { });
+            }
+        }
+        else if (appState === "active" && pullOnForeground) {
+            const { online, syncing } = store.getState();
+            if (online && !syncing) {
+                store.getState().pull().catch(() => { });
+            }
+        }
+        // "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?.();
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",