({
- id: `conformance-angular-${sourceSeq++}`,
+ id: collectionId ?? `conformance-angular-${sourceSeq++}`,
getKey: (r) => r.id,
initialData: [...initialData],
}),
@@ -213,17 +216,28 @@ function mountControllable(
initial: P,
): ControllableHandle
{
const param = signal
(initial)
- const { result, destroy } = inCtx(() =>
- injectLiveQuery({
+ const published = createPublicationLog()
+ const { result, destroy } = inCtx(() => {
+ const query = injectLiveQuery({
params: () => ({ value: param() }),
query: ({ params, q }: any) => build(q, params.value),
- }),
- )
+ })
+ // Angular renders the value each effect run reads.
+ effect(() => {
+ published.record(query.data())
+ })
+ return query
+ })
const handle = makeHandle(result, destroy)
return {
...handle,
+ publications: published.values,
async setParam(next: P) {
param.set(next)
+ // The first paint after the change: the framework has flushed its
+ // reactive work, but no later task has run.
+ TestBed.tick()
+ published.record(result.data())
await settle()
},
}
@@ -231,6 +245,8 @@ function mountControllable
(
const angularDriver: LiveQueryDriver = {
name: `angular`,
+ // Reactive reads decide when the query compiles again.
+ comparesQueryIdentity: false,
disabledRepresentation: `empty-reactive`,
ops: { eq, gt, count, sum, coalesce, createOptimisticAction },
makeSource,
diff --git a/packages/db/src/collection/lifecycle.ts b/packages/db/src/collection/lifecycle.ts
index 3c3a6730bc..f8e513795a 100644
--- a/packages/db/src/collection/lifecycle.ts
+++ b/packages/db/src/collection/lifecycle.ts
@@ -31,6 +31,9 @@ import type { CollectionStateManager } from './state'
*/
export const UNSUBSCRIBED_GC_FLOOR_MS = 50
+/** A Collection's gcTime when its config names none (5 minutes). */
+export const DEFAULT_GC_TIME_MS = 300000
+
export class CollectionLifecycleManager<
TOutput extends object = Record,
TKey extends string | number = string | number,
@@ -303,7 +306,7 @@ export class CollectionLifecycleManager<
public startGCTimer(minDelay = 0): void {
if (!this.canGarbageCollect()) return
- const gcTime = this.config.gcTime ?? 300000 // 5 minutes default
+ const gcTime = this.config.gcTime ?? DEFAULT_GC_TIME_MS
// If gcTime is 0, negative, or non-finite (Infinity, -Infinity, NaN), GC is disabled.
// Note: setTimeout with Infinity coerces to 0 via ToInt32, causing immediate GC,
diff --git a/packages/db/src/errors.ts b/packages/db/src/errors.ts
index 7ced1918a7..221be72d63 100644
--- a/packages/db/src/errors.ts
+++ b/packages/db/src/errors.ts
@@ -1173,3 +1173,24 @@ export class UnhashableQueryIRError extends Error {
this.name = `UnhashableQueryIRError`
}
}
+
+/**
+ * Error thrown when a mounted framework binding that compares query identity
+ * reads a different source Collection under a Collection ID it has already
+ * read, in an earlier query or the same one. The identity names each source by
+ * its ID, so the binding could otherwise keep a live query that reads the old
+ * source.
+ */
+export class SourceCollectionIdReuseError extends TanStackDBError {
+ constructor(
+ public readonly bindingName: string,
+ public readonly collectionId: string,
+ ) {
+ super(
+ devBuild() && process.env.NODE_ENV !== `production`
+ ? `[${bindingName}] Collection ID "${collectionId}" named a different source Collection than one this live query already read. While the hook is mounted, each Collection ID must keep naming one source Collection. Unmount the hook and clean up its previous source and client scope before reusing the ID.`
+ : codedMessage(245, { bindingName, collectionId }),
+ )
+ this.name = `SourceCollectionIdReuseError`
+ }
+}
diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts
index 00e18d9dda..51a4976462 100644
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -14,13 +14,11 @@ export * from './types'
export * from './proxy'
export * from './query/index.js'
export * from './optimistic-action'
+export type { LiveQueryKey, LiveQueryOptions } from './live-query-options'
+/** @internal Unstable layer for the first-party framework adapters. */
export * from './live-query-adapter'
-export * from './live-query-observer'
/** @internal First-party persistence adapter capability. */
export * from './persisted-readiness'
-export * from './live-query-options'
-/** @internal Unstable adapter primitive for RFC #1623. */
-export * from './live-query-window-controller'
export * from './local-only'
export * from './local-storage'
export {
diff --git a/packages/db/src/live-query-adapter.ts b/packages/db/src/live-query-adapter.ts
index 6979829a25..9fffe4bbd2 100644
--- a/packages/db/src/live-query-adapter.ts
+++ b/packages/db/src/live-query-adapter.ts
@@ -1,81 +1,154 @@
-import type { Collection } from './collection/index.js'
-import type { CollectionStatus } from './types.js'
+import { SourceCollectionIdReuseError } from './errors.js'
+import { isCollection } from './live-query-primitives.js'
+import {
+ getPreparedLiveQueryIdentity,
+ getPreparedLiveQuerySources,
+} from './live-query-options.js'
+import type { DbClient } from './client.js'
+import type { LiveQueryKey } from './live-query-options.js'
/**
- * Shared helpers for the first-party framework adapters (`@tanstack/react-db`,
- * `@tanstack/vue-db`, `@tanstack/svelte-db`, `@tanstack/solid-db`,
- * `@tanstack/angular-db`).
+ * The adapter layer: what the first-party framework adapters
+ * (`@tanstack/react-db`, `@tanstack/preact-db`, `@tanstack/vue-db`,
+ * `@tanstack/svelte-db`, `@tanstack/solid-db`, `@tanstack/angular-db`) build
+ * their bindings from. It centralizes logic every adapter used to duplicate,
+ * so they stay consistent across frameworks.
*
- * These centralize small pieces of logic every adapter used to duplicate, so
- * they stay consistent across frameworks. They are intended for the official
- * adapters; treat them as unstable for external use.
+ * Application code should use an adapter instead. Everything exported here is
+ * unstable for external use and changes with the adapters that share it.
*/
+export * from './live-query-primitives.js'
+export * from './live-query-observer.js'
+export * from './live-query-window-binding.js'
+export {
+ getLiveQueryHash,
+ getPreparedLiveQueryIdentity,
+ getPreparedLiveQuerySources,
+ prepareLiveQueryValue,
+ rejectLiveQueryInput,
+ releaseDeferredOnReclaim,
+ resolveLiveQueryValue,
+ resumeDeferredLiveQueryCollections,
+} from './live-query-options.js'
+export type { DeferredLiveQueryCollections } from './live-query-options.js'
+export {
+ createLiveQueryWindowController,
+ fetchNextLiveQueryWindowPage,
+} from './live-query-window-controller.js'
+export type {
+ CreateLiveQueryWindowControllerOptions,
+ LiveQueryWindowController,
+ LiveQueryWindowSnapshot,
+} from './live-query-window-controller.js'
+
/**
- * Structural check for a live-query/`Collection` instance.
+ * The `queryKey` of a config-object query input, if it supplies one. An empty
+ * key is absent, as it is for `getLiveQueryHash`, so a hook and a `DbClient`
+ * preload agree on the query's identity.
+ */
+export function getLiveQueryKey(input: unknown): LiveQueryKey | undefined {
+ const queryKey =
+ input && typeof input === `object` && !isCollection(input)
+ ? (input as { queryKey?: unknown }).queryKey
+ : undefined
+ return Array.isArray(queryKey) && queryKey.length > 0 ? queryKey : undefined
+}
+
+/*
+ * Query identity and source Collection ID claims.
*
- * Uses duck typing rather than `instanceof CollectionImpl` on purpose: adapters
- * and core can resolve to different copies of `@tanstack/db` (dual-package /
- * multi-realm), where `instanceof` gives false negatives. The three methods
- * below uniquely identify a Collection.
+ * A binding that compares derived query identity decides from it whether to
+ * compile again: React and Preact compare it on every render, and a `DbClient`
+ * matches preloaded and hydrated queries by its hash. That identity names each
+ * source by its Collection ID. While such a binding is mounted, an ID must
+ * keep naming one source object in each client scope, or the binding could
+ * reuse a live query that reads the old source. A binding that compiles again
+ * whenever its reactive reads change compares no identity, so neither check
+ * applies to it.
*/
-export function isCollection(
- value: unknown,
-): value is Collection {
- return (
- typeof value === `object` &&
- value !== null &&
- typeof (value as any).subscribeChanges === `function` &&
- typeof (value as any).startSyncImmediate === `function` &&
- typeof (value as any).id === `string`
- )
+
+const sourceObjectTokens = new WeakMap()
+let nextSourceObjectToken = 0
+
+/** A process-unique number for a source object, without retaining it. */
+export function getSourceObjectToken(source: object): number {
+ let token = sourceObjectTokens.get(source)
+ if (token === undefined) {
+ token = ++nextSourceObjectToken
+ sourceObjectTokens.set(source, token)
+ }
+ return token
}
+// The client scope of a binding that reads no DbClient.
+const unscopedClaims = {}
+
/**
- * The Collection an adapter hands users as `collection`. A pooled live query
- * stands in for its live-query Collection and builds it only when touched.
+ * The source object each Collection ID named while one binding is mounted,
+ * per client scope.
*/
-export function getPublicCollection<
- T extends Collection | null | undefined,
->(collection: T): T {
- return (
- (collection as { publicCollection?: T } | null | undefined)
- ?.publicCollection ?? collection
- )
+export type LiveQuerySourceIdClaims = WeakMap>
+
+export function createLiveQuerySourceIdClaims(): LiveQuerySourceIdClaims {
+ return new WeakMap()
}
-/** Whether a collection yields a single result (`findOne`) rather than an array. */
-export function isSingleResultCollection(
- collection: Collection,
-): boolean {
- return (
- (collection.config as { singleResult?: boolean } | undefined)
- ?.singleResult === true
- )
+/** Record a query's sources, or throw before recording any. */
+export function claimLiveQuerySourceIds(
+ claims: LiveQuerySourceIdClaims,
+ sources: ReadonlyArray<{ id: string }>,
+ client: DbClient | undefined,
+ bindingName: string,
+): void {
+ const scope = client ?? unscopedClaims
+ const prior = claims.get(scope)
+ const seen = new Map()
+ for (const source of sources) {
+ const token = getSourceObjectToken(source)
+ const previous = seen.get(source.id) ?? prior?.get(source.id)
+ if (previous !== undefined && previous !== token) {
+ throw new SourceCollectionIdReuseError(bindingName, source.id)
+ }
+ seen.set(source.id, token)
+ }
+ const claimed = prior ?? new Map()
+ for (const [id, token] of seen) claimed.set(id, token)
+ claims.set(scope, claimed)
}
-/** The derived boolean status flags every adapter exposes for a query. */
-export interface LiveQueryStatusFlags {
- isLoading: boolean
- isReady: boolean
- isIdle: boolean
- isError: boolean
- isCleanedUp: boolean
+/** Where a binding that compares query identity checks a prepared query. */
+export interface LiveQueryIdentityScope {
+ /** This binding's source Collection ID claims. */
+ claims: LiveQuerySourceIdClaims
+ client: DbClient | undefined
+ bindingName: string
+ /** Report a descriptor source that no client bound. */
+ onUnboundDescriptor?: (alias: string) => never
}
/**
- * Derive the boolean status flags from a collection status. Adapters represent
- * a disabled query separately (with `isReady: true`); this covers the real
- * `CollectionStatus` values.
+ * Identify a prepared query for a binding that compares query identity. The
+ * identity throws `UnhashableQueryIRError` for IR without a stable identity,
+ * then the query's sources claim their Collection IDs. The binding's render
+ * boundary releases the sync starts a rejected render deferred; see
+ * `rejectLiveQueryInput`.
*/
-export function getLiveQueryStatusFlags(
- status: CollectionStatus,
-): LiveQueryStatusFlags {
- return {
- isLoading: status === `loading`,
- isReady: status === `ready`,
- isIdle: status === `idle`,
- isError: status === `error`,
- isCleanedUp: status === `cleaned-up`,
- }
+export function identifyLiveQuery(
+ preparedValue: unknown,
+ scope: LiveQueryIdentityScope,
+ identify: (
+ preparedValue: unknown,
+ ) => TIdentity = getPreparedLiveQueryIdentity as (
+ preparedValue: unknown,
+ ) => TIdentity,
+): TIdentity {
+ const identity = identify(preparedValue)
+ claimLiveQuerySourceIds(
+ scope.claims,
+ getPreparedLiveQuerySources(preparedValue, scope.onUnboundDescriptor),
+ scope.client,
+ scope.bindingName,
+ )
+ return identity
}
diff --git a/packages/db/src/live-query-observer.ts b/packages/db/src/live-query-observer.ts
index 3e8e15a6c8..c907d089ed 100644
--- a/packages/db/src/live-query-observer.ts
+++ b/packages/db/src/live-query-observer.ts
@@ -3,7 +3,7 @@ import {
getLiveQueryStatusFlags,
getPublicCollection,
isSingleResultCollection,
-} from './live-query-adapter.js'
+} from './live-query-primitives.js'
import { getBuilderFromConfig } from './query/live/collection-registry.js'
import { getPooledLiveQuerySource } from './query/pooled-live-query.js'
import { getPersistedReadinessSource } from './persisted-readiness.js'
diff --git a/packages/db/src/live-query-options.ts b/packages/db/src/live-query-options.ts
index 25abc0d25c..cbdc2dba58 100644
--- a/packages/db/src/live-query-options.ts
+++ b/packages/db/src/live-query-options.ts
@@ -1,6 +1,10 @@
import { BaseQueryBuilder } from './query/builder/index.js'
import { collectSourceRefs, requireCollectionSource } from './query/ir.js'
-import { isCollection } from './live-query-adapter.js'
+import { isCollection } from './live-query-primitives.js'
+import {
+ DEFAULT_GC_TIME_MS,
+ UNSUBSCRIBED_GC_FLOOR_MS,
+} from './collection/lifecycle.js'
import { createLiveQueryCollection } from './query/live-query-collection.js'
import {
createPooledLiveQuery,
@@ -32,6 +36,66 @@ export type DeferredLiveQueryCollections = Set<
CollectionImpl
>
+/**
+ * Release the sync starts a rejected query input deferred, then rethrow its
+ * rejection. A framework hook calls this around its own render work, so a
+ * query the hook rejects leaves no source deferred and a later reader can
+ * start it. A render that throws after the hook returns, such as in a sibling
+ * hook, is not a rejection of this input: like any render that never commits,
+ * it releases its deferral through `releaseDeferredOnReclaim` when garbage
+ * collection reclaims its live query. As for a
+ * `DbClient` preload, the rejection wins over a source whose resumed start
+ * fails; that source records its own failure.
+ */
+export function rejectLiveQueryInput(
+ collections: DeferredLiveQueryCollections | undefined,
+ rejection: unknown,
+): never {
+ try {
+ if (collections) resumeDeferredLiveQueryCollections(collections)
+ } catch {
+ // Report the rejection, not a later start failure.
+ }
+ throw rejection
+}
+
+/**
+ * Release a render's deferred sync starts when the live query it built is
+ * reclaimed. A render that commits releases them first, when it subscribes.
+ * A render that never commits, because a sibling threw or it suspended, leaves
+ * its live query unsubscribed until garbage collection cleans it up; that
+ * cleanup releases the starts, so a direct reader's demand, made before or
+ * after, then starts the sources. A live query that garbage collection never
+ * reclaims, because its config disables GC or does not start its sync,
+ * releases after the unsubscribed GC floor instead. Releases only the starts
+ * deferred so far, not ones a later render of the same hook defers. Pass only
+ * a live query the render built, and call the returned function when the
+ * render commits, so a committed hook keeps no listener, timer, or copied
+ * sources.
+ */
+export function releaseDeferredOnReclaim(
+ liveQuery: Pick, `once` | `config` | `status`>,
+ deferredCollections: DeferredLiveQueryCollections,
+): (() => void) | undefined {
+ if (deferredCollections.size === 0) return undefined
+ const pending: DeferredLiveQueryCollections = new Set(deferredCollections)
+ const release = () => {
+ try {
+ resumeDeferredLiveQueryCollections(pending)
+ } catch {
+ // A source whose resumed start fails records its own failure.
+ }
+ }
+ // The lifecycle's own rule: GC reclaims only a started collection with a
+ // finite, positive gcTime.
+ const gcTime = liveQuery.config.gcTime ?? DEFAULT_GC_TIME_MS
+ if (gcTime > 0 && Number.isFinite(gcTime) && liveQuery.status !== `idle`) {
+ return liveQuery.once(`status:cleaned-up`, release)
+ }
+ const timer = setTimeout(release, UNSUBSCRIBED_GC_FLOOR_MS)
+ return () => clearTimeout(timer)
+}
+
/** Release every deferred source, then report the first startup failure. */
export function resumeDeferredLiveQueryCollections(
collections: DeferredLiveQueryCollections,
@@ -203,12 +267,6 @@ export function getLiveQueryHash(
return getStableValueHash(identity, `queryKey`)
}
-/**
- * Resolve an adapter's query value to what its observer watches: `null` for a
- * disabled query, an existing Collection with sync started, or a live query.
- * A query builder whose shape a shared partition can serve gets a pooled view
- * instead of its own live-query Collection.
- */
// A config that names only its query and lifetime describes the same live
// query as its builder. Any other option shapes its Collection, so compiles.
function poolConfig(
@@ -226,6 +284,12 @@ function poolConfig(
})
}
+/**
+ * Resolve an adapter's query value to what its observer watches: `null` for a
+ * disabled query, an existing Collection with sync started, or a live query.
+ * A query builder whose shape a shared partition can serve gets a pooled view
+ * instead of its own live-query Collection.
+ */
export function resolveLiveQueryValue(
value: unknown,
{
diff --git a/packages/db/src/live-query-primitives.ts b/packages/db/src/live-query-primitives.ts
new file mode 100644
index 0000000000..a2436f9ac9
--- /dev/null
+++ b/packages/db/src/live-query-primitives.ts
@@ -0,0 +1,74 @@
+import type { Collection } from './collection/index.js'
+import type { CollectionStatus } from './types.js'
+
+// Collection guards and status flags. Core modules import them from here, and
+// the adapter layer (`live-query-adapter.ts`) re-exports them.
+
+/**
+ * Structural check for a live-query/`Collection` instance.
+ *
+ * Uses duck typing rather than `instanceof CollectionImpl` on purpose: adapters
+ * and core can resolve to different copies of `@tanstack/db` (dual-package /
+ * multi-realm), where `instanceof` gives false negatives. The three methods
+ * below uniquely identify a Collection.
+ */
+export function isCollection(
+ value: unknown,
+): value is Collection {
+ return (
+ typeof value === `object` &&
+ value !== null &&
+ typeof (value as any).subscribeChanges === `function` &&
+ typeof (value as any).startSyncImmediate === `function` &&
+ typeof (value as any).id === `string`
+ )
+}
+
+/**
+ * The Collection an adapter hands users as `collection`. A pooled live query
+ * stands in for its live-query Collection and builds it only when touched.
+ */
+export function getPublicCollection<
+ T extends Collection | null | undefined,
+>(collection: T): T {
+ return (
+ (collection as { publicCollection?: T } | null | undefined)
+ ?.publicCollection ?? collection
+ )
+}
+
+/** Whether a collection yields a single result (`findOne`) rather than an array. */
+export function isSingleResultCollection(
+ collection: Collection,
+): boolean {
+ return (
+ (collection.config as { singleResult?: boolean } | undefined)
+ ?.singleResult === true
+ )
+}
+
+/** The derived boolean status flags every adapter exposes for a query. */
+export interface LiveQueryStatusFlags {
+ isLoading: boolean
+ isReady: boolean
+ isIdle: boolean
+ isError: boolean
+ isCleanedUp: boolean
+}
+
+/**
+ * Derive the boolean status flags from a collection status. Adapters represent
+ * a disabled query separately (with `isReady: true`); this covers the real
+ * `CollectionStatus` values.
+ */
+export function getLiveQueryStatusFlags(
+ status: CollectionStatus,
+): LiveQueryStatusFlags {
+ return {
+ isLoading: status === `loading`,
+ isReady: status === `ready`,
+ isIdle: status === `idle`,
+ isError: status === `error`,
+ isCleanedUp: status === `cleaned-up`,
+ }
+}
diff --git a/packages/db/src/live-query-window-binding.ts b/packages/db/src/live-query-window-binding.ts
new file mode 100644
index 0000000000..8964dc3767
--- /dev/null
+++ b/packages/db/src/live-query-window-binding.ts
@@ -0,0 +1,278 @@
+import { codedMessage, devBuild } from './error-message.js'
+import { createLiveQueryCollection } from './query/live-query-collection.js'
+import {
+ assertLiveQueryWindowManyResult,
+ compareLiveQueryWindowDependencies,
+ createLiveQueryWindowController,
+ getLiveQueryWindowCollectionWarning,
+ getLiveQueryWindowInputKind,
+ liveQueryWindowMatches,
+ normalizeLiveQueryWindowPageSize,
+ resolveLiveQueryWindowInput,
+ shouldPreserveLiveQueryWindowPageCount,
+} from './live-query-window-controller.js'
+import type { Collection } from './collection/index.js'
+import type { LiveQueryWindowController } from './live-query-window-controller.js'
+
+/**
+ * Window binding: what one mounted infinite-query hook keeps between updates.
+ *
+ * Every framework adapter's `useLiveInfiniteQuery` reaches the same decision
+ * on each render or reactive rerun. It keeps the binding when nothing changed,
+ * replaces only the window controller when the page shape changed, or binds a
+ * new window collection when the input changed. A new controller keeps the
+ * loaded page count when the old pages still describe the new query.
+ * Adapters own only their framework's subscription and disposal of
+ * `controller`.
+ */
+
+// Live queries created here are cleaned up immediately (0 disables GC).
+const WINDOW_COLLECTION_GC_TIME_MS = 1
+
+/** Validated infinite-query page shape. */
+export interface LiveQueryWindowPageShape {
+ pageSize: number
+ /** First result-page label, not a server cursor or remote offset. */
+ initialPageParam: number
+}
+
+/**
+ * Read an infinite-query config's page shape. `getNextPageParam` is rejected:
+ * the hook widens an ordered live query and has no server cursor to advance.
+ */
+export function readLiveQueryWindowPageShape(config: {
+ pageSize?: number
+ initialPageParam?: number
+}): LiveQueryWindowPageShape {
+ if (`getNextPageParam` in config) {
+ throw new Error(
+ devBuild() && process.env.NODE_ENV !== `production`
+ ? `getNextPageParam is not supported by useLiveInfiniteQuery. Use an on-demand collection and fulfill meta.loadSubsetOptions in queryFn for server pagination.`
+ : codedMessage(246),
+ )
+ }
+ return {
+ pageSize: normalizeLiveQueryWindowPageSize(config.pageSize),
+ initialPageParam: config.initialPageParam ?? 0,
+ }
+}
+
+/**
+ * When a query input compiles again.
+ *
+ * - `identity`: when its identity dependencies change by structure, as for a
+ * derived query identity or a `queryKey`.
+ * - `dependencies`: when a dependency changes by reference, as for a
+ * dependency list.
+ * - `always`: on every update, as for a reactive rerun, which happens only
+ * when something the query reads changed.
+ */
+export type LiveQueryWindowRecompile = `identity` | `dependencies` | `always`
+
+export interface LiveQueryWindowUpdate extends LiveQueryWindowPageShape {
+ /**
+ * A supplied live-query Collection, or a callback that returns the query.
+ * The binding calls the callback only when it compiles a new window
+ * collection, except in `always` mode, where it calls it on every update.
+ */
+ input: unknown
+ /** The query input's identity dependencies. */
+ dependencies?: ReadonlyArray
+ /** Context compared by reference, such as the `DbClient` a query binds to. */
+ scope?: unknown
+ recompile: LiveQueryWindowRecompile
+}
+
+export interface LiveQueryWindowBinding extends LiveQueryWindowPageShape {
+ /** The supplied Collection; `undefined` for a query input. */
+ supplied: Collection | undefined
+ dependencies: ReadonlyArray | undefined
+ scope: unknown
+ collection: Collection
+ /** Whether this binding created `collection` from a query. */
+ ownsCollection: boolean
+ controller: LiveQueryWindowController
+ /**
+ * A developer hint about a newly bound supplied collection's window, for the
+ * adapter to print once. Production builds carry none.
+ */
+ warning: string | undefined
+}
+
+/**
+ * Bind an infinite-query update. Returns `previous` when it still serves the
+ * update; otherwise returns a new binding whose controller the adapter
+ * subscribes and later disposes.
+ *
+ * `uncommitted` is a binding built by an earlier update that never took
+ * effect, such as a React render that did not commit. When it answers this
+ * update, its window collection is reused instead of compiling another.
+ */
+export function bindLiveQueryWindow(
+ previous: LiveQueryWindowBinding | null,
+ update: LiveQueryWindowUpdate,
+ uncommitted?: LiveQueryWindowBinding | null,
+): LiveQueryWindowBinding {
+ // A reactive rerun resolves its input first: a getter may return a
+ // supplied Collection.
+ const resolved =
+ update.recompile === `always`
+ ? resolveLiveQueryWindowInput(update.input)
+ : undefined
+ const supplied =
+ resolved === undefined
+ ? getLiveQueryWindowInputKind(update.input) === `collection`
+ ? (update.input as Collection)
+ : undefined
+ : resolved.kind === `collection`
+ ? resolved.collection
+ : undefined
+ const inputKind = supplied ? `collection` : `query`
+ const previousKind = previous
+ ? previous.supplied
+ ? `collection`
+ : `query`
+ : undefined
+ // A snapshot: a caller may change its dependency array in place.
+ const dependencies = supplied ? undefined : [...(update.dependencies ?? [])]
+
+ const change = compareUpdate(previous, update, dependencies)
+ const needsNewCollection =
+ previous === null ||
+ previousKind !== inputKind ||
+ (supplied ? previous.supplied !== supplied : change.recompile)
+ const pageShapeChanged =
+ previous === null ||
+ previous.pageSize !== update.pageSize ||
+ previous.initialPageParam !== update.initialPageParam
+ if (!needsNewCollection && !pageShapeChanged) return previous
+
+ const initialPageCount = shouldPreserveLiveQueryWindowPageCount({
+ hasPreviousController: previous !== null,
+ previousInputKind: previousKind,
+ inputKind,
+ sameCollection: supplied !== undefined && previous?.supplied === supplied,
+ dependenciesChanged: change.dependenciesChanged,
+ dependenciesStructurallyEqual: change.dependenciesStructurallyEqual,
+ pageShapeChanged,
+ })
+ ? Math.max(1, previous!.controller.getSnapshot().pages.length)
+ : 1
+ // The peek-ahead window for every retained page.
+ const requiredLimit = initialPageCount * update.pageSize + 1
+
+ let collection = previous?.collection
+ let ownsCollection = previous?.ownsCollection ?? false
+ let warning: string | undefined
+ if (needsNewCollection) {
+ if (
+ !supplied &&
+ uncommitted?.ownsCollection &&
+ !compareUpdate(uncommitted, update, dependencies).recompile &&
+ uncommitted.collection.status !== `cleaned-up` &&
+ uncommitted.collection.status !== `error` &&
+ liveQueryWindowMatches(uncommitted.collection, requiredLimit)
+ ) {
+ // Nothing has taken effect since the earlier update built this
+ // collection, and its window is exactly the retained pages, so its first
+ // rows are correct. A collection in terminal error, such as after its
+ // source restarted, cannot serve the query again.
+ collection = uncommitted.collection
+ ownsCollection = true
+ } else {
+ const window = openWindowCollection(
+ resolved ?? resolveLiveQueryWindowInput(update.input),
+ update.pageSize,
+ requiredLimit,
+ )
+ collection = window.collection
+ ownsCollection = window.ownsCollection
+ warning = window.warning
+ }
+ }
+
+ return {
+ supplied,
+ dependencies,
+ scope: update.scope,
+ pageSize: update.pageSize,
+ initialPageParam: update.initialPageParam,
+ collection: collection!,
+ ownsCollection,
+ controller: createLiveQueryWindowController(collection, {
+ pageSize: update.pageSize,
+ initialPageParam: update.initialPageParam,
+ initialPageCount,
+ }),
+ warning,
+ }
+}
+
+/** How an update's query identity differs from a binding's. */
+function compareUpdate(
+ binding: LiveQueryWindowBinding | null,
+ update: LiveQueryWindowUpdate,
+ dependencies: ReadonlyArray | undefined,
+): {
+ recompile: boolean
+ dependenciesChanged: boolean
+ dependenciesStructurallyEqual: boolean
+} {
+ const comparison = compareLiveQueryWindowDependencies(
+ binding?.dependencies,
+ dependencies ?? [],
+ )
+ const scopeChanged = binding?.scope !== update.scope
+ const dependenciesChanged =
+ scopeChanged ||
+ (update.recompile === `identity`
+ ? !comparison.structurallyEqual
+ : comparison.changed)
+ return {
+ recompile: update.recompile === `always` || dependenciesChanged,
+ dependenciesChanged,
+ // An identity that changed differs by structure by definition.
+ dependenciesStructurallyEqual:
+ !scopeChanged &&
+ update.recompile !== `identity` &&
+ comparison.structurallyEqual,
+ }
+}
+
+/**
+ * Bind the window collection for a resolved input, starting its sync now when
+ * its first published rows are already correct. A created collection's window
+ * covers every retained page, so it never publishes fewer rows than the
+ * controller's pages; the controller grows it with `setWindow`. A supplied
+ * window that the controller must still adjust waits for the subscription.
+ */
+function openWindowCollection(
+ input: ReturnType>,
+ pageSize: number,
+ requiredLimit: number,
+): {
+ collection: Collection
+ ownsCollection: boolean
+ warning: string | undefined
+} {
+ if (input.kind === `collection`) {
+ const warning = getLiveQueryWindowCollectionWarning(
+ input.collection,
+ pageSize + 1,
+ )
+ if (liveQueryWindowMatches(input.collection, requiredLimit)) {
+ input.collection.startSyncImmediate()
+ }
+ return { collection: input.collection, ownsCollection: false, warning }
+ }
+ const collection = createLiveQueryCollection({
+ query: input.query.limit(requiredLimit).offset(0),
+ gcTime: WINDOW_COLLECTION_GC_TIME_MS,
+ })
+ assertLiveQueryWindowManyResult(collection)
+ // Like useLiveQuery, start sync during render once the query is valid. A
+ // render reads only rows the sources already hold, and sends no request
+ // until the subscription attaches.
+ collection.startSyncImmediate()
+ return { collection, ownsCollection: true, warning: undefined }
+}
diff --git a/packages/db/src/live-query-window-controller.ts b/packages/db/src/live-query-window-controller.ts
index 98b5a191cc..ee804a739b 100644
--- a/packages/db/src/live-query-window-controller.ts
+++ b/packages/db/src/live-query-window-controller.ts
@@ -6,7 +6,7 @@ import {
getLiveQueryStatusFlags,
isCollection,
isSingleResultCollection,
-} from './live-query-adapter.js'
+} from './live-query-primitives.js'
import { createLiveQueryObserver } from './live-query-observer.js'
import { BaseQueryBuilder } from './query/builder/index.js'
import { deepEquals } from './utils.js'
diff --git a/packages/db/tests/conformance/contract.ts b/packages/db/tests/conformance/contract.ts
index 92075b4187..976ebf5a6d 100644
--- a/packages/db/tests/conformance/contract.ts
+++ b/packages/db/tests/conformance/contract.ts
@@ -6,7 +6,7 @@
* errors, enablement, recompilation, and teardown. Each adapter owns only the
* bridge from its native scheduler into the small `LiveQueryDriver` language.
* Running one shared scenario through every bridge separates engine semantics
- * from React, Vue, Solid, Angular, and Svelte timing.
+ * from React, Preact, Vue, Solid, Angular, and Svelte timing.
*
* Realm safety: the driver — not the scenarios — creates source collections and
* supplies query operators, both imported from the *adapter's* copy of
@@ -19,6 +19,48 @@
* visible after the driver's documented flush cut. Result helpers read raw
* fields and selected rows; they do not repair malformed adapter output.
*
+ * Query identity (1.0 law, maintainer decisions 2026-10-22 and 2026-10-23).
+ * The law depends on how a binding decides to compile again.
+ *
+ * A binding that compares query identity re-runs its query input and compiles
+ * again only when the input's identity changed. React and Preact compare it
+ * on every render. Such a binding compiles an input that has no `queryKey`
+ * only when the query IR has a stable identity; otherwise it throws
+ * `UnhashableQueryIRError`. The identity names each source by its Collection
+ * ID, so while the binding is mounted each claimed ID keeps naming one source
+ * object: a different object under a claimed ID, in a later query or in the
+ * same one, throws
+ * `SourceCollectionIdReuseError` before any row from either source is
+ * returned. Revisiting the same object is legal, and a new binding starts with
+ * no claims. An input with a nonempty `queryKey` owns its identity and skips
+ * both checks: a keyed step records no claim and checks none, so a claim
+ * made before it still binds a later derived step (maintainer decision
+ * 2026-10-23). An empty key is absent, as it is for a `DbClient` preload.
+ *
+ * A binding that compiles again whenever its reactive reads change (Vue,
+ * Solid, Angular, and Svelte without a `DbClient`) compares no identity. It
+ * compiles any query input, including one without a stable IR identity, and
+ * its rows follow the current input: after a source swap under the same
+ * Collection ID, every value it publishes holds only the new source's rows
+ * (or none while it loads) and never the old ones,
+ * and one query over two same-ID objects reads each of them.
+ * A `DbClient` matches queries by identity hash, so a binding backed by one
+ * follows the comparing law; that boundary has its own receiving witnesses.
+ *
+ * Rejection is observed at the adapter's native compile point. The driver
+ * surfaces it as a throw from `mount*`, a rejected `setParam`, or a throw from
+ * the next `current()` read. After a rejection, no later read exposes rows:
+ * each `current()` throws or holds none, so a framework whose memo throws once
+ * cannot fall back to the previous query's rows. Each driver releases any
+ * native scope that a rejected mount acquired. In the current drivers this
+ * check cannot fail, and reactive drivers do not reject here. React unmounts
+ * a tree whose render throws, so its driver rethrows on later reads. Preact
+ * keeps a component whose render throws mounted, so its driver mounts the hook
+ * under an error boundary, as an application must to recover, and rethrows on
+ * later reads. A Preact component without a boundary is outside this cut. It guards a future driver whose binding stays mounted. The one such
+ * binding today, a `DbClient`-backed Svelte query, has its own witness in the
+ * Svelte descriptor release oracle, which reads each field after a rejection.
+ *
* All current scenarios must pass. A future known bug needs an independently
* approved exact failure signature; a whole-test waiver could hide another bug.
*/
@@ -140,7 +182,18 @@ export interface LiveQueryHandle {
* new value and settles.
*/
export interface ControllableHandle extends LiveQueryHandle {
+ /** Rejects when the adapter rejects the reconfigured query input. */
setParam: (param: P) => Promise
+ /**
+ * The `data` value the binding left published at the end of each
+ * synchronous turn since mount, in order. Drivers record at their
+ * framework's publication points (React and Preact commits, Vue pre-flushes,
+ * Svelte pre-effects, Solid render effects, Angular effects) through
+ * `publication-log.ts`, which keeps the last value of each turn: a value
+ * replaced within one turn is never painted. A law about what a swap may
+ * show reads these, not only the value after `setParam` settles.
+ */
+ publications: () => ReadonlyArray
}
/**
@@ -160,9 +213,13 @@ export interface LiveQueryDriver {
disabledRepresentation: `absent` | `empty-reactive`
/** Operators from the adapter's `@tanstack/db` realm. */
ops: DbOps
- /** Create a realm-correct source collection + mutators, keyed by `id`. */
+ /**
+ * Create a realm-correct source collection + mutators, keyed by `id`. Pass
+ * `collectionId` to create another source object under an existing ID.
+ */
makeSource: (
initialData: ReadonlyArray,
+ collectionId?: string,
) => SourceHandle
/** Create a source that starts `loading` and readies on demand (keyed by `id`). */
makeDeferredSource: () => DeferredSourceHandle
@@ -192,15 +249,34 @@ export interface LiveQueryDriver {
build: (q: any, param: P) => any,
initial: P,
) => ControllableHandle
+ /**
+ * Mount a controllable query in the config-object form whose `queryKey` is
+ * `key(param)`, or none when that returns `undefined`. Every driver that
+ * compares query identity supplies it; a reactive binding has no keys.
+ */
+ mountKeyedControllable?:
(
+ build: (q: any, param: P) => any,
+ key: (param: P) => ReadonlyArray | undefined,
+ initial: P,
+ ) => ControllableHandle
/** Mount a pre-created collection passed directly to the hook. */
mountCollection: (collection: Collection) => LiveQueryHandle
/** Mount via the config-object input form (`{ query: build }`). */
mountConfig: (
build: QueryBuild,
- opts?: { gcTime?: number },
+ opts?: { gcTime?: number; queryKey?: ReadonlyArray },
) => LiveQueryHandle
/** Mount an explicitly-disabled query (adapter's own null/undefined form). */
mountDisabled: () => LiveQueryHandle
+ /**
+ * Whether the binding compares query identity to decide when to compile
+ * again (see the opening query-identity law). The driver declares the
+ * adapter's documented policy for the inputs it mounts; the suite does not
+ * infer it from observed output. Svelte compares identity only for a query
+ * that a `DbClient` backs, and its shared drivers mount none, so they
+ * declare `false`.
+ */
+ comparesQueryIdentity: boolean
/** No active waivers. Kept empty in drivers to make this boundary explicit. */
knownGaps?: ReadonlyArray
/**
diff --git a/packages/db/tests/conformance/infinite-contract.ts b/packages/db/tests/conformance/infinite-contract.ts
index aa8a1f37fc..01c0d4d78e 100644
--- a/packages/db/tests/conformance/infinite-contract.ts
+++ b/packages/db/tests/conformance/infinite-contract.ts
@@ -30,6 +30,13 @@
* framework's own publication cut. Pre-commit work, such as a React render that
* never commits, belongs to the drivers: Vue's setup is its commit, so that cut
* has no shared form.
+ *
+ * The query-identity laws in `contract.ts` apply to infinite bindings too. A
+ * binding that compares query identity needs `queryKey` for an unhashable
+ * query and rejects a different source object under a Collection ID it
+ * already read; rejection surfaces as a throw from the mount, `setParamSync`,
+ * the next `flush`, or `current()`. A reactive binding compiles either input
+ * and publishes the current source's pages.
*/
import type { Collection, LiveQueryWindowController } from '@tanstack/db'
import type { QueryBuild, SourceHandle } from './contract'
@@ -37,6 +44,8 @@ import type { QueryBuild, SourceHandle } from './contract'
export interface InfiniteQueryConfig {
pageSize?: number
initialPageParam?: number
+ /** Explicit identity for a query whose IR has no stable hash. */
+ queryKey?: ReadonlyArray
}
export interface InfiniteQueryResult {
@@ -99,9 +108,14 @@ export interface InfiniteQueryInputHandle extends InfiniteQueryHandle {
export interface InfiniteQueryDriver {
name: string
+ /** Whether the binding compares query identity; see `contract.ts`. */
+ comparesQueryIdentity: boolean
gt: (a: any, b: any) => any
+ eq: (a: any, b: any) => any
+ /** Pass `collectionId` to create another source object under an existing ID. */
makeSource: (
initialData: ReadonlyArray,
+ collectionId?: string,
) => SourceHandle
makeOnDemandSource: (
data: ReadonlyArray,
@@ -138,6 +152,17 @@ export interface InfiniteQueryDriver {
initial: P,
config?: InfiniteQueryConfig,
) => InfiniteQueryControllableHandle
+ /**
+ * Mount a controllable query whose config names `key(param)` as its
+ * `queryKey`, or none when that returns `undefined`. Every driver that
+ * compares query identity supplies it; a reactive binding has no keys.
+ */
+ mountKeyedControllable?:
(
+ build: (q: any, param: P) => any,
+ key: (param: P) => ReadonlyArray | undefined,
+ initial: P,
+ config?: InfiniteQueryConfig,
+ ) => InfiniteQueryControllableHandle
mountCollection: (
collection: Collection,
config?: InfiniteQueryConfig,
diff --git a/packages/db/tests/conformance/infinite-suite-oracle.ts b/packages/db/tests/conformance/infinite-suite-oracle.ts
index 0cb95e8f33..260aa85724 100644
--- a/packages/db/tests/conformance/infinite-suite-oracle.ts
+++ b/packages/db/tests/conformance/infinite-suite-oracle.ts
@@ -16,6 +16,7 @@
* history instead of test-runner housekeeping.
*/
import { describe, expect, it, vi } from 'vitest'
+import { createOracleReach } from '../oracle-reach'
import { expectPageRows } from './page-laws-oracle'
import { ScenarioLifetime } from './scenario-lifetime'
import { ScenarioSources } from './scenario-sources'
@@ -24,6 +25,7 @@ import type {
InfiniteQueryDriver,
InfiniteQueryHandle,
} from './infinite-contract'
+import type { QueryBuild } from './contract'
interface InfiniteRow {
id: string
@@ -146,6 +148,36 @@ async function captureError(fn: () => InfiniteQueryHandle): Promise {
}
}
+/** A rejected input throws at mount, reconfiguration, flush, or read. */
+async function captureRejection(
+ run: () => Promise | unknown,
+): Promise {
+ try {
+ await run()
+ return undefined
+ } catch (error) {
+ return error
+ }
+}
+
+/**
+ * After a rejection, every read throws or holds no rows. Two reads catch a
+ * memo that throws once and then serves its previous value. No current driver
+ * can fail this check (see `contract.ts`); it guards a driver whose binding
+ * stays mounted after a rejection.
+ */
+function expectNoPagesAfterRejection(handle: InfiniteQueryHandle): void {
+ for (let read = 0; read < 2; read++) {
+ let data: unknown
+ try {
+ data = handle.current().data
+ } catch {
+ continue
+ }
+ expect(data).toEqual([])
+ }
+}
+
async function waitFor(check: () => boolean): Promise {
for (let attempt = 0; attempt < 20; attempt++) {
if (check()) return
@@ -179,7 +211,8 @@ export function runInfiniteQuerySuite(rawDriver: InfiniteQueryDriver): void {
}
const driver: InfiniteQueryDriver = {
...rawDriver,
- makeSource: (data) => sources!.track(rawDriver.makeSource(data)),
+ makeSource: (data, collectionId) =>
+ sources!.track(rawDriver.makeSource(data, collectionId)),
makeOnDemandSource: (data, delay) =>
sources!.track(rawDriver.makeOnDemandSource(data, delay)),
makeLaggingOnDemandSource: (data) =>
@@ -202,6 +235,8 @@ export function runInfiniteQuerySuite(rawDriver: InfiniteQueryDriver): void {
key: string,
name: string,
fn: () => Promise | void,
+ // A generated grammar runs many histories, each through the driver's cut.
+ timeoutMs?: number,
) => {
registry.register(key)
const label = `[${key}] ${name}`
@@ -223,7 +258,7 @@ export function runInfiniteQuerySuite(rawDriver: InfiniteQueryDriver): void {
sources = null
}
}
- it(label, run)
+ it(label, run, timeoutMs)
}
describe(`infinite-query conformance :: ${driver.name}`, () => {
@@ -1655,8 +1690,359 @@ export function runInfiniteQuerySuite(rawDriver: InfiniteQueryDriver): void {
},
)
+ // ---- query identity (1.0 law; see contract.ts) ----------------------
+ //
+ // Each history branches only on the driver's public identity policy, and
+ // both branches check pages: a comparing binding rejects, and a reactive
+ // binding pages the current input.
+
+ // `fn.where` runs a JavaScript predicate, so its IR has no stable hash.
+ const functionalRanks = (source: { collection: any }) => (q: any) =>
+ q
+ .from({ items: source.collection })
+ .fn.where(({ items }: any) => items.rank > 4)
+ .orderBy(({ items }: any) => items.rank, `desc`)
+
+ scenario(
+ `unhashable-query`,
+ `pages a query without a stable IR identity, needing queryKey only where the binding compares identity`,
+ async () => {
+ const source = driver.makeSource(rows(8))
+ if (driver.comparesQueryIdentity) {
+ // An empty key is absent, as it is for a DbClient preload.
+ for (const config of [
+ { pageSize: 3 },
+ { pageSize: 3, queryKey: [] },
+ ]) {
+ const error = await captureError(() =>
+ driver.mount(functionalRanks(source), config),
+ )
+ expect(error).toMatchObject({ name: `UnhashableQueryIRError` })
+ }
+ }
+ const handle = driver.mount(
+ functionalRanks(source),
+ driver.comparesQueryIdentity
+ ? { pageSize: 3, queryKey: [`ranks-above`, 4] }
+ : { pageSize: 3 },
+ )
+ await handle.flush()
+ await handle.fetchNextPage()
+ await handle.flush()
+ expectPageRows(handle.current(), rows(8).slice(0, 4), 3)
+ expect(handle.current().hasNextPage).toBe(false)
+ },
+ )
+
+ scenario(
+ `source-id-reuse`,
+ `rejects or pages a different source under a Collection ID the binding read`,
+ async () => {
+ // Claim memory grammar, as in the live suite without a disabled step:
+ // a history mounts on A(x) or C(y), then takes two steps over A(x),
+ // B(x) (another object under A's ID), and C(y). The pairwise model
+ // judges each step from the history alone. A comparing binding rejects
+ // a step when an earlier step read another object under its ID, which
+ // ends the history; a reactive binding pages the selected source.
+ type Pick = `A` | `B` | `C`
+ const first = driver.makeSource(rows(4))
+ const sourceOf: Record = {
+ A: first,
+ B: driver.makeSource(rows(3, `r`), first.collection.id),
+ C: driver.makeSource(rows(2, `o`)),
+ }
+ const pagesOf: Record> = {
+ A: rows(4).slice(0, 3),
+ B: rows(3, `r`),
+ C: rows(2, `o`),
+ }
+ const collides = (history: ReadonlyArray, next: Pick) =>
+ history.some(
+ (prior) =>
+ prior !== next &&
+ sourceOf[prior].collection.id === sourceOf[next].collection.id,
+ )
+ type ReachState =
+ | `swap after an intervening query`
+ | `revisit after an intervening query`
+ // A state names what lies between the step that made a claim and the
+ // step that tests it.
+ const reachedState = (
+ history: ReadonlyArray,
+ next: Pick,
+ ): ReachState | undefined => {
+ const lastIndex = (match: (pick: Pick) => boolean) => {
+ for (let index = history.length - 1; index >= 0; index--) {
+ if (match(history[index]!)) return index
+ }
+ return -1
+ }
+ const conflict = lastIndex(
+ (prior) =>
+ prior !== next &&
+ sourceOf[prior].collection.id === sourceOf[next].collection.id,
+ )
+ if (conflict >= 0) {
+ return history.length - conflict > 1
+ ? `swap after an intervening query`
+ : undefined
+ }
+ const revisit = lastIndex((prior) => prior === next)
+ return revisit >= 0 && history.length - revisit > 1
+ ? `revisit after an intervening query`
+ : undefined
+ }
+ // Declared reach: the states where a claim must outlive the query
+ // that made it.
+ const reach = createOracleReach(
+ `infinite source-id claim memory`,
+ [
+ `swap after an intervening query`,
+ `revisit after an intervening query`,
+ ],
+ )
+ const picks: ReadonlyArray = [`A`, `B`, `C`]
+ for (const start of [`A`, `C`] as const) {
+ for (const second of picks) {
+ for (const third of picks) {
+ reach.beginHistory()
+ const history: Array = [start]
+ const handle = driver.mountControllable(
+ (q, pick: Pick) =>
+ q
+ .from({ items: sourceOf[pick].collection })
+ .orderBy(({ items }: any) => items.rank, `desc`),
+ start as Pick,
+ { pageSize: 3 },
+ )
+ await handle.flush()
+ expectPageRows(handle.current(), pagesOf[start], 3)
+ for (const next of [second, third]) {
+ const state = reachedState(history, next)
+ if (state) reach.reach(state)
+ if (driver.comparesQueryIdentity && collides(history, next)) {
+ const error = await captureRejection(async () => {
+ handle.setParamSync(next)
+ await handle.flush()
+ return handle.current()
+ })
+ expect(error).toMatchObject({
+ name: `SourceCollectionIdReuseError`,
+ })
+ expectNoPagesAfterRejection(handle)
+ break
+ }
+ const observed = handle.observations().length
+ handle.setParamSync(next)
+ if (collides(history, next)) {
+ // A reactive binding read the swap as a new source. At the
+ // first paint, after the framework's microtask flush and
+ // before any later task, it shows only the new source's
+ // rows or none; so does every value it publishes after.
+ await Promise.resolve()
+ await Promise.resolve()
+ const allowed = new Set(pagesOf[next].map((row) => row.id))
+ const firstPaint = handle
+ .current()
+ .data.map((row: { id: string }) => row.id)
+ expect(
+ firstPaint.filter((id: string) => !allowed.has(id)),
+ `first paint ${JSON.stringify(firstPaint)}`,
+ ).toEqual([])
+ await handle.flush()
+ for (const observation of handle
+ .observations()
+ .slice(observed)) {
+ expect(
+ observation.ids.filter((id) => !allowed.has(id)),
+ `published ${JSON.stringify(observation.ids)}`,
+ ).toEqual([])
+ }
+ } else {
+ await handle.flush()
+ }
+ history.push(next)
+ expectPageRows(handle.current(), pagesOf[next], 3)
+ }
+ handle.unmount()
+ }
+ }
+ }
+ reach.assertReached()
+
+ if (!driver.comparesQueryIdentity) return
+ // Keyed dimension (comparing bindings only), as in the live suite:
+ // AK reads A(x) and BK reads B(x) under their own keys. A keyed step
+ // records no claim and checks none, so a claim made before it still
+ // binds a later derived step.
+ type KeyedPick = Pick | `AK` | `BK`
+ const base = (pick: KeyedPick): Pick =>
+ pick === `AK` ? `A` : pick === `BK` ? `B` : pick
+ const isKeyed = (pick: KeyedPick) => pick !== base(pick)
+ const conflicts = (prior: KeyedPick, next: KeyedPick) =>
+ !isKeyed(prior) &&
+ !isKeyed(next) &&
+ base(prior) !== base(next) &&
+ sourceOf[base(prior)].collection.id ===
+ sourceOf[base(next)].collection.id
+ type KeyedReachState =
+ `claim crosses a keyed step` | `keyed step after a claim`
+ const keyedReach = createOracleReach(
+ `infinite source-id claim memory with keys`,
+ [`claim crosses a keyed step`, `keyed step after a claim`],
+ )
+ const mountKeyed = driver.mountKeyedControllable
+ // Every comparing driver supplies the keyed form.
+ expect(mountKeyed).toBeDefined()
+ const keyedPicks: ReadonlyArray = [`A`, `B`, `C`, `AK`, `BK`]
+ for (const start of [`A`, `C`, `AK`] as const) {
+ for (const second of keyedPicks) {
+ for (const third of keyedPicks) {
+ keyedReach.beginHistory()
+ const history: Array = [start]
+ const handle = mountKeyed!(
+ (q, pick: KeyedPick) =>
+ q
+ .from({ items: sourceOf[base(pick)].collection })
+ .orderBy(({ items }: any) => items.rank, `desc`),
+ (pick) => (isKeyed(pick) ? [`keyed`, pick] : undefined),
+ start as KeyedPick,
+ { pageSize: 3 },
+ )
+ await handle.flush()
+ expectPageRows(handle.current(), pagesOf[base(start)], 3)
+ for (const next of [second, third]) {
+ let claimIndex = -1
+ for (let index = history.length - 1; index >= 0; index--) {
+ if (conflicts(history[index]!, next)) {
+ claimIndex = index
+ break
+ }
+ }
+ if (
+ claimIndex >= 0 &&
+ history.slice(claimIndex + 1).some(isKeyed)
+ ) {
+ keyedReach.reach(`claim crosses a keyed step`)
+ }
+ if (
+ isKeyed(next) &&
+ history.some(
+ (prior) =>
+ !isKeyed(prior) &&
+ base(prior) !== base(next) &&
+ sourceOf[base(prior)].collection.id ===
+ sourceOf[base(next)].collection.id,
+ )
+ ) {
+ keyedReach.reach(`keyed step after a claim`)
+ }
+ if (claimIndex >= 0) {
+ const error = await captureRejection(async () => {
+ handle.setParamSync(next)
+ await handle.flush()
+ return handle.current()
+ })
+ expect(error).toMatchObject({
+ name: `SourceCollectionIdReuseError`,
+ })
+ expectNoPagesAfterRejection(handle)
+ break
+ }
+ handle.setParamSync(next)
+ await handle.flush()
+ history.push(next)
+ expectPageRows(handle.current(), pagesOf[base(next)], 3)
+ }
+ handle.unmount()
+ }
+ }
+ }
+ keyedReach.assertReached()
+ },
+ // 18 histories of three steps each, and 75 keyed histories for a
+ // comparing binding.
+ 60_000,
+ )
+
+ scenario(
+ `unhashable-recompile`,
+ `recompiling to a query without a stable IR identity follows the binding's identity policy`,
+ async () => {
+ const source = driver.makeSource(rows(8))
+ // `null` selects the structured query; a number, the functional one
+ // that keeps ranks at or below it.
+ const handle = driver.mountControllable(
+ (q, atMost: number | null) => {
+ const query = q
+ .from({ items: source.collection })
+ .orderBy(({ items }: any) => items.rank, `desc`)
+ return atMost === null
+ ? query
+ : query.fn.where(({ items }: any) => items.rank <= atMost)
+ },
+ null as number | null,
+ { pageSize: 3 },
+ )
+ await handle.flush()
+ expectPageRows(handle.current(), rows(8).slice(0, 3), 3)
+ if (driver.comparesQueryIdentity) {
+ const error = await captureRejection(async () => {
+ handle.setParamSync(4)
+ await handle.flush()
+ return handle.current()
+ })
+ expect(error).toMatchObject({ name: `UnhashableQueryIRError` })
+ expectNoPagesAfterRejection(handle)
+ return
+ }
+ // A changed captured value recompiles, though no identity names it.
+ handle.setParamSync(4)
+ await handle.flush()
+ expectPageRows(handle.current(), rows(8).slice(4, 7), 3)
+ handle.setParamSync(2)
+ await handle.flush()
+ expectPageRows(handle.current(), rows(8).slice(6, 8), 3)
+ },
+ )
+
+ scenario(
+ `source-id-reuse-in-one-query`,
+ `rejects or pages one query that reads two sources under one Collection ID`,
+ async () => {
+ // Overlapping but different rows: ids 1-4 and 3-6.
+ const first = driver.makeSource(rows(4))
+ const reused = driver.makeSource(rows(6).slice(2), first.collection.id)
+ const build: QueryBuild = (q) =>
+ q
+ .from({ items: first.collection })
+ .join(
+ { other: reused.collection },
+ ({ items, other }: any) => driver.eq(items.id, other.id),
+ `inner`,
+ )
+ .orderBy(({ items }: any) => items.rank, `desc`)
+ .select(({ items }: any) => ({ ...items }))
+ if (driver.comparesQueryIdentity) {
+ const error = await captureError(() =>
+ driver.mount(build, { pageSize: 3 }),
+ )
+ expect(error).toMatchObject({ name: `SourceCollectionIdReuseError` })
+ return
+ }
+ // The inner join matches only ids both objects hold: 3 and 4.
+ // Reading the first object for both sides pages 1-3; the second, 3-5.
+ const handle = driver.mount(build, { pageSize: 3 })
+ await handle.flush()
+ expect(handle.current().data.map((row: any) => row.id)).toEqual([
+ `3`,
+ `4`,
+ ])
+ },
+ )
+
it(`registers every distinct scenario without whole-test waivers`, () => {
- expect(registry.size).toBe(39)
+ expect(registry.size).toBe(43)
})
})
}
diff --git a/packages/db/tests/conformance/publication-log.ts b/packages/db/tests/conformance/publication-log.ts
new file mode 100644
index 0000000000..94fb31b9d2
--- /dev/null
+++ b/packages/db/tests/conformance/publication-log.ts
@@ -0,0 +1,31 @@
+/**
+ * Records what a framework binding leaves published at the end of each
+ * synchronous turn. A binding may publish several values while one flush
+ * runs, such as a Solid render effect or a Svelte pre-effect that reads the
+ * previous query's rows before the binding's own effect replaces them. A
+ * browser paints only between tasks, so a value replaced within one turn is
+ * never seen. The microtask boundary is a stricter cut than the next paint:
+ * a value still published when the turn ends counts, even if a later task
+ * replaces it before the browser paints.
+ */
+export function createPublicationLog() {
+ const turns: Array = []
+ let turnOpen = false
+ return {
+ /** Record a published value, replacing an earlier one from this turn. */
+ record(value: unknown): void {
+ const copy = Array.isArray(value) ? [...value] : value
+ if (turnOpen) {
+ turns[turns.length - 1] = copy
+ return
+ }
+ turns.push(copy)
+ turnOpen = true
+ queueMicrotask(() => {
+ turnOpen = false
+ })
+ },
+ /** The value published at the end of each turn, in order. */
+ values: (): ReadonlyArray => turns,
+ }
+}
diff --git a/packages/db/tests/conformance/suite.ts b/packages/db/tests/conformance/suite.ts
index 6882c980ee..8648a67732 100644
--- a/packages/db/tests/conformance/suite.ts
+++ b/packages/db/tests/conformance/suite.ts
@@ -35,9 +35,25 @@
* cardinality, disabled + transitions, deferred readiness / eager / ready-with-
* no-data, initial readiness over a lagging on-demand source, param recompilation, optimistic mutation, pre-created & config-object
* inputs, error status, and order-only moves.
+ *
+ * The query-identity scenarios (see `contract.ts`) run each history through
+ * both identity policies. A comparing binding rejects an unhashable query
+ * without `queryKey` (an empty key counts as none) at mount and at
+ * recompilation and accepts it with a key;
+ * a reactive binding runs it and recompiles when a captured value changes.
+ * The source-ID grammar enumerates every three-step history over A(x), B(x)
+ * (another object under A's ID), C(y), and a disabled step, judged by a
+ * pairwise model. It distinguishes a remembered claim from a check against
+ * only the previous query: A(x) -> C(y) -> B(x) and A(x) -> disabled -> B(x)
+ * reject in a comparing binding and read B in a reactive one, while
+ * A(x) -> C(y) -> A(x) is legal everywhere. It declares reach for each of
+ * those states.
+ * A new binding reads B after the first unmounts. Two same-ID objects in one
+ * query follow the same split: rejected, or each read.
*/
import { describe, expect, it } from 'vitest'
import { waitForPersistedInitialRender } from '@tanstack/db'
+import { createOracleReach } from '../oracle-reach'
import { ScenarioLifetime } from './scenario-lifetime'
import { ScenarioSources } from './scenario-sources'
import { scenarioRegistry } from './registration'
@@ -73,6 +89,60 @@ async function expectRetired(collection: ConformanceCollection): Promise {
.toBe(`cleaned-up`)
}
+/**
+ * A rejected query input throws at the adapter's compile point: from the
+ * mount or reconfiguration, or from the next result read.
+ */
+async function expectRejection(
+ name: string,
+ run: () => Promise | unknown,
+): Promise {
+ let rejection: unknown
+ try {
+ await run()
+ } catch (error) {
+ rejection = error
+ }
+ expect(rejection, `expected ${name}`).toMatchObject({ name })
+}
+
+/**
+ * After a rejection, every read throws or holds no rows. Two reads catch a
+ * memo that throws once and then serves its previous value. No current driver
+ * can fail this check (see `contract.ts`); it guards a driver whose binding
+ * stays mounted after a rejection.
+ */
+function expectNoRowsAfterRejection(h: LiveQueryHandle): void {
+ for (let read = 0; read < 2; read++) {
+ let result: ReturnType
+ try {
+ result = h.current()
+ } catch {
+ continue
+ }
+ const { data, state } = result
+ expect(
+ Array.isArray(data) ? data : data === undefined ? [] : [data],
+ ).toEqual([])
+ expect(state?.size ?? 0).toBe(0)
+ }
+}
+
+/** A published `data` value holds no row outside `rows`. */
+function expectOnlyRowsOf(
+ value: unknown,
+ rows: ReadonlyArray<{ id: string }>,
+): void {
+ const allowed = new Set(rows.map(({ id }) => id))
+ const published = (Array.isArray(value) ? value : value ? [value] : []).map(
+ (row: { id: string }) => row.id,
+ )
+ expect(
+ published.filter((id) => !allowed.has(id)),
+ `published rows ${JSON.stringify(published)}`,
+ ).toEqual([])
+}
+
async function wait(ms: number): Promise {
await new Promise((resolve) => setTimeout(resolve, ms))
}
@@ -113,7 +183,8 @@ export function runSuite(rawDriver: LiveQueryDriver) {
}
const driver: LiveQueryDriver = {
...rawDriver,
- makeSource: (data) => sources!.track(rawDriver.makeSource(data)),
+ makeSource: (data, collectionId) =>
+ sources!.track(rawDriver.makeSource(data, collectionId)),
makeDeferredSource: () =>
sources!.track(rawDriver.makeDeferredSource()),
makeLaggingSource: () =>
@@ -170,6 +241,8 @@ export function runSuite(rawDriver: LiveQueryDriver) {
key: string,
name: string,
fn: () => Promise | void,
+ // A generated grammar runs many histories, each through the driver's cut.
+ timeoutMs?: number,
) => {
registry.register(key)
const label = `[${key}] ${name}`
@@ -191,7 +264,7 @@ export function runSuite(rawDriver: LiveQueryDriver) {
sources = null
}
}
- it(label, run)
+ it(label, run, timeoutMs)
}
describe(`live-query conformance :: ${driver.name}`, () => {
@@ -1092,6 +1165,437 @@ export function runSuite(rawDriver: LiveQueryDriver) {
},
)
+ // ---- Tier 2: query identity (1.0 law; see contract.ts) ---------------
+ //
+ // Each scenario runs one history and branches only on the driver's public
+ // `comparesQueryIdentity` policy: a comparing binding rejects, and a
+ // reactive binding publishes the current input's rows. Both branches
+ // check rows, so a reactive binding that kept the old source's rows fails
+ // as surely as a comparing binding that accepted the swap.
+
+ // `fn.where` runs a JavaScript predicate, so its IR has no stable hash.
+ const olderThan = (source: { collection: any }, age: number) => (q: any) =>
+ q
+ .from({ items: source.collection })
+ .fn.where(({ items }: any) => items.age > age)
+ .select(({ items }: any) => ({ id: items.id }))
+ const idsOf = (rows: ReadonlyArray<{ id: string }>) =>
+ rows.map(({ id }) => ({ id }))
+ const comparesIdentity = driver.comparesQueryIdentity
+
+ scenario(
+ `unhashable-query`,
+ `a query without a stable IR identity needs queryKey only where the binding compares identity`,
+ async () => {
+ const source = driver.makeSource(SEED)
+ const build = olderThan(source, 26)
+ for (const mount of [
+ () => driver.mount(build),
+ () => driver.mountConfig(build),
+ ]) {
+ if (comparesIdentity) {
+ await expectRejection(`UnhashableQueryIRError`, async () => {
+ const h = mount()
+ await h.flush()
+ return h.current()
+ })
+ } else {
+ const h = mount()
+ await h.flush()
+ expectUnorderedRows(h.current().data, [{ id: `1` }, { id: `3` }])
+ h.unmount()
+ }
+ }
+ if (!comparesIdentity) {
+ // An empty key counts as none, so it changes nothing here either.
+ const h = driver.mountConfig(build, { queryKey: [] })
+ await h.flush()
+ expectUnorderedRows(h.current().data, [{ id: `1` }, { id: `3` }])
+ h.unmount()
+ }
+ if (comparesIdentity) {
+ // An empty key is absent, as it is for a DbClient preload, so the
+ // query still needs a derived identity.
+ await expectRejection(`UnhashableQueryIRError`, async () => {
+ const h = driver.mountConfig(build, { queryKey: [] })
+ await h.flush()
+ return h.current()
+ })
+ // A queryKey owns the identity, so the same query runs.
+ const h = driver.mountConfig(build, { queryKey: [`older-than`, 26] })
+ await h.flush()
+ expectUnorderedRows(h.current().data, [{ id: `1` }, { id: `3` }])
+ h.unmount()
+ }
+ },
+ )
+
+ scenario(
+ `unhashable-recompile`,
+ `recompiling to a query without a stable IR identity follows the binding's identity policy`,
+ async () => {
+ const source = driver.makeSource(SEED)
+ // `null` selects the structured query; a number, the functional one.
+ const h = driver.mountControllable(
+ (q, age) =>
+ age === null
+ ? q
+ .from({ items: source.collection })
+ .select(({ items }: any) => ({ id: items.id }))
+ : olderThan(source, age)(q),
+ null,
+ )
+ await h.flush()
+ expectUnorderedRows(h.current().data, idsOf(SEED))
+ if (comparesIdentity) {
+ await expectRejection(`UnhashableQueryIRError`, async () => {
+ await h.setParam(26)
+ return h.current()
+ })
+ expectNoRowsAfterRejection(h)
+ return
+ }
+ // A changed captured value recompiles, though no identity names it.
+ await h.setParam(26)
+ expectUnorderedRows(h.current().data, [{ id: `1` }, { id: `3` }])
+ await h.setParam(32)
+ expectUnorderedRows(h.current().data, [{ id: `3` }])
+ h.unmount()
+ },
+ )
+
+ scenario(
+ `source-id-reuse`,
+ `a different source under a Collection ID the binding read is rejected or read as the new source`,
+ async () => {
+ // Claim memory grammar. A history mounts one controllable binding on
+ // A(x) or C(y), then applies two actions. An action selects A(x), B(x)
+ // (another object under A's ID), C(y), or D, which disables the query.
+ // The model judges each step from the history alone, pairwise and
+ // independent of production: in a comparing binding, a step rejects
+ // when an earlier step of the same binding read another object under
+ // its ID, and the rejection ends the history because the failed hook
+ // unmounts. A reactive binding never rejects and shows the rows of
+ // the source the step selects.
+ const sourcesByPick = {
+ A: driver.makeSource(SEED),
+ C: driver.makeSource([
+ { id: `9`, name: `Other`, age: 40, team: `c` },
+ ]),
+ }
+ const reused = driver.makeSource(
+ [{ id: `8`, name: `Reused`, age: 50, team: `d` }],
+ sourcesByPick.A.collection.id,
+ )
+ expect(reused.collection).not.toBe(sourcesByPick.A.collection)
+ type Pick = `A` | `B` | `C` | `D`
+ const objectOf = (pick: Exclude) =>
+ pick === `B` ? reused : sourcesByPick[pick]
+ const rowsOf: Record, Array<{ id: string }>> = {
+ A: idsOf(SEED),
+ B: [{ id: `8` }],
+ C: [{ id: `9` }],
+ }
+ const collides = (history: ReadonlyArray, next: Pick) =>
+ next !== `D` &&
+ history.some(
+ (prior) =>
+ prior !== `D` &&
+ prior !== next &&
+ objectOf(prior).collection.id === objectOf(next).collection.id,
+ )
+ // Declared reach: the states where a claim must outlive the query
+ // that made it.
+ const reach = createOracleReach(`source-id claim memory`, [
+ `swap after an intervening query`,
+ `swap after a disabled step`,
+ `revisit after an intervening query`,
+ ])
+ type ReachState =
+ | `swap after an intervening query`
+ | `swap after a disabled step`
+ | `revisit after an intervening query`
+ // A state names what lies between the step that made a claim and the
+ // step that tests it, so a direct swap or a revisit after only a
+ // disabled step does not count as an intervening query.
+ const reachedState = (
+ history: ReadonlyArray,
+ next: Pick,
+ ): ReachState | undefined => {
+ if (next === `D`) return undefined
+ const lastIndex = (match: (pick: Pick) => boolean) => {
+ for (let index = history.length - 1; index >= 0; index--) {
+ if (match(history[index]!)) return index
+ }
+ return -1
+ }
+ const between = (index: number) => history.slice(index + 1)
+ const conflict = lastIndex(
+ (prior) =>
+ prior !== `D` &&
+ prior !== next &&
+ objectOf(prior).collection.id === objectOf(next).collection.id,
+ )
+ if (conflict >= 0) {
+ const steps = between(conflict)
+ if (steps.some((pick) => pick !== `D`)) {
+ return `swap after an intervening query`
+ }
+ return steps.includes(`D`)
+ ? `swap after a disabled step`
+ : undefined
+ }
+ const revisit = lastIndex((prior) => prior === next)
+ return revisit >= 0 &&
+ between(revisit).some((pick) => pick !== `D` && pick !== next)
+ ? `revisit after an intervening query`
+ : undefined
+ }
+ // Keyed dimension (comparing bindings only). A step may name its
+ // source through a nonempty queryKey: AK reads A(x) and BK reads B(x)
+ // under their own keys. A keyed step records no claim and checks
+ // none, so a claim made before it still binds a later derived step.
+ type KeyedPick = Pick | `AK` | `BK`
+ const objectOfKeyed = (pick: Exclude) =>
+ pick === `AK`
+ ? objectOf(`A`)
+ : pick === `BK`
+ ? objectOf(`B`)
+ : objectOf(pick)
+ const rowsOfKeyed = (pick: Exclude) =>
+ rowsOf[pick === `AK` ? `A` : pick === `BK` ? `B` : pick]
+ const isKeyed = (pick: KeyedPick) => pick === `AK` || pick === `BK`
+ const keyedCollides = (
+ history: ReadonlyArray