@tanstack/db 0.5.30 → 0.5.31

package/dist/cjs/index.cjs

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const ir = require("./query/ir.cjs");
-const index = require("./collection/index.cjs");
+const index$1 = require("./collection/index.cjs");
 const SortedMap = require("./SortedMap.cjs");
 const transactions = require("./transactions.cjs");
 const proxy = require("./proxy.cjs");
@@ -16,17 +16,17 @@ const btreeIndex = require("./indexes/btree-index.cjs");
 const lazyIndex = require("./indexes/lazy-index.cjs");
 const expressionHelpers = require("./query/expression-helpers.cjs");
 const functions = require("./query/builder/functions.cjs");
-const index$1 = require("./query/builder/index.cjs");
+const index = require("./query/builder/index.cjs");
+const subsetDedupe = require("./query/subset-dedupe.cjs");
 const index$2 = require("./query/compiler/index.cjs");
 const liveQueryCollection = require("./query/live-query-collection.cjs");
-const predicateUtils = require("./query/predicate-utils.cjs");
-const subsetDedupe = require("./query/subset-dedupe.cjs");
 const debounceStrategy = require("./strategies/debounceStrategy.cjs");
+const predicateUtils = require("./query/predicate-utils.cjs");
 const queueStrategy = require("./strategies/queueStrategy.cjs");
 const throttleStrategy = require("./strategies/throttleStrategy.cjs");
 exports.IR = ir;
-exports.CollectionImpl = index.CollectionImpl;
-exports.createCollection = index.createCollection;
+exports.CollectionImpl = index$1.CollectionImpl;
+exports.createCollection = index$1.createCollection;
 exports.SortedMap = SortedMap.SortedMap;
 exports.createTransaction = transactions.createTransaction;
 exports.getActiveTransaction = transactions.getActiveTransaction;
@@ -161,11 +161,13 @@ exports.operators = functions.operators;
 exports.or = functions.or;
 exports.sum = functions.sum;
 exports.upper = functions.upper;
-exports.BaseQueryBuilder = index$1.BaseQueryBuilder;
-exports.Query = index$1.Query;
+exports.BaseQueryBuilder = index.BaseQueryBuilder;
+exports.Query = index.Query;
+exports.DeduplicatedLoadSubset = subsetDedupe.DeduplicatedLoadSubset;
 exports.compileQuery = index$2.compileQuery;
 exports.createLiveQueryCollection = liveQueryCollection.createLiveQueryCollection;
 exports.liveQueryCollectionOptions = liveQueryCollection.liveQueryCollectionOptions;
+exports.debounceStrategy = debounceStrategy.debounceStrategy;
 exports.isLimitSubset = predicateUtils.isLimitSubset;
 exports.isOffsetLimitSubset = predicateUtils.isOffsetLimitSubset;
 exports.isOrderBySubset = predicateUtils.isOrderBySubset;
@@ -173,8 +175,6 @@ exports.isPredicateSubset = predicateUtils.isPredicateSubset;
 exports.isWhereSubset = predicateUtils.isWhereSubset;
 exports.minusWherePredicates = predicateUtils.minusWherePredicates;
 exports.unionWherePredicates = predicateUtils.unionWherePredicates;
-exports.DeduplicatedLoadSubset = subsetDedupe.DeduplicatedLoadSubset;
-exports.debounceStrategy = debounceStrategy.debounceStrategy;
 exports.queueStrategy = queueStrategy.queueStrategy;
 exports.throttleStrategy = throttleStrategy.throttleStrategy;
 //# sourceMappingURL=index.cjs.map

package/dist/esm/index.js

@@ -15,11 +15,11 @@ import { IndexProxy, LazyIndexWrapper } from "./indexes/lazy-index.js";
 import { extractFieldPath, extractSimpleComparisons, extractValue, parseLoadSubsetOptions, parseOrderByExpression, parseWhereExpression, walkExpression } from "./query/expression-helpers.js";
 import { add, and, avg, coalesce, concat, count, eq, gt, gte, ilike, inArray, isNull, isUndefined, length, like, lower, lt, lte, max, min, not, operators, or, sum, upper } from "./query/builder/functions.js";
 import { BaseQueryBuilder, Query } from "./query/builder/index.js";
+import { DeduplicatedLoadSubset } from "./query/subset-dedupe.js";
 import { compileQuery } from "./query/compiler/index.js";
 import { createLiveQueryCollection, liveQueryCollectionOptions } from "./query/live-query-collection.js";
-import { isLimitSubset, isOffsetLimitSubset, isOrderBySubset, isPredicateSubset, isWhereSubset, minusWherePredicates, unionWherePredicates } from "./query/predicate-utils.js";
-import { DeduplicatedLoadSubset } from "./query/subset-dedupe.js";
 import { debounceStrategy } from "./strategies/debounceStrategy.js";
+import { isLimitSubset, isOffsetLimitSubset, isOrderBySubset, isPredicateSubset, isWhereSubset, minusWherePredicates, unionWherePredicates } from "./query/predicate-utils.js";
 import { queueStrategy } from "./strategies/queueStrategy.js";
 import { throttleStrategy } from "./strategies/throttleStrategy.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/db",
-  "version": "0.5.30",
+  "version": "0.5.31",
   "description": "A reactive client store for building super fast apps on sync",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -34,7 +34,8 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills"
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",

package/skills/db-core/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: db-core
+description: >
+  TanStack DB core concepts: createCollection with queryCollectionOptions,
+  electricCollectionOptions, powerSyncCollectionOptions, rxdbCollectionOptions,
+  trailbaseCollectionOptions, localOnlyCollectionOptions. Live queries via
+  query builder (from, where, join, select, groupBy, orderBy, limit). Optimistic
+  mutations with draft proxy (collection.insert, collection.update,
+  collection.delete). createOptimisticAction, createTransaction,
+  createPacedMutations. Entry point for all TanStack DB skills.
+type: core
+library: db
+library_version: '0.5.30'
+---
+
+# TanStack DB — Core Concepts
+
+TanStack DB is a reactive client-side data store. It loads data into typed
+collections from any backend (REST APIs, sync engines, local storage), provides
+sub-millisecond live queries via differential dataflow, and supports instant
+optimistic mutations with automatic rollback.
+
+Framework packages (`@tanstack/react-db`, `@tanstack/vue-db`, `@tanstack/svelte-db`,
+`@tanstack/solid-db`) re-export everything from `@tanstack/db` plus framework-specific
+hooks. In framework projects, import from the framework package directly.
+`@tanstack/angular-db` is the exception -- import operators from `@tanstack/db` separately.
+
+## Sub-Skills
+
+| Need to...                                       | Read                                                 |
+| ------------------------------------------------ | ---------------------------------------------------- |
+| Create a collection, pick an adapter, add schema | db-core/collection-setup/SKILL.md                    |
+| Query data with where, join, groupBy, select     | db-core/live-queries/SKILL.md                        |
+| Insert, update, delete with optimistic UI        | db-core/mutations-optimistic/SKILL.md                |
+| Build a custom sync adapter                      | db-core/custom-adapter/SKILL.md                      |
+| Preload collections in route loaders             | meta-framework/SKILL.md                              |
+| Add offline transaction queueing                 | offline/SKILL.md (in @tanstack/offline-transactions) |
+
+For framework-specific hooks:
+
+| Framework | Read                |
+| --------- | ------------------- |
+| React     | react-db/SKILL.md   |
+| Vue       | vue-db/SKILL.md     |
+| Svelte    | svelte-db/SKILL.md  |
+| Solid     | solid-db/SKILL.md   |
+| Angular   | angular-db/SKILL.md |
+
+## Quick Decision Tree
+
+- Setting up for the first time? → db-core/collection-setup
+- Building queries on collection data? → db-core/live-queries
+- Writing data / handling optimistic state? → db-core/mutations-optimistic
+- Using React hooks? → react-db
+- Preloading in route loaders (Start, Next, Remix)? → meta-framework
+- Building an adapter for a new backend? → db-core/custom-adapter
+- Need offline transaction persistence? → offline
+
+## Version
+
+Targets @tanstack/db v0.5.30.

package/skills/db-core/collection-setup/SKILL.md

@@ -0,0 +1,427 @@
+---
+name: db-core/collection-setup
+description: >
+  Creating typed collections with createCollection. Adapter selection:
+  queryCollectionOptions (REST/TanStack Query), electricCollectionOptions
+  (ElectricSQL real-time sync), powerSyncCollectionOptions (PowerSync SQLite),
+  rxdbCollectionOptions (RxDB), trailbaseCollectionOptions (TrailBase),
+  localOnlyCollectionOptions, localStorageCollectionOptions. CollectionConfig
+  options: getKey, schema, sync, gcTime, autoIndex, syncMode (eager/on-demand/
+  progressive). StandardSchema validation with Zod/Valibot/ArkType. Collection
+  lifecycle (idle/loading/ready/error). Adapter-specific sync patterns including
+  Electric txid tracking and Query direct writes.
+type: sub-skill
+library: db
+library_version: '0.5.30'
+sources:
+  - 'TanStack/db:docs/overview.md'
+  - 'TanStack/db:docs/guides/schemas.md'
+  - 'TanStack/db:docs/collections/query-collection.md'
+  - 'TanStack/db:docs/collections/electric-collection.md'
+  - 'TanStack/db:docs/collections/powersync-collection.md'
+  - 'TanStack/db:docs/collections/rxdb-collection.md'
+  - 'TanStack/db:docs/collections/trailbase-collection.md'
+  - 'TanStack/db:packages/db/src/collection/index.ts'
+---
+
+This skill builds on db-core. Read it first for the overall mental model.
+
+# Collection Setup & Schema
+
+## Setup
+
+```ts
+import { createCollection } from '@tanstack/react-db'
+import { queryCollectionOptions } from '@tanstack/query-db-collection'
+import { QueryClient } from '@tanstack/query-core'
+import { z } from 'zod'
+
+const queryClient = new QueryClient()
+
+const todoSchema = z.object({
+  id: z.number(),
+  text: z.string(),
+  completed: z.boolean().default(false),
+  created_at: z
+    .union([z.string(), z.date()])
+    .transform((val) => (typeof val === 'string' ? new Date(val) : val)),
+})
+
+const todoCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ['todos'],
+    queryFn: async () => {
+      const res = await fetch('/api/todos')
+      return res.json()
+    },
+    queryClient,
+    getKey: (item) => item.id,
+    schema: todoSchema,
+    onInsert: async ({ transaction }) => {
+      await api.todos.create(transaction.mutations[0].modified)
+      await todoCollection.utils.refetch()
+    },
+    onUpdate: async ({ transaction }) => {
+      const mut = transaction.mutations[0]
+      await api.todos.update(mut.key, mut.changes)
+      await todoCollection.utils.refetch()
+    },
+    onDelete: async ({ transaction }) => {
+      await api.todos.delete(transaction.mutations[0].key)
+      await todoCollection.utils.refetch()
+    },
+  }),
+)
+```
+
+## Choosing an Adapter
+
+| Backend                          | Adapter                         | Package                             |
+| -------------------------------- | ------------------------------- | ----------------------------------- |
+| REST API / TanStack Query        | `queryCollectionOptions`        | `@tanstack/query-db-collection`     |
+| ElectricSQL (real-time Postgres) | `electricCollectionOptions`     | `@tanstack/electric-db-collection`  |
+| PowerSync (SQLite offline)       | `powerSyncCollectionOptions`    | `@tanstack/powersync-db-collection` |
+| RxDB (reactive database)         | `rxdbCollectionOptions`         | `@tanstack/rxdb-db-collection`      |
+| TrailBase (event streaming)      | `trailbaseCollectionOptions`    | `@tanstack/trailbase-db-collection` |
+| No backend (UI state)            | `localOnlyCollectionOptions`    | `@tanstack/db`                      |
+| Browser localStorage             | `localStorageCollectionOptions` | `@tanstack/db`                      |
+
+If the user specifies a backend (e.g. Electric, PowerSync), use that adapter directly. Only use `localOnlyCollectionOptions` when there is no backend yet — the collection API is uniform, so swapping to a real adapter later only changes the options creator.
+
+## Sync Modes
+
+```ts
+queryCollectionOptions({
+  syncMode: 'eager', // default — loads all data upfront
+  // syncMode: "on-demand", // loads only what live queries request
+  // syncMode: "progressive", // (Electric only) query subset first, full sync in background
+})
+```
+
+| Mode          | Best for                                       | Data size |
+| ------------- | ---------------------------------------------- | --------- |
+| `eager`       | Mostly-static datasets                         | <10k rows |
+| `on-demand`   | Search, catalogs, large tables                 | >50k rows |
+| `progressive` | Collaborative apps needing instant first paint | Any       |
+
+## Core Patterns
+
+### Local-only collection for prototyping
+
+```ts
+import {
+  createCollection,
+  localOnlyCollectionOptions,
+} from '@tanstack/react-db'
+
+const todoCollection = createCollection(
+  localOnlyCollectionOptions({
+    getKey: (item) => item.id,
+    initialData: [{ id: 1, text: 'Learn TanStack DB', completed: false }],
+  }),
+)
+```
+
+### Schema with type transformations
+
+```ts
+const schema = z.object({
+  id: z.number(),
+  title: z.string(),
+  due_date: z
+    .union([z.string(), z.date()])
+    .transform((val) => (typeof val === 'string' ? new Date(val) : val)),
+  priority: z.number().default(0),
+})
+```
+
+Use `z.union([z.string(), z.date()])` for transformed fields — this ensures `TInput` is a superset of `TOutput` so that `update()` works correctly with the draft proxy.
+
+### ElectricSQL with txid tracking
+
+Always use a schema with Electric — without one, the collection types as `Record<string, unknown>`.
+
+```ts
+import { electricCollectionOptions } from '@tanstack/electric-db-collection'
+import { z } from 'zod'
+
+const todoSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  completed: z.boolean(),
+  created_at: z.coerce.date(),
+})
+
+const todoCollection = createCollection(
+  electricCollectionOptions({
+    schema: todoSchema,
+    shapeOptions: { url: '/api/electric/todos' },
+    getKey: (item) => item.id,
+    onInsert: async ({ transaction }) => {
+      const res = await api.todos.create(transaction.mutations[0].modified)
+      return { txid: res.txid }
+    },
+  }),
+)
+```
+
+The returned `txid` tells the collection to hold optimistic state until Electric streams back that transaction. See the [Electric adapter reference](references/electric-adapter.md) for the full dual-path pattern (schema + parser).
+
+## Common Mistakes
+
+### CRITICAL queryFn returning empty array deletes all data
+
+Wrong:
+
+```ts
+queryCollectionOptions({
+  queryFn: async () => {
+    const res = await fetch('/api/todos?status=active')
+    return res.json() // returns [] when no active todos — deletes everything
+  },
+})
+```
+
+Correct:
+
+```ts
+queryCollectionOptions({
+  queryFn: async () => {
+    const res = await fetch('/api/todos') // fetch complete state
+    return res.json()
+  },
+  // Use on-demand mode + live query where() for filtering
+  syncMode: 'on-demand',
+})
+```
+
+`queryFn` result is treated as complete server state. Returning `[]` means "server has no items", deleting all existing collection data.
+
+Source: docs/collections/query-collection.md
+
+### CRITICAL Not using the correct adapter for your backend
+
+Wrong:
+
+```ts
+const todoCollection = createCollection(
+  localOnlyCollectionOptions({
+    getKey: (item) => item.id,
+  }),
+)
+// Manually fetching and inserting...
+```
+
+Correct:
+
+```ts
+const todoCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ['todos'],
+    queryFn: async () => fetch('/api/todos').then((r) => r.json()),
+    queryClient,
+    getKey: (item) => item.id,
+  }),
+)
+```
+
+Each backend has a dedicated adapter that handles sync, mutation handlers, and utilities. Using `localOnlyCollectionOptions` or bare `createCollection` for a real backend bypasses all of this.
+
+Source: docs/overview.md
+
+### CRITICAL Electric txid queried outside mutation transaction
+
+Wrong:
+
+```ts
+// Backend handler
+app.post('/api/todos', async (req, res) => {
+  const txid = await generateTxId(sql) // WRONG: separate transaction
+  await sql`INSERT INTO todos ${sql(req.body)}`
+  res.json({ txid })
+})
+```
+
+Correct:
+
+```ts
+app.post('/api/todos', async (req, res) => {
+  let txid
+  await sql.begin(async (tx) => {
+    txid = await generateTxId(tx) // CORRECT: same transaction
+    await tx`INSERT INTO todos ${tx(req.body)}`
+  })
+  res.json({ txid })
+})
+```
+
+`pg_current_xact_id()` must be queried inside the same SQL transaction as the mutation. Otherwise the txid doesn't match and `awaitTxId` stalls forever.
+
+Source: docs/collections/electric-collection.md
+
+### CRITICAL queryFn returning partial data without merging
+
+Wrong:
+
+```ts
+queryCollectionOptions({
+  queryFn: async () => {
+    const newItems = await fetch('/api/todos?since=' + lastSync)
+    return newItems.json() // only new items — everything else deleted
+  },
+})
+```
+
+Correct:
+
+```ts
+queryCollectionOptions({
+  queryFn: async (ctx) => {
+    const existing = ctx.queryClient.getQueryData(['todos']) || []
+    const newItems = await fetch('/api/todos?since=' + lastSync).then((r) =>
+      r.json(),
+    )
+    return [...existing, ...newItems]
+  },
+})
+```
+
+`queryFn` result replaces all collection data. For incremental fetches, merge with existing data.
+
+Source: docs/collections/query-collection.md
+
+### HIGH Using async schema validation
+
+Wrong:
+
+```ts
+const schema = z.object({
+  email: z.string().refine(async (val) => {
+    const exists = await checkEmail(val)
+    return !exists
+  }),
+})
+```
+
+Correct:
+
+```ts
+const schema = z.object({
+  email: z.string().email(),
+})
+// Do async validation in the mutation handler instead
+```
+
+Schema validation must be synchronous. Async validation throws `SchemaMustBeSynchronousError` at mutation time.
+
+Source: packages/db/src/collection/mutations.ts:101
+
+### HIGH getKey returning undefined for some items
+
+Wrong:
+
+```ts
+createCollection(
+  queryCollectionOptions({
+    getKey: (item) => item.metadata.id, // undefined if metadata missing
+  }),
+)
+```
+
+Correct:
+
+```ts
+createCollection(
+  queryCollectionOptions({
+    getKey: (item) => item.id, // always present
+  }),
+)
+```
+
+`getKey` must return a defined value for every item. Throws `UndefinedKeyError` otherwise.
+
+Source: packages/db/src/collection/mutations.ts:148
+
+### HIGH TInput not a superset of TOutput with schema transforms
+
+Wrong:
+
+```ts
+const schema = z.object({
+  created_at: z.string().transform((val) => new Date(val)),
+})
+// update() fails — draft.created_at is Date but schema only accepts string
+```
+
+Correct:
+
+```ts
+const schema = z.object({
+  created_at: z
+    .union([z.string(), z.date()])
+    .transform((val) => (typeof val === 'string' ? new Date(val) : val)),
+})
+```
+
+When a schema transforms types, `TInput` must accept both the pre-transform and post-transform types for `update()` to work with the draft proxy.
+
+Source: docs/guides/schemas.md
+
+### HIGH React Native missing crypto.randomUUID polyfill
+
+TanStack DB uses `crypto.randomUUID()` internally. React Native doesn't provide this. Install `react-native-random-uuid` and import it at your app entry point.
+
+Source: docs/overview.md
+
+### MEDIUM Providing both explicit type parameter and schema
+
+Wrong:
+
+```ts
+createCollection<Todo>(queryCollectionOptions({ schema: todoSchema, ... }))
+```
+
+Correct:
+
+```ts
+createCollection(queryCollectionOptions({ schema: todoSchema, ... }))
+```
+
+When a schema is provided, the collection infers types from it. An explicit generic creates conflicting type constraints.
+
+Source: docs/overview.md
+
+### MEDIUM Direct writes overridden by next query sync
+
+Wrong:
+
+```ts
+todoCollection.utils.writeInsert(newItem)
+// Next queryFn execution replaces all data, losing the direct write
+```
+
+Correct:
+
+```ts
+todoCollection.utils.writeInsert(newItem)
+// Use staleTime to prevent immediate refetch
+// Or return { refetch: false } from mutation handlers
+```
+
+Direct writes update the collection immediately, but the next `queryFn` returns complete server state which overwrites them.
+
+Source: docs/collections/query-collection.md
+
+## References
+
+- [TanStack Query adapter](references/query-adapter.md)
+- [ElectricSQL adapter](references/electric-adapter.md)
+- [PowerSync adapter](references/powersync-adapter.md)
+- [RxDB adapter](references/rxdb-adapter.md)
+- [TrailBase adapter](references/trailbase-adapter.md)
+- [Local adapters (local-only, localStorage)](references/local-adapters.md)
+- [Schema validation patterns](references/schema-patterns.md)
+
+See also: db-core/mutations-optimistic/SKILL.md — mutation handlers configured here execute during mutations.
+
+See also: db-core/custom-adapter/SKILL.md — for building your own adapter.