add findOne() to query builder by fcannizzaro · Pull Request #440 · TanStack/db

fcannizzaro · 2025-08-23T19:32:01Z

Hi! I've implemented the findOne() in the query builder (#182) for db and react-db.

When findOne() is chained in the query builder, I store a single variable in the context (extending also the context type for the inference) that is then inherited from the collection config to allow the data getter to return a single row or an array.

I also tested both db/test and react-db/test (by adding also a dedicated test for this feature).

LMK if it's ok to do like this or if you have some better ideas.

changeset-bot · 2025-08-23T19:32:06Z

⚠️ No Changeset found

Latest commit: 50d3dd8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

obeattie · 2025-08-29T14:54:29Z

I'd definitely find an API like this to retrieve just a single row helpful.

samwillis · 2025-09-09T22:19:32Z

@fcannizzaro just letting you know this hasn't dropped off my radar, we discussed it in a meeting today and are going to push through with adding this findOne api. I'll get back to you with a proper review and some guidance tomorrow.

pkg-pr-new · 2025-09-27T16:47:33Z

More templates

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@440

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@440

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@440

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@440

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@440

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@440

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@440

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@440

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@440

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@440

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@440

commit: 50d3dd8

samwillis · 2025-09-27T16:47:56Z

Hi @fcannizzaro, I'm finally catching up on this. I've rebased your branch on main, and fixed a couple of things. One addition is that it now supports specifying findOne() outside the context of a useLiveQuery call, so constructing the live query collection elsewhere then passing that to the useLiveQuery. This needed feeding single: true through a few more layers...

@kevin-dp could you take a look at this, you may know of a cleaner way to do this.

kevin-dp

Great work. I left a few minor comments that we should address to improve maintainability.

packages/db/src/collection/index.ts

packages/db/src/query/builder/index.ts

packages/db/src/query/compiler/index.ts

packages/db/src/types.ts

packages/db/src/query/live-query-collection.ts

packages/react-db/src/useLiveQuery.ts

packages/db/src/query/builder/types.ts

samwillis

This is looking great @fcannizzaro, I think we are nearly there.

It looks like there is a type error throwing in CI, once thats fixed I suspect we are ready to approve.

fcannizzaro · 2025-09-30T12:45:52Z

@samwillis Can you check what's the error ? Locally pnpm test has no failed test

samwillis · 2025-09-30T13:14:46Z

Seems to be in the react-db package:

packages/react-db test:  ✓  TS   @tanstack/react-db  tests/useLiveQuery.test-d.tsx (4 tests)
packages/react-db test: ⎯⎯⎯⎯⎯⎯ Unhandled Errors ⎯⎯⎯⎯⎯⎯
packages/react-db test: 
packages/react-db test: Vitest caught 2 unhandled errors during the test run.
packages/react-db test: This might cause false positive tests. Resolve unhandled errors to make sure your tests are not affected.
packages/react-db test: ⎯⎯⎯ Unhandled Source Error ⎯⎯⎯
packages/react-db test: TypeCheckError: No overload matches this call.
packages/react-db test:   The last overload gave the following error.
packages/react-db test:     Type 'Plugin<any>[]' is not assignable to type 'PluginOption'.
packages/react-db test:       Type 'Plugin<any>[]' is not assignable to type 'PluginOption[]'.
packages/react-db test:         Type 'Plugin<any>' is not assignable to type 'PluginOption'.
packages/react-db test:           Type 'Plugin<any>' is not assignable to type 'Plugin$1<any>'.
packages/react-db test:             Types of property 'hotUpdate' are incompatible.
packages/react-db test:               Type 'ObjectHook<(this HotUpdatePluginContext, options HotUpdateOptions) => void | EnvironmentModuleNode[] | Promise<void | EnvironmentModuleNode[]>> | undefined' is not assignable to type 'ObjectHook<(this MinimalPluginContext & { environment DevEnvironment; }, options HotUpdateOptions) => void | EnvironmentModuleNode[] | Promise<void | EnvironmentModuleNode[]>> | undefined'.
packages/react-db test:                 Type '(this HotUpdatePluginContext, options HotUpdateOptions) => void | EnvironmentModuleNode[] | Promise<void | EnvironmentModuleNode[]>' is not assignable to type 'ObjectHook<(this MinimalPluginContext & { environment DevEnvironment; }, options HotUpdateOptions) => void | EnvironmentModuleNode[] | Promise<void | EnvironmentModuleNode[]>> | undefined'.
packages/react-db test:                   Type '(this HotUpdatePluginContext, options HotUpdateOptions) => void | EnvironmentModuleNode[] | Promise<void | EnvironmentModuleNode[]>' is not assignable to type '(this MinimalPluginContext & { environment DevEnvironment; }, options HotUpdateOptions) => void | EnvironmentModuleNode[] | Promise<void | EnvironmentModuleNode[]>'.
packages/react-db test:                     The 'this' types of each signature are incompatible.
packages/react-db test:                       Type 'MinimalPluginContext & { environment DevEnvironment; }' is not assignable to type 'HotUpdatePluginContext'.
packages/react-db test:                         Types of property 'environment' are incompatible.
packages/react-db test:                           Property 'options' is missing in type 'import("/home/runner/work/db/db/node_modules/.pnpm/vite@7.1.7_@types+node@22.18.1_jiti@2.6.0_lightningcss@1.30.1_sass@1.90.0_terser@5.44.0_tsx@4.20.6_yaml@2.8.1/node_modules/vite/dist/node/index").DevEnvironment' but required in type 'import("/home/runner/work/db/db/node_modules/.pnpm/vite@6.3.6_@types+node@22.18.1_jiti@2.6.0_lightningcss@1.30.1_sass@1.90.0_terser@5.44.0_tsx@4.20.6_yaml@2.8.1/node_modules/vite/dist/node/index").DevEnvironment'.
packages/react-db test:  ❯ vite.config.ts:7:13
packages/react-db test: ⎯⎯⎯ Unhandled Source Error ⎯⎯⎯
packages/react-db test: TypeCheckError: Argument of type 'UserConfig & Promise<UserConfig> & (UserConfigFnObject & UserConfigExport)' is not assignable to parameter of type 'never'.
packages/react-db test:   Type 'UserConfig & Promise<UserConfig> & UserConfigFnObject' is not assignable to type 'never'.
packages/react-db test:  ❯ vite.config.ts:19:3
packages/react-db test: ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
packages/react-db test:  Test Files  2 passed (2)
packages/react-db test:       Tests  29 passed (29)
packages/react-db test: Type Errors  no errors
packages/react-db test:      Errors  2 errors
packages/react-db test:    Start at  12:18:39
packages/react-db test:    Duration  13.46s (transform 2.68s, setup 590ms, collect 3.51s, tests 522ms, environment 2.04s, prepare 388ms, typecheck 13.05s)

https://github.com/TanStack/db/actions/runs/18129520557/job/51592548474?pr=440

fcannizzaro · 2025-09-30T13:31:29Z

It seems a vite configuration error (?)

samwillis

I fixed the type issue in another pr, then merged in main. All good now.
Just going to merge!

Thanks @fcannizzaro! 🥳

fcannizzaro and others added 4 commits September 27, 2025 13:26

add findOne() to query builder

da9c97c

move utility type to db/types

e954b29

fix utility type

817afa4

add single support to aditional useLiveQuery overloads

79ab356

samwillis force-pushed the add-find-one-to-query branch from 6196879 to c18e878 Compare September 27, 2025 16:45

Add support for specifying .findOne() outside of a query builder

61b66a5

samwillis force-pushed the add-find-one-to-query branch from c18e878 to 61b66a5 Compare September 27, 2025 16:48

samwillis requested a review from kevin-dp September 27, 2025 16:48

kevin-dp approved these changes Sep 29, 2025

View reviewed changes

kevin-dp reviewed Sep 29, 2025

View reviewed changes

packages/db/src/query/builder/types.ts Outdated Show resolved Hide resolved

samwillis and others added 5 commits September 29, 2025 17:50

WIP addressing of the review

594cc93

fix for review

ea94c4e

remove unused offset

f1ea36f

restore text comments

3e9512f

restore text comments

f9c46a8

samwillis reviewed Sep 30, 2025

View reviewed changes

disable limit=1 for future enforcing

40e1e7a

KyleAMathews moved this to In Progress in TanStack DB 1.0.0 release Sep 30, 2025

KyleAMathews added this to TanStack DB 1.0.0 release Sep 30, 2025

Merge branch 'main' into add-find-one-to-query

257dd56

samwillis mentioned this pull request Oct 3, 2025

update vite deps and node types to fix types issues #636

Merged

Merge branch 'main' into add-find-one-to-query

50d3dd8

samwillis approved these changes Oct 3, 2025

View reviewed changes

samwillis merged commit c4c2399 into TanStack:main Oct 3, 2025
6 checks passed

fcannizzaro deleted the add-find-one-to-query branch October 3, 2025 17:41

evanheckert mentioned this pull request Oct 25, 2025

add a .findOne() to query build to return the first item #182

Closed

KyleAMathews moved this from In Progress to Done in TanStack DB 1.0.0 release Nov 4, 2025

elohmeier mentioned this pull request Dec 11, 2025

feat(svelte-db): Add findOne() / SingleResult support to useLiveQuery #1001

Merged

Conversation

fcannizzaro commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

obeattie commented Aug 29, 2025

Uh oh!

samwillis commented Sep 9, 2025

Uh oh!

pkg-pr-new bot commented Sep 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

samwillis commented Sep 27, 2025

Uh oh!

kevin-dp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samwillis left a comment

Choose a reason for hiding this comment

Uh oh!

fcannizzaro commented Sep 30, 2025

Uh oh!

samwillis commented Sep 30, 2025

Uh oh!

fcannizzaro commented Sep 30, 2025

Uh oh!

samwillis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fcannizzaro commented Aug 23, 2025 •

edited

Loading

changeset-bot bot commented Aug 23, 2025 •

edited

Loading

pkg-pr-new bot commented Sep 27, 2025 •

edited

Loading