pbtsdb 0.11.0 → 2.0.1

package/dist/core.d.ts

@@ -1,9 +1,7 @@
-import { Collection, InsertMutationFn, UpdateMutationFn, DeleteMutationFn, BaseCollectionConfig, IR } from '@tanstack/db';
+import { Collection, InsertMutationFn, UpdateMutationFn, DeleteMutationFn, BaseCollectionConfig, UtilsRecord, IR } from '@tanstack/db';
 export { BTreeIndex, BasicIndex, DeltaEvent, DeltaType, EffectConfig, EffectContext, IndexConstructor, ReverseIndex, createEffect, materialize, toArray } from '@tanstack/db';
 import PocketBase, { RecordSubscribeOptions } from 'pocketbase';
 export { RecordSubscribeOptions } from 'pocketbase';
-import { QueryCollectionUtils } from '@tanstack/query-db-collection';
-import { QueryClient } from '@tanstack/react-query';
 
 /** Which rows a collection's realtime subscription covers. */
 type RealtimeMode = 'collection' | 'query';
@@ -102,8 +100,8 @@ type RelationAsCollection<T> = T extends Array<infer U> ? U extends object ? Col
 interface RelationTarget {
     /** Relation targets of this collection, for nested expand paths. */
     readonly relationTargets: Record<string, RelationTarget> | undefined;
-    /** Upsert filed rows into the store. False when the store cannot take them yet. */
-    writeFiled: (records: object[]) => Promise<boolean>;
+    /** Upsert filed rows into the store for `holder`, a parent's token. False when the store cannot take them yet. */
+    writeFiled: (records: object[], holder: object) => Promise<boolean>;
     /**
      * A parent's fetch may file and mark `field` once `settles` resolves; the
      * target's own fetch for that subset waits for it (see docs/internals.md,
@@ -112,11 +110,16 @@ interface RelationTarget {
     expectFiling: (field: string, settles: Promise<void>) => () => void;
     /** Record that every row with `field === value` is now in this collection's store. */
     markSubsetLoaded: (field: string, value: string) => void;
+    /** Release rows `holder` filed that no parent row files any more. */
+    releaseFiled: (ids: readonly string[], holder: object) => void;
+    /** Whether a `writeFiled` would land within the current task: the store is syncing and ready. */
+    isReady: () => boolean;
     /**
-     * Hold this collection live for a parent, with the filters covering the
-     * rows the parent filed here (query mode only).
+     * Hold this collection live for a parent identified by `holder`, with the
+     * filters covering the rows the parent filed here (query mode only).
+     * Releasing the hold releases every row filed under `holder`.
      */
-    holdLive: () => HeldTarget;
+    holdLive: (holder: object) => HeldTarget;
 }
 /**
  * A parent's hold on a relation target, returned by `holdLive`.
@@ -205,7 +208,7 @@ interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionNa
      * @example
      * ```ts
      * // Allow inserting without created, updated (server-generated timestamps)
-     * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {
+     * const booksCollection = createCollection<Schema>(pb)('books', {
      *     omitOnInsert: ['created', 'updated'] as const
      * });
      *
@@ -234,20 +237,21 @@ interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionNa
      * @example
      * ```ts
      * // Use default automatic handler (recommended)
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
+     * const collection = createCollection<Schema>(pb)('books');
      *
      * // Custom handler
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     * const collection = createCollection<Schema>(pb)('books', {
      *     onInsert: async ({ transaction }) => {
-     *         for (const mutation of transaction.mutations) {
-     *             await customInsertLogic(mutation.modified);
-     *         }
-     *         await queryClient.invalidateQueries({ queryKey: ['books'] });
+     *         const created = await Promise.all(
+     *             transaction.mutations.map(mutation => customInsertLogic(mutation.modified))
+     *         );
+     *         // Land the server rows before the optimistic state drops
+     *         await collection.accept(created);
      *     }
      * });
      *
      * // Disable inserts (read-only collection)
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     * const collection = createCollection<Schema>(pb)('books', {
      *     onInsert: false
      * });
      * ```
@@ -266,20 +270,23 @@ interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionNa
      * @example
      * ```ts
      * // Use default automatic handler (recommended)
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
+     * const collection = createCollection<Schema>(pb)('books');
      *
      * // Custom handler
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     * const collection = createCollection<Schema>(pb)('books', {
      *     onUpdate: async ({ transaction }) => {
-     *         for (const mutation of transaction.mutations) {
-     *             await customUpdateLogic(mutation.original.id, mutation.changes);
-     *         }
-     *         await queryClient.invalidateQueries({ queryKey: ['books'] });
+     *         const updated = await Promise.all(
+     *             transaction.mutations.map(mutation =>
+     *                 customUpdateLogic(mutation.original.id, mutation.changes)
+     *             )
+     *         );
+     *         // Land the server rows before the optimistic state drops
+     *         await collection.accept(updated);
      *     }
      * });
      *
      * // Disable updates (read-only collection)
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     * const collection = createCollection<Schema>(pb)('books', {
      *     onUpdate: false
      * });
      * ```
@@ -297,41 +304,44 @@ interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionNa
      * @example
      * ```ts
      * // Use default automatic handler (recommended)
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
+     * const collection = createCollection<Schema>(pb)('books');
      *
      * // Custom handler
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     * const collection = createCollection<Schema>(pb)('books', {
      *     onDelete: async ({ transaction }) => {
-     *         for (const mutation of transaction.mutations) {
-     *             await customDeleteLogic(mutation.original.id);
-     *         }
-     *         await queryClient.invalidateQueries({ queryKey: ['books'] });
+     *         const ids = transaction.mutations.map(mutation => mutation.original.id);
+     *         await Promise.all(ids.map(id => customDeleteLogic(id)));
+     *         // Remove the rows before the optimistic state drops
+     *         await collection.evict(ids);
      *     }
      * });
      *
      * // Disable deletes (read-only collection)
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     * const collection = createCollection<Schema>(pb)('books', {
      *     onDelete: false
      * });
      * ```
      */
     onDelete?: DeleteMutationFn<ExtractRecordType<Schema, CollectionName>> | false;
     /**
-     * If true, refetch the entire collection after a successful insert,
-     * update, or delete. Defaults to false: the built-in insert/update handlers
-     * write the server response straight back into the synced layer, and the
-     * realtime subscription reconciles everything else. Set true if you do not
-     * trust realtime to reconcile in time (e.g. flaky socket, server-side hooks
-     * producing fields you must read synchronously).
-     *
-     * Only affects the built-in default handlers. If you supply your own
-     * onInsert/onUpdate/onDelete, you control the return value yourself.
+     * If true, the built-in handlers reload the collection's live subsets
+     * after a successful insert, update, or delete, before the mutation
+     * settles. Defaults to false: the built-in handlers write the server
+     * response into the synced layer before they settle, and the realtime
+     * subscription reconciles everything else. Set true when a server-side
+     * hook changes rows you must read right after the mutation.
+     *
+     * Only affects the built-in default handlers. A custom
+     * onInsert/onUpdate should land the server response with
+     * `await collection.accept(rows)` before it returns, and a custom
+     * onDelete should `await collection.evict(ids)`. A custom handler that
+     * needs a refetch can call `await collection.reload()` instead.
      *
      * @default false
      *
      * @example
      * ```ts
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     * const collection = createCollection<Schema>(pb)('books', {
      *     refetchOnMutation: true,
      * });
      * ```
@@ -353,10 +363,10 @@ interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionNa
      * @example
      * ```ts
      * // Default: eager mode - client-side filtering
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
+     * const collection = createCollection<Schema>(pb)('books');
      *
      * // On-demand mode - server-side filtering
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     * const collection = createCollection<Schema>(pb)('books', {
      *     syncMode: 'on-demand'
      * });
      * ```
@@ -377,7 +387,7 @@ interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionNa
      *
      * @example
      * ```ts
-     * const books = createCollection<Schema>(pb, queryClient)('books', {
+     * const books = createCollection<Schema>(pb)('books', {
      *     syncMode: 'on-demand',
      *     realtime: 'query',
      * });
@@ -385,35 +395,39 @@ interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionNa
      */
     realtime?: RealtimeMode;
     /**
-     * Whether to ignore PocketBase auto-cancellation errors.
-     *
-     * PocketBase automatically cancels pending requests when a new request is made
-     * to the same endpoint. This can throw ClientResponseError with a message
-     * containing "autocancelled". When this option is true, such errors are
-     * silently ignored and the existing cached data is returned for the cancelled request.
-     *
-     * @default true
-     *
-     * @example
-     * ```ts
-     * // Default: auto-cancellation errors are ignored
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
-     *
-     * // Explicitly handle auto-cancellation errors
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     ignoreAutoCancellation: false
-     * });
-     * ```
+     * How long, in milliseconds, an on-demand subset stays loaded after its
+     * last live query unsubscribes. A query with an equal request that mounts
+     * within the window reuses the rows with no request; realtime keeps them
+     * fresh meanwhile. Rows a parent filed through a relation follow the
+     * same window, and so does the accepted holder a mutation write-back or
+     * `accept()` gives a row. `0` releases a subset as soon as it unloads
+     * and keeps an accepted row until a reload or idle. A `reload()`
+     * releases every waiting subset.
+     *
+     * @default 5000
+     */
+    subsetGcTime?: number;
+    /**
+     * Waits, in milliseconds, before each retry of a failed subset or eager
+     * load. The last delay repeats until the load succeeds, so a live query
+     * stays loading through an outage instead of entering an error state it
+     * cannot leave; a `reload()` or a realtime reconnect retries at once. A
+     * response the server gave on purpose (a 4xx other than 401, 408 or
+     * 429) is not retried and reports its error; a 401 waits for the next
+     * auth change. Each delay carries up to a quarter of jitter either way.
+     * `[]` disables retries.
+     *
+     * @default [1000, 2000, 4000, 8000, 15000, 30000]
      */
-    ignoreAutoCancellation?: boolean;
+    loadRetryDelays?: readonly number[];
     /**
      * Additional options passed directly to the underlying TanStack DB collection.
      * Use this to configure indexing, garbage collection, comparison functions,
      * and any other TanStack DB collection options not explicitly exposed by pbtsdb.
      *
-     * Options set here are spread into the `queryCollectionOptions()` call.
+     * Options set here are spread into the TanStack DB `createCollection()` call.
      * Fields managed by pbtsdb (`getKey`, `syncMode`, `onInsert`, `onUpdate`,
-     * `onDelete`, `schema`) are excluded from the type.
+     * `onDelete`, `schema`, `utils`) are excluded from the type.
      *
      * pbtsdb defaults `autoIndex` to `'eager'` with `defaultIndexType: BTreeIndex`
      * so `orderBy` + `limit` queries page lazily; both can be overridden here.
@@ -421,7 +435,7 @@ interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionNa
      * @example
      * ```ts
      * import { BasicIndex } from 'pbtsdb'
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     * const collection = createCollection<Schema>(pb)('books', {
      *     collectionOptions: {
      *         autoIndex: 'off',
      *         gcTime: 60000,
@@ -429,7 +443,7 @@ interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionNa
      * });
      * ```
      */
-    collectionOptions?: Omit<Partial<BaseCollectionConfig<ExtractRecordType<Schema, CollectionName>, string | number>>, 'getKey' | 'syncMode' | 'onInsert' | 'onUpdate' | 'onDelete' | 'schema'>;
+    collectionOptions?: Omit<Partial<BaseCollectionConfig<ExtractRecordType<Schema, CollectionName>, string | number>>, 'getKey' | 'syncMode' | 'onInsert' | 'onUpdate' | 'onDelete' | 'schema' | 'utils'>;
 }
 
 type RelationTargets = Record<string, RelationTarget>;
@@ -452,30 +466,92 @@ interface CreateCollectionFactoryOptions {
     subscribeOptions?: () => RecordSubscribeOptions | undefined;
 }
 /**
- * Subscription helpers added to collection instances.
+ * pbtsdb's utilities on `collection.utils`. The same functions are also
+ * assigned on the collection itself.
+ */
+interface PbCollectionUtils<T extends object> extends UtilsRecord {
+    /**
+     * Land rows the server returned as confirmed state, for example a custom
+     * endpoint's response. A row older than the stored one is ignored.
+     * Resolves when the rows are accepted; they become visible with the
+     * settlement of any persisting mutation, so a mutation handler can await it.
+     * Throws on an eager collection that is idle: it does not start a full load.
+     */
+    accept: (rows: readonly T[]) => Promise<void>;
+    /**
+     * Refetch every live query's subset (the whole collection in eager mode)
+     * and release the realtime-topic and accepted holders of rows the results
+     * do not confirm; rows a subset or a parent holds stay. Resolves when the
+     * rows are accepted; they become visible with the settlement of any
+     * persisting mutation.
+     */
+    reload: () => Promise<void>;
+    /**
+     * Remove rows the server deleted, for example after a custom endpoint
+     * deleted them. The rows leave every holder, and a fetch in flight does
+     * not put them back. Resolves when the removal is accepted, so a custom
+     * delete handler can await it. A no-op while the collection is not
+     * syncing.
+     */
+    evict: (ids: readonly string[]) => Promise<void>;
+}
+/**
+ * Helpers added to collection instances.
  * @internal
  */
-interface CollectionSubscriptionHelpers {
+interface CollectionSubscriptionHelpers<T extends object> {
     /** The PocketBase collection name */
     collectionName: string;
     /** Wait for subscription to be established (useful in tests) */
     waitForSubscription: (timeout?: number) => Promise<void>;
     /** Check if collection has an active subscription */
     isSubscribed: () => boolean;
-    /** Relation targets declared through `relations` */
+    /**
+     * Relation targets declared through `relations`. Relation plumbing, not public API.
+     * @internal
+     */
     relationTargets: RelationTargets | undefined;
-    /** Number of relation targets currently held live */
+    /**
+     * Number of relation targets currently held live. Relation plumbing, not public API.
+     * @internal
+     */
     heldRelationTargetCount: () => number;
-    /** Record that every row with `field === value` is now in this collection's store */
+    /**
+     * Record that every row with `field === value` is now in this collection's store. Relation plumbing, not public API.
+     * @internal
+     */
     markSubsetLoaded: (field: string, value: string) => void;
-    /** Number of field/value pairs currently marked loaded */
+    /**
+     * Number of field/value pairs currently marked loaded. Relation plumbing, not public API.
+     * @internal
+     */
     loadedSubsetCount: () => number;
-    /** Hold this collection live as a relation target; see RelationTarget.holdLive */
-    holdLive: () => HeldTarget;
-    /** Receive rows a parent expanded into this collection; see RelationTarget.writeFiled */
-    writeFiled: (records: object[]) => Promise<boolean>;
-    /** A parent's fetch may file a subset here; see RelationTarget.expectFiling */
+    /**
+     * Hold this collection live as a relation target; see RelationTarget.holdLive. Relation plumbing, not public API.
+     * @internal
+     */
+    holdLive: (holder: object) => HeldTarget;
+    /**
+     * Receive rows a parent expanded into this collection; see RelationTarget.writeFiled. Relation plumbing, not public API.
+     * @internal
+     */
+    writeFiled: (records: object[], holder: object) => Promise<boolean>;
+    /**
+     * Release rows a parent stopped filing here; see RelationTarget.releaseFiled. Relation plumbing, not public API.
+     * @internal
+     */
+    releaseFiled: (ids: readonly string[], holder: object) => void;
+    /**
+     * A parent's fetch may file a subset here; see RelationTarget.expectFiling. Relation plumbing, not public API.
+     * @internal
+     */
     expectFiling: (field: string, settles: Promise<void>) => () => void;
+    /** See {@link PbCollectionUtils.accept}. */
+    accept: PbCollectionUtils<T>['accept'];
+    /** See {@link PbCollectionUtils.reload}. */
+    reload: PbCollectionUtils<T>['reload'];
+    /** See {@link PbCollectionUtils.evict}. */
+    evict: PbCollectionUtils<T>['evict'];
 }
 
 /**
@@ -484,7 +560,7 @@ interface CollectionSubscriptionHelpers {
  * Views are created by {@link PbCollectionView.fetchRelations} and
  * {@link PbCollectionView.withRealtime}, and compose in either order.
  */
-type PbCollectionView<Schema extends SchemaDeclaration, C extends keyof Schema & string, Opts> = Collection<ExtractRecordType<Schema, C>, string | number, QueryCollectionUtils<ExtractRecordType<Schema, C>, string | number, ExtractRecordType<Schema, C>>, never, InsertInputOf<Schema, C, Opts>> & CollectionSubscriptionHelpers & {
+type PbCollectionView<Schema extends SchemaDeclaration, C extends keyof Schema & string, Opts> = Collection<ExtractRecordType<Schema, C>, string | number, PbCollectionUtils<ExtractRecordType<Schema, C>>, never, InsertInputOf<Schema, C, Opts>> & CollectionSubscriptionHelpers<ExtractRecordType<Schema, C>> & {
     /** The PocketBase collection name */
     readonly collectionName: C;
     /** @internal phantom; never present at runtime */
@@ -516,13 +592,13 @@ type AlwaysFetchRelationsCheck<Opts> = {
  * Use this when you need fine-grained control or need to create collections with dependencies.
  *
  * @param pb - PocketBase client instance
- * @param queryClient - TanStack Query client
+ * @param factoryOptions - Options applied to every collection this factory creates
  * @returns A curried function that takes collection name and options
  *
  * @example
  * Basic usage:
  * ```ts
- * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {});
+ * const booksCollection = createCollection<Schema>(pb)('books', {});
  *
  * // Use directly
  * const books = await booksCollection.getFullList();
@@ -531,8 +607,8 @@ type AlwaysFetchRelationsCheck<Opts> = {
  * @example
  * With relations fetched on every request:
  * ```ts
- * const authorsCollection = createCollection<Schema>(pb, queryClient)('authors', {});
- * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {
+ * const authorsCollection = createCollection<Schema>(pb)('authors', {});
+ * const booksCollection = createCollection<Schema>(pb)('books', {
  *     relations: { author: authorsCollection },
  *     alwaysFetchRelations: ['author'],
  * });
@@ -545,7 +621,7 @@ type AlwaysFetchRelationsCheck<Opts> = {
  * @example
  * With a per-query fetchRelations view:
  * ```ts
- * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {
+ * const booksCollection = createCollection<Schema>(pb)('books', {
  *     relations: { author: authorsCollection },
  * });
  *
@@ -555,7 +631,7 @@ type AlwaysFetchRelationsCheck<Opts> = {
  * authorsCollection.get(data[0].author)?.name
  * ```
  */
-declare function createCollection<Schema extends SchemaDeclaration>(pb: PocketBase, queryClient: QueryClient, factoryOptions?: CreateCollectionFactoryOptions): <C extends keyof Schema & string, const Opts extends CreateCollectionOptions<Schema, C>>(collectionName: C, options?: Opts & AlwaysFetchRelationsCheck<Opts>) => PbCollection<Schema, C, Opts>;
+declare function createCollection<Schema extends SchemaDeclaration>(pb: PocketBase, factoryOptions?: CreateCollectionFactoryOptions): <C extends keyof Schema & string, const Opts extends CreateCollectionOptions<Schema, C>>(collectionName: C, options?: Opts & AlwaysFetchRelationsCheck<Opts>) => PbCollection<Schema, C, Opts>;
 
 /**
  * Logger interface for subscription events and internal operations.
@@ -628,6 +704,76 @@ type BasicExpression<T = unknown> = IR.BasicExpression<T>;
 declare function convertToPocketBaseFilter(where: BasicExpression<boolean> | undefined | null): string | undefined;
 declare function convertToPocketBaseSort(orderBy: IR.OrderBy | undefined | null): string | undefined;
 
+/** The state of pbtsdb's realtime connection for one PocketBase client. */
+type RealtimeStatus = 
+/** `disconnectRealtime(pb)` is in effect, or no collection has subscribed yet. */
+{
+    state: 'disabled';
+}
+/** The first connection of a session is opening. */
+ | {
+    state: 'connecting';
+}
+/** The stream is open and `PB_CONNECT` was received. */
+ | {
+    state: 'connected';
+}
+/**
+ * The stream dropped, or never came up, and a retry is scheduled.
+ * `attempt` is the number of the retry, `nextRetryAt` when it fires and
+ * `since` when the connection was lost, both epoch milliseconds.
+ */
+ | {
+    state: 'reconnecting';
+    attempt: number;
+    nextRetryAt: number;
+    since: number;
+};
+/** Loads that are not progressing, across every collection of one client. */
+type LoadStatus = {
+    /** Live demands sleeping in their `loadRetryDelays` backoff. */
+    retrying: number;
+    /** When the oldest still-retrying load first failed, epoch milliseconds. */
+    failingSince?: number;
+    /** Live demands whose load ended in an error that is not retried, such as a 403 or 404. */
+    failed: number;
+};
+type SyncStatus = {
+    realtime: RealtimeStatus;
+    loads: LoadStatus;
+};
+type SyncStatusListener = (status: SyncStatus) => void;
+
+/**
+ * Forgets the shared realtime connection's server-side session and
+ * reconnects under `pb`'s current auth, re-sending every subscribed topic.
+ * pbtsdb does this itself when `pb.authStore` changes to another auth
+ * record; call it for a change the store cannot see, such as a server
+ * switch. It also lifts {@link disconnectRealtime}. A no-op if `pb` has no
+ * realtime connection yet.
+ */
+declare function resetRealtime(pb: PocketBase): void;
+/**
+ * Closes pbtsdb's realtime connection for `pb` and keeps it closed: no
+ * connection opens until {@link resetRealtime}. Collections keep working
+ * over REST and keep their subscriptions registered, so a later
+ * `resetRealtime(pb)` resumes every topic and reloads every ready
+ * collection. Use it at logout, or at startup where realtime is not wanted.
+ */
+declare function disconnectRealtime(pb: PocketBase): void;
+/**
+ * The sync state of `pb`'s collections: whether pbtsdb's realtime stream
+ * is up, and how many live loads are stuck in retry or ended in an error
+ * the server meant. The snapshot is stable until a value changes, so it
+ * suits `useSyncExternalStore`; see {@link subscribeSyncStatus}.
+ */
+declare function getSyncStatus(pb: PocketBase): SyncStatus;
+/**
+ * Calls `listener` with each new {@link getSyncStatus} snapshot. Returns
+ * the unsubscribe function.
+ */
+declare function subscribeSyncStatus(pb: PocketBase, listener: SyncStatusListener): () => void;
+
 /**
  * Generates a new PocketBase-compatible record ID.
  * Returns a 15-character alphanumeric string (lowercase letters and numbers).
@@ -643,4 +789,4 @@ declare function convertToPocketBaseSort(orderBy: IR.OrderBy | undefined | null)
  */
 declare function newRecordId(): string;
 
-export { type CreateCollectionFactoryOptions, type CreateCollectionOptions, type ExcludeUndefined, type ExpandPath, type ExtractRecordType, type ExtractRelations, type Logger, type OmittableFields, type PbCollection, type PbCollectionView, type RealtimeMode, type RelationAsCollection, type RelationsConfig, type SchemaDeclaration, convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, newRecordId, resetLogger, setLogger };
+export { type CreateCollectionFactoryOptions, type CreateCollectionOptions, type ExcludeUndefined, type ExpandPath, type ExtractRecordType, type ExtractRelations, type LoadStatus, type Logger, type OmittableFields, type PbCollection, type PbCollectionUtils, type PbCollectionView, type RealtimeMode, type RealtimeStatus, type RelationAsCollection, type RelationsConfig, type SchemaDeclaration, type SyncStatus, type SyncStatusListener, convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, disconnectRealtime, getSyncStatus, newRecordId, resetLogger, resetRealtime, setLogger, subscribeSyncStatus };

package/dist/core.js

@@ -1,3 +1,3 @@
-export { BTreeIndex, BasicIndex, ReverseIndex, convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, createEffect, materialize, newRecordId, resetLogger, setLogger, toArray } from './chunk-OBDOVDCI.js';
+export { BTreeIndex, BasicIndex, ReverseIndex, convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, createEffect, disconnectRealtime, getSyncStatus, materialize, newRecordId, resetLogger, resetRealtime, setLogger, subscribeSyncStatus, toArray } from './chunk-TTENGDS3.js';
 //# sourceMappingURL=core.js.map
 //# sourceMappingURL=core.js.map

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { BTreeIndex, BasicIndex, DeltaEvent, DeltaType, EffectConfig, EffectContext, IndexConstructor, ReverseIndex, createEffect, materialize, toArray } from '@tanstack/db';
+import PocketBase from 'pocketbase';
 export { RecordSubscribeOptions } from 'pocketbase';
-export { CreateCollectionFactoryOptions, CreateCollectionOptions, ExcludeUndefined, ExpandPath, ExtractRecordType, ExtractRelations, Logger, OmittableFields, PbCollection, PbCollectionView, RealtimeMode, RelationAsCollection, RelationsConfig, SchemaDeclaration, convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, newRecordId, resetLogger, setLogger } from './core.js';
+import { SyncStatus } from './core.js';
+export { CreateCollectionFactoryOptions, CreateCollectionOptions, ExcludeUndefined, ExpandPath, ExtractRecordType, ExtractRelations, LoadStatus, Logger, OmittableFields, PbCollection, PbCollectionUtils, PbCollectionView, RealtimeMode, RealtimeStatus, RelationAsCollection, RelationsConfig, SchemaDeclaration, SyncStatusListener, convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, disconnectRealtime, getSyncStatus, newRecordId, resetLogger, resetRealtime, setLogger, subscribeSyncStatus } from './core.js';
 import React, { ReactNode } from 'react';
-import '@tanstack/query-db-collection';
-import '@tanstack/react-query';
 
 /**
  * UseStore hook type for variadic collection access.
@@ -51,7 +51,7 @@ interface ReactProviderResult<CollectionsMap> {
  * import { useLiveQuery } from '@tanstack/react-db';
  *
  * // Step 1: Create collections
- * const c = createCollection<Schema>(pb, queryClient);
+ * const c = createCollection<Schema>(pb);
  * const collections = {
  *     books: c('books', {}),
  *     authors: c('authors', {}),
@@ -63,11 +63,9 @@ interface ReactProviderResult<CollectionsMap> {
  * // Step 3: Wrap your app
  * function App() {
  *     return (
- *         <QueryClientProvider client={queryClient}>
- *             <Provider>
- *                 <BooksList />
- *             </Provider>
- *         </QueryClientProvider>
+ *         <Provider>
+ *             <BooksList />
+ *         </Provider>
  *     );
  * }
  *
@@ -101,7 +99,7 @@ interface ReactProviderResult<CollectionsMap> {
  * @example
  * With relations filed via alwaysFetchRelations:
  * ```tsx
- * const c = createCollection<Schema>(pb, queryClient);
+ * const c = createCollection<Schema>(pb);
  * const authors = c('authors', { syncMode: 'on-demand' });
  * const books = c('books', {
  *     relations: { author: authors },
@@ -134,5 +132,21 @@ interface ReactProviderResult<CollectionsMap> {
  * ```
  */
 declare function createReactProvider<CollectionsMap extends Record<string, unknown>>(collections: CollectionsMap): ReactProviderResult<CollectionsMap>;
+/**
+ * The current {@link SyncStatus} of `pb`'s collections, re-rendering on
+ * each change. Use it for a connectivity notice: the realtime stream
+ * dropping while REST still works, or queries stuck in retry.
+ *
+ * @example
+ * ```tsx
+ * function SyncNotice() {
+ *     const { realtime, loads } = useSyncStatus(pb);
+ *     if (realtime.state === 'reconnecting') return <p>Reconnecting…</p>;
+ *     if (loads.retrying > 0) return <p>Retrying {loads.retrying} queries</p>;
+ *     return null;
+ * }
+ * ```
+ */
+declare function useSyncStatus(pb: PocketBase): SyncStatus;
 
-export { type ReactProviderResult, createReactProvider };
+export { type ReactProviderResult, SyncStatus, createReactProvider, useSyncStatus };

package/dist/index.js

@@ -1,5 +1,6 @@
-export { BTreeIndex, BasicIndex, ReverseIndex, convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, createEffect, materialize, newRecordId, resetLogger, setLogger, toArray } from './chunk-OBDOVDCI.js';
-import { createContext, useContext } from 'react';
+import { subscribeSyncStatus, getSyncStatus } from './chunk-TTENGDS3.js';
+export { BTreeIndex, BasicIndex, ReverseIndex, convertToPocketBaseFilter, convertToPocketBaseSort, createCollection, createEffect, disconnectRealtime, getSyncStatus, materialize, newRecordId, resetLogger, resetRealtime, setLogger, subscribeSyncStatus, toArray } from './chunk-TTENGDS3.js';
+import { createContext, useSyncExternalStore, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 function createReactProvider(collections) {
@@ -24,7 +25,14 @@ function createReactProvider(collections) {
     useStore
   };
 }
+function useSyncStatus(pb) {
+  return useSyncExternalStore(
+    (listener) => subscribeSyncStatus(pb, listener),
+    () => getSyncStatus(pb),
+    () => getSyncStatus(pb)
+  );
+}
 
-export { createReactProvider };
+export { createReactProvider, useSyncStatus };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/react.tsx"],"names":[],"mappings":";;;;AAmIO,SAAS,oBACZ,WAAA,EACmC;AACnC,EAAA,MAAM,OAAA,GAAU,cAAqC,IAAI,CAAA;AAEzD,EAAA,MAAM,QAAA,GAA8C,CAAC,EAAE,QAAA,EAAS,qBAC5D,GAAA,CAAC,OAAA,CAAQ,QAAA,EAAR,EAAiB,KAAA,EAAO,WAAA,EAAc,QAAA,EAAS,CAAA;AAGpD,EAAA,SAAS,YACF,IAAA,EACiF;AACpF,IAAA,MAAM,OAAA,GAAU,WAAW,OAAO,CAAA;AAElC,IAAA,IAAI,CAAC,OAAA,EAAS;AACV,MAAA,MAAM,IAAI,KAAA;AAAA,QACN;AAAA,OACJ;AAAA,IACJ;AAEA,IAAA,OAAO,IAAA,CAAK,IAAI,CAAA,GAAA,KAAO;AACnB,MAAA,IAAI,EAAE,OAAO,OAAA,CAAA,EAAU;AACnB,QAAA,MAAM,IAAI,KAAA,CAAM,CAAA,YAAA,EAAe,MAAA,CAAO,GAAG,CAAC,CAAA,0BAAA,CAA4B,CAAA;AAAA,MAC1E;AACA,MAAA,OAAO,QAAQ,GAAG,CAAA;AAAA,IACtB,CAAC,CAAA;AAAA,EACL;AAEA,EAAA,OAAO;AAAA,IACH,QAAA;AAAA,IACA;AAAA,GACJ;AACJ","file":"index.js","sourcesContent":["import React, { createContext, type ReactNode, useContext } from 'react'\n\n/**\n * UseStore hook type for variadic collection access.\n * @internal\n */\ntype UseStoreFn<CollectionsMap> = <K extends (keyof CollectionsMap)[]>(\n    ...keys: K\n) => { [I in keyof K]: K[I] extends keyof CollectionsMap ? CollectionsMap[K[I]] : never }\n\n/**\n * Return type for createReactProvider function.\n */\nexport interface ReactProviderResult<CollectionsMap> {\n    /**\n     * React Context Provider component.\n     * Wrap your app with this provider to make collections available to useStore.\n     */\n    Provider: React.FC<{ children: ReactNode }>\n\n    /**\n     * Hook to access collections from the provider.\n     * Uses variadic arguments for clean syntax with automatic type inference.\n     *\n     * @example\n     * ```tsx\n     * // Single collection\n     * const [books] = useStore('books');\n     *\n     * // Multiple collections (no 'as const' needed!)\n     * const [books, authors] = useStore('books', 'authors');\n     * ```\n     */\n    useStore: UseStoreFn<CollectionsMap>\n}\n\n/**\n * Creates a React Provider and useStore hook from a collections map.\n *\n * @param collections - Map of collection keys to Collection instances\n * @returns Object containing Provider component and useStore hook\n *\n * @example\n * Basic usage:\n * ```tsx\n * import { createCollection, createReactProvider } from 'pbtsdb';\n * import { useLiveQuery } from '@tanstack/react-db';\n *\n * // Step 1: Create collections\n * const c = createCollection<Schema>(pb, queryClient);\n * const collections = {\n *     books: c('books', {}),\n *     authors: c('authors', {}),\n * };\n *\n * // Step 2: Wrap for React\n * const { Provider, useStore } = createReactProvider(collections);\n *\n * // Step 3: Wrap your app\n * function App() {\n *     return (\n *         <QueryClientProvider client={queryClient}>\n *             <Provider>\n *                 <BooksList />\n *             </Provider>\n *         </QueryClientProvider>\n *     );\n * }\n *\n * // Step 4: Use in components\n * function BooksList() {\n *     const [books] = useStore('books');\n *     const { data } = useLiveQuery((q) => q.from({ books }));\n *     return <div>{data?.map(book => <p key={book.id}>{book.title}</p>)}</div>;\n * }\n * ```\n *\n * @example\n * Variadic useStore pattern:\n * ```tsx\n * function BooksWithAuthors() {\n *     const [books, authors] = useStore('books', 'authors');\n *\n *     const { data } = useLiveQuery((q) =>\n *         q.from({ book: books })\n *          .join(\n *              { author: authors },\n *              ({ book, author }) => eq(book.author, author.id),\n *              'left'\n *          )\n *     );\n *\n *     return <div>...</div>;\n * }\n * ```\n *\n * @example\n * With relations filed via alwaysFetchRelations:\n * ```tsx\n * const c = createCollection<Schema>(pb, queryClient);\n * const authors = c('authors', { syncMode: 'on-demand' });\n * const books = c('books', {\n *     relations: { author: authors },\n *     alwaysFetchRelations: ['author'],\n * });\n *\n * const { Provider, useStore } = createReactProvider({ authors, books });\n *\n * function BooksWithAuthors() {\n *     const [books, authors] = useStore('books', 'authors');\n *     const { data } = useLiveQuery((q) =>\n *         q.from({ b: books }).select(({ b }) => ({\n *             ...b,\n *             author: materialize(\n *                 q.from({ a: authors }).where(({ a }) => eq(a.id, b.author)).findOne()\n *             ),\n *         }))\n *     );\n *\n *     return (\n *         <ul>\n *             {data?.map(row => (\n *                 <li key={row.id}>\n *                     {row.title} by {row.author?.name}\n *                 </li>\n *             ))}\n *         </ul>\n *     );\n * }\n * ```\n */\nexport function createReactProvider<CollectionsMap extends Record<string, unknown>>(\n    collections: CollectionsMap\n): ReactProviderResult<CollectionsMap> {\n    const Context = createContext<CollectionsMap | null>(null)\n\n    const Provider: React.FC<{ children: ReactNode }> = ({ children }) => (\n        <Context.Provider value={collections}>{children}</Context.Provider>\n    )\n\n    function useStore<K extends (keyof CollectionsMap)[]>(\n        ...keys: K\n    ): { [I in keyof K]: K[I] extends keyof CollectionsMap ? CollectionsMap[K[I]] : never } {\n        const context = useContext(Context)\n\n        if (!context) {\n            throw new Error(\n                'useStore must be used within the Provider returned by createReactProvider'\n            )\n        }\n\n        return keys.map(key => {\n            if (!(key in context)) {\n                throw new Error(`Collection \"${String(key)}\" not found in collections`)\n            }\n            return context[key]\n        }) as { [I in keyof K]: K[I] extends keyof CollectionsMap ? CollectionsMap[K[I]] : never }\n    }\n\n    return {\n        Provider,\n        useStore: useStore as UseStoreFn<CollectionsMap>,\n    }\n}\n"]}
+{"version":3,"sources":["../src/react.tsx"],"names":[],"mappings":";;;;;AAoIO,SAAS,oBACZ,WAAA,EACmC;AACnC,EAAA,MAAM,OAAA,GAAU,cAAqC,IAAI,CAAA;AAEzD,EAAA,MAAM,QAAA,GAA8C,CAAC,EAAE,QAAA,EAAS,qBAC5D,GAAA,CAAC,OAAA,CAAQ,QAAA,EAAR,EAAiB,KAAA,EAAO,WAAA,EAAc,QAAA,EAAS,CAAA;AAGpD,EAAA,SAAS,YACF,IAAA,EACiF;AACpF,IAAA,MAAM,OAAA,GAAU,WAAW,OAAO,CAAA;AAElC,IAAA,IAAI,CAAC,OAAA,EAAS;AACV,MAAA,MAAM,IAAI,KAAA;AAAA,QACN;AAAA,OACJ;AAAA,IACJ;AAEA,IAAA,OAAO,IAAA,CAAK,IAAI,CAAA,GAAA,KAAO;AACnB,MAAA,IAAI,EAAE,OAAO,OAAA,CAAA,EAAU;AACnB,QAAA,MAAM,IAAI,KAAA,CAAM,CAAA,YAAA,EAAe,MAAA,CAAO,GAAG,CAAC,CAAA,0BAAA,CAA4B,CAAA;AAAA,MAC1E;AACA,MAAA,OAAO,QAAQ,GAAG,CAAA;AAAA,IACtB,CAAC,CAAA;AAAA,EACL;AAEA,EAAA,OAAO;AAAA,IACH,QAAA;AAAA,IACA;AAAA,GACJ;AACJ;AAiBO,SAAS,cAAc,EAAA,EAA4B;AACtD,EAAA,OAAO,oBAAA;AAAA,IACH,CAAA,QAAA,KAAY,mBAAA,CAAoB,EAAA,EAAI,QAAQ,CAAA;AAAA,IAC5C,MAAM,cAAc,EAAE,CAAA;AAAA,IACtB,MAAM,cAAc,EAAE;AAAA,GAC1B;AACJ","file":"index.js","sourcesContent":["import type PocketBase from 'pocketbase'\nimport React, { createContext, type ReactNode, useContext, useSyncExternalStore } from 'react'\nimport type { SyncStatus } from './sync-status'\nimport { getSyncStatus, subscribeSyncStatus } from './transport'\n\n/**\n * UseStore hook type for variadic collection access.\n * @internal\n */\ntype UseStoreFn<CollectionsMap> = <K extends (keyof CollectionsMap)[]>(\n    ...keys: K\n) => { [I in keyof K]: K[I] extends keyof CollectionsMap ? CollectionsMap[K[I]] : never }\n\n/**\n * Return type for createReactProvider function.\n */\nexport interface ReactProviderResult<CollectionsMap> {\n    /**\n     * React Context Provider component.\n     * Wrap your app with this provider to make collections available to useStore.\n     */\n    Provider: React.FC<{ children: ReactNode }>\n\n    /**\n     * Hook to access collections from the provider.\n     * Uses variadic arguments for clean syntax with automatic type inference.\n     *\n     * @example\n     * ```tsx\n     * // Single collection\n     * const [books] = useStore('books');\n     *\n     * // Multiple collections (no 'as const' needed!)\n     * const [books, authors] = useStore('books', 'authors');\n     * ```\n     */\n    useStore: UseStoreFn<CollectionsMap>\n}\n\n/**\n * Creates a React Provider and useStore hook from a collections map.\n *\n * @param collections - Map of collection keys to Collection instances\n * @returns Object containing Provider component and useStore hook\n *\n * @example\n * Basic usage:\n * ```tsx\n * import { createCollection, createReactProvider } from 'pbtsdb';\n * import { useLiveQuery } from '@tanstack/react-db';\n *\n * // Step 1: Create collections\n * const c = createCollection<Schema>(pb);\n * const collections = {\n *     books: c('books', {}),\n *     authors: c('authors', {}),\n * };\n *\n * // Step 2: Wrap for React\n * const { Provider, useStore } = createReactProvider(collections);\n *\n * // Step 3: Wrap your app\n * function App() {\n *     return (\n *         <Provider>\n *             <BooksList />\n *         </Provider>\n *     );\n * }\n *\n * // Step 4: Use in components\n * function BooksList() {\n *     const [books] = useStore('books');\n *     const { data } = useLiveQuery((q) => q.from({ books }));\n *     return <div>{data?.map(book => <p key={book.id}>{book.title}</p>)}</div>;\n * }\n * ```\n *\n * @example\n * Variadic useStore pattern:\n * ```tsx\n * function BooksWithAuthors() {\n *     const [books, authors] = useStore('books', 'authors');\n *\n *     const { data } = useLiveQuery((q) =>\n *         q.from({ book: books })\n *          .join(\n *              { author: authors },\n *              ({ book, author }) => eq(book.author, author.id),\n *              'left'\n *          )\n *     );\n *\n *     return <div>...</div>;\n * }\n * ```\n *\n * @example\n * With relations filed via alwaysFetchRelations:\n * ```tsx\n * const c = createCollection<Schema>(pb);\n * const authors = c('authors', { syncMode: 'on-demand' });\n * const books = c('books', {\n *     relations: { author: authors },\n *     alwaysFetchRelations: ['author'],\n * });\n *\n * const { Provider, useStore } = createReactProvider({ authors, books });\n *\n * function BooksWithAuthors() {\n *     const [books, authors] = useStore('books', 'authors');\n *     const { data } = useLiveQuery((q) =>\n *         q.from({ b: books }).select(({ b }) => ({\n *             ...b,\n *             author: materialize(\n *                 q.from({ a: authors }).where(({ a }) => eq(a.id, b.author)).findOne()\n *             ),\n *         }))\n *     );\n *\n *     return (\n *         <ul>\n *             {data?.map(row => (\n *                 <li key={row.id}>\n *                     {row.title} by {row.author?.name}\n *                 </li>\n *             ))}\n *         </ul>\n *     );\n * }\n * ```\n */\nexport function createReactProvider<CollectionsMap extends Record<string, unknown>>(\n    collections: CollectionsMap\n): ReactProviderResult<CollectionsMap> {\n    const Context = createContext<CollectionsMap | null>(null)\n\n    const Provider: React.FC<{ children: ReactNode }> = ({ children }) => (\n        <Context.Provider value={collections}>{children}</Context.Provider>\n    )\n\n    function useStore<K extends (keyof CollectionsMap)[]>(\n        ...keys: K\n    ): { [I in keyof K]: K[I] extends keyof CollectionsMap ? CollectionsMap[K[I]] : never } {\n        const context = useContext(Context)\n\n        if (!context) {\n            throw new Error(\n                'useStore must be used within the Provider returned by createReactProvider'\n            )\n        }\n\n        return keys.map(key => {\n            if (!(key in context)) {\n                throw new Error(`Collection \"${String(key)}\" not found in collections`)\n            }\n            return context[key]\n        }) as { [I in keyof K]: K[I] extends keyof CollectionsMap ? CollectionsMap[K[I]] : never }\n    }\n\n    return {\n        Provider,\n        useStore: useStore as UseStoreFn<CollectionsMap>,\n    }\n}\n\n/**\n * The current {@link SyncStatus} of `pb`'s collections, re-rendering on\n * each change. Use it for a connectivity notice: the realtime stream\n * dropping while REST still works, or queries stuck in retry.\n *\n * @example\n * ```tsx\n * function SyncNotice() {\n *     const { realtime, loads } = useSyncStatus(pb);\n *     if (realtime.state === 'reconnecting') return <p>Reconnecting…</p>;\n *     if (loads.retrying > 0) return <p>Retrying {loads.retrying} queries</p>;\n *     return null;\n * }\n * ```\n */\nexport function useSyncStatus(pb: PocketBase): SyncStatus {\n    return useSyncExternalStore(\n        listener => subscribeSyncStatus(pb, listener),\n        () => getSyncStatus(pb),\n        () => getSyncStatus(pb)\n    )\n}\n"]}