pbtsdb 0.11.0 → 2.0.1

package/llms.txt

@@ -1,6 +1,6 @@
 # pbtsdb
 
-> Type-safe PocketBase integration with TanStack Query and TanStack DB for React applications. Provides reactive collections with automatic real-time subscriptions, optimistic mutations, full TypeScript type safety, and minimal boilerplate.
+> Type-safe PocketBase integration with TanStack DB for React applications. Provides reactive collections with automatic real-time subscriptions, optimistic mutations, full TypeScript type safety, and minimal boilerplate.
 
 This library connects PocketBase (backend-as-a-service) to TanStack's reactive database tools. Use it when building React applications that need real-time data synchronization with PocketBase while maintaining strict type safety.
 
@@ -26,7 +26,7 @@ export type Schema = {
 }
 
 // 2. Create collections using curried createCollection
-const c = createCollection<Schema>(pb, queryClient);
+const c = createCollection<Schema>(pb);
 const collections = {
     books: c('books', {}),
     authors: c('authors', {}),
@@ -72,7 +72,7 @@ const [myBooks] = useStore('myBooks');
 
 ## Key Concepts
 
-- **createCollection**: Curried function `createCollection<Schema>(pb, queryClient, factoryOptions?)` returns `(collectionName, options) => Collection`
+- **createCollection**: Curried function `createCollection<Schema>(pb, factoryOptions?)` returns `(collectionName, options) => Collection`
 - **createReactProvider**: Wraps collections for React, returns `{ Provider, useStore }`
 - **Collections are lazy**: No network activity until first query
 - **Subscriptions are automatic**: Start when component mounts, stop 5s after unmount
@@ -86,7 +86,7 @@ For non-React environments, use `createCollection` directly:
 ```typescript
 import { createCollection } from 'pbtsdb';
 
-const c = createCollection<Schema>(pb, queryClient);
+const c = createCollection<Schema>(pb);
 const booksCollection = c('books', {});
 
 // Collections have TanStack DB interface
@@ -95,12 +95,12 @@ const booksCollection = c('books', {});
 
 ## Real-time Subscription Options
 
-The third `createCollection` argument applies to every collection the factory
+The second `createCollection` argument applies to every collection the factory
 builds. `subscribeOptions` is a getter invoked at subscribe time, so the value
 may change across reconnects:
 
 ```typescript
-const c = createCollection<Schema>(pb, queryClient, {
+const c = createCollection<Schema>(pb, {
     subscribeOptions: () => {
         const token = getShareToken();
         return token ? { headers: { 'X-Share-Token': token } } : undefined;
@@ -142,7 +142,7 @@ Collections support insert, update, and delete with automatic PocketBase sync:
 import { newRecordId, createCollection, createReactProvider } from 'pbtsdb';
 
 // Setup with custom mutation handlers (optional)
-const c = createCollection<Schema>(pb, queryClient);
+const c = createCollection<Schema>(pb);
 const collections = {
     books: c('books', {
         onInsert: async ({ transaction }) => { /* custom logic */ },
@@ -176,37 +176,38 @@ function BooksList() {
     // Delete with optimistic update
     books.delete('record_id');
 
-    // Batch mutations - merges multiple updates to same record
-    books.utils.writeBatch(() => {
-        books.update('id1', (draft) => { draft.field1 = 'value1' });
-        books.update('id1', (draft) => { draft.field2 = 'value2' }); // Merged!
-        books.update('id2', (draft) => { draft.field = 'value' });
-    });
-
-    // Wait for persistence
-    await tx.isPersisted.promise; // States: pending → persisting → completed
+    // Wait for persistence (isPersisted.promise is deprecated)
+    await tx.when('settled'); // States: pending → persisting → completed
 }
 ```
 
 **Key Points:**
 - Mutations are optimistic by default (UI updates immediately)
 - Auto-syncs to PocketBase in background
-- Batch mutations merge updates to same record
+- The built-in handlers write the server response into the collection before they settle, so the settled row is the server's row (`created`, `updated`, hook-rewritten values)
 - Transaction states: pending → persisting → completed
 - Use `newRecordId()` to generate PocketBase-compatible IDs
+- `row.$hasPendingWrites` is true while a row has an unsettled optimistic change (`$synced` is deprecated)
+- A custom `onInsert`/`onUpdate` should `await collection.accept(serverRows)` and a custom `onDelete` should `await collection.evict(ids)` before it returns `void`; otherwise the row shows its previous server value from settle until the realtime echo
+- `collection.accept(rows)` lands server-returned rows as confirmed state; `collection.evict(ids)` removes rows the server deleted; `collection.reload()` refetches every live query's subset and drops rows the results do not confirm. All three resolve on acceptance and are also on `collection.utils`
 
 ## Common Patterns
 
 **Approach 1: Related data (Recommended)**
 
 PocketBase `expand` only files related records into their own collections;
-rows never carry `expand`. Read related records from the target collection.
+rows never carry `expand`. Read related records from the target collection
+through `materialize()` or a join inside the `useLiveQuery` that needs them.
+Do not read them with `collection.get(id)` in a component: a `get()` does not
+re-render when the row changes, and the row can leave the store while the
+component still shows it. `get()` is for code outside React, such as a mutation
+handler.
 
 ```typescript
 import { eq } from '@tanstack/db';
 import { materialize } from 'pbtsdb';
 
-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 },   // where expanded records are filed
@@ -245,7 +246,7 @@ const { data } = useLiveQuery((q) => q.from({ books: books.fetchRelations('tags'
 
 **Approach 2: TanStack Joins**
 ```typescript
-const c = createCollection<Schema>(pb, queryClient);
+const c = createCollection<Schema>(pb);
 const collections = {
     jobs: c('jobs', {}),
     customers: c('customers', {}),
@@ -271,13 +272,16 @@ const [jobs, customers] = useStore('jobs', 'customers');
 
 - Simple CRUD without real-time (PocketBase SDK is simpler)
 - Very large collections (>10k records - use pagination)
-- Non-PocketBase backends (use TanStack Query directly)
+- Non-PocketBase backends (use `@tanstack/db` directly)
 - Server-side only Node.js (use PocketBase SDK directly)
 
 ### Package Details
 
-- Requires React 18+, TypeScript 5.0+, PocketBase 0.21.0+
-- Collections use TanStack Query for caching and TanStack DB for reactivity
-- Real-time via PocketBase Server-Sent Events (SSE)
-- Automatic reconnection with exponential backoff on subscription failures
+- Requires React 18+, TypeScript 5.0+, PocketBase 0.22.0+
+- Requires `@tanstack/db` 0.12.1+, `@tanstack/react-db` 0.5.5+
+- Collections use TanStack DB's core sync API, with pbtsdb's own membership ledger
+- Real-time via PocketBase Server-Sent Events (SSE), through pbtsdb's own client
+- Automatic reconnection with exponential backoff; a reconnect the server did
+  not resume refetches every live query, since PocketBase does not replay
+  events missed during the gap
 - Default syncMode is 'eager' (matches TanStack DB default)

package/package.json

@@ -1,11 +1,10 @@
 {
     "name": "pbtsdb",
-    "version": "0.11.0",
-    "description": "Type-safe PocketBase integration with TanStack Query and TanStack DB",
+    "version": "2.0.1",
+    "description": "Type-safe PocketBase integration with TanStack DB",
     "keywords": [
         "pocketbase",
         "tanstack",
-        "tanstack-query",
         "tanstack-db",
         "database",
         "react",
@@ -57,10 +56,8 @@
         "test:server:migrate": "pocketbase migrate --dir ./pb_data"
     },
     "peerDependencies": {
-        "@tanstack/db": ">=0.9.0",
-        "@tanstack/query-db-collection": ">=1.2.13",
-        "@tanstack/react-db": ">=0.3.8",
-        "@tanstack/react-query": ">=5.0.0",
+        "@tanstack/db": ">=0.12.1",
+        "@tanstack/react-db": ">=0.5.5",
         "pocketbase": ">=0.22.0",
         "react": ">=18.0.0",
         "react-dom": ">=18.0.0"
@@ -78,10 +75,8 @@
     },
     "devDependencies": {
         "@biomejs/biome": "^2.5.0",
-        "@tanstack/db": ">=0.9.0",
-        "@tanstack/query-db-collection": ">=1.2.13",
-        "@tanstack/react-db": ">=0.3.8",
-        "@tanstack/react-query": ">=5.101.0",
+        "@tanstack/db": ">=0.12.1",
+        "@tanstack/react-db": ">=0.5.5",
         "@testing-library/react": ">=16.3.2",
         "@types/node": ">=25.0.10",
         "@types/react": ">=19.2.10",