├── .changeset
    └── config.json
├── .github
    └── workflows
    │   ├── autofix.yml
    │   ├── pr.yml
    │   └── release.yml
├── .gitignore
├── .husky
    └── pre-commit
├── .npmrc
├── .nvmrc
├── .prettierignore
├── .prettierrc
├── LICENSE
├── README.md
├── docs
    ├── config.json
    ├── framework
    │   ├── react
    │   │   └── adapter.md
    │   ├── solid
    │   │   └── adapter.md
    │   ├── svelte
    │   │   └── adapter.md
    │   └── vue
    │   │   └── adapter.md
    ├── index.md
    ├── installation.md
    ├── overview.md
    ├── quick-start.md
    ├── unidirectional-data-flow.lg.png
    └── unidirectional-data-flow.png
├── eslint.config.mjs
├── examples
    └── react
    │   └── todo
    │       ├── CHANGELOG.md
    │       ├── README.md
    │       ├── docker-compose.yml
    │       ├── drizzle.config.ts
    │       ├── drizzle
    │           ├── 0000_whole_sprite.sql
    │           ├── 0001_sturdy_titania.sql
    │           ├── 0002_update_timestamps_trigger.sql
    │           └── meta
    │           │   ├── 0000_snapshot.json
    │           │   ├── 0001_snapshot.json
    │           │   ├── 0002_snapshot.json
    │           │   └── _journal.json
    │       ├── index.html
    │       ├── package.json
    │       ├── pnpm-lock.yaml
    │       ├── postgres.conf
    │       ├── public
    │           └── vite.svg
    │       ├── scripts
    │           └── migrate.ts
    │       ├── src
    │           ├── App.tsx
    │           ├── DevTools.tsx
    │           ├── DiffView.tsx
    │           ├── api
    │           │   ├── server.ts
    │           │   └── write-to-pg.ts
    │           ├── assets
    │           │   └── react.svg
    │           ├── db
    │           │   ├── index.ts
    │           │   ├── postgres.ts
    │           │   ├── schema.ts
    │           │   └── validation.ts
    │           ├── index.css
    │           ├── main.tsx
    │           └── vite-env.d.ts
    │       └── vite.config.ts
├── media
    └── repo-header.jpg
├── package.json
├── packages
    ├── db-collections
    │   ├── CHANGELOG.md
    │   ├── README.md
    │   ├── package.json
    │   ├── src
    │   │   ├── electric.ts
    │   │   ├── index.ts
    │   │   └── query.ts
    │   ├── tests
    │   │   ├── electric.test.ts
    │   │   ├── query.test.ts
    │   │   └── test-setup.ts
    │   ├── tsconfig.json
    │   └── vite.config.ts
    ├── db
    │   ├── CHANGELOG.md
    │   ├── README.md
    │   ├── package.json
    │   ├── src
    │   │   ├── SortedMap.ts
    │   │   ├── collection.ts
    │   │   ├── deferred.ts
    │   │   ├── errors.ts
    │   │   ├── index.ts
    │   │   ├── proxy.ts
    │   │   ├── query
    │   │   │   ├── compiled-query.ts
    │   │   │   ├── evaluators.ts
    │   │   │   ├── extractors.ts
    │   │   │   ├── functions.ts
    │   │   │   ├── group-by.ts
    │   │   │   ├── index.ts
    │   │   │   ├── joins.ts
    │   │   │   ├── key-by.ts
    │   │   │   ├── order-by.ts
    │   │   │   ├── pipeline-compiler.ts
    │   │   │   ├── query-builder.ts
    │   │   │   ├── schema.ts
    │   │   │   ├── select.ts
    │   │   │   ├── types.ts
    │   │   │   └── utils.ts
    │   │   ├── transactions.ts
    │   │   ├── types.ts
    │   │   └── utils.ts
    │   ├── tests
    │   │   ├── SortedMap.test.ts
    │   │   ├── collection-getters.test.ts
    │   │   ├── collection-subscribe-changes.test.ts
    │   │   ├── collection.test.ts
    │   │   ├── deferred.test.ts
    │   │   ├── errors.test.ts
    │   │   ├── object-key-map.test.ts
    │   │   ├── preloadCollection.test.ts
    │   │   ├── proxy.test.ts
    │   │   ├── query
    │   │   │   ├── compiler.test.ts
    │   │   │   ├── conditions.test.ts
    │   │   │   ├── function-integration.test.ts
    │   │   │   ├── functions.test.ts
    │   │   │   ├── group-by.test.ts
    │   │   │   ├── having.test.ts
    │   │   │   ├── in-operator.test.ts
    │   │   │   ├── join.test.ts
    │   │   │   ├── key-by.test.ts
    │   │   │   ├── like-operator.test.ts
    │   │   │   ├── nested-conditions.test.ts
    │   │   │   ├── order-by.test.ts
    │   │   │   ├── query-builder
    │   │   │   │   ├── from.test.ts
    │   │   │   │   ├── group-by.test.ts
    │   │   │   │   ├── having.test.ts
    │   │   │   │   ├── join.test.ts
    │   │   │   │   ├── key-by.test.ts
    │   │   │   │   ├── order-by.test.ts
    │   │   │   │   ├── select-functions.test.ts
    │   │   │   │   ├── select.test.ts
    │   │   │   │   ├── where.test.ts
    │   │   │   │   └── with.test.ts
    │   │   │   ├── query-collection.test.ts
    │   │   │   ├── query-types.test.ts
    │   │   │   ├── table-alias.test.ts
    │   │   │   ├── types.test.ts
    │   │   │   ├── wildcard-select.test.ts
    │   │   │   └── with.test.ts
    │   │   ├── test-setup.ts
    │   │   ├── transaction-types.test.ts
    │   │   ├── transactions.test.ts
    │   │   └── utils.test.ts
    │   ├── tsconfig.json
    │   └── vite.config.ts
    ├── react-db
    │   ├── CHANGELOG.md
    │   ├── README.md
    │   ├── package.json
    │   ├── src
    │   │   ├── index.ts
    │   │   ├── useLiveQuery.ts
    │   │   └── useOptimisticMutation.ts
    │   ├── tests
    │   │   ├── test-setup.ts
    │   │   └── useLiveQuery.test.tsx
    │   ├── tsconfig.json
    │   └── vite.config.ts
    └── vue-db
    │   ├── CHANGELOG.md
    │   ├── README.md
    │   ├── package.json
    │   ├── src
    │       ├── index.ts
    │       ├── useLiveQuery.ts
    │       └── useOptimisticMutation.ts
    │   ├── tests
    │       └── useLiveQuery.test.ts
    │   ├── tsconfig.json
    │   └── vite.config.ts
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── todo.md
└── tsconfig.json


/.changeset/config.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
 3 |   "changelog": [
 4 |     "@svitejs/changesets-changelog-github-compact",
 5 |     { "repo": "TanStack/optimistic" }
 6 |   ],
 7 |   "commit": false,
 8 |   "access": "public",
 9 |   "baseBranch": "main",
10 |   "updateInternalDependencies": "patch",
11 |   "fixed": [],
12 |   "linked": [],
13 |   "ignore": []
14 | }
15 | 


--------------------------------------------------------------------------------
/.github/workflows/autofix.yml:
--------------------------------------------------------------------------------
 1 | name: autofix.ci # needed to securely identify the workflow
 2 | 
 3 | on:
 4 |   pull_request:
 5 |   push:
 6 |     branches: [main, alpha, beta]
 7 | 
 8 | concurrency:
 9 |   group: ${{ github.workflow }}-${{ github.event.number || github.ref }}
10 |   cancel-in-progress: true
11 | 
12 | permissions:
13 |   contents: read
14 | 
15 | jobs:
16 |   autofix:
17 |     name: autofix
18 |     runs-on: ubuntu-latest
19 |     steps:
20 |       - name: Checkout
21 |         uses: actions/checkout@v4.2.2
22 |       - name: Setup Tools
23 |         uses: tanstack/config/.github/setup@main
24 |       - name: Fix formatting
25 |         run: pnpm prettier --ignore-unknown . --check
26 |       - name: Apply fixes
27 |         uses: autofix-ci/action@551dded8c6cc8a1054039c8bc0b8b48c51dfc6ef
28 |         with:
29 |           commit-message: "ci: apply automated fixes"
30 | 


--------------------------------------------------------------------------------
/.github/workflows/pr.yml:
--------------------------------------------------------------------------------
 1 | name: PR
 2 | 
 3 | on:
 4 |   pull_request:
 5 | 
 6 | concurrency:
 7 |   group: ${{ github.workflow }}-${{ github.event.number || github.ref }}
 8 |   cancel-in-progress: true
 9 | 
10 | env:
11 |   NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
12 | 
13 | permissions:
14 |   contents: read
15 | 
16 | jobs:
17 |   test:
18 |     name: Test
19 |     runs-on: ubuntu-latest
20 |     steps:
21 |       - name: Checkout
22 |         uses: actions/checkout@v4.2.2
23 |         with:
24 |           fetch-depth: 0
25 |       - name: Setup Tools
26 |         uses: tanstack/config/.github/setup@main
27 |       - name: Get base and head commits for `nx affected`
28 |         uses: nrwl/nx-set-shas@v4.3.0
29 |         with:
30 |           main-branch-name: main
31 |       - name: Run Checks
32 |         run: pnpm run lint && pnpm run build && pnpm run test
33 |   preview:
34 |     name: Preview
35 |     runs-on: ubuntu-latest
36 |     steps:
37 |       - name: Checkout
38 |         uses: actions/checkout@v4.2.2
39 |         with:
40 |           fetch-depth: 0
41 |       - name: Setup Tools
42 |         uses: tanstack/config/.github/setup@main
43 |       - name: Build Packages
44 |         run: pnpm run build
45 |       - name: Publish Previews
46 |         run: pnpx pkg-pr-new publish --pnpm --compact './packages/*' --template './examples/*/*'
47 | 


--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
 1 | name: Release
 2 | 
 3 | on:
 4 |   push:
 5 |     branches: [main, alpha, beta]
 6 | 
 7 | concurrency:
 8 |   group: ${{ github.workflow }}-${{ github.event.number || github.ref }}
 9 |   cancel-in-progress: true
10 | 
11 | env:
12 |   NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
13 | 
14 | permissions:
15 |   contents: write
16 |   id-token: write
17 |   pull-requests: write
18 | 
19 | jobs:
20 |   release:
21 |     name: Release
22 |     if: github.repository_owner == 'TanStack'
23 |     runs-on: ubuntu-latest
24 |     steps:
25 |       - name: Checkout
26 |         uses: actions/checkout@v4.2.2
27 |         with:
28 |           fetch-depth: 0
29 |       - name: Setup Tools
30 |         uses: tanstack/config/.github/setup@main
31 |       - name: Run Tests
32 |         run: pnpm run lint && pnpm run build && pnpm run test
33 |       - name: Run Changesets (version or publish)
34 |         uses: changesets/action@v1.4.9
35 |         with:
36 |           version: pnpm run changeset:version
37 |           publish: pnpm run changeset:publish
38 |           commit: "ci: Version Packages"
39 |           title: "ci: Version Packages"
40 |         env:
41 |           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
42 |           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
43 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
  1 | # Logs
  2 | logs
  3 | *.log
  4 | npm-debug.log*
  5 | yarn-debug.log*
  6 | yarn-error.log*
  7 | lerna-debug.log*
  8 | .pnpm-debug.log*
  9 | 
 10 | # Diagnostic reports (https://nodejs.org/api/report.html)
 11 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 12 | 
 13 | # Runtime data
 14 | pids
 15 | *.pid
 16 | *.seed
 17 | *.pid.lock
 18 | 
 19 | # Directory for instrumented libs generated by jscoverage/JSCover
 20 | lib-cov
 21 | 
 22 | # Coverage directory used by tools like istanbul
 23 | coverage
 24 | *.lcov
 25 | 
 26 | # nyc test coverage
 27 | .nyc_output
 28 | 
 29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
 30 | .grunt
 31 | 
 32 | # Bower dependency directory (https://bower.io/)
 33 | bower_components
 34 | 
 35 | # node-waf configuration
 36 | .lock-wscript
 37 | 
 38 | # Compiled binary addons (https://nodejs.org/api/addons.html)
 39 | build/Release
 40 | 
 41 | # Dependency directories
 42 | node_modules/
 43 | jspm_packages/
 44 | 
 45 | # Snowpack dependency directory (https://snowpack.dev/)
 46 | web_modules/
 47 | 
 48 | # TypeScript cache
 49 | *.tsbuildinfo
 50 | 
 51 | # Optional npm cache directory
 52 | .npm
 53 | 
 54 | # Optional eslint cache
 55 | .eslintcache
 56 | 
 57 | # Optional stylelint cache
 58 | .stylelintcache
 59 | 
 60 | # Microbundle cache
 61 | .rpt2_cache/
 62 | .rts2_cache_cjs/
 63 | .rts2_cache_es/
 64 | .rts2_cache_umd/
 65 | 
 66 | # Optional REPL history
 67 | .node_repl_history
 68 | 
 69 | # Output of 'npm pack'
 70 | *.tgz
 71 | 
 72 | # Yarn Integrity file
 73 | .yarn-integrity
 74 | 
 75 | # dotenv environment variable files
 76 | .env
 77 | .env.development.local
 78 | .env.test.local
 79 | .env.production.local
 80 | .env.local
 81 | 
 82 | # parcel-bundler cache (https://parceljs.org/)
 83 | .cache
 84 | .parcel-cache
 85 | 
 86 | # Next.js build output
 87 | .next
 88 | out
 89 | 
 90 | # Nuxt.js build / generate output
 91 | .nuxt
 92 | dist
 93 | 
 94 | # Gatsby files
 95 | .cache/
 96 | # Comment in the public line in if your project uses Gatsby and not Next.js
 97 | # https://nextjs.org/blog/next-9-1#public-directory-support
 98 | # public
 99 | 
100 | # vuepress build output
101 | .vuepress/dist
102 | 
103 | # vuepress v2.x temp and cache directory
104 | .temp
105 | .cache
106 | 
107 | # Docusaurus cache and generated files
108 | .docusaurus
109 | 
110 | # Serverless directories
111 | .serverless/
112 | 
113 | # FuseBox cache
114 | .fusebox/
115 | 
116 | # DynamoDB Local files
117 | .dynamodb/
118 | 
119 | # TernJS port file
120 | .tern-port
121 | 
122 | # Stores VSCode versions used for testing VSCode extensions
123 | .vscode-test
124 | 
125 | # yarn v2
126 | .yarn/cache
127 | .yarn/unplugged
128 | .yarn/build-state.yml
129 | .yarn/install-state.gz
130 | .pnp.*
131 | .DS_Store
132 | 


--------------------------------------------------------------------------------
/.husky/pre-commit:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env sh
2 | . "$(dirname -- "$0")/_/husky.sh"
3 | 
4 | pnpm lint-staged
5 | 


--------------------------------------------------------------------------------
/.npmrc:
--------------------------------------------------------------------------------
1 | link-workspace-packages=true
2 | prefer-workspace-packages=true
3 | provenance=true
4 | 


--------------------------------------------------------------------------------
/.nvmrc:
--------------------------------------------------------------------------------
1 | 22.13.1
2 | 


--------------------------------------------------------------------------------
/.prettierignore:
--------------------------------------------------------------------------------
1 | **/.next
2 | **/.nx/cache
3 | **/.svelte-kit
4 | **/coverage
5 | **/dist
6 | **/docs
7 | **/snap
8 | pnpm-lock.yaml
9 | 


--------------------------------------------------------------------------------
/.prettierrc:
--------------------------------------------------------------------------------
1 | {
2 |   "trailingComma": "es5",
3 |   "semi": false,
4 |   "tabWidth": 2
5 | }
6 | 


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


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # TanStack DB
  2 | 
  3 | <!-- ![TanStack DB Header](https://github.com/tanstack/db/raw/main/media/repo-header.png) -->
  4 | 
  5 | **A reactive client store for building super fast apps on sync**
  6 | 
  7 | TanStack DB extends TanStack Query with collections, live queries and optimistic mutations that keep your UI reactive, consistent and blazing fast 🔥
  8 | 
  9 | <p>
 10 |   <a href="https://x.com/intent/post?text=TanStack%20DB&url=https://tanstack.com/db">
 11 |     <img alt="#TanStack" src="https://img.shields.io/twitter/url?color=%2308a0e9&label=%23TanStack&style=social&url=https%3A%2F%2Ftwitter.com%2Fintent%2Ftweet%3Fbutton_hashtag%3DTanStack" /></a>
 12 |   <a href="#status">
 13 |     <img src="https://img.shields.io/badge/status-alpha-orange" alt="Status - Alpha"></a>
 14 |   <a href="https://npmjs.com/package/@tanstack/db">
 15 |     <img alt="" src="https://img.shields.io/npm/dm/@tanstack/db.svg" /></a>
 16 |   <a href="https://discord.gg/yjUNbvbraC">
 17 |     <img alt="" src="https://img.shields.io/badge/Discord-TanStack-%235865F2" /></a>
 18 |   <a href="https://github.com/tanstack/db/discussions">
 19 |     <img alt="Join the discussion on Github" src="https://img.shields.io/badge/Discussions-Chat%20now!-green" /></a>
 20 |   <a href="https://x.com/tan_stack">
 21 |     <img alt="" src="https://img.shields.io/twitter/follow/tan_stack.svg?style=social&label=Follow @TanStack" /></a>
 22 | </p>
 23 | 
 24 | Enjoy this library? Try the entire [TanStack](https://tanstack.com), including [TanStack Query](https://tanstack.com/query), [TanStack Store](https://tanstack.com/store), etc.
 25 | 
 26 | ## 🚀 Why TanStack DB?
 27 | 
 28 | TanStack DB gives you robust support for real-time sync, live queries and local writes. With no stale data, super fast re-rendering and sub-millisecond cross-collection queries — even for large complex apps.
 29 | 
 30 | Built on a TypeScript implementation of differential dataflow ([#](https://github.com/electric-sql/d2ts)), TanStack DB gives you:
 31 | 
 32 | - 🔥 **a blazing fast query engine**<br />
 33 |   for sub-millisecond live queries &mdash; even for complex queries with joins and aggregates
 34 | - 🎯 **fine-grained reactivity**<br />
 35 |   to minimize component re-rendering
 36 | - 💪 **robust transaction primitives**<br />
 37 |   for easy optimistic mutations with sync and lifecycle support
 38 | - 🌟 **normalized data**<br />
 39 |   to keep your backend simple
 40 | 
 41 | TanStack DB is **backend agnostic** and **incrementally adoptable**:
 42 | 
 43 | - plug in any backend: sync engines, REST APIs, GraphQL, polling, custom sources
 44 | - builds on [TanStack Store](https://tanstack.com/store), works with and alongside [TanStack Query](https://tanstack.com/query)
 45 | 
 46 | ## 💥 Usage example
 47 | 
 48 | Sync data into collections:
 49 | 
 50 | ```ts
 51 | import { createQueryCollection } from "@tanstack/db-collections"
 52 | 
 53 | const todoCollection = createQueryCollection<Todo>({
 54 |   queryKey: ["todos"],
 55 |   queryFn: async () => fetch("/api/todos"),
 56 |   getId: (item) => item.id,
 57 |   schema: todoSchema, // any standard schema
 58 | })
 59 | ```
 60 | 
 61 | Use live queries in your components:
 62 | 
 63 | ```tsx
 64 | import { useLiveQuery } from "@tanstack/react-db"
 65 | 
 66 | const Todos = () => {
 67 |   const { data: todos } = useLiveQuery((query) =>
 68 |     query.from({ todoCollection }).where("@completed", "=", false)
 69 |   )
 70 | 
 71 |   return <List items={todos} />
 72 | }
 73 | ```
 74 | 
 75 | Apply transactional writes with local optimistic state:
 76 | 
 77 | ```tsx
 78 | import { useOptimisticMutation } from "@tanstack/react-db"
 79 | 
 80 | const AddTodo = () => {
 81 |   const addTodo = useOptimisticMutation({
 82 |     mutationFn: async ({ transaction }) => {
 83 |       const { collection, modified: newTodo } = transaction.mutations[0]!
 84 | 
 85 |       await api.todos.create(newTodo)
 86 |       await collection.refetch()
 87 |     },
 88 |   })
 89 | 
 90 |   return (
 91 |     <Button
 92 |       onClick={() =>
 93 |         addTodo.mutate(() =>
 94 |           todoCollection.insert({
 95 |             id: uuid(),
 96 |             text: "🔥 Make app faster",
 97 |             completed: false,
 98 |           })
 99 |         )
100 |       }
101 |     />
102 |   )
103 | }
104 | ```
105 | 
106 | ## 📚 Docs
107 | 
108 | See the [Usage guide](./docs/index.md) for more details, including how to do:
109 | 
110 | - real-time sync
111 | - cross-collection queries
112 | - fine-grained reactivity
113 | - different strategies for data loading and handling mutations
114 | 
115 | There's also an example [React todo app](./examples/react/todo) and usage examples in the [package tests](./packages/db/tests).
116 | 
117 | ## 🧱 Core concepts
118 | 
119 | ### Collections
120 | 
121 | - typed sets of objects that can mirror a backend table or be populated with a filtered view or result set, such as `pendingTodos` or `decemberNewTodos`
122 | - collections are just JavaScript data &mdash; load them on demand and define as many as you need
123 | 
124 | ### Live queries
125 | 
126 | - run reactively against and across collections with support for joins, filters and aggregates
127 | - powered by differential dataflow: query results update incrementally, not by re-running the whole query
128 | 
129 | ### Transactional mutators
130 | 
131 | - batch and stage local changes across collections with immediate application of local optimistic updates
132 | - sync transactions to the backend with automatic rollbacks and management of optimistic state
133 | 
134 | ## 🔧 Install
135 | 
136 | ```bash
137 | npm install @tanstack/react-db @tanstack/db-collections
138 | ```
139 | 
140 | Other framework integrations are in progress.
141 | 
142 | ## ❓ FAQ
143 | 
144 | **How is this different from TanStack Query?**<br />
145 | TanStack DB builds _on top of_ TanStack Query. Use Query to fetch data; use DB to manage reactive local collections and mutations. They complement each other.
146 | 
147 | **Do I need a sync engine like ElectricSQL?**<br />
148 | No. TanStack DB _is_ designed to work with sync engines like [Electric](https://electric-sql.com) but _also_ works with any backend: polling APIs, GraphQL, REST, or custom sync logic.
149 | 
150 | **What is a Collection? Is it like a DB table?**<br />
151 | Kind of. Collections are typed sets of objects, but they can also be filtered views or custom groupings. They're just JavaScript structures that you define and manage.
152 | 
153 | **Is this an ORM? Do queries hit my backend?**<br />
154 | No. TanStack DB is not an ORM. Queries run entirely in the client against local collections. The framework provides strong primitives to manage how data is loaded and synced.
155 | 
156 | ## Partners
157 | 
158 | <a href="https://electric-sql.com">
159 |   <img alt="ElectricSQL logo"
160 |       src="https://raw.githubusercontent.com/electric-sql/meta/main/identity/ElectricSQL-logo.with-background.sm.png"
161 |   />
162 | </a>
163 | 
164 | ## Status
165 | 
166 | Tanstack DB is currently an early preview release in alpha. It's still under active development. There will be bugs and the APIs are still liable to change.
167 | 
168 | ## Contributing
169 | 
170 | View the contributing guidelines [here](https://github.com/TanStack/query/blob/main/CONTRIBUTING.md).
171 | 
172 | ### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
173 | 
174 | <!-- Use the force, Luke -->
175 | 


--------------------------------------------------------------------------------
/docs/config.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "$schema": "https://raw.githubusercontent.com/TanStack/tanstack.com/main/tanstack-docs-config.schema.json",
 3 |   "docSearch": {
 4 |     "appId": "",
 5 |     "apiKey": "",
 6 |     "indexName": "tanstack-db"
 7 |   },
 8 |   "sections": [
 9 |     {
10 |       "label": "Getting Started",
11 |       "children": [
12 |         {
13 |           "label": "Overview",
14 |           "to": "overview"
15 |         },
16 |         {
17 |           "label": "Quick Start",
18 |           "to": "quick-start"
19 |         },
20 |         {
21 |           "label": "Installation",
22 |           "to": "installation"
23 |         }
24 |       ],
25 |       "frameworks": [
26 |         {
27 |           "label": "react",
28 |           "children": [
29 |             {
30 |               "label": "React Adapter",
31 |               "to": "framework/react/adapter"
32 |             }
33 |           ]
34 |         },
35 |         {
36 |           "label": "vue",
37 |           "children": [
38 |             {
39 |               "label": "Vue Adapter",
40 |               "to": "framework/vue/adapter"
41 |             }
42 |           ]
43 |         }
44 |       ]
45 |     },
46 |     {
47 |       "label": "Guides",
48 |       "children": [
49 |         
50 |       ]
51 |     },
52 |     {
53 |       "label": "API Reference",
54 |       "children": [
55 |         {
56 |           "label": "Core API Reference",
57 |           "to": "reference/index"
58 |         }
59 |       ],
60 |       "frameworks": [
61 |         {
62 |           "label": "react",
63 |           "children": [
64 |             {
65 |               "label": "React Hooks",
66 |               "to": "framework/react/reference/index"
67 |             }
68 |           ]
69 |         },
70 |         {
71 |           "label": "vue",
72 |           "children": [
73 |             {
74 |               "label": "Vue Hooks",
75 |               "to": "framework/vue/reference/index"
76 |             }
77 |           ]
78 |         }
79 |       ]
80 |     },
81 |     {
82 |       "label": "Examples",
83 |       "children": [],
84 |       "frameworks": [
85 |         {
86 |           "label": "react",
87 |           "children": [
88 |             {
89 |               "label": "Todo List",
90 |               "to": "framework/react/examples/todo"
91 |             }
92 |           ]
93 |         }
94 |       ]
95 |     }
96 |   ]
97 | }
98 | 


--------------------------------------------------------------------------------
/docs/framework/react/adapter.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: TanStack DB React Adapter
 3 | id: adapter
 4 | ---
 5 | 
 6 | ## Installation
 7 | 
 8 | ```sh
 9 | npm install @tanstack/react-db
10 | ```
11 | 
12 | ## React Hooks
13 | 
14 | See the [React Functions Reference](../reference/index.md) to see the full list of hooks available in the React Adapter.
15 | 
16 | ## Basic Usage
17 | 
18 | 


--------------------------------------------------------------------------------
/docs/framework/solid/adapter.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: TanStack DB Solid Adapter
3 | ref: docs/framework/react/adapter.md
4 | replace: {
5 |   "React": "Solid",
6 |   "react": "solid"
7 | }
8 | ---
9 | 


--------------------------------------------------------------------------------
/docs/framework/svelte/adapter.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: TanStack DB Svelte Adapter
3 | ref: docs/framework/react/adapter.md
4 | replace: {
5 |   "React": "Svelte",
6 |   "react": "svelte"
7 | }
8 | ---
9 | 


--------------------------------------------------------------------------------
/docs/framework/vue/adapter.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: TanStack DB Vue Adapter
3 | ref: docs/framework/react/adapter.md
4 | replace: {
5 |   "React": "Vue",
6 |   "react": "vue"
7 | }
8 | ---
9 | 


--------------------------------------------------------------------------------
/docs/installation.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Installation
 3 | id: installation
 4 | ---
 5 | 
 6 | You can install TanStack DB with any [NPM](https://npmjs.com) package manager.
 7 | 
 8 | Only install one of the following packages depending on your use case:
 9 | 
10 | ## React
11 | 
12 | ```sh
13 | npm install @tanstack/react-db
14 | ```
15 | 
16 | TanStack DB is compatible with React v16.8+
17 | 
18 | ## Solid
19 | 
20 | ```sh
21 | npm install @tanstack/solid-db
22 | ```
23 | 
24 | COMING SOON
25 | 
26 | ## Svelte
27 | 
28 | ```sh
29 | npm install @tanstack/svelte-db
30 | ```
31 | 
32 | COMING SOON
33 | 
34 | ## Vue
35 | 
36 | ```sh
37 | npm install @tanstack/vue-db
38 | ```
39 | 
40 | TanStack DB is compatible with Vue v3.3.0+
41 | 
42 | ## Vanilla JS
43 | 
44 | ```sh
45 | npm install @tanstack/db
46 | ```
47 | 
48 | Install the the core `@tanstack/db` package to use with any framework or without a framework. Each framework package up above will also re-export everything from this core package.
49 | 


--------------------------------------------------------------------------------
/docs/quick-start.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Quick Start
3 | id: quick-start
4 | ---
5 | 


--------------------------------------------------------------------------------
/docs/unidirectional-data-flow.lg.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TanStack/db/08bc4e39fa5720b17b1ae09d67b8ac174f56e7d7/docs/unidirectional-data-flow.lg.png


--------------------------------------------------------------------------------
/docs/unidirectional-data-flow.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TanStack/db/08bc4e39fa5720b17b1ae09d67b8ac174f56e7d7/docs/unidirectional-data-flow.png


--------------------------------------------------------------------------------
/eslint.config.mjs:
--------------------------------------------------------------------------------
 1 | import prettierPlugin from "eslint-plugin-prettier"
 2 | import prettierConfig from "eslint-config-prettier"
 3 | import stylisticPlugin from "@stylistic/eslint-plugin"
 4 | import { tanstackConfig } from "@tanstack/config/eslint"
 5 | 
 6 | export default [
 7 |   ...tanstackConfig,
 8 |   { ignores: [`dist/`] },
 9 |   {
10 |     plugins: {
11 |       stylistic: stylisticPlugin,
12 |       prettier: prettierPlugin,
13 |     },
14 |     rules: {
15 |       "prettier/prettier": `error`,
16 |       "stylistic/quotes": [`error`, `backtick`],
17 |       ...prettierConfig.rules,
18 |     },
19 |   },
20 | ]
21 | 


--------------------------------------------------------------------------------
/examples/react/todo/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # examples/react/todo
 2 | 
 3 | ## 0.0.8
 4 | 
 5 | ### Patch Changes
 6 | 
 7 | - Updated dependencies []:
 8 |   - @tanstack/db-collections@0.0.6
 9 |   - @tanstack/react-db@0.0.4
10 | 
11 | ## 0.0.7
12 | 
13 | ### Patch Changes
14 | 
15 | - Updated dependencies [[`0bbf4c4`](https://github.com/TanStack/db/commit/0bbf4c46e01b382a70a437f05dfc09c9ff749a15)]:
16 |   - @tanstack/db-collections@0.0.5
17 | 
18 | ## 0.0.6
19 | 
20 | ### Patch Changes
21 | 
22 | - Updated dependencies [[`2d0fcf1`](https://github.com/TanStack/db/commit/2d0fcf16a61a3fcd6a7220b5501640cc0f67218f)]:
23 |   - @tanstack/db-collections@0.0.4
24 | 
25 | ## 0.0.5
26 | 
27 | ### Patch Changes
28 | 
29 | - Updated dependencies []:
30 |   - @tanstack/db-collections@0.0.3
31 |   - @tanstack/react-db@0.0.3
32 | 
33 | ## 0.0.4
34 | 
35 | ### Patch Changes
36 | 
37 | - Updated dependencies [[`4c82edb`](https://github.com/TanStack/db/commit/4c82edb9547f26c9de44f5bf43d4385c38920672), [`4c82edb`](https://github.com/TanStack/db/commit/4c82edb9547f26c9de44f5bf43d4385c38920672)]:
38 |   - @tanstack/react-db@0.0.2
39 |   - @tanstack/db-collections@0.0.2
40 | 
41 | ## 0.0.3
42 | 
43 | ### Patch Changes
44 | 
45 | - Updated dependencies [[`b42479c`](https://github.com/TanStack/db/commit/b42479cf95f9a820b36e01684b13a9179973f3d8)]:
46 |   - @tanstack/react-db@0.0.3
47 | 
48 | ## 0.0.2
49 | 
50 | ### Patch Changes
51 | 
52 | - Updated dependencies [[`9bb6e89`](https://github.com/TanStack/db/commit/9bb6e8909cebdcd7c03091bfc12dd37f5ab2e1ea)]:
53 |   - @tanstack/react-db@0.0.2
54 | 


--------------------------------------------------------------------------------
/examples/react/todo/README.md:
--------------------------------------------------------------------------------
 1 | # Todo example app
 2 | 
 3 | ## How to run
 4 | 
 5 | - Go to the root of the repository and run:
 6 | 
 7 |   - `pnpm install`
 8 |   - `pnpm build`
 9 | 
10 | - Install packages
11 |   `pnpm install`
12 | 
13 | - Start dev server & Docker containers
14 |   `pnpm dev`
15 | 
16 | - Run db migrations
17 |   `pnpm db:push`
18 | 


--------------------------------------------------------------------------------
/examples/react/todo/docker-compose.yml:
--------------------------------------------------------------------------------
 1 | version: "3.8"
 2 | services:
 3 |   postgres:
 4 |     image: postgres:17-alpine
 5 |     environment:
 6 |       POSTGRES_DB: todo_app
 7 |       POSTGRES_USER: postgres
 8 |       POSTGRES_PASSWORD: postgres
 9 |     ports:
10 |       - "54322:5432"
11 |     volumes:
12 |       - ./postgres.conf:/etc/postgresql/postgresql.conf:ro
13 |     tmpfs:
14 |       - /var/lib/postgresql/data
15 |       - /tmp
16 |     command:
17 |       - postgres
18 |       - -c
19 |       - config_file=/etc/postgresql/postgresql.conf
20 |     healthcheck:
21 |       test: ["CMD-SHELL", "pg_isready -U postgres"]
22 |       interval: 5s
23 |       timeout: 5s
24 |       retries: 5
25 | 
26 |   electric:
27 |     image: electricsql/electric:canary
28 |     environment:
29 |       DATABASE_URL: postgresql://postgres:postgres@postgres:5432/todo_app?sslmode=disable
30 |       ELECTRIC_INSECURE: true
31 |     ports:
32 |       - 3003:3000
33 |     depends_on:
34 |       postgres:
35 |         condition: service_healthy
36 | 
37 | volumes:
38 |   postgres_data:
39 | 


--------------------------------------------------------------------------------
/examples/react/todo/drizzle.config.ts:
--------------------------------------------------------------------------------
 1 | import type { Config } from "drizzle-kit"
 2 | 
 3 | export default {
 4 |   schema: `./src/db/schema.ts`,
 5 |   out: `./drizzle`,
 6 |   dialect: `postgresql`,
 7 |   casing: `snake_case`,
 8 |   dbCredentials: {
 9 |     host: process.env.DB_HOST || `localhost`,
10 |     port: parseInt(process.env.DB_PORT || `54322`),
11 |     user: process.env.DB_USER || `postgres`,
12 |     password: process.env.DB_PASSWORD || `postgres`,
13 |     database: process.env.DB_NAME || `todo_app`,
14 |   },
15 | } satisfies Config
16 | 


--------------------------------------------------------------------------------
/examples/react/todo/drizzle/0000_whole_sprite.sql:
--------------------------------------------------------------------------------
1 | CREATE TABLE "todos" (
2 | 	"id" serial PRIMARY KEY NOT NULL,
3 | 	"text" text NOT NULL,
4 | 	"completed" boolean DEFAULT false NOT NULL,
5 | 	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
6 | 	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
7 | );
8 | 


--------------------------------------------------------------------------------
/examples/react/todo/drizzle/0001_sturdy_titania.sql:
--------------------------------------------------------------------------------
1 | CREATE TABLE "config" (
2 | 	"id" serial PRIMARY KEY NOT NULL,
3 | 	"key" text NOT NULL,
4 | 	"value" text NOT NULL,
5 | 	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
6 | 	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
7 | 	CONSTRAINT "config_key_unique" UNIQUE("key")
8 | );
9 | 


--------------------------------------------------------------------------------
/examples/react/todo/drizzle/0002_update_timestamps_trigger.sql:
--------------------------------------------------------------------------------
 1 | -- Custom SQL migration file, put your code below! --
 2 | 
 3 | -- Create a function to update the updated_at timestamp
 4 | CREATE OR REPLACE FUNCTION update_updated_at_column()
 5 | RETURNS TRIGGER AS $$
 6 | BEGIN
 7 |     NEW.updated_at = NOW();
 8 |     RETURN NEW;
 9 | END;
10 | $$ LANGUAGE plpgsql;
11 | 
12 | -- Create trigger for todos table
13 | DROP TRIGGER IF EXISTS update_todos_updated_at ON "todos";
14 | CREATE TRIGGER update_todos_updated_at
15 | BEFORE UPDATE ON "todos"
16 | FOR EACH ROW
17 | EXECUTE FUNCTION update_updated_at_column();
18 | 
19 | -- Create trigger for config table
20 | DROP TRIGGER IF EXISTS update_config_updated_at ON "config";
21 | CREATE TRIGGER update_config_updated_at
22 | BEFORE UPDATE ON "config"
23 | FOR EACH ROW
24 | EXECUTE FUNCTION update_updated_at_column();
25 | 
26 | -- Insert default config for background color
27 | INSERT INTO "config" ("key", "value")
28 | VALUES ('backgroundColor', '#f5f5f5')
29 | ON CONFLICT ("key") DO NOTHING;


--------------------------------------------------------------------------------
/examples/react/todo/drizzle/meta/0000_snapshot.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "id": "1649b703-2b2d-413c-8185-15390a9d97e7",
 3 |   "prevId": "00000000-0000-0000-0000-000000000000",
 4 |   "version": "7",
 5 |   "dialect": "postgresql",
 6 |   "tables": {
 7 |     "public.todos": {
 8 |       "name": "todos",
 9 |       "schema": "",
10 |       "columns": {
11 |         "id": {
12 |           "name": "id",
13 |           "type": "serial",
14 |           "primaryKey": true,
15 |           "notNull": true
16 |         },
17 |         "text": {
18 |           "name": "text",
19 |           "type": "text",
20 |           "primaryKey": false,
21 |           "notNull": true
22 |         },
23 |         "completed": {
24 |           "name": "completed",
25 |           "type": "boolean",
26 |           "primaryKey": false,
27 |           "notNull": true,
28 |           "default": false
29 |         },
30 |         "created_at": {
31 |           "name": "created_at",
32 |           "type": "timestamp with time zone",
33 |           "primaryKey": false,
34 |           "notNull": true,
35 |           "default": "now()"
36 |         },
37 |         "updated_at": {
38 |           "name": "updated_at",
39 |           "type": "timestamp with time zone",
40 |           "primaryKey": false,
41 |           "notNull": true,
42 |           "default": "now()"
43 |         }
44 |       },
45 |       "indexes": {},
46 |       "foreignKeys": {},
47 |       "compositePrimaryKeys": {},
48 |       "uniqueConstraints": {},
49 |       "policies": {},
50 |       "checkConstraints": {},
51 |       "isRLSEnabled": false
52 |     }
53 |   },
54 |   "enums": {},
55 |   "schemas": {},
56 |   "sequences": {},
57 |   "roles": {},
58 |   "policies": {},
59 |   "views": {},
60 |   "_meta": {
61 |     "columns": {},
62 |     "schemas": {},
63 |     "tables": {}
64 |   }
65 | }
66 | 


--------------------------------------------------------------------------------
/examples/react/todo/drizzle/meta/0001_snapshot.json:
--------------------------------------------------------------------------------
  1 | {
  2 |   "id": "1b3a815a-1865-451b-b646-983e995ee97e",
  3 |   "prevId": "1649b703-2b2d-413c-8185-15390a9d97e7",
  4 |   "version": "7",
  5 |   "dialect": "postgresql",
  6 |   "tables": {
  7 |     "public.config": {
  8 |       "name": "config",
  9 |       "schema": "",
 10 |       "columns": {
 11 |         "id": {
 12 |           "name": "id",
 13 |           "type": "serial",
 14 |           "primaryKey": true,
 15 |           "notNull": true
 16 |         },
 17 |         "key": {
 18 |           "name": "key",
 19 |           "type": "text",
 20 |           "primaryKey": false,
 21 |           "notNull": true
 22 |         },
 23 |         "value": {
 24 |           "name": "value",
 25 |           "type": "text",
 26 |           "primaryKey": false,
 27 |           "notNull": true
 28 |         },
 29 |         "created_at": {
 30 |           "name": "created_at",
 31 |           "type": "timestamp with time zone",
 32 |           "primaryKey": false,
 33 |           "notNull": true,
 34 |           "default": "now()"
 35 |         },
 36 |         "updated_at": {
 37 |           "name": "updated_at",
 38 |           "type": "timestamp with time zone",
 39 |           "primaryKey": false,
 40 |           "notNull": true,
 41 |           "default": "now()"
 42 |         }
 43 |       },
 44 |       "indexes": {},
 45 |       "foreignKeys": {},
 46 |       "compositePrimaryKeys": {},
 47 |       "uniqueConstraints": {
 48 |         "config_key_unique": {
 49 |           "name": "config_key_unique",
 50 |           "nullsNotDistinct": false,
 51 |           "columns": ["key"]
 52 |         }
 53 |       },
 54 |       "policies": {},
 55 |       "checkConstraints": {},
 56 |       "isRLSEnabled": false
 57 |     },
 58 |     "public.todos": {
 59 |       "name": "todos",
 60 |       "schema": "",
 61 |       "columns": {
 62 |         "id": {
 63 |           "name": "id",
 64 |           "type": "serial",
 65 |           "primaryKey": true,
 66 |           "notNull": true
 67 |         },
 68 |         "text": {
 69 |           "name": "text",
 70 |           "type": "text",
 71 |           "primaryKey": false,
 72 |           "notNull": true
 73 |         },
 74 |         "completed": {
 75 |           "name": "completed",
 76 |           "type": "boolean",
 77 |           "primaryKey": false,
 78 |           "notNull": true,
 79 |           "default": false
 80 |         },
 81 |         "created_at": {
 82 |           "name": "created_at",
 83 |           "type": "timestamp with time zone",
 84 |           "primaryKey": false,
 85 |           "notNull": true,
 86 |           "default": "now()"
 87 |         },
 88 |         "updated_at": {
 89 |           "name": "updated_at",
 90 |           "type": "timestamp with time zone",
 91 |           "primaryKey": false,
 92 |           "notNull": true,
 93 |           "default": "now()"
 94 |         }
 95 |       },
 96 |       "indexes": {},
 97 |       "foreignKeys": {},
 98 |       "compositePrimaryKeys": {},
 99 |       "uniqueConstraints": {},
100 |       "policies": {},
101 |       "checkConstraints": {},
102 |       "isRLSEnabled": false
103 |     }
104 |   },
105 |   "enums": {},
106 |   "schemas": {},
107 |   "sequences": {},
108 |   "roles": {},
109 |   "policies": {},
110 |   "views": {},
111 |   "_meta": {
112 |     "columns": {},
113 |     "schemas": {},
114 |     "tables": {}
115 |   }
116 | }
117 | 


--------------------------------------------------------------------------------
/examples/react/todo/drizzle/meta/0002_snapshot.json:
--------------------------------------------------------------------------------
  1 | {
  2 |   "id": "017c3a1c-9d70-4fed-ad07-9a2e1ab49bb4",
  3 |   "prevId": "1b3a815a-1865-451b-b646-983e995ee97e",
  4 |   "version": "7",
  5 |   "dialect": "postgresql",
  6 |   "tables": {
  7 |     "public.config": {
  8 |       "name": "config",
  9 |       "schema": "",
 10 |       "columns": {
 11 |         "id": {
 12 |           "name": "id",
 13 |           "type": "serial",
 14 |           "primaryKey": true,
 15 |           "notNull": true
 16 |         },
 17 |         "key": {
 18 |           "name": "key",
 19 |           "type": "text",
 20 |           "primaryKey": false,
 21 |           "notNull": true
 22 |         },
 23 |         "value": {
 24 |           "name": "value",
 25 |           "type": "text",
 26 |           "primaryKey": false,
 27 |           "notNull": true
 28 |         },
 29 |         "created_at": {
 30 |           "name": "created_at",
 31 |           "type": "timestamp with time zone",
 32 |           "primaryKey": false,
 33 |           "notNull": true,
 34 |           "default": "now()"
 35 |         },
 36 |         "updated_at": {
 37 |           "name": "updated_at",
 38 |           "type": "timestamp with time zone",
 39 |           "primaryKey": false,
 40 |           "notNull": true,
 41 |           "default": "now()"
 42 |         }
 43 |       },
 44 |       "indexes": {},
 45 |       "foreignKeys": {},
 46 |       "compositePrimaryKeys": {},
 47 |       "uniqueConstraints": {
 48 |         "config_key_unique": {
 49 |           "name": "config_key_unique",
 50 |           "columns": ["key"],
 51 |           "nullsNotDistinct": false
 52 |         }
 53 |       },
 54 |       "policies": {},
 55 |       "checkConstraints": {},
 56 |       "isRLSEnabled": false
 57 |     },
 58 |     "public.todos": {
 59 |       "name": "todos",
 60 |       "schema": "",
 61 |       "columns": {
 62 |         "id": {
 63 |           "name": "id",
 64 |           "type": "serial",
 65 |           "primaryKey": true,
 66 |           "notNull": true
 67 |         },
 68 |         "text": {
 69 |           "name": "text",
 70 |           "type": "text",
 71 |           "primaryKey": false,
 72 |           "notNull": true
 73 |         },
 74 |         "completed": {
 75 |           "name": "completed",
 76 |           "type": "boolean",
 77 |           "primaryKey": false,
 78 |           "notNull": true,
 79 |           "default": false
 80 |         },
 81 |         "created_at": {
 82 |           "name": "created_at",
 83 |           "type": "timestamp with time zone",
 84 |           "primaryKey": false,
 85 |           "notNull": true,
 86 |           "default": "now()"
 87 |         },
 88 |         "updated_at": {
 89 |           "name": "updated_at",
 90 |           "type": "timestamp with time zone",
 91 |           "primaryKey": false,
 92 |           "notNull": true,
 93 |           "default": "now()"
 94 |         }
 95 |       },
 96 |       "indexes": {},
 97 |       "foreignKeys": {},
 98 |       "compositePrimaryKeys": {},
 99 |       "uniqueConstraints": {},
100 |       "policies": {},
101 |       "checkConstraints": {},
102 |       "isRLSEnabled": false
103 |     }
104 |   },
105 |   "enums": {},
106 |   "schemas": {},
107 |   "views": {},
108 |   "sequences": {},
109 |   "roles": {},
110 |   "policies": {},
111 |   "_meta": {
112 |     "columns": {},
113 |     "schemas": {},
114 |     "tables": {}
115 |   }
116 | }
117 | 


--------------------------------------------------------------------------------
/examples/react/todo/drizzle/meta/_journal.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "version": "7",
 3 |   "dialect": "postgresql",
 4 |   "entries": [
 5 |     {
 6 |       "idx": 0,
 7 |       "version": "7",
 8 |       "when": 1740502196428,
 9 |       "tag": "0000_whole_sprite",
10 |       "breakpoints": true
11 |     },
12 |     {
13 |       "idx": 1,
14 |       "version": "7",
15 |       "when": 1740601351239,
16 |       "tag": "0001_sturdy_titania",
17 |       "breakpoints": true
18 |     },
19 |     {
20 |       "idx": 2,
21 |       "version": "7",
22 |       "when": 1740606615508,
23 |       "tag": "0002_update_timestamps_trigger",
24 |       "breakpoints": true
25 |     }
26 |   ]
27 | }
28 | 


--------------------------------------------------------------------------------
/examples/react/todo/index.html:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html lang="en">
 3 |   <head>
 4 |     <meta charset="UTF-8" />
 5 |     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
 6 |     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 7 |     <link href="/src/styles.css" rel="stylesheet" />
 8 |     <title>TODO App</title>
 9 |   </head>
10 |   <body>
11 |     <div id="root"></div>
12 |     <script type="module" src="/src/main.tsx"></script>
13 |   </body>
14 | </html>
15 | 


--------------------------------------------------------------------------------
/examples/react/todo/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@tanstack/db-example-react-todo",
 3 |   "private": true,
 4 |   "version": "0.0.8",
 5 |   "dependencies": {
 6 |     "@tanstack/db-collections": "^0.0.6",
 7 |     "@tanstack/query-core": "^5.75.7",
 8 |     "@tanstack/react-db": "^0.0.4",
 9 |     "cors": "^2.8.5",
10 |     "drizzle-orm": "^0.40.1",
11 |     "drizzle-zod": "^0.7.0",
12 |     "express": "^4.19.2",
13 |     "postgres": "^3.4.5",
14 |     "react": "^19.0.0",
15 |     "react-dom": "^19.0.0",
16 |     "tailwindcss": "^4.0.17",
17 |     "zod": "^3.24.2"
18 |   },
19 |   "devDependencies": {
20 |     "@eslint/js": "^9.22.0",
21 |     "@tailwindcss/vite": "^4.0.0-alpha.8",
22 |     "@types/cors": "^2.8.17",
23 |     "@types/express": "^4.17.21",
24 |     "@types/node": "^22.13.10",
25 |     "@types/pg": "^8.11.11",
26 |     "@types/react": "^19.0.12",
27 |     "@types/react-dom": "^19.0.0",
28 |     "@typescript-eslint/eslint-plugin": "^8.26.1",
29 |     "@typescript-eslint/parser": "^8.26.1",
30 |     "@vitejs/plugin-react": "^4.3.4",
31 |     "concurrently": "^9.1.2",
32 |     "dotenv": "^16.3.1",
33 |     "drizzle-kit": "^0.30.5",
34 |     "eslint": "^9.22.0",
35 |     "eslint-plugin-react-hooks": "^5.2.0",
36 |     "eslint-plugin-react-refresh": "^0.4.5",
37 |     "pg": "^8.14.1",
38 |     "tsx": "^4.6.2",
39 |     "typescript": "^5.8.2",
40 |     "vite": "^6.2.2"
41 |   },
42 |   "scripts": {
43 |     "api:dev": "tsx watch src/api/server.ts",
44 |     "build": "tsc -b && vite build",
45 |     "db:ensure-config": "tsx scripts/ensure-default-config.ts",
46 |     "db:generate": "drizzle-kit generate",
47 |     "db:push": "tsx scripts/migrate.ts",
48 |     "db:studio": "drizzle-kit studio",
49 |     "dev": "docker compose up -d && concurrently \"pnpm api:dev\" \"vite\"",
50 |     "lint": "eslint . --fix",
51 |     "preview": "vite preview"
52 |   },
53 |   "type": "module"
54 | }
55 | 


--------------------------------------------------------------------------------
/examples/react/todo/postgres.conf:
--------------------------------------------------------------------------------
 1 | listen_addresses = '*'
 2 | max_connections = 100
 3 | shared_buffers = 128MB
 4 | dynamic_shared_memory_type = posix
 5 | max_wal_size = 1GB
 6 | min_wal_size = 80MB
 7 | log_timezone = 'UTC'
 8 | datestyle = 'iso, mdy'
 9 | timezone = 'UTC'
10 | lc_messages = 'en_US.utf8'
11 | lc_monetary = 'en_US.utf8'
12 | lc_numeric = 'en_US.utf8'
13 | lc_time = 'en_US.utf8'
14 | default_text_search_config = 'pg_catalog.english'
15 | wal_level = logical
16 | max_replication_slots = 10
17 | max_wal_senders = 10
18 | 


--------------------------------------------------------------------------------
/examples/react/todo/public/vite.svg:
--------------------------------------------------------------------------------
1 | <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>


--------------------------------------------------------------------------------
/examples/react/todo/scripts/migrate.ts:
--------------------------------------------------------------------------------
 1 | import { drizzle } from "drizzle-orm/node-postgres"
 2 | import { migrate } from "drizzle-orm/node-postgres/migrator"
 3 | import pkg from "pg"
 4 | import * as dotenv from "dotenv"
 5 | 
 6 | dotenv.config()
 7 | 
 8 | const { Pool } = pkg
 9 | const pool = new Pool({
10 |   host: process.env.DB_HOST || `localhost`,
11 |   port: parseInt(process.env.DB_PORT || `54322`),
12 |   user: process.env.DB_USER || `postgres`,
13 |   password: process.env.DB_PASSWORD || `postgres`,
14 |   database: process.env.DB_NAME || `todo_app`,
15 | })
16 | 
17 | const db = drizzle(pool)
18 | 
19 | async function main() {
20 |   console.log(`Running migrations...`)
21 |   await migrate(db, { migrationsFolder: `./drizzle` })
22 |   console.log(`Migrations completed!`)
23 |   await pool.end()
24 | }
25 | 
26 | main().catch((err) => {
27 |   console.error(`Migration failed!`, err)
28 |   process.exit(1)
29 | })
30 | 


--------------------------------------------------------------------------------
/examples/react/todo/src/DiffView.tsx:
--------------------------------------------------------------------------------
 1 | import React from "react"
 2 | import { diffLines } from "diff"
 3 | 
 4 | interface DiffViewProps {
 5 |   oldValue: unknown
 6 |   newValue: unknown
 7 | }
 8 | 
 9 | export function DiffView({ oldValue, newValue }: DiffViewProps) {
10 |   const diff = diffLines(
11 |     JSON.stringify(oldValue, null, 2),
12 |     JSON.stringify(newValue, null, 2)
13 |   )
14 | 
15 |   return (
16 |     <pre className="text-sm font-mono bg-gray-50 p-2 rounded overflow-auto">
17 |       {diff.map((part, index) => (
18 |         <div
19 |           key={index}
20 |           className={`${
21 |             part.added
22 |               ? `bg-green-50 text-green-800 border-l-4 border-green-500`
23 |               : part.removed
24 |                 ? `bg-red-50 text-red-800 border-l-4 border-red-500`
25 |                 : `text-gray-800`
26 |           } px-2 whitespace-pre`}
27 |         >
28 |           {part.added ? `+ ` : part.removed ? `- ` : `  `}
29 |           {part.value}
30 |         </div>
31 |       ))}
32 |     </pre>
33 |   )
34 | }
35 | 


--------------------------------------------------------------------------------
/examples/react/todo/src/api/write-to-pg.ts:
--------------------------------------------------------------------------------
  1 | import type postgres from "postgres"
  2 | import type { PendingMutation } from "../types"
  3 | 
  4 | /**
  5 |  * Get the table name from the relation metadata
  6 |  */
  7 | function getTableName(relation?: Array<string>): string {
  8 |   if (!relation || relation.length < 2) {
  9 |     throw new Error(`could not find the table name`)
 10 |   }
 11 | 
 12 |   // The table name is typically the second element in the relation array
 13 |   // e.g. ['public', 'todos'] -> 'todos'
 14 |   return relation[1]
 15 | }
 16 | 
 17 | /**
 18 |  * Process an array of PendingMutations and write to the database
 19 |  */
 20 | export async function processMutations(
 21 |   sql: postgres.Sql<Record<string, unknown>>,
 22 |   pendingMutations: Array<PendingMutation>
 23 | ): Promise<number> {
 24 |   return await sql.begin(async (tx) => {
 25 |     // Get the transaction ID
 26 |     const [{ txid }] = await tx`SELECT txid_current() as txid`
 27 | 
 28 |     // Process each mutation in order
 29 |     for (const mutation of pendingMutations) {
 30 |       // Get the table name from the relation metadata
 31 |       const tableName = getTableName(
 32 |         mutation.syncMetadata.relation as Array<string> | undefined
 33 |       )
 34 | 
 35 |       // Get the primary key columns from metadata
 36 |       const primaryKey = (mutation.syncMetadata.primaryKey as
 37 |         | Array<string>
 38 |         | undefined) || [`id`]
 39 | 
 40 |       // Process based on operation type
 41 |       switch (mutation.type) {
 42 |         case `insert`: {
 43 |           const columns = Object.keys(mutation.modified)
 44 |           const values = Object.values(mutation.modified)
 45 |           const placeholders = values.map((_, i) => `$${i + 1}`).join(`, `)
 46 | 
 47 |           await tx.unsafe(
 48 |             `INSERT INTO ${tableName} (${columns.join(`, `)}) VALUES (${placeholders})`,
 49 |             values
 50 |           )
 51 |           break
 52 |         }
 53 | 
 54 |         case `update`: {
 55 |           // Build SET clause
 56 |           const setColumns = Object.keys(mutation.changes)
 57 |           const setValues = Object.values(mutation.changes)
 58 |           const setClause = setColumns
 59 |             .map((col, i) => `${col} = $${i + 1}`)
 60 |             .join(`, `)
 61 | 
 62 |           // Build WHERE clause for primary key columns starting after SET values
 63 |           const whereClause = primaryKey
 64 |             .map((column, i) => `${column} = $${i + setValues.length + 1}`)
 65 |             .join(` AND `)
 66 | 
 67 |           // Combine all values
 68 |           const allValues = [
 69 |             ...setValues,
 70 |             ...primaryKey.map((k) => mutation.original[k]),
 71 |           ]
 72 | 
 73 |           await tx.unsafe(
 74 |             `UPDATE ${tableName}
 75 |              SET ${setClause}
 76 |              WHERE ${whereClause}`,
 77 |             allValues
 78 |           )
 79 |           break
 80 |         }
 81 | 
 82 |         case `delete`: {
 83 |           // Build WHERE clause for primary key columns
 84 |           const whereClause = primaryKey
 85 |             .map((column, i) => `${column} = $${i + 1}`)
 86 |             .join(` AND `)
 87 | 
 88 |           // Extract primary key values in same order as columns
 89 |           const primaryKeyValues = primaryKey.map((k) => mutation.original[k])
 90 | 
 91 |           await tx.unsafe(
 92 |             `DELETE FROM ${tableName}
 93 |              WHERE ${whereClause}`,
 94 |             primaryKeyValues
 95 |           )
 96 |           break
 97 |         }
 98 | 
 99 |         default:
100 |           throw new Error(`Unknown operation type: ${mutation.type}`)
101 |       }
102 |     }
103 | 
104 |     return Number(txid)
105 |   })
106 | }
107 | 


--------------------------------------------------------------------------------
/examples/react/todo/src/assets/react.svg:
--------------------------------------------------------------------------------
1 | <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="35.93" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 228"><path fill="#00D8FF" d="M210.483 73.824a171.49 171.49 0 0 0-8.24-2.597c.465-1.9.893-3.777 1.273-5.621c6.238-30.281 2.16-54.676-11.769-62.708c-13.355-7.7-35.196.329-57.254 19.526a171.23 171.23 0 0 0-6.375 5.848a155.866 155.866 0 0 0-4.241-3.917C100.759 3.829 77.587-4.822 63.673 3.233C50.33 10.957 46.379 33.89 51.995 62.588a170.974 170.974 0 0 0 1.892 8.48c-3.28.932-6.445 1.924-9.474 2.98C17.309 83.498 0 98.307 0 113.668c0 15.865 18.582 31.778 46.812 41.427a145.52 145.52 0 0 0 6.921 2.165a167.467 167.467 0 0 0-2.01 9.138c-5.354 28.2-1.173 50.591 12.134 58.266c13.744 7.926 36.812-.22 59.273-19.855a145.567 145.567 0 0 0 5.342-4.923a168.064 168.064 0 0 0 6.92 6.314c21.758 18.722 43.246 26.282 56.54 18.586c13.731-7.949 18.194-32.003 12.4-61.268a145.016 145.016 0 0 0-1.535-6.842c1.62-.48 3.21-.974 4.76-1.488c29.348-9.723 48.443-25.443 48.443-41.52c0-15.417-17.868-30.326-45.517-39.844Zm-6.365 70.984c-1.4.463-2.836.91-4.3 1.345c-3.24-10.257-7.612-21.163-12.963-32.432c5.106-11 9.31-21.767 12.459-31.957c2.619.758 5.16 1.557 7.61 2.4c23.69 8.156 38.14 20.213 38.14 29.504c0 9.896-15.606 22.743-40.946 31.14Zm-10.514 20.834c2.562 12.94 2.927 24.64 1.23 33.787c-1.524 8.219-4.59 13.698-8.382 15.893c-8.067 4.67-25.32-1.4-43.927-17.412a156.726 156.726 0 0 1-6.437-5.87c7.214-7.889 14.423-17.06 21.459-27.246c12.376-1.098 24.068-2.894 34.671-5.345a134.17 134.17 0 0 1 1.386 6.193ZM87.276 214.515c-7.882 2.783-14.16 2.863-17.955.675c-8.075-4.657-11.432-22.636-6.853-46.752a156.923 156.923 0 0 1 1.869-8.499c10.486 2.32 22.093 3.988 34.498 4.994c7.084 9.967 14.501 19.128 21.976 27.15a134.668 134.668 0 0 1-4.877 4.492c-9.933 8.682-19.886 14.842-28.658 17.94ZM50.35 144.747c-12.483-4.267-22.792-9.812-29.858-15.863c-6.35-5.437-9.555-10.836-9.555-15.216c0-9.322 13.897-21.212 37.076-29.293c2.813-.98 5.757-1.905 8.812-2.773c3.204 10.42 7.406 21.315 12.477 32.332c-5.137 11.18-9.399 22.249-12.634 32.792a134.718 134.718 0 0 1-6.318-1.979Zm12.378-84.26c-4.811-24.587-1.616-43.134 6.425-47.789c8.564-4.958 27.502 2.111 47.463 19.835a144.318 144.318 0 0 1 3.841 3.545c-7.438 7.987-14.787 17.08-21.808 26.988c-12.04 1.116-23.565 2.908-34.161 5.309a160.342 160.342 0 0 1-1.76-7.887Zm110.427 27.268a347.8 347.8 0 0 0-7.785-12.803c8.168 1.033 15.994 2.404 23.343 4.08c-2.206 7.072-4.956 14.465-8.193 22.045a381.151 381.151 0 0 0-7.365-13.322Zm-45.032-43.861c5.044 5.465 10.096 11.566 15.065 18.186a322.04 322.04 0 0 0-30.257-.006c4.974-6.559 10.069-12.652 15.192-18.18ZM82.802 87.83a323.167 323.167 0 0 0-7.227 13.238c-3.184-7.553-5.909-14.98-8.134-22.152c7.304-1.634 15.093-2.97 23.209-3.984a321.524 321.524 0 0 0-7.848 12.897Zm8.081 65.352c-8.385-.936-16.291-2.203-23.593-3.793c2.26-7.3 5.045-14.885 8.298-22.6a321.187 321.187 0 0 0 7.257 13.246c2.594 4.48 5.28 8.868 8.038 13.147Zm37.542 31.03c-5.184-5.592-10.354-11.779-15.403-18.433c4.902.192 9.899.29 14.978.29c5.218 0 10.376-.117 15.453-.343c-4.985 6.774-10.018 12.97-15.028 18.486Zm52.198-57.817c3.422 7.8 6.306 15.345 8.596 22.52c-7.422 1.694-15.436 3.058-23.88 4.071a382.417 382.417 0 0 0 7.859-13.026a347.403 347.403 0 0 0 7.425-13.565Zm-16.898 8.101a358.557 358.557 0 0 1-12.281 19.815a329.4 329.4 0 0 1-23.444.823c-7.967 0-15.716-.248-23.178-.732a310.202 310.202 0 0 1-12.513-19.846h.001a307.41 307.41 0 0 1-10.923-20.627a310.278 310.278 0 0 1 10.89-20.637l-.001.001a307.318 307.318 0 0 1 12.413-19.761c7.613-.576 15.42-.876 23.31-.876H128c7.926 0 15.743.303 23.354.883a329.357 329.357 0 0 1 12.335 19.695a358.489 358.489 0 0 1 11.036 20.54a329.472 329.472 0 0 1-11 20.722Zm22.56-122.124c8.572 4.944 11.906 24.881 6.52 51.026c-.344 1.668-.73 3.367-1.15 5.09c-10.622-2.452-22.155-4.275-34.23-5.408c-7.034-10.017-14.323-19.124-21.64-27.008a160.789 160.789 0 0 1 5.888-5.4c18.9-16.447 36.564-22.941 44.612-18.3ZM128 90.808c12.625 0 22.86 10.235 22.86 22.86s-10.235 22.86-22.86 22.86s-22.86-10.235-22.86-22.86s10.235-22.86 22.86-22.86Z"></path></svg>


--------------------------------------------------------------------------------
/examples/react/todo/src/db/index.ts:
--------------------------------------------------------------------------------
 1 | import { drizzle } from "drizzle-orm/node-postgres"
 2 | import { Pool } from "pg"
 3 | import * as schema from "./schema"
 4 | 
 5 | // Create a PostgreSQL pool
 6 | const pool = new Pool({
 7 |   host: process.env.DB_HOST || `localhost`,
 8 |   port: parseInt(process.env.DB_PORT || `5432`),
 9 |   user: process.env.DB_USER || `postgres`,
10 |   password: process.env.DB_PASSWORD,
11 |   database: process.env.DB_NAME || `todo_app`,
12 | })
13 | 
14 | // Create drizzle database instance
15 | export const db = drizzle(pool, { schema })
16 | 


--------------------------------------------------------------------------------
/examples/react/todo/src/db/postgres.ts:
--------------------------------------------------------------------------------
 1 | import postgres from "postgres"
 2 | 
 3 | // Create a postgres instance
 4 | export const sql = postgres({
 5 |   host: `localhost`,
 6 |   port: 54322,
 7 |   user: `postgres`,
 8 |   password: `postgres`,
 9 |   database: `todo_app`,
10 | })
11 | 


--------------------------------------------------------------------------------
/examples/react/todo/src/db/schema.ts:
--------------------------------------------------------------------------------
 1 | import { boolean, pgTable, serial, text, timestamp } from "drizzle-orm/pg-core"
 2 | 
 3 | export const todos = pgTable(`todos`, {
 4 |   id: serial(`id`).primaryKey(),
 5 |   text: text(`text`).notNull(),
 6 |   completed: boolean(`completed`).notNull().default(false),
 7 |   created_at: timestamp(`created_at`, { withTimezone: true })
 8 |     .defaultNow()
 9 |     .notNull(),
10 |   updated_at: timestamp(`updated_at`, { withTimezone: true })
11 |     .notNull()
12 |     .defaultNow(),
13 | })
14 | 
15 | export type Todo = typeof todos.$inferSelect
16 | export type NewTodo = typeof todos.$inferInsert
17 | 
18 | export const config = pgTable(`config`, {
19 |   id: serial(`id`).primaryKey(),
20 |   key: text(`key`).notNull().unique(),
21 |   value: text(`value`).notNull(),
22 |   created_at: timestamp(`created_at`, { withTimezone: true })
23 |     .notNull()
24 |     .defaultNow(),
25 |   updated_at: timestamp(`updated_at`, { withTimezone: true })
26 |     .notNull()
27 |     .defaultNow(),
28 | })
29 | 
30 | export type Config = typeof config.$inferSelect
31 | export type NewConfig = typeof config.$inferInsert
32 | 


--------------------------------------------------------------------------------
/examples/react/todo/src/db/validation.ts:
--------------------------------------------------------------------------------
 1 | import { createInsertSchema, createSelectSchema } from "drizzle-zod"
 2 | import { config, todos } from "./schema"
 3 | import type { z } from "zod"
 4 | 
 5 | // Auto-generated schemas from Drizzle schema
 6 | export const insertTodoSchema = createInsertSchema(todos)
 7 | export const selectTodoSchema = createSelectSchema(todos)
 8 | 
 9 | // Partial schema for updates
10 | export const updateTodoSchema = insertTodoSchema.partial().strict()
11 | 
12 | // Config schemas
13 | export const insertConfigSchema = createInsertSchema(config).strict()
14 | export const selectConfigSchema = createSelectSchema(config)
15 | export const updateConfigSchema = insertConfigSchema.partial().strict()
16 | 
17 | // Type inference
18 | export type InsertTodo = z.infer<typeof insertTodoSchema>
19 | export type SelectTodo = z.infer<typeof selectTodoSchema>
20 | export type UpdateTodo = z.infer<typeof updateTodoSchema>
21 | 
22 | export type InsertConfig = z.infer<typeof insertConfigSchema>
23 | export type SelectConfig = z.infer<typeof selectConfigSchema>
24 | export type UpdateConfig = z.infer<typeof updateConfigSchema>
25 | 
26 | // Validation functions
27 | export const validateInsertTodo = (data: unknown): InsertTodo => {
28 |   if (data.text === `really hard todo`) {
29 |     throw new Error(`we don't want to do really hard todos`)
30 |   }
31 |   return insertTodoSchema.parse(data)
32 | }
33 | 
34 | export const validateSelectTodo = (data: unknown): SelectTodo => {
35 |   return selectTodoSchema.parse(data)
36 | }
37 | 
38 | export const validateUpdateTodo = (data: unknown): UpdateTodo => {
39 |   return updateTodoSchema.parse(data)
40 | }
41 | 
42 | export const validateInsertConfig = (data: unknown): InsertConfig => {
43 |   return insertConfigSchema.parse(data)
44 | }
45 | 
46 | export const validateSelectConfig = (data: unknown): SelectConfig => {
47 |   return selectConfigSchema.parse(data)
48 | }
49 | 
50 | export const validateUpdateConfig = (data: unknown): UpdateConfig => {
51 |   return updateConfigSchema.parse(data)
52 | }
53 | 
54 | // Safe parsing functions that return Result type instead of throwing
55 | export const safeParseInsertTodo = (data: unknown) => {
56 |   return insertTodoSchema.safeParse(data)
57 | }
58 | 
59 | export const safeParseSelectTodo = (data: unknown) => {
60 |   return selectTodoSchema.safeParse(data)
61 | }
62 | 
63 | export const safeParseUpdateTodo = (data: unknown) => {
64 |   return updateTodoSchema.safeParse(data)
65 | }
66 | 
67 | export const safeParseInsertConfig = (data: unknown) => {
68 |   return insertConfigSchema.safeParse(data)
69 | }
70 | 
71 | export const safeParseSelectConfig = (data: unknown) => {
72 |   return selectConfigSchema.safeParse(data)
73 | }
74 | 
75 | export const safeParseUpdateConfig = (data: unknown) => {
76 |   return updateConfigSchema.safeParse(data)
77 | }
78 | 


--------------------------------------------------------------------------------
/examples/react/todo/src/index.css:
--------------------------------------------------------------------------------
 1 | @import "tailwindcss";
 2 | 
 3 | html,
 4 | body {
 5 |   margin: 0;
 6 |   padding: 0;
 7 | }
 8 | 
 9 | button {
10 |   margin: 0;
11 |   padding: 0;
12 |   border: 0;
13 |   background: none;
14 |   font-size: 100%;
15 |   vertical-align: baseline;
16 |   font-family: inherit;
17 |   font-weight: inherit;
18 |   color: inherit;
19 |   appearance: none;
20 | }
21 | 
22 | body {
23 |   font:
24 |     14px "Helvetica Neue",
25 |     Helvetica,
26 |     Arial,
27 |     sans-serif;
28 |   line-height: 1.4em;
29 |   background: #f5f5f5;
30 |   color: #4d4d4d;
31 |   margin: 0 auto;
32 |   -webkit-font-smoothing: antialiased;
33 |   -moz-osx-font-smoothing: grayscale;
34 |   font-weight: 300;
35 | }
36 | 
37 | :root {
38 |   font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
39 |   line-height: 1.5;
40 |   font-weight: 400;
41 | 
42 |   color-scheme: light dark;
43 |   color: rgba(255, 255, 255, 0.87);
44 |   background-color: #242424;
45 | 
46 |   font-synthesis: none;
47 |   text-rendering: optimizeLegibility;
48 | }
49 | 
50 | a {
51 |   font-weight: 500;
52 |   color: #646cff;
53 |   text-decoration: inherit;
54 | }
55 | a:hover {
56 |   color: #535bf2;
57 | }
58 | 
59 | h1 {
60 |   font-size: 3.2em;
61 |   line-height: 1.1;
62 | }
63 | 
64 | button {
65 |   border-radius: 8px;
66 |   border: 1px solid transparent;
67 |   padding: 0.6em 1.2em;
68 |   font-size: 1em;
69 |   font-weight: 500;
70 |   font-family: inherit;
71 |   background-color: #1a1a1a;
72 |   cursor: pointer;
73 |   transition: border-color 0.25s;
74 | }
75 | button:hover {
76 |   border-color: #646cff;
77 | }
78 | button:focus,
79 | button:focus-visible {
80 |   outline: 4px auto -webkit-focus-ring-color;
81 | }
82 | 
83 | @media (prefers-color-scheme: light) {
84 |   :root {
85 |     color: #213547;
86 |     background-color: #ffffff;
87 |   }
88 |   a:hover {
89 |     color: #747bff;
90 |   }
91 |   button {
92 |     background-color: #f9f9f9;
93 |   }
94 | }
95 | 


--------------------------------------------------------------------------------
/examples/react/todo/src/main.tsx:
--------------------------------------------------------------------------------
 1 | import React from "react"
 2 | import { createRoot } from "react-dom/client"
 3 | import "./index.css"
 4 | import App from "./App.tsx"
 5 | 
 6 | createRoot(document.getElementById(`root`)!).render(
 7 |   <React.StrictMode>
 8 |     <App />
 9 |   </React.StrictMode>
10 | )
11 | 


--------------------------------------------------------------------------------
/examples/react/todo/src/vite-env.d.ts:
--------------------------------------------------------------------------------
1 | /// <reference types="vite/client" />
2 | 


--------------------------------------------------------------------------------
/examples/react/todo/vite.config.ts:
--------------------------------------------------------------------------------
1 | import { defineConfig } from "vite"
2 | import react from "@vitejs/plugin-react"
3 | import tailwindcss from "@tailwindcss/vite"
4 | 
5 | // https://vitejs.dev/config/
6 | export default defineConfig({
7 |   plugins: [react(), tailwindcss()],
8 | })
9 | 


--------------------------------------------------------------------------------
/media/repo-header.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TanStack/db/08bc4e39fa5720b17b1ae09d67b8ac174f56e7d7/media/repo-header.jpg


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@tanstack/db-monorepo",
 3 |   "private": true,
 4 |   "description": "Optimistic UI library for sync engines",
 5 |   "version": "0.0.0",
 6 |   "repository": {
 7 |     "type": "git",
 8 |     "url": "https://github.com/tanstack/db.git"
 9 |   },
10 |   "author": "Kyle Mathews <mathews.kyle@gmail.com>",
11 |   "packageManager": "pnpm@10.6.3",
12 |   "type": "module",
13 |   "keywords": [],
14 |   "license": "MIT",
15 |   "scripts": {
16 |     "build": "pnpm --filter \"./packages/**\" build",
17 |     "changeset": "changeset",
18 |     "changeset:publish": "changeset publish",
19 |     "changeset:version": "changeset version && pnpm install --no-frozen-lockfile",
20 |     "lint": "pnpm --filter \"./packages/**\" lint",
21 |     "lint-all": "eslint . --fix",
22 |     "prepack": "vite build",
23 |     "prepare": "husky",
24 |     "test": "pnpm --filter \"./packages/**\" test"
25 |   },
26 |   "dependencies": {
27 |     "diff": "^7.0.0"
28 |   },
29 |   "devDependencies": {
30 |     "@changesets/cli": "^2.28.1",
31 |     "@eslint/js": "^9.22.0",
32 |     "@stylistic/eslint-plugin": "^4.2.0",
33 |     "@svitejs/changesets-changelog-github-compact": "^1.2.0",
34 |     "@tanstack/config": "^0.17.1",
35 |     "@testing-library/jest-dom": "^6.6.3",
36 |     "@types/node": "^22.13.10",
37 |     "@types/react": "^19.0.12",
38 |     "@types/react-dom": "^19.0.4",
39 |     "@types/use-sync-external-store": "^0.0.6",
40 |     "@typescript-eslint/eslint-plugin": "^8.26.1",
41 |     "@typescript-eslint/parser": "^8.26.1",
42 |     "@vitejs/plugin-react": "^4.3.4",
43 |     "eslint": "^9.22.0",
44 |     "eslint-config-prettier": "^10.1.1",
45 |     "eslint-plugin-prettier": "^5.2.3",
46 |     "eslint-plugin-react": "^7.37.4",
47 |     "husky": "^9.1.7",
48 |     "jsdom": "^26.0.0",
49 |     "lint-staged": "^15.5.0",
50 |     "mitt": "^3.0.1",
51 |     "prettier": "^3.5.3",
52 |     "publint": "^0.3.9",
53 |     "shx": "^0.4.0",
54 |     "tsup": "^8.0.2",
55 |     "typescript": "^5.8.2",
56 |     "vite": "^6.2.2",
57 |     "vitest": "^3.0.9",
58 |     "zod": "^3.24.2"
59 |   },
60 |   "exports": {
61 |     "./react-electric": {
62 |       "types": "./dist/lib/electric.d.ts",
63 |       "import": "./dist/lib/electric.mjs",
64 |       "require": "./dist/cjs/lib/electric.cjs"
65 |     },
66 |     "./package.json": "./package.json"
67 |   },
68 |   "files": [
69 |     "dist",
70 |     "src"
71 |   ],
72 |   "lint-staged": {
73 |     "*.{ts,tsx}": [
74 |       "eslint --fix"
75 |     ]
76 |   },
77 |   "workspaces": [
78 |     "packages/*",
79 |     "examples/*",
80 |     "examples/react/*"
81 |   ],
82 |   "overrides": {
83 |     "@tanstack/db": "workspace:*",
84 |     "@tanstack/react-db": "workspace:*",
85 |     "@tanstack/vue-db": "workspace:*"
86 |   }
87 | }
88 | 


--------------------------------------------------------------------------------
/packages/db-collections/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # @tanstack/db-collections
 2 | 
 3 | ## 0.0.6
 4 | 
 5 | ### Patch Changes
 6 | 
 7 | - Updated dependencies [[`8ce449e`](https://github.com/TanStack/db/commit/8ce449ed6d070e9e591d1b74b0db5fed7a3fc92f)]:
 8 |   - @tanstack/db@0.0.4
 9 | 
10 | ## 0.0.5
11 | 
12 | ### Patch Changes
13 | 
14 | - Replace `queryCollection.invalidate()` with `queryCollection.refetch()`. ([#109](https://github.com/TanStack/db/pull/109))
15 | 
16 |   This means that we actually wait for the collection to be updated before
17 |   discarding local optimistic state.
18 | 
19 | ## 0.0.4
20 | 
21 | ### Patch Changes
22 | 
23 | - Added staleTime support for QueryCollection ([#104](https://github.com/TanStack/db/pull/104))
24 | 
25 | ## 0.0.3
26 | 
27 | ### Patch Changes
28 | 
29 | - Updated dependencies [[`b29420b`](https://github.com/TanStack/db/commit/b29420bcdae30dfeffeef63a8753b83306a54e5a)]:
30 |   - @tanstack/db@0.0.3
31 | 
32 | ## 0.0.2
33 | 
34 | ### Patch Changes
35 | 
36 | - Added QueryCollection ([#78](https://github.com/TanStack/db/pull/78))
37 | 
38 | - Updated dependencies [[`4c82edb`](https://github.com/TanStack/db/commit/4c82edb9547f26c9de44f5bf43d4385c38920672)]:
39 |   - @tanstack/db@0.0.2
40 | 


--------------------------------------------------------------------------------
/packages/db-collections/README.md:
--------------------------------------------------------------------------------
1 | # @tanstack/db-collections
2 | 
3 | A collection of TanStack DB Collections. See [TanStack/db](https://github.com/TanStack/db) for more details.
4 | 


--------------------------------------------------------------------------------
/packages/db-collections/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@tanstack/db-collections",
 3 |   "description": "A collection for (aspirationally) every way of loading your data",
 4 |   "version": "0.0.6",
 5 |   "dependencies": {
 6 |     "@tanstack/db": "workspace:*",
 7 |     "@tanstack/query-core": "^5.75.7",
 8 |     "@tanstack/store": "^0.7.0"
 9 |   },
10 |   "devDependencies": {
11 |     "@electric-sql/client": "1.0.0",
12 |     "@vitest/coverage-istanbul": "^3.0.9"
13 |   },
14 |   "exports": {
15 |     ".": {
16 |       "import": {
17 |         "types": "./dist/esm/index.d.ts",
18 |         "default": "./dist/esm/index.js"
19 |       },
20 |       "require": {
21 |         "types": "./dist/cjs/index.d.cts",
22 |         "default": "./dist/cjs/index.cjs"
23 |       }
24 |     },
25 |     "./package.json": "./package.json"
26 |   },
27 |   "files": [
28 |     "dist",
29 |     "src"
30 |   ],
31 |   "main": "dist/cjs/index.cjs",
32 |   "module": "dist/esm/index.js",
33 |   "packageManager": "pnpm@10.5.2",
34 |   "peerDependencies": {
35 |     "@electric-sql/client": ">=1.0.0",
36 |     "typescript": ">=4.7"
37 |   },
38 |   "author": "Kyle Mathews",
39 |   "license": "MIT",
40 |   "repository": {
41 |     "type": "git",
42 |     "url": "https://github.com/TanStack/db.git",
43 |     "directory": "packages/db-collections"
44 |   },
45 |   "homepage": "https://tanstack.com/db",
46 |   "keywords": [
47 |     "optimistic",
48 |     "typescript"
49 |   ],
50 |   "scripts": {
51 |     "build": "vite build",
52 |     "dev": "vite build --watch",
53 |     "lint": "eslint . --fix",
54 |     "test": "npx vitest --run"
55 |   },
56 |   "sideEffects": false,
57 |   "type": "module",
58 |   "types": "dist/esm/index.d.ts"
59 | }
60 | 


--------------------------------------------------------------------------------
/packages/db-collections/src/electric.ts:
--------------------------------------------------------------------------------
  1 | import {
  2 |   ShapeStream,
  3 |   isChangeMessage,
  4 |   isControlMessage,
  5 | } from "@electric-sql/client"
  6 | import { Store } from "@tanstack/store"
  7 | import { Collection } from "@tanstack/db"
  8 | import type { CollectionConfig, SyncConfig } from "@tanstack/db"
  9 | import type {
 10 |   ControlMessage,
 11 |   Message,
 12 |   Row,
 13 |   ShapeStreamOptions,
 14 | } from "@electric-sql/client"
 15 | 
 16 | /**
 17 |  * Configuration interface for ElectricCollection
 18 |  */
 19 | export interface ElectricCollectionConfig<T extends Row<unknown>>
 20 |   extends Omit<CollectionConfig<T>, `sync`> {
 21 |   /**
 22 |    * Configuration options for the ElectricSQL ShapeStream
 23 |    */
 24 |   streamOptions: ShapeStreamOptions
 25 | 
 26 |   /**
 27 |    * Array of column names that form the primary key of the shape
 28 |    */
 29 |   primaryKey: Array<string>
 30 | }
 31 | 
 32 | /**
 33 |  * Specialized Collection class for ElectricSQL integration
 34 |  */
 35 | export class ElectricCollection<
 36 |   T extends Row<unknown> = Record<string, unknown>,
 37 | > extends Collection<T> {
 38 |   private seenTxids: Store<Set<number>>
 39 | 
 40 |   constructor(config: ElectricCollectionConfig<T>) {
 41 |     const seenTxids = new Store<Set<number>>(new Set([Math.random()]))
 42 |     const sync = createElectricSync<T>(config.streamOptions, {
 43 |       primaryKey: config.primaryKey,
 44 |       seenTxids,
 45 |     })
 46 | 
 47 |     super({ ...config, sync })
 48 | 
 49 |     this.seenTxids = seenTxids
 50 |   }
 51 | 
 52 |   /**
 53 |    * Wait for a specific transaction ID to be synced
 54 |    * @param txId The transaction ID to wait for
 55 |    * @param timeout Optional timeout in milliseconds (defaults to 30000ms)
 56 |    * @returns Promise that resolves when the txId is synced
 57 |    */
 58 |   async awaitTxId(txId: number, timeout = 30000): Promise<boolean> {
 59 |     const hasTxid = this.seenTxids.state.has(txId)
 60 |     if (hasTxid) return true
 61 | 
 62 |     return new Promise((resolve, reject) => {
 63 |       const timeoutId = setTimeout(() => {
 64 |         unsubscribe()
 65 |         reject(new Error(`Timeout waiting for txId: ${txId}`))
 66 |       }, timeout)
 67 | 
 68 |       const unsubscribe = this.seenTxids.subscribe(() => {
 69 |         if (this.seenTxids.state.has(txId)) {
 70 |           clearTimeout(timeoutId)
 71 |           unsubscribe()
 72 |           resolve(true)
 73 |         }
 74 |       })
 75 |     })
 76 |   }
 77 | }
 78 | 
 79 | function isUpToDateMessage<T extends Row<unknown> = Row>(
 80 |   message: Message<T>
 81 | ): message is ControlMessage & { up_to_date: true } {
 82 |   return isControlMessage(message) && message.headers.control === `up-to-date`
 83 | }
 84 | 
 85 | // Check if a message contains txids in its headers
 86 | function hasTxids<T extends Row<unknown> = Row>(
 87 |   message: Message<T>
 88 | ): message is Message<T> & { headers: { txids?: Array<number> } } {
 89 |   return (
 90 |     `headers` in message &&
 91 |     `txids` in message.headers &&
 92 |     Array.isArray(message.headers.txids)
 93 |   )
 94 | }
 95 | 
 96 | /**
 97 |  * Creates an ElectricSQL sync configuration
 98 |  *
 99 |  * @param streamOptions - Configuration options for the ShapeStream
100 |  * @param options - Options for the ElectricSync configuration
101 |  * @returns ElectricSync configuration
102 |  */
103 | /**
104 |  * Create a new ElectricCollection instance
105 |  */
106 | export function createElectricCollection<T extends Row<unknown>>(
107 |   config: ElectricCollectionConfig<T>
108 | ): ElectricCollection<T> {
109 |   return new ElectricCollection(config)
110 | }
111 | 
112 | /**
113 |  * Internal function to create ElectricSQL sync configuration
114 |  */
115 | function createElectricSync<T extends Row<unknown>>(
116 |   streamOptions: ShapeStreamOptions,
117 |   options: { primaryKey: Array<string>; seenTxids: Store<Set<number>> }
118 | ): SyncConfig<T> {
119 |   const { primaryKey, seenTxids } = options
120 | 
121 |   // Store for the relation schema information
122 |   const relationSchema = new Store<string | undefined>(undefined)
123 | 
124 |   /**
125 |    * Get the sync metadata for insert operations
126 |    * @returns Record containing primaryKey and relation information
127 |    */
128 |   const getSyncMetadata = (): Record<string, unknown> => {
129 |     // Use the stored schema if available, otherwise default to 'public'
130 |     const schema = relationSchema.state || `public`
131 | 
132 |     return {
133 |       primaryKey,
134 |       relation: streamOptions.params?.table
135 |         ? [schema, streamOptions.params.table]
136 |         : undefined,
137 |     }
138 |   }
139 | 
140 |   return {
141 |     sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {
142 |       const { begin, write, commit } = params
143 |       const stream = new ShapeStream(streamOptions)
144 |       let transactionStarted = false
145 |       let newTxids = new Set<number>()
146 | 
147 |       stream.subscribe((messages: Array<Message<Row>>) => {
148 |         let hasUpToDate = false
149 | 
150 |         for (const message of messages) {
151 |           // Check for txids in the message and add them to our store
152 |           if (hasTxids(message) && message.headers.txids) {
153 |             message.headers.txids.forEach((txid) => newTxids.add(txid))
154 |           }
155 | 
156 |           // Check if the message contains schema information
157 |           if (isChangeMessage(message) && message.headers.schema) {
158 |             // Store the schema for future use if it's a valid string
159 |             if (typeof message.headers.schema === `string`) {
160 |               const schema: string = message.headers.schema
161 |               relationSchema.setState(() => schema)
162 |             }
163 |           }
164 | 
165 |           if (isChangeMessage(message)) {
166 |             if (!transactionStarted) {
167 |               begin()
168 |               transactionStarted = true
169 |             }
170 | 
171 |             const key = message.key
172 | 
173 |             // Include the primary key and relation info in the metadata
174 |             const enhancedMetadata = {
175 |               ...message.headers,
176 |               primaryKey,
177 |             }
178 | 
179 |             write({
180 |               key,
181 |               type: message.headers.operation,
182 |               value: message.value as unknown as T,
183 |               metadata: enhancedMetadata,
184 |             })
185 |           } else if (isUpToDateMessage(message)) {
186 |             hasUpToDate = true
187 |           }
188 |         }
189 | 
190 |         if (hasUpToDate && transactionStarted) {
191 |           commit()
192 |           seenTxids.setState((currentTxids) => {
193 |             const clonedSeen = new Set(currentTxids)
194 |             newTxids.forEach((txid) => clonedSeen.add(txid))
195 | 
196 |             newTxids = new Set()
197 |             return clonedSeen
198 |           })
199 |           transactionStarted = false
200 |         }
201 |       })
202 |     },
203 |     // Expose the getSyncMetadata function
204 |     getSyncMetadata,
205 |   }
206 | }
207 | 
208 | /**
209 |  * Configuration options for ElectricSync
210 |  */
211 | export interface ElectricSyncOptions {
212 |   /**
213 |    * Array of column names that form the primary key of the shape
214 |    */
215 |   primaryKey: Array<string>
216 | }
217 | 


--------------------------------------------------------------------------------
/packages/db-collections/src/index.ts:
--------------------------------------------------------------------------------
 1 | export {
 2 |   ElectricCollection,
 3 |   createElectricCollection,
 4 |   type ElectricCollectionConfig,
 5 | } from "./electric"
 6 | export {
 7 |   QueryCollection,
 8 |   createQueryCollection,
 9 |   type QueryCollectionConfig,
10 | } from "./query"
11 | 


--------------------------------------------------------------------------------
/packages/db-collections/tests/test-setup.ts:
--------------------------------------------------------------------------------
1 | import "@testing-library/jest-dom/vitest"
2 | 


--------------------------------------------------------------------------------
/packages/db-collections/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "extends": "../../tsconfig.json",
 3 |   "compilerOptions": {
 4 |     "target": "ES2020",
 5 |     "module": "ESNext",
 6 |     "moduleResolution": "Bundler",
 7 |     "declaration": true,
 8 |     "outDir": "dist",
 9 |     "strict": true,
10 |     "esModuleInterop": true,
11 |     "skipLibCheck": true,
12 |     "forceConsistentCasingInFileNames": true,
13 |     "jsx": "react",
14 |     "paths": {
15 |       "@tanstack/store": ["../store/src"]
16 |     }
17 |   },
18 |   "include": ["src", "tests", "vite.config.ts"],
19 |   "exclude": ["node_modules", "dist"]
20 | }
21 | 


--------------------------------------------------------------------------------
/packages/db-collections/vite.config.ts:
--------------------------------------------------------------------------------
 1 | import { defineConfig, mergeConfig } from "vitest/config"
 2 | import { tanstackViteConfig } from "@tanstack/config/vite"
 3 | import packageJson from "./package.json"
 4 | 
 5 | const config = defineConfig({
 6 |   test: {
 7 |     name: packageJson.name,
 8 |     dir: `./tests`,
 9 |     environment: `jsdom`,
10 |     coverage: { enabled: true, provider: `istanbul`, include: [`src/**/*`] },
11 |     typecheck: { enabled: true },
12 |     setupFiles: [`./tests/test-setup.ts`],
13 |   },
14 | })
15 | 
16 | export default mergeConfig(
17 |   config,
18 |   tanstackViteConfig({
19 |     entry: `./src/index.ts`,
20 |     srcDir: `./src`,
21 |   })
22 | )
23 | 


--------------------------------------------------------------------------------
/packages/db/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # @tanstack/db
 2 | 
 3 | ## 0.0.4
 4 | 
 5 | ### Patch Changes
 6 | 
 7 | - fix a bug where optimistic operations could be applied to the wrong collection ([#113](https://github.com/TanStack/db/pull/113))
 8 | 
 9 | ## 0.0.3
10 | 
11 | ### Patch Changes
12 | 
13 | - fix a bug where query results would not correctly update ([#87](https://github.com/TanStack/db/pull/87))
14 | 
15 | ## 0.0.2
16 | 
17 | ### Patch Changes
18 | 
19 | - Fixed an issue with injecting the optimistic state removal into the reactive live query. ([#78](https://github.com/TanStack/db/pull/78))
20 | 
21 | ## 0.0.3
22 | 
23 | ### Patch Changes
24 | 
25 | - Make transactions first class & move ownership of mutationFn from collections to transactions ([#53](https://github.com/TanStack/db/pull/53))
26 | 
27 | ## 0.0.2
28 | 
29 | ### Patch Changes
30 | 
31 | - make mutationFn optional for read-only collections ([#12](https://github.com/TanStack/db/pull/12))
32 | 
33 | - Improve test coverage ([#10](https://github.com/TanStack/db/pull/10))
34 | 
35 | ## 0.0.1
36 | 
37 | ### Patch Changes
38 | 
39 | - feat: Initial release ([#2](https://github.com/TanStack/db/pull/2))
40 | 


--------------------------------------------------------------------------------
/packages/db/README.md:
--------------------------------------------------------------------------------
 1 | # @tanstack/db
 2 | 
 3 | **A reactive client store for building super fast apps on sync**
 4 | 
 5 | TanStack DB extends TanStack Query with collections, live queries and optimistic mutations that keep your UI reactive, consistent and blazing fast 🔥
 6 | 
 7 | <p>
 8 |   <a href="https://x.com/intent/post?text=TanStack%20DB&url=https://tanstack.com/db">
 9 |     <img alt="#TanStack" src="https://img.shields.io/twitter/url?color=%2308a0e9&label=%23TanStack&style=social&url=https%3A%2F%2Ftwitter.com%2Fintent%2Ftweet%3Fbutton_hashtag%3DTanStack" /></a>
10 |   <a href="#status">
11 |     <img src="https://img.shields.io/badge/status-alpha-orange" alt="Status - Alpha"></a>
12 |   <a href="https://npmjs.com/package/@tanstack/db">
13 |     <img alt="" src="https://img.shields.io/npm/dm/@tanstack/db.svg" /></a>
14 |   <a href="https://discord.gg/yjUNbvbraC">
15 |     <img alt="" src="https://img.shields.io/badge/Discord-TanStack-%235865F2" /></a>
16 |   <a href="https://github.com/tanstack/db/discussions">
17 |     <img alt="Join the discussion on Github" src="https://img.shields.io/badge/Discussions-Chat%20now!-green" /></a>
18 |   <a href="https://x.com/tan_stack">
19 |     <img alt="" src="https://img.shields.io/twitter/follow/tan_stack.svg?style=social&label=Follow @TanStack" /></a>
20 | </p>
21 | 
22 | ## 💥 Visit the [TanStack/db](https://github.com/TanStack/db) repo for docs and details!
23 | 
24 | - 🔥 **blazing fast query engine**<br />
25 |   for sub-millisecond live queries &mdash; even for complex queries with joins and aggregates
26 | - 🎯 **fine-grained reactivity**<br />
27 |   to minimize component re-rendering
28 | - 💪 **robust transaction primitives**<br />
29 |   for easy optimistic mutations with sync and lifecycle support
30 | - 🌟 **normalized data**<br />
31 |   to keep your backend simple
32 | 
33 | ---
34 | 
35 | ### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
36 | 
37 | Enjoy this library? Try the entire [TanStack](https://tanstack.com), including [TanStack Query](https://tanstack.com/query), [TanStack Store](https://tanstack.com/store), etc.
38 | 


--------------------------------------------------------------------------------
/packages/db/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@tanstack/db",
 3 |   "description": "A reactive client store for building super fast apps on sync",
 4 |   "version": "0.0.4",
 5 |   "dependencies": {
 6 |     "@electric-sql/d2ts": "^0.1.5",
 7 |     "@standard-schema/spec": "^1.0.0",
 8 |     "@tanstack/store": "^0.7.0"
 9 |   },
10 |   "devDependencies": {
11 |     "@vitest/coverage-istanbul": "^3.0.9"
12 |   },
13 |   "exports": {
14 |     ".": {
15 |       "import": {
16 |         "types": "./dist/esm/index.d.ts",
17 |         "default": "./dist/esm/index.js"
18 |       },
19 |       "require": {
20 |         "types": "./dist/cjs/index.d.cts",
21 |         "default": "./dist/cjs/index.cjs"
22 |       }
23 |     },
24 |     "./package.json": "./package.json"
25 |   },
26 |   "files": [
27 |     "dist",
28 |     "src"
29 |   ],
30 |   "main": "dist/cjs/index.cjs",
31 |   "module": "dist/esm/index.js",
32 |   "packageManager": "pnpm@10.5.2",
33 |   "peerDependencies": {
34 |     "typescript": ">=4.7"
35 |   },
36 |   "author": "Kyle Mathews",
37 |   "license": "MIT",
38 |   "repository": {
39 |     "type": "git",
40 |     "url": "https://github.com/TanStack/db.git",
41 |     "directory": "packages/db"
42 |   },
43 |   "homepage": "https://tanstack.com/db",
44 |   "keywords": [
45 |     "optimistic",
46 |     "typescript"
47 |   ],
48 |   "scripts": {
49 |     "build": "vite build",
50 |     "dev": "vite build --watch",
51 |     "lint": "eslint . --fix",
52 |     "test": "npx vitest --run"
53 |   },
54 |   "sideEffects": false,
55 |   "type": "module",
56 |   "types": "dist/esm/index.d.ts"
57 | }
58 | 


--------------------------------------------------------------------------------
/packages/db/src/SortedMap.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * A Map implementation that keeps its entries sorted based on a comparator function
  3 |  * @template TKey - The type of keys in the map
  4 |  * @template TValue - The type of values in the map
  5 |  */
  6 | export class SortedMap<TKey, TValue> {
  7 |   private map: Map<TKey, TValue>
  8 |   private sortedKeys: Array<TKey>
  9 |   private comparator: (a: TValue, b: TValue) => number
 10 | 
 11 |   /**
 12 |    * Creates a new SortedMap instance
 13 |    *
 14 |    * @param comparator - Optional function to compare values for sorting
 15 |    */
 16 |   constructor(comparator?: (a: TValue, b: TValue) => number) {
 17 |     this.map = new Map<TKey, TValue>()
 18 |     this.sortedKeys = []
 19 |     this.comparator = comparator || this.defaultComparator
 20 |   }
 21 | 
 22 |   /**
 23 |    * Default comparator function used when none is provided
 24 |    *
 25 |    * @param a - First value to compare
 26 |    * @param b - Second value to compare
 27 |    * @returns -1 if a < b, 1 if a > b, 0 if equal
 28 |    */
 29 |   private defaultComparator(a: TValue, b: TValue): number {
 30 |     if (a < b) return -1
 31 |     if (a > b) return 1
 32 |     return 0
 33 |   }
 34 | 
 35 |   /**
 36 |    * Sets a key-value pair in the map and maintains sort order
 37 |    *
 38 |    * @param key - The key to set
 39 |    * @param value - The value to associate with the key
 40 |    * @returns This SortedMap instance for chaining
 41 |    */
 42 |   set(key: TKey, value: TValue): this {
 43 |     this.map.set(key, value)
 44 | 
 45 |     if (!this.sortedKeys.includes(key)) {
 46 |       this.sortedKeys.push(key)
 47 |     }
 48 | 
 49 |     // Re-sort keys based on values
 50 |     this.sortedKeys.sort((a, b) => {
 51 |       const valueA = this.map.get(a)!
 52 |       const valueB = this.map.get(b)!
 53 |       return this.comparator(valueA, valueB)
 54 |     })
 55 | 
 56 |     return this
 57 |   }
 58 | 
 59 |   /**
 60 |    * Gets a value by its key
 61 |    *
 62 |    * @param key - The key to look up
 63 |    * @returns The value associated with the key, or undefined if not found
 64 |    */
 65 |   get(key: TKey): TValue | undefined {
 66 |     return this.map.get(key)
 67 |   }
 68 | 
 69 |   /**
 70 |    * Removes a key-value pair from the map
 71 |    *
 72 |    * @param key - The key to remove
 73 |    * @returns True if the key was found and removed, false otherwise
 74 |    */
 75 |   delete(key: TKey): boolean {
 76 |     if (this.map.delete(key)) {
 77 |       const index = this.sortedKeys.indexOf(key)
 78 |       this.sortedKeys.splice(index, 1)
 79 |       return true
 80 |     }
 81 |     return false
 82 |   }
 83 | 
 84 |   /**
 85 |    * Checks if a key exists in the map
 86 |    *
 87 |    * @param key - The key to check
 88 |    * @returns True if the key exists, false otherwise
 89 |    */
 90 |   has(key: TKey): boolean {
 91 |     return this.map.has(key)
 92 |   }
 93 | 
 94 |   /**
 95 |    * Removes all key-value pairs from the map
 96 |    */
 97 |   clear(): void {
 98 |     this.map.clear()
 99 |     this.sortedKeys = []
100 |   }
101 | 
102 |   /**
103 |    * Gets the number of key-value pairs in the map
104 |    */
105 |   get size(): number {
106 |     return this.map.size
107 |   }
108 | 
109 |   /**
110 |    * Default iterator that returns entries in sorted order
111 |    *
112 |    * @returns An iterator for the map's entries
113 |    */
114 |   *[Symbol.iterator](): IterableIterator<[TKey, TValue]> {
115 |     for (const key of this.sortedKeys) {
116 |       yield [key, this.map.get(key)!] as [TKey, TValue]
117 |     }
118 |   }
119 | 
120 |   /**
121 |    * Returns an iterator for the map's entries in sorted order
122 |    *
123 |    * @returns An iterator for the map's entries
124 |    */
125 |   entries(): IterableIterator<[TKey, TValue]> {
126 |     return this[Symbol.iterator]()
127 |   }
128 | 
129 |   /**
130 |    * Returns an iterator for the map's keys in sorted order
131 |    *
132 |    * @returns An iterator for the map's keys
133 |    */
134 |   keys(): IterableIterator<TKey> {
135 |     return this.sortedKeys[Symbol.iterator]()
136 |   }
137 | 
138 |   /**
139 |    * Returns an iterator for the map's values in sorted order
140 |    *
141 |    * @returns An iterator for the map's values
142 |    */
143 |   values(): IterableIterator<TValue> {
144 |     return function* (this: SortedMap<TKey, TValue>) {
145 |       for (const key of this.sortedKeys) {
146 |         yield this.map.get(key)!
147 |       }
148 |     }.call(this)
149 |   }
150 | 
151 |   /**
152 |    * Executes a callback function for each key-value pair in the map in sorted order
153 |    *
154 |    * @param callbackfn - Function to execute for each entry
155 |    */
156 |   forEach(
157 |     callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void
158 |   ): void {
159 |     for (const key of this.sortedKeys) {
160 |       callbackfn(this.map.get(key)!, key, this.map)
161 |     }
162 |   }
163 | }
164 | 


--------------------------------------------------------------------------------
/packages/db/src/deferred.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * A Deferred object represents a Promise that can be resolved or rejected
 3 |  * from outside the Promise constructor.
 4 |  */
 5 | export interface Deferred<T> {
 6 |   /** The Promise object being controlled */
 7 |   promise: Promise<T>
 8 | 
 9 |   /** Function to resolve the Promise with a value or another Promise */
10 |   resolve: (value: T | PromiseLike<T>) => void
11 | 
12 |   /** Function to reject the Promise with an error */
13 |   reject: (reason?: Error | unknown) => void
14 | 
15 |   /** Check if the Promise has been resolved or rejected */
16 |   isPending: () => boolean
17 | }
18 | 
19 | /**
20 |  * Creates a Deferred object containing a Promise and methods to control it.
21 |  *
22 |  * @returns A Deferred object with promise, resolve, reject, and isPending methods
23 |  */
24 | export function createDeferred<T>(): Deferred<T> {
25 |   let resolve!: (value: T | PromiseLike<T>) => void
26 |   let reject!: (reason?: Error | unknown) => void
27 |   let isPending = true
28 | 
29 |   const promise = new Promise<T>((res, rej) => {
30 |     resolve = (value) => {
31 |       isPending = false
32 |       res(value)
33 |     }
34 | 
35 |     reject = (reason) => {
36 |       isPending = false
37 |       rej(reason)
38 |     }
39 |   })
40 | 
41 |   return {
42 |     promise,
43 |     resolve,
44 |     reject,
45 |     isPending: () => isPending,
46 |   }
47 | }
48 | 


--------------------------------------------------------------------------------
/packages/db/src/errors.ts:
--------------------------------------------------------------------------------
1 | export class NonRetriableError extends Error {
2 |   constructor(message: string) {
3 |     super(message)
4 |     this.name = `NonRetriableError`
5 |   }
6 | }
7 | 


--------------------------------------------------------------------------------
/packages/db/src/index.ts:
--------------------------------------------------------------------------------
 1 | // Re-export all public APIs
 2 | export * from "./collection"
 3 | export * from "./SortedMap"
 4 | export * from "./transactions"
 5 | export * from "./types"
 6 | export * from "./errors"
 7 | export * from "./utils"
 8 | export * from "./proxy"
 9 | export * from "./query/index.js"
10 | 
11 | // Re-export some stuff explicitly to ensure the type & value is exported
12 | export { Collection } from "./collection"
13 | 


--------------------------------------------------------------------------------
/packages/db/src/query/compiled-query.ts:
--------------------------------------------------------------------------------
  1 | import { D2, MessageType, MultiSet, output } from "@electric-sql/d2ts"
  2 | import { Effect, batch } from "@tanstack/store"
  3 | import { Collection } from "../collection.js"
  4 | import { compileQueryPipeline } from "./pipeline-compiler.js"
  5 | import type { ChangeMessage, SyncConfig } from "../types.js"
  6 | import type {
  7 |   IStreamBuilder,
  8 |   MultiSetArray,
  9 |   RootStreamBuilder,
 10 | } from "@electric-sql/d2ts"
 11 | import type { QueryBuilder, ResultsFromContext } from "./query-builder.js"
 12 | import type { Context, Schema } from "./types.js"
 13 | 
 14 | export function compileQuery<TContext extends Context<Schema>>(
 15 |   queryBuilder: QueryBuilder<TContext>
 16 | ) {
 17 |   return new CompiledQuery<ResultsFromContext<TContext>>(queryBuilder)
 18 | }
 19 | 
 20 | export class CompiledQuery<TResults extends object = Record<string, unknown>> {
 21 |   private graph: D2
 22 |   private inputs: Record<string, RootStreamBuilder<any>>
 23 |   private inputCollections: Record<string, Collection<any>>
 24 |   private resultCollection: Collection<TResults>
 25 |   public state: `compiled` | `running` | `stopped` = `compiled`
 26 |   private version = 0
 27 |   private unsubscribeEffect?: () => void
 28 | 
 29 |   constructor(queryBuilder: QueryBuilder<Context<Schema>>) {
 30 |     const query = queryBuilder._query
 31 |     const collections = query.collections
 32 | 
 33 |     if (!collections) {
 34 |       throw new Error(`No collections provided`)
 35 |     }
 36 | 
 37 |     this.inputCollections = collections
 38 | 
 39 |     const graph = new D2({ initialFrontier: this.version })
 40 |     const inputs = Object.fromEntries(
 41 |       Object.entries(collections).map(([key]) => [key, graph.newInput<any>()])
 42 |     )
 43 | 
 44 |     const sync: SyncConfig<TResults>[`sync`] = ({ begin, write, commit }) => {
 45 |       compileQueryPipeline<IStreamBuilder<[unknown, TResults]>>(
 46 |         query,
 47 |         inputs
 48 |       ).pipe(
 49 |         output(({ type, data }) => {
 50 |           if (type === MessageType.DATA) {
 51 |             begin()
 52 |             data.collection
 53 |               .getInner()
 54 |               .reduce((acc, [[key, value], multiplicity]) => {
 55 |                 const changes = acc.get(key) || {
 56 |                   deletes: 0,
 57 |                   inserts: 0,
 58 |                   value,
 59 |                 }
 60 |                 if (multiplicity < 0) {
 61 |                   changes.deletes += Math.abs(multiplicity)
 62 |                 } else if (multiplicity > 0) {
 63 |                   changes.inserts += multiplicity
 64 |                   changes.value = value
 65 |                 }
 66 |                 acc.set(key, changes)
 67 |                 return acc
 68 |               }, new Map<unknown, { deletes: number; inserts: number; value: TResults }>())
 69 |               .forEach((changes, rawKey) => {
 70 |                 const key = (rawKey as any).toString()
 71 |                 const { deletes, inserts, value } = changes
 72 |                 if (inserts && !deletes) {
 73 |                   write({
 74 |                     key,
 75 |                     value: value,
 76 |                     type: `insert`,
 77 |                   })
 78 |                 } else if (inserts >= deletes) {
 79 |                   write({
 80 |                     key,
 81 |                     value: value,
 82 |                     type: `update`,
 83 |                   })
 84 |                 } else if (deletes > 0) {
 85 |                   write({
 86 |                     key,
 87 |                     value: value,
 88 |                     type: `delete`,
 89 |                   })
 90 |                 }
 91 |               })
 92 |             commit()
 93 |           }
 94 |         })
 95 |       )
 96 |       graph.finalize()
 97 |     }
 98 | 
 99 |     this.graph = graph
100 |     this.inputs = inputs
101 |     this.resultCollection = new Collection<TResults>({
102 |       id: crypto.randomUUID(), // TODO: remove when we don't require any more
103 |       sync: {
104 |         sync,
105 |       },
106 |     })
107 |   }
108 | 
109 |   get results() {
110 |     return this.resultCollection
111 |   }
112 | 
113 |   private sendChangesToInput(inputKey: string, changes: Array<ChangeMessage>) {
114 |     const input = this.inputs[inputKey]!
115 |     const multiSetArray: MultiSetArray<unknown> = []
116 |     for (const change of changes) {
117 |       if (change.type === `insert`) {
118 |         multiSetArray.push([change.value, 1])
119 |       } else if (change.type === `update`) {
120 |         multiSetArray.push([change.previousValue, -1])
121 |         multiSetArray.push([change.value, 1])
122 |       } else {
123 |         // change.type === `delete`
124 |         multiSetArray.push([change.value, -1])
125 |       }
126 |     }
127 |     input.sendData(this.version, new MultiSet(multiSetArray))
128 |   }
129 | 
130 |   private sendFrontierToInput(inputKey: string) {
131 |     const input = this.inputs[inputKey]!
132 |     input.sendFrontier(this.version)
133 |   }
134 | 
135 |   private sendFrontierToAllInputs() {
136 |     Object.entries(this.inputs).forEach(([key]) => {
137 |       this.sendFrontierToInput(key)
138 |     })
139 |   }
140 | 
141 |   private incrementVersion() {
142 |     this.version++
143 |   }
144 | 
145 |   private runGraph() {
146 |     this.graph.run()
147 |   }
148 | 
149 |   start() {
150 |     if (this.state === `running`) {
151 |       throw new Error(`Query is already running`)
152 |     } else if (this.state === `stopped`) {
153 |       throw new Error(`Query is stopped`)
154 |     }
155 | 
156 |     batch(() => {
157 |       Object.entries(this.inputCollections).forEach(([key, collection]) => {
158 |         this.sendChangesToInput(key, collection.currentStateAsChanges())
159 |       })
160 |       this.incrementVersion()
161 |       this.sendFrontierToAllInputs()
162 |       this.runGraph()
163 |     })
164 | 
165 |     const changeEffect = new Effect({
166 |       fn: () => {
167 |         batch(() => {
168 |           Object.entries(this.inputCollections).forEach(([key, collection]) => {
169 |             this.sendChangesToInput(key, collection.derivedChanges.state)
170 |           })
171 |           this.incrementVersion()
172 |           this.sendFrontierToAllInputs()
173 |           this.runGraph()
174 |         })
175 |       },
176 |       deps: Object.values(this.inputCollections).map(
177 |         (collection) => collection.derivedChanges
178 |       ),
179 |     })
180 |     this.unsubscribeEffect = changeEffect.mount()
181 | 
182 |     this.state = `running`
183 |     return () => {
184 |       this.stop()
185 |     }
186 |   }
187 | 
188 |   stop() {
189 |     this.unsubscribeEffect?.()
190 |     this.unsubscribeEffect = undefined
191 |     this.state = `stopped`
192 |   }
193 | }
194 | 


--------------------------------------------------------------------------------
/packages/db/src/query/group-by.ts:
--------------------------------------------------------------------------------
  1 | import { groupBy, groupByOperators, map } from "@electric-sql/d2ts"
  2 | import {
  3 |   evaluateOperandOnNestedRow,
  4 |   extractValueFromNestedRow,
  5 | } from "./extractors"
  6 | import { isAggregateFunctionCall } from "./utils"
  7 | import type { ConditionOperand, FunctionCall, Query } from "./schema"
  8 | import type { IStreamBuilder } from "@electric-sql/d2ts"
  9 | 
 10 | const { sum, count, avg, min, max, median, mode } = groupByOperators
 11 | 
 12 | /**
 13 |  * Process the groupBy clause in a D2QL query
 14 |  */
 15 | export function processGroupBy(
 16 |   pipeline: IStreamBuilder<Record<string, unknown>>,
 17 |   query: Query,
 18 |   mainTableAlias: string
 19 | ) {
 20 |   // Normalize groupBy to an array of column references
 21 |   const groupByColumns = Array.isArray(query.groupBy)
 22 |     ? query.groupBy
 23 |     : [query.groupBy]
 24 | 
 25 |   // Create a key extractor function for the groupBy operator
 26 |   const keyExtractor = (nestedRow: Record<string, unknown>) => {
 27 |     const key: Record<string, unknown> = {}
 28 | 
 29 |     // Extract each groupBy column value
 30 |     for (const column of groupByColumns) {
 31 |       if (typeof column === `string` && (column as string).startsWith(`@`)) {
 32 |         const columnRef = (column as string).substring(1)
 33 |         const columnName = columnRef.includes(`.`)
 34 |           ? columnRef.split(`.`)[1]
 35 |           : columnRef
 36 | 
 37 |         key[columnName!] = extractValueFromNestedRow(
 38 |           nestedRow,
 39 |           columnRef,
 40 |           mainTableAlias
 41 |         )
 42 |       }
 43 |     }
 44 | 
 45 |     return key
 46 |   }
 47 | 
 48 |   // Create aggregate functions for any aggregated columns in the SELECT clause
 49 |   const aggregates: Record<string, any> = {}
 50 | 
 51 |   // Scan the SELECT clause for aggregate functions
 52 |   for (const item of query.select) {
 53 |     if (typeof item === `object`) {
 54 |       for (const [alias, expr] of Object.entries(item)) {
 55 |         if (typeof expr === `object` && isAggregateFunctionCall(expr)) {
 56 |           // Get the function name (the only key in the object)
 57 |           const functionName = Object.keys(expr)[0]
 58 |           // Get the column reference or expression to aggregate
 59 |           const columnRef = (expr as FunctionCall)[
 60 |             functionName as keyof FunctionCall
 61 |           ]
 62 | 
 63 |           // Add the aggregate function to our aggregates object
 64 |           aggregates[alias] = getAggregateFunction(
 65 |             functionName!,
 66 |             columnRef,
 67 |             mainTableAlias
 68 |           )
 69 |         }
 70 |       }
 71 |     }
 72 |   }
 73 | 
 74 |   // Apply the groupBy operator if we have any aggregates
 75 |   if (Object.keys(aggregates).length > 0) {
 76 |     pipeline = pipeline.pipe(
 77 |       groupBy(keyExtractor, aggregates),
 78 |       // Convert KeyValue<string, ResultType> to Record<string, unknown>
 79 |       map(([_key, value]) => {
 80 |         // After groupBy, the value already contains both the key fields and aggregate results
 81 |         // We need to return it as is, not wrapped in a nested structure
 82 |         return value as Record<string, unknown>
 83 |       })
 84 |     )
 85 |   }
 86 | 
 87 |   return pipeline
 88 | }
 89 | 
 90 | /**
 91 |  * Helper function to get an aggregate function based on the function name
 92 |  */
 93 | export function getAggregateFunction(
 94 |   functionName: string,
 95 |   columnRef: string | ConditionOperand,
 96 |   mainTableAlias: string
 97 | ) {
 98 |   // Create a value extractor function for the column to aggregate
 99 |   const valueExtractor = (nestedRow: Record<string, unknown>) => {
100 |     let value: unknown
101 |     if (typeof columnRef === `string` && columnRef.startsWith(`@`)) {
102 |       value = extractValueFromNestedRow(
103 |         nestedRow,
104 |         columnRef.substring(1),
105 |         mainTableAlias
106 |       )
107 |     } else {
108 |       value = evaluateOperandOnNestedRow(
109 |         nestedRow,
110 |         columnRef as ConditionOperand,
111 |         mainTableAlias
112 |       )
113 |     }
114 |     // Ensure we return a number for aggregate functions
115 |     return typeof value === `number` ? value : 0
116 |   }
117 | 
118 |   // Return the appropriate aggregate function
119 |   switch (functionName.toUpperCase()) {
120 |     case `SUM`:
121 |       return sum(valueExtractor)
122 |     case `COUNT`:
123 |       return count() // count() doesn't need a value extractor
124 |     case `AVG`:
125 |       return avg(valueExtractor)
126 |     case `MIN`:
127 |       return min(valueExtractor)
128 |     case `MAX`:
129 |       return max(valueExtractor)
130 |     case `MEDIAN`:
131 |       return median(valueExtractor)
132 |     case `MODE`:
133 |       return mode(valueExtractor)
134 |     default:
135 |       throw new Error(`Unsupported aggregate function: ${functionName}`)
136 |   }
137 | }
138 | 


--------------------------------------------------------------------------------
/packages/db/src/query/index.ts:
--------------------------------------------------------------------------------
1 | export * from "./query-builder.js"
2 | export * from "./compiled-query.js"
3 | export * from "./pipeline-compiler.js"
4 | export * from "./schema.js"
5 | export * from "./types.js"
6 | 


--------------------------------------------------------------------------------
/packages/db/src/query/key-by.ts:
--------------------------------------------------------------------------------
 1 | import { keyBy } from "@electric-sql/d2ts"
 2 | import type { IStreamBuilder } from "@electric-sql/d2ts"
 3 | import type { Query } from "./schema"
 4 | 
 5 | export function processKeyBy(
 6 |   resultPipeline: IStreamBuilder<
 7 |     Record<string, unknown> | [string | number, Record<string, unknown>]
 8 |   >,
 9 |   query: Query
10 | ) {
11 |   if (!query.keyBy) {
12 |     return resultPipeline
13 |   }
14 |   const keyByParam = query.keyBy
15 | 
16 |   resultPipeline = resultPipeline.pipe(
17 |     keyBy((row: Record<string, unknown>) => {
18 |       if (Array.isArray(keyByParam)) {
19 |         // Multiple columns - extract values and JSON stringify
20 |         const keyValues: Record<string, unknown> = {}
21 |         for (const keyColumn of keyByParam) {
22 |           // Remove @ prefix if present
23 |           const columnName = (keyColumn as string).startsWith(`@`)
24 |             ? (keyColumn as string).substring(1)
25 |             : (keyColumn as string)
26 | 
27 |           if (columnName in row) {
28 |             keyValues[columnName] = row[columnName]
29 |           } else {
30 |             throw new Error(
31 |               `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
32 |             )
33 |           }
34 |         }
35 |         return JSON.stringify(keyValues)
36 |       } else {
37 |         // Single column
38 |         // Remove @ prefix if present
39 |         const columnName = (keyByParam as string).startsWith(`@`)
40 |           ? (keyByParam as string).substring(1)
41 |           : (keyByParam as string)
42 | 
43 |         if (!(columnName in row)) {
44 |           throw new Error(
45 |             `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
46 |           )
47 |         }
48 | 
49 |         const keyValue = row[columnName]
50 |         // Use the value directly if it's a string or number, otherwise JSON stringify
51 |         if (typeof keyValue === `string` || typeof keyValue === `number`) {
52 |           return keyValue
53 |         } else {
54 |           return JSON.stringify(keyValue)
55 |         }
56 |       }
57 |     })
58 |   )
59 | 
60 |   return resultPipeline
61 | }
62 | 


--------------------------------------------------------------------------------
/packages/db/src/query/pipeline-compiler.ts:
--------------------------------------------------------------------------------
  1 | import { filter, map } from "@electric-sql/d2ts"
  2 | import { evaluateConditionOnNestedRow } from "./evaluators.js"
  3 | import { processJoinClause } from "./joins.js"
  4 | import { processGroupBy } from "./group-by.js"
  5 | import { processOrderBy } from "./order-by.js"
  6 | import { processKeyBy } from "./key-by.js"
  7 | import { processSelect } from "./select.js"
  8 | import type { Condition, Query } from "./schema.js"
  9 | import type { IStreamBuilder } from "@electric-sql/d2ts"
 10 | 
 11 | /**
 12 |  * Compiles a query into a D2 pipeline
 13 |  * @param query The query to compile
 14 |  * @param inputs Mapping of table names to input streams
 15 |  * @returns A stream builder representing the compiled query
 16 |  */
 17 | export function compileQueryPipeline<T extends IStreamBuilder<unknown>>(
 18 |   query: Query,
 19 |   inputs: Record<string, IStreamBuilder<Record<string, unknown>>>
 20 | ): T {
 21 |   // Create a copy of the inputs map to avoid modifying the original
 22 |   const allInputs = { ...inputs }
 23 | 
 24 |   // Process WITH queries if they exist
 25 |   if (query.with && query.with.length > 0) {
 26 |     // Process each WITH query in order
 27 |     for (const withQuery of query.with) {
 28 |       // Ensure the WITH query has an alias
 29 |       if (!withQuery.as) {
 30 |         throw new Error(`WITH query must have an "as" property`)
 31 |       }
 32 | 
 33 |       // Ensure the WITH query is not keyed
 34 |       if ((withQuery as Query).keyBy !== undefined) {
 35 |         throw new Error(`WITH query cannot have a "keyBy" property`)
 36 |       }
 37 | 
 38 |       // Check if this CTE name already exists in the inputs
 39 |       if (allInputs[withQuery.as]) {
 40 |         throw new Error(`CTE with name "${withQuery.as}" already exists`)
 41 |       }
 42 | 
 43 |       // Create a new query without the 'with' property to avoid circular references
 44 |       const withQueryWithoutWith = { ...withQuery, with: undefined }
 45 | 
 46 |       // Compile the WITH query using the current set of inputs
 47 |       // (which includes previously compiled WITH queries)
 48 |       const compiledWithQuery = compileQueryPipeline(
 49 |         withQueryWithoutWith,
 50 |         allInputs
 51 |       )
 52 | 
 53 |       // Add the compiled query to the inputs map using its alias
 54 |       allInputs[withQuery.as] = compiledWithQuery as IStreamBuilder<
 55 |         Record<string, unknown>
 56 |       >
 57 |     }
 58 |   }
 59 | 
 60 |   // Create a map of table aliases to inputs
 61 |   const tables: Record<string, IStreamBuilder<Record<string, unknown>>> = {}
 62 | 
 63 |   // The main table is the one in the FROM clause
 64 |   const mainTableAlias = query.as || query.from
 65 | 
 66 |   // Get the main input from the inputs map (now including CTEs)
 67 |   const input = allInputs[query.from]
 68 |   if (!input) {
 69 |     throw new Error(`Input for table "${query.from}" not found in inputs map`)
 70 |   }
 71 | 
 72 |   tables[mainTableAlias] = input
 73 | 
 74 |   // Prepare the initial pipeline with the main table wrapped in its alias
 75 |   let pipeline = input.pipe(
 76 |     map((row: unknown) => {
 77 |       // Initialize the record with a nested structure
 78 |       return { [mainTableAlias]: row } as Record<string, unknown>
 79 |     })
 80 |   )
 81 | 
 82 |   // Process JOIN clauses if they exist
 83 |   if (query.join) {
 84 |     pipeline = processJoinClause(
 85 |       pipeline,
 86 |       query,
 87 |       tables,
 88 |       mainTableAlias,
 89 |       allInputs
 90 |     )
 91 |   }
 92 | 
 93 |   // Process the WHERE clause if it exists
 94 |   if (query.where) {
 95 |     pipeline = pipeline.pipe(
 96 |       filter((nestedRow) => {
 97 |         const result = evaluateConditionOnNestedRow(
 98 |           nestedRow,
 99 |           query.where as Condition,
100 |           mainTableAlias
101 |         )
102 |         return result
103 |       })
104 |     )
105 |   }
106 | 
107 |   // Process the GROUP BY clause if it exists
108 |   if (query.groupBy) {
109 |     pipeline = processGroupBy(pipeline, query, mainTableAlias)
110 |   }
111 | 
112 |   // Process the HAVING clause if it exists
113 |   // This works similarly to WHERE but is applied after any aggregations
114 |   if (query.having) {
115 |     pipeline = pipeline.pipe(
116 |       filter((row) => {
117 |         // For HAVING, we're working with the flattened row that contains both
118 |         // the group by keys and the aggregate results directly
119 |         const result = evaluateConditionOnNestedRow(
120 |           { [mainTableAlias]: row, ...row } as Record<string, unknown>,
121 |           query.having as Condition,
122 |           mainTableAlias
123 |         )
124 |         return result
125 |       })
126 |     )
127 |   }
128 | 
129 |   // Process the SELECT clause - this is where we flatten the structure
130 |   pipeline = processSelect(pipeline, query, mainTableAlias, allInputs)
131 | 
132 |   let resultPipeline: IStreamBuilder<
133 |     Record<string, unknown> | [string | number, Record<string, unknown>]
134 |   > = pipeline
135 | 
136 |   // Process keyBy parameter if it exists
137 |   if (query.keyBy) {
138 |     resultPipeline = processKeyBy(resultPipeline, query)
139 |   }
140 | 
141 |   // Process orderBy parameter if it exists
142 |   if (query.orderBy) {
143 |     resultPipeline = processOrderBy(resultPipeline, query, mainTableAlias)
144 |   } else if (query.limit !== undefined || query.offset !== undefined) {
145 |     // If there's a limit or offset without orderBy, throw an error
146 |     throw new Error(
147 |       `LIMIT and OFFSET require an ORDER BY clause to ensure deterministic results`
148 |     )
149 |   }
150 | 
151 |   return resultPipeline as T
152 | }
153 | 


--------------------------------------------------------------------------------
/packages/db/src/query/select.ts:
--------------------------------------------------------------------------------
  1 | import { map } from "@electric-sql/d2ts"
  2 | import {
  3 |   evaluateOperandOnNestedRow,
  4 |   extractValueFromNestedRow,
  5 | } from "./extractors"
  6 | import type { IStreamBuilder } from "@electric-sql/d2ts"
  7 | import type { ConditionOperand, Query } from "./schema"
  8 | 
  9 | export function processSelect(
 10 |   pipeline: IStreamBuilder<Record<string, unknown>>,
 11 |   query: Query,
 12 |   mainTableAlias: string,
 13 |   inputs: Record<string, IStreamBuilder<Record<string, unknown>>>
 14 | ) {
 15 |   return pipeline.pipe(
 16 |     map((nestedRow: Record<string, unknown>) => {
 17 |       const result: Record<string, unknown> = {}
 18 | 
 19 |       // Check if this is a grouped result (has no nested table structure)
 20 |       // If it's a grouped result, we need to handle it differently
 21 |       const isGroupedResult =
 22 |         query.groupBy &&
 23 |         Object.keys(nestedRow).some(
 24 |           (key) =>
 25 |             !Object.keys(inputs).includes(key) &&
 26 |             typeof nestedRow[key] !== `object`
 27 |         )
 28 | 
 29 |       for (const item of query.select) {
 30 |         if (typeof item === `string`) {
 31 |           // Handle wildcard select - all columns from all tables
 32 |           if ((item as string) === `@*`) {
 33 |             // For grouped results, just return the row as is
 34 |             if (isGroupedResult) {
 35 |               Object.assign(result, nestedRow)
 36 |             } else {
 37 |               // Extract all columns from all tables
 38 |               Object.assign(result, extractAllColumnsFromAllTables(nestedRow))
 39 |             }
 40 |             continue
 41 |           }
 42 | 
 43 |           // Handle @table.* syntax - all columns from a specific table
 44 |           if (
 45 |             (item as string).startsWith(`@`) &&
 46 |             (item as string).endsWith(`.*`)
 47 |           ) {
 48 |             const tableAlias = (item as string).slice(1, -2) // Remove the '@' and '.*' parts
 49 | 
 50 |             // For grouped results, check if we have columns from this table
 51 |             if (isGroupedResult) {
 52 |               // In grouped results, we don't have the nested structure anymore
 53 |               // So we can't extract by table. Just continue to the next item.
 54 |               continue
 55 |             } else {
 56 |               // Extract all columns from the specified table
 57 |               Object.assign(
 58 |                 result,
 59 |                 extractAllColumnsFromTable(nestedRow, tableAlias)
 60 |               )
 61 |             }
 62 |             continue
 63 |           }
 64 | 
 65 |           // Handle simple column references like "@table.column" or "@column"
 66 |           if ((item as string).startsWith(`@`)) {
 67 |             const columnRef = (item as string).substring(1)
 68 |             const alias = columnRef
 69 | 
 70 |             // For grouped results, check if the column is directly in the row first
 71 |             if (isGroupedResult && columnRef in nestedRow) {
 72 |               result[alias] = nestedRow[columnRef]
 73 |             } else {
 74 |               // Extract the value from the nested structure
 75 |               result[alias] = extractValueFromNestedRow(
 76 |                 nestedRow,
 77 |                 columnRef,
 78 |                 mainTableAlias,
 79 |                 undefined
 80 |               )
 81 |             }
 82 | 
 83 |             // If the alias contains a dot (table.column),
 84 |             // use just the column part as the field name
 85 |             if (alias.includes(`.`)) {
 86 |               const columnName = alias.split(`.`)[1]
 87 |               result[columnName!] = result[alias]
 88 |               delete result[alias]
 89 |             }
 90 |           }
 91 |         } else {
 92 |           // Handle aliased columns like { alias: "@column_name" }
 93 |           for (const [alias, expr] of Object.entries(item)) {
 94 |             if (typeof expr === `string` && (expr as string).startsWith(`@`)) {
 95 |               const columnRef = (expr as string).substring(1)
 96 | 
 97 |               // For grouped results, check if the column is directly in the row first
 98 |               if (isGroupedResult && columnRef in nestedRow) {
 99 |                 result[alias] = nestedRow[columnRef]
100 |               } else {
101 |                 // Extract the value from the nested structure
102 |                 result[alias] = extractValueFromNestedRow(
103 |                   nestedRow,
104 |                   columnRef,
105 |                   mainTableAlias,
106 |                   undefined
107 |                 )
108 |               }
109 |             } else if (typeof expr === `object`) {
110 |               // For grouped results, the aggregate results are already in the row
111 |               if (isGroupedResult && alias in nestedRow) {
112 |                 result[alias] = nestedRow[alias]
113 |               } else {
114 |                 // This might be a function call
115 |                 result[alias] = evaluateOperandOnNestedRow(
116 |                   nestedRow,
117 |                   expr as ConditionOperand,
118 |                   mainTableAlias,
119 |                   undefined
120 |                 )
121 |               }
122 |             }
123 |           }
124 |         }
125 |       }
126 | 
127 |       return result
128 |     })
129 |   )
130 | }
131 | 
132 | // Helper function to extract all columns from all tables in a nested row
133 | function extractAllColumnsFromAllTables(
134 |   nestedRow: Record<string, unknown>
135 | ): Record<string, unknown> {
136 |   const result: Record<string, unknown> = {}
137 | 
138 |   // Process each table in the nested row
139 |   for (const [tableAlias, tableData] of Object.entries(nestedRow)) {
140 |     if (tableData && typeof tableData === `object`) {
141 |       // Add all columns from this table to the result
142 |       // If there are column name conflicts, the last table's columns will overwrite previous ones
143 |       Object.assign(result, extractAllColumnsFromTable(nestedRow, tableAlias))
144 |     }
145 |   }
146 | 
147 |   return result
148 | }
149 | 
150 | // Helper function to extract all columns from a table in a nested row
151 | function extractAllColumnsFromTable(
152 |   nestedRow: Record<string, unknown>,
153 |   tableAlias: string
154 | ): Record<string, unknown> {
155 |   const result: Record<string, unknown> = {}
156 | 
157 |   // Get the table data
158 |   const tableData = nestedRow[tableAlias] as
159 |     | Record<string, unknown>
160 |     | null
161 |     | undefined
162 | 
163 |   if (!tableData || typeof tableData !== `object`) {
164 |     return result
165 |   }
166 | 
167 |   // Add all columns from the table to the result
168 |   for (const [columnName, value] of Object.entries(tableData)) {
169 |     result[columnName] = value
170 |   }
171 | 
172 |   return result
173 | }
174 | 


--------------------------------------------------------------------------------
/packages/db/src/transactions.ts:
--------------------------------------------------------------------------------
  1 | import { createDeferred } from "./deferred"
  2 | import type { Deferred } from "./deferred"
  3 | import type {
  4 |   PendingMutation,
  5 |   TransactionConfig,
  6 |   TransactionState,
  7 | } from "./types"
  8 | 
  9 | function generateUUID() {
 10 |   // Check if crypto.randomUUID is available (modern browsers and Node.js 15+)
 11 |   if (
 12 |     typeof crypto !== `undefined` &&
 13 |     typeof crypto.randomUUID === `function`
 14 |   ) {
 15 |     return crypto.randomUUID()
 16 |   }
 17 | 
 18 |   // Fallback implementation for older environments
 19 |   return `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`.replace(/[xy]/g, function (c) {
 20 |     const r = (Math.random() * 16) | 0
 21 |     const v = c === `x` ? r : (r & 0x3) | 0x8
 22 |     return v.toString(16)
 23 |   })
 24 | }
 25 | 
 26 | const transactions: Array<Transaction> = []
 27 | 
 28 | export function createTransaction(config: TransactionConfig): Transaction {
 29 |   if (typeof config.mutationFn === `undefined`) {
 30 |     throw `mutationFn is required when creating a transaction`
 31 |   }
 32 | 
 33 |   let transactionId = config.id
 34 |   if (!transactionId) {
 35 |     transactionId = generateUUID()
 36 |   }
 37 |   const newTransaction = new Transaction({ ...config, id: transactionId })
 38 |   transactions.push(newTransaction)
 39 | 
 40 |   return newTransaction
 41 | }
 42 | 
 43 | let transactionStack: Array<Transaction> = []
 44 | 
 45 | export function getActiveTransaction(): Transaction | undefined {
 46 |   if (transactionStack.length > 0) {
 47 |     return transactionStack.slice(-1)[0]
 48 |   } else {
 49 |     return undefined
 50 |   }
 51 | }
 52 | 
 53 | function registerTransaction(tx: Transaction) {
 54 |   transactionStack.push(tx)
 55 | }
 56 | 
 57 | function unregisterTransaction(tx: Transaction) {
 58 |   transactionStack = transactionStack.filter((t) => t.id !== tx.id)
 59 | }
 60 | 
 61 | export class Transaction {
 62 |   public id: string
 63 |   public state: TransactionState
 64 |   public mutationFn
 65 |   public mutations: Array<PendingMutation<any>>
 66 |   public isPersisted: Deferred<Transaction>
 67 |   public autoCommit: boolean
 68 |   public createdAt: Date
 69 |   public metadata: Record<string, unknown>
 70 |   public error?: {
 71 |     message: string
 72 |     error: Error
 73 |   }
 74 | 
 75 |   constructor(config: TransactionConfig) {
 76 |     this.id = config.id!
 77 |     this.mutationFn = config.mutationFn
 78 |     this.state = `pending`
 79 |     this.mutations = []
 80 |     this.isPersisted = createDeferred()
 81 |     this.autoCommit = config.autoCommit ?? true
 82 |     this.createdAt = new Date()
 83 |     this.metadata = config.metadata ?? {}
 84 |   }
 85 | 
 86 |   setState(newState: TransactionState) {
 87 |     this.state = newState
 88 |   }
 89 | 
 90 |   mutate(callback: () => void): Transaction {
 91 |     if (this.state !== `pending`) {
 92 |       throw `You can no longer call .mutate() as the transaction is no longer pending`
 93 |     }
 94 | 
 95 |     registerTransaction(this)
 96 |     try {
 97 |       callback()
 98 |     } finally {
 99 |       unregisterTransaction(this)
100 |     }
101 | 
102 |     if (this.autoCommit) {
103 |       this.commit()
104 |     }
105 | 
106 |     return this
107 |   }
108 | 
109 |   applyMutations(mutations: Array<PendingMutation<any>>): void {
110 |     for (const newMutation of mutations) {
111 |       const existingIndex = this.mutations.findIndex(
112 |         (m) => m.key === newMutation.key
113 |       )
114 | 
115 |       if (existingIndex >= 0) {
116 |         // Replace existing mutation
117 |         this.mutations[existingIndex] = newMutation
118 |       } else {
119 |         // Insert new mutation
120 |         this.mutations.push(newMutation)
121 |       }
122 |     }
123 |   }
124 | 
125 |   rollback(config?: { isSecondaryRollback?: boolean }): Transaction {
126 |     const isSecondaryRollback = config?.isSecondaryRollback ?? false
127 |     if (this.state === `completed`) {
128 |       throw `You can no longer call .rollback() as the transaction is already completed`
129 |     }
130 | 
131 |     this.setState(`failed`)
132 | 
133 |     // See if there's any other transactions w/ mutations on the same keys
134 |     // and roll them back as well.
135 |     if (!isSecondaryRollback) {
136 |       const mutationKeys = new Set()
137 |       this.mutations.forEach((m) => mutationKeys.add(m.key))
138 |       transactions.forEach(
139 |         (t) =>
140 |           t.state === `pending` &&
141 |           t.mutations.some((m) => mutationKeys.has(m.key)) &&
142 |           t.rollback({ isSecondaryRollback: true })
143 |       )
144 |     }
145 | 
146 |     // Reject the promise
147 |     this.isPersisted.reject(this.error?.error)
148 | 
149 |     this.touchCollection()
150 | 
151 |     return this
152 |   }
153 | 
154 |   // Tell collection that something has changed with the transaction
155 |   touchCollection(): void {
156 |     const hasCalled = new Set()
157 |     this.mutations.forEach((mutation) => {
158 |       if (!hasCalled.has(mutation.collection.id)) {
159 |         mutation.collection.transactions.setState((state) => state)
160 |         mutation.collection.commitPendingTransactions()
161 |         hasCalled.add(mutation.collection.id)
162 |       }
163 |     })
164 |   }
165 | 
166 |   async commit(): Promise<Transaction> {
167 |     if (this.state !== `pending`) {
168 |       throw `You can no longer call .commit() as the transaction is no longer pending`
169 |     }
170 | 
171 |     this.setState(`persisting`)
172 | 
173 |     if (this.mutations.length === 0) {
174 |       this.setState(`completed`)
175 |     }
176 | 
177 |     // Run mutationFn
178 |     try {
179 |       await this.mutationFn({ transaction: this })
180 | 
181 |       this.setState(`completed`)
182 |       this.touchCollection()
183 | 
184 |       this.isPersisted.resolve(this)
185 |     } catch (error) {
186 |       // Update transaction with error information
187 |       this.error = {
188 |         message: error instanceof Error ? error.message : String(error),
189 |         error: error instanceof Error ? error : new Error(String(error)),
190 |       }
191 | 
192 |       // rollback the transaction
193 |       return this.rollback()
194 |     }
195 | 
196 |     return this
197 |   }
198 | }
199 | 


--------------------------------------------------------------------------------
/packages/db/src/types.ts:
--------------------------------------------------------------------------------
  1 | import type { Collection } from "./collection"
  2 | import type { StandardSchemaV1 } from "@standard-schema/spec"
  3 | import type { Transaction } from "./transactions"
  4 | 
  5 | export type TransactionState = `pending` | `persisting` | `completed` | `failed`
  6 | 
  7 | /**
  8 |  * Represents a pending mutation within a transaction
  9 |  * Contains information about the original and modified data, as well as metadata
 10 |  */
 11 | export interface PendingMutation<T extends object = Record<string, unknown>> {
 12 |   mutationId: string
 13 |   original: Record<string, unknown>
 14 |   modified: Record<string, unknown>
 15 |   changes: Record<string, unknown>
 16 |   key: string
 17 |   type: OperationType
 18 |   metadata: unknown
 19 |   syncMetadata: Record<string, unknown>
 20 |   createdAt: Date
 21 |   updatedAt: Date
 22 |   collection: Collection<T>
 23 | }
 24 | 
 25 | /**
 26 |  * Configuration options for creating a new transaction
 27 |  */
 28 | export type MutationFnParams = {
 29 |   transaction: Transaction
 30 | }
 31 | 
 32 | export type MutationFn = (params: MutationFnParams) => Promise<any>
 33 | 
 34 | export interface TransactionConfig {
 35 |   /** Unique identifier for the transaction */
 36 |   id?: string
 37 |   /* If the transaction should autocommit after a mutate call or should commit be called explicitly */
 38 |   autoCommit?: boolean
 39 |   mutationFn: MutationFn
 40 |   /** Custom metadata to associate with the transaction */
 41 |   metadata?: Record<string, unknown>
 42 | }
 43 | 
 44 | export type { Transaction }
 45 | 
 46 | type Value<TExtensions = never> =
 47 |   | string
 48 |   | number
 49 |   | boolean
 50 |   | bigint
 51 |   | null
 52 |   | TExtensions
 53 |   | Array<Value<TExtensions>>
 54 |   | { [key: string]: Value<TExtensions> }
 55 | 
 56 | export type Row<TExtensions = never> = Record<string, Value<TExtensions>>
 57 | 
 58 | export type OperationType = `insert` | `update` | `delete`
 59 | 
 60 | export interface SyncConfig<T extends object = Record<string, unknown>> {
 61 |   sync: (params: {
 62 |     collection: Collection<T>
 63 |     begin: () => void
 64 |     write: (message: ChangeMessage<T>) => void
 65 |     commit: () => void
 66 |   }) => void
 67 | 
 68 |   /**
 69 |    * Get the sync metadata for insert operations
 70 |    * @returns Record containing primaryKey and relation information
 71 |    */
 72 |   getSyncMetadata?: () => Record<string, unknown>
 73 | }
 74 | 
 75 | export interface ChangeMessage<T extends object = Record<string, unknown>> {
 76 |   key: string
 77 |   value: T
 78 |   previousValue?: T
 79 |   type: OperationType
 80 |   metadata?: Record<string, unknown>
 81 | }
 82 | 
 83 | export interface OptimisticChangeMessage<
 84 |   T extends object = Record<string, unknown>,
 85 | > extends ChangeMessage<T> {
 86 |   // Is this change message part of an active transaction. Only applies to optimistic changes.
 87 |   isActive?: boolean
 88 | }
 89 | 
 90 | /**
 91 |  * The Standard Schema interface.
 92 |  * This follows the standard-schema specification: https://github.com/standard-schema/standard-schema
 93 |  */
 94 | export type StandardSchema<T> = StandardSchemaV1 & {
 95 |   "~standard": {
 96 |     types?: {
 97 |       input: T
 98 |       output: T
 99 |     }
100 |   }
101 | }
102 | 
103 | /**
104 |  * Type alias for StandardSchema
105 |  */
106 | export type StandardSchemaAlias<T = unknown> = StandardSchema<T>
107 | 
108 | export interface OperationConfig {
109 |   metadata?: Record<string, unknown>
110 | }
111 | 
112 | export interface InsertConfig {
113 |   key?: string | Array<string | undefined>
114 |   metadata?: Record<string, unknown>
115 | }
116 | 
117 | export interface CollectionConfig<T extends object = Record<string, unknown>> {
118 |   id: string
119 |   sync: SyncConfig<T>
120 |   schema?: StandardSchema<T>
121 | }
122 | 
123 | export type ChangesPayload<T extends object = Record<string, unknown>> = Array<
124 |   ChangeMessage<T>
125 | >
126 | 


--------------------------------------------------------------------------------
/packages/db/src/utils.ts:
--------------------------------------------------------------------------------
 1 | export function getLockedObjects(): Set<string> {
 2 |   // Stub implementation that returns an empty Set
 3 |   return new Set()
 4 | }
 5 | 
 6 | let globalVersion = 0
 7 | 
 8 | export function getGlobalVersion(): number {
 9 |   return globalVersion
10 | }
11 | 
12 | export function advanceGlobalVersion(): number {
13 |   console.log(`==== advancing global version`, globalVersion + 1)
14 |   return globalVersion++
15 | }
16 | 


--------------------------------------------------------------------------------
/packages/db/tests/SortedMap.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it } from "vitest"
  2 | import { SortedMap } from "../src/SortedMap"
  3 | 
  4 | describe(`SortedMap`, () => {
  5 |   it(`maintains sorted order by values`, () => {
  6 |     const map = new SortedMap<string, number>()
  7 |     map.set(`c`, 3)
  8 |     map.set(`a`, 1)
  9 |     map.set(`b`, 2)
 10 | 
 11 |     const values = Array.from(map.values())
 12 |     expect(values).toEqual([1, 2, 3])
 13 |   })
 14 | 
 15 |   it(`works with custom comparator`, () => {
 16 |     // Create a map that sorts numbers in descending order
 17 |     const map = new SortedMap<string, number>((a, b) => b - a)
 18 |     map.set(`a`, 1)
 19 |     map.set(`c`, 3)
 20 |     map.set(`b`, 2)
 21 | 
 22 |     const values = Array.from(map.values())
 23 |     expect(values).toEqual([3, 2, 1])
 24 |   })
 25 | 
 26 |   it(`correctly handles updates`, () => {
 27 |     const map = new SortedMap<string, number>()
 28 |     map.set(`a`, 1)
 29 |     map.set(`b`, 3)
 30 |     map.set(`a`, 2) // update existing key
 31 | 
 32 |     expect(map.size).toBe(2)
 33 |     expect(map.get(`a`)).toBe(2)
 34 |     const values = Array.from(map.values())
 35 |     expect(values).toEqual([2, 3])
 36 |   })
 37 | 
 38 |   it(`correctly handles deletions`, () => {
 39 |     const map = new SortedMap<string, number>()
 40 |     map.set(`a`, 1)
 41 |     map.set(`b`, 2)
 42 |     map.set(`c`, 3)
 43 | 
 44 |     map.delete(`b`)
 45 |     expect(map.size).toBe(2)
 46 |     const values = Array.from(map.values())
 47 |     expect(values).toEqual([1, 3])
 48 |   })
 49 | 
 50 |   it(`implements iteration methods correctly`, () => {
 51 |     const map = new SortedMap<string, number>()
 52 |     map.set(`b`, 2)
 53 |     map.set(`a`, 1)
 54 |     map.set(`c`, 3)
 55 | 
 56 |     // Test entries()
 57 |     const entries = Array.from(map.entries())
 58 |     expect(entries).toEqual([
 59 |       [`a`, 1],
 60 |       [`b`, 2],
 61 |       [`c`, 3],
 62 |     ])
 63 | 
 64 |     // Test values()
 65 |     const values = Array.from(map.values())
 66 |     expect(values).toEqual([1, 2, 3])
 67 | 
 68 |     // Test forEach
 69 |     const forEachResults: Array<number> = []
 70 |     map.forEach((value) => forEachResults.push(value))
 71 |     expect(forEachResults).toEqual([1, 2, 3])
 72 |   })
 73 | 
 74 |   // Test to cover the defaultComparator method (line 32)
 75 |   it(`uses defaultComparator correctly when no custom comparator is provided`, () => {
 76 |     const map = new SortedMap<string, string>()
 77 |     map.set(`c`, `charlie`)
 78 |     map.set(`a`, `alpha`)
 79 |     map.set(`b`, `bravo`)
 80 | 
 81 |     const values = Array.from(map.values())
 82 |     expect(values).toEqual([`alpha`, `bravo`, `charlie`])
 83 | 
 84 |     // Test with values that would be sorted differently by a custom comparator
 85 |     const numericMap = new SortedMap<string, string>()
 86 |     numericMap.set(`a`, `10`)
 87 |     numericMap.set(`b`, `2`)
 88 | 
 89 |     // Default string comparison will put '10' before '2'
 90 |     const numericValues = Array.from(numericMap.values())
 91 |     expect(numericValues).toEqual([`10`, `2`])
 92 |   })
 93 | 
 94 |   // Test for keys() method
 95 |   it(`provides keys in sorted order`, () => {
 96 |     const map = new SortedMap<string, number>()
 97 |     map.set(`c`, 3)
 98 |     map.set(`a`, 1)
 99 |     map.set(`b`, 2)
100 | 
101 |     const keys = Array.from(map.keys())
102 |     expect(keys).toEqual([`a`, `b`, `c`])
103 |   })
104 | 
105 |   // Test for Symbol.iterator implementation
106 |   it(`supports direct iteration with for...of`, () => {
107 |     const map = new SortedMap<string, number>()
108 |     map.set(`c`, 3)
109 |     map.set(`a`, 1)
110 |     map.set(`b`, 2)
111 | 
112 |     const entries: Array<[string, number]> = []
113 |     for (const entry of map) {
114 |       entries.push(entry)
115 |     }
116 | 
117 |     expect(entries).toEqual([
118 |       [`a`, 1],
119 |       [`b`, 2],
120 |       [`c`, 3],
121 |     ])
122 |   })
123 | 
124 |   // Test for clear method
125 |   it(`clears all entries`, () => {
126 |     const map = new SortedMap<string, number>()
127 |     map.set(`a`, 1)
128 |     map.set(`b`, 2)
129 | 
130 |     map.clear()
131 |     expect(map.size).toBe(0)
132 |     expect(Array.from(map.entries())).toEqual([])
133 |   })
134 | })
135 | 


--------------------------------------------------------------------------------
/packages/db/tests/collection-getters.test.ts:
--------------------------------------------------------------------------------
  1 | import { beforeEach, describe, expect, it, vi } from "vitest"
  2 | import { Collection } from "../src/collection"
  3 | import type { ChangeMessage, CollectionConfig } from "../src/types"
  4 | 
  5 | describe(`Collection getters`, () => {
  6 |   let collection: Collection
  7 |   let mockSync: {
  8 |     sync: (params: {
  9 |       collection: Collection
 10 |       begin: () => void
 11 |       write: (message: ChangeMessage) => void
 12 |       commit: () => void
 13 |     }) => void
 14 |   }
 15 |   let mockMutationFn: { persist: () => Promise<void> }
 16 |   let config: CollectionConfig
 17 | 
 18 |   beforeEach(() => {
 19 |     mockSync = {
 20 |       sync: vi.fn(({ begin, write, commit }) => {
 21 |         // Simulate a sync operation
 22 |         begin()
 23 |         write({
 24 |           type: `insert`,
 25 |           key: `item1`,
 26 |           value: { id: `item1`, name: `Item 1` },
 27 |         })
 28 |         write({
 29 |           type: `insert`,
 30 |           key: `item2`,
 31 |           value: { id: `item2`, name: `Item 2` },
 32 |         })
 33 |         commit()
 34 |       }),
 35 |     }
 36 | 
 37 |     mockMutationFn = {
 38 |       persist: vi.fn().mockResolvedValue(undefined),
 39 |     }
 40 | 
 41 |     config = {
 42 |       id: `test-collection`,
 43 |       sync: mockSync,
 44 |       mutationFn: mockMutationFn,
 45 |     }
 46 | 
 47 |     collection = new Collection(config)
 48 |   })
 49 | 
 50 |   describe(`state getter`, () => {
 51 |     it(`returns the current state as a Map`, () => {
 52 |       const state = collection.state
 53 |       expect(state).toBeInstanceOf(Map)
 54 |       expect(state.size).toBe(2)
 55 |       expect(state.get(`item1`)).toEqual({ id: `item1`, name: `Item 1` })
 56 |       expect(state.get(`item2`)).toEqual({ id: `item2`, name: `Item 2` })
 57 |     })
 58 |   })
 59 | 
 60 |   describe(`stateWhenReady`, () => {
 61 |     it(`resolves immediately if data is already available`, async () => {
 62 |       const statePromise = collection.stateWhenReady()
 63 |       const state = await statePromise
 64 |       expect(state).toBeInstanceOf(Map)
 65 |       expect(state.size).toBe(2)
 66 |     })
 67 | 
 68 |     it(`waits for data if not yet available`, async () => {
 69 |       // Create a new collection with a sync that doesn't immediately commit
 70 |       let commitFn: () => void
 71 | 
 72 |       const delayedSyncMock = {
 73 |         sync: vi.fn(({ begin, write, commit }) => {
 74 |           // Start sync but don't commit yet
 75 |           begin()
 76 |           write({
 77 |             type: `insert`,
 78 |             key: `delayed-item`,
 79 |             value: { id: `delayed-item`, name: `Delayed Item` },
 80 |           })
 81 |           // Save the commit function for later
 82 |           commitFn = commit
 83 |         }),
 84 |       }
 85 | 
 86 |       const delayedCollection = new Collection({
 87 |         id: `delayed-collection`,
 88 |         sync: delayedSyncMock,
 89 |         mutationFn: mockMutationFn,
 90 |       })
 91 | 
 92 |       // Start the stateWhenReady promise
 93 |       const statePromise = delayedCollection.stateWhenReady()
 94 | 
 95 |       // Manually trigger the commit after a short delay
 96 |       setTimeout(() => {
 97 |         commitFn()
 98 |       }, 10)
 99 | 
100 |       // Now the promise should resolve
101 |       const state = await statePromise
102 |       expect(state).toBeInstanceOf(Map)
103 |       expect(state.get(`delayed-item`)).toEqual({
104 |         id: `delayed-item`,
105 |         name: `Delayed Item`,
106 |       })
107 |     })
108 |   })
109 | 
110 |   describe(`toArray getter`, () => {
111 |     it(`returns the current state as an array`, () => {
112 |       const array = collection.toArray
113 |       expect(Array.isArray(array)).toBe(true)
114 |       expect(array.length).toBe(2)
115 |       expect(array).toContainEqual({ id: `item1`, name: `Item 1` })
116 |       expect(array).toContainEqual({ id: `item2`, name: `Item 2` })
117 |     })
118 |   })
119 | 
120 |   describe(`toArrayWhenReady`, () => {
121 |     it(`resolves immediately if data is already available`, async () => {
122 |       const arrayPromise = collection.toArrayWhenReady()
123 |       const array = await arrayPromise
124 |       expect(Array.isArray(array)).toBe(true)
125 |       expect(array.length).toBe(2)
126 |     })
127 | 
128 |     it(`waits for data if not yet available`, async () => {
129 |       // Create a new collection with a sync that doesn't immediately commit
130 |       let commitFn: () => void
131 | 
132 |       const delayedSyncMock = {
133 |         sync: vi.fn(({ begin, write, commit }) => {
134 |           // Start sync but don't commit yet
135 |           begin()
136 |           write({
137 |             type: `insert`,
138 |             key: `delayed-item`,
139 |             value: { id: `delayed-item`, name: `Delayed Item` },
140 |           })
141 |           // Save the commit function for later
142 |           commitFn = commit
143 |         }),
144 |       }
145 | 
146 |       const delayedCollection = new Collection({
147 |         id: `delayed-collection`,
148 |         sync: delayedSyncMock,
149 |         mutationFn: mockMutationFn,
150 |       })
151 | 
152 |       // Start the toArrayWhenReady promise
153 |       const arrayPromise = delayedCollection.toArrayWhenReady()
154 | 
155 |       // Manually trigger the commit after a short delay
156 |       setTimeout(() => {
157 |         commitFn()
158 |       }, 10)
159 | 
160 |       // Now the promise should resolve
161 |       const array = await arrayPromise
162 |       expect(Array.isArray(array)).toBe(true)
163 |       expect(array).toContainEqual({ id: `delayed-item`, name: `Delayed Item` })
164 |     })
165 |   })
166 | })
167 | 


--------------------------------------------------------------------------------
/packages/db/tests/deferred.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it } from "vitest"
  2 | import { createDeferred } from "../src/deferred"
  3 | import type { Deferred } from "../src/deferred"
  4 | 
  5 | describe(`Deferred`, () => {
  6 |   it(`should create a deferred object with the correct shape`, () => {
  7 |     const deferred = createDeferred<number>()
  8 |     expect(deferred).toHaveProperty(`promise`)
  9 |     expect(deferred).toHaveProperty(`resolve`)
 10 |     expect(deferred).toHaveProperty(`reject`)
 11 |     expect(deferred).toHaveProperty(`isPending`)
 12 |     expect(typeof deferred.resolve).toBe(`function`)
 13 |     expect(typeof deferred.reject).toBe(`function`)
 14 |     expect(typeof deferred.isPending).toBe(`function`)
 15 |   })
 16 | 
 17 |   it(`should resolve with the correct value`, async () => {
 18 |     const deferred = createDeferred<number>()
 19 |     deferred.resolve(42)
 20 |     const result = await deferred.promise
 21 |     expect(result).toBe(42)
 22 |   })
 23 | 
 24 |   it(`should reject with the correct error`, async () => {
 25 |     const deferred = createDeferred<number>()
 26 |     const error = new Error(`test error`)
 27 |     deferred.reject(error)
 28 |     await expect(deferred.promise).rejects.toThrow(error)
 29 |   })
 30 | 
 31 |   it(`should track pending state correctly`, () => {
 32 |     const deferred = createDeferred<number>()
 33 |     expect(deferred.isPending()).toBe(true)
 34 |     deferred.resolve(42)
 35 |     expect(deferred.isPending()).toBe(false)
 36 |   })
 37 | 
 38 |   it(`should track pending state after rejection`, async () => {
 39 |     const deferred = createDeferred<number>()
 40 |     expect(deferred.isPending()).toBe(true)
 41 | 
 42 |     const error = new Error(`test error`)
 43 |     deferred.reject(error)
 44 |     await expect(deferred.promise).rejects.toThrow(error)
 45 |     expect(deferred.isPending()).toBe(false)
 46 |   })
 47 | 
 48 |   it(`should work with different types`, async () => {
 49 |     // String type
 50 |     const stringDeferred = createDeferred<string>()
 51 |     stringDeferred.resolve(`hello`)
 52 |     expect(await stringDeferred.promise).toBe(`hello`)
 53 | 
 54 |     // Object type
 55 |     interface TestObject {
 56 |       foo: string
 57 |       bar: number
 58 |     }
 59 |     const objectDeferred = createDeferred<TestObject>()
 60 |     const testObj = { foo: `test`, bar: 123 }
 61 |     objectDeferred.resolve(testObj)
 62 |     expect(await objectDeferred.promise).toEqual(testObj)
 63 | 
 64 |     // Array type
 65 |     const arrayDeferred = createDeferred<Array<number>>()
 66 |     arrayDeferred.resolve([1, 2, 3])
 67 |     expect(await arrayDeferred.promise).toEqual([1, 2, 3])
 68 | 
 69 |     // Union type
 70 |     const unionDeferred = createDeferred<string | number>()
 71 |     unionDeferred.resolve(42)
 72 |     expect(await unionDeferred.promise).toBe(42)
 73 |   })
 74 | 
 75 |   it(`should handle promise chaining`, async () => {
 76 |     const deferred = createDeferred<number>()
 77 |     const chainedPromise = deferred.promise
 78 |       .then((x) => x * 2)
 79 |       .then((x) => x.toString())
 80 | 
 81 |     deferred.resolve(21)
 82 |     const result = await chainedPromise
 83 |     expect(result).toBe(`42`)
 84 |   })
 85 | 
 86 |   it(`should handle async resolution`, async () => {
 87 |     const deferred = createDeferred<number>()
 88 |     const asyncValue = Promise.resolve(42)
 89 |     deferred.resolve(asyncValue)
 90 |     const result = await deferred.promise
 91 |     expect(result).toBe(42)
 92 |   })
 93 | 
 94 |   // Type tests - these will fail at compile time if types are wrong
 95 |   it(`type tests`, () => {
 96 |     const numberDeferred: Deferred<number> = createDeferred<number>()
 97 |     numberDeferred.resolve(42) // Should compile
 98 |     // @ts-expect-error - wrong type
 99 |     numberDeferred.resolve(`42`) // Should not compile
100 | 
101 |     const stringDeferred: Deferred<string> = createDeferred<string>()
102 |     stringDeferred.resolve(`hello`) // Should compile
103 |     // @ts-expect-error - wrong type
104 |     stringDeferred.resolve(42) // Should not compile
105 | 
106 |     const promiseDeferred: Deferred<Promise<number>> =
107 |       createDeferred<Promise<number>>()
108 |     promiseDeferred.resolve(Promise.resolve(42)) // Should compile
109 |     // @ts-expect-error - wrong type
110 |     promiseDeferred.resolve(42) // Should not compile
111 |   })
112 | })
113 | 


--------------------------------------------------------------------------------
/packages/db/tests/errors.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from "vitest"
 2 | import { NonRetriableError } from "../src/errors"
 3 | 
 4 | describe(`Errors`, () => {
 5 |   it(`should create a NonRetriableError with the correct name and message`, () => {
 6 |     const errorMessage = `This is a non-retriable error`
 7 |     const error = new NonRetriableError(errorMessage)
 8 | 
 9 |     expect(error).toBeInstanceOf(Error)
10 |     expect(error.name).toBe(`NonRetriableError`)
11 |     expect(error.message).toBe(errorMessage)
12 |   })
13 | 
14 |   it(`should be catchable as an Error`, () => {
15 |     const errorMessage = `This is a non-retriable error`
16 | 
17 |     try {
18 |       throw new NonRetriableError(errorMessage)
19 |     } catch (error) {
20 |       expect(error).toBeInstanceOf(Error)
21 |       expect(error).toBeInstanceOf(NonRetriableError)
22 |       expect((error as Error).message).toBe(errorMessage)
23 |     }
24 |   })
25 | })
26 | 


--------------------------------------------------------------------------------
/packages/db/tests/object-key-map.test.ts:
--------------------------------------------------------------------------------
  1 | import { beforeEach, describe, expect, it } from "vitest"
  2 | import { z } from "zod"
  3 | import { Collection } from "../src/collection"
  4 | import { createTransaction } from "../src/transactions"
  5 | 
  6 | describe(`Object-Key Association`, () => {
  7 |   let collection: Collection<{ name: string; age: number }>
  8 |   let mutationFn: () => {}
  9 | 
 10 |   beforeEach(() => {
 11 |     const schema = z.object({
 12 |       name: z.string(),
 13 |       age: z.number(),
 14 |     })
 15 | 
 16 |     collection = new Collection<{ name: string; age: number }>({
 17 |       id: `test-sync`,
 18 |       schema,
 19 |       sync: {
 20 |         sync: async () => {},
 21 |       },
 22 |     })
 23 |     mutationFn = async () => {}
 24 |   })
 25 | 
 26 |   it(`should associate an object with its key after insert`, () => {
 27 |     // Insert an object
 28 |     const data = { name: `John`, age: 30 }
 29 |     const tx1 = createTransaction({ mutationFn })
 30 |     tx1.mutate(() => collection.insert(data, { key: `user1` }))
 31 | 
 32 |     const item = collection.state.get(`user1`)
 33 | 
 34 |     // Make sure item exists before using it as a key
 35 |     expect(item).toBeDefined()
 36 | 
 37 |     // Update using the object reference
 38 |     const tx2 = createTransaction({ mutationFn })
 39 |     tx2.mutate(() =>
 40 |       collection.update(item, (draft) => {
 41 |         draft.age = 31
 42 |       })
 43 |     )
 44 | 
 45 |     // Verify the update worked
 46 |     const updated = collection.state.get(`user1`)
 47 |     expect(updated).toEqual({ name: `John`, age: 31 })
 48 |   })
 49 | 
 50 |   it(`should work with multiple objects`, () => {
 51 |     // Insert multiple objects
 52 |     const johnData = { name: `John`, age: 30 }
 53 |     const janeData = { name: `Jane`, age: 28 }
 54 | 
 55 |     const tx1 = createTransaction({ mutationFn })
 56 |     tx1.mutate(() =>
 57 |       collection.insert([johnData, janeData], {
 58 |         key: [`user1`, `user2`],
 59 |       })
 60 |     )
 61 | 
 62 |     const john = collection.state.get(`user1`)
 63 |     const jane = collection.state.get(`user2`)
 64 | 
 65 |     // Update multiple objects using their references
 66 |     const tx2 = createTransaction({ mutationFn })
 67 |     tx2.mutate(() =>
 68 |       collection.update([john!, jane!], (items) => {
 69 |         if (items[0] && items[1]) {
 70 |           items[0].age = 31
 71 |           items[1].name = `Jane Doe`
 72 |         }
 73 |       })
 74 |     )
 75 | 
 76 |     // Verify updates
 77 |     expect(collection.state.get(`user1`)).toEqual({ name: `John`, age: 31 })
 78 |     expect(collection.state.get(`user2`)).toEqual({ name: `Jane Doe`, age: 28 })
 79 |   })
 80 | 
 81 |   it(`should handle delete with object reference`, () => {
 82 |     // Insert an object
 83 |     const data = { name: `John`, age: 30 }
 84 |     const tx1 = createTransaction({ mutationFn })
 85 |     tx1.mutate(() => collection.insert(data, { key: `user1` }))
 86 | 
 87 |     const john = collection.state.get(`user1`)
 88 | 
 89 |     // Delete using the object reference
 90 |     const tx2 = createTransaction({ mutationFn })
 91 |     tx2.mutate(() => collection.delete(john))
 92 | 
 93 |     // Verify deletion
 94 |     expect(collection.state.get(`user1`)).toBeUndefined()
 95 |   })
 96 | 
 97 |   it(`should maintain object-key association after updates`, () => {
 98 |     // Insert an object
 99 |     const data = { name: `John`, age: 30 }
100 |     const tx1 = createTransaction({ mutationFn })
101 |     tx1.mutate(() => collection.insert(data, { key: `user1` }))
102 | 
103 |     const john = collection.state.get(`user1`)
104 | 
105 |     // First update
106 |     const tx2 = createTransaction({ mutationFn })
107 |     tx2.mutate(() =>
108 |       collection.update(john, (item) => {
109 |         item.age = 31
110 |       })
111 |     )
112 | 
113 |     // Second update using the same object reference
114 |     const tx3 = createTransaction({ mutationFn })
115 |     tx3.mutate(() =>
116 |       collection.update(john, (item) => {
117 |         item.name = `John Doe`
118 |       })
119 |     )
120 | 
121 |     // Verify both updates worked
122 |     const updated = collection.state.get(`user1`)
123 |     expect(updated).toEqual({ name: `John Doe`, age: 31 })
124 |   })
125 | 
126 |   it(`should throw error when object is not associated with any key`, () => {
127 |     const unknownObject = { name: `Unknown`, age: 25 }
128 | 
129 |     // Try to update using an object that wasn't inserted
130 |     const tx = createTransaction({ mutationFn })
131 |     expect(() => {
132 |       tx.mutate(() =>
133 |         collection.update(unknownObject, (item) => {
134 |           item.age = 26
135 |         })
136 |       )
137 |     }).toThrow()
138 |   })
139 | 
140 |   it(`should support bulk insert with multiple keys`, () => {
141 |     // Insert multiple objects
142 |     const johnData = { name: `John`, age: 30 }
143 |     const janeData = { name: `Jane`, age: 28 }
144 |     const bobData = { name: `Bob`, age: 35 }
145 | 
146 |     const tx = createTransaction({ mutationFn })
147 |     tx.mutate(() =>
148 |       collection.insert([johnData, janeData, bobData], {
149 |         key: [`user1`, `user2`, `user3`],
150 |       })
151 |     )
152 | 
153 |     const john = collection.state.get(`user1`)
154 |     const jane = collection.state.get(`user2`)
155 |     const bob = collection.state.get(`user3`)
156 | 
157 |     // Verify inserts
158 |     expect(john).toEqual({ name: `John`, age: 30 })
159 |     expect(jane).toEqual({ name: `Jane`, age: 28 })
160 |     expect(bob).toEqual({ name: `Bob`, age: 35 })
161 |   })
162 | })
163 | 


--------------------------------------------------------------------------------
/packages/db/tests/preloadCollection.test.ts:
--------------------------------------------------------------------------------
  1 | import { beforeEach, describe, expect, it, vi } from "vitest"
  2 | import { preloadCollection } from "../src/collection"
  3 | import type { CollectionConfig } from "../src/types"
  4 | 
  5 | describe(`preloadCollection`, () => {
  6 |   beforeEach(() => {
  7 |     vi.resetAllMocks()
  8 |   })
  9 | 
 10 |   it(`should resolve once the first commit is done`, async () => {
 11 |     // Create a mock sync function that will call begin, write, and commit
 12 |     let commitFn: () => void
 13 | 
 14 |     const config: { id: string } & CollectionConfig = {
 15 |       id: `test-collection`,
 16 |       sync: {
 17 |         sync: ({ begin, write, commit }) => {
 18 |           // Store the commit function to call it later
 19 |           commitFn = commit
 20 | 
 21 |           // Start the transaction
 22 |           begin()
 23 | 
 24 |           // Write some data
 25 |           write({
 26 |             key: `test`,
 27 |             value: { name: `Test Item` },
 28 |             type: `insert`,
 29 |           })
 30 | 
 31 |           // We'll call commit later in the test
 32 |         },
 33 |       },
 34 |     }
 35 | 
 36 |     // Create a preload promise
 37 |     const preloadPromise = preloadCollection(config)
 38 | 
 39 |     // The promise should not resolve yet
 40 |     let resolved = false
 41 |     preloadPromise.then(() => {
 42 |       resolved = true
 43 |     })
 44 | 
 45 |     // Wait a tick to allow any synchronous resolution
 46 |     await new Promise((resolve) => setTimeout(resolve, 0))
 47 |     expect(resolved).toBe(false)
 48 | 
 49 |     // Now commit the transaction
 50 |     commitFn!()
 51 | 
 52 |     // Wait for the promise to resolve
 53 |     await preloadPromise
 54 |     expect(resolved).toBe(true)
 55 |   })
 56 | 
 57 |   it(`should resolve immediately if already loaded`, async () => {
 58 |     // Create a mock sync function
 59 |     let commitCalled = 0
 60 |     const config: { id: string } & CollectionConfig = {
 61 |       id: `test-collection-2`,
 62 |       sync: {
 63 |         sync: ({ begin, write, commit }) => {
 64 |           begin()
 65 |           write({
 66 |             key: `test`,
 67 |             value: { name: `Test Item` },
 68 |             type: `insert`,
 69 |           })
 70 |           Promise.resolve().then(() => {
 71 |             commit()
 72 |             commitCalled++
 73 |           })
 74 |         },
 75 |       },
 76 |     }
 77 | 
 78 |     // First call should create the collection and wait for commit
 79 |     await preloadCollection(config)
 80 |     expect(commitCalled).toBe(1)
 81 | 
 82 |     // Second call should resolve immediately because collection already exists
 83 |     // and has committed
 84 |     await preloadCollection(config)
 85 |     expect(commitCalled).toBe(1) // Sync should not be called again
 86 |     expect(commitCalled).toBe(1) // Sync should not be called again
 87 |   })
 88 | 
 89 |   it(`should return the same promise for concurrent preload calls`, async () => {
 90 |     let commitFn: () => void
 91 |     let beginCalled = 0
 92 | 
 93 |     const config: { id: string } & CollectionConfig = {
 94 |       id: `test-collection-3`,
 95 |       sync: {
 96 |         sync: ({ begin, write, commit }) => {
 97 |           beginCalled++
 98 |           commitFn = commit
 99 |           begin()
100 |           write({
101 |             key: `test`,
102 |             value: { name: `Test Item` },
103 |             type: `insert`,
104 |           })
105 |           // Don't commit yet
106 |         },
107 |       },
108 |     }
109 | 
110 |     // Create two preload promises
111 |     const promise1 = preloadCollection(config)
112 |     const promise2 = preloadCollection(config)
113 | 
114 |     // They should be the same promise
115 |     expect(promise1).toBe(promise2)
116 |     expect(beginCalled).toBe(1) // Sync should only be called once
117 | 
118 |     // Now commit
119 |     commitFn!()
120 | 
121 |     // Both promises should resolve
122 |     await Promise.all([promise1, promise2])
123 |   })
124 | })
125 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/from.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from "vitest"
 2 | import { queryBuilder } from "../../../src/query/query-builder.js"
 3 | import type { Input, Schema } from "../../../src/query/types.js"
 4 | 
 5 | // Test schema
 6 | interface Employee extends Input {
 7 |   id: number
 8 |   name: string
 9 |   department_id: number | null
10 | }
11 | 
12 | interface Department extends Input {
13 |   id: number
14 |   name: string
15 |   budget: number
16 | }
17 | 
18 | // Make sure TestSchema extends Schema
19 | interface TestSchema extends Schema {
20 |   employees: Employee
21 |   departments: Department
22 | }
23 | 
24 | describe(`QueryBuilder.from`, () => {
25 |   it(`sets the from clause correctly`, () => {
26 |     const query = queryBuilder<TestSchema>().from(`employees`)
27 |     const builtQuery = query._query
28 | 
29 |     expect(builtQuery.from).toBe(`employees`)
30 |     expect(builtQuery.as).toBeUndefined()
31 |   })
32 | 
33 |   it(`sets the from clause with an alias`, () => {
34 |     const query = queryBuilder<TestSchema>().from(`employees`, `e`)
35 |     const builtQuery = query._query
36 | 
37 |     expect(builtQuery.from).toBe(`employees`)
38 |     expect(builtQuery.as).toBe(`e`)
39 |   })
40 | 
41 |   it(`allows chaining other methods after from`, () => {
42 |     const query = queryBuilder<TestSchema>()
43 |       .from(`employees`)
44 |       .where(`@id`, `=`, 1)
45 |       .select(`@id`, `@name`)
46 | 
47 |     const builtQuery = query._query
48 | 
49 |     expect(builtQuery.from).toBe(`employees`)
50 |     expect(builtQuery.where).toBeDefined()
51 |     expect(builtQuery.select).toHaveLength(2)
52 |   })
53 | })
54 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/group-by.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it } from "vitest"
  2 | import { queryBuilder } from "../../../src/query/query-builder.js"
  3 | import type { Input, Schema } from "../../../src/query/types.js"
  4 | 
  5 | // Test schema
  6 | interface Employee extends Input {
  7 |   id: number
  8 |   name: string
  9 |   department_id: number
 10 |   salary: number
 11 | }
 12 | 
 13 | interface Department extends Input {
 14 |   id: number
 15 |   name: string
 16 |   budget: number
 17 |   location: string
 18 | }
 19 | 
 20 | // Make sure TestSchema extends Schema
 21 | interface TestSchema extends Schema {
 22 |   employees: Employee
 23 |   departments: Department
 24 | }
 25 | 
 26 | describe(`QueryBuilder.groupBy`, () => {
 27 |   it(`sets a single property reference as groupBy`, () => {
 28 |     const query = queryBuilder<TestSchema>()
 29 |       .from(`employees`)
 30 |       .groupBy(`@department_id`)
 31 |       .select(`@department_id`, { count: { COUNT: `@id` } as any })
 32 | 
 33 |     const builtQuery = query._query
 34 |     expect(builtQuery.groupBy).toBe(`@department_id`)
 35 |   })
 36 | 
 37 |   it(`sets an array of property references as groupBy`, () => {
 38 |     const query = queryBuilder<TestSchema>()
 39 |       .from(`employees`)
 40 |       .groupBy([`@department_id`, `@salary`])
 41 |       .select(`@department_id`, `@salary`, { count: { COUNT: `@id` } as any })
 42 | 
 43 |     const builtQuery = query._query
 44 |     expect(builtQuery.groupBy).toEqual([`@department_id`, `@salary`])
 45 |   })
 46 | 
 47 |   it(`overrides previous groupBy values`, () => {
 48 |     const query = queryBuilder<TestSchema>()
 49 |       .from(`employees`)
 50 |       .groupBy(`@department_id`)
 51 |       .groupBy(`@salary`) // This should override
 52 |       .select(`@department_id`, `@salary`, { count: { COUNT: `@id` } as any })
 53 | 
 54 |     const builtQuery = query._query
 55 |     expect(builtQuery.groupBy).toBe(`@salary`)
 56 |   })
 57 | 
 58 |   it(`works with joined tables`, () => {
 59 |     const query = queryBuilder<TestSchema>()
 60 |       .from(`employees`, `e`)
 61 |       .join({
 62 |         type: `inner`,
 63 |         from: `departments`,
 64 |         as: `d`,
 65 |         on: [`@e.department_id`, `=`, `@d.id`],
 66 |       })
 67 |       .groupBy(`@d.name`)
 68 |       .select(`@d.name`, { avg_salary: { AVG: `@e.salary` } as any })
 69 | 
 70 |     const builtQuery = query._query
 71 |     expect(builtQuery.groupBy).toBe(`@d.name`)
 72 |   })
 73 | 
 74 |   it(`allows combining with having for filtered aggregations`, () => {
 75 |     const query = queryBuilder<TestSchema>()
 76 |       .from(`employees`, `e`)
 77 |       .join({
 78 |         type: `inner`,
 79 |         from: `departments`,
 80 |         as: `d`,
 81 |         on: [`@e.department_id`, `=`, `@d.id`],
 82 |       })
 83 |       .groupBy(`@d.name`)
 84 |       .having({ SUM: `@e.salary` } as any, `>`, 100000)
 85 |       .select(`@d.name`, { total_salary: { SUM: `@e.salary` } as any })
 86 | 
 87 |     const builtQuery = query._query
 88 |     expect(builtQuery.groupBy).toBe(`@d.name`)
 89 |     expect(builtQuery.having).toEqual([{ SUM: `@e.salary` }, `>`, 100000])
 90 |   })
 91 | 
 92 |   it(`can be combined with other query methods`, () => {
 93 |     const query = queryBuilder<TestSchema>()
 94 |       .from(`employees`, `e`)
 95 |       .join({
 96 |         type: `inner`,
 97 |         from: `departments`,
 98 |         as: `d`,
 99 |         on: [`@e.department_id`, `=`, `@d.id`],
100 |       })
101 |       .where(`@e.salary`, `>`, 50000)
102 |       .groupBy(`@d.name`)
103 |       .having({ COUNT: `@e.id` } as any, `>`, 5)
104 |       .select(`@d.name`, { count: { COUNT: `@e.id` } as any })
105 |       .orderBy(`@d.name`)
106 |       .limit(10)
107 | 
108 |     const builtQuery = query._query
109 | 
110 |     // Check groupBy
111 |     expect(builtQuery.groupBy).toBe(`@d.name`)
112 | 
113 |     // Also verify all other parts of the query are present
114 |     expect(builtQuery.from).toBe(`employees`)
115 |     expect(builtQuery.join).toBeDefined()
116 |     expect(builtQuery.where).toBeDefined()
117 |     expect(builtQuery.select).toBeDefined()
118 |     expect(builtQuery.having).toBeDefined()
119 |     expect(builtQuery.orderBy).toBeDefined()
120 |     expect(builtQuery.limit).toBe(10)
121 |   })
122 | })
123 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/having.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it } from "vitest"
  2 | import { queryBuilder } from "../../../src/query/query-builder.js"
  3 | import type { Input, Schema } from "../../../src/query/types.js"
  4 | 
  5 | // Test schema
  6 | interface Employee extends Input {
  7 |   id: number
  8 |   name: string
  9 |   department_id: number
 10 |   salary: number
 11 |   active: boolean
 12 | }
 13 | 
 14 | interface Department extends Input {
 15 |   id: number
 16 |   name: string
 17 |   budget: number
 18 |   location: string
 19 | }
 20 | 
 21 | // Make sure TestSchema extends Schema
 22 | interface TestSchema extends Schema {
 23 |   employees: Employee
 24 |   departments: Department
 25 | }
 26 | 
 27 | describe(`QueryBuilder.having`, () => {
 28 |   it(`sets a simple having condition with property reference and literal`, () => {
 29 |     const query = queryBuilder<TestSchema>()
 30 |       .from(`employees`)
 31 |       .having(`@salary`, `>`, 50000)
 32 | 
 33 |     const builtQuery = query._query
 34 |     expect(builtQuery.having).toEqual([`@salary`, `>`, 50000])
 35 |   })
 36 | 
 37 |   it(`supports various comparison operators`, () => {
 38 |     const operators = [
 39 |       `=`,
 40 |       `!=`,
 41 |       `<`,
 42 |       `<=`,
 43 |       `>`,
 44 |       `>=`,
 45 |       `like`,
 46 |       `in`,
 47 |       `is`,
 48 |       `is not`,
 49 |     ] as const
 50 | 
 51 |     for (const op of operators) {
 52 |       const query = queryBuilder<TestSchema>()
 53 |         .from(`employees`)
 54 |         .having(`@salary`, op as any, 50000)
 55 | 
 56 |       const builtQuery = query._query
 57 |       expect(builtQuery.having).toBeDefined()
 58 |       const having = builtQuery.having!
 59 |       expect(having[1]).toBe(op)
 60 |     }
 61 |   })
 62 | 
 63 |   it(`allows comparing property references to property references`, () => {
 64 |     const query = queryBuilder<TestSchema>()
 65 |       .from(`employees`, `e`)
 66 |       .join({
 67 |         type: `inner`,
 68 |         from: `departments`,
 69 |         as: `d`,
 70 |         on: [`@e.department_id`, `=`, `@d.id`],
 71 |       })
 72 |       .having(`@e.salary`, `>`, `@d.budget`)
 73 | 
 74 |     const builtQuery = query._query
 75 |     expect(builtQuery.having).toEqual([`@e.salary`, `>`, `@d.budget`])
 76 |   })
 77 | 
 78 |   it(`allows comparing literals to property references`, () => {
 79 |     const query = queryBuilder<TestSchema>()
 80 |       .from(`employees`)
 81 |       .having(50000, `<`, `@salary`)
 82 | 
 83 |     const builtQuery = query._query
 84 |     expect(builtQuery.having).toEqual([50000, `<`, `@salary`])
 85 |   })
 86 | 
 87 |   it(`combines multiple having calls with AND`, () => {
 88 |     const query = queryBuilder<TestSchema>()
 89 |       .from(`employees`)
 90 |       .having(`@salary`, `>`, 50000)
 91 |       .having(`@active`, `=`, true)
 92 | 
 93 |     const builtQuery = query._query
 94 |     expect(builtQuery.having).toEqual([
 95 |       [`@salary`, `>`, 50000],
 96 |       `and`,
 97 |       [`@active`, `=`, true],
 98 |     ])
 99 |   })
100 | 
101 |   it(`supports passing a complete condition`, () => {
102 |     const condition = [`@salary`, `>`, 50000] as any
103 | 
104 |     const query = queryBuilder<TestSchema>().from(`employees`).having(condition)
105 | 
106 |     const builtQuery = query._query
107 |     expect(builtQuery.having).toEqual(condition)
108 |   })
109 | 
110 |   it(`works in a practical example with groupBy`, () => {
111 |     const query = queryBuilder<TestSchema>()
112 |       .from(`employees`, `e`)
113 |       .join({
114 |         type: `inner`,
115 |         from: `departments`,
116 |         as: `d`,
117 |         on: [`@e.department_id`, `=`, `@d.id`],
118 |       })
119 |       .select(`@d.name`, { avg_salary: { SUM: `@e.salary` } as any })
120 |       .groupBy(`@d.name`)
121 |       .having({ SUM: `@e.salary` } as any, `>`, 100000)
122 | 
123 |     const builtQuery = query._query
124 |     expect(builtQuery.groupBy).toBe(`@d.name`)
125 |     expect(builtQuery.having).toEqual([{ SUM: `@e.salary` }, `>`, 100000])
126 |   })
127 | 
128 |   it(`allows combining with other query methods`, () => {
129 |     const query = queryBuilder<TestSchema>()
130 |       .from(`employees`, `e`)
131 |       .join({
132 |         type: `inner`,
133 |         from: `departments`,
134 |         as: `d`,
135 |         on: [`@e.department_id`, `=`, `@d.id`],
136 |       })
137 |       .where(`@e.active`, `=`, true)
138 |       .groupBy(`@d.name`)
139 |       .having(`@e.salary`, `>`, 50000)
140 |       .select(`@d.name`, { total_salary: { SUM: `@e.salary` } as any })
141 |       .orderBy(`@d.name`)
142 |       .limit(10)
143 | 
144 |     const builtQuery = query._query
145 |     expect(builtQuery.where).toBeDefined()
146 |     expect(builtQuery.groupBy).toBeDefined()
147 |     expect(builtQuery.having).toBeDefined()
148 |     expect(builtQuery.select).toBeDefined()
149 |     expect(builtQuery.orderBy).toBeDefined()
150 |     expect(builtQuery.limit).toBeDefined()
151 |   })
152 | })
153 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/join.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it } from "vitest"
  2 | import { queryBuilder } from "../../../src/query/query-builder.js"
  3 | import type { Input, Schema } from "../../../src/query/types.js"
  4 | 
  5 | // Test schema
  6 | interface Employee extends Input {
  7 |   id: number
  8 |   name: string
  9 |   department_id: number
 10 |   salary: number
 11 | }
 12 | 
 13 | interface Department extends Input {
 14 |   id: number
 15 |   name: string
 16 |   budget: number
 17 |   location: string
 18 | }
 19 | 
 20 | // Make sure TestSchema extends Schema
 21 | interface TestSchema extends Schema {
 22 |   employees: Employee
 23 |   departments: Department
 24 | }
 25 | 
 26 | describe(`QueryBuilder.join`, () => {
 27 |   it(`adds a simple inner join`, () => {
 28 |     const query = queryBuilder<TestSchema>()
 29 |       .from(`employees`, `e`)
 30 |       .join({
 31 |         type: `inner`,
 32 |         from: `departments`,
 33 |         as: `d`,
 34 |         on: [`@e.department_id`, `=`, `@d.id`],
 35 |       })
 36 | 
 37 |     const builtQuery = query._query
 38 |     expect(builtQuery.join).toBeDefined()
 39 |     const join = builtQuery.join!
 40 |     expect(join).toHaveLength(1)
 41 |     expect(join[0]).toMatchObject({
 42 |       type: `inner`,
 43 |       from: `departments`,
 44 |       as: `d`,
 45 |       on: [`@e.department_id`, `=`, `@d.id`],
 46 |     })
 47 |   })
 48 | 
 49 |   it(`supports all join types`, () => {
 50 |     const joinTypes = [`inner`, `left`, `right`, `full`, `cross`] as const
 51 | 
 52 |     for (const type of joinTypes) {
 53 |       const query = queryBuilder<TestSchema>()
 54 |         .from(`employees`, `e`)
 55 |         .join({
 56 |           type,
 57 |           from: `departments`,
 58 |           as: `d`,
 59 |           on: [`@e.department_id`, `=`, `@d.id`],
 60 |         })
 61 | 
 62 |       const builtQuery = query._query
 63 |       expect(builtQuery.join).toBeDefined()
 64 |       expect(builtQuery.join![0]!.type).toBe(type)
 65 |     }
 66 |   })
 67 | 
 68 |   it(`supports multiple joins`, () => {
 69 |     const query = queryBuilder<TestSchema>()
 70 |       .from(`employees`, `e`)
 71 |       .join({
 72 |         type: `inner`,
 73 |         from: `departments`,
 74 |         as: `d1`,
 75 |         on: [`@e.department_id`, `=`, `@d1.id`],
 76 |       })
 77 |       .join({
 78 |         type: `left`,
 79 |         from: `departments`,
 80 |         as: `d2`,
 81 |         on: [`@e.department_id`, `=`, `@d2.id`],
 82 |       })
 83 | 
 84 |     const builtQuery = query._query
 85 |     expect(builtQuery.join).toBeDefined()
 86 |     const join = builtQuery.join!
 87 |     expect(join).toHaveLength(2)
 88 |     expect(join[0]!.type).toBe(`inner`)
 89 |     expect(join[0]!.as).toBe(`d1`)
 90 |     expect(join[1]!.type).toBe(`left`)
 91 |     expect(join[1]!.as).toBe(`d2`)
 92 |   })
 93 | 
 94 |   it(`allows join with a where condition`, () => {
 95 |     const query = queryBuilder<TestSchema>()
 96 |       .from(`employees`, `e`)
 97 |       .join({
 98 |         type: `inner`,
 99 |         from: `departments`,
100 |         as: `d`,
101 |         on: [`@e.department_id`, `=`, `@d.id`],
102 |         where: [`@d.budget`, `>`, 1000000],
103 |       })
104 | 
105 |     const builtQuery = query._query
106 |     expect(builtQuery.join).toBeDefined()
107 |     expect(builtQuery.join![0]!.where).toEqual([`@d.budget`, `>`, 1000000])
108 |   })
109 | 
110 |   it(`allows accessing joined table in select`, () => {
111 |     const query = queryBuilder<TestSchema>()
112 |       .from(`employees`, `e`)
113 |       .join({
114 |         type: `inner`,
115 |         from: `departments`,
116 |         as: `d`,
117 |         on: [`@e.department_id`, `=`, `@d.id`],
118 |       })
119 |       .select(`@e.id`, `@e.name`, `@d.name`, `@d.budget`)
120 | 
121 |     const builtQuery = query._query
122 |     expect(builtQuery.select).toEqual([
123 |       `@e.id`,
124 |       `@e.name`,
125 |       `@d.name`,
126 |       `@d.budget`,
127 |     ])
128 |   })
129 | 
130 |   it(`allows accessing joined table in where`, () => {
131 |     const query = queryBuilder<TestSchema>()
132 |       .from(`employees`, `e`)
133 |       .join({
134 |         type: `inner`,
135 |         from: `departments`,
136 |         as: `d`,
137 |         on: [`@e.department_id`, `=`, `@d.id`],
138 |       })
139 |       .where(`@d.budget`, `>`, 1000000)
140 | 
141 |     const builtQuery = query._query
142 |     expect(builtQuery.where).toEqual([`@d.budget`, `>`, 1000000])
143 |   })
144 | 
145 |   it(`creates a complex query with multiple joins, select and where`, () => {
146 |     const query = queryBuilder<TestSchema>()
147 |       .from(`employees`, `e`)
148 |       .join({
149 |         type: `inner`,
150 |         from: `departments`,
151 |         as: `d`,
152 |         on: [`@e.department_id`, `=`, `@d.id`],
153 |       })
154 |       .where(`@e.salary`, `>`, 50000)
155 |       .where(`@d.budget`, `>`, 1000000)
156 |       .select(`@e.id`, `@e.name`, `@d.name`, {
157 |         dept_location: `@d.location`,
158 |       })
159 | 
160 |     const builtQuery = query._query
161 |     expect(builtQuery.from).toBe(`employees`)
162 |     expect(builtQuery.as).toBe(`e`)
163 |     expect(builtQuery.join).toBeDefined()
164 |     const join = builtQuery.join!
165 |     expect(join).toHaveLength(1)
166 |     expect(join[0]!.type).toBe(`inner`)
167 |     expect(join[0]!.from).toBe(`departments`)
168 |     expect(join[0]!.as).toBe(`d`)
169 |     expect(builtQuery.where).toBeDefined()
170 |     expect(builtQuery.select).toHaveLength(4)
171 |   })
172 | })
173 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/key-by.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it } from "vitest"
  2 | import { queryBuilder } from "../../../src/query/query-builder.js"
  3 | import type { Input, Schema } from "../../../src/query/types.js"
  4 | 
  5 | // Test schema
  6 | interface Employee extends Input {
  7 |   id: number
  8 |   name: string
  9 |   department_id: number
 10 |   salary: number
 11 | }
 12 | 
 13 | interface Department extends Input {
 14 |   id: number
 15 |   name: string
 16 |   budget: number
 17 |   location: string
 18 | }
 19 | 
 20 | // Make sure TestSchema extends Schema
 21 | interface TestSchema extends Schema {
 22 |   employees: Employee
 23 |   departments: Department
 24 | }
 25 | 
 26 | describe(`QueryBuilder.keyBy`, () => {
 27 |   it(`sets a single property reference as keyBy`, () => {
 28 |     const query = queryBuilder<TestSchema>()
 29 |       .from(`employees`)
 30 |       .select(`@id`, `@name`)
 31 |       .keyBy(`@id`)
 32 | 
 33 |     const builtQuery = query._query
 34 |     expect(builtQuery.keyBy).toBe(`@id`)
 35 |   })
 36 | 
 37 |   it(`sets an array of property references as keyBy`, () => {
 38 |     const query = queryBuilder<TestSchema>()
 39 |       .from(`employees`)
 40 |       .select(`@id`, `@name`, `@department_id`)
 41 |       .keyBy([`@id`, `@department_id`])
 42 | 
 43 |     const builtQuery = query._query
 44 |     expect(builtQuery.keyBy).toEqual([`@id`, `@department_id`])
 45 |   })
 46 | 
 47 |   it(`overrides previous keyBy values`, () => {
 48 |     const query = queryBuilder<TestSchema>()
 49 |       .from(`employees`)
 50 |       .select(`@id`, `@name`, `@department_id`)
 51 |       .keyBy(`@id`)
 52 |       .keyBy(`@department_id`) // This should override
 53 | 
 54 |     const builtQuery = query._query
 55 |     expect(builtQuery.keyBy).toBe(`@department_id`)
 56 |   })
 57 | 
 58 |   it(`works with joined tables`, () => {
 59 |     const query = queryBuilder<TestSchema>()
 60 |       .from(`employees`, `e`)
 61 |       .join({
 62 |         type: `inner`,
 63 |         from: `departments`,
 64 |         as: `d`,
 65 |         on: [`@e.department_id`, `=`, `@d.id`],
 66 |       })
 67 |       .select(`@e.id`, `@e.name`, `@d.name`)
 68 |       .keyBy(`@d.id`)
 69 | 
 70 |     const builtQuery = query._query
 71 |     expect(builtQuery.keyBy).toBe(`@d.id`)
 72 |   })
 73 | 
 74 |   it(`can be combined with other query methods`, () => {
 75 |     const query = queryBuilder<TestSchema>()
 76 |       .from(`employees`, `e`)
 77 |       .join({
 78 |         type: `inner`,
 79 |         from: `departments`,
 80 |         as: `d`,
 81 |         on: [`@e.department_id`, `=`, `@d.id`],
 82 |       })
 83 |       .where(`@e.salary`, `>`, 50000)
 84 |       .select(`@e.id`, `@e.name`, `@d.name`)
 85 |       .orderBy(`@e.salary`)
 86 |       .limit(10)
 87 |       .offset(5)
 88 |       .keyBy(`@e.id`)
 89 | 
 90 |     const builtQuery = query._query
 91 | 
 92 |     // Check keyBy
 93 |     expect(builtQuery.keyBy).toBe(`@e.id`)
 94 | 
 95 |     // Also verify all other parts of the query are present
 96 |     expect(builtQuery.from).toBe(`employees`)
 97 |     expect(builtQuery.as).toBe(`e`)
 98 |     expect(builtQuery.join).toBeDefined()
 99 |     expect(builtQuery.where).toBeDefined()
100 |     expect(builtQuery.select).toHaveLength(4)
101 |     expect(builtQuery.select).toEqual([
102 |       `@e.id`,
103 |       `@e.name`,
104 |       `@d.name`,
105 |       { _orderByIndex: { ORDER_INDEX: `numeric` } }, // Added by the orderBy method
106 |     ])
107 |     expect(builtQuery.orderBy).toBe(`@e.salary`)
108 |     expect(builtQuery.limit).toBe(10)
109 |     expect(builtQuery.offset).toBe(5)
110 |   })
111 | })
112 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/order-by.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it } from "vitest"
  2 | import { queryBuilder } from "../../../src/query/query-builder.js"
  3 | import type { Input, Schema } from "../../../src/query/types.js"
  4 | 
  5 | // Test schema
  6 | interface Employee extends Input {
  7 |   id: number
  8 |   name: string
  9 |   department_id: number
 10 |   salary: number
 11 | }
 12 | 
 13 | interface Department extends Input {
 14 |   id: number
 15 |   name: string
 16 |   budget: number
 17 |   location: string
 18 | }
 19 | 
 20 | // Make sure TestSchema extends Schema
 21 | interface TestSchema extends Schema {
 22 |   employees: Employee
 23 |   departments: Department
 24 | }
 25 | 
 26 | describe(`QueryBuilder orderBy, limit, and offset`, () => {
 27 |   describe(`orderBy`, () => {
 28 |     it(`sets a simple string order`, () => {
 29 |       const query = queryBuilder<TestSchema>().from(`employees`).orderBy(`@id`)
 30 | 
 31 |       const builtQuery = query._query
 32 |       expect(builtQuery.orderBy).toBe(`@id`)
 33 |     })
 34 | 
 35 |     it(`sets an object with direction`, () => {
 36 |       const query = queryBuilder<TestSchema>()
 37 |         .from(`employees`)
 38 |         .orderBy({ "@id": `desc` })
 39 | 
 40 |       const builtQuery = query._query
 41 |       expect(builtQuery.orderBy).toEqual({ "@id": `desc` })
 42 |     })
 43 | 
 44 |     it(`sets an array of orders`, () => {
 45 |       const query = queryBuilder<TestSchema>()
 46 |         .from(`employees`)
 47 |         .orderBy([`@id`, { "@name": `asc` }])
 48 | 
 49 |       const builtQuery = query._query
 50 |       expect(builtQuery.orderBy).toEqual([`@id`, { "@name": `asc` }])
 51 |     })
 52 | 
 53 |     it(`overrides previous orderBy values`, () => {
 54 |       const query = queryBuilder<TestSchema>()
 55 |         .from(`employees`)
 56 |         .orderBy(`@id`)
 57 |         .orderBy(`@name`) // This should override
 58 | 
 59 |       const builtQuery = query._query
 60 |       expect(builtQuery.orderBy).toBe(`@name`)
 61 |     })
 62 |   })
 63 | 
 64 |   describe(`limit`, () => {
 65 |     it(`sets a limit on the query`, () => {
 66 |       const query = queryBuilder<TestSchema>().from(`employees`).limit(10)
 67 | 
 68 |       const builtQuery = query._query
 69 |       expect(builtQuery.limit).toBe(10)
 70 |     })
 71 | 
 72 |     it(`overrides previous limit values`, () => {
 73 |       const query = queryBuilder<TestSchema>()
 74 |         .from(`employees`)
 75 |         .limit(10)
 76 |         .limit(20) // This should override
 77 | 
 78 |       const builtQuery = query._query
 79 |       expect(builtQuery.limit).toBe(20)
 80 |     })
 81 |   })
 82 | 
 83 |   describe(`offset`, () => {
 84 |     it(`sets an offset on the query`, () => {
 85 |       const query = queryBuilder<TestSchema>().from(`employees`).offset(5)
 86 | 
 87 |       const builtQuery = query._query
 88 |       expect(builtQuery.offset).toBe(5)
 89 |     })
 90 | 
 91 |     it(`overrides previous offset values`, () => {
 92 |       const query = queryBuilder<TestSchema>()
 93 |         .from(`employees`)
 94 |         .offset(5)
 95 |         .offset(15) // This should override
 96 | 
 97 |       const builtQuery = query._query
 98 |       expect(builtQuery.offset).toBe(15)
 99 |     })
100 |   })
101 | 
102 |   describe(`combined methods`, () => {
103 |     it(`builds a complex query with orderBy, limit, and offset`, () => {
104 |       const query = queryBuilder<TestSchema>()
105 |         .from(`employees`, `e`)
106 |         .join({
107 |           type: `inner`,
108 |           from: `departments`,
109 |           as: `d`,
110 |           on: [`@e.department_id`, `=`, `@d.id`],
111 |         })
112 |         .where(`@e.salary`, `>`, 50000)
113 |         .select(`@e.id`, `@e.name`, `@d.name`)
114 |         .orderBy([`@e.salary`, { "@d.name": `asc` }])
115 |         .limit(10)
116 |         .offset(5)
117 | 
118 |       const builtQuery = query._query
119 |       expect(builtQuery.orderBy).toEqual([`@e.salary`, { "@d.name": `asc` }])
120 |       expect(builtQuery.limit).toBe(10)
121 |       expect(builtQuery.offset).toBe(5)
122 | 
123 |       // Also verify all other parts of the query are present
124 |       expect(builtQuery.from).toBe(`employees`)
125 |       expect(builtQuery.as).toBe(`e`)
126 |       expect(builtQuery.join).toBeDefined()
127 |       expect(builtQuery.where).toBeDefined()
128 |       expect(builtQuery.select).toEqual([
129 |         `@e.id`,
130 |         `@e.name`,
131 |         `@d.name`,
132 |         { _orderByIndex: { ORDER_INDEX: `numeric` } }, // Added by the orderBy method
133 |       ])
134 |     })
135 |   })
136 | })
137 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/select-functions.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it, vi } from "vitest"
  2 | import { queryBuilder } from "../../../src/query/query-builder.js"
  3 | import type { Input, Schema } from "../../../src/query/types.js"
  4 | 
  5 | // Test schema
  6 | interface Employee extends Input {
  7 |   id: number
  8 |   name: string
  9 |   department_id: number
 10 |   salary: number
 11 | }
 12 | 
 13 | interface Department extends Input {
 14 |   id: number
 15 |   name: string
 16 |   budget: number
 17 |   location: string
 18 | }
 19 | 
 20 | // Make sure TestSchema extends Schema
 21 | interface TestSchema extends Schema {
 22 |   employees: Employee
 23 |   departments: Department
 24 | }
 25 | 
 26 | describe(`QueryBuilder.select with function calls`, () => {
 27 |   it(`handles aggregate functions without using `, () => {
 28 |     const query = queryBuilder<TestSchema>()
 29 |       .from(`employees`)
 30 |       .select(`@id`, {
 31 |         sum_salary: { SUM: `@salary` },
 32 |         avg_salary: { AVG: `@salary` },
 33 |         count: { COUNT: `@id` },
 34 |         min_salary: { MIN: `@salary` },
 35 |         max_salary: { MAX: `@salary` },
 36 |       })
 37 | 
 38 |     const builtQuery = query._query
 39 |     expect(builtQuery.select).toMatchObject([
 40 |       `@id`,
 41 |       {
 42 |         sum_salary: { SUM: `@salary` },
 43 |         avg_salary: { AVG: `@salary` },
 44 |         count: { COUNT: `@id` },
 45 |         min_salary: { MIN: `@salary` },
 46 |         max_salary: { MAX: `@salary` },
 47 |       },
 48 |     ])
 49 |   })
 50 | 
 51 |   it(`handles string functions without using `, () => {
 52 |     const query = queryBuilder<TestSchema>()
 53 |       .from(`employees`)
 54 |       .select(`@id`, {
 55 |         upper_name: { UPPER: `@name` },
 56 |         lower_name: { LOWER: `@name` },
 57 |         name_length: { LENGTH: `@name` },
 58 |         concat_text: { CONCAT: [`Employee: `, `@name`] },
 59 |       })
 60 | 
 61 |     const builtQuery = query._query
 62 |     expect(builtQuery.select).toMatchObject([
 63 |       `@id`,
 64 |       {
 65 |         upper_name: { UPPER: `@name` },
 66 |         lower_name: { LOWER: `@name` },
 67 |         name_length: { LENGTH: `@name` },
 68 |         concat_text: { CONCAT: [`Employee: `, `@name`] },
 69 |       },
 70 |     ])
 71 |   })
 72 | 
 73 |   it(`handles JSON functions without using `, () => {
 74 |     // Create a field that would contain JSON
 75 |     const query = queryBuilder<TestSchema>()
 76 |       .from(`employees`)
 77 |       .select(`@id`, {
 78 |         json_value: { JSON_EXTRACT: [`@name`, `$.property`] },
 79 |       })
 80 | 
 81 |     const builtQuery = query._query
 82 |     expect(builtQuery.select).toHaveLength(2)
 83 |     expect(builtQuery.select[1]).toHaveProperty(`json_value`)
 84 |   })
 85 | 
 86 |   it(`validates and filters out invalid function calls`, () => {
 87 |     // Mock console.warn to verify warnings
 88 |     const consoleWarnMock = vi
 89 |       .spyOn(console, `warn`)
 90 |       .mockImplementation(() => {})
 91 | 
 92 |     queryBuilder<TestSchema>()
 93 |       .from(`employees`)
 94 |       .select(`@id`, {
 95 |         // This is an invalid function that should trigger a warning
 96 |         // @ts-expect-error
 97 |         invalid_func: { INVALID_FUNCTION: `@name` },
 98 |       })
 99 | 
100 |     // Verify the warning was logged
101 |     expect(consoleWarnMock).toHaveBeenCalledWith(
102 |       expect.stringContaining(`Unsupported function: INVALID_FUNCTION`)
103 |     )
104 | 
105 |     // Restore the original console.warn
106 |     consoleWarnMock.mockRestore()
107 |   })
108 | 
109 |   it(`combines function calls with other select elements`, () => {
110 |     const query = queryBuilder<TestSchema>()
111 |       .from(`employees`, `e`)
112 |       .join({
113 |         type: `inner`,
114 |         from: `departments`,
115 |         as: `d`,
116 |         on: [`@e.department_id`, `=`, `@d.id`],
117 |       })
118 |       .select(`@e.id`, `@e.name`, `@d.name`, {
119 |         dept_budget: `@d.budget`,
120 |         sum_salary: { SUM: `@e.salary` },
121 |         upper_name: { UPPER: `@e.name` },
122 |       })
123 | 
124 |     const builtQuery = query._query
125 |     expect(builtQuery.select).toHaveLength(4)
126 |     expect(builtQuery.select[0]).toBe(`@e.id`)
127 |     expect(builtQuery.select[1]).toBe(`@e.name`)
128 |     expect(builtQuery.select[2]).toBe(`@d.name`)
129 |     expect(builtQuery.select[3]).toHaveProperty(`dept_budget`)
130 |     expect(builtQuery.select[3]).toHaveProperty(`sum_salary`)
131 |     expect(builtQuery.select[3]).toHaveProperty(`upper_name`)
132 |   })
133 | })
134 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/select.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from "vitest"
 2 | import { queryBuilder } from "../../../src/query/query-builder.js"
 3 | import type { Input, Schema } from "../../../src/query/types.js"
 4 | 
 5 | // Test schema
 6 | interface Employee extends Input {
 7 |   id: number
 8 |   name: string
 9 |   department_id: number | null
10 |   salary: number
11 | }
12 | 
13 | interface Department extends Input {
14 |   id: number
15 |   name: string
16 |   budget: number
17 | }
18 | 
19 | // Make sure TestSchema extends Schema
20 | interface TestSchema extends Schema {
21 |   employees: Employee
22 |   departments: Department
23 | }
24 | 
25 | describe(`QueryBuilder.select`, () => {
26 |   it(`sets the select clause correctly with individual columns`, () => {
27 |     const query = queryBuilder<TestSchema>()
28 |       .from(`employees`)
29 |       .select(`@id`, `@name`)
30 | 
31 |     const builtQuery = query._query
32 |     expect(builtQuery.select).toEqual([`@id`, `@name`])
33 |   })
34 | 
35 |   it(`handles aliased columns`, () => {
36 |     const query = queryBuilder<TestSchema>()
37 |       .from(`employees`)
38 |       .select(`@id`, { employee_name: `@name` })
39 | 
40 |     const builtQuery = query._query
41 |     expect(builtQuery.select).toHaveLength(2)
42 |     expect(builtQuery.select[0]).toBe(`@id`)
43 |     expect(builtQuery.select[1]).toHaveProperty(`employee_name`, `@name`)
44 |   })
45 | 
46 |   it(`handles function calls`, () => {
47 |     const query = queryBuilder<TestSchema>()
48 |       .from(`employees`)
49 |       .select(`@id`, {
50 |         upper_name: { UPPER: `@name` },
51 |       })
52 | 
53 |     const builtQuery = query._query
54 |     expect(builtQuery.select).toHaveLength(2)
55 |     expect(builtQuery.select[1]).toHaveProperty(`upper_name`)
56 |   })
57 | 
58 |   it(`overrides previous select calls`, () => {
59 |     const query = queryBuilder<TestSchema>()
60 |       .from(`employees`)
61 |       .select(`@id`, `@name`)
62 |       .select(`@id`, `@salary`) // This should override the previous select
63 | 
64 |     const builtQuery = query._query
65 |     expect(builtQuery.select).toEqual([`@id`, `@salary`])
66 |   })
67 | 
68 |   it(`supports qualified table references`, () => {
69 |     const query = queryBuilder<TestSchema>()
70 |       .from(`employees`, `e`)
71 |       .select(`@e.id`, `@e.name`)
72 | 
73 |     const builtQuery = query._query
74 |     expect(builtQuery.select).toEqual([`@e.id`, `@e.name`])
75 |   })
76 | 
77 |   // Runtime test for the result types
78 |   it(`infers correct result types`, () => {
79 |     const query = queryBuilder<TestSchema>()
80 |       .from(`employees`)
81 |       .select(`@id`, `@name`)
82 | 
83 |     // We can't directly assert on types in a test, but we can check
84 |     // that the query is constructed correctly, which implies the types work
85 |     const builtQuery = query._query
86 |     expect(builtQuery.select).toEqual([`@id`, `@name`])
87 |   })
88 | })
89 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/where.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it } from "vitest"
  2 | import { queryBuilder } from "../../../src/query/query-builder.js"
  3 | import type { Input, Schema } from "../../../src/query/types.js"
  4 | 
  5 | // Test schema
  6 | interface Employee extends Input {
  7 |   id: number
  8 |   name: string
  9 |   department_id: number | null
 10 |   salary: number
 11 |   active: boolean
 12 | }
 13 | 
 14 | interface Department extends Input {
 15 |   id: number
 16 |   name: string
 17 |   budget: number
 18 | }
 19 | 
 20 | // Make sure TestSchema extends Schema
 21 | interface TestSchema extends Schema {
 22 |   employees: Employee
 23 |   departments: Department
 24 | }
 25 | 
 26 | describe(`QueryBuilder.where`, () => {
 27 |   it(`sets a simple condition with property reference and literal`, () => {
 28 |     const query = queryBuilder<TestSchema>()
 29 |       .from(`employees`)
 30 |       .where(`@id`, `=`, 1)
 31 | 
 32 |     const builtQuery = query._query
 33 |     expect(builtQuery.where).toEqual([`@id`, `=`, 1])
 34 |   })
 35 | 
 36 |   it(`supports various comparison operators`, () => {
 37 |     const operators = [
 38 |       `=`,
 39 |       `!=`,
 40 |       `<`,
 41 |       `<=`,
 42 |       `>`,
 43 |       `>=`,
 44 |       `like`,
 45 |       `in`,
 46 |       `is`,
 47 |       `is not`,
 48 |     ] as const
 49 | 
 50 |     for (const op of operators) {
 51 |       const query = queryBuilder<TestSchema>()
 52 |         .from(`employees`)
 53 |         .where(`@id`, op as any, 1)
 54 | 
 55 |       const builtQuery = query._query
 56 |       expect(builtQuery.where).toBeDefined()
 57 |       // Type assertion since we know where is defined based on our query
 58 |       const where = builtQuery.where!
 59 |       expect(where[1]).toBe(op)
 60 |     }
 61 |   })
 62 | 
 63 |   it(`allows comparing property references to property references`, () => {
 64 |     const query = queryBuilder<TestSchema>()
 65 |       .from(`employees`, `e`)
 66 |       .where(`@e.department_id`, `=`, `@department.id`)
 67 | 
 68 |     const builtQuery = query._query
 69 |     expect(builtQuery.where).toEqual([
 70 |       `@e.department_id`,
 71 |       `=`,
 72 |       `@department.id`,
 73 |     ])
 74 |   })
 75 | 
 76 |   it(`allows comparing literals to property references`, () => {
 77 |     const query = queryBuilder<TestSchema>()
 78 |       .from(`employees`)
 79 |       .where(10000, `<`, `@salary`)
 80 | 
 81 |     const builtQuery = query._query
 82 |     expect(builtQuery.where).toEqual([10000, `<`, `@salary`])
 83 |   })
 84 | 
 85 |   it(`supports boolean literals`, () => {
 86 |     const query = queryBuilder<TestSchema>()
 87 |       .from(`employees`)
 88 |       .where(`@active`, `=`, true)
 89 | 
 90 |     const builtQuery = query._query
 91 |     expect(builtQuery.where).toEqual([`@active`, `=`, true])
 92 |   })
 93 | 
 94 |   it(`combines multiple where calls with AND`, () => {
 95 |     const query = queryBuilder<TestSchema>()
 96 |       .from(`employees`)
 97 |       .where(`@id`, `>`, 10)
 98 |       .where(`@salary`, `>=`, 50000)
 99 | 
100 |     const builtQuery = query._query
101 |     expect(builtQuery.where).toEqual([
102 |       [`@id`, `>`, 10],
103 |       `and`,
104 |       [`@salary`, `>=`, 50000],
105 |     ])
106 |   })
107 | 
108 |   it(`handles multiple chained where clauses`, () => {
109 |     const query = queryBuilder<TestSchema>()
110 |       .from(`employees`)
111 |       .where(`@id`, `>`, 10)
112 |       .where(`@salary`, `>=`, 50000)
113 |       .where(`@active`, `=`, true)
114 | 
115 |     const builtQuery = query._query
116 |     expect(builtQuery.where).toEqual([
117 |       [[`@id`, `>`, 10], `and`, [`@salary`, `>=`, 50000]],
118 |       `and`,
119 |       [`@active`, `=`, true],
120 |     ])
121 |   })
122 | 
123 |   it(`supports passing a complete condition`, () => {
124 |     const condition = [`@id`, `=`, 1] as any
125 | 
126 |     const query = queryBuilder<TestSchema>().from(`employees`).where(condition)
127 | 
128 |     const builtQuery = query._query
129 |     expect(builtQuery.where).toEqual(condition)
130 |   })
131 | 
132 |   it(`allows combining with other methods`, () => {
133 |     const query = queryBuilder<TestSchema>()
134 |       .from(`employees`)
135 |       .where(`@salary`, `>`, 50000)
136 |       .select(`@id`, `@name`, `@salary`)
137 | 
138 |     const builtQuery = query._query
139 |     expect(builtQuery.where).toEqual([`@salary`, `>`, 50000])
140 |     expect(builtQuery.select).toEqual([`@id`, `@name`, `@salary`])
141 |   })
142 | })
143 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-builder/with.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it } from "vitest"
  2 | import { queryBuilder } from "../../../src/query/query-builder.js"
  3 | import type { Input, Schema } from "../../../src/query/types.js"
  4 | 
  5 | // Test schema
  6 | interface Employee extends Input {
  7 |   id: number
  8 |   name: string
  9 |   department_id: number | null
 10 | }
 11 | 
 12 | interface Department extends Input {
 13 |   id: number
 14 |   name: string
 15 |   budget: number
 16 | }
 17 | 
 18 | // Make sure TestSchema extends Schema
 19 | interface TestSchema extends Schema {
 20 |   employees: Employee
 21 |   departments: Department
 22 | }
 23 | 
 24 | // Define interfaces for the CTE result types
 25 | interface EmployeeCTE {
 26 |   id: number
 27 |   name: string
 28 | }
 29 | 
 30 | interface EmployeeWithDeptCTE {
 31 |   id: number
 32 |   name: string
 33 |   department_id: number | null
 34 | }
 35 | 
 36 | interface DepartmentCTE {
 37 |   id: number
 38 |   name: string
 39 | }
 40 | 
 41 | describe(`QueryBuilder.with`, () => {
 42 |   it(`defines a simple CTE correctly`, () => {
 43 |     // Explicitly provide the result type for better type checking
 44 |     const query = queryBuilder<TestSchema>()
 45 |       .with<`emp_cte`, EmployeeCTE>(`emp_cte`, (q) =>
 46 |         q.from(`employees`).select(`@id`, `@name`)
 47 |       )
 48 |       .from(`emp_cte`)
 49 |       .select(`@id`, `@name`)
 50 | 
 51 |     const builtQuery = query._query
 52 | 
 53 |     expect(builtQuery.with).toBeDefined()
 54 |     expect(builtQuery.with).toHaveLength(1)
 55 |     expect(builtQuery.with?.[0]!.as).toBe(`emp_cte`)
 56 |     expect(builtQuery.with?.[0]!.from).toBe(`employees`)
 57 |     expect(builtQuery.with?.[0]!.select).toHaveLength(2)
 58 |     expect(builtQuery.from).toBe(`emp_cte`)
 59 |   })
 60 | 
 61 |   it(`defines multiple CTEs correctly`, () => {
 62 |     const query = queryBuilder<TestSchema>()
 63 |       .with<`emp_cte`, EmployeeWithDeptCTE>(`emp_cte`, (q) =>
 64 |         q.from(`employees`).select(`@id`, `@name`, `@department_id`)
 65 |       )
 66 |       .with<`dept_cte`, DepartmentCTE>(`dept_cte`, (q) =>
 67 |         q.from(`departments`).select(`@id`, `@name`)
 68 |       )
 69 |       .from(`emp_cte`)
 70 |       .join({
 71 |         type: `inner`,
 72 |         from: `dept_cte`,
 73 |         on: [`@emp_cte.department_id`, `=`, `@dept_cte.id`],
 74 |       })
 75 |       .select(`@emp_cte.id`, `@emp_cte.name`, `@dept_cte.name`)
 76 | 
 77 |     const builtQuery = query._query
 78 | 
 79 |     expect(builtQuery.with).toBeDefined()
 80 |     expect(builtQuery.with).toHaveLength(2)
 81 |     expect(builtQuery.with?.[0]!.as).toBe(`emp_cte`)
 82 |     expect(builtQuery.with?.[1]!.as).toBe(`dept_cte`)
 83 |     expect(builtQuery.from).toBe(`emp_cte`)
 84 |     expect(builtQuery.join).toBeDefined()
 85 |     expect(builtQuery.join?.[0]!.from).toBe(`dept_cte`)
 86 |   })
 87 | 
 88 |   it(`allows chaining other methods after with`, () => {
 89 |     // Define the type of filtered employees
 90 |     interface FilteredEmployees {
 91 |       id: number
 92 |       name: string
 93 |     }
 94 | 
 95 |     const query = queryBuilder<TestSchema>()
 96 |       .with<`filtered_employees`, FilteredEmployees>(
 97 |         `filtered_employees`,
 98 |         (q) =>
 99 |           q
100 |             .from(`employees`)
101 |             .where(`@department_id`, `=`, 1)
102 |             .select(`@id`, `@name`)
103 |       )
104 |       .from(`filtered_employees`)
105 |       .where(`@id`, `>`, 100)
106 |       .select(`@id`, { employee_name: `@name` })
107 | 
108 |     const builtQuery = query._query
109 | 
110 |     expect(builtQuery.with).toBeDefined()
111 |     expect(builtQuery.with?.[0]!.where).toBeDefined()
112 |     expect(builtQuery.from).toBe(`filtered_employees`)
113 |     expect(builtQuery.where).toBeDefined()
114 |     expect(builtQuery.select).toHaveLength(2)
115 |   })
116 | })
117 | 


--------------------------------------------------------------------------------
/packages/db/tests/query/query-types.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, test } from "vitest"
  2 | import type {
  3 |   Comparator,
  4 |   Condition,
  5 |   ConditionOperand,
  6 |   FlatCompositeCondition,
  7 |   LogicalOperator,
  8 |   Query,
  9 |   SimpleCondition,
 10 | } from "../../src/query/schema.js"
 11 | 
 12 | type User = {
 13 |   id: number
 14 |   name: string
 15 |   age: number
 16 |   department: string
 17 | }
 18 | 
 19 | type Context = {
 20 |   baseSchema: {
 21 |     users: User
 22 |   }
 23 |   schema: {
 24 |     users: User
 25 |   }
 26 | }
 27 | 
 28 | // This test verifies that TypeScript properly accepts/rejects objects that should/shouldn't match Query types
 29 | describe(`Query Type System`, () => {
 30 |   test(`Query objects conform to the expected schema`, () => {
 31 |     // Simple runtime test that confirms our test file is running
 32 |     expect(true).toBe(true)
 33 | 
 34 |     // The actual type checking happens at compile time
 35 |     // If this file compiles, then the types are correctly defined
 36 |   })
 37 | })
 38 | 
 39 | // This portion contains compile-time type assertions
 40 | // These won't run at runtime but will cause TypeScript errors if the types don't match
 41 | 
 42 | // Valid basic query
 43 | const basicQuery = {
 44 |   select: [`@id`, `@name`],
 45 |   from: `users`,
 46 | } satisfies Query<Context>
 47 | 
 48 | // Valid query with aliased columns
 49 | const aliasedQuery = {
 50 |   select: [`@id`, { full_name: `@name` }],
 51 |   from: `users`,
 52 | } satisfies Query<Context>
 53 | 
 54 | // Valid query with simple WHERE condition
 55 | const simpleWhereQuery = {
 56 |   select: [`@id`, `@name`],
 57 |   from: `users`,
 58 |   where: [`@age`, `>`, 18] as SimpleCondition,
 59 | } satisfies Query<Context>
 60 | 
 61 | // Valid query with flat composite WHERE condition
 62 | const compositeWhereQuery = {
 63 |   select: [`@id`, `@name`],
 64 |   from: `users`,
 65 |   where: [
 66 |     `@age`,
 67 |     `>`,
 68 |     18,
 69 |     `and` as LogicalOperator,
 70 |     `@active`,
 71 |     `=`,
 72 |     true,
 73 |   ] as FlatCompositeCondition,
 74 | } satisfies Query<Context>
 75 | 
 76 | // Full query with all optional properties
 77 | const fullQuery = {
 78 |   select: [`@id`, `@name`, { age_years: `@age` }],
 79 |   as: `user_data`,
 80 |   from: `users`,
 81 |   where: [`@active`, `=`, true] as SimpleCondition,
 82 |   groupBy: [`@department`],
 83 |   having: [`@count`, `>`, 5] as SimpleCondition,
 84 |   orderBy: { "@name": `asc` },
 85 |   limit: 10,
 86 |   offset: 20,
 87 | } satisfies Query<Context>
 88 | 
 89 | // Condition type checking
 90 | const simpleCondition: SimpleCondition = [`@age`, `>`, 18]
 91 | const simpleCond: Condition = simpleCondition
 92 | 
 93 | // Flat composite condition
 94 | const flatCompositeCondition: FlatCompositeCondition = [
 95 |   `@age`,
 96 |   `>`,
 97 |   18,
 98 |   `and`,
 99 |   `@active`,
100 |   `=`,
101 |   true,
102 | ]
103 | const flatCompCond: Condition = flatCompositeCondition
104 | 
105 | // Nested composite condition
106 | const nestedCompositeCondition = [
107 |   [`@age`, `>`, 18] as SimpleCondition,
108 |   `and` as LogicalOperator,
109 |   [`@active`, `=`, true] as SimpleCondition,
110 | ] as [SimpleCondition, LogicalOperator, SimpleCondition]
111 | const nestedCompCond: Condition = nestedCompositeCondition
112 | 
113 | // The code below demonstrates type compatibility for ConditionOperand
114 | // If TypeScript compiles this file, then these assignments work
115 | const operand1: ConditionOperand<Context> = `string literal`
116 | const operand2: ConditionOperand<Context> = 42
117 | const operand3: ConditionOperand<Context> = true
118 | const operand4: ConditionOperand<Context> = null
119 | const operand5: ConditionOperand<Context> = undefined
120 | const operand6: ConditionOperand<Context> = `@department`
121 | const operand7: ConditionOperand<Context> = { col: `department` }
122 | const operand8: ConditionOperand<Context> = { value: { nested: `object` } }
123 | 
124 | // The code below demonstrates type compatibility for Comparator
125 | // If TypeScript compiles this file, then these assignments work
126 | const comp1: Comparator = `=`
127 | const comp2: Comparator = `!=`
128 | const comp3: Comparator = `<`
129 | const comp4: Comparator = `<=`
130 | const comp5: Comparator = `>`
131 | const comp6: Comparator = `>=`
132 | const comp7: Comparator = `like`
133 | const comp8: Comparator = `not like`
134 | const comp9: Comparator = `in`
135 | const comp10: Comparator = `not in`
136 | const comp11: Comparator = `is`
137 | const comp12: Comparator = `is not`
138 | 
139 | // The following lines would fail type checking if uncommented:
140 | 
141 | /*
142 | // Missing required 'from' property
143 | const invalidQuery1 = {
144 |   select: ['@id', '@name']
145 | } satisfies Query; // This would fail
146 | 
147 | // Invalid select items
148 | const invalidQuery2 = {
149 |   select: [1, 2, 3], // Should be strings or objects with column aliases
150 |   from: 'users'
151 | } satisfies Query; // This would fail
152 | 
153 | // Invalid condition structure
154 | const invalidQuery3 = {
155 |   select: ['@id'],
156 |   from: 'users',
157 |   where: ['@age', '>', '18', 'extra'] // Invalid condition structure
158 | } satisfies Query; // This would fail
159 | */
160 | 


--------------------------------------------------------------------------------
/packages/db/tests/test-setup.ts:
--------------------------------------------------------------------------------
1 | import "@testing-library/jest-dom/vitest"
2 | 


--------------------------------------------------------------------------------
/packages/db/tests/transaction-types.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from "vitest"
 2 | import type {
 3 |   MutationFactoryConfig,
 4 |   PendingMutation,
 5 |   Transaction,
 6 |   TransactionConfig,
 7 |   TransactionState,
 8 | } from "../src/types"
 9 | 
10 | describe(`Transaction Types`, () => {
11 |   it(`should validate PendingMutation structure with collectionId`, () => {
12 |     // Type assertion test - this will fail at compile time if the type is incorrect
13 |     const pendingMutation: PendingMutation = {
14 |       mutationId: `test-mutation-1`,
15 |       original: { id: 1, name: `Original` },
16 |       modified: { id: 1, name: `Modified` },
17 |       changes: { name: `Modified` },
18 |       key: `1`,
19 |       type: `update`,
20 |       metadata: null,
21 |       syncMetadata: {},
22 |       createdAt: new Date(),
23 |       updatedAt: new Date(),
24 |       collectionId: `users`, // New required field
25 |     }
26 | 
27 |     expect(pendingMutation.collectionId).toBe(`users`)
28 |     expect(pendingMutation.type).toBe(`update`)
29 |   })
30 | 
31 |   it(`should validate TransactionConfig structure`, () => {
32 |     // Empty config is valid
33 |     const minimalConfig: TransactionConfig = {}
34 |     expect(minimalConfig).toBeDefined()
35 | 
36 |     // Full config
37 |     const fullConfig: TransactionConfig = {
38 |       id: `custom-transaction-id`,
39 |       metadata: { source: `user-form` },
40 |     }
41 | 
42 |     expect(fullConfig.id).toBe(`custom-transaction-id`)
43 |     expect(fullConfig.metadata).toEqual({ source: `user-form` })
44 |   })
45 | 
46 |   it(`should validate Transaction structure`, () => {
47 |     const mockToObject = () => ({
48 |       id: `test-transaction`,
49 |       state: `pending` as TransactionState,
50 |       createdAt: new Date(),
51 |       updatedAt: new Date(),
52 |       mutations: [],
53 |       metadata: {},
54 |     })
55 | 
56 |     const transaction: Transaction = {
57 |       id: `test-transaction`,
58 |       state: `pending`,
59 |       createdAt: new Date(),
60 |       updatedAt: new Date(),
61 |       mutations: [],
62 |       metadata: {},
63 |       toObject: mockToObject,
64 |     }
65 | 
66 |     expect(transaction.id).toBe(`test-transaction`)
67 | 
68 |     // Test toObject method
69 |     const plainObject = transaction.toObject()
70 |     expect(plainObject.id).toBe(`test-transaction`)
71 |     expect(plainObject).not.toHaveProperty(`toObject`)
72 |   })
73 | 
74 |   it(`should validate MutationFactoryConfig structure`, () => {
75 |     // Minimal config with just the required mutationFn
76 |     const minimalConfig: MutationFactoryConfig = {
77 |       mutationFn: async () => {
78 |         return Promise.resolve({ success: true })
79 |       },
80 |     }
81 | 
82 |     expect(typeof minimalConfig.mutationFn).toBe(`function`)
83 | 
84 |     // Full config with metadata
85 |     const fullConfig: MutationFactoryConfig = {
86 |       mutationFn: async () => {
87 |         return Promise.resolve({ success: true })
88 |       },
89 |       metadata: { source: `signup-form` },
90 |     }
91 | 
92 |     expect(fullConfig.metadata).toEqual({ source: `signup-form` })
93 |   })
94 | })
95 | 


--------------------------------------------------------------------------------
/packages/db/tests/utils.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from "vitest"
 2 | import { getLockedObjects } from "../src/utils"
 3 | 
 4 | describe(`Utils`, () => {
 5 |   it(`should return an empty Set from getLockedObjects`, () => {
 6 |     const lockedObjects = getLockedObjects()
 7 | 
 8 |     expect(lockedObjects).toBeInstanceOf(Set)
 9 |     expect(lockedObjects.size).toBe(0)
10 |   })
11 | })
12 | 


--------------------------------------------------------------------------------
/packages/db/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "extends": "../../tsconfig.json",
 3 |   "compilerOptions": {
 4 |     "target": "ES2020",
 5 |     "module": "ESNext",
 6 |     "moduleResolution": "Bundler",
 7 |     "declaration": true,
 8 |     "outDir": "dist",
 9 |     "strict": true,
10 |     "esModuleInterop": true,
11 |     "skipLibCheck": true,
12 |     "forceConsistentCasingInFileNames": true,
13 |     "jsx": "react",
14 |     "paths": {
15 |       "@tanstack/store": ["../store/src"]
16 |     }
17 |   },
18 |   "include": ["src", "tests", "vite.config.ts"],
19 |   "exclude": ["node_modules", "dist"]
20 | }
21 | 


--------------------------------------------------------------------------------
/packages/db/vite.config.ts:
--------------------------------------------------------------------------------
 1 | import { defineConfig, mergeConfig } from "vitest/config"
 2 | import { tanstackViteConfig } from "@tanstack/config/vite"
 3 | import packageJson from "./package.json"
 4 | 
 5 | const config = defineConfig({
 6 |   test: {
 7 |     name: packageJson.name,
 8 |     dir: `./tests`,
 9 |     environment: `jsdom`,
10 |     coverage: { enabled: true, provider: `istanbul`, include: [`src/**/*`] },
11 |     typecheck: { enabled: true },
12 |     setupFiles: [`./tests/test-setup.ts`],
13 |   },
14 | })
15 | 
16 | export default mergeConfig(
17 |   config,
18 |   tanstackViteConfig({
19 |     entry: `./src/index.ts`,
20 |     srcDir: `./src`,
21 |   })
22 | )
23 | 


--------------------------------------------------------------------------------
/packages/react-db/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # @tanstack/react-db
 2 | 
 3 | ## 0.0.4
 4 | 
 5 | ### Patch Changes
 6 | 
 7 | - Updated dependencies [[`8ce449e`](https://github.com/TanStack/db/commit/8ce449ed6d070e9e591d1b74b0db5fed7a3fc92f)]:
 8 |   - @tanstack/db@0.0.4
 9 | 
10 | ## 0.0.3
11 | 
12 | ### Patch Changes
13 | 
14 | - Updated dependencies [[`b29420b`](https://github.com/TanStack/db/commit/b29420bcdae30dfeffeef63a8753b83306a54e5a)]:
15 |   - @tanstack/db@0.0.3
16 | 
17 | ## 0.0.2
18 | 
19 | ### Patch Changes
20 | 
21 | - Fixed an issue with injecting the optimistic state removal into the reactive live query. ([#78](https://github.com/TanStack/db/pull/78))
22 | 
23 | - Updated dependencies [[`4c82edb`](https://github.com/TanStack/db/commit/4c82edb9547f26c9de44f5bf43d4385c38920672)]:
24 |   - @tanstack/db@0.0.2
25 | 
26 | ## 0.0.3
27 | 
28 | ### Patch Changes
29 | 
30 | - Make transactions first class & move ownership of mutationFn from collections to transactions ([#53](https://github.com/TanStack/db/pull/53))
31 | 
32 | - Updated dependencies [[`b42479c`](https://github.com/TanStack/db/commit/b42479cf95f9a820b36e01684b13a9179973f3d8)]:
33 |   - @tanstack/db@0.0.3
34 | 
35 | ## 0.0.2
36 | 
37 | ### Patch Changes
38 | 
39 | - make mutationFn optional for read-only collections ([#12](https://github.com/TanStack/db/pull/12))
40 | 
41 | - Updated dependencies [[`9bb6e89`](https://github.com/TanStack/db/commit/9bb6e8909cebdcd7c03091bfc12dd37f5ab2e1ea), [`8eb7e9b`](https://github.com/TanStack/db/commit/8eb7e9b1d1f569c5c064e0f440257589486b73cf)]:
42 |   - @tanstack/db@0.0.2
43 | 
44 | ## 0.0.1
45 | 
46 | ### Patch Changes
47 | 
48 | - feat: Initial release ([#2](https://github.com/TanStack/db/pull/2))
49 | 
50 | - Updated dependencies [[`2d2dd77`](https://github.com/TanStack/db/commit/2d2dd7743f715ffefaeee8e8d11173b751c7043b)]:
51 |   - @tanstack/db@0.0.1
52 | 


--------------------------------------------------------------------------------
/packages/react-db/README.md:
--------------------------------------------------------------------------------
1 | # @tanstack/react-db
2 | 
3 | React hooks for TanStack DB. See [TanStack/db](https://github.com/TanStack/db) for more details.
4 | 


--------------------------------------------------------------------------------
/packages/react-db/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@tanstack/react-db",
 3 |   "description": "React integration for @tanstack/db",
 4 |   "version": "0.0.4",
 5 |   "author": "Kyle Mathews",
 6 |   "license": "MIT",
 7 |   "repository": {
 8 |     "type": "git",
 9 |     "url": "https://github.com/TanStack/db.git",
10 |     "directory": "packages/react-db"
11 |   },
12 |   "homepage": "https://tanstack.com/db",
13 |   "keywords": [
14 |     "optimistic",
15 |     "react",
16 |     "typescript"
17 |   ],
18 |   "packageManager": "pnpm@10.5.2",
19 |   "dependencies": {
20 |     "@tanstack/db": "workspace:*",
21 |     "@tanstack/react-store": "^0.7.0",
22 |     "use-sync-external-store": "^1.2.0"
23 |   },
24 |   "devDependencies": {
25 |     "@electric-sql/client": "1.0.0",
26 |     "@testing-library/react": "^16.2.0",
27 |     "@types/react": "^19.0.12",
28 |     "@types/react-dom": "^19.0.3",
29 |     "@types/use-sync-external-store": "^0.0.6",
30 |     "@vitest/coverage-istanbul": "^3.0.9",
31 |     "react": "^19.0.0",
32 |     "react-dom": "^19.0.0"
33 |   },
34 |   "exports": {
35 |     ".": {
36 |       "import": {
37 |         "types": "./dist/esm/index.d.ts",
38 |         "default": "./dist/esm/index.js"
39 |       },
40 |       "require": {
41 |         "types": "./dist/cjs/index.d.cts",
42 |         "default": "./dist/cjs/index.cjs"
43 |       }
44 |     },
45 |     "./package.json": "./package.json"
46 |   },
47 |   "files": [
48 |     "dist",
49 |     "src"
50 |   ],
51 |   "main": "dist/cjs/index.cjs",
52 |   "module": "dist/esm/index.js",
53 |   "peerDependencies": {
54 |     "react": ">=16.8.0"
55 |   },
56 |   "scripts": {
57 |     "build": "vite build",
58 |     "dev": "vite build --watch",
59 |     "test": "npx vitest --run",
60 |     "lint": "eslint . --fix"
61 |   },
62 |   "sideEffects": false,
63 |   "type": "module",
64 |   "types": "dist/esm/index.d.ts"
65 | }
66 | 


--------------------------------------------------------------------------------
/packages/react-db/src/index.ts:
--------------------------------------------------------------------------------
 1 | // Re-export all public APIs
 2 | export * from "./useOptimisticMutation"
 3 | export * from "./useLiveQuery"
 4 | 
 5 | // Re-export everything from @tanstack/db
 6 | export * from "@tanstack/db"
 7 | 
 8 | // Re-export some stuff explicitly to ensure the type & value is exported
 9 | export { Collection } from "@tanstack/db"
10 | export { createTransaction } from "@tanstack/db"
11 | 


--------------------------------------------------------------------------------
/packages/react-db/src/useLiveQuery.ts:
--------------------------------------------------------------------------------
 1 | import { useEffect, useMemo, useState } from "react"
 2 | import { useStore } from "@tanstack/react-store"
 3 | import { compileQuery, queryBuilder } from "@tanstack/db"
 4 | import type {
 5 |   Collection,
 6 |   Context,
 7 |   InitialQueryBuilder,
 8 |   QueryBuilder,
 9 |   ResultsFromContext,
10 |   Schema,
11 | } from "@tanstack/db"
12 | 
13 | export interface UseLiveQueryReturn<T extends object> {
14 |   state: Map<string, T>
15 |   data: Array<T>
16 |   collection: Collection<T>
17 | }
18 | 
19 | export function useLiveQuery<
20 |   TResultContext extends Context<Schema> = Context<Schema>,
21 | >(
22 |   queryFn: (
23 |     q: InitialQueryBuilder<Context<Schema>>
24 |   ) => QueryBuilder<TResultContext>,
25 |   deps: Array<unknown> = []
26 | ): UseLiveQueryReturn<ResultsFromContext<TResultContext>> {
27 |   const [restart, forceRestart] = useState(0)
28 | 
29 |   const compiledQuery = useMemo(() => {
30 |     const query = queryFn(queryBuilder())
31 |     const compiled = compileQuery(query)
32 |     compiled.start()
33 |     return compiled
34 |   }, [...deps, restart])
35 | 
36 |   const state = useStore(compiledQuery.results.derivedState)
37 |   const data = useStore(compiledQuery.results.derivedArray)
38 | 
39 |   // Clean up on unmount
40 |   useEffect(() => {
41 |     if (compiledQuery.state === `stopped`) {
42 |       forceRestart((count) => {
43 |         return (count += 1)
44 |       })
45 |     }
46 | 
47 |     return () => {
48 |       compiledQuery.stop()
49 |     }
50 |   }, [compiledQuery])
51 | 
52 |   return {
53 |     state,
54 |     data,
55 |     collection: compiledQuery.results,
56 |   }
57 | }
58 | 


--------------------------------------------------------------------------------
/packages/react-db/src/useOptimisticMutation.ts:
--------------------------------------------------------------------------------
 1 | import { createTransaction } from "@tanstack/db"
 2 | import type { Transaction, TransactionConfig } from "@tanstack/db"
 3 | 
 4 | export function useOptimisticMutation(config: TransactionConfig) {
 5 |   return {
 6 |     mutate: (callback: () => void): Transaction => {
 7 |       const transaction = createTransaction(config)
 8 |       transaction.mutate(callback)
 9 |       return transaction
10 |     },
11 |     createTransaction: (): Transaction => {
12 |       return createTransaction({ ...config, autoCommit: false })
13 |     },
14 |   }
15 | }
16 | 


--------------------------------------------------------------------------------
/packages/react-db/tests/test-setup.ts:
--------------------------------------------------------------------------------
1 | import "@testing-library/jest-dom/vitest"
2 | import { cleanup } from "@testing-library/react"
3 | import { afterEach } from "vitest"
4 | 
5 | global.IS_REACT_ACT_ENVIRONMENT = true
6 | // https://testing-library.com/docs/react-testing-library/api#cleanup
7 | afterEach(() => cleanup())
8 | 


--------------------------------------------------------------------------------
/packages/react-db/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "extends": "../../tsconfig.json",
 3 |   "compilerOptions": {
 4 |     "target": "ES2020",
 5 |     "module": "ESNext",
 6 |     "moduleResolution": "Bundler",
 7 |     "declaration": true,
 8 |     "outDir": "dist",
 9 |     "strict": true,
10 |     "esModuleInterop": true,
11 |     "skipLibCheck": true,
12 |     "forceConsistentCasingInFileNames": true,
13 |     "jsx": "react-jsx",
14 |     "paths": {
15 |       "@tanstack/store": ["../store/src"],
16 |       "@tanstack/db": ["../db/src"]
17 |     }
18 |   },
19 |   "include": ["src/**/*", "tests", "vite.config.ts"],
20 |   "exclude": ["node_modules", "dist"]
21 | }
22 | 


--------------------------------------------------------------------------------
/packages/react-db/vite.config.ts:
--------------------------------------------------------------------------------
 1 | import { defineConfig, mergeConfig } from "vitest/config"
 2 | import { tanstackViteConfig } from "@tanstack/config/vite"
 3 | import react from "@vitejs/plugin-react"
 4 | import packageJson from "./package.json"
 5 | 
 6 | const config = defineConfig({
 7 |   plugins: [react()],
 8 |   test: {
 9 |     name: packageJson.name,
10 |     dir: `./tests`,
11 |     watch: false,
12 |     environment: `jsdom`,
13 |     setupFiles: [`./tests/test-setup.ts`],
14 |     coverage: { enabled: true, provider: `istanbul`, include: [`src/**/*`] },
15 |     typecheck: { enabled: true },
16 |   },
17 | })
18 | 
19 | export default mergeConfig(
20 |   config,
21 |   tanstackViteConfig({
22 |     entry: `./src/index.ts`,
23 |     srcDir: `./src`,
24 |   })
25 | )
26 | 


--------------------------------------------------------------------------------
/packages/vue-db/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # @tanstack/vue-db
 2 | 
 3 | ## 0.0.3
 4 | 
 5 | ### Patch Changes
 6 | 
 7 | - Updated dependencies [[`8ce449e`](https://github.com/TanStack/db/commit/8ce449ed6d070e9e591d1b74b0db5fed7a3fc92f)]:
 8 |   - @tanstack/db@0.0.4
 9 | 
10 | ## 0.0.2
11 | 
12 | ### Patch Changes
13 | 
14 | - Updated dependencies [[`b29420b`](https://github.com/TanStack/db/commit/b29420bcdae30dfeffeef63a8753b83306a54e5a)]:
15 |   - @tanstack/db@0.0.3
16 | 
17 | ## 0.0.1
18 | 
19 | ### Patch Changes
20 | 
21 | - Add Vue support ([#83](https://github.com/TanStack/db/pull/83))
22 | 


--------------------------------------------------------------------------------
/packages/vue-db/README.md:
--------------------------------------------------------------------------------
1 | # @tanstack/vue-db
2 | 
3 | Vue composables for TanStack DB. See [TanStack/db](https://github.com/TanStack/db) for more details.
4 | 


--------------------------------------------------------------------------------
/packages/vue-db/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@tanstack/vue-db",
 3 |   "description": "Vue integration for @tanstack/db",
 4 |   "version": "0.0.3",
 5 |   "author": "Kyle Mathews",
 6 |   "license": "MIT",
 7 |   "repository": {
 8 |     "type": "git",
 9 |     "url": "https://github.com/TanStack/db.git",
10 |     "directory": "packages/vue-db"
11 |   },
12 |   "homepage": "https://tanstack.com/db",
13 |   "keywords": [
14 |     "optimistic",
15 |     "vue",
16 |     "typescript"
17 |   ],
18 |   "packageManager": "pnpm@10.5.2",
19 |   "dependencies": {
20 |     "@tanstack/db": "workspace:*",
21 |     "@tanstack/vue-store": "^0.7.0"
22 |   },
23 |   "devDependencies": {
24 |     "@electric-sql/client": "1.0.0",
25 |     "@vitest/coverage-istanbul": "^3.0.9",
26 |     "@vitejs/plugin-vue": "^5.2.4",
27 |     "vue": "^3.5.13"
28 |   },
29 |   "exports": {
30 |     ".": {
31 |       "import": {
32 |         "types": "./dist/esm/index.d.ts",
33 |         "default": "./dist/esm/index.js"
34 |       },
35 |       "require": {
36 |         "types": "./dist/cjs/index.d.cts",
37 |         "default": "./dist/cjs/index.cjs"
38 |       }
39 |     },
40 |     "./package.json": "./package.json"
41 |   },
42 |   "files": [
43 |     "dist",
44 |     "src"
45 |   ],
46 |   "main": "dist/cjs/index.cjs",
47 |   "module": "dist/esm/index.js",
48 |   "peerDependencies": {
49 |     "vue": ">=3.3.0"
50 |   },
51 |   "scripts": {
52 |     "build": "vite build",
53 |     "dev": "vite build --watch",
54 |     "test": "npx vitest --run",
55 |     "lint": "eslint . --fix"
56 |   },
57 |   "sideEffects": false,
58 |   "type": "module",
59 |   "types": "dist/esm/index.d.ts"
60 | }
61 | 


--------------------------------------------------------------------------------
/packages/vue-db/src/index.ts:
--------------------------------------------------------------------------------
 1 | // Re-export all public APIs
 2 | export * from "./useOptimisticMutation"
 3 | export * from "./useLiveQuery"
 4 | 
 5 | // Re-export everything from @tanstack/db
 6 | export * from "@tanstack/db"
 7 | 
 8 | // Re-export some stuff explicitly to ensure the type & value is exported
 9 | export { Collection } from "@tanstack/db"
10 | export { createTransaction } from "@tanstack/db"
11 | 


--------------------------------------------------------------------------------
/packages/vue-db/src/useLiveQuery.ts:
--------------------------------------------------------------------------------
 1 | import { computed, toValue, watch } from "vue"
 2 | import { useStore } from "@tanstack/vue-store"
 3 | import { compileQuery, queryBuilder } from "@tanstack/db"
 4 | import type {
 5 |   Collection,
 6 |   Context,
 7 |   InitialQueryBuilder,
 8 |   QueryBuilder,
 9 |   ResultsFromContext,
10 |   Schema,
11 | } from "@tanstack/db"
12 | import type { ComputedRef, MaybeRefOrGetter } from "vue"
13 | 
14 | export interface UseLiveQueryReturn<T extends object> {
15 |   state: ComputedRef<Map<string, T>>
16 |   data: ComputedRef<Array<T>>
17 |   collection: ComputedRef<Collection<T>>
18 | }
19 | 
20 | export function useLiveQuery<
21 |   TResultContext extends Context<Schema> = Context<Schema>,
22 | >(
23 |   queryFn: (
24 |     q: InitialQueryBuilder<Context<Schema>>
25 |   ) => QueryBuilder<TResultContext>,
26 |   deps: Array<MaybeRefOrGetter<unknown>> = []
27 | ): UseLiveQueryReturn<ResultsFromContext<TResultContext>> {
28 |   const compiledQuery = computed(() => {
29 |     // Just reference deps to make computed reactive to them
30 |     deps.forEach((dep) => toValue(dep))
31 | 
32 |     const query = queryFn(queryBuilder())
33 |     const compiled = compileQuery(query)
34 |     compiled.start()
35 |     return compiled
36 |   })
37 | 
38 |   const state = computed(() => {
39 |     return useStore(compiledQuery.value.results.derivedState).value
40 |   })
41 |   const data = computed(() => {
42 |     return useStore(compiledQuery.value.results.derivedArray).value
43 |   })
44 | 
45 |   watch(compiledQuery, (newQuery, oldQuery, onInvalidate) => {
46 |     if (newQuery.state === `stopped`) {
47 |       newQuery.start()
48 |     }
49 | 
50 |     onInvalidate(() => {
51 |       oldQuery.stop()
52 |     })
53 |   })
54 | 
55 |   return {
56 |     state,
57 |     data,
58 |     collection: computed(() => compiledQuery.value.results),
59 |   }
60 | }
61 | 


--------------------------------------------------------------------------------
/packages/vue-db/src/useOptimisticMutation.ts:
--------------------------------------------------------------------------------
 1 | import { createTransaction } from "@tanstack/db"
 2 | import type { Transaction, TransactionConfig } from "@tanstack/db"
 3 | 
 4 | export function useOptimisticMutation(config: TransactionConfig) {
 5 |   return {
 6 |     mutate: (callback: () => void): Transaction => {
 7 |       const transaction = createTransaction(config)
 8 |       transaction.mutate(callback)
 9 |       return transaction
10 |     },
11 |     createTransaction: (): Transaction => {
12 |       return createTransaction({ ...config, autoCommit: false })
13 |     },
14 |   }
15 | }
16 | 


--------------------------------------------------------------------------------
/packages/vue-db/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "extends": "../../tsconfig.json",
 3 |   "compilerOptions": {
 4 |     "target": "ES2020",
 5 |     "module": "ESNext",
 6 |     "moduleResolution": "Bundler",
 7 |     "declaration": true,
 8 |     "outDir": "dist",
 9 |     "strict": true,
10 |     "esModuleInterop": true,
11 |     "skipLibCheck": true,
12 |     "forceConsistentCasingInFileNames": true,
13 |     "paths": {
14 |       "@tanstack/store": ["../store/src"],
15 |       "@tanstack/db": ["../db/src"]
16 |     }
17 |   },
18 |   "include": ["src/**/*", "tests", "vite.config.ts"],
19 |   "exclude": ["node_modules", "dist"]
20 | }
21 | 


--------------------------------------------------------------------------------
/packages/vue-db/vite.config.ts:
--------------------------------------------------------------------------------
 1 | import { defineConfig, mergeConfig } from "vitest/config"
 2 | import { tanstackViteConfig } from "@tanstack/config/vite"
 3 | import vue from "@vitejs/plugin-vue"
 4 | import packageJson from "./package.json"
 5 | 
 6 | const config = defineConfig({
 7 |   plugins: [vue()],
 8 |   test: {
 9 |     name: packageJson.name,
10 |     dir: `./tests`,
11 |     watch: false,
12 |     environment: `jsdom`,
13 |     coverage: { enabled: true, provider: `istanbul`, include: [`src/**/*`] },
14 |     typecheck: { enabled: true },
15 |   },
16 | })
17 | 
18 | export default mergeConfig(
19 |   config,
20 |   tanstackViteConfig({
21 |     entry: `./src/index.ts`,
22 |     srcDir: `./src`,
23 |   })
24 | )
25 | 


--------------------------------------------------------------------------------
/pnpm-workspace.yaml:
--------------------------------------------------------------------------------
1 | packages:
2 |   - "packages/**"
3 |   - "examples/**"
4 | 


--------------------------------------------------------------------------------
/todo.md:
--------------------------------------------------------------------------------
 1 | # TODO: Sync Library Implementation
 2 | 
 3 | ## 1. Project Initialization
 4 | 
 5 | - [ ] **1A**: Create & configure a new TypeScript project
 6 |   - [ ] Initialize `package.json`
 7 |   - [ ] Add `tsconfig.json` with standard TS settings
 8 |   - [ ] Set up Jest or Vitest test runner
 9 | - [ ] **1B**: Linting & Formatting - [ ] Install ESLint / Prettier (or similar) - [ ] Add minimal lint/format config - [ ] Create a "hello world" test in `tests/hello.test.ts` to verify everything works
10 | 
11 | ## 2. Types & Basic Helpers
12 | 
13 | - [ ] **2A**: Define **core interfaces** in `src/types.ts` - [ ] `TransactionState` - [ ] `Attempt` - [ ] `PendingMutation` - [ ] `Transaction`
14 | - [ ] **2B**: Define **Sync-related types** in `src/types.ts` - [ ] `SyncConfig` - [ ] `MutationFn` - [ ] `MutationStrategy`
15 | - [ ] **2C**: Create `NonRetriableError` in `src/errors.ts`
16 | - [ ] **2D**: Create a placeholder `getLockedObjects` in `src/utils.ts` (return empty `Set` for now)
17 | - [ ] **2E**: Unit tests in `tests/types.test.ts` - [ ] Confirm each interface/type is defined correctly - [ ] Verify basic usage or shape checking
18 | 
19 | ## 3. IndexedDB Storage
20 | 
21 | - [ ] **3A**: Implement `TransactionStore` in `src/TransactionStore.ts` - [ ] `getTransactions(): Promise<Transaction[]>` - [ ] `putTransaction(tx: Transaction): Promise<void>` - [ ] `deleteTransaction(id: string): Promise<void>` - [ ] Internally use IndexedDB or an equivalent library
22 | - [ ] **3B**: Write tests in `tests/TransactionStore.test.ts` - [ ] Confirm create/update/delete flow - [ ] Verify correct reading of stored transactions
23 | 
24 | ## 4. TransactionManager & Lifecycle
25 | 
26 | - [ ] **4A**: Create `TransactionManager` in `src/TransactionManager.ts` - [ ] Constructor accepts `TransactionStore` - [ ] `createTransaction(mutations: PendingMutation[], strategy: MutationStrategy): Promise<Transaction>`
27 | - [ ] **4B**: Add lifecycle state management - [ ] `updateTransactionState(id: string, newState: TransactionState): Promise<void>` - [ ] Transitions: `pending`, `persisting`, `completed`, `failed`, etc.
28 | - [ ] **4C**: Implement exponential backoff in `scheduleRetry(id: string, attemptNumber: number)`
29 | - [ ] **4D**: Write tests in `tests/TransactionManager.test.ts` - [ ] Creating a new transaction - [ ] Changing transaction states & verifying correctness - [ ] Checking scheduled retry times (no actual timer needed, just stored times)
30 | 
31 | ## 5. Modes: Ordered vs. Parallel
32 | 
33 | - [ ] **5A**: Extend `TransactionManager` to handle a `type` field in `MutationStrategy` (either `'ordered'` or `'parallel'`)
34 | - [ ] **5B**: Ordered logic - [ ] Enqueue new transactions if an existing one is still `persisting` or `queued`
35 | - [ ] **5C**: Parallel logic - [ ] Immediately mark transactions `pending` or `persisting` - [ ] No explicit queue
36 | - [ ] **5D**: Concurrency tests in `tests/TransactionManager.test.ts` - [ ] Multiple transactions in ordered mode (should not persist in parallel) - [ ] Multiple transactions in parallel mode (should run immediately)
37 | 
38 | ## 6. Basic `useCollection` Hook
39 | 
40 | - [ ] **6A**: Create `src/useCollection.ts` - [ ] Export `useCollection(config: { sync: SyncConfig; mutationFn?: MutationFn })` - [ ] Return `{ data, update, insert, delete: deleteFn, withMutation }`
41 | - [ ] **6B**: Connect to `TransactionManager` - [ ] On `update/insert/delete`, call `createTransaction()`
42 | - [ ] **6C**: Basic test in `tests/useCollection.test.ts` - [ ] Render a React component using the hook - [ ] Call `update()` or `insert()` - [ ] Confirm that a transaction is created (verify some state in manager or a mock function) - [ ] `data` can be empty or unchanged for now
43 | 
44 | ## 7. Optimistic Updates
45 | 
46 | - [ ] **7A**: Implement local data state inside `useCollection`
47 | - [ ] **7B**: On transaction creation, immediately apply changes to `data`
48 | - [ ] **7C**: On transaction failure, revert changes
49 | - [ ] **7D**: Write new tests in `tests/useCollection.test.ts` - [ ] Simulate success -> `data` remains updated - [ ] Simulate failure -> `data` reverts
50 | 
51 | ## 8. Mock Persist & Retry
52 | 
53 | - [ ] **8A**: Add a **mock** `persist` method in `mutationFn` - [ ] Wait ~100–500ms - [ ] 50% chance success, 50% chance fail
54 | - [ ] **8B**: On failure, trigger retries in `TransactionManager` - [ ] Up to 4 retries
55 | - [ ] **8C**: Unit tests for retry behavior - [ ] Verify final transaction state after repeated failures -> `failed` - [ ] Verify success after a retry -> `completed` - [ ] Check local data for revert vs. final updates
56 | 
57 | ## 9. Sync Merges & Lock Management
58 | 
59 | - [ ] **9A**: For ordered mode, block subsequent transactions while one is `persisting` - [ ] Release lock after `persisting` transaction completes
60 | - [ ] **9B**: Provide a **minimal or no-op** merge function for parallel mode - [ ] Reapply optimistic updates on new sync data
61 | - [ ] **9C**: Allow a custom merge function to be passed in
62 | - [ ] **9D**: Add concurrency tests - [ ] Locking logic in ordered mode - [ ] Parallel concurrency with merges
63 | 
64 | ## 10. Real `setup` & Integration
65 | 
66 | - [ ] **10A**: Implement a real or mock `setup` in `SyncConfig` - [ ] Fetch initial data from an endpoint or test fixture
67 | - [ ] **10B**: Evolve the mock `persist` into a more realistic approach - [ ] Possibly call a local in-memory server or a test-based REST endpoint
68 | - [ ] **10C**: Write integration test in `tests/integration.test.ts` - [ ] Confirm initial data is loaded - [ ] Perform a successful update -> data updates - [ ] Perform a failing update -> confirm revert or eventual success with retry - [ ] Ensure everything ties together end-to-end
69 | 
70 | ## 11. Advanced Errors, Logging & Cleanup
71 | 
72 | - [ ] **11A**: Utilize `NonRetriableError` - [ ] E.g., if API returns 400, throw `NonRetriableError` and skip retries
73 | - [ ] **11B**: Optional logging / event hooks in `TransactionManager` - [ ] Provide ways to track or debug transaction states
74 | - [ ] **11C**: Final code cleanup - [ ] Remove stubs/orphan code - [ ] Ensure everything is exported from `src/index.ts` or a root file
75 | - [ ] **11D**: Final coverage check / polish - [ ] Ensure tests cover all key flows - [ ] Document usage in a short README or doc
76 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "allowJs": true,
 4 |     "allowSyntheticDefaultImports": true,
 5 |     "allowUnreachableCode": false,
 6 |     "allowUnusedLabels": false,
 7 |     "checkJs": true,
 8 |     "declaration": true,
 9 |     "esModuleInterop": true,
10 |     "forceConsistentCasingInFileNames": true,
11 |     "isolatedModules": true,
12 |     "lib": ["ES2022", "DOM", "DOM.Iterable"],
13 |     "module": "NodeNext",
14 |     "moduleResolution": "bundler",
15 |     "noEmit": true,
16 |     "noImplicitReturns": true,
17 |     "noUncheckedIndexedAccess": true,
18 |     "noUnusedLocals": true,
19 |     "noUnusedParameters": true,
20 |     "resolveJsonModule": true,
21 |     "skipLibCheck": true,
22 |     "strict": true,
23 |     "target": "ES2020",
24 |     "jsx": "react-jsx"
25 |   },
26 |   "include": [
27 |     "src/**/*.ts",
28 |     "src/**/*.tsx",
29 |     "test/**/*.ts",
30 |     "vite.config.ts",
31 |     "vitest.config.ts",
32 |     "todo-app/**/*.ts",
33 |     "todo-app/**/*.tsx",
34 |     "examples/**/*.ts",
35 |     "examples/**/*.tsx",
36 |     "eslint.config.mjs"
37 |   ],
38 |   "exclude": ["node_modules"]
39 | }
40 | 


--------------------------------------------------------------------------------