@drakkar.software/starfish-client 3.0.0-alpha.2 → 3.0.0-alpha.22

package/dist/bindings/legend.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/bindings/legend.ts"],
-  "sourcesContent": ["import { observable } from \"@legendapp/state\"\nimport type { Observable } from \"@legendapp/state\"\nimport type { SyncManager } from \"../sync.js\"\n\nexport interface StarfishLegendState {\n  data: Record<string, unknown>\n  syncing: boolean\n  online: boolean\n  dirty: boolean\n  error: string | null\n}\n\nexport interface StarfishLegendStore {\n  /** The observable state tree \u2014 read fields with `.get()` inside `observer` components. */\n  state: Observable<StarfishLegendState>\n  pull: () => Promise<void>\n  set: (modifier: (current: Record<string, unknown>) => Record<string, unknown>) => void\n  flush: () => Promise<void>\n  setOnline: (online: boolean) => void\n}\n\nexport interface CreateStarfishObservableOptions {\n  /** Unique name for this collection (used for persistence keys when applicable). */\n  name: string\n  syncManager: SyncManager\n  /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */\n  produce?: <T>(base: T, recipe: (draft: T) => T | void) => T\n}\n\nexport function createStarfishObservable(\n  options: CreateStarfishObservableOptions,\n): StarfishLegendStore {\n  const state = observable<StarfishLegendState>({\n    data: {},\n    syncing: false,\n    online: true,\n    dirty: false,\n    error: null,\n  })\n\n  const flush = async (): Promise<void> => {\n    if (state.syncing.get() || !state.dirty.get()) return\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.push(state.data.get())\n      state.data.set(options.syncManager.getData())\n      state.dirty.set(false)\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const pull = async (): Promise<void> => {\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.pull()\n      state.data.set(options.syncManager.getData())\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const set = (\n    modifier: (current: Record<string, unknown>) => Record<string, unknown>,\n  ): void => {\n    try {\n      const current = state.data.get()\n      const next = options.produce\n        ? options.produce(\n            current,\n            modifier as (draft: Record<string, unknown>) => Record<string, unknown> | void,\n          )\n        : modifier(current)\n      state.data.set(next)\n      state.dirty.set(true)\n      state.error.set(null)\n      if (state.online.get()) flush().catch(() => {})\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    }\n  }\n\n  const setOnline = (online: boolean): void => {\n    state.online.set(online)\n    if (online && state.dirty.get()) flush().catch(() => {})\n  }\n\n  return { state, pull, set, flush, setOnline }\n}\n"],
-  "mappings": ";AAAA,SAAS,kBAAkB;AA6BpB,SAAS,yBACd,SACqB;AACrB,QAAM,QAAQ,WAAgC;AAAA,IAC5C,MAAM,CAAC;AAAA,IACP,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,OAAO;AAAA,IACP,OAAO;AAAA,EACT,CAAC;AAED,QAAM,QAAQ,YAA2B;AACvC,QAAI,MAAM,QAAQ,IAAI,KAAK,CAAC,MAAM,MAAM,IAAI,EAAG;AAC/C,UAAM,QAAQ,IAAI,IAAI;AACtB,UAAM,MAAM,IAAI,IAAI;AACpB,QAAI;AACF,YAAM,QAAQ,YAAY,KAAK,MAAM,KAAK,IAAI,CAAC;AAC/C,YAAM,KAAK,IAAI,QAAQ,YAAY,QAAQ,CAAC;AAC5C,YAAM,MAAM,IAAI,KAAK;AAAA,IACvB,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE,UAAE;AACA,YAAM,QAAQ,IAAI,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,OAAO,YAA2B;AACtC,UAAM,QAAQ,IAAI,IAAI;AACtB,UAAM,MAAM,IAAI,IAAI;AACpB,QAAI;AACF,YAAM,QAAQ,YAAY,KAAK;AAC/B,YAAM,KAAK,IAAI,QAAQ,YAAY,QAAQ,CAAC;AAAA,IAC9C,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE,UAAE;AACA,YAAM,QAAQ,IAAI,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,MAAM,CACV,aACS;AACT,QAAI;AACF,YAAM,UAAU,MAAM,KAAK,IAAI;AAC/B,YAAM,OAAO,QAAQ,UACjB,QAAQ;AAAA,QACN;AAAA,QACA;AAAA,MACF,IACA,SAAS,OAAO;AACpB,YAAM,KAAK,IAAI,IAAI;AACnB,YAAM,MAAM,IAAI,IAAI;AACpB,YAAM,MAAM,IAAI,IAAI;AACpB,UAAI,MAAM,OAAO,IAAI,EAAG,OAAM,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IAChD,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE;AAAA,EACF;AAEA,QAAM,YAAY,CAAC,WAA0B;AAC3C,UAAM,OAAO,IAAI,MAAM;AACvB,QAAI,UAAU,MAAM,MAAM,IAAI,EAAG,OAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACzD;AAEA,SAAO,EAAE,OAAO,MAAM,KAAK,OAAO,UAAU;AAC9C;",
+  "sourcesContent": ["import { observable } from \"@legendapp/state\"\nimport type { Observable } from \"@legendapp/state\"\nimport type { SyncManager } from \"../sync.js\"\nimport type { AppendLogCursor, AppendElement } from \"../append-log.js\"\n\nexport interface StarfishLegendState {\n  data: Record<string, unknown>\n  syncing: boolean\n  online: boolean\n  dirty: boolean\n  error: string | null\n}\n\nexport interface StarfishLegendStore {\n  /** The observable state tree \u2014 read fields with `.get()` inside `observer` components. */\n  state: Observable<StarfishLegendState>\n  pull: () => Promise<void>\n  set: (modifier: (current: Record<string, unknown>) => Record<string, unknown>) => void\n  flush: () => Promise<void>\n  setOnline: (online: boolean) => void\n}\n\nexport interface CreateStarfishObservableOptions {\n  /** Unique name for this collection (used for persistence keys when applicable). */\n  name: string\n  syncManager: SyncManager\n  /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */\n  produce?: <T>(base: T, recipe: (draft: T) => T | void) => T\n}\n\nexport function createStarfishObservable(\n  options: CreateStarfishObservableOptions,\n): StarfishLegendStore {\n  const state = observable<StarfishLegendState>({\n    data: {},\n    syncing: false,\n    online: true,\n    dirty: false,\n    error: null,\n  })\n\n  const flush = async (): Promise<void> => {\n    if (state.syncing.get() || !state.dirty.get()) return\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.push(state.data.get())\n      state.data.set(options.syncManager.getData())\n      state.dirty.set(false)\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const pull = async (): Promise<void> => {\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.pull()\n      state.data.set(options.syncManager.getData())\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const set = (\n    modifier: (current: Record<string, unknown>) => Record<string, unknown>,\n  ): void => {\n    try {\n      const current = state.data.get()\n      const next = options.produce\n        ? options.produce(\n            current,\n            modifier as (draft: Record<string, unknown>) => Record<string, unknown> | void,\n          )\n        : modifier(current)\n      state.data.set(next)\n      state.dirty.set(true)\n      state.error.set(null)\n      if (state.online.get()) flush().catch(() => {})\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    }\n  }\n\n  const setOnline = (online: boolean): void => {\n    state.online.set(online)\n    if (online && state.dirty.get()) flush().catch(() => {})\n  }\n\n  return { state, pull, set, flush, setOnline }\n}\n\n// \u2500\u2500 Append-only log binding \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// The reactive counterpart for an append-only collection, backed by an\n// `AppendLogCursor`. Read-only (a log only grows): no `set`/`flush`/`dirty`.\n// The cursor owns the items + checkpoint; persist via `getItems()` and\n// rehydrate by constructing the cursor with `initialItems`.\n//\n// The store assumes it is the SOLE driver of its cursor (it seeds from\n// `cursor.getItems()` at construction and updates only via its own `pull()`);\n// don't also call `cursor.pull()` directly, or the observable will go stale.\n\nexport interface StarfishLogObservableState {\n  /** The full accumulated log, newest appended last. */\n  items: AppendElement[]\n  /** A `pull()` is in flight. */\n  loading: boolean\n  online: boolean\n  error: string | null\n  /** The cursor's checkpoint (max `ts` held). */\n  checkpoint: number\n}\n\nexport interface StarfishLogObservableStore {\n  /** The observable state tree \u2014 read fields with `.get()` inside `observer` components. */\n  state: Observable<StarfishLogObservableState>\n  /** Pull elements newer than the checkpoint, append them, return the new batch.\n   *  Errors are captured into `state.error`. */\n  pull: () => Promise<AppendElement[]>\n  setOnline: (online: boolean) => void\n}\n\nexport interface CreateStarfishLogObservableOptions {\n  cursor: AppendLogCursor\n}\n\nexport function createStarfishLogObservable(\n  options: CreateStarfishLogObservableOptions,\n): StarfishLogObservableStore {\n  const { cursor } = options\n  const state = observable<StarfishLogObservableState>({\n    // Seed from the cursor so a warm-started cursor's items show immediately.\n    items: cursor.getItems(),\n    loading: false,\n    online: true,\n    error: null,\n    checkpoint: cursor.getCheckpoint(),\n  })\n\n  const pull = async (): Promise<AppendElement[]> => {\n    if (state.loading.get()) return []\n    state.loading.set(true)\n    state.error.set(null)\n    try {\n      const batch = await cursor.pull()\n      state.items.set(cursor.getItems())\n      state.checkpoint.set(cursor.getCheckpoint())\n      return batch\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n      return []\n    } finally {\n      state.loading.set(false)\n    }\n  }\n\n  const setOnline = (online: boolean): void => {\n    state.online.set(online)\n  }\n\n  return { state, pull, setOnline }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/bindings/zustand.d.ts

@@ -3,7 +3,8 @@ import { type StateStorage } from "zustand/middleware";
 import type { DevtoolsOptions } from "zustand/middleware";
 import type { Encryptor } from "@drakkar.software/starfish-protocol";
 import { SyncManager } from "../sync.js";
-import type { StarfishCapProvider, ConflictResolver } from "../types.js";
+import { AppendLogCursor, type AppendElement } from "../append-log.js";
+import type { StarfishCapProvider, ConflictResolver, PullCache } from "../types.js";
 import type { SyncLogger } from "../logger.js";
 import type { Validator } from "../validate.js";
 export interface StarfishState {
@@ -14,6 +15,14 @@ export interface StarfishState {
     error: string | null;
     /** Last-known server hash, persisted alongside `data`/`dirty`. Restored into the bound SyncManager on hydration. */
     hash: string | null;
+    /**
+     * True when the currently-shown `data` came from the offline read-through
+     * cache (a cache-first {@link StarfishActions.seed} or a {@link StarfishActions.pull}
+     * the client served from cache because the transport was unreachable) rather
+     * than a live server response. A successful live pull/flush clears it. Use it
+     * to drive an "offline / showing last-synced data" indicator.
+     */
+    stale: boolean;
 }
 export interface StarfishActions {
     pull: () => Promise<void>;
@@ -22,6 +31,14 @@ export interface StarfishActions {
     restore: (data: Record<string, unknown>) => void;
     flush: () => Promise<void>;
     setOnline: (online: boolean) => void;
+    /**
+     * Cache-first paint: populate `data` from the client's offline read-through
+     * cache (decrypting in memory for E2E collections) without touching the
+     * network. A no-op when the client has no cache configured or there's no
+     * (unexpired) entry. {@link useSyncInit} calls this once before the initial
+     * pull; the live pull then supersedes the seeded snapshot.
+     */
+    seed: () => Promise<void>;
 }
 export type StarfishStore = StarfishState & StarfishActions;
 export interface CreateStarfishStoreOptions {
@@ -104,6 +121,13 @@ export declare function useConnectivity(store: StoreApi<StarfishStore>): void;
 export declare function useLastSynced(store: StoreApi<StarfishStore>): string;
 export interface SyncInitConfig {
     serverUrl: string;
+    /**
+     * Optional server namespace, forwarded to the underlying {@link StarfishClient}
+     * so `pullPath`/`pushPath` are rewritten to `/v1/<namespace>/…` (signed AND sent).
+     * Leave unset for a root-mounted server. Pass the bare name (e.g. `"octochat"`),
+     * not `/v1/octochat` — the `/v1/` is added by the client.
+     */
+    namespace?: string;
     capProvider?: StarfishCapProvider;
     pullPath: string;
     pushPath: string;
@@ -115,6 +139,16 @@ export interface SyncInitConfig {
     storeName?: string;
     storage?: StateStorage | false;
     fetch?: typeof globalThis.fetch;
+    /**
+     * Offline-first read-through cache for the underlying {@link StarfishClient}
+     * (see {@link StarfishClientOptions.cache}). When set, the store seeds from the
+     * last-synced ciphertext on creation (cache-first paint, decrypted in memory)
+     * and the live pull falls back to it when the transport is unreachable; the
+     * store's `stale` flag reflects whether the shown data is from cache.
+     */
+    cache?: PullCache;
+    /** Max age (ms) for {@link cache} entries; see {@link StarfishClientOptions.cacheMaxAgeMs}. */
+    cacheMaxAgeMs?: number;
     logger?: SyncLogger;
     validate?: Validator;
 }
@@ -128,3 +162,40 @@ export interface SyncInitConfig {
  * Pass `null` to disable sync (returns `null`).
  */
 export declare function useSyncInit(config: SyncInitConfig | null): StoreApi<StarfishStore> | null;
+export interface StarfishLogState {
+    /** The full accumulated log, newest appended last. */
+    items: AppendElement[];
+    /** A `pull()` is in flight. */
+    loading: boolean;
+    online: boolean;
+    error: string | null;
+    /** The cursor's checkpoint (max `ts` held). */
+    checkpoint: number;
+}
+export interface StarfishLogActions {
+    /** Pull elements newer than the checkpoint, append them, and return the new
+     *  batch. Errors are captured into `error` (mirroring the SyncManager store). */
+    pull: () => Promise<AppendElement[]>;
+    setOnline: (online: boolean) => void;
+}
+export type StarfishLogStore = StarfishLogState & StarfishLogActions;
+export interface CreateStarfishLogOptions {
+    cursor: AppendLogCursor;
+    devtools?: (storeCreator: any) => any;
+}
+export declare function createStarfishLog(options: CreateStarfishLogOptions): StoreApi<StarfishLogStore>;
+/** Derived status for an append-log store. */
+export type LogStatus = "idle" | "loading" | "error" | "offline";
+/** Derive a single status from log store state. */
+export declare function deriveLogStatus(state: StarfishLogState): LogStatus;
+/** Use the full append-log store state and actions. */
+export declare function useStarfishLog(store: StoreApi<StarfishLogStore>): StarfishLogStore;
+/** Use only the accumulated items, with an optional selector for fine-grained subscriptions. */
+export declare function useStarfishLogItems<T = AppendElement[]>(store: StoreApi<StarfishLogStore>, selector?: (items: AppendElement[]) => T): T;
+/** Use the derived log status (idle | loading | error | offline). */
+export declare function useLogStatus(store: StoreApi<StarfishLogStore>): LogStatus;
+/** Subscribe to log status changes outside of React. Invoked immediately with the
+ *  current status, then on every change. Returns an unsubscribe function. */
+export declare function subscribeLogStatus(store: StoreApi<StarfishLogStore>, callback: (status: LogStatus) => void): () => void;
+/** Binds browser online/offline events to the log store's setOnline action. Cleans up on unmount. */
+export declare function useLogConnectivity(store: StoreApi<StarfishLogStore>): void;