local-replica 0.0.0 → 0.0.1

package/dist/zustand/index.d.ts

@@ -1 +1,362 @@
-export {}
+import { G as ReplicaResource, O as ReplicaAction, S as ReplicaOptimisticToken, X as ReplicaSource, _ as OptimisticMutationOptions, tt as ReplicaPagedData, x as ReplicaHeadOutcome, y as ReplicaEngineOptions } from "../index-CFbCHM7Q.js";
+/**
+ * Scheduling knobs a sync can ask its driver for. Named after SWR's options;
+ * a driver maps them onto its own cache (or ignores what it cannot honor).
+ */
+export interface ReplicaSyncSchedule {
+  /** Collapse identical requests within this window (ms). */
+  dedupingInterval?: number;
+  /** Skip focus revalidation while the last one is younger than this (ms). */
+  focusThrottleInterval?: number;
+  /**
+   * Hold every network request (mount, stale, focus, revalidate) while it
+   * returns `true`, for a read whose input outside the sync key is not ready
+   * yet. Unlike `revalidateOnMount: false` it also covers a later key change.
+   * Read on each request, so it may close over a ref.
+   */
+  isPaused?: () => boolean;
+  /** Poll every N ms while mounted (0 = off); a function decides per tick from the latest data. */
+  refreshInterval?: number | ((latest: any) => number);
+  /** Keep polling while the page is hidden. */
+  refreshWhenHidden?: boolean;
+  /** Keep polling while the browser is offline. */
+  refreshWhenOffline?: boolean;
+  revalidateIfStale?: boolean;
+  revalidateOnFocus?: boolean;
+  /**
+   * Whether the first mount fetches. `false` leaves the first request to an
+   * explicit `revalidate`, for a read whose input outside the sync key is not
+   * ready yet. SWR only honors it on the first mount: a later key change still
+   * fetches when the new key has no cached data.
+   */
+  revalidateOnMount?: boolean;
+  revalidateOnReconnect?: boolean;
+}
+export interface ReplicaQueryOptions<T> extends ReplicaSyncSchedule {
+  /** Run once per key: no refetch on focus, reconnect or remount (hydration reads). */
+  once?: boolean;
+  onError?: (error: unknown) => void;
+  onSuccess?: (data: T) => void;
+}
+export interface ReplicaQueryResult<T> {
+  data?: T;
+  error?: unknown;
+  isValidating: boolean;
+  /** Re-run this query. */
+  mutate: () => Promise<unknown>;
+}
+/**
+ * The query cache that schedules a replica's fetches: dedupe, focus /
+ * reconnect revalidation, retries. The replica decides what a response means;
+ * the driver only decides when to ask. `createSWRDriver` adapts SWR.
+ */
+export interface ReplicaSyncDriver {
+  /** Re-run every mounted query whose key matches. */
+  revalidate: (match: (key: unknown) => boolean) => Promise<unknown>;
+  /**
+   * Write a head response that `slice.fetch` requested outside `useQuery` into
+   * the query cache under its sync key, without re-running the query — so a
+   * `useQuery` of that key sees the latest data (a `revalidateIfStale: false`
+   * mount does not refetch it). Optional: a driver without a cache of its own
+   * leaves it out; requests still dedupe in the slice.
+   *
+   * The slice calls it only while no `useQuery` request of the key is in
+   * flight. A cache that discards in-flight requests a write overtakes (SWR
+   * does) would otherwise drop a newer response than the one written.
+   */
+  seed?: (key: readonly unknown[], data: unknown) => void;
+  useQuery: <T>(key: readonly unknown[] | null, fetcher: () => Promise<T>, options: ReplicaQueryOptions<T>) => ReplicaQueryResult<T>;
+}
+type SWRLikeHook = (key: any, fetcher: any, config?: any) => {
+  data?: any;
+  error?: unknown;
+  isValidating: boolean;
+  mutate: () => Promise<any>;
+};
+/**
+ * Driver over SWR. Pass the app's own hook and scoped `mutate` when it wraps
+ * SWR (custom cache provider, key augmentation, retry policy).
+ */
+export declare const createSWRDriver: ({ mutate, useSWR }: {
+  /**
+   * SWR's (scoped) `mutate`. Called as `mutate(match)` to revalidate, and as
+   * `mutate(key, data, { revalidate: false })` to seed — pass the arguments
+   * through unchanged: SWR tells a revalidation from a write by their count.
+   */
+  mutate: (...args: [match: (key: any) => boolean] | [key: unknown, data: unknown, options: object]) => Promise<unknown>;
+  useSWR: SWRLikeHook;
+}) => ReplicaSyncDriver;
+/** Zustand `setState`, with the devtools action label. */
+type Setter<TStore> = (partial: Partial<TStore>, replace?: false, action?: any) => void;
+/**
+ * One `key` write in a batched lens update (see {@link ReplicaLens.setMany}).
+ */
+export interface ReplicaViewSet<TData> {
+  data: TData | undefined;
+  key: string;
+}
+/**
+ * Where the materialized value lives in the domain store. Selectors keep
+ * reading this location; the slice is the only writer.
+ */
+export interface ReplicaLens<TStore, TData> {
+  clear: (state: TStore) => Partial<TStore>;
+  get: (state: TStore, key: string) => TData | undefined;
+  /** Enumerate loaded keys (needed for entity propagation). */
+  keys?: (state: TStore) => string[];
+  set: (state: TStore, key: string, data: TData | undefined) => Partial<TStore>;
+  /**
+   * Apply several key writes in one pass — one clone of the backing field
+   * instead of one per key. Optional: the slice falls back to repeated `set`
+   * when a lens does not implement it.
+   */
+  setMany?: (state: TStore, entries: ReplicaViewSet<TData>[]) => Partial<TStore>;
+}
+export interface CreateReplicaSliceOptions<TStore, TParams, TData, TFetched> extends Omit<ReplicaEngineOptions<TParams, TData, TFetched>, 'port' | 'revalidate'> {
+  /** Query cache that schedules fetches (see `createSWRDriver`). */
+  driver: ReplicaSyncDriver;
+  /**
+   * Side effects of the resource itself, run by every head response — a
+   * mounted `useSync` and an imperative `fetch` alike — after the response is
+   * folded in (see {@link ReplicaEffects}).
+   */
+  effects?: ReplicaEffects<TParams, TFetched>;
+  get: () => TStore;
+  set: Setter<TStore>;
+  /** Store field holding the {@link ReplicaState} bookkeeping slot. */
+  stateKey: keyof TStore & string;
+  /** Where the view lives in the store; `recordLens(field)` covers `Record<key, TData>`. */
+  view: ReplicaLens<TStore, TData>;
+}
+/**
+ * What a failed sync read was captured under. `scope` is the cache scope active
+ * when the request was issued, which may differ from the scope active when the
+ * callback runs (an identity / workspace switch in between).
+ */
+export interface ReplicaSyncErrorContext {
+  /**
+   * Whether the captured `scope` is still the one the store is on. A failure
+   * with `isActive: false` belongs to an identity / workspace the store has
+   * left: surface it on the *current* view only when this is true, while still
+   * using the captured `key` / `scope` to clean up the scope it came from.
+   */
+  isActive: boolean;
+  /** The entry key the read was for; `undefined` for a disabled read. */
+  key: string | undefined;
+  /** The cache scope the read was captured under. */
+  scope: string;
+}
+/** Where a settled head response was captured, for {@link ReplicaEffects}. */
+export interface ReplicaSettleContext {
+  key: string;
+  /** The cache scope the request was captured under (the active one, except for `onPurge`). */
+  scope: string;
+  /** Which path requested it: a mounted `useSync`, or `slice.fetch`. */
+  source: 'fetch' | 'sync';
+}
+/**
+ * Resource-level side effects of head responses. Unlike `useSync`'s per-call
+ * `onSuccess` / `onError` (UI callbacks of one mounted view), these run for
+ * every response the resource settles, whichever path requested it — so a
+ * store that fetches while no view is mounted keeps the same side effects.
+ *
+ * They run only for a response that passed every guard (clear, removal, active
+ * query, a newer response already applied) and, for `onApplied` / `onMissing`,
+ * only when its captured scope is still the active one.
+ */
+export interface ReplicaEffects<TParams, TFetched> {
+  /**
+   * A response was folded into the active scope (`prepareHead` kept it and it
+   * is not a terminal absence). Runs even when the value did not change.
+   */
+  onApplied?: (data: TFetched, params: TParams, context: ReplicaSettleContext) => void;
+  /**
+   * A failed head read. Like `useSync`'s `onError`, it is forwarded off-scope
+   * too, with `isActive: false`: use the captured key / scope to clean up that
+   * scope, and touch the view on screen only when `isActive`.
+   */
+  onError?: (error: unknown, params: TParams, context: ReplicaSyncErrorContext) => void;
+  /**
+   * The response was a terminal absence (`isMissing`) and the entry was
+   * removed from the active scope. An absence captured under a scope the store
+   * has left purges that scope's row and runs `onPurge` instead.
+   */
+  onMissing?: (params: TParams, context: ReplicaSettleContext) => void;
+  /**
+   * A terminal absence captured under a scope the store has since left. The
+   * entry's row in that scope is already purged; purge what other resources
+   * keep of it there (a linked list row). Never touch the view on screen.
+   */
+  onPurge?: (params: TParams, context: ReplicaSettleContext) => void;
+}
+export interface ReplicaFetchOptions {
+  /**
+   * Start a new request even when one for the same entry is in flight, and
+   * retire every request started before it: a late response of an older one
+   * is dropped instead of applied. Use it for refreshes after a mutation,
+   * where an in-flight request may hold the pre-mutation value. By default
+   * `fetch` joins the request in flight (a `useSync` one or another `fetch`).
+   */
+  fresh?: boolean;
+  /**
+   * The cache scope the fetch belongs to, captured by a caller that started a
+   * multi-step flow earlier (a warmup fanning out from a parent response). The
+   * response settles into that scope under the same off-scope rules as any
+   * other. When the scope is no longer active the fetch rejects without a
+   * request: it would read the new identity's data under the old one's label.
+   * Defaults to the active scope.
+   */
+  scope?: string;
+}
+export interface ReplicaFetchResult<TFetched> {
+  /**
+   * Whether the response was settled into the active scope: folded in, or
+   * applied as a terminal absence. `false` when a guard dropped it (scope
+   * switch, `remove` / `clear` mid-flight, superseded) or `prepareHead` did.
+   */
+  applied: boolean;
+  /** The response as fetched, also when it was not applied. */
+  data: TFetched;
+  /** The response was a terminal absence (`isMissing`), in whichever scope. */
+  missing: boolean;
+}
+export interface ReplicaSyncOptions<TFetched = unknown, TData = unknown> extends ReplicaSyncSchedule {
+  enabled?: boolean;
+  /**
+   * Side effects of a failed fetch (error side-maps); the store view is left as is.
+   * Receives the captured {@link ReplicaSyncErrorContext} so a terminal removal
+   * can target the scope the request belonged to rather than the one that is
+   * active once the callback runs.
+   */
+  onError?: (error: unknown, context: ReplicaSyncErrorContext) => void;
+  /**
+   * Side effects of a hydrated persisted value, run after it is folded into the
+   * replica. A cold start with no network (offline / slow) has no response for
+   * `onSuccess` to run on, so the same "success" handling must also run off the
+   * persisted value it paints.
+   */
+  onHydrated?: (data: TData) => void;
+  /**
+   * Side effects of a response, run after it is folded into the replica
+   * (e.g. adopting an active id). UI callbacks of this view only: effects every
+   * response of the resource needs belong in the slice's `effects`, which
+   * `fetch` runs too.
+   */
+  onSuccess?: (data: TFetched) => void;
+}
+export interface ReplicaSyncResult {
+  error: unknown;
+  /** The persisted row has been read (or there is nothing to read). */
+  isHydrated: boolean;
+  /** A network request is in flight. Never a reason to hide store data. */
+  isValidating: boolean;
+  /** Re-run the network sync for this entry. */
+  revalidate: () => Promise<unknown>;
+}
+/** `slice.fetch` was asked to fetch for a scope that is no longer active. */
+export declare class ReplicaScopeChangedError extends Error {
+  constructor(name: string, scope: string);
+}
+export interface ReplicaSyncResult {
+  error: unknown;
+  /** The persisted row has been read (or there is nothing to read). */
+  isHydrated: boolean;
+  /** A network request is in flight. Never a reason to hide store data. */
+  isValidating: boolean;
+  /** Re-run the network sync for this entry. */
+  revalidate: () => Promise<unknown>;
+}
+/**
+ * Bind a replica to a domain Zustand store.
+ *
+ * The domain store stays the only UI source of truth: components read the
+ * `view` location through their usual selectors. The engine owns every
+ * transition of that location; this slice adds the Zustand port and a
+ * `useSync` hook that only orchestrates fetching — data never flows through
+ * its return value.
+ */
+export declare const createReplicaSlice: <TStore, TParams, TData, TFetched = TData>(resource: ReplicaResource<TParams, TData, TFetched>, { driver, effects, get, set, stateKey, view, ...options }: CreateReplicaSliceOptions<TStore, TParams, TData, TFetched>) => {
+  applyHead: (params: TParams, fetched: TFetched, scope?: string) => {
+    changed: boolean;
+    outcome: ReplicaHeadOutcome;
+  };
+  beginEntityOptimistic: <TItem>(id: string, fn: (item: TItem) => TItem | undefined) => ReplicaOptimisticToken<TData>[];
+  beginOptimistic: (key: string, apply: (data: TData) => TData, query?: string) => ReplicaOptimisticToken<TData>;
+  clear: () => Promise<boolean>;
+  clearGeneration: (scope: string) => number;
+  clearScope: (scope: string) => Promise<boolean>;
+  removalGeneration: (scope: string, key: string) => number;
+  collapse: (key: string) => boolean;
+  dispatch: (action: ReplicaAction<TData>) => boolean;
+  ensureScope: (scope: string) => void;
+  entityKeys: (id: string) => string[];
+  fetcher: ((params: TParams, cursor?: any) => Promise<TFetched>) | undefined;
+  getConfirmed: (key: string) => TData | undefined;
+  hydrate: (params: TParams, scope?: string, { overwrite }?: {
+    overwrite?: boolean;
+  }) => Promise<boolean>;
+  insertHead: <TItem>(key: string, items: TItem[], { persist }?: {
+    persist?: boolean | undefined;
+  }) => boolean;
+  isMissingHead: (incoming: TFetched) => boolean;
+  loadMore: (key: string, fallbackParams?: TParams | undefined) => Promise<void>;
+  optimistic: <TResult>(key: string, apply: (data: TData) => TData, serverCall: () => Promise<TResult>, mutationOptions?: OptimisticMutationOptions<TData, TResult>) => Promise<TResult>;
+  patchStoredEntity: <TItem>(id: string, fn: (item: TItem) => TItem | undefined) => Promise<void>;
+  patchStoredRows: (fn: (data: TData) => TData | null | undefined) => Promise<void>;
+  persist: (key: string) => void;
+  removeEntity: (id: string, options?: {
+    persist?: boolean;
+    scope?: string;
+  } | undefined) => void;
+  replace: (params: TParams, fetched: TFetched, scope?: string) => boolean;
+  resource: ReplicaResource<TParams, TData, TFetched, any>;
+  retain: (key: string, queryKey?: string) => () => void;
+  revalidate: (key?: string) => Promise<unknown>;
+  update: (key: string, apply: (data: TData | undefined) => TData | undefined, { persist, seedTag, source }?: {
+    persist?: boolean;
+    seedTag?: string;
+    source?: ReplicaSource;
+  }) => boolean;
+  updateEntity: <TItem>(id: string, fn: (item: TItem) => TItem | undefined, options?: {
+    persist?: boolean;
+    scope?: string;
+  } | undefined) => void;
+  updateMany: (entries: {
+    apply: (data: TData | undefined) => TData | undefined;
+    key: string;
+  }[], { persist, seedTag, source }?: {
+    persist?: boolean;
+    seedTag?: string;
+    source?: ReplicaSource;
+  }) => boolean;
+  /** @internal Records of `useSync` requests not yet released (leak checks in tests). */
+  debugPendingSyncRequests: () => number;
+  /** @internal Retirement records still held (leak checks in tests). */
+  debugRetiredRequests: () => number;
+  fetch: (params: TParams, { fresh, scope }?: ReplicaFetchOptions) => Promise<ReplicaFetchResult<TFetched>>;
+  remove: (key: string, scope?: string) => boolean;
+  useSync: (params: TParams | null | undefined, { enabled, onError, onHydrated, onSuccess, ...schedule }?: ReplicaSyncOptions<TFetched, TData>) => ReplicaSyncResult;
+};
+export type ReplicaSlice<TStore, TParams, TData, TFetched = TData> = ReturnType<typeof createReplicaSlice<TStore, TParams, TData, TFetched>>;
+/** Lens for the common case: a `Record<key, TData>` field on the store. */
+export declare const recordLens: <TStore, TData>(field: keyof TStore & string) => ReplicaLens<TStore, TData>;
+/**
+ * Lens for a paged view split across store fields: the rows stay where
+ * existing readers expect them (`itemsField[key]`, a plain array), the paging
+ * bookkeeping lives in `metaField[key]`, and `derive` recomputes fields built
+ * from the rows (e.g. a parsed display list) in the same commit — so a derived
+ * field is never one frame behind its rows.
+ *
+ * Rows seeded without bookkeeping (by code outside the replica) read as a
+ * single head page.
+ */
+export declare const splitPagedLens: <TStore, TItem, TCursor = unknown>({ clearDerived, derive, itemsField, metaField }: {
+  /** Derived fields to reset on a scope change. */
+  clearDerived?: () => Partial<TStore>;
+  /** Fields computed from an entry's rows (`undefined` = the entry is gone). */
+  derive?: (state: TStore, key: string, items: TItem[] | undefined) => Partial<TStore>;
+  itemsField: keyof TStore & string;
+  metaField: keyof TStore & string;
+}) => ReplicaLens<TStore, ReplicaPagedData<TItem, TCursor>>;
+export {};
+//# sourceMappingURL=index.d.ts.map