pbtsdb 0.11.0 → 2.0.1

package/README.md

@@ -1,13 +1,12 @@
 # pbtsdb: PocketBase TanStack Database Integration
 
-> Type-safe PocketBase integration with TanStack Query and TanStack DB
+> Type-safe PocketBase integration with TanStack DB
 
-A TypeScript library that seamlessly integrates [PocketBase](https://pocketbase.io) with [TanStack Query](https://tanstack.com/query) and [TanStack DB](https://tanstack.com/db), providing:
+A TypeScript library that seamlessly integrates [PocketBase](https://pocketbase.io) with [TanStack DB](https://tanstack.com/db), providing:
 
 - 🔥 **Real-time subscriptions** with automatic synchronization
 - 🎯 **Full TypeScript type safety** for queries and relations
 - ⚡ **Reactive collections** with TanStack DB
-- 🔄 **Automatic caching** via TanStack Query
 - ✨ **Optimistic mutations** with insert/update/delete support
 - 🎨 **React hooks** for easy component integration
 - 🔗 **Type-safe joins** and relation fetching into their own collections
@@ -22,6 +21,7 @@ A TypeScript library that seamlessly integrates [PocketBase](https://pocketbase.
   - [Related data](#related-data)
   - [React Integration](#react-integration)
   - [Subscriptions](#subscriptions)
+  - [Sync Status API](#sync-status-api)
   - [Utility Functions](#utility-functions)
 - [Usage Examples](#usage-examples)
   - [Includes (Nested Subqueries)](#includes-nested-subqueries)
@@ -32,16 +32,14 @@ A TypeScript library that seamlessly integrates [PocketBase](https://pocketbase.
 ## Installation
 
 ```bash
-npm install pbtsdb pocketbase @tanstack/db @tanstack/query-db-collection @tanstack/react-query @tanstack/react-db
+npm install pbtsdb pocketbase @tanstack/db @tanstack/react-db
 ```
 
 ### Peer Dependencies
 
 - `pocketbase` >= 0.22.0
-- `@tanstack/db` >= 0.6.0
-- `@tanstack/query-db-collection` >= 1.0.40
-- `@tanstack/react-query` >= 5.0.0
-- `@tanstack/react-db` >= 0.1.86 (optional; only for `createReactProvider`)
+- `@tanstack/db` >= 0.12.1
+- `@tanstack/react-db` >= 0.5.5 (optional; only for `createReactProvider`)
 - `react` and `react-dom` >= 18.0.0 (optional)
 
 All peer dependencies use minimum version constraints; newer versions should work. The
@@ -110,18 +108,12 @@ type BlogSchema = {
 ```typescript
 // app.tsx
 import PocketBase from 'pocketbase';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { createCollection, createReactProvider } from 'pbtsdb';
 
 const pb = new PocketBase('http://localhost:8090');
-const queryClient = new QueryClient({
-    defaultOptions: {
-        queries: { staleTime: 60_000 } // Cache for 1 minute
-    }
-});
 
 // Create collections with automatic type inference
-const c = createCollection<BlogSchema>(pb, queryClient);
+const c = createCollection<BlogSchema>(pb);
 const users = c('users', {});
 export const { Provider, useStore } = createReactProvider({
     users,
@@ -139,11 +131,9 @@ export const { Provider, useStore } = createReactProvider({
 
 export function App() {
     return (
-        <QueryClientProvider client={queryClient}>
-            <Provider>
-                <BlogDashboard />
-            </Provider>
-        </QueryClientProvider>
+        <Provider>
+            <BlogDashboard />
+        </Provider>
     );
 }
 ```
@@ -253,14 +243,13 @@ Collections are reactive data stores that automatically sync with PocketBase:
 
 ```typescript
 // Create a collection using the curried API
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 const booksCollection = c('books', {});
 
 // Collections automatically:
 // - Fetch data from PocketBase
 // - Subscribe to real-time updates
 // - Update React components when data changes
-// - Cache data via TanStack Query
 ```
 
 ### Real-time Subscriptions
@@ -269,7 +258,7 @@ Collections manage subscriptions **automatically** based on query lifecycle:
 
 ```typescript
 // Collections are lazy - no subscription until queried
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 const booksCollection = c('books', {});
 
 // Subscription starts automatically when query becomes active
@@ -286,6 +275,74 @@ const { data } = useLiveQuery((q) =>
 - **Shared:** Multiple components using the same collection share one subscription
 - **No manual control needed:** The collection handles all subscription management internally
 
+### Reconnects
+
+pbtsdb runs its own realtime connection. When the connection drops, it reconnects with backoff and refetches every live query, because PocketBase does not replay events missed during the gap. A server that supports pbtsdb's resume extension (`?resume=<clientId>&after=<seq>` on the SSE URL, `resumed: true` in `PB_CONNECT`, `seq` on each event) replays the gap instead, and no refetch runs.
+
+pbtsdb's connection is independent of `pb.realtime`. When `pb.authStore` changes to another auth record (login, logout, switching users), pbtsdb forgets the connection's server-side session and reconnects at once, re-sending every subscribed topic under the new auth; every ready collection reloads once that POST succeeds, the same as a non-resumed reconnect. A token refresh for the same record changes nothing. PocketBase would otherwise answer the next subscriptions POST with a 403, or keep serving the previous user's data.
+
+Call `resetRealtime(pb)` yourself for a change the auth store cannot see, such as pointing `pb` at another server:
+
+```typescript
+import { disconnectRealtime, resetRealtime } from 'pbtsdb';
+
+resetRealtime(pb); // forget the session and re-subscribe every open topic now
+
+disconnectRealtime(pb); // close the connection and keep it closed
+resetRealtime(pb); // open it again; every ready collection reloads
+```
+
+`disconnectRealtime(pb)` closes the connection and keeps it closed until `resetRealtime(pb)`. Collections keep working over REST and keep their subscriptions registered. Use it at logout, or at startup where realtime is not wanted, such as an embedded view.
+
+### Sync Status
+
+Two problems are visible only to pbtsdb: the realtime stream dropping while REST still works, so lists look fine but stop updating; and a query sleeping in its load retry backoff, so a list sits in "loading" with no reason shown. `getSyncStatus(pb)` reports both, for every collection of one client:
+
+```typescript
+import { getSyncStatus, subscribeSyncStatus } from 'pbtsdb';
+
+const status = getSyncStatus(pb);
+// {
+//     realtime:
+//         | { state: 'disabled' }    // disconnectRealtime(pb), or no collection has subscribed yet
+//         | { state: 'connecting' }  // the first connection of a session is opening
+//         | { state: 'connected' }   // stream open, PB_CONNECT received
+//         | { state: 'reconnecting'; attempt: number; nextRetryAt: number; since: number },
+//     loads: {
+//         retrying: number,       // live queries sleeping in loadRetryDelays backoff
+//         failingSince?: number,  // when the oldest of them first failed, epoch ms
+//         failed: number,         // live queries whose load ended in a 4xx that is not retried
+//     },
+// }
+
+const stop = subscribeSyncStatus(pb, status => console.log(status));
+```
+
+`reconnecting` means the stream was up and dropped, or a retry never came up, and the next retry is scheduled; the first connection of a session reports `connecting` instead. `nextRetryAt` and `since` are epoch milliseconds, and `nextRetryAt` changes only when a new retry is scheduled. `disabled` is not a problem state: it is what `disconnectRealtime(pb)` asks for, and what an app sees before login.
+
+`retrying` counts only demands a live query still holds; a parked subset or an unmounted query is never counted. `failed` is separate because a 403 or 404 is an answer, not an outage; the count drops when the query reloads or unmounts.
+
+The snapshot is stable: `getSyncStatus(pb)` returns the same object, with the same nested objects, until a value changes. The React entry point wraps it in `useSyncStatus(pb)`:
+
+```tsx
+import { useSyncStatus } from 'pbtsdb';
+
+function SyncNotice() {
+    const { realtime, loads } = useSyncStatus(pb);
+    if (realtime.state === 'reconnecting') return <p>Live updates paused, reconnecting…</p>;
+    if (loads.retrying > 0) return <p>Retrying {loads.retrying} queries…</p>;
+    return null;
+}
+```
+
+The shape of `SyncStatus` is public and changes only in a major release.
+
+### Subset Lifetime
+
+In on-demand mode a live query's subset is released when the last subscriber unmounts, after a grace window of `subsetGcTime` milliseconds (default 5000). A query with an equal request that mounts within the window reuses the rows with no request. Realtime keeps the parked rows fresh, and rows a parent filed through a relation stay for the same window, so a panel that mounts and unmounts quickly costs no refetch. `collection.reload()` releases every parked subset. An auth change releases every waiting subset and every accepted row at once and reloads every live subset under the new auth, whether or not realtime is connected, so a load right after a logout never reuses the previous user's rows and the order of `authStore.clear()` and `disconnectRealtime(pb)` does not matter. Set `subsetGcTime: 0` to release a subset as soon as it unloads; `0` also keeps accepted rows until a reload or idle instead of expiring them.
+
+A subset load that fails is retried with backoff (`loadRetryDelays`, default 1, 2, 4, 8, 15 and then every 30 seconds) until it succeeds, so a live query stays loading through an outage instead of entering an error state it cannot leave. A `collection.reload()` or a realtime reconnect retries at once, also while another reload is running. 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 and then retries. Delays carry a little jitter so many queries do not retry in lockstep.
+
 ### Sync Modes
 
 Every collection is either **eager** (the default) or **on-demand**:
@@ -331,9 +388,9 @@ builder still loads the first `n + limit` rows. Put a page boundary in the
 
 ### Mutations and Refetch
 
-By default, pbtsdb does **not** refetch the entire collection after a successful insert, update, or delete. The realtime subscription delivers server-confirmed rows — including server-assigned fields like `id`, `created`, `updated`, and any values rewritten by PocketBase hooks — and TanStack DB's optimistic write keeps the UI consistent in the meantime. The post-mutation refetch is therefore redundant.
+The built-in handlers write PocketBase's response into the collection before they return: server-assigned fields like `created` and `updated`, and any values rewritten by PocketBase hooks. A built-in delete removes the row the same way. TanStack DB drops a mutation's optimistic state when its handler settles, and rows written while the handler runs publish together with that drop, so the settled row is the server's row with no gap. The realtime echo that follows changes nothing.
 
-Set `refetchOnMutation: true` to opt back into the previous behavior — for example, when realtime is unreliable in your environment, or when a server-side hook produces a field you must read synchronously after the mutation resolves:
+By default, pbtsdb does **not** refetch after a successful insert, update, or delete. Set `refetchOnMutation: true` to refetch the collection's active queries before the handler settles — for example, when a server-side hook changes other rows you must read right after the mutation:
 
 ```typescript
 const collection = c('books', {
@@ -341,7 +398,23 @@ const collection = c('books', {
 });
 ```
 
-The option only affects the built-in default handlers. If you supply your own `onInsert`, `onUpdate`, or `onDelete`, you control its return value yourself — return `{ refetch: false }` (or omit a return) to skip the refetch, return `{ refetch: true }` to force one.
+The option only affects the built-in default handlers. A custom `onInsert`, `onUpdate`, or `onDelete` controls write-back itself:
+
+- TanStack DB drops the optimistic state when your handler returns. Until the realtime echo arrives, the row shows its previous server value: an updated row reverts, an inserted row disappears, and a deleted row comes back.
+- For an insert or an update, `await collection.accept(serverRows)` before you return. This closes the gap.
+- For a delete, `await collection.evict(ids)` before you return. Without it, the deleted row shows again until the delete echo arrives.
+- In on-demand mode, when realtime goes idle (no live query on the collection), rows held only by an accepted write-back are released. A row written back while nothing is mounted is fetched again on the next mount.
+- The handler returns `void`. Core no longer reads a `{ refetch }` result; call `collection.reload()` yourself if the handler needs a refetch.
+
+### Writing server rows yourself
+
+`collection.accept(rows)` lands rows the server returned, for example the response of a custom endpoint, as confirmed state. A row older than the stored one is ignored. Use it when the screen must update before the realtime echo arrives. It resolves when the rows are accepted, so a custom mutation handler can await it.
+
+`collection.evict(ids)` removes 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. It resolves when the removal is accepted, so a custom delete handler can await it.
+
+`collection.reload()` refetches every live query's subset. Then it releases the realtime-topic and accepted holders of the rows the results do not confirm. A row that a parent filed through a relation stays. Use it when the server state changed with no realtime event, such as after a user loses access to rows.
+
+All three are also on `collection.utils`.
 
 ### Type Safety
 
@@ -367,7 +440,6 @@ The main function for creating type-safe collections. Uses a curried API for bet
 ```typescript
 const c = createCollection<Schema>(
     pb: PocketBase,
-    queryClient: QueryClient,
     factoryOptions?: CreateCollectionFactoryOptions
 );
 const collection = c(collectionName: string, options?: CreateCollectionOptions);
@@ -375,7 +447,6 @@ const collection = c(collectionName: string, options?: CreateCollectionOptions);
 
 **Parameters:**
 - `pb` - PocketBase instance
-- `queryClient` - TanStack Query QueryClient instance
 - `factoryOptions` - Optional configuration applied to every collection this factory builds (see [Subscription Options](#subscription-options))
 - `collectionName` - Name of the PocketBase collection
 - `options` - Optional configuration
@@ -390,7 +461,6 @@ const collection = c(collectionName: string, options?: CreateCollectionOptions);
 - `onUpdate?: UpdateMutationFn | false` - Custom update handler or `false` to disable
 - `onDelete?: DeleteMutationFn | false` - Custom delete handler or `false` to disable
 - `refetchOnMutation?: boolean` - Refetch the collection after a built-in insert/update/delete succeeds (default: `false`; see [Mutations and Refetch](#mutations-and-refetch))
-- `ignoreAutoCancellation?: boolean` - Ignore PocketBase auto-cancellation errors (default: `true`)
 - `collectionOptions?: object` - Additional TanStack DB collection options passed through directly (see [Collection Options Passthrough](#collection-options-passthrough))
 
 **Returns:** Fully-typed Collection instance with subscription capabilities
@@ -399,7 +469,7 @@ const collection = c(collectionName: string, options?: CreateCollectionOptions);
 
 Basic collection (lazy, subscribes automatically on first query):
 ```typescript
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 const booksCollection = c('books', {});
 ```
 
@@ -410,7 +480,7 @@ collections. Rows never carry `expand`; read related records from the target
 collection.
 
 ```typescript
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 const authors = c('authors', { syncMode: 'on-demand' });
 const tags = c('tags', { syncMode: 'on-demand' });
 const books = c('books', {
@@ -421,8 +491,8 @@ const books = c('books', {
 
 Every books request expands `author`; the expanded authors are filed into
 `authors` (an on-demand target has its sync started) and removed from the
-book rows. Read them through `materialize()` in a query, a join, or
-`authors.get(book.author)`:
+book rows. Read them through `materialize()` in a query or through a join,
+inside the `useLiveQuery` that needs them:
 
 ```typescript
 import { eq } from '@tanstack/db';
@@ -446,6 +516,14 @@ reads through a `fetchRelations()` view, whose fetch goes to PocketBase so its
 paths get filed; anything else is fetched in one batched request. An empty
 `inArray(id, [])` yields no rows and no request.
 
+Do not read a related row with `authors.get(book.author)` in a component. A
+`get()` is a one-time read: the component does not re-render when the author
+changes, and the row can leave the store while the component still shows it,
+because a filed row stays only as long as a live query holds the parent row
+that filed it. A `useLiveQuery` with `materialize()` or a join holds the rows
+it reads and re-renders when they change. `get()` is for code outside React
+that needs a value right now, such as a mutation handler or a test.
+
 Fetch a relation for one query only with `fetchRelations()`; the view shares the
 collection's store, realtime subscription, and mutations, and only its fetches
 add the `expand` parameter:
@@ -490,7 +568,7 @@ never treated as complete.
 Pass any [TanStack DB `BaseCollectionConfig`](https://tanstack.com/db/latest/docs/overview) option directly via `collectionOptions`. This is useful for configuring indexing, garbage collection, and other collection-level settings:
 
 ```typescript
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 const booksCollection = c('books', {
     collectionOptions: {
         gcTime: 60000,       // 1 minute GC
@@ -504,7 +582,7 @@ pbtsdb defaults `autoIndex` to `'eager'` with `defaultIndexType: BTreeIndex`, so
 TanStack DB does not warn about a missing index). Pass `autoIndex: 'off'` or a
 different `defaultIndexType` in `collectionOptions` to change that per collection.
 
-The following fields are managed by pbtsdb and excluded from `collectionOptions`: `getKey`, `syncMode`, `onInsert`, `onUpdate`, `onDelete`, `schema`.
+The following fields are managed by pbtsdb and excluded from `collectionOptions`: `getKey`, `syncMode`, `onInsert`, `onUpdate`, `onDelete`, `schema`, `utils`.
 
 ### React Integration
 
@@ -527,7 +605,7 @@ const { Provider, useStore } = createReactProvider(collections: CollectionsMap);
 ```typescript
 import { createCollection, createReactProvider } from 'pbtsdb';
 
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 const collections = {
     authors: c('authors', {}),
     books: c('books', {
@@ -685,7 +763,7 @@ options — `headers`, `filter`, `expand`, `fields` — to every real-time
 subscription the factory creates.
 
 ```typescript
-const c = createCollection<Schema>(pb, queryClient, {
+const c = createCollection<Schema>(pb, {
     subscribeOptions: () => {
         const token = getShareToken();
         return token ? { headers: { 'X-Share-Token': token } } : undefined;
@@ -717,6 +795,32 @@ An `expand` you add here is yours: pbtsdb strips only the paths it requested
 through `alwaysFetchRelations` and `fetchRelations()`, so records expanded by
 this option stay on the echoed rows, untyped.
 
+### Sync Status API
+
+#### getSyncStatus()
+
+```typescript
+getSyncStatus(pb: PocketBase): SyncStatus
+```
+
+The current [sync status](#sync-status) of `pb`'s collections. The returned object is stable until a value changes.
+
+#### subscribeSyncStatus()
+
+```typescript
+subscribeSyncStatus(pb: PocketBase, listener: (status: SyncStatus) => void): () => void
+```
+
+Calls `listener` with each new snapshot. Returns the unsubscribe function.
+
+#### useSyncStatus()
+
+```typescript
+useSyncStatus(pb: PocketBase): SyncStatus
+```
+
+React hook over the two functions above, built on `useSyncExternalStore`. Exported from `pbtsdb`, not from `pbtsdb/core`.
+
 ### Utility Functions
 
 #### newRecordId()
@@ -968,7 +1072,7 @@ export function CreateBookForm() {
         try {
             // Optimistic insert - appears instantly
             const tx = books.insert({ id: newRecordId(), title, author: 'author_id' });
-            await tx.isPersisted.promise;
+            await tx.when('settled');
 
             if (tx.state === 'completed') setTitle('');
             else setError('Failed to create book');
@@ -1143,7 +1247,7 @@ Always create collections with proper type parameters:
 
 ```typescript
 // ✅ Good - full type safety
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 const books = c('books', {
     omitOnInsert: ['created', 'updated'] as const
 });
@@ -1164,7 +1268,7 @@ Define all collections once at app initialization:
 
 ```typescript
 // ✅ Do this - centralized, type-safe
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 
 export const { Provider, useStore } = createReactProvider({
     posts: c('posts', { omitOnInsert: ['created', 'updated'] as const }),
@@ -1179,7 +1283,7 @@ When declaring `relations`, create the target collection first:
 
 ```typescript
 // ✅ Good - authors exists before books references it
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 const authors = c('authors', {});
 const books = c('books', {
     relations: { author: authors },  // authors is already created
@@ -1230,7 +1334,7 @@ return <PostsList posts={data} />;
 per parent row, on every fetch of the parent:
 
 ```typescript
-const c = createCollection<MySchema>(pb, queryClient);
+const c = createCollection<MySchema>(pb);
 const authors = c('authors', {});
 const posts = c('posts', {
     relations: { author: authors },
@@ -1246,20 +1350,6 @@ it) and, once the rows are filed, subsequent queries make no request at all.
 Prefer `alwaysFetchRelations` when the parent is the only path by which those
 rows enter an on-demand collection; otherwise let the query load them.
 
-### 6. Configure QueryClient Defaults
-
-```typescript
-const queryClient = new QueryClient({
-    defaultOptions: {
-        queries: {
-            staleTime: 60_000,      // 1 minute
-            gcTime: 300_000,        // 5 minutes
-            refetchOnWindowFocus: false
-        }
-    }
-});
-```
-
 ## Configuration
 
 ### Custom Logger Integration
@@ -1381,6 +1471,5 @@ npm run typecheck   # TypeScript only
 
 **Built with:**
 - [PocketBase](https://pocketbase.io) - Backend-as-a-Service
-- [TanStack Query](https://tanstack.com/query) - Powerful data fetching
 - [TanStack DB](https://tanstack.com/db) - Reactive database
 - [TypeScript](https://www.typescriptlang.org) - Type safety