tanstack-db-pglite 1.3.5 → 1.3.7

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,21 @@ 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 ({ write, markReady }) => {
+    const eventSource = new EventSource('/api/chats/sync')
+
+    eventSource.onmessage = (event) => {
+      const item = JSON.parse(event.data)
+      write(item)
+    }
+
+    eventSource.addEventListener('ready', () => markReady())
+
+    return () => {
+      eventSource.close()
+    }
   },
   onInsert: async (params) => {
     await saveInCloud(params)
@@ -59,3 +63,108 @@ 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 ({ write, markReady }) => {
+    const eventSource = new EventSource('/api/chats/sync')
+
+    eventSource.onmessage = (event) => {
+      const item = JSON.parse(event.data)
+      write(item)
+    }
+
+    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/package.json

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