tanstack-db-pglite 1.3.4 → 1.3.6

package/README.md

@@ -1,25 +1,34 @@
 # tanstack-db-pglite
 
-A seamless integration between [TanStack DB](https://tanstack.com/db) and [PGLite](https://github.com/electric-sql/pglite) with [Drizzle ORM](https://orm.drizzle.team/) for browser-based database management.
+A seamless integration between [TanStack DB](https://tanstack.com/db) and [PGLite](https://github.com/electric-sql/pglite) with optional [Drizzle ORM](https://orm.drizzle.team/) support for browser-based database management.
 
 ## Installation
 
 ```bash
-npm install tanstack-db-pglite @tanstack/db drizzle-orm @electric-sql/pglite
+npm install tanstack-db-pglite @tanstack/db @electric-sql/pglite
 ```
 
-> **Note:** `@tanstack/db` and `drizzle-orm` are peer dependencies and must be installed separately.
+> **Note:** `@tanstack/db` and `@electric-sql/pglite` are peer dependencies. `drizzle-orm` is an optional peer dependency required only when using `drizzleCollectionOptions`.
 
-## Quick Start
+## APIs
+
+This package exports two collection option creators:
+
+- `drizzleCollectionOptions` — uses Drizzle ORM on top of PGlite
+- `sqlCollectionOptions` — uses raw SQL queries directly on PGlite
+
+Both follow the TanStack DB [collection options creator](https://tanstack.com/db/latest/docs/guides/collection-options-creator) pattern.
+
+## Quick Start (Drizzle)
 
 ```typescript
-import { PGLite } from '@electric-sql/pglite'
+import { PGlite } from '@electric-sql/pglite'
 import { createCollection } from '@tanstack/react-db'
 import { drizzle } from 'drizzle-orm/pglite'
 import { drizzleCollectionOptions } from 'tanstack-db-pglite'
 import { chats } from '~/drizzle'
 
-const pglite = new PGLite()
+const pglite = new PGlite()
 const db = drizzle(pglite)
 
 export const chatsCollection = createCollection(drizzleCollectionOptions({
@@ -27,26 +36,23 @@ export const chatsCollection = createCollection(drizzleCollectionOptions({
   table: chats,
   primaryColumn: chats.id,
   prepare: async () => {
-    // Prepare your database before starting the collection (e.g., run migrations)
     await waitForMigrations()
   },
-  sync: async ({ collection, write }) => {
-    // Send some data to your backend to sync and receive the response
-    const sync = await syncWithCloud(
-      collection.toArray.map(c => ({
-        id: c.id,
-        updatedAt: c.updatedAt
-      }))
-    )
-
-    sync.forEach((item) => {
-      if (item.type === 'delete') {
-        write({ type: 'delete', value: collection.get(item.value)! })
-      }
-      else {
-        write(item)
-      }
-    })
+  sync: async ({ begin, commit, write, markReady }) => {
+    const eventSource = new EventSource('/api/chats/sync')
+
+    eventSource.onmessage = (event) => {
+      const item = JSON.parse(event.data)
+      begin()
+      write(item)
+      commit()
+    }
+
+    eventSource.addEventListener('ready', () => markReady())
+
+    return () => {
+      eventSource.close()
+    }
   },
   onInsert: async (params) => {
     await saveInCloud(params)
@@ -59,3 +65,110 @@ export const chatsCollection = createCollection(drizzleCollectionOptions({
   },
 }))
 ```
+
+## Quick Start (Raw SQL)
+
+```typescript
+import { PGlite } from '@electric-sql/pglite'
+import { createCollection } from '@tanstack/react-db'
+import { sqlCollectionOptions } from 'tanstack-db-pglite'
+import { z } from 'zod'
+
+const pglite = new PGlite()
+
+const chatSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  updatedAt: z.string(),
+})
+
+export const chatsCollection = createCollection(sqlCollectionOptions({
+  db: pglite,
+  tableName: 'chats',
+  primaryKeyColumn: 'id',
+  schema: chatSchema,
+  prepare: async () => {
+    await pglite.query(`
+      CREATE TABLE IF NOT EXISTS chats (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        "updatedAt" TEXT NOT NULL
+      )
+    `)
+  },
+  sync: async ({ begin, commit, write, markReady }) => {
+    const eventSource = new EventSource('/api/chats/sync')
+
+    eventSource.onmessage = (event) => {
+      const item = JSON.parse(event.data)
+      begin()
+      write(item)
+      commit()
+    }
+
+    eventSource.addEventListener('ready', () => markReady())
+
+    return () => {
+      eventSource.close()
+    }
+  },
+}))
+```
+
+## Options
+
+### Common Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `startSync` | `boolean` | Whether to run the `sync` callback automatically on startup. Defaults to `true`. When `false`, use `collection.utils.runSync()` to trigger manually. |
+| `prepare` | `() => Promise<unknown> \| unknown` | Runs before the initial data load (e.g., run migrations). |
+| `sync` | `(params) => Promise<(() => void) \| void>` | Sync callback receiving `write`, `markReady`, `collection`, and `metadata`. Return a cleanup function to close subscriptions. |
+| `rowUpdateMode` | `'partial' \| 'full'` | Whether sync updates contain partial changes or full row replacements. |
+| `onInsert` | `(params) => Promise<void>` | Called when a row is inserted optimistically. Persist to your backend here. |
+| `onUpdate` | `(params) => Promise<void>` | Called when a row is updated optimistically. Persist to your backend here. |
+| `onDelete` | `(params) => Promise<void>` | Called when a row is deleted optimistically. Persist to your backend here. |
+
+### `drizzleCollectionOptions` Specific
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `db` | `PgliteDatabase` | Drizzle PGlite database instance. |
+| `table` | `PgTable` | Drizzle table definition. |
+| `primaryColumn` | `IndexColumn` | The primary key column from the table. |
+
+### `sqlCollectionOptions` Specific
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `db` | `PGlite \| PGliteWorker` | PGlite instance (or worker). |
+| `tableName` | `string` | SQL table name. |
+| `primaryKeyColumn` | `string` | Name of the primary key column. |
+| `schema` | `StandardSchemaV1` | A Standard Schema (e.g., Zod) for the row type. |
+| `getKey` | `(row) => string` | Custom key extractor. Defaults to `row[primaryKeyColumn]`. |
+
+## Utilities
+
+Both adapters expose a `utils` object on the collection:
+
+```typescript
+// Manually trigger sync (cleans up any previous sync, then re-syncs)
+await chatsCollection.utils.runSync()
+```
+
+This is useful when `startSync: false` and you want to control when sync starts (e.g., after authentication).
+
+## Sync Callback
+
+The `sync` callback receives:
+
+- **`write(message)`** — writes a change to both PGlite and the TanStack DB collection. Accepts `{ type: 'insert', value }`, `{ type: 'update', value }`, or `{ type: 'delete', key }`.
+- **`markReady()`** — signals that the initial data is loaded and the collection is ready for queries. Must be called once.
+- **`collection`** — reference to the collection instance.
+- **`metadata`** — persisted sync metadata API for storing resume tokens, cursors, etc.
+
+Return a cleanup function to close long-lived connections (WebSocket, EventSource, etc.) when the collection is destroyed or `runSync()` is called again.
+
+## License
+
+MIT

package/dist/drizzle.d.ts

@@ -19,7 +19,7 @@ export declare function drizzleCollectionOptions<Table extends PgTable>({ startS
     table: Table;
     primaryColumn: IndexColumn;
     rowUpdateMode?: 'partial' | 'full';
-    sync?: (params: Pick<SyncParams<Table>, 'write' | 'collection' | 'markReady' | 'metadata'>) => Promise<(() => void) | void>;
+    sync?: (params: SyncParams<Table>) => Promise<(() => void) | void>;
     prepare?: () => Promise<unknown> | unknown;
     onInsert?: (params: InsertMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;
     onUpdate?: (params: UpdateMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;

package/dist/drizzle.js

@@ -12,6 +12,7 @@ import { createSelectSchema } from 'drizzle-zod';
 export function drizzleCollectionOptions({ startSync = true, ...config }) {
     // Sync params can be null while running PGLite migrations
     const { promise: syncParams, resolve: resolveSyncParams } = Promise.withResolvers();
+    let syncCleanup;
     // eslint-disable-next-line ts/no-explicit-any
     async function onDrizzleInsert(data, tx) {
         // @ts-expect-error drizzle types
@@ -88,12 +89,13 @@ export function drizzleCollectionOptions({ startSync = true, ...config }) {
                     const key = 'key' in message ? message.key : params.collection.getKeyFromItem(message.value);
                     await onDrizzleDelete([key]);
                 }
-                params.begin();
                 params.write(message);
-                params.commit();
             },
             collection: params.collection,
             markReady: params.markReady,
+            begin: params.begin,
+            commit: params.commit,
+            truncate: params.truncate,
             ...(params.metadata && { metadata: params.metadata }),
         });
     };
@@ -105,7 +107,6 @@ export function drizzleCollectionOptions({ startSync = true, ...config }) {
             ...(config.rowUpdateMode && { rowUpdateMode: config.rowUpdateMode }),
             sync: (params) => {
                 resolveSyncParams(params);
-                let cleanup;
                 (async () => {
                     await config.prepare?.();
                     // @ts-expect-error drizzle types
@@ -118,7 +119,7 @@ export function drizzleCollectionOptions({ startSync = true, ...config }) {
                     if (startSync) {
                         const result = await sync();
                         if (typeof result === 'function') {
-                            cleanup = result;
+                            syncCleanup = result;
                         }
                     }
                     else {
@@ -126,7 +127,8 @@ export function drizzleCollectionOptions({ startSync = true, ...config }) {
                     }
                 })();
                 return () => {
-                    cleanup?.();
+                    syncCleanup?.();
+                    syncCleanup = undefined;
                 };
             },
         },
@@ -167,9 +169,14 @@ export function drizzleCollectionOptions({ startSync = true, ...config }) {
                 if (!config.sync) {
                     throw new Error('Sync is not defined');
                 }
+                syncCleanup?.();
+                syncCleanup = undefined;
                 const params = await syncParams;
                 await params.collection.stateWhenReady();
-                await sync();
+                const result = await sync();
+                if (typeof result === 'function') {
+                    syncCleanup = result;
+                }
             },
         },
     };

package/dist/sql.js

@@ -12,6 +12,7 @@ function quoteId(name) {
  * until `markReady()` is called.
  */
 export function sqlCollectionOptions({ startSync = true, ...config }) {
+    let syncCleanup;
     const table = quoteId(config.tableName);
     const primaryKey = quoteId(config.primaryKeyColumn);
     const getKey = config.getKey ?? ((row) => String(row[config.primaryKeyColumn]));
@@ -92,7 +93,6 @@ export function sqlCollectionOptions({ startSync = true, ...config }) {
             ...(config.rowUpdateMode && { rowUpdateMode: config.rowUpdateMode }),
             sync: (params) => {
                 resolveSyncParams(params);
-                let cleanup;
                 (async () => {
                     await config.prepare?.();
                     const rows = await runSelect(config.db);
@@ -104,7 +104,7 @@ export function sqlCollectionOptions({ startSync = true, ...config }) {
                     if (startSync) {
                         const result = await sync();
                         if (typeof result === 'function') {
-                            cleanup = result;
+                            syncCleanup = result;
                         }
                     }
                     else {
@@ -112,7 +112,8 @@ export function sqlCollectionOptions({ startSync = true, ...config }) {
                     }
                 })();
                 return () => {
-                    cleanup?.();
+                    syncCleanup?.();
+                    syncCleanup = undefined;
                 };
             },
         },
@@ -152,7 +153,10 @@ export function sqlCollectionOptions({ startSync = true, ...config }) {
                 }
                 const params = await syncParams;
                 await params.collection.stateWhenReady();
-                await sync();
+                const result = await sync();
+                if (typeof result === 'function') {
+                    syncCleanup = result;
+                }
             },
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanstack-db-pglite",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "author": "Valerii Strilets",
   "license": "MIT",
   "repository": {