@taladb/react 0.10.2 → 0.11.1

package/dist/index.d.mts

@@ -1,13 +1,13 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { CollectionOptions, Document, TalaDB, OpenDBOptions, Collection, Filter, AggregatePipeline, RestSourceOptions, ReplicationSource, CoverageState } from 'taladb';
+import { CollectionOptions, Document, TalaDB, OpenDBOptions, Collection, Filter, AggregatePipeline } from 'taladb';
 
 /**
  * Per-collection options (`schema`, `syncSchema`, `migrateDocument`, …), keyed by
  * collection name.
  *
  * Register them once on the provider and every hook below it — `useCollection`,
- * and therefore `useFind`, `useQuery` and `useMutation` — resolves a *configured*
+ * and therefore `useFind`, `useFindOne` and `useWrite` — resolves a *configured*
  * collection. Without this, those hooks call `db.collection(name)` with no
  * options, so a hook-driven write silently skips the strict `schema` validation
  * and the `_v` stamp that `db.collection(name, { … })` would have applied.
@@ -16,6 +16,16 @@ type CollectionRegistry = Record<string, CollectionOptions<any>>;
 /** Resolves the registered options for a collection. Stable across renders. */
 interface CollectionResolver {
     get<T extends Document>(name: string): CollectionOptions<T> | undefined;
+    /**
+     * Every registered collection name, or `[]` when the provider declared none.
+     *
+     * `get` alone cannot tell "this name is not registered" from "nothing is
+     * registered at all", and that distinction is the difference between an error
+     * and a warning for anything validating a name it inferred rather than was
+     * given — see `@taladb/react/query`'s collection resolution, which refuses to
+     * guess against a populated registry but must stay usable without one.
+     */
+    names(): string[];
 }
 declare function useCollectionOptions(): CollectionResolver;
 type SharedProps = {
@@ -92,7 +102,7 @@ declare function useTalaDB(): TalaDB;
  * The collection is opened **with its registered options** — the `schema`,
  * `syncSchema` and `migrateDocument` declared in the provider's `collections`
  * prop, or the `options` passed here (which win). That is what makes a write
- * through `useMutation` hard-fail on an invalid document and carry its `_v`
+ * through `useWrite` hard-fail on an invalid document and carry its `_v`
  * shape version, exactly as `db.collection(name, { … })` does. Without it the
  * hooks resolve a bare, unconfigured handle and silently skip validation.
  *
@@ -197,283 +207,7 @@ interface AggregateResult<R> {
  */
 declare function useAggregate<T extends Document, R extends Document = T>(collection: Collection<T>, pipeline: AggregatePipeline<T>): AggregateResult<R>;
 
-/** Resolved network configuration for one replicated slice. */
-interface ResolvedReplicationConfig {
-    /** Base URL; `/push` and `/pull` are appended by {@link HttpSyncAdapter}. */
-    endpoint: string;
-    /**
-     * Async (or sync) resolver for per-request headers — typically the
-     * `Authorization` bearer. Called **once per pass, at send time**, so a token
-     * that refreshed while a write sat in the local database is picked up when the
-     * write finally flushes.
-     */
-    getAuth?: () => Promise<Record<string, string>> | Record<string, string>;
-    /** `fetch` implementation. Defaults to the global `fetch`. */
-    fetch?: typeof fetch;
-    /** Override the `/push` and `/pull` sub-paths to match an existing API. */
-    paths?: {
-        push?: string;
-        pull?: string;
-    };
-}
-
-/** When the background hydration walk is allowed to start. */
-type HydrateMode = 
-/** Immediately on mount. */
-'eager'
-/** When the browser is idle (default). Keeps first paint responsive. */
- | 'idle'
-/** Never automatically — the app calls `hydrate()` itself. */
- | 'manual';
-interface ReplicateScope<RemoteRow = any, T extends Document = Document> extends Omit<RestSourceOptions<RemoteRow, T>, 'collection'> {
-    /**
-     * Provide a fully custom source instead of the REST defaults. When present,
-     * every other field here is ignored.
-     */
-    source?: ReplicationSource<RemoteRow, T>;
-    hydrate?: HydrateMode;
-    /** Rows per bootstrap page. Default 500. */
-    pageSize?: number;
-    /** Re-check the origin for changes on this interval. `0` disables. */
-    refreshMs?: number;
-    /**
-     * Fetch the current query directly when coverage isn't ready yet, so a cold
-     * start paints immediately. Default `true`.
-     *
-     * Mandatory in practice for a Vite SPA or React Native, which have no server
-     * render to paint behind while the replica fills.
-     */
-    bridge?: boolean;
-}
-/** One entry per local collection. */
-type ReplicateRegistry = Record<string, ReplicateScope<any, any>>;
-
-/** A slice to warm on first run — a collection, optionally on a specific endpoint. */
-type PrefetchSlice = {
-    collection: string;
-    endpoint?: string;
-};
-/** A prefetch entry: a collection name (shorthand) or a {@link PrefetchSlice}. */
-type PrefetchEntry = string | PrefetchSlice;
-/** `'once'` warms a slice only if it has never synced; `'always'` on every mount. */
-type PrefetchMode = 'once' | 'always';
-/**
- * Replication settings shared by `useQuery` / `useMutation`, supplied once by
- * `<ReplicationProvider>` and overridable per hook.
- *
- * The origin is *your* API — never a database credential. It authorizes the
- * session token from {@link ReplicationConfig.getAuth} and returns only that
- * user's slice, so the auth header doubles as the per-user scope.
- */
-interface ReplicationConfig {
-    /** Base sync URL, e.g. `/api/sync`. `/push` and `/pull` are appended. */
-    endpoint: string;
-    /**
-     * Per-request header resolver — typically `{ Authorization: 'Bearer …' }`.
-     * Async so it can await a token refresh. Resolved at **send time**, once per
-     * pass, so an offline write flushed later carries a current token.
-     */
-    getAuth?: () => Promise<Record<string, string>> | Record<string, string>;
-    /** `fetch` implementation. Defaults to the global `fetch`. */
-    fetch?: typeof fetch;
-    /** Override the `/push` and `/pull` sub-paths to match an existing API. */
-    paths?: {
-        push?: string;
-        pull?: string;
-    };
-    /**
-     * Default background refresh interval (ms) for `useQuery`. A replication
-     * *interval*, not a cache TTL — the local data is never evicted, only
-     * refreshed. Omit or set `0` to disable polling by default; a hook can still
-     * opt in per query. `30_000` matches the guide's own example cadence.
-     */
-    pollMs?: number;
-    /**
-     * Slices to warm into the local replica in the background on first run, so a
-     * later `useQuery` for that collection reads local instead of waiting on the
-     * network. Best-effort and non-blocking: deferred to browser idle, run in the
-     * sync Worker on web, and silently skipped on failure. Each entry is a
-     * collection name or a {@link PrefetchSlice}.
-     */
-    prefetch?: PrefetchEntry[];
-    /** How prefetch decides to warm a slice. Default `'once'`. */
-    prefetchMode?: PrefetchMode;
-    /** Max concurrent prefetch pulls — keeps the active page from starving. Default `2`. */
-    prefetchConcurrency?: number;
-}
-interface ReplicationProviderProps extends Partial<ReplicationConfig> {
-    /**
-     * Collections to replicate from a remote origin, keyed by local collection name.
-     *
-     * This is what makes `useQuery` a local read: once a collection is fully
-     * hydrated for its scope, filtering, sorting and paging never touch the network.
-     * See {@link ReplicateRegistry}.
-     */
-    replicate?: ReplicateRegistry;
-    children: ReactNode;
-}
-/**
- * Supplies replication defaults (endpoint, auth, poll interval, prefetch) to the
- * `useQuery` / `useMutation` hooks below it. Compose it inside a
- * `<TalaDBProvider>`:
- *
- * ```tsx
- * <TalaDBProvider name="app.db" fallback={<Splash />}>
- *   <ReplicationProvider
- *     endpoint="/api/sync"
- *     getAuth={async () => ({ Authorization: `Bearer ${await session.token()}` })}
- *     pollMs={30_000}
- *     prefetch={['products', 'categories']}
- *   >
- *     <App />
- *   </ReplicationProvider>
- * </TalaDBProvider>
- * ```
- */
-declare function ReplicationProvider({ children, replicate, ...config }: ReplicationProviderProps): react_jsx_runtime.JSX.Element;
-/**
- * Read the nearest replication config, merged with per-hook overrides.
- * Non-throwing: `config` is `null` when no endpoint is resolvable (valid for
- * `source: 'local-only'`); the caller decides whether that's an error.
- */
-declare function useReplicationConfig(overrides?: Partial<ReplicationConfig>): {
-    config: ResolvedReplicationConfig | null;
-    pollMs: number;
-};
-
-interface Coverage {
-    /** The raw state machine value. */
-    status: CoverageState['status'];
-    /**
-     * Whether a purely local read is authorized.
-     *
-     * True **only** for `complete`. Notably *not* for `best-effort`, which means we
-     * applied every row the origin gave us but the origin could not pin a snapshot —
-     * so a row that shifted between pages during the walk may never have been seen,
-     * and we cannot prove the replica is whole. Serving that as authoritative would
-     * silently return incomplete results, which is worse than going to the network.
-     */
-    ready: boolean;
-    /** Rows hydrated so far. */
-    rows: number;
-    /** Total rows in scope when supplied by the origin. */
-    total?: number;
-    /** 0–1 when the origin reported a total; otherwise undefined. */
-    progress?: number;
-    /** Present on `error`, `stale` and `best-effort`. */
-    reason?: string;
-}
-/**
- * How much of a collection is local, and whether it can be trusted for a
- * network-free read.
- *
- * @example
- * const { ready, progress } = useCoverage('products')
- * if (!ready) return <ProgressBar value={progress} />
- */
-declare function useCoverage(collection: string): Coverage;
-/** Semantic alias for progress-oriented UIs. */
-declare const useHydrationProgress: typeof useCoverage;
-
-type ReadSource = 'local-first' | 'remote-first' | 'local-only';
-interface UseQueryOptions<T extends Document> extends Partial<Pick<ReplicationConfig, 'endpoint' | 'getAuth' | 'fetch' | 'paths' | 'pollMs'>> {
-    /** The local collection to read. */
-    collection: string;
-    /** Mongo-style filter, applied **locally**. */
-    filter?: Filter<T>;
-    /** Sort, applied locally. `1` ascending, `-1` descending. */
-    sort?: Partial<Record<keyof T & string, 1 | -1>>;
-    /** 1-based page number. Requires `limit`. */
-    page?: number;
-    /** Rows per page. */
-    limit?: number;
-    /** Skip N rows. Ignored when `page` is set. */
-    skip?: number;
-    /** Skip the query entirely (e.g. while a route param is undefined). */
-    enabled?: boolean;
-    /** Legacy sync-contract read policy. Used when no full-replication scope exists. */
-    source?: ReadSource;
-}
-interface QueryResult<T> {
-    /** The current page. Reactive: re-renders as rows land. */
-    data: T[];
-    /** Total rows in the replicated scope when reported by the origin. */
-    total?: number;
-    /** True until the first local snapshot arrives. */
-    loading: boolean;
-    /** Most recent local read error. */
-    error: unknown | null;
-    /** Most recent cold-start bridge error. */
-    fetchError: unknown | null;
-    /** How much of the collection is local, and whether it is trustworthy. */
-    coverage: Coverage;
-    /**
-     * A cold-start bridge fetch is in flight — we are serving the network because
-     * the replica isn't complete yet.
-     */
-    fetching: boolean;
-    /** Legacy sync-contract pull in progress. */
-    syncing: boolean;
-    /** Legacy sync-contract pull error. */
-    syncError: unknown | null;
-    /** Force a delta refresh from the origin. */
-    refetch: () => Promise<void>;
-}
-/**
- * Read a page of a collection.
- *
- * ## The point
- *
- * Once the collection is **covered** — fully replicated for this scope — this hook
- * touches the network **zero times**. Filtering, sorting and paging are local
- * queries against the on-device database. Page 1 → page 2 → a new filter → page 47
- * → back to page 1: every one is a local read, instant and offline-capable.
- * Pagination stops being a network concern at all.
- *
- * That is the whole reason to put a real database on the device. A cache of API
- * pages could only ever answer the queries you already asked; a *covered replica*
- * answers queries nobody has asked yet.
- *
- * ## Before coverage lands
- *
- * On a cold start the replica is empty, and a SPA or React Native app has no server
- * render to paint behind. So the hook **bridges**: it fetches exactly the rows this
- * query needs and writes them into the same collection, under the same derived ids
- * the background walk will use. Those rows are not a cache entry to be reconciled
- * later — they are the replica, arriving early. When the walk reaches them it
- * overwrites them in place.
- *
- * @example
- * const { data, coverage } = useQuery<Product>({
- *   collection: 'products',
- *   filter: { category: 'kitchen', price: { $lt: 500 } },
- *   sort: { price: 1 },
- *   page: 2,
- *   limit: 100,
- * })
- */
-declare function useQuery<T extends Document>(options: UseQueryOptions<T>): QueryResult<T>;
-
-/**
- * Several pages at once, from several collections. Index-aligned with `queries`.
- *
- * Hooks can't be called in a variable-length loop, so this manages its own
- * subscriptions rather than calling `useQuery` N times. Behaviour is otherwise
- * identical: once a collection is covered, its read is purely local.
- *
- * TalaDB is a document store with no cross-collection joins, so a page needing
- * several collections composes them in the component (or denormalises at the
- * origin). This is the hook for that.
- *
- * @example
- * const [products, categories] = useQueries([
- *   { collection: 'products', filter: { category }, sort: { price: 1 }, page, limit: 50 },
- *   { collection: 'categories' },
- * ])
- */
-declare function useQueries(queries: UseQueryOptions<Document>[]): QueryResult<Document>[];
-
-/** A single write intent against the local replica. Discriminated on `type`. */
+/** A single write intent. Discriminated on `type`. */
 type WriteOp<T extends Document> = {
     type: 'insert';
     doc: Omit<T, '_id'>;
@@ -485,45 +219,42 @@ type WriteOp<T extends Document> = {
     type: 'delete';
     where: Filter<T>;
 };
-interface UseMutationOptions extends Partial<Pick<ReplicationConfig, 'endpoint' | 'getAuth' | 'fetch' | 'paths'>> {
+interface UseWriteOptions {
     /** Collection the write targets. */
     collection: string;
-    /**
-     * Replication direction for the drain. `push` *(default)* sends the write;
-     * read hooks reconcile the authoritative value on their next pull. `both`
-     * also pulls the authoritative echo inline (heavier — replays the collection).
-     */
-    direction?: 'push' | 'both';
-    /**
-     * On mount, attempt to flush any local writes left unsent from a previous
-     * (offline) session for this collection. Default `true`.
-     */
-    drainOnMount?: boolean;
 }
-interface MutationResult<T extends Document> {
+interface WriteResult<T extends Document> {
     /** Fire-and-forget write. Errors surface on `error`, never thrown to render. */
-    mutate: (op: WriteOp<T>) => void;
-    /** Awaitable write. Resolves once the local write and drain settle; rejects on error. */
-    mutateAsync: (op: WriteOp<T>) => Promise<void>;
-    /** A write (local + drain) is in flight. */
+    write: (op: WriteOp<T>) => void;
+    /** Awaitable write. Resolves once the write commits; rejects on error. */
+    writeAsync: (op: WriteOp<T>) => Promise<void>;
+    /** A write is in flight. */
     pending: boolean;
-    /** Most recent write/drain error. The local write is durable regardless. */
+    /** Most recent write error. */
     error: unknown | null;
 }
 /**
- * Local-first write hook. A mutation writes the local replica **first**
- * (immediate, durable, reactive — every `useQuery`/`useFind` on the collection
- * re-renders) and then replicates the change outward over the sync-contract with
- * bounded retry. The network step never rolls the local write back: it is
- * already committed, and a later drain still delivers it (write-behind).
+ * Write hook over a TalaDB collection.
+ *
+ * The write is local, immediate, durable, and reactive — every `useFind` /
+ * `useFindOne` / `useAggregate` subscribed to the collection re-renders once it
+ * commits. There is no network step in this hook and no rollback to reason
+ * about: the database is on the device, and the write either committed or threw.
+ *
+ * Named `useWrite`, not `useMutation`, because it is exactly a local write and
+ * nothing more. The React Query-shaped name belongs to a hook that also owns a
+ * network round-trip; this one would only borrow the expectation and then fail
+ * to meet it.
  *
- * Write-authority is origin-authoritative by default — the push sends the
- * change and the server is the arbiter; read hooks pull the authoritative value.
+ * If the application has enabled the change webhook (`openDB({ webhook })`),
+ * the resulting HTTP request is dispatched by the client after the commit,
+ * outside this hook and outside `pending` — a webhook is a notification, not
+ * part of the write's success.
  *
  * @example
- * const { mutate, pending } = useMutation<Order>({ collection: 'orders' })
- * mutate({ type: 'update', where: { _id }, set: { status: 'shipped' } })
+ * const { write, pending } = useWrite<Order>({ collection: 'orders' })
+ * write({ type: 'update', where: { _id }, set: { status: 'shipped' } })
  */
-declare function useMutation<T extends Document>(options: UseMutationOptions): MutationResult<T>;
+declare function useWrite<T extends Document>(options: UseWriteOptions): WriteResult<T>;
 
-export { type AggregateResult, type CollectionRegistry, type CollectionResolver, type Coverage, type FindOneResult, type FindResult, type HydrateMode, type MutationResult, type PrefetchEntry, type PrefetchMode, type PrefetchSlice, type QueryResult, type ReplicateRegistry, type ReplicateScope, type ReplicationConfig, ReplicationProvider, type ReplicationProviderProps, TalaDBProvider, type TalaDBProviderProps, type UseMutationOptions, type UseQueryOptions, type WriteOp, useAggregate, useCollection, useCollectionOptions, useCoverage, useFind, useFindOne, useHydrationProgress, useMutation, useQueries, useQuery, useReplicationConfig, useTalaDB };
+export { type AggregateResult, type CollectionRegistry, type CollectionResolver, type FindOneResult, type FindResult, TalaDBProvider, type TalaDBProviderProps, type UseWriteOptions, type WriteOp, type WriteResult, useAggregate, useCollection, useCollectionOptions, useFind, useFindOne, useTalaDB, useWrite };