pbtsdb 0.7.3 → 0.9.0

package/README.md

@@ -10,7 +10,7 @@ A TypeScript library that seamlessly integrates [PocketBase](https://pocketbase.
 - 🔄 **Automatic caching** via TanStack Query
 - ✨ **Optimistic mutations** with insert/update/delete support
 - 🎨 **React hooks** for easy component integration
-- 🔗 **Type-safe joins** and relation expansion
+- 🔗 **Type-safe joins** and relation fetching into their own collections
 
 ## Table of Contents
 
@@ -19,34 +19,33 @@ A TypeScript library that seamlessly integrates [PocketBase](https://pocketbase.
 - [Core Concepts](#core-concepts)
 - [API Reference](#api-reference)
   - [createCollection()](#createcollection)
+  - [Related data](#related-data)
   - [React Integration](#react-integration)
   - [Subscriptions](#subscriptions)
+  - [Utility Functions](#utility-functions)
 - [Usage Examples](#usage-examples)
-  - [Basic Queries](#basic-queries)
-  - [Filtering and Sorting](#filtering-and-sorting)
-  - [Relations and Joins](#relations-and-joins)
   - [Includes (Nested Subqueries)](#includes-nested-subqueries)
-  - [Real-time Updates](#real-time-updates)
-  - [Mutations](#mutations)
 - [TypeScript](#typescript)
 - [Best Practices](#best-practices)
+- [Configuration](#configuration)
 
 ## Installation
 
 ```bash
-npm install pbtsdb pocketbase @tanstack/react-query @tanstack/react-db @tanstack/query-db-collection
+npm install pbtsdb pocketbase @tanstack/db @tanstack/query-db-collection @tanstack/react-query @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.0
-- `@tanstack/query-db-collection` >= 1.0.0
-- `react` >= 18.0.0
-- `react-dom` >= 18.0.0
+- `@tanstack/react-db` >= 0.1.86 (optional; only for `createReactProvider`)
+- `react` and `react-dom` >= 18.0.0 (optional)
 
-All peer dependencies use minimum version constraints - newer versions should work.
+All peer dependencies use minimum version constraints; newer versions should work. The
+non-React entry point `pbtsdb/core` needs neither `react` nor `@tanstack/react-db`.
 
 ## Quick Start
 
@@ -123,14 +122,19 @@ const queryClient = new QueryClient({
 
 // Create collections with automatic type inference
 const c = createCollection<BlogSchema>(pb, queryClient);
+const users = c('users', {});
 export const { Provider, useStore } = createReactProvider({
+    users,
     posts: c('posts', {
-        omitOnInsert: ['created', 'updated'] as const
+        omitOnInsert: ['created', 'updated'] as const,
+        relations: { author: users },
+        alwaysFetchRelations: ['author'],
     }),
-    users: c('users', {}),
     comments: c('comments', {
-        omitOnInsert: ['created', 'updated'] as const
-    })
+        omitOnInsert: ['created', 'updated'] as const,
+        relations: { author: users },
+        alwaysFetchRelations: ['author'],
+    }),
 });
 
 export function App() {
@@ -149,14 +153,22 @@ export function App() {
 ```typescript
 // BlogDashboard.tsx
 import { useLiveQuery } from '@tanstack/react-db';
+import { eq } from '@tanstack/db';
+import { materialize } from 'pbtsdb';
 import { useStore } from './app';
 
 export function BlogDashboard() {
-    const [posts] = useStore('posts');
+    const [posts, users] = useStore('posts', 'users');
 
     const { data: allPosts, isLoading } = useLiveQuery((q) =>
         q.from({ posts })
             .orderBy(({ posts }) => posts.created, 'desc')
+            .select(({ posts }) => ({
+                ...posts,
+                author: materialize(
+                    q.from({ u: users }).where(({ u }) => eq(u.id, posts.author)).findOne()
+                ),
+            }))
     );
 
     if (isLoading) return <div>Loading posts...</div>;
@@ -168,8 +180,8 @@ export function BlogDashboard() {
                 <article key={post.id}>
                     <h2>{post.title}</h2>
                     <p>{post.content}</p>
-                    {/* Expanded author is fully typed! */}
-                    <small>By {post.expand?.author?.username}</small>
+                    {/* Author was filed into the users collection by alwaysFetchRelations */}
+                    <small>By {post.author?.username}</small>
                 </article>
             ))}
         </div>
@@ -184,16 +196,22 @@ export function BlogDashboard() {
 import { useLiveQuery } from '@tanstack/react-db';
 import { eq } from '@tanstack/db';
 import { useStore } from './app';
-import { newRecordId } from 'pbtsdb';
+import { materialize, newRecordId } from 'pbtsdb';
 
 export function PostWithComments({ postId }: { postId: string }) {
-    const [comments, posts] = useStore('comments', 'posts');
+    const [comments, posts, users] = useStore('comments', 'posts', 'users');
 
     // Real-time comments for this post
     const { data: postComments } = useLiveQuery((q) =>
         q.from({ comments })
             .where(({ comments }) => eq(comments.post, postId))
             .orderBy(({ comments }) => comments.created, 'desc')
+            .select(({ comments }) => ({
+                ...comments,
+                author: materialize(
+                    q.from({ u: users }).where(({ u }) => eq(u.id, comments.author)).findOne()
+                ),
+            }))
     );
 
     const handleAddComment = (text: string, authorId: string) => {
@@ -211,7 +229,7 @@ export function PostWithComments({ postId }: { postId: string }) {
             <h3>Comments ({postComments?.length || 0})</h3>
             {postComments?.map(comment => (
                 <div key={comment.id}>
-                    <strong>{comment.expand?.author?.username}:</strong>
+                    <strong>{comment.author?.username}:</strong>
                     <p>{comment.text}</p>
                 </div>
             ))}
@@ -225,7 +243,7 @@ export function PostWithComments({ postId }: { postId: string }) {
 - ✅ Type-safe queries
 - ✅ Automatic real-time updates
 - ✅ Optimistic mutations
-- ✅ Expanded relations
+- ✅ Related data read from its own collection, no embedded copies
 
 ## Core Concepts
 
@@ -268,6 +286,22 @@ 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
 
+### Sync Modes
+
+Every collection is either **eager** (the default) or **on-demand**:
+
+```typescript
+const authors = c('authors', {});                       // eager: one full fetch, then realtime
+const books = c('books', { syncMode: 'on-demand' });    // on-demand: fetch what queries ask for
+```
+
+An eager collection loads all of its rows on first use and answers every query
+from memory. An on-demand collection translates each live query's `where`,
+`orderBy`, and `limit` into a PocketBase request, so only the rows a query asks
+for enter the store, and different filters are cached under different keys.
+Use on-demand for large collections; realtime keeps both modes current once rows
+are loaded.
+
 ### 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.
@@ -320,12 +354,14 @@ const collection = c(collectionName: string, options?: CreateCollectionOptions);
 - `options` - Optional configuration
 
 **Options:**
-- `expand?: Record<string, Collection>` - Relations to auto-expand and auto-upsert on every fetch
+- `relations?: Record<string, Collection>` - Collections that receive expanded records for each relation; declares what `alwaysFetchRelations` and `collection.fetchRelations()` may name
+- `alwaysFetchRelations?: readonly string[]` - Expand paths fetched with every request and filed into their `relations` targets; never kept on the row
 - `omitOnInsert?: readonly string[]` - Fields to make optional during insert (e.g., `['created', 'updated'] as const`)
 - `syncMode?: 'eager' | 'on-demand'` - Data fetching strategy (default: `'eager'`)
 - `onInsert?: InsertMutationFn | false` - Custom insert handler or `false` to disable
 - `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))
 
@@ -339,40 +375,81 @@ const c = createCollection<MySchema>(pb, queryClient);
 const booksCollection = c('books', {});
 ```
 
-With auto-expand relations:
+#### Related data
+
+PocketBase `expand` is used only to bring related records into their own
+collections. Rows never carry `expand`; read related records from the target
+collection.
+
 ```typescript
 const c = createCollection<MySchema>(pb, queryClient);
-const authorsCollection = c('authors', {});
-const booksCollection = c('books', {
-    expand: {
-        author: authorsCollection  // Auto-expand and auto-upsert
-    }
+const authors = c('authors', { syncMode: 'on-demand' });
+const tags = c('tags', { syncMode: 'on-demand' });
+const books = c('books', {
+    relations: { author: authors, tags },   // where expanded records are filed
+    alwaysFetchRelations: ['author'],       // fetched with every books request
 });
+```
 
-// Expand is automatic on every fetch
-const { data } = useLiveQuery((q) => q.from({ books: booksCollection }));
+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)`:
 
-// Expanded records auto-inserted into authorsCollection
+```typescript
+import { eq } from '@tanstack/db';
+import { materialize } from 'pbtsdb';
+
+const { data } = useLiveQuery((q) =>
+    q.from({ b: books }).select(({ b }) => ({
+        ...b,
+        author: materialize(
+            q.from({ a: authors }).where(({ a }) => eq(a.id, b.author)).findOne()
+        ),
+    }))
+);
+// data[0].author?.name is Authors | undefined and updates when the author changes
+```
+
+Because the authors are already in the store, that include makes no request:
+an id-only load (`eq(id, x)`, `inArray(id, [...])`, or an `or` of those) is
+served from the synced store when every id is present, except when the query
+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.
+
+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:
+
+```typescript
+const { data } = useLiveQuery((q) => q.from({ b: books.fetchRelations('tags') }));
+// tags referenced by these books are now in the tags collection
 ```
 
+Paths can be nested through a target collection's own `relations`
+(`'book.author'`). While a query fetches into a target, that target keeps its
+realtime subscription, so `get()` reads stay fresh.
+
 #### Collection Options Passthrough
 
 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
-import { BasicIndex } from 'pbtsdb';
-
 const c = createCollection<MySchema>(pb, queryClient);
 const booksCollection = c('books', {
     collectionOptions: {
-        autoIndex: 'eager',
-        defaultIndexType: BasicIndex,
         gcTime: 60000,       // 1 minute GC
         startSync: true,     // Start syncing immediately
     }
 });
 ```
 
+pbtsdb defaults `autoIndex` to `'eager'` with `defaultIndexType: BTreeIndex`, so
+`orderBy` + `limit` queries page lazily instead of loading the whole subset (and
+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`.
 
 ### React Integration
@@ -534,6 +611,10 @@ both transports:
 Setting the matching header on REST requests remains the application's job, via
 `pb.beforeSend`. Requires `pocketbase >= 0.22.0`.
 
+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.
+
 ### Utility Functions
 
 #### newRecordId()
@@ -564,6 +645,7 @@ pbtsdb re-exports commonly used TanStack DB utilities so you don't need to depen
 ```typescript
 import {
     // Includes helpers
+    materialize,
     toArray,
     createEffect,
 
@@ -624,7 +706,7 @@ export function TaskBoard({ userId }: { userId: string }) {
 ```typescript
 // ProductCatalog.tsx
 import { useLiveQuery } from '@tanstack/react-db';
-import { and, gte, lte } from '@tanstack/db';
+import { and, eq, lte } from '@tanstack/db';
 import { useStore } from './app';
 
 export function ProductCatalog() {
@@ -636,12 +718,12 @@ export function ProductCatalog() {
     const { data: filteredProducts } = useLiveQuery((q) => {
         let query = q.from({ products })
             .where(({ products }) => and(
-                products.in_stock === true,
+                eq(products.in_stock, true),
                 lte(products.price, maxPrice)
             ));
 
         if (category) {
-            query = query.where(({ products }) => products.category === category);
+            query = query.where(({ products }) => eq(products.category, category));
         }
 
         return query.orderBy(({ products }) => products.rating, 'desc');
@@ -671,13 +753,20 @@ export function ProductCatalog() {
 import { useLiveQuery } from '@tanstack/react-db';
 import { eq } from '@tanstack/db';
 import { useStore } from './app';
-import { newRecordId } from 'pbtsdb';
+import { materialize, newRecordId } from 'pbtsdb';
 
 export function SocialFeed({ currentUserId }: { currentUserId: string }) {
-    const [posts, likes] = useStore('posts', 'likes');
+    const [posts, likes, users] = useStore('posts', 'likes', 'users');
 
     const { data: feedPosts } = useLiveQuery((q) =>
-        q.from({ posts }).orderBy(({ posts }) => posts.created, 'desc')
+        q.from({ posts })
+            .orderBy(({ posts }) => posts.created, 'desc')
+            .select(({ posts }) => ({
+                ...posts,
+                author: materialize(
+                    q.from({ u: users }).where(({ u }) => eq(u.id, posts.author)).findOne()
+                ),
+            }))
     );
 
     const { data: userLikes } = useLiveQuery((q) =>
@@ -699,7 +788,7 @@ export function SocialFeed({ currentUserId }: { currentUserId: string }) {
         <div>
             {feedPosts?.map(post => (
                 <div key={post.id}>
-                    <strong>{post.expand?.author?.username}</strong>
+                    <strong>{post.author?.username}</strong>
                     <p>{post.content}</p>
                     <button onClick={() => handleLike(post.id)}>
                         {likedPostIds.has(post.id) ? '❤️' : '🤍'} {post.likes_count}
@@ -781,8 +870,9 @@ export function CreateBookForm() {
 
             if (tx.state === 'completed') setTitle('');
             else setError('Failed to create book');
-        } catch (err: any) {
-            setError(err.data ? Object.values(err.data).join(', ') : err.message);
+        } catch (err) {
+            const failure = err as { data?: Record<string, unknown>; message?: string };
+            setError(failure.data ? Object.values(failure.data).join(', ') : failure.message ?? 'Failed');
         }
     };
 
@@ -846,20 +936,27 @@ TanStack DB 0.6.0 introduces **includes** — nested subqueries within `select()
 
 #### Single relation with `findOne()`
 
+Wrap a `findOne()` subquery in `materialize()` to get a plain `T | undefined`
+value that updates when the child changes. Without it, the include is a live
+sub-collection rather than a value.
+
 ```typescript
 import { useLiveQuery, eq } from '@tanstack/react-db';
+import { materialize } from 'pbtsdb';
 
 const { data: booksWithAuthors } = useLiveQuery((q) =>
     q.from({ b: booksCollection }).select(({ b }) => ({
         id: b.id,
         title: b.title,
-        author: q
-            .from({ a: authorsCollection })
-            .where(({ a }) => eq(a.id, b.author))
-            .select(({ a }) => ({ id: a.id, name: a.name }))
-            .findOne(),
+        author: materialize(
+            q.from({ a: authorsCollection })
+                .where(({ a }) => eq(a.id, b.author))
+                .select(({ a }) => ({ id: a.id, name: a.name }))
+                .findOne()
+        ),
     }))
 );
+// booksWithAuthors[0].author?.name
 ```
 
 #### Many relation with `toArray()`
@@ -882,26 +979,31 @@ const { data: booksWithTags } = useLiveQuery((q) =>
 );
 ```
 
-#### Combining expand with includes
+#### Includes on filed relations
 
-Use PocketBase's `expand` to auto-populate a related collection, then use includes to query from it:
+Use PocketBase's `expand` to file a relation into its target collection, then use includes to query from it. Because the rows are already in the store, the include makes no request:
 
 ```typescript
 const authorsCollection = c('authors', { syncMode: 'on-demand' });
+const tagsCollection = c('tags', { syncMode: 'on-demand' });
+const bookTagsCollection = c('book_tags', { syncMode: 'on-demand' });
 const booksCollection = c('books', {
     syncMode: 'on-demand',
-    expand: { author: authorsCollection },  // Auto-populates authorsCollection
+    relations: { author: authorsCollection },  // where expanded authors are filed
+    alwaysFetchRelations: ['author'],
 });
 
 const { data } = useLiveQuery((q) =>
     q.from({ b: booksCollection }).select(({ b }) => ({
         id: b.id,
         title: b.title,
-        // Query from the expand-populated authorsCollection
-        author: q.from({ a: authorsCollection })
-            .where(({ a }) => eq(a.id, b.author))
-            .select(({ a }) => ({ id: a.id, name: a.name }))
-            .findOne(),
+        // Reads from authorsCollection with no request; the rows are already filed
+        author: materialize(
+            q.from({ a: authorsCollection })
+                .where(({ a }) => eq(a.id, b.author))
+                .select(({ a }) => ({ id: a.id, name: a.name }))
+                .findOne()
+        ),
         tags: toArray(
             q.from({ bt: bookTagsCollection })
                 .where(({ bt }) => eq(bt.book, b.id))
@@ -944,12 +1046,11 @@ const books = c('books', {
     omitOnInsert: ['created', 'updated'] as const
 });
 
-// ✅ Good - with auto-expand relations
+// ✅ Good - with always-fetched relations
 const authors = c('authors', {});
 const books = c('books', {
-    expand: {
-        author: authors
-    }
+    relations: { author: authors },
+    alwaysFetchRelations: ['author'],
 });
 ```
 
@@ -972,23 +1073,23 @@ export const { Provider, useStore } = createReactProvider({
 
 ### 2. Create Dependencies Before Dependents
 
-When using expand collections, create the target collection first:
+When declaring `relations`, create the target collection first:
 
 ```typescript
 // ✅ Good - authors exists before books references it
 const c = createCollection<MySchema>(pb, queryClient);
 const authors = c('authors', {});
 const books = c('books', {
-    expand: {
-        author: authors  // authors is already created
-    }
+    relations: { author: authors },  // authors is already created
+    alwaysFetchRelations: ['author'],
 });
 
 // ❌ Bad - can't reference what doesn't exist yet
 const books = c('books', {
-    expand: {
+    relations: {
         author: ???  // Where is authors?
-    }
+    },
+    alwaysFetchRelations: ['author'],
 });
 ```
 
@@ -1021,26 +1122,28 @@ if (!data?.length) return <div>No posts found</div>;
 return <PostsList posts={data} />;
 ```
 
-### 5. Use Expand for Performance
+### 5. Choose Between alwaysFetchRelations and Joins
 
-Use PocketBase's expand feature for better performance:
+`alwaysFetchRelations` costs one request but carries the related record once
+per parent row, on every fetch of the parent:
 
 ```typescript
-// ✅ Fast - single query with server-side expand
 const c = createCollection<MySchema>(pb, queryClient);
 const authors = c('authors', {});
 const posts = c('posts', {
-    expand: {
-        author: authors  // Auto-expand on every fetch
-    }
+    relations: { author: authors },
+    alwaysFetchRelations: ['author'],  // expanded on every posts request
 });
 
 const { data } = useLiveQuery((q) => q.from({ posts }));
-
-// ⚠️ Slower - multiple queries + client-side join
-// Only use TanStack DB joins for inner/right/full join behavior
 ```
 
+A join or a `materialize()` include costs one batched request per query
+(fetching each distinct related row once, however many parent rows reference
+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
@@ -1119,12 +1222,13 @@ Contributions welcome! Please open an issue or PR.
 ### Development Setup
 
 **Prerequisites:**
-- Node.js 18+
+- Node.js 20+
 - Git
+- The [PocketBase](https://pocketbase.io/docs/) binary on your `PATH` (the test server uses it)
 
 **Clone and Install:**
 ```bash
-git clone https://github.com/yourusername/pbtsdb
+git clone https://github.com/nathanstitt/pbtsdb
 cd pbtsdb
 npm install
 ```