@taladb/react 0.9.0 → 0.9.1

package/dist/index.d.mts

@@ -118,4 +118,233 @@ interface FindOneResult<T> {
  */
 declare function useFindOne<T extends Document>(collection: Collection<T>, filter: Filter<T>): FindOneResult<T>;
 
-export { type FindOneResult, type FindResult, TalaDBProvider, type TalaDBProviderProps, useCollection, useFind, useFindOne, useTalaDB };
+/** 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;
+    };
+}
+
+/** 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 ReplicationConfig {
+    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, ...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;
+};
+
+/**
+ * How a `useQuery` combines the local replica with the remote origin.
+ * *(`remote-only` is a planned addition; the durable-replica model makes it a
+ * rare escape hatch.)*
+ */
+type ReadSource = 'local-first' | 'remote-first' | 'local-only';
+interface UseQueryOptions<T extends Document> extends Partial<Pick<ReplicationConfig, 'endpoint' | 'getAuth' | 'fetch' | 'paths' | 'pollMs'>> {
+    /** Collection name — replicated as a whole; the `filter` narrows locally. */
+    collection: string;
+    /** Live filter over the local collection. Inline objects are safe. */
+    filter?: Filter<T>;
+    /**
+     * - `local-first` *(default)* — serve local immediately; refresh in the
+     *   background, and the live query re-renders when the pull lands.
+     * - `remote-first` — stay `loading` until the first pull completes, then serve.
+     * - `local-only` — never touch the network (no endpoint required).
+     */
+    source?: ReadSource;
+}
+interface QueryResult<T> {
+    /** Current matching documents from the local replica. Reactive. */
+    data: T[];
+    /** First local snapshot pending — plus the first pull, for `remote-first`. */
+    loading: boolean;
+    /** Most recent local-read error. */
+    error: unknown | null;
+    /** A background replication pass is in flight. */
+    syncing: boolean;
+    /** Most recent replication error (the local data is still served). */
+    syncError: unknown | null;
+    /** Trigger a pull now. No-op for `local-only`. */
+    refetch: () => Promise<void>;
+}
+/**
+ * Bind a component to a slice of a remote origin, backed by the local replica.
+ *
+ * The read is a live query over the local collection (`useFind`); the network
+ * pull writes into that same collection, so the live query re-renders on its
+ * own — one-way data flow, no `queryKey`, no `invalidateQueries`. See
+ * `docs/scoped-replication.md`.
+ *
+ * @example
+ * const { data, loading, syncing } = useQuery<Product>({
+ *   collection: 'products',
+ *   filter: { category: 'kitchen' },
+ *   pollMs: 30_000,
+ * })
+ */
+declare function useQuery<T extends Document>(options: UseQueryOptions<T>): QueryResult<T>;
+
+/**
+ * Run several scoped queries at once — one replication + live query per entry,
+ * in parallel. The result array is index-aligned with `queries`.
+ *
+ * Each entry is an independent `useQuery`: its own collection, filter, source,
+ * and (optionally) endpoint. This is the multi-slice page case — e.g. a
+ * dashboard that needs `orders` and `products` from the same origin. There are
+ * no cross-collection joins (TalaDB is a document store); compose in the
+ * component.
+ *
+ * v1 note: entries are typed as `Document`. For a strictly-typed single slice
+ * use `useQuery<T>`; per-entry generics (tuple typing) are a follow-up.
+ *
+ * @example
+ * const [orders, products] = useQueries([
+ *   { collection: 'orders', filter: { open: true } },
+ *   { collection: 'products' },
+ * ])
+ */
+declare function useQueries(queries: UseQueryOptions<Document>[]): QueryResult<Document>[];
+
+/** A single write intent against the local replica. Discriminated on `type`. */
+type WriteOp<T extends Document> = {
+    type: 'insert';
+    doc: Omit<T, '_id'>;
+} | {
+    type: 'update';
+    where: Filter<T>;
+    set: Partial<Omit<T, '_id'>>;
+} | {
+    type: 'delete';
+    where: Filter<T>;
+};
+interface UseMutationOptions extends Partial<Pick<ReplicationConfig, 'endpoint' | 'getAuth' | 'fetch' | 'paths'>> {
+    /** 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> {
+    /** 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. */
+    pending: boolean;
+    /** Most recent write/drain error. The local write is durable regardless. */
+    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-authority is origin-authoritative by default — the push sends the
+ * change and the server is the arbiter; read hooks pull the authoritative value.
+ *
+ * @example
+ * const { mutate, pending } = useMutation<Order>({ collection: 'orders' })
+ * mutate({ type: 'update', where: { _id }, set: { status: 'shipped' } })
+ */
+declare function useMutation<T extends Document>(options: UseMutationOptions): MutationResult<T>;
+
+export { type FindOneResult, type FindResult, type MutationResult, type PrefetchEntry, type PrefetchMode, type PrefetchSlice, type QueryResult, type ReadSource, type ReplicationConfig, ReplicationProvider, type ReplicationProviderProps, TalaDBProvider, type TalaDBProviderProps, type UseMutationOptions, type UseQueryOptions, type WriteOp, useCollection, useFind, useFindOne, useMutation, useQueries, useQuery, useReplicationConfig, useTalaDB };

package/dist/index.d.ts

@@ -118,4 +118,233 @@ interface FindOneResult<T> {
  */
 declare function useFindOne<T extends Document>(collection: Collection<T>, filter: Filter<T>): FindOneResult<T>;
 
-export { type FindOneResult, type FindResult, TalaDBProvider, type TalaDBProviderProps, useCollection, useFind, useFindOne, useTalaDB };
+/** 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;
+    };
+}
+
+/** 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 ReplicationConfig {
+    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, ...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;
+};
+
+/**
+ * How a `useQuery` combines the local replica with the remote origin.
+ * *(`remote-only` is a planned addition; the durable-replica model makes it a
+ * rare escape hatch.)*
+ */
+type ReadSource = 'local-first' | 'remote-first' | 'local-only';
+interface UseQueryOptions<T extends Document> extends Partial<Pick<ReplicationConfig, 'endpoint' | 'getAuth' | 'fetch' | 'paths' | 'pollMs'>> {
+    /** Collection name — replicated as a whole; the `filter` narrows locally. */
+    collection: string;
+    /** Live filter over the local collection. Inline objects are safe. */
+    filter?: Filter<T>;
+    /**
+     * - `local-first` *(default)* — serve local immediately; refresh in the
+     *   background, and the live query re-renders when the pull lands.
+     * - `remote-first` — stay `loading` until the first pull completes, then serve.
+     * - `local-only` — never touch the network (no endpoint required).
+     */
+    source?: ReadSource;
+}
+interface QueryResult<T> {
+    /** Current matching documents from the local replica. Reactive. */
+    data: T[];
+    /** First local snapshot pending — plus the first pull, for `remote-first`. */
+    loading: boolean;
+    /** Most recent local-read error. */
+    error: unknown | null;
+    /** A background replication pass is in flight. */
+    syncing: boolean;
+    /** Most recent replication error (the local data is still served). */
+    syncError: unknown | null;
+    /** Trigger a pull now. No-op for `local-only`. */
+    refetch: () => Promise<void>;
+}
+/**
+ * Bind a component to a slice of a remote origin, backed by the local replica.
+ *
+ * The read is a live query over the local collection (`useFind`); the network
+ * pull writes into that same collection, so the live query re-renders on its
+ * own — one-way data flow, no `queryKey`, no `invalidateQueries`. See
+ * `docs/scoped-replication.md`.
+ *
+ * @example
+ * const { data, loading, syncing } = useQuery<Product>({
+ *   collection: 'products',
+ *   filter: { category: 'kitchen' },
+ *   pollMs: 30_000,
+ * })
+ */
+declare function useQuery<T extends Document>(options: UseQueryOptions<T>): QueryResult<T>;
+
+/**
+ * Run several scoped queries at once — one replication + live query per entry,
+ * in parallel. The result array is index-aligned with `queries`.
+ *
+ * Each entry is an independent `useQuery`: its own collection, filter, source,
+ * and (optionally) endpoint. This is the multi-slice page case — e.g. a
+ * dashboard that needs `orders` and `products` from the same origin. There are
+ * no cross-collection joins (TalaDB is a document store); compose in the
+ * component.
+ *
+ * v1 note: entries are typed as `Document`. For a strictly-typed single slice
+ * use `useQuery<T>`; per-entry generics (tuple typing) are a follow-up.
+ *
+ * @example
+ * const [orders, products] = useQueries([
+ *   { collection: 'orders', filter: { open: true } },
+ *   { collection: 'products' },
+ * ])
+ */
+declare function useQueries(queries: UseQueryOptions<Document>[]): QueryResult<Document>[];
+
+/** A single write intent against the local replica. Discriminated on `type`. */
+type WriteOp<T extends Document> = {
+    type: 'insert';
+    doc: Omit<T, '_id'>;
+} | {
+    type: 'update';
+    where: Filter<T>;
+    set: Partial<Omit<T, '_id'>>;
+} | {
+    type: 'delete';
+    where: Filter<T>;
+};
+interface UseMutationOptions extends Partial<Pick<ReplicationConfig, 'endpoint' | 'getAuth' | 'fetch' | 'paths'>> {
+    /** 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> {
+    /** 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. */
+    pending: boolean;
+    /** Most recent write/drain error. The local write is durable regardless. */
+    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-authority is origin-authoritative by default — the push sends the
+ * change and the server is the arbiter; read hooks pull the authoritative value.
+ *
+ * @example
+ * const { mutate, pending } = useMutation<Order>({ collection: 'orders' })
+ * mutate({ type: 'update', where: { _id }, set: { status: 'shipped' } })
+ */
+declare function useMutation<T extends Document>(options: UseMutationOptions): MutationResult<T>;
+
+export { type FindOneResult, type FindResult, type MutationResult, type PrefetchEntry, type PrefetchMode, type PrefetchSlice, type QueryResult, type ReadSource, type ReplicationConfig, ReplicationProvider, type ReplicationProviderProps, TalaDBProvider, type TalaDBProviderProps, type UseMutationOptions, type UseQueryOptions, type WriteOp, useCollection, useFind, useFindOne, useMutation, useQueries, useQuery, useReplicationConfig, useTalaDB };

package/dist/index.js

@@ -31,10 +31,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ReplicationProvider: () => ReplicationProvider,
   TalaDBProvider: () => TalaDBProvider,
   useCollection: () => useCollection,
   useFind: () => useFind,
   useFindOne: () => useFindOne,
+  useMutation: () => useMutation,
+  useQueries: () => useQueries,
+  useQuery: () => useQuery,
+  useReplicationConfig: () => useReplicationConfig,
   useTalaDB: () => useTalaDB
 });
 module.exports = __toCommonJS(index_exports);
@@ -143,11 +148,404 @@ function useFindOne(collection, filter) {
   const getSnapshot = (0, import_react4.useCallback)(() => snapshotRef.current, []);
   return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
 }
+
+// src/replication/config.tsx
+var import_react5 = require("react");
+
+// src/replication/engine.ts
+var import_taladb = require("taladb");
+function replicationTarget(endpoint, collection) {
+  return `${endpoint}::${collection}`;
+}
+async function buildAdapter(config) {
+  const headers = config.getAuth ? await config.getAuth() : void 0;
+  return new import_taladb.HttpSyncAdapter({
+    endpoint: config.endpoint,
+    headers,
+    fetch: config.fetch,
+    paths: config.paths
+  });
+}
+var inflight = /* @__PURE__ */ new Map();
+function inflightKey(endpoint, collection, direction) {
+  return `${endpoint}::${collection}::${direction}`;
+}
+function replicate(db, config, collection, direction) {
+  const key = inflightKey(config.endpoint, collection, direction);
+  const existing = inflight.get(key);
+  if (existing) return existing;
+  const pass = (async () => {
+    const adapter = await buildAdapter(config);
+    await db.sync(adapter, {
+      collections: [collection],
+      direction,
+      target: replicationTarget(config.endpoint, collection)
+    });
+  })().finally(() => {
+    inflight.delete(key);
+  });
+  inflight.set(key, pass);
+  return pass;
+}
+var BACKOFFS_MS = [200, 400, 800];
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function replicateWithRetry(db, config, collection, direction) {
+  let lastError;
+  for (let attempt = 0; attempt <= BACKOFFS_MS.length; attempt++) {
+    try {
+      await replicate(db, config, collection, direction);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt < BACKOFFS_MS.length) await sleep(BACKOFFS_MS[attempt]);
+    }
+  }
+  throw lastError;
+}
+
+// src/replication/config.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var ReplicationContext = (0, import_react5.createContext)(null);
+function ReplicationProvider({ children, ...config }) {
+  const key = `${config.endpoint}|${config.pollMs ?? ""}|${JSON.stringify(config.paths ?? null)}|${JSON.stringify(config.prefetch ?? null)}|${config.prefetchMode ?? ""}|${config.prefetchConcurrency ?? ""}`;
+  const value = (0, import_react5.useMemo)(
+    () => config,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [key]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(ReplicationContext.Provider, { value, children: [
+    value.prefetch && value.prefetch.length > 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(PrefetchRunner, {}) : null,
+    children
+  ] });
+}
+function resolveReplicationConfig(base, overrides) {
+  const endpoint = overrides?.endpoint ?? base?.endpoint;
+  const pollMs = overrides?.pollMs ?? base?.pollMs ?? 0;
+  if (!endpoint) return { config: null, pollMs };
+  return {
+    config: {
+      endpoint,
+      getAuth: overrides?.getAuth ?? base?.getAuth,
+      fetch: overrides?.fetch ?? base?.fetch,
+      paths: overrides?.paths ?? base?.paths
+    },
+    pollMs
+  };
+}
+function useReplicationBase() {
+  return (0, import_react5.useContext)(ReplicationContext);
+}
+function useReplicationConfig(overrides) {
+  return resolveReplicationConfig((0, import_react5.useContext)(ReplicationContext), overrides);
+}
+var CURSOR_COLLECTION = "__taladb_sync";
+function normalizePrefetch(entries) {
+  return (entries ?? []).map((e) => typeof e === "string" ? { collection: e } : e);
+}
+var idleScheduler = (fn) => {
+  const g = globalThis;
+  if (typeof g.requestIdleCallback === "function") {
+    const id2 = g.requestIdleCallback(fn, { timeout: 2e3 });
+    return () => g.cancelIdleCallback?.(id2);
+  }
+  const id = setTimeout(fn, 0);
+  return () => clearTimeout(id);
+};
+var schedule = idleScheduler;
+async function hasSynced(db, target) {
+  try {
+    const doc = await db.collection(CURSOR_COLLECTION).findOne({ target });
+    return doc != null;
+  } catch {
+    return false;
+  }
+}
+function PrefetchRunner() {
+  const db = useTalaDB();
+  const base = useReplicationBase();
+  const slices = normalizePrefetch(base?.prefetch);
+  const mode = base?.prefetchMode ?? "once";
+  const concurrency = Math.max(1, base?.prefetchConcurrency ?? 2);
+  const baseRef = (0, import_react5.useRef)(base);
+  baseRef.current = base;
+  const sig = JSON.stringify({ slices, mode, concurrency, endpoint: base?.endpoint ?? null });
+  (0, import_react5.useEffect)(() => {
+    if (slices.length === 0) return void 0;
+    let cancelled = false;
+    const cancelSchedule = schedule(() => {
+      void run();
+    });
+    async function run() {
+      const b = baseRef.current;
+      const queue = normalizePrefetch(b?.prefetch);
+      const worker = async () => {
+        while (!cancelled) {
+          const slice = queue.shift();
+          if (!slice) return;
+          const { config } = resolveReplicationConfig(b, { endpoint: slice.endpoint });
+          if (!config) continue;
+          const target = replicationTarget(config.endpoint, slice.collection);
+          if (mode === "once" && await hasSynced(db, target)) continue;
+          if (cancelled) return;
+          try {
+            await replicate(db, config, slice.collection, "pull");
+          } catch {
+          }
+        }
+      };
+      const lanes = Math.min(concurrency, queue.length);
+      await Promise.all(Array.from({ length: lanes }, () => worker()));
+    }
+    return () => {
+      cancelled = true;
+      cancelSchedule();
+    };
+  }, [db, sig]);
+  return null;
+}
+
+// src/useQuery.ts
+var import_react6 = require("react");
+function useQuery(options) {
+  const { collection, filter, source = "local-first" } = options;
+  const networked = source !== "local-only";
+  const db = useTalaDB();
+  const col = useCollection(collection);
+  const read = useFind(col, filter);
+  const { config, pollMs } = useReplicationConfig({
+    endpoint: options.endpoint,
+    getAuth: options.getAuth,
+    fetch: options.fetch,
+    paths: options.paths,
+    pollMs: options.pollMs
+  });
+  const configRef = (0, import_react6.useRef)(config);
+  configRef.current = config;
+  const [syncing, setSyncing] = (0, import_react6.useState)(false);
+  const [syncError, setSyncError] = (0, import_react6.useState)(null);
+  const [firstSyncDone, setFirstSyncDone] = (0, import_react6.useState)(false);
+  const endpoint = config?.endpoint;
+  const refetch = (0, import_react6.useCallback)(async () => {
+    const cfg = configRef.current;
+    if (!networked || !cfg) return;
+    setSyncing(true);
+    setSyncError(null);
+    try {
+      await replicate(db, cfg, collection, "pull");
+    } catch (e) {
+      setSyncError(e);
+    } finally {
+      setSyncing(false);
+      setFirstSyncDone(true);
+    }
+  }, [db, collection, networked, endpoint]);
+  (0, import_react6.useEffect)(() => {
+    if (!networked) return;
+    void refetch();
+    if (pollMs > 0) {
+      const id = setInterval(() => void refetch(), pollMs);
+      return () => clearInterval(id);
+    }
+    return void 0;
+  }, [refetch, networked, pollMs]);
+  if (networked && !config) {
+    throw new Error(
+      `useQuery({ collection: '${collection}' }) needs an endpoint for source '${source}'. Wrap the tree in <ReplicationProvider endpoint="\u2026">, pass { endpoint }, or use source: "local-only".`
+    );
+  }
+  const loading = source === "remote-first" ? read.loading || !firstSyncDone : read.loading;
+  return { data: read.data, loading, error: read.error, syncing, syncError, refetch };
+}
+
+// src/useQueries.ts
+var import_react7 = require("react");
+var NOOP_REFETCH = async () => {
+};
+function emptyResult() {
+  return { data: [], loading: true, error: null, syncing: false, syncError: null, refetch: NOOP_REFETCH };
+}
+function useQueries(queries) {
+  const db = useTalaDB();
+  const base = useReplicationBase();
+  for (const q of queries) {
+    const networked = (q.source ?? "local-first") !== "local-only";
+    if (networked && !(q.endpoint ?? base?.endpoint)) {
+      throw new Error(
+        `useQueries: the query for '${q.collection}' needs an endpoint for source '${q.source ?? "local-first"}'. Provide <ReplicationProvider endpoint="\u2026">, pass { endpoint }, or use source: "local-only".`
+      );
+    }
+  }
+  const sig = JSON.stringify(
+    queries.map((q) => ({
+      collection: q.collection,
+      filter: q.filter ?? null,
+      source: q.source ?? "local-first",
+      endpoint: q.endpoint ?? null,
+      pollMs: q.pollMs ?? null
+    }))
+  );
+  const queriesRef = (0, import_react7.useRef)(queries);
+  queriesRef.current = queries;
+  const baseRef = (0, import_react7.useRef)(base);
+  baseRef.current = base;
+  const [results, setResults] = (0, import_react7.useState)(
+    () => queries.map(() => emptyResult())
+  );
+  (0, import_react7.useEffect)(() => {
+    const qs = queriesRef.current;
+    const b = baseRef.current;
+    let cancelled = false;
+    const setAt = (i, fn) => {
+      setResults((prev) => {
+        if (i >= prev.length) return prev;
+        const copy = prev.slice();
+        copy[i] = fn(copy[i]);
+        return copy;
+      });
+    };
+    const resolved = qs.map((q, i) => {
+      const { config } = resolveReplicationConfig(b, {
+        endpoint: q.endpoint,
+        getAuth: q.getAuth,
+        fetch: q.fetch,
+        paths: q.paths,
+        pollMs: q.pollMs
+      });
+      const networked = (q.source ?? "local-first") !== "local-only";
+      const pollMs = q.pollMs ?? b?.pollMs ?? 0;
+      const refetch = async () => {
+        if (!networked || !config) return;
+        setAt(i, (r) => ({ ...r, syncing: true, syncError: null }));
+        try {
+          await replicate(db, config, q.collection, "pull");
+        } catch (e) {
+          if (!cancelled) setAt(i, (r) => ({ ...r, syncError: e }));
+        } finally {
+          if (!cancelled) setAt(i, (r) => ({ ...r, syncing: false }));
+        }
+      };
+      return { config, networked, pollMs, refetch };
+    });
+    setResults(
+      qs.map((_q, i) => ({
+        data: [],
+        loading: true,
+        error: null,
+        syncing: false,
+        syncError: null,
+        refetch: resolved[i].refetch
+      }))
+    );
+    const unsubs = qs.map((q, i) => {
+      const col = db.collection(q.collection);
+      return col.subscribe(
+        q.filter ?? {},
+        (docs) => {
+          if (!cancelled) setAt(i, (r) => ({ ...r, data: docs, loading: false, error: null }));
+        },
+        (error) => {
+          if (!cancelled) setAt(i, (r) => ({ ...r, loading: false, error }));
+        }
+      );
+    });
+    const intervals = [];
+    resolved.forEach((res) => {
+      if (!res.networked || !res.config) return;
+      void res.refetch();
+      if (res.pollMs > 0) intervals.push(setInterval(() => void res.refetch(), res.pollMs));
+    });
+    return () => {
+      cancelled = true;
+      unsubs.forEach((u) => u());
+      intervals.forEach((id) => clearInterval(id));
+    };
+  }, [db, sig]);
+  return queries.map((_q, i) => results[i] ?? emptyResult());
+}
+
+// src/useMutation.ts
+var import_react8 = require("react");
+function useMutation(options) {
+  const { collection, direction = "push", drainOnMount = true } = options;
+  const db = useTalaDB();
+  const col = useCollection(collection);
+  const { config } = useReplicationConfig({
+    endpoint: options.endpoint,
+    getAuth: options.getAuth,
+    fetch: options.fetch,
+    paths: options.paths
+  });
+  const configRef = (0, import_react8.useRef)(config);
+  configRef.current = config;
+  const [pending, setPending] = (0, import_react8.useState)(false);
+  const [error, setError] = (0, import_react8.useState)(null);
+  const endpoint = config?.endpoint;
+  const applyLocal = (0, import_react8.useCallback)(
+    async (op) => {
+      switch (op.type) {
+        case "insert":
+          await col.insert(op.doc);
+          return;
+        case "update":
+          await col.updateOne(op.where, { $set: op.set });
+          return;
+        case "delete":
+          await col.deleteOne(op.where);
+          return;
+      }
+    },
+    [col]
+  );
+  const drain = (0, import_react8.useCallback)(async () => {
+    const cfg = configRef.current;
+    if (!cfg) return;
+    await replicateWithRetry(db, cfg, collection, direction);
+  }, [db, collection, direction, endpoint]);
+  const mutateAsync = (0, import_react8.useCallback)(
+    async (op) => {
+      setPending(true);
+      setError(null);
+      try {
+        await applyLocal(op);
+        await drain();
+      } catch (e) {
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    [applyLocal, drain]
+  );
+  const mutate = (0, import_react8.useCallback)(
+    (op) => {
+      void mutateAsync(op).catch(() => {
+      });
+    },
+    [mutateAsync]
+  );
+  (0, import_react8.useEffect)(() => {
+    if (!drainOnMount || !configRef.current) return;
+    void drain().catch(() => {
+    });
+  }, [drain, drainOnMount]);
+  if (!config) {
+    throw new Error(
+      `useMutation({ collection: '${collection}' }) needs an endpoint. Wrap the tree in <ReplicationProvider endpoint="\u2026"> or pass { endpoint }.`
+    );
+  }
+  return { mutate, mutateAsync, pending, error };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ReplicationProvider,
   TalaDBProvider,
   useCollection,
   useFind,
   useFindOne,
+  useMutation,
+  useQueries,
+  useQuery,
+  useReplicationConfig,
   useTalaDB
 });

package/dist/index.mjs

@@ -104,10 +104,409 @@ function useFindOne(collection, filter) {
   const getSnapshot = useCallback2(() => snapshotRef.current, []);
   return useSyncExternalStore2(subscribe, getSnapshot, getSnapshot);
 }
+
+// src/replication/config.tsx
+import {
+  createContext as createContext2,
+  useContext as useContext2,
+  useEffect as useEffect2,
+  useMemo as useMemo2,
+  useRef as useRef3
+} from "react";
+
+// src/replication/engine.ts
+import { HttpSyncAdapter } from "taladb";
+function replicationTarget(endpoint, collection) {
+  return `${endpoint}::${collection}`;
+}
+async function buildAdapter(config) {
+  const headers = config.getAuth ? await config.getAuth() : void 0;
+  return new HttpSyncAdapter({
+    endpoint: config.endpoint,
+    headers,
+    fetch: config.fetch,
+    paths: config.paths
+  });
+}
+var inflight = /* @__PURE__ */ new Map();
+function inflightKey(endpoint, collection, direction) {
+  return `${endpoint}::${collection}::${direction}`;
+}
+function replicate(db, config, collection, direction) {
+  const key = inflightKey(config.endpoint, collection, direction);
+  const existing = inflight.get(key);
+  if (existing) return existing;
+  const pass = (async () => {
+    const adapter = await buildAdapter(config);
+    await db.sync(adapter, {
+      collections: [collection],
+      direction,
+      target: replicationTarget(config.endpoint, collection)
+    });
+  })().finally(() => {
+    inflight.delete(key);
+  });
+  inflight.set(key, pass);
+  return pass;
+}
+var BACKOFFS_MS = [200, 400, 800];
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function replicateWithRetry(db, config, collection, direction) {
+  let lastError;
+  for (let attempt = 0; attempt <= BACKOFFS_MS.length; attempt++) {
+    try {
+      await replicate(db, config, collection, direction);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt < BACKOFFS_MS.length) await sleep(BACKOFFS_MS[attempt]);
+    }
+  }
+  throw lastError;
+}
+
+// src/replication/config.tsx
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+var ReplicationContext = createContext2(null);
+function ReplicationProvider({ children, ...config }) {
+  const key = `${config.endpoint}|${config.pollMs ?? ""}|${JSON.stringify(config.paths ?? null)}|${JSON.stringify(config.prefetch ?? null)}|${config.prefetchMode ?? ""}|${config.prefetchConcurrency ?? ""}`;
+  const value = useMemo2(
+    () => config,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [key]
+  );
+  return /* @__PURE__ */ jsxs(ReplicationContext.Provider, { value, children: [
+    value.prefetch && value.prefetch.length > 0 ? /* @__PURE__ */ jsx2(PrefetchRunner, {}) : null,
+    children
+  ] });
+}
+function resolveReplicationConfig(base, overrides) {
+  const endpoint = overrides?.endpoint ?? base?.endpoint;
+  const pollMs = overrides?.pollMs ?? base?.pollMs ?? 0;
+  if (!endpoint) return { config: null, pollMs };
+  return {
+    config: {
+      endpoint,
+      getAuth: overrides?.getAuth ?? base?.getAuth,
+      fetch: overrides?.fetch ?? base?.fetch,
+      paths: overrides?.paths ?? base?.paths
+    },
+    pollMs
+  };
+}
+function useReplicationBase() {
+  return useContext2(ReplicationContext);
+}
+function useReplicationConfig(overrides) {
+  return resolveReplicationConfig(useContext2(ReplicationContext), overrides);
+}
+var CURSOR_COLLECTION = "__taladb_sync";
+function normalizePrefetch(entries) {
+  return (entries ?? []).map((e) => typeof e === "string" ? { collection: e } : e);
+}
+var idleScheduler = (fn) => {
+  const g = globalThis;
+  if (typeof g.requestIdleCallback === "function") {
+    const id2 = g.requestIdleCallback(fn, { timeout: 2e3 });
+    return () => g.cancelIdleCallback?.(id2);
+  }
+  const id = setTimeout(fn, 0);
+  return () => clearTimeout(id);
+};
+var schedule = idleScheduler;
+async function hasSynced(db, target) {
+  try {
+    const doc = await db.collection(CURSOR_COLLECTION).findOne({ target });
+    return doc != null;
+  } catch {
+    return false;
+  }
+}
+function PrefetchRunner() {
+  const db = useTalaDB();
+  const base = useReplicationBase();
+  const slices = normalizePrefetch(base?.prefetch);
+  const mode = base?.prefetchMode ?? "once";
+  const concurrency = Math.max(1, base?.prefetchConcurrency ?? 2);
+  const baseRef = useRef3(base);
+  baseRef.current = base;
+  const sig = JSON.stringify({ slices, mode, concurrency, endpoint: base?.endpoint ?? null });
+  useEffect2(() => {
+    if (slices.length === 0) return void 0;
+    let cancelled = false;
+    const cancelSchedule = schedule(() => {
+      void run();
+    });
+    async function run() {
+      const b = baseRef.current;
+      const queue = normalizePrefetch(b?.prefetch);
+      const worker = async () => {
+        while (!cancelled) {
+          const slice = queue.shift();
+          if (!slice) return;
+          const { config } = resolveReplicationConfig(b, { endpoint: slice.endpoint });
+          if (!config) continue;
+          const target = replicationTarget(config.endpoint, slice.collection);
+          if (mode === "once" && await hasSynced(db, target)) continue;
+          if (cancelled) return;
+          try {
+            await replicate(db, config, slice.collection, "pull");
+          } catch {
+          }
+        }
+      };
+      const lanes = Math.min(concurrency, queue.length);
+      await Promise.all(Array.from({ length: lanes }, () => worker()));
+    }
+    return () => {
+      cancelled = true;
+      cancelSchedule();
+    };
+  }, [db, sig]);
+  return null;
+}
+
+// src/useQuery.ts
+import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef4, useState as useState2 } from "react";
+function useQuery(options) {
+  const { collection, filter, source = "local-first" } = options;
+  const networked = source !== "local-only";
+  const db = useTalaDB();
+  const col = useCollection(collection);
+  const read = useFind(col, filter);
+  const { config, pollMs } = useReplicationConfig({
+    endpoint: options.endpoint,
+    getAuth: options.getAuth,
+    fetch: options.fetch,
+    paths: options.paths,
+    pollMs: options.pollMs
+  });
+  const configRef = useRef4(config);
+  configRef.current = config;
+  const [syncing, setSyncing] = useState2(false);
+  const [syncError, setSyncError] = useState2(null);
+  const [firstSyncDone, setFirstSyncDone] = useState2(false);
+  const endpoint = config?.endpoint;
+  const refetch = useCallback3(async () => {
+    const cfg = configRef.current;
+    if (!networked || !cfg) return;
+    setSyncing(true);
+    setSyncError(null);
+    try {
+      await replicate(db, cfg, collection, "pull");
+    } catch (e) {
+      setSyncError(e);
+    } finally {
+      setSyncing(false);
+      setFirstSyncDone(true);
+    }
+  }, [db, collection, networked, endpoint]);
+  useEffect3(() => {
+    if (!networked) return;
+    void refetch();
+    if (pollMs > 0) {
+      const id = setInterval(() => void refetch(), pollMs);
+      return () => clearInterval(id);
+    }
+    return void 0;
+  }, [refetch, networked, pollMs]);
+  if (networked && !config) {
+    throw new Error(
+      `useQuery({ collection: '${collection}' }) needs an endpoint for source '${source}'. Wrap the tree in <ReplicationProvider endpoint="\u2026">, pass { endpoint }, or use source: "local-only".`
+    );
+  }
+  const loading = source === "remote-first" ? read.loading || !firstSyncDone : read.loading;
+  return { data: read.data, loading, error: read.error, syncing, syncError, refetch };
+}
+
+// src/useQueries.ts
+import { useEffect as useEffect4, useRef as useRef5, useState as useState3 } from "react";
+var NOOP_REFETCH = async () => {
+};
+function emptyResult() {
+  return { data: [], loading: true, error: null, syncing: false, syncError: null, refetch: NOOP_REFETCH };
+}
+function useQueries(queries) {
+  const db = useTalaDB();
+  const base = useReplicationBase();
+  for (const q of queries) {
+    const networked = (q.source ?? "local-first") !== "local-only";
+    if (networked && !(q.endpoint ?? base?.endpoint)) {
+      throw new Error(
+        `useQueries: the query for '${q.collection}' needs an endpoint for source '${q.source ?? "local-first"}'. Provide <ReplicationProvider endpoint="\u2026">, pass { endpoint }, or use source: "local-only".`
+      );
+    }
+  }
+  const sig = JSON.stringify(
+    queries.map((q) => ({
+      collection: q.collection,
+      filter: q.filter ?? null,
+      source: q.source ?? "local-first",
+      endpoint: q.endpoint ?? null,
+      pollMs: q.pollMs ?? null
+    }))
+  );
+  const queriesRef = useRef5(queries);
+  queriesRef.current = queries;
+  const baseRef = useRef5(base);
+  baseRef.current = base;
+  const [results, setResults] = useState3(
+    () => queries.map(() => emptyResult())
+  );
+  useEffect4(() => {
+    const qs = queriesRef.current;
+    const b = baseRef.current;
+    let cancelled = false;
+    const setAt = (i, fn) => {
+      setResults((prev) => {
+        if (i >= prev.length) return prev;
+        const copy = prev.slice();
+        copy[i] = fn(copy[i]);
+        return copy;
+      });
+    };
+    const resolved = qs.map((q, i) => {
+      const { config } = resolveReplicationConfig(b, {
+        endpoint: q.endpoint,
+        getAuth: q.getAuth,
+        fetch: q.fetch,
+        paths: q.paths,
+        pollMs: q.pollMs
+      });
+      const networked = (q.source ?? "local-first") !== "local-only";
+      const pollMs = q.pollMs ?? b?.pollMs ?? 0;
+      const refetch = async () => {
+        if (!networked || !config) return;
+        setAt(i, (r) => ({ ...r, syncing: true, syncError: null }));
+        try {
+          await replicate(db, config, q.collection, "pull");
+        } catch (e) {
+          if (!cancelled) setAt(i, (r) => ({ ...r, syncError: e }));
+        } finally {
+          if (!cancelled) setAt(i, (r) => ({ ...r, syncing: false }));
+        }
+      };
+      return { config, networked, pollMs, refetch };
+    });
+    setResults(
+      qs.map((_q, i) => ({
+        data: [],
+        loading: true,
+        error: null,
+        syncing: false,
+        syncError: null,
+        refetch: resolved[i].refetch
+      }))
+    );
+    const unsubs = qs.map((q, i) => {
+      const col = db.collection(q.collection);
+      return col.subscribe(
+        q.filter ?? {},
+        (docs) => {
+          if (!cancelled) setAt(i, (r) => ({ ...r, data: docs, loading: false, error: null }));
+        },
+        (error) => {
+          if (!cancelled) setAt(i, (r) => ({ ...r, loading: false, error }));
+        }
+      );
+    });
+    const intervals = [];
+    resolved.forEach((res) => {
+      if (!res.networked || !res.config) return;
+      void res.refetch();
+      if (res.pollMs > 0) intervals.push(setInterval(() => void res.refetch(), res.pollMs));
+    });
+    return () => {
+      cancelled = true;
+      unsubs.forEach((u) => u());
+      intervals.forEach((id) => clearInterval(id));
+    };
+  }, [db, sig]);
+  return queries.map((_q, i) => results[i] ?? emptyResult());
+}
+
+// src/useMutation.ts
+import { useCallback as useCallback4, useEffect as useEffect5, useRef as useRef6, useState as useState4 } from "react";
+function useMutation(options) {
+  const { collection, direction = "push", drainOnMount = true } = options;
+  const db = useTalaDB();
+  const col = useCollection(collection);
+  const { config } = useReplicationConfig({
+    endpoint: options.endpoint,
+    getAuth: options.getAuth,
+    fetch: options.fetch,
+    paths: options.paths
+  });
+  const configRef = useRef6(config);
+  configRef.current = config;
+  const [pending, setPending] = useState4(false);
+  const [error, setError] = useState4(null);
+  const endpoint = config?.endpoint;
+  const applyLocal = useCallback4(
+    async (op) => {
+      switch (op.type) {
+        case "insert":
+          await col.insert(op.doc);
+          return;
+        case "update":
+          await col.updateOne(op.where, { $set: op.set });
+          return;
+        case "delete":
+          await col.deleteOne(op.where);
+          return;
+      }
+    },
+    [col]
+  );
+  const drain = useCallback4(async () => {
+    const cfg = configRef.current;
+    if (!cfg) return;
+    await replicateWithRetry(db, cfg, collection, direction);
+  }, [db, collection, direction, endpoint]);
+  const mutateAsync = useCallback4(
+    async (op) => {
+      setPending(true);
+      setError(null);
+      try {
+        await applyLocal(op);
+        await drain();
+      } catch (e) {
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    [applyLocal, drain]
+  );
+  const mutate = useCallback4(
+    (op) => {
+      void mutateAsync(op).catch(() => {
+      });
+    },
+    [mutateAsync]
+  );
+  useEffect5(() => {
+    if (!drainOnMount || !configRef.current) return;
+    void drain().catch(() => {
+    });
+  }, [drain, drainOnMount]);
+  if (!config) {
+    throw new Error(
+      `useMutation({ collection: '${collection}' }) needs an endpoint. Wrap the tree in <ReplicationProvider endpoint="\u2026"> or pass { endpoint }.`
+    );
+  }
+  return { mutate, mutateAsync, pending, error };
+}
 export {
+  ReplicationProvider,
   TalaDBProvider,
   useCollection,
   useFind,
   useFindOne,
+  useMutation,
+  useQueries,
+  useQuery,
+  useReplicationConfig,
   useTalaDB
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taladb/react",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "React hooks for TalaDB — useFind, useFindOne, and useCollection for React and React Native",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -41,7 +41,7 @@
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "taladb": "^0.9.0"
+    "taladb": "^0.9.1"
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",
@@ -53,7 +53,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.0",
-    "taladb": "0.9.0"
+    "taladb": "0.9.1"
   },
   "scripts": {
     "build": "tsup",