Query once API implementation (#1211)

samwillis · cursoragent · autofix-ci[bot] · web-flow · commit 41c0ea2d956f · 2026-03-10T11:43:20.000Z
* feat(db): add queryOnce API for one-shot query execution

Implements the queryOnce function as described in the RFC. This provides
a lightweight wrapper around createLiveQueryCollection that:

- Creates a live query collection with gcTime: 0
- Preloads the data
- Extracts results as an array (or single item for findOne)
- Automatically cleans up the collection

The queryOnce function:
- Accepts either a query function or config object
- Supports all query builder operations (where, select, join, orderBy, etc.)
- Properly handles findOne() queries returning single results
- Ensures cleanup happens even on error via try/finally

Use cases:
- AI/LLM context building
- Data export
- Background processing
- Testing

API:
```typescript
// Simple query
const users = await queryOnce((q) =&gt;
  q.from({ user: usersCollection })
   .where(({ user }) =&gt; eq(user.active, true))
)

// Single result with findOne
const user = await queryOnce((q) =&gt;
  q.from({ user: usersCollection })
   .where(({ user }) =&gt; eq(user.id, 1))
   .findOne()
)

// Config object form
const orders = await queryOnce({
  query: (q) =&gt; q.from({ order: ordersCollection }).limit(100)
})
```

* ci: apply automated fixes

* fix(db): use gcTime 1 for queryOnce cleanup

* docs: add queryOnce to live queries guide

* feat(db): allow queryOnce to accept QueryBuilder

Co-authored-by: sam.willis &lt;sam.willis@gmail.com&gt;

* refactor(db): tighten queryOnce runtime behavior

* ci: apply automated fixes

* fix(db): normalize queryOnce query builder input

* chore: add changeset for queryOnce

* ci: apply automated fixes

* fix(db): remove redundant queryOnce undefined fallback

Drop the unnecessary nullish-coalescing in queryOnce so the single-result path returns the iterator value directly while preserving the existing undefined-on-empty behavior.

Made-with: Cursor

---------

Co-authored-by: Cursor Agent &lt;cursoragent@cursor.com&gt;
Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
diff --git a/.changeset/query-once-api.md b/.changeset/query-once-api.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/db': minor
+---
+
+Add `queryOnce` helper for one-shot query execution, including `findOne()` support and optional QueryBuilder configs.
diff --git a/docs/guides/live-queries.md b/docs/guides/live-queries.md
@@ -32,6 +32,7 @@ The result types are automatically inferred from your query structure, providing
 ## Table of Contents
 
 - [Creating Live Query Collections](#creating-live-query-collections)
+- [One-shot Queries with queryOnce](#one-shot-queries-with-queryonce)
 - [From Clause](#from-clause)
 - [Where Clauses](#where-clauses)
 - [Select Projections](#select)
@@ -114,6 +115,36 @@ const activeUsers = createLiveQueryCollection((q) =>
 )
 ```
 
+## One-shot Queries with queryOnce
+
+If you need a one-time snapshot (no ongoing reactivity), use `queryOnce`. It
+creates a live query collection, preloads it, extracts the results, and cleans
+up automatically so you do not have to remember to call `cleanup()`.
+
+```ts
+import { eq, queryOnce } from '@tanstack/db'
+
+// Basic one-shot query
+const activeUsers = await queryOnce((q) =>
+  q
+    .from({ user: usersCollection })
+    .where(({ user }) => eq(user.active, true))
+    .select(({ user }) => ({ id: user.id, name: user.name }))
+)
+
+// Single result with findOne()
+const user = await queryOnce((q) =>
+  q
+    .from({ user: usersCollection })
+    .where(({ user }) => eq(user.id, userId))
+    .findOne()
+)
+```
+
+Use `queryOnce` for scripts, background tasks, data export, or AI/LLM context
+building. `findOne()` resolves to `undefined` when no rows match. For UI
+bindings and reactive updates, use live queries instead.
+
 ### Using with Frameworks
 
 In React, you can use the `useLiveQuery` hook:
diff --git a/packages/db/src/query/index.ts b/packages/db/src/query/index.ts
@@ -74,6 +74,9 @@ export {
   liveQueryCollectionOptions,
 } from './live-query-collection.js'
 
+// One-shot query execution
+export { queryOnce, type QueryOnceConfig } from './query-once.js'
+
 export { type LiveQueryCollectionConfig } from './live/types.js'
 export { type LiveQueryCollectionUtils } from './live/collection-config-builder.js'
 
diff --git a/packages/db/src/query/query-once.ts b/packages/db/src/query/query-once.ts
@@ -0,0 +1,115 @@
+import { createLiveQueryCollection } from './live-query-collection.js'
+import type { InitialQueryBuilder, QueryBuilder } from './builder/index.js'
+import type { Context, InferResultType } from './builder/types.js'
+
+/**
+ * Configuration options for queryOnce
+ */
+export interface QueryOnceConfig<TContext extends Context> {
+  /**
+   * Query builder function that defines the query
+   */
+  query:
+    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)
+    | QueryBuilder<TContext>
+  // Future: timeout, signal, etc.
+}
+
+// Overload 1: Simple query function returning array (non-single result)
+/**
+ * Executes a one-shot query and returns the results as an array.
+ *
+ * This function creates a live query collection, preloads it, extracts the results,
+ * and automatically cleans up the collection. It's ideal for:
+ * - AI/LLM context building
+ * - Data export
+ * - Background processing
+ * - Testing
+ *
+ * @param queryFn - A function that receives the query builder and returns a query
+ * @returns A promise that resolves to an array of query results
+ *
+ * @example
+ * ```typescript
+ * // Basic query
+ * const users = await queryOnce((q) =>
+ *   q.from({ user: usersCollection })
+ * )
+ *
+ * // With filtering and projection
+ * const activeUserNames = await queryOnce((q) =>
+ *   q.from({ user: usersCollection })
+ *    .where(({ user }) => eq(user.active, true))
+ *    .select(({ user }) => ({ name: user.name }))
+ * )
+ * ```
+ */
+export function queryOnce<TContext extends Context>(
+  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
+): Promise<InferResultType<TContext>>
+
+// Overload 2: Config object form returning array (non-single result)
+/**
+ * Executes a one-shot query using a configuration object.
+ *
+ * @param config - Configuration object with the query function
+ * @returns A promise that resolves to an array of query results
+ *
+ * @example
+ * ```typescript
+ * const recentOrders = await queryOnce({
+ *   query: (q) =>
+ *     q.from({ order: ordersCollection })
+ *      .orderBy(({ order }) => desc(order.createdAt))
+ *      .limit(100),
+ * })
+ * ```
+ */
+export function queryOnce<TContext extends Context>(
+  config: QueryOnceConfig<TContext>,
+): Promise<InferResultType<TContext>>
+
+// Implementation
+export async function queryOnce<TContext extends Context>(
+  configOrQuery:
+    | QueryOnceConfig<TContext>
+    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>),
+): Promise<InferResultType<TContext>> {
+  // Normalize input
+  const config: QueryOnceConfig<TContext> =
+    typeof configOrQuery === `function`
+      ? { query: configOrQuery }
+      : configOrQuery
+
+  const query = (q: InitialQueryBuilder) => {
+    const queryConfig = config.query
+    return typeof queryConfig === `function` ? queryConfig(q) : queryConfig
+  }
+
+  // Create collection with minimal GC time; preload handles sync start
+  const collection = createLiveQueryCollection({
+    query,
+    gcTime: 1, // Cleanup in next tick when no subscribers (0 disables GC)
+  })
+
+  try {
+    // Wait for initial data load
+    await collection.preload()
+
+    // Check if this is a single-result query (findOne was called)
+    const isSingleResult =
+      (collection.config as { singleResult?: boolean }).singleResult === true
+
+    // Extract and return results
+    if (isSingleResult) {
+      const first = collection.values().next().value as
+        | InferResultType<TContext>
+        | undefined
+      return first as InferResultType<TContext>
+    }
+    return collection.toArray as InferResultType<TContext>
+  } finally {
+    // Always cleanup, even on error
+    await collection.cleanup()
+  }
+}
diff --git a/packages/db/tests/query/query-once.test.ts b/packages/db/tests/query/query-once.test.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/db': minor
 +---
++
 +Add `queryOnce` helper for one-shot query execution, including `findOne()` support and optional QueryBuilder configs.