@octanejs/tanstack-db 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @octanejs/tanstack-db
+
+Octane live-query hooks for [TanStack DB](https://github.com/TanStack/db).
+
+Re-exports [`@tanstack/db`](https://tanstack.com/db) unchanged and implements its
+live-query binding surface on Octane hooks:
+
+- `useLiveQuery`
+- `useLiveInfiniteQuery`
+- `useLiveSuspenseQuery`
+- `useLiveQueryEffect`
+- `usePacedMutations`
+
+Install `octane` alongside this package and configure the Octane compiler in your
+build tool (see [octanejs.dev](https://octanejs.dev/docs/build-tools)).
+
+## Compatibility
+
+Ports the React live-query hooks of `@tanstack/react-db@0.1.96` onto Octane and
+re-exports the framework-neutral `@tanstack/db@0.7.0` core unchanged.
+`useLiveQuery`/`useLiveSuspenseQuery` run on db's shared `createLiveQueryObserver`
+and `useLiveInfiniteQuery` on the coordinated `createLiveQueryWindowController`.
+
+Intentional differences from React:
+
+- **Suspense** integrates via Octane's `use(thenable)` rather than throwing a raw
+  promise (observable behavior — fallback then data — matches).
+- **`useLiveInfiniteQuery`** rejects a pre-created collection that lacks an
+  `orderBy` synchronously during render, so the error reaches the caller.
+- **StrictMode double-invocation** is not applicable (Octane has no development
+  double-invoke).
+
+See `UPSTREAM.md` for the pin and export crosswalk and `status.json` for the
+tracked binding status.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@octanejs/tanstack-db",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "TanStack DB bindings for Octane — reuses @tanstack/db's framework-agnostic core with Octane live-query hooks.",
+  "author": "Kyle Mathews",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tanstack-db"
+  },
+  "homepage": "https://tanstack.com/db",
+  "keywords": [
+    "optimistic",
+    "octane",
+    "typescript",
+    "tanstack-intent"
+  ],
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@tanstack/db": "^0.7.0"
+  },
+  "peerDependencies": {
+    "octane": "0.1.38"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "@octanejs/testing-library": "0.1.35",
+    "octane": "0.1.38"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/skills/tanstack-db/SKILL.md

@@ -0,0 +1,432 @@
+---
+name: tanstack-db
+description: >
+  Octane bindings for TanStack DB. useLiveQuery hook with dependency arrays
+  (8 overloads: query function, config object, pre-created collection,
+  disabled state via returning undefined/null). useLiveSuspenseQuery for
+  Octane Suspense with Error Boundaries (data always defined).
+  useLiveInfiniteQuery for cursor-based pagination (pageSize, fetchNextPage,
+  hasNextPage, isFetchingNextPage). usePacedMutations for debounced Octane
+  state updates. Return shape: data, state, collection, status, isLoading,
+  isReady, isError. Import from @octanejs/tanstack-db (re-exports all of
+  @tanstack/db).
+type: framework
+library: db
+framework: octane
+library_version: '0.6.0'
+requires:
+  - db-core
+sources:
+  - 'TanStack/db:docs/framework/octane/overview.md'
+  - 'TanStack/db:docs/guides/live-queries.md'
+  - 'TanStack/db:packages/octane-db/src/useLiveQuery.ts'
+  - 'TanStack/db:packages/octane-db/src/useLiveInfiniteQuery.ts'
+  - 'TanStack/db:packages/octane-db/src/useLiveQueryEffect.ts'
+---
+
+This skill builds on db-core. Read it first for collection setup, query builder, and mutation patterns.
+
+# TanStack DB — Octane
+
+## Setup
+
+```tsx
+import { useLiveQuery, eq, not } from '@octanejs/tanstack-db'
+
+function TodoList() {
+  const { data: todos, isLoading } = useLiveQuery((q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => not(todo.completed))
+      .orderBy(({ todo }) => todo.created_at, 'asc'),
+  )
+
+  if (isLoading) return <div>Loading...</div>
+
+  return (
+    <ul>
+      {todos.map((todo) => (
+        <li key={todo.id}>{todo.text}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+`@octanejs/tanstack-db` re-exports everything from `@tanstack/db`. In Octane projects, import everything from `@octanejs/tanstack-db`.
+
+## Hooks
+
+### useLiveQuery
+
+```tsx
+// Query function with dependency array
+const {
+  data,
+  state,
+  collection,
+  status,
+  isLoading,
+  isReady,
+  isError,
+  isIdle,
+  isCleanedUp,
+} = useLiveQuery(
+  (q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => eq(todo.userId, userId)),
+  [userId],
+)
+
+// Config object
+const { data } = useLiveQuery({
+  query: (q) => q.from({ todo: todoCollection }),
+  gcTime: 60000,
+})
+
+// Pre-created collection (from route loader)
+const { data } = useLiveQuery(preloadedCollection)
+
+// Conditional query — return undefined/null to disable
+const { data, status } = useLiveQuery(
+  (q) => {
+    if (!userId) return undefined
+    return q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => eq(todo.userId, userId))
+  },
+  [userId],
+)
+// When disabled: status='disabled', data=undefined
+```
+
+### useLiveSuspenseQuery
+
+```tsx
+// data is ALWAYS defined — never undefined
+// Must wrap in <Suspense> and <ErrorBoundary>
+function TodoList() {
+  const { data: todos } = useLiveSuspenseQuery((q) =>
+    q.from({ todo: todoCollection }),
+  )
+
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.text}</li>
+      ))}
+    </ul>
+  )
+}
+
+// With deps — re-suspends when deps change
+const { data } = useLiveSuspenseQuery(
+  (q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => eq(todo.category, category)),
+  [category],
+)
+```
+
+### useLiveInfiniteQuery
+
+```tsx
+const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+  useLiveInfiniteQuery(
+    (q) =>
+      q
+        .from({ posts: postsCollection })
+        .where(({ posts }) => eq(posts.category, category))
+        .orderBy(({ posts }) => posts.createdAt, 'desc'),
+    { pageSize: 20 },
+    [category],
+  )
+
+// data is the flat array of all loaded pages
+// fetchNextPage() loads the next page
+// hasNextPage is true when more data is available
+```
+
+### usePacedMutations
+
+```tsx
+import { usePacedMutations, debounceStrategy } from "@octanejs/tanstack-db"
+
+const mutate = usePacedMutations({
+  onMutate: (value: string) => {
+    noteCollection.update(noteId, (draft) => {
+      draft.content = value
+    })
+  },
+  mutationFn: async ({ transaction }) => {
+    await api.notes.update(noteId, transaction.mutations[0].changes)
+  },
+  strategy: debounceStrategy({ wait: 500 }),
+})
+
+// In handler:
+<textarea onChange={(e) => mutate(e.target.value)} />
+```
+
+### useLiveQueryEffect
+
+```tsx
+import { useLiveQueryEffect, eq } from '@octanejs/tanstack-db'
+
+// Fire side effects when rows enter, exit, or update a query result.
+// No render output — the effect is created on mount, disposed on unmount,
+// and recreated when deps change.
+function ChatComponent() {
+  useLiveQueryEffect(
+    {
+      query: (q) =>
+        q.from({ msg: messages }).where(({ msg }) => eq(msg.role, 'user')),
+      skipInitial: true,
+      onEnter: async (event) => {
+        await generateResponse(event.value)
+      },
+    },
+    [],
+  )
+
+  return <div>...</div>
+}
+```
+
+## Includes (Hierarchical Data)
+
+When a query uses includes (subqueries in `select`), each child field is a live `Collection` by default. Subscribe to it with `useLiveQuery` in a subcomponent:
+
+```tsx
+function ProjectList() {
+  const { data: projects } = useLiveQuery((q) =>
+    q.from({ p: projectsCollection }).select(({ p }) => ({
+      id: p.id,
+      name: p.name,
+      issues: q
+        .from({ i: issuesCollection })
+        .where(({ i }) => eq(i.projectId, p.id))
+        .select(({ i }) => ({ id: i.id, title: i.title })),
+    })),
+  )
+
+  return (
+    <ul>
+      {projects.map((project) => (
+        <li key={project.id}>
+          {project.name}
+          <IssueList issuesCollection={project.issues} />
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+// Child component subscribes to the child Collection
+function IssueList({ issuesCollection }) {
+  const { data: issues } = useLiveQuery(issuesCollection)
+  return (
+    <ul>
+      {issues.map((issue) => (
+        <li key={issue.id}>{issue.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+Only the affected `IssueList` re-renders when an issue changes — the parent does not.
+
+With `toArray()`, child results are plain arrays and the parent re-renders on child changes:
+
+```tsx
+import { toArray, eq } from '@octanejs/tanstack-db'
+
+const { data: projects } = useLiveQuery((q) =>
+  q.from({ p: projectsCollection }).select(({ p }) => ({
+    id: p.id,
+    name: p.name,
+    issues: toArray(
+      q
+        .from({ i: issuesCollection })
+        .where(({ i }) => eq(i.projectId, p.id))
+        .select(({ i }) => ({ id: i.id, title: i.title })),
+    ),
+  })),
+)
+// project.issues is Array<{ id, title }> — no subcomponent needed
+```
+
+See db-core/live-queries/SKILL.md for full includes rules (correlation conditions, nested includes, aggregates).
+
+## Virtual Properties
+
+Live query results include computed, read-only virtual properties on every row:
+
+- `$synced`: `true` when the row is confirmed by sync; `false` when it is still optimistic.
+- `$origin`: `"local"` if the last confirmed change came from this client, otherwise `"remote"`.
+- `$key`: the row key for the result.
+- `$collectionId`: the source collection ID.
+
+These props are added automatically and can be used in `where`, `select`, and `orderBy` clauses. Do not persist them back to storage.
+
+```tsx
+const { data } = useLiveQuery(
+  (q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => eq(todo.$synced, false)),
+  [],
+)
+// Shows only optimistic (unconfirmed) todos
+```
+
+## Octane-Specific Patterns
+
+### Dependency arrays
+
+```tsx
+// Include ALL external reactive values
+const { data } = useLiveQuery(
+  (q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) =>
+        and(eq(todo.userId, userId), eq(todo.status, filter)),
+      ),
+  [userId, filter],
+)
+
+// Empty array = static query, never re-runs
+const { data } = useLiveQuery((q) => q.from({ todo: todoCollection }), [])
+
+// No array = re-runs on every render (usually wrong)
+```
+
+### Suspense + Error Boundary
+
+```tsx
+<ErrorBoundary fallback={<div>Error</div>}>
+  <Suspense fallback={<div>Loading...</div>}>
+    <TodoList />
+  </Suspense>
+</ErrorBoundary>
+```
+
+### Router loader preloading
+
+```tsx
+// In route loader:
+await todoCollection.preload()
+
+// In component — data available immediately:
+const { data } = useLiveQuery((q) => q.from({ todo: todoCollection }))
+```
+
+See meta-framework/SKILL.md for full preloading patterns.
+
+## Common Mistakes
+
+### CRITICAL Missing external values in dependency array
+
+Wrong:
+
+```tsx
+const { data } = useLiveQuery((q) =>
+  q.from({ todo: todoCollection }).where(({ todo }) => eq(todo.userId, userId)),
+)
+```
+
+Correct:
+
+```tsx
+const { data } = useLiveQuery(
+  (q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => eq(todo.userId, userId)),
+  [userId],
+)
+```
+
+When the query uses external state not in the deps array, the query won't re-run when that value changes, showing stale results.
+
+Source: docs/framework/octane/overview.md
+
+### HIGH useLiveSuspenseQuery without Error Boundary
+
+Wrong:
+
+```tsx
+<Suspense fallback={<div>Loading...</div>}>
+  <TodoList /> {/* uses useLiveSuspenseQuery */}
+</Suspense>
+```
+
+Correct:
+
+```tsx
+<ErrorBoundary fallback={<div>Error</div>}>
+  <Suspense fallback={<div>Loading...</div>}>
+    <TodoList />
+  </Suspense>
+</ErrorBoundary>
+```
+
+`useLiveSuspenseQuery` throws errors during rendering. Without an Error Boundary, the entire app crashes.
+
+Source: docs/guides/live-queries.md
+
+### HIGH "Not a Collection" error from duplicate @tanstack/db
+
+If `useLiveQuery` throws `InvalidSourceError: The value provided for alias "todo" is not a Collection`, it usually means two copies of `@tanstack/db` are installed. The collection was created by one copy, but `useLiveQuery` checks `instanceof` against the other.
+
+In dev mode, TanStack DB also throws `DuplicateDbInstanceError` if two instances are detected.
+
+**Diagnose:**
+
+```bash
+pnpm ls @tanstack/db
+```
+
+If multiple versions appear, fix with one of:
+
+**pnpm overrides** (in root package.json):
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "@tanstack/db": "^0.6.0"
+    }
+  }
+}
+```
+
+**Vite resolve.alias** (in vite.config.ts):
+
+```ts
+import path from 'path'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@tanstack/db': path.resolve('./node_modules/@tanstack/db'),
+    },
+  },
+})
+```
+
+The root cause is typically a dependency that bundles its own copy instead of declaring `@tanstack/db` as a `peerDependency`.
+
+### HIGH Tension: Query expressiveness vs. IVM constraints
+
+The query builder looks like SQL but has constraints that SQL doesn't — equality joins only, orderBy required for limit/offset, no distinct without select. Agents write SQL-style queries that violate these constraints. See db-core/live-queries/SKILL.md § Common Mistakes for all constraints.
+
+See also: db-core/live-queries/SKILL.md — for query builder API and all operators.
+
+See also: db-core/mutations-optimistic/SKILL.md — for mutation patterns.
+
+See also: meta-framework/SKILL.md — for preloading in route loaders.

package/src/index.ts

@@ -0,0 +1,13 @@
+// Re-export all public APIs
+export * from './useLiveQuery';
+export * from './useLiveSuspenseQuery';
+export * from './usePacedMutations';
+export * from './useLiveInfiniteQuery';
+export * from './useLiveQueryEffect';
+
+// Re-export everything from @tanstack/db
+export * from '@tanstack/db';
+
+// Re-export some stuff explicitly to ensure the type & value is exported
+export type { Collection } from '@tanstack/db';
+export { createTransaction } from '@tanstack/db';

package/src/slot.ts

@@ -0,0 +1,26 @@
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+
+/**
+ * Derive a stable sub-slot from a wrapper's compiler-injected slot so nested
+ * Octane hooks inside a custom hook each get distinct call-site identity.
+ */
+export function subSlot(slot: symbol | undefined, tag: string): symbol | undefined {
+	if (slot === undefined) return undefined;
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let sym = byTag.get(tag);
+	if (sym === undefined) {
+		sym = Symbol.for(`${slot.description ?? ``}:${tag}`);
+		byTag.set(tag, sym);
+	}
+	return sym;
+}
+
+/** Split a compiler-injected trailing slot symbol off hook runtime args. */
+export function splitTrailingSlot<T extends Array<unknown>>(
+	args: T,
+): [Array<unknown>, symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === `symbol` ? tail : undefined;
+	return [slot !== undefined ? args.slice(0, -1) : args, slot];
+}