pbtsdb 0.0.1 → 0.1.0

package/README.md

@@ -8,6 +8,7 @@ A TypeScript library that seamlessly integrates [PocketBase](https://pocketbase.
 - 🎯 **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 expansion
 
@@ -17,21 +18,22 @@ A TypeScript library that seamlessly integrates [PocketBase](https://pocketbase.
 - [Quick Start](#quick-start)
 - [Core Concepts](#core-concepts)
 - [API Reference](#api-reference)
-  - [CollectionFactory](#collectionfactory)
-  - [React Provider](#react-provider)
+  - [createCollection()](#createcollection)
+  - [React Integration](#react-integration)
   - [Subscriptions](#subscriptions)
 - [Usage Examples](#usage-examples)
   - [Basic Queries](#basic-queries)
   - [Filtering and Sorting](#filtering-and-sorting)
   - [Relations and Joins](#relations-and-joins)
   - [Real-time Updates](#real-time-updates)
+  - [Mutations](#mutations)
 - [TypeScript](#typescript)
 - [Best Practices](#best-practices)
 
 ## Installation
 
 ```bash
-npm install pocketbase-tanstack-db pocketbase @tanstack/react-query @tanstack/react-db @tanstack/query-db-collection
+npm install pbtsdb pocketbase @tanstack/react-query @tanstack/react-db @tanstack/query-db-collection
 ```
 
 ### Peer Dependencies
@@ -43,107 +45,187 @@ npm install pocketbase-tanstack-db pocketbase @tanstack/react-query @tanstack/re
 - `react` >= 18.0.0
 - `react-dom` >= 18.0.0
 
+All peer dependencies use minimum version constraints - newer versions should work.
+
 ## Quick Start
 
+Let's build a **real-world blog** with posts, authors, and comments using pbtsdb.
+
 ### 1. Define Your Schema
 
-Create type-safe schema definitions for your PocketBase collections.  The schema should be formed like the below, it's recommended
-that you install https://github.com/satohshi/pocketbase-schema-generator as a pocketbase hook.  When configured a schema file will be auto-generated on every schema change.
+First, generate your types from PocketBase. Install [pocketbase-schema-generator](https://github.com/satohshi/pocketbase-schema-generator) as a PocketBase hook to auto-generate types on schema changes.
 
 ```typescript
-import type { SchemaDeclaration } from 'pocketbase-tanstack-db';
+// schema.ts - Auto-generated from PocketBase
+interface Post {
+    id: string;
+    title: string;
+    content: string;
+    author: string;      // FK to users
+    published: boolean;
+    created: string;
+    updated: string;
+}
 
-// Define your record types
-interface Author {
+interface User {
     id: string;
-    name: string;
+    username: string;
     email: string;
+    avatar?: string;
     created: string;
     updated: string;
 }
 
-interface Book {
+interface Comment {
     id: string;
-    title: string;
-    author: string; // FK to authors
-    genre: 'Fiction' | 'Non-Fiction' | 'Science Fiction';
-    published_date: string;
+    post: string;        // FK to posts
+    author: string;      // FK to users
+    text: string;
     created: string;
     updated: string;
 }
 
-// Create schema declaration
-interface MySchema extends SchemaDeclaration {
-    authors: {
-        Row: Author;
-        Relations: {
-            forward: {};
-            back: {
-                books: ['books', true]; // One-to-many relation
-            };
-        };
+// Schema declaration for pbtsdb
+type BlogSchema = {
+    posts: {
+        type: Post;
+        relations: { author?: User };
+    };
+    users: {
+        type: User;
+        relations: {};
     };
-    books: {
-        Row: Book;
-        Relations: {
-            forward: {
-                author: ['authors', false]; // Many-to-one relation
-            };
-            back: {};
+    comments: {
+        type: Comment;
+        relations: {
+            post?: Post;
+            author?: User;
         };
     };
 }
 ```
 
-### 2. Initialize PocketBase and Collections
+### 2. Set Up Your App
 
 ```typescript
+// app.tsx
 import PocketBase from 'pocketbase';
-import { QueryClient } from '@tanstack/react-query';
-import { CollectionFactory } from 'pocketbase-tanstack-db';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { createCollection, createReactProvider } from 'pbtsdb';
 
-// Initialize PocketBase
 const pb = new PocketBase('http://localhost:8090');
-
-// Initialize QueryClient
 const queryClient = new QueryClient({
     defaultOptions: {
-        queries: {
-            staleTime: 1000 * 60, // 1 minute
-        },
-    },
+        queries: { staleTime: 60_000 } // Cache for 1 minute
+    }
 });
 
-// Create collection factory
-const factory = new CollectionFactory<MySchema>(pb, queryClient);
+// Create collections with automatic type inference
+const c = createCollection<BlogSchema>(pb, queryClient);
+export const { Provider, useStore } = createReactProvider({
+    posts: c('posts', {
+        omitOnInsert: ['created', 'updated'] as const
+    }),
+    users: c('users', {}),
+    comments: c('comments', {
+        omitOnInsert: ['created', 'updated'] as const
+    })
+});
 
-// Create collections
-const authorsCollection = factory.create('authors');
-const booksCollection = factory.create('books');
+export function App() {
+    return (
+        <QueryClientProvider client={queryClient}>
+            <Provider>
+                <BlogDashboard />
+            </Provider>
+        </QueryClientProvider>
+    );
+}
 ```
 
-### 3. Use in React Components
+### 3. Build Your Components
 
 ```typescript
+// BlogDashboard.tsx
 import { useLiveQuery } from '@tanstack/react-db';
+import { useStore } from './app';
 
-function BooksList() {
-    const { data: books, isLoading } = useLiveQuery((q) =>
-        q.from({ books: booksCollection })
+export function BlogDashboard() {
+    const [posts] = useStore('posts');
+
+    const { data: allPosts, isLoading } = useLiveQuery((q) =>
+        q.from({ posts })
+            .orderBy(({ posts }) => posts.created, 'desc')
     );
 
-    if (isLoading) return <div>Loading...</div>;
+    if (isLoading) return <div>Loading posts...</div>;
 
     return (
-        <ul>
-            {books?.map(book => (
-                <li key={book.id}>{book.title}</li>
+        <div>
+            <h1>Blog Posts</h1>
+            {allPosts?.map(post => (
+                <article key={post.id}>
+                    <h2>{post.title}</h2>
+                    <p>{post.content}</p>
+                    {/* Expanded author is fully typed! */}
+                    <small>By {post.expand?.author?.username}</small>
+                </article>
             ))}
-        </ul>
+        </div>
     );
 }
 ```
 
+### 4. Add Real-time Comments
+
+```typescript
+// PostWithComments.tsx
+import { useLiveQuery } from '@tanstack/react-db';
+import { eq } from '@tanstack/db';
+import { useStore } from './app';
+import { newRecordId } from 'pbtsdb';
+
+export function PostWithComments({ postId }: { postId: string }) {
+    const [comments, posts] = useStore('comments', 'posts');
+
+    // 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')
+    );
+
+    const handleAddComment = (text: string, authorId: string) => {
+        comments.insert({
+            id: newRecordId(),
+            post: postId,
+            author: authorId,
+            text
+        });
+        // Comment appears instantly (optimistic), syncs to PocketBase in background
+    };
+
+    return (
+        <div>
+            <h3>Comments ({postComments?.length || 0})</h3>
+            {postComments?.map(comment => (
+                <div key={comment.id}>
+                    <strong>{comment.expand?.author?.username}:</strong>
+                    <p>{comment.text}</p>
+                </div>
+            ))}
+            <CommentForm onSubmit={handleAddComment} />
+        </div>
+    );
+}
+```
+
+**That's it!** You now have a real-time blog with:
+- ✅ Type-safe queries
+- ✅ Automatic real-time updates
+- ✅ Optimistic mutations
+- ✅ Expanded relations
+
 ## Core Concepts
 
 ### Collections
@@ -151,8 +233,9 @@ function BooksList() {
 Collections are reactive data stores that automatically sync with PocketBase:
 
 ```typescript
-// Create a collection
-const booksCollection = factory.create('books');
+// Create a collection using the curried API
+const c = createCollection<MySchema>(pb, queryClient);
+const booksCollection = c('books', {});
 
 // Collections automatically:
 // - Fetch data from PocketBase
@@ -167,22 +250,23 @@ Collections manage subscriptions **automatically** based on query lifecycle:
 
 ```typescript
 // Collections are lazy - no subscription until queried
-const booksCollection = factory.create('books');
+const c = createCollection<MySchema>(pb, queryClient);
+const booksCollection = c('books', {});
 
 // Subscription starts automatically when query becomes active
 const { data } = useLiveQuery((q) =>
     q.from({ books: booksCollection })
 );
 // ✅ Subscribed to changes while component is mounted
-// ✅ Unsubscribes automatically when component unmounts (with 5s cleanup delay)
-
-// Advanced: Manual subscription control
-await booksCollection.subscribe(); // Subscribe to all
-await booksCollection.subscribe('record_id'); // Subscribe to specific record
-booksCollection.unsubscribe('record_id'); // Unsubscribe from specific record
-booksCollection.unsubscribeAll(); // Clear all subscriptions
+// ✅ Unsubscribes automatically when component unmounts
 ```
 
+**Subscription Lifecycle:**
+- **Lazy:** No subscription starts until the first `useLiveQuery` using the collection renders
+- **Automatic:** Subscription starts when first subscriber mounts, stops when last subscriber unmounts
+- **Shared:** Multiple components using the same collection share one subscription
+- **No manual control needed:** The collection handles all subscription management internally
+
 ### Type Safety
 
 Full TypeScript support with compile-time type checking:
@@ -200,138 +284,137 @@ const { data } = useLiveQuery((q) =>
 
 ## API Reference
 
-### CollectionFactory
+### createCollection()
 
-The main class for creating type-safe collections.
-
-#### Constructor
+The main function for creating type-safe collections. Uses a curried API for better type inference.
 
 ```typescript
-new CollectionFactory<Schema>(pocketbase: PocketBase, queryClient: QueryClient)
+const c = createCollection<Schema>(pb: PocketBase, queryClient: QueryClient);
+const collection = c(collectionName: string, options?: CreateCollectionOptions);
 ```
 
 **Parameters:**
-- `pocketbase`: PocketBase instance
-- `queryClient`: TanStack Query QueryClient instance
-
-**Example:**
-```typescript
-const factory = new CollectionFactory<MySchema>(pb, queryClient);
-```
-
-#### create()
-
-Creates a reactive collection from a PocketBase collection.
-
-```typescript
-create<CollectionName>(
-    collection: CollectionName,
-    options?: CreateCollectionOptions
-): Collection & SubscribableCollection
-```
+- `pb` - PocketBase instance
+- `queryClient` - TanStack Query QueryClient instance
+- `collectionName` - Name of the PocketBase collection
+- `options` - Optional configuration
 
 **Options:**
-- `expand?: string` - Relations to expand (e.g., `'author,metadata'`)
-- `relations?: Record<string, Collection>` - Collections for manual joins
+- `expand?: Record<string, Collection>` - Relations to auto-expand and auto-upsert on every fetch
+- `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
+
+**Returns:** Fully-typed Collection instance with subscription capabilities
 
 **Examples:**
 
 Basic collection (lazy, subscribes automatically on first query):
 ```typescript
-const booksCollection = factory.create('books');
+const c = createCollection<MySchema>(pb, queryClient);
+const booksCollection = c('books', {});
 ```
 
-With expand:
+With auto-expand relations:
 ```typescript
-const booksCollection = factory.create('books', {
-    expand: 'author' as const // Type-safe expand
+const c = createCollection<MySchema>(pb, queryClient);
+const authorsCollection = c('authors', {});
+const booksCollection = c('books', {
+    expand: {
+        author: authorsCollection  // Auto-expand and auto-upsert
+    }
 });
 
-// Expanded relations available
+// Expand is automatic on every fetch
 const { data } = useLiveQuery((q) => q.from({ books: booksCollection }));
-data[0].expand?.author // ✅ Typed!
-```
 
-With relations for joins:
-```typescript
-const authorsCollection = factory.create('authors');
-const booksCollection = factory.create('books', {
-    relations: {
-        author: authorsCollection
-    }
-});
+// Expanded records auto-inserted into authorsCollection
 ```
 
-### React Provider
+### React Integration
 
-Provide collections to your React component tree.
+#### createReactProvider()
 
-#### CollectionsProvider
+Creates a React Provider and useStore hook from a collections map.
 
 ```typescript
-<CollectionsProvider collections={collectionsMap}>
-    {children}
-</CollectionsProvider>
+const { Provider, useStore } = createReactProvider(collections: CollectionsMap);
 ```
 
+**Parameters:**
+- `collections` - Object mapping keys to Collection instances
+
+**Returns:**
+- `Provider` - React Context Provider component
+- `useStore` - Hook to access collections (variadic args, returns typed tuple)
+
 **Example:**
 ```typescript
-import { CollectionsProvider } from 'pocketbase-tanstack-db';
+import { createCollection, createReactProvider } from 'pbtsdb';
 
+const c = createCollection<MySchema>(pb, queryClient);
 const collections = {
-    authors: factory.create('authors'),
-    books: factory.create('books'),
+    authors: c('authors', {}),
+    books: c('books', {
+        omitOnInsert: ['created', 'updated'] as const
+    }),
 };
 
-function App() {
-    return (
-        <CollectionsProvider collections={collections}>
-            <BooksList />
-        </CollectionsProvider>
-    );
-}
+const { Provider, useStore } = createReactProvider(collections);
+
+// Wrap your app
+<Provider>
+    <App />
+</Provider>
+```
+
+**With custom collection key:**
+```typescript
+const collections = {
+    myBooks: c('books', {})  // Key 'myBooks', PocketBase collection 'books'
+};
+
+const { Provider, useStore } = createReactProvider(collections);
+
+// Access via custom key
+const [myBooks] = useStore('myBooks');
 ```
 
 #### useStore()
 
-Access a single collection from the provider.
+Access collections from the provider. Uses variadic arguments and returns a typed tuple.
 
+**Single collection:**
 ```typescript
-const collection = useStore<RecordType>(key: string)
+const [collection] = useStore('key')
 ```
 
-**Example:**
+**Multiple collections:**
+```typescript
+const [col1, col2, col3] = useStore('key1', 'key2', 'key3')
+```
+
+**Examples:**
 ```typescript
 function BooksList() {
-    const booksCollection = useStore<Book>('books');
+    const [books] = useStore('books');  // ✅ Typed automatically!
 
     const { data } = useLiveQuery((q) =>
-        q.from({ books: booksCollection })
+        q.from({ books })
     );
 
     return <div>{/* ... */}</div>;
 }
-```
-
-#### useStores()
 
-Access multiple collections at once.
-
-```typescript
-const [col1, col2] = useStores<[Type1, Type2]>(keys: string[])
-```
-
-**Example:**
-```typescript
 function BooksWithAuthors() {
-    const [booksCollection, authorsCollection] = useStores<[Book, Author]>(
-        ['books', 'authors']
-    );
+    const [books, authors] = useStore('books', 'authors');  // ✅ Variadic!
 
     const { data } = useLiveQuery((q) =>
-        q.from({ book: booksCollection })
+        q.from({ book: books })
             .join(
-                { author: authorsCollection },
+                { author: authors },
                 ({ book, author }) => eq(book.author, author.id),
                 'left'
             )
@@ -343,50 +426,26 @@ function BooksWithAuthors() {
 
 ### Subscriptions
 
-Collections support real-time subscriptions to PocketBase.
-
-#### subscribe()
-
-Subscribe to collection changes.
-
-```typescript
-// Subscribe to all records
-await collection.subscribe();
-
-// Subscribe to specific record
-await collection.subscribe('record_id');
-```
-
-#### unsubscribe()
-
-Unsubscribe from changes.
-
-```typescript
-// Unsubscribe from all
-collection.unsubscribe();
-
-// Unsubscribe from specific record
-collection.unsubscribe('record_id');
-```
+Collections manage real-time subscriptions to PocketBase **automatically**. No manual subscription management is needed for normal usage.
 
-#### unsubscribeAll()
-
-Clear all subscriptions for a collection.
+#### Automatic Subscription Lifecycle
 
 ```typescript
-collection.unsubscribeAll();
+// Subscriptions start automatically when useLiveQuery renders
+function MyComponent() {
+    const [books] = useStore('books');
+    const { data } = useLiveQuery((q) => q.from({ books }));
+    // ✅ Subscription active while this component is mounted
+    // ✅ Automatically stops when component unmounts
+}
 ```
 
 #### isSubscribed()
 
-Check subscription status.
+Check if a collection has an active subscription.
 
 ```typescript
-// Check collection-wide subscription
 const isSubbed = collection.isSubscribed(); // boolean
-
-// Check specific record subscription
-const isRecordSubbed = collection.isSubscribed('record_id'); // boolean
 ```
 
 #### waitForSubscription()
@@ -394,519 +453,432 @@ const isRecordSubbed = collection.isSubscribed('record_id'); // boolean
 Wait for subscription to be established (useful in tests).
 
 ```typescript
-await collection.waitForSubscription(); // Wait for collection-wide
-await collection.waitForSubscription('record_id'); // Wait for specific record
-await collection.waitForSubscription(undefined, 5000); // With timeout
+await collection.waitForSubscription(); // Wait with default 5s timeout
+await collection.waitForSubscription(10000); // Wait with custom timeout (ms)
 ```
 
-## Usage Examples
-
-### Basic Queries
-
-#### Fetch All Records
-
-```typescript
-const { data: books, isLoading, error } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-);
-
-if (isLoading) return <div>Loading...</div>;
-if (error) return <div>Error: {error.message}</div>;
+### Utility Functions
 
-return (
-    <ul>
-        {books?.map(book => (
-            <li key={book.id}>{book.title}</li>
-        ))}
-    </ul>
-);
-```
+#### newRecordId()
 
-#### Fetch Single Record
+Generate a PocketBase-compatible record ID (15-character alphanumeric string).
 
 ```typescript
-import { eq } from '@tanstack/db';
+import { newRecordId } from 'pbtsdb';
 
-const bookId = 'abc123';
+const id = newRecordId(); // "a1b2c3d4e5f6g7h"
 
-const { data: books } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-        .where(({ books }) => eq(books.id, bookId))
-);
+// Use when creating records
+const newBook = {
+    id: newRecordId(),
+    title: 'New Book',
+    // ... other fields
+};
 
-const book = books?.[0];
+booksCollection.insert(newBook);
 ```
 
-### Filtering and Sorting
+**Returns:** `string` - 15-character lowercase alphanumeric ID
+
+## Usage Examples
 
-#### Basic Filtering
+### Example 1: Task Manager with Filtering
 
 ```typescript
-import { eq, gt, and, or } from '@tanstack/db';
+// TaskBoard.tsx
+import { useLiveQuery } from '@tanstack/react-db';
+import { eq, and } from '@tanstack/db';
+import { useStore } from './app';
 
-// Filter by genre
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-        .where(({ books }) => eq(books.genre, 'Fiction'))
-);
+export function TaskBoard({ userId }: { userId: string }) {
+    const [tasks] = useStore('tasks');
 
-// Filter by date
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-        .where(({ books }) =>
-            gt(books.published_date, '2020-01-01')
-        )
-);
+    // Filter tasks by assignee and status - updates in real-time
+    const { data: myTasks } = useLiveQuery((q) =>
+        q.from({ tasks })
+            .where(({ tasks }) => and(eq(tasks.assignee, userId), eq(tasks.status, 'in_progress')))
+            .orderBy(({ tasks }) => tasks.due_date, 'asc')
+    );
 
-// Multiple conditions with AND
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-        .where(({ books }) => and(
-            eq(books.genre, 'Fiction'),
-            gt(books.published_date, '2020-01-01')
-        ))
-);
+    const handleComplete = (taskId: string) => {
+        tasks.update(taskId, (draft) => { draft.status = 'done'; });
+    };
 
-// Multiple conditions with OR
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-        .where(({ books }) => or(
-            eq(books.genre, 'Fiction'),
-            eq(books.genre, 'Science Fiction')
-        ))
-);
+    return (
+        <div>
+            <h2>My Tasks ({myTasks?.length || 0})</h2>
+            {myTasks?.map(task => (
+                <div key={task.id}>
+                    {task.title}
+                    <button onClick={() => handleComplete(task.id)}>Complete</button>
+                </div>
+            ))}
+        </div>
+    );
+}
 ```
 
-#### Advanced Filtering
+### Example 2: E-commerce Product Catalog with Filtering
 
 ```typescript
-import { gte, lte, and } from '@tanstack/db';
+// ProductCatalog.tsx
+import { useLiveQuery } from '@tanstack/react-db';
+import { and, gte, lte } from '@tanstack/db';
+import { useStore } from './app';
+
+export function ProductCatalog() {
+    const [products] = useStore('products');
+    const [category, setCategory] = useState<string | null>(null);
+    const [maxPrice, setMaxPrice] = useState(1000);
+
+    // Dynamic filtering - updates reactively
+    const { data: filteredProducts } = useLiveQuery((q) => {
+        let query = q.from({ products })
+            .where(({ products }) => and(
+                products.in_stock === true,
+                lte(products.price, maxPrice)
+            ));
+
+        if (category) {
+            query = query.where(({ products }) => products.category === category);
+        }
 
-// Complex nested queries
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-        .where(({ books }) => and(
-            eq(books.genre, 'Fiction'),
-            or(
-                gte(books.published_date, '2020-01-01'),
-                lte(books.published_date, '2010-12-31')
-            )
-        ))
-);
+        return query.orderBy(({ products }) => products.rating, 'desc');
+    });
+
+    return (
+        <div>
+            <select onChange={(e) => setCategory(e.target.value || null)}>
+                <option value="">All Categories</option>
+                <option value="electronics">Electronics</option>
+            </select>
+            <input type="range" max="1000" value={maxPrice}
+                onChange={(e) => setMaxPrice(+e.target.value)} />
+
+            {filteredProducts?.map(product => (
+                <ProductCard key={product.id} product={product} />
+            ))}
+        </div>
+    );
+}
 ```
 
-#### Sorting
+### Example 3: Social Media Feed with Likes
 
 ```typescript
-// Sort descending
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-        .orderBy(({ books }) => books.published_date, 'desc')
-);
-
-// Sort ascending
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-        .orderBy(({ books }) => books.title, 'asc')
-);
-
-// Multiple sorts
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-        .orderBy(({ books }) => books.genre, 'asc')
-        .orderBy(({ books }) => books.published_date, 'desc')
-);
-```
+// SocialFeed.tsx
+import { useLiveQuery } from '@tanstack/react-db';
+import { eq } from '@tanstack/db';
+import { useStore } from './app';
+import { newRecordId } from 'pbtsdb';
 
-### Relations and Joins
+export function SocialFeed({ currentUserId }: { currentUserId: string }) {
+    const [posts, likes] = useStore('posts', 'likes');
 
-#### Type-Safe Expand (Recommended)
+    const { data: feedPosts } = useLiveQuery((q) =>
+        q.from({ posts }).orderBy(({ posts }) => posts.created, 'desc')
+    );
 
-Use PocketBase's built-in expand for fast, server-side joins:
+    const { data: userLikes } = useLiveQuery((q) =>
+        q.from({ likes }).where(({ likes }) => eq(likes.user, currentUserId))
+    );
 
-```typescript
-// Create collection with expand
-const booksCollection = factory.create('books', {
-    expand: 'author' as const // ← Type-safe!
-});
+    const likedPostIds = new Set(userLikes?.map(l => l.post) || []);
 
-// Use in query
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-);
+    const handleLike = (postId: string) => {
+        if (likedPostIds.has(postId)) {
+            const like = userLikes?.find(l => l.post === postId);
+            if (like) likes.delete(like.id);
+        } else {
+            likes.insert({ id: newRecordId(), post: postId, user: currentUserId });
+        }
+    };
 
-// Access expanded relations (fully typed!)
-data?.forEach(book => {
-    if (book.expand?.author) {
-        console.log(book.expand.author.name); // ✅ Type-safe
-    }
-});
+    return (
+        <div>
+            {feedPosts?.map(post => (
+                <div key={post.id}>
+                    <strong>{post.expand?.author?.username}</strong>
+                    <p>{post.content}</p>
+                    <button onClick={() => handleLike(post.id)}>
+                        {likedPostIds.has(post.id) ? '❤️' : '🤍'} {post.likes_count}
+                    </button>
+                </div>
+            ))}
+        </div>
+    );
+}
 ```
 
-#### Multiple Expands
+### Example 4: Real-time Collaborative Todo List
 
 ```typescript
-const booksCollection = factory.create('books', {
-    expand: 'author,metadata' as const
-});
-
-// Both relations expanded
-data[0].expand?.author   // ✅ Author type
-data[0].expand?.metadata // ✅ Metadata type
-```
-
-#### TanStack DB Joins
-
-For complex client-side joins:
+// CollaborativeTodoList.tsx
+import { useLiveQuery } from '@tanstack/react-db';
+import { eq } from '@tanstack/db';
+import { useStore } from './app';
+import { newRecordId } from 'pbtsdb';
+
+export function CollaborativeTodoList({ listId, userId }: { listId: string; userId: string }) {
+    const [todos] = useStore('todos');
+    const [newText, setNewText] = useState('');
+
+    // Real-time todos - updates when any user adds/edits
+    const { data: allTodos } = useLiveQuery((q) =>
+        q.from({ todos })
+            .where(({ todos }) => eq(todos.list_id, listId))
+            .orderBy(({ todos }) => todos.created, 'asc')
+    );
 
-```typescript
-const authorsCollection = factory.create('authors');
-const booksCollection = factory.create('books', {
-    relations: {
-        author: authorsCollection
-    }
-});
+    const handleAdd = () => {
+        if (!newText.trim()) return;
+        todos.insert({ id: newRecordId(), text: newText, completed: false, list_id: listId, created_by: userId });
+        setNewText('');
+    };
 
-// Manual join with full type safety
-const { data } = useLiveQuery((q) =>
-    q.from({ book: booksCollection })
-        .join(
-            { author: authorsCollection },
-            ({ book, author }) => eq(book.author, author.id),
-            'left' // Join type: 'left' | 'right' | 'inner' | 'full'
-        )
-        .select(({ book, author }) => ({
-            ...book,
-            expand: {
-                author: author ? { ...author } : undefined
-            }
-        }))
-);
+    return (
+        <div>
+            <input value={newText} onChange={(e) => setNewText(e.target.value)}
+                onKeyPress={(e) => e.key === 'Enter' && handleAdd()} />
+            <ul>
+                {allTodos?.map(todo => (
+                    <li key={todo.id}>
+                        <input type="checkbox" checked={todo.completed}
+                            onChange={() => todos.update(todo.id, d => { d.completed = !d.completed; })} />
+                        {todo.text}
+                        <button onClick={() => todos.delete(todo.id)}>×</button>
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+}
 ```
 
-#### Inner Join (Filter Out Missing Relations)
+Real-time collaboration works automatically - when User A adds/edits a todo, User B sees it instantly.
 
-```typescript
-const { data } = useLiveQuery((q) =>
-    q.from({ book: booksCollection })
-        .join(
-            { author: authorsCollection },
-            ({ book, author }) => eq(book.author, author.id),
-            'inner' // Only books WITH authors
-        )
-);
-```
-
-#### Complex Multi-Collection Joins
+### Example 5: Form with Optimistic Updates and Error Handling
 
 ```typescript
-const authorsCollection = factory.create('authors');
-const booksCollection = factory.create('books');
-const metadataCollection = factory.create('book_metadata');
+// CreateBookForm.tsx
+import { useStore } from './app';
+import { newRecordId } from 'pbtsdb';
 
-const { data } = useLiveQuery((q) =>
-    q.from({ book: booksCollection })
-        .join(
-            { author: authorsCollection },
-            ({ book, author }) => eq(book.author, author.id),
-            'left'
-        )
-        .join(
-            { metadata: metadataCollection },
-            ({ book, metadata }) => eq(book.id, metadata.book),
-            'left'
-        )
-        .select(({ book, author, metadata }) => ({
-            ...book,
-            expand: {
-                author: author ? { ...author } : undefined,
-                metadata: metadata ? { ...metadata } : undefined
-            }
-        }))
-);
-```
+export function CreateBookForm() {
+    const [books] = useStore('books');
+    const [title, setTitle] = useState('');
+    const [error, setError] = useState<string | null>(null);
 
-### Real-time Updates
+    const handleSubmit = async (e: React.FormEvent) => {
+        e.preventDefault();
+        setError(null);
 
-#### Automatic Updates
+        try {
+            // Optimistic insert - appears instantly
+            const tx = books.insert({ id: newRecordId(), title, author: 'author_id' });
+            await tx.isPersisted.promise;
 
-Collections automatically receive real-time updates based on query lifecycle:
+            if (tx.state === 'completed') setTitle('');
+            else setError('Failed to create book');
+        } catch (err: any) {
+            setError(err.data ? Object.values(err.data).join(', ') : err.message);
+        }
+    };
 
-```typescript
-function BooksList() {
-    const { data } = useLiveQuery((q) =>
-        q.from({ books: booksCollection })
+    return (
+        <form onSubmit={handleSubmit}>
+            {error && <div className="error">{error}</div>}
+            <input value={title} onChange={(e) => setTitle(e.target.value)} required />
+            <button type="submit">Add Book</button>
+        </form>
     );
-
-    // Subscription automatically starts when component mounts
-    // Component re-renders automatically when:
-    // - A book is created
-    // - A book is updated
-    // - A book is deleted
-    // Subscription automatically stops when component unmounts (with 5s delay)
-
-    return <ul>{/* ... */}</ul>;
 }
 ```
 
-**Subscription Lifecycle:**
-- ✅ Collections are lazy - no network activity on creation
-- ✅ Subscription starts when first `useLiveQuery` becomes active
-- ✅ Multiple queries share a single subscription per collection
-- ✅ Subscription stops 5 seconds after last query unmounts
-- ✅ Prevents thrashing during rapid mount/unmount cycles
-
-#### Manual Subscription Control (Advanced)
+Optimistic updates show changes instantly; automatic rollback on server errors.
 
-For advanced use cases, you can manually control subscriptions:
+### Example 6: Dashboard with Multiple Collections and Joins
 
 ```typescript
-const booksCollection = factory.create('books');
+// ProjectDashboard.tsx
+import { useLiveQuery } from '@tanstack/react-db';
+import { eq } from '@tanstack/db';
+import { useStore } from './app';
 
-// Manually subscribe (bypasses automatic lifecycle)
-await booksCollection.subscribe();
+export function ProjectDashboard({ projectId }: { projectId: string }) {
+    const [projects, tasks, teamMembers, users] = useStore('projects', 'tasks', 'team_members', 'users');
 
-// Subscribe to specific record
-await booksCollection.subscribe('record_id');
+    const { data: projectList } = useLiveQuery((q) =>
+        q.from({ projects }).where(({ projects }) => eq(projects.id, projectId))
+    );
 
-// Unsubscribe when done
-booksCollection.unsubscribe('record_id');
-booksCollection.unsubscribeAll();
-```
+    const { data: projectTasks } = useLiveQuery((q) =>
+        q.from({ tasks }).where(({ tasks }) => eq(tasks.project, projectId))
+    );
 
-#### Subscribing to Specific Records
+    // Join team members with users
+    const { data: team } = useLiveQuery((q) =>
+        q.from({ member: teamMembers })
+            .where(({ member }) => eq(member.project, projectId))
+            .join({ user: users }, ({ member, user }) => eq(member.user, user.id), 'left')
+            .select(({ member, user }) => ({ id: member.id, role: member.role, name: user?.name }))
+    );
 
-```typescript
-// Subscribe to a specific book
-await booksCollection.subscribe('book_id_123');
+    const completed = projectTasks?.filter(t => t.completed).length || 0;
+    const total = projectTasks?.length || 0;
 
-// Check if subscribed
-if (booksCollection.isSubscribed('book_id_123')) {
-    console.log('Subscribed to book_id_123');
+    return (
+        <div>
+            <h1>{projectList?.[0]?.name}</h1>
+            <p>Progress: {completed}/{total} tasks</p>
+            <p>Team: {team?.map(m => m.name).join(', ')}</p>
+        </div>
+    );
 }
-
-// Unsubscribe from specific record
-booksCollection.unsubscribe('book_id_123');
 ```
 
-#### Waiting for Subscription (Testing)
-
-```typescript
-// Useful in tests
-await booksCollection.waitForSubscription();
-
-// Now safe to create/update records and expect real-time updates
-const newBook = await pb.collection('books').create({ /* ... */ });
-
-// Wait for update to propagate
-await waitFor(() => {
-    expect(data?.some(b => b.id === newBook.id)).toBe(true);
-});
-```
+Demonstrates variadic `useStore()`, client-side aggregations, and TanStack DB joins.
 
 ## TypeScript
 
-### Schema Declaration
+pbtsdb is fully type-safe. Here's what you need to know:
 
-Define your schema with full type safety:
+### Define Your Schema
 
-```typescript
-import type { SchemaDeclaration } from 'pocketbase-tanstack-db';
+Use the simple schema format shown in the Quick Start:
 
-interface MySchema extends SchemaDeclaration {
+```typescript
+type MySchema = {
     collection_name: {
-        Row: RecordType;      // Your record type
-        Relations: {
-            forward: {
-                // Forward relations (FK fields)
-                field_name: [
-                    'target_collection',
-                    is_array // false for single, true for array
-                ];
-            };
-            back: {
-                // Back relations (reverse lookups)
-                relation_name: ['source_collection', is_array];
-            };
+        type: RecordInterface;    // Your record type
+        relations: {
+            field_name: RelatedType;  // Related record types
         };
     };
 }
 ```
 
-### Example: Blog Schema
-
-```typescript
-interface Post {
-    id: string;
-    title: string;
-    content: string;
-    author: string; // FK to users
-    tags: string[]; // FK array to tags
-    created: string;
-    updated: string;
-}
-
-interface User {
-    id: string;
-    username: string;
-    email: string;
-    created: string;
-    updated: string;
-}
-
-interface Tag {
-    id: string;
-    name: string;
-    created: string;
-    updated: string;
-}
-
-interface BlogSchema extends SchemaDeclaration {
-    posts: {
-        Row: Post;
-        Relations: {
-            forward: {
-                author: ['users', false];  // Single relation
-                tags: ['tags', true];      // Array relation
-            };
-            back: {};
-        };
-    };
-    users: {
-        Row: User;
-        Relations: {
-            forward: {};
-            back: {
-                posts: ['posts', true];    // One user, many posts
-            };
-        };
-    };
-    tags: {
-        Row: Tag;
-        Relations: {
-            forward: {};
-            back: {
-                posts: ['posts', true];    // One tag, many posts
-            };
-        };
-    };
-}
-```
+**Pro tip:** Use [pocketbase-schema-generator](https://github.com/satohshi/pocketbase-schema-generator) to auto-generate types from your PocketBase database.
 
-### Type-Safe Expand
+### Type-Safe Collections
 
-Use `as const` for type-safe expand strings:
+Always create collections with proper type parameters:
 
 ```typescript
-const postsCollection = factory.create('posts', {
-    expand: 'author,tags' as const
-    // ✅ TypeScript validates these are real relations
+// ✅ Good - full type safety
+const c = createCollection<MySchema>(pb, queryClient);
+const books = c('books', {
+    omitOnInsert: ['created', 'updated'] as const
 });
 
-// Expanded fields are typed
-data[0].expand?.author.username  // ✅ string
-data[0].expand?.tags[0].name     // ✅ string
+// ✅ Good - with auto-expand relations
+const authors = c('authors', {});
+const books = c('books', {
+    expand: {
+        author: authors
+    }
+});
 ```
 
 ## Best Practices
 
-### 1. Choose the Right Approach for Relations
-
-**Use Type-Safe Expand when:**
-- You need fast, single-query performance
-- Relations are straightforward
+### 1. Define Collections Centrally
 
+Define all collections once at app initialization:
 
 ```typescript
-// ✅ Fast, simple, type-safe
-const books = factory.create('books', {
-    expand: 'author' as const
+// ✅ Do this - centralized, type-safe
+const c = createCollection<MySchema>(pb, queryClient);
+
+export const { Provider, useStore } = createReactProvider({
+    posts: c('posts', { omitOnInsert: ['created', 'updated'] as const }),
+    users: c('users', {}),
+    comments: c('comments', { omitOnInsert: ['created', 'updated'] as const })
 });
 ```
 
-**Use TanStack Joins when:**
-- You need inner/right/full joins
-- You want the related records to update in response to sync
-- Complex client-side filtering after joins
-- Building computed fields from multiple collections
+### 2. Create Dependencies Before Dependents
 
+When using expand collections, create the target collection first:
 
 ```typescript
-// ✅ Flexible, powerful, type-safe
-const { data } = useLiveQuery((q) =>
-    q.from({ book: booksCollection })
-        .join({ author: authorsCollection }, ..., 'inner')
-);
-```
-
-### 2. Use Provider for App-Wide Collections
-
-```typescript
-// ✅ Define collections once
-const collections = {
-    books: factory.create('books'),
-    authors: factory.create('authors'),
-};
+// ✅ 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
+    }
+});
 
-// Use throughout app
-<CollectionsProvider collections={collections}>
-    <App />
-</CollectionsProvider>
+// ❌ Bad - can't reference what doesn't exist yet
+const books = c('books', {
+    expand: {
+        author: ???  // Where is authors?
+    }
+});
 ```
 
-### 3. Type Your Hooks
+### 3. Subscriptions are Automatic
+
+Don't manually subscribe - just use `useLiveQuery`:
 
 ```typescript
-// ✅ Explicit typing
-const booksCollection = useStore<Book>('books');
+// ✅ Do this
+const { data } = useLiveQuery((q) => q.from({ posts }));
 
-// ✅ Tuple typing for multiple collections
-const [books, authors] = useStores<[Book, Author]>(['books', 'authors']);
+// ❌ Don't do this
+useEffect(() => {
+    posts.subscribe();
+    return () => posts.unsubscribe();
+}, []);
 ```
 
-### 4. Handle Loading and Error States
+### 4. Handle Loading States
+
+Always check loading and error states:
 
 ```typescript
-const { data, isLoading, error } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-);
+const { data, isLoading, error } = useLiveQuery((q) => q.from({ posts }));
 
-if (isLoading) return <Spinner />;
-if (error) return <ErrorMessage error={error} />;
-if (!data?.length) return <EmptyState />;
+if (isLoading) return <div>Loading...</div>;
+if (error) return <div>Error: {error.message}</div>;
+if (!data?.length) return <div>No posts found</div>;
 
-return <BooksList books={data} />;
+return <PostsList posts={data} />;
 ```
 
-### 5. Subscriptions are Automatic
+### 5. Use Expand for Performance
 
-No need to manually subscribe/unsubscribe - the library handles it:
+Use PocketBase's expand feature for better performance:
 
 ```typescript
-// ❌ Don't do this (unless you have advanced use case)
-useEffect(() => {
-    booksCollection.subscribe();
-    return () => booksCollection.unsubscribe();
-}, []);
+// ✅ 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
+    }
+});
 
-// ✅ Do this instead - automatic lifecycle management
-const { data } = useLiveQuery((q) =>
-    q.from({ books: booksCollection })
-);
+const { data } = useLiveQuery((q) => q.from({ posts }));
+
+// ⚠️ Slower - multiple queries + client-side join
+// Only use TanStack DB joins for inner/right/full join behavior
 ```
 
-### 6. Use QueryClient Configuration
+### 6. Configure QueryClient Defaults
 
 ```typescript
 const queryClient = new QueryClient({
     defaultOptions: {
         queries: {
-            staleTime: 1000 * 60 * 5, // 5 minutes
-            gcTime: 1000 * 60 * 10,   // 10 minutes
-            retry: 3,
-            refetchOnWindowFocus: false,
-        },
-    },
+            staleTime: 60_000,      // 1 minute
+            gcTime: 300_000,        // 5 minutes
+            refetchOnWindowFocus: false
+        }
+    }
 });
 ```
 
@@ -917,7 +889,7 @@ const queryClient = new QueryClient({
 By default, pbtsdb logs debug messages to the console in development mode. You can integrate with your own logging service (Sentry, LogRocket, etc.) using `setLogger`:
 
 ```typescript
-import { setLogger } from 'pocketbase-tanstack-db';
+import { setLogger } from 'pbtsdb';
 
 // Example: Send errors to Sentry
 setLogger({
@@ -946,7 +918,7 @@ setLogger({
 **Disable logging completely:**
 
 ```typescript
-import { setLogger } from 'pocketbase-tanstack-db';
+import { setLogger } from 'pbtsdb';
 
 setLogger({
     debug: () => {},
@@ -958,14 +930,14 @@ setLogger({
 **Reset to default logger:**
 
 ```typescript
-import { resetLogger } from 'pocketbase-tanstack-db';
+import { resetLogger } from 'pbtsdb';
 
 resetLogger();
 ```
 
 ## License
 
-ISC
+MIT
 
 ## Contributing
 
@@ -979,8 +951,8 @@ Contributions welcome! Please open an issue or PR.
 
 **Clone and Install:**
 ```bash
-git clone https://github.com/yourusername/pocketbase-tanstack-db
-cd pocketbase-tanstack-db
+git clone https://github.com/yourusername/pbtsdb
+cd pbtsdb
 npm install
 ```