@tanstack/db 0.6.0 → 0.6.2

package/skills/db-core/persistence/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: db-core/persistence
+description: >
+  SQLite-backed persistence for TanStack DB collections. persistedCollectionOptions
+  wraps any adapter (Electric, Query, PowerSync, or local-only) with durable local
+  storage. Platform adapters: browser (WA-SQLite OPFS), React Native (op-sqlite),
+  Expo (expo-sqlite), Electron (IPC), Node (better-sqlite3), Capacitor, Tauri,
+  Cloudflare Durable Objects. Multi-tab/multi-process coordination via
+  BrowserCollectionCoordinator / ElectronCollectionCoordinator /
+  SingleProcessCoordinator. schemaVersion for migration resets. Local-only mode
+  for offline-first without a server.
+type: sub-skill
+library: db
+library_version: '0.6.0'
+sources:
+  - 'TanStack/db:packages/db-sqlite-persistence-core/src/persisted.ts'
+  - 'TanStack/db:packages/browser-db-sqlite-persistence/src/index.ts'
+  - 'TanStack/db:packages/react-native-db-sqlite-persistence/src/index.ts'
+  - 'TanStack/db:packages/expo-db-sqlite-persistence/src/index.ts'
+  - 'TanStack/db:packages/electron-db-sqlite-persistence/src/index.ts'
+  - 'TanStack/db:packages/node-db-sqlite-persistence/src/index.ts'
+  - 'TanStack/db:examples/react/offline-transactions/src/db/persisted-todos.ts'
+  - 'TanStack/db:examples/react-native/shopping-list/src/db/collections.ts'
+---
+
+This skill builds on db-core and db-core/collection-setup. Read those first.
+
+# SQLite Persistence
+
+TanStack DB persistence adds a durable SQLite-backed layer to any collection. Data survives page reloads, app restarts, and offline periods. The server remains authoritative for synced collections -- persistence provides a local cache that hydrates instantly.
+
+## Choosing a Platform Package
+
+| Platform       | Package                                                      | Create function                              |
+| -------------- | ------------------------------------------------------------ | -------------------------------------------- |
+| Browser (OPFS) | `@tanstack/browser-db-sqlite-persistence`                    | `createBrowserWASQLitePersistence`           |
+| React Native   | `@tanstack/react-native-db-sqlite-persistence`               | `createReactNativeSQLitePersistence`         |
+| Expo           | `@tanstack/expo-db-sqlite-persistence`                       | `createExpoSQLitePersistence`                |
+| Electron       | `@tanstack/electron-db-sqlite-persistence`                   | `createElectronSQLitePersistence` (renderer) |
+| Node.js        | `@tanstack/node-db-sqlite-persistence`                       | `createNodeSQLitePersistence`                |
+| Capacitor      | `@tanstack/capacitor-db-sqlite-persistence`                  | `createCapacitorSQLitePersistence`           |
+| Tauri          | `@tanstack/tauri-db-sqlite-persistence`                      | `createTauriSQLitePersistence`               |
+| Cloudflare DO  | `@tanstack/cloudflare-durable-objects-db-sqlite-persistence` | `createCloudflareDOSQLitePersistence`        |
+
+All platform packages re-export `persistedCollectionOptions` from the core.
+
+## Local-Only Persistence (No Server)
+
+For purely local data with no sync backend:
+
+```ts
+import { createCollection } from '@tanstack/react-db'
+import {
+  BrowserCollectionCoordinator,
+  createBrowserWASQLitePersistence,
+  openBrowserWASQLiteOPFSDatabase,
+  persistedCollectionOptions,
+} from '@tanstack/browser-db-sqlite-persistence'
+
+const database = await openBrowserWASQLiteOPFSDatabase({
+  databaseName: 'my-app.sqlite',
+})
+
+const coordinator = new BrowserCollectionCoordinator({
+  dbName: 'my-app',
+})
+
+const persistence = createBrowserWASQLitePersistence({
+  database,
+  coordinator,
+})
+
+const draftsCollection = createCollection(
+  persistedCollectionOptions<Draft, string>({
+    id: 'drafts',
+    getKey: (d) => d.id,
+    persistence,
+    schemaVersion: 1,
+  }),
+)
+```
+
+Local-only collections provide `collection.utils.acceptMutations()` for applying mutations directly.
+
+## Synced Persistence (Wrapping an Adapter)
+
+Spread an existing adapter's options into `persistedCollectionOptions` to add persistence on top of sync:
+
+```ts
+import { createCollection } from '@tanstack/react-db'
+import { electricCollectionOptions } from '@tanstack/electric-db-collection'
+import {
+  createReactNativeSQLitePersistence,
+  persistedCollectionOptions,
+} from '@tanstack/react-native-db-sqlite-persistence'
+
+const persistence = createReactNativeSQLitePersistence({ database })
+
+const todosCollection = createCollection(
+  persistedCollectionOptions({
+    ...electricCollectionOptions({
+      id: 'todos',
+      shapeOptions: { url: '/api/electric/todos' },
+      getKey: (item) => item.id,
+    }),
+    persistence,
+    schemaVersion: 1,
+  }),
+)
+```
+
+This works with any adapter: `electricCollectionOptions`, `queryCollectionOptions`, `powerSyncCollectionOptions`, etc. The `persistedCollectionOptions` wrapper intercepts the sync layer to persist data as it flows through.
+
+## Multi-Tab / Multi-Process Coordination
+
+Coordinators handle leader election and cross-instance communication so only one tab/process owns the database writer.
+
+| Platform                              | Coordinator                     | Mechanism                                      |
+| ------------------------------------- | ------------------------------- | ---------------------------------------------- |
+| Browser                               | `BrowserCollectionCoordinator`  | BroadcastChannel + Web Locks                   |
+| Electron                              | `ElectronCollectionCoordinator` | IPC (main holds DB, renderer accesses via RPC) |
+| Single-process (RN, Expo, Node, etc.) | `SingleProcessCoordinator`      | No-op (always leader)                          |
+
+Browser example:
+
+```ts
+import { BrowserCollectionCoordinator } from '@tanstack/browser-db-sqlite-persistence'
+
+const coordinator = new BrowserCollectionCoordinator({
+  dbName: 'my-app',
+})
+
+// Pass to persistence
+const persistence = createBrowserWASQLitePersistence({ database, coordinator })
+
+// Cleanup on shutdown
+coordinator.dispose()
+```
+
+Electron requires setup in both processes:
+
+```ts
+// Main process
+import { exposeElectronSQLitePersistence } from '@tanstack/electron-db-sqlite-persistence'
+exposeElectronSQLitePersistence({ persistence, ipcMain })
+
+// Renderer process
+import {
+  createElectronSQLitePersistence,
+  ElectronCollectionCoordinator,
+} from '@tanstack/electron-db-sqlite-persistence'
+
+const coordinator = new ElectronCollectionCoordinator({ dbName: 'my-app' })
+const persistence = createElectronSQLitePersistence({
+  ipcRenderer: window.electron.ipcRenderer,
+  coordinator,
+})
+```
+
+## Schema Versioning
+
+`schemaVersion` tracks the shape of persisted data. When the stored version doesn't match the code, the collection resets (drops and reloads from server for synced collections, or throws for local-only).
+
+```ts
+persistedCollectionOptions({
+  // ...
+  schemaVersion: 2, // bump when you change the data shape
+})
+```
+
+There is no custom migration function -- a version mismatch triggers a full reset. For synced collections this is safe because the server re-supplies the data.
+
+## Key Options
+
+| Option          | Type                             | Description                                              |
+| --------------- | -------------------------------- | -------------------------------------------------------- |
+| `persistence`   | `PersistedCollectionPersistence` | Platform adapter + coordinator                           |
+| `schemaVersion` | `number`                         | Data version (default 1). Bump on schema changes         |
+| `id`            | `string`                         | Required for local-only. Collection identifier in SQLite |
+
+## Common Mistakes
+
+### CRITICAL Using local-only persistence without an `id`
+
+Wrong:
+
+```ts
+persistedCollectionOptions({
+  getKey: (d) => d.id,
+  persistence,
+  // missing id — generates random UUID each session, data won't persist across reloads
+})
+```
+
+Correct:
+
+```ts
+persistedCollectionOptions({
+  id: 'drafts',
+  getKey: (d) => d.id,
+  persistence,
+})
+```
+
+Without an explicit `id`, the code generates a random UUID each session, so persisted data is silently abandoned on every reload. Local-only persisted collections must always provide an `id`. Synced collections derive it from the adapter config.
+
+### HIGH Forgetting the coordinator in multi-tab apps
+
+Wrong:
+
+```ts
+const persistence = createBrowserWASQLitePersistence({ database })
+// No coordinator — concurrent tabs corrupt the database
+```
+
+Correct:
+
+```ts
+const coordinator = new BrowserCollectionCoordinator({ dbName: 'my-app' })
+const persistence = createBrowserWASQLitePersistence({ database, coordinator })
+```
+
+Without a coordinator, multiple browser tabs write to SQLite concurrently, causing data corruption. Always use `BrowserCollectionCoordinator` in browser environments.
+
+### HIGH Not bumping schemaVersion after changing data shape
+
+If you add, remove, or rename fields in your collection type but keep the same `schemaVersion`, the persisted SQLite data will have the old shape. For synced collections, bump the version to trigger a reset and re-sync.
+
+### MEDIUM Not disposing the coordinator on cleanup
+
+```ts
+// On app shutdown or hot module reload
+coordinator.dispose()
+await database.close?.()
+```
+
+Failing to dispose leaks BroadcastChannel subscriptions and Web Lock handles.
+
+See also: db-core/collection-setup/SKILL.md — for adapter selection and collection configuration.
+
+See also: offline/SKILL.md — for offline transaction queueing (complements persistence).

package/skills/meta-framework/SKILL.md

@@ -9,7 +9,7 @@ description: >
   loader APIs.
 type: composition
 library: db
-library_version: '0.5.30'
+library_version: '0.6.0'
 requires:
   - db-core
   - db-core/collection-setup

package/src/query/compiler/joins.ts

@@ -302,8 +302,20 @@ function processJoin(
             return
           }
 
-          // Request filtered snapshot from lazy collection for matching join keys
-          const joinKeys = data.getInner().map(([[joinKey]]) => joinKey)
+          // Deduplicate and filter null keys before requesting snapshot
+          const joinKeys = [
+            ...new Set(
+              data
+                .getInner()
+                .map(([[joinKey]]) => joinKey)
+                .filter((key) => key != null),
+            ),
+          ]
+
+          if (joinKeys.length === 0) {
+            return
+          }
+
           const lazyJoinRef = new PropRef(followRefResult.path)
           const loaded = lazySourceSubscription.requestSnapshot({
             where: inArray(lazyJoinRef, joinKeys),

package/src/query/live/collection-config-builder.ts

@@ -227,7 +227,8 @@ export class CollectionConfigBuilder<
       id: this.id,
       getKey:
         this.config.getKey ||
-        ((item) => this.resultKeys.get(item) as string | number),
+        ((item: any) =>
+          (this.resultKeys.get(item) ?? item.$key) as string | number),
       sync: this.getSyncConfig(),
       compare: this.compare,
       defaultStringCollation: this.compareOptions,
@@ -1515,6 +1516,7 @@ function createChildCollectionEntry(
       },
     },
     startSync: true,
+    gcTime: 0,
   })
 
   const entry: ChildCollectionEntry = {