@tanstack/db 0.5.32 → 0.6.0

package/src/query/live-query-collection.ts

@@ -6,7 +6,11 @@ import {
 } from './live/collection-registry.js'
 import type { LiveQueryCollectionUtils } from './live/collection-config-builder.js'
 import type { LiveQueryCollectionConfig } from './live/types.js'
-import type { InitialQueryBuilder, QueryBuilder } from './builder/index.js'
+import type {
+  ExtractContext,
+  InitialQueryBuilder,
+  QueryBuilder,
+} from './builder/index.js'
 import type { Collection } from '../collection/index.js'
 import type {
   CollectionConfig,
@@ -15,7 +19,13 @@ import type {
   SingleResult,
   UtilsRecord,
 } from '../types.js'
-import type { Context, GetResult } from './builder/types.js'
+import type {
+  Context,
+  RootObjectResultConstraint,
+  RootQueryBuilder,
+  RootQueryFn,
+  RootQueryResult,
+} from './builder/types.js'
 
 type CollectionConfigForContext<
   TContext extends Context,
@@ -60,10 +70,13 @@ type CollectionForContext<
  * @returns Collection options that can be passed to createCollection
  */
 export function liveQueryCollectionOptions<
-  TContext extends Context,
-  TResult extends object = GetResult<TContext>,
+  TQuery extends QueryBuilder<any>,
+  TContext extends Context = ExtractContext<TQuery>,
+  TResult extends object = RootQueryResult<TContext>,
 >(
-  config: LiveQueryCollectionConfig<TContext, TResult>,
+  config: LiveQueryCollectionConfig<TContext, TResult> & {
+    query: RootQueryFn<TQuery> | RootQueryBuilder<TQuery>
+  },
 ): CollectionConfigForContext<TContext, TResult> & {
   utils: LiveQueryCollectionUtils
 } {
@@ -113,34 +126,42 @@ export function liveQueryCollectionOptions<
 
 // Overload 1: Accept just the query function
 export function createLiveQueryCollection<
-  TContext extends Context,
-  TResult extends object = GetResult<TContext>,
+  TQueryFn extends (q: InitialQueryBuilder) => QueryBuilder<any>,
+  TQuery extends QueryBuilder<any> = ReturnType<TQueryFn>,
 >(
-  query: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
-): CollectionForContext<TContext, TResult> & {
+  query: TQueryFn & RootQueryFn<TQuery>,
+): CollectionForContext<
+  ExtractContext<TQuery>,
+  RootQueryResult<ExtractContext<TQuery>>
+> & {
   utils: LiveQueryCollectionUtils
 }
 
 // Overload 2: Accept full config object with optional utilities
 export function createLiveQueryCollection<
-  TContext extends Context,
-  TResult extends object = GetResult<TContext>,
+  TQuery extends QueryBuilder<any>,
+  TContext extends Context = ExtractContext<TQuery>,
   TUtils extends UtilsRecord = {},
 >(
-  config: LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils },
-): CollectionForContext<TContext, TResult> & {
+  config: LiveQueryCollectionConfig<TContext, RootQueryResult<TContext>> & {
+    query: RootQueryFn<TQuery> | RootQueryBuilder<TQuery>
+    utils?: TUtils
+  },
+): CollectionForContext<TContext, RootQueryResult<TContext>> & {
   utils: LiveQueryCollectionUtils & TUtils
 }
 
 // Implementation
 export function createLiveQueryCollection<
   TContext extends Context,
-  TResult extends object = GetResult<TContext>,
+  TResult extends object = RootQueryResult<TContext>,
   TUtils extends UtilsRecord = {},
 >(
   configOrQuery:
     | (LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils })
-    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>),
+    | ((
+        q: InitialQueryBuilder,
+      ) => QueryBuilder<TContext> & RootObjectResultConstraint<TContext>),
 ): CollectionForContext<TContext, TResult> & {
   utils: LiveQueryCollectionUtils & TUtils
 } {
@@ -150,9 +171,11 @@ export function createLiveQueryCollection<
     const config: LiveQueryCollectionConfig<TContext, TResult> = {
       query: configOrQuery as (
         q: InitialQueryBuilder,
-      ) => QueryBuilder<TContext>,
+      ) => QueryBuilder<TContext> & RootObjectResultConstraint<TContext>,
     }
-    const options = liveQueryCollectionOptions<TContext, TResult>(config)
+    // The implementation accepts both overload shapes, but TypeScript cannot
+    // preserve the overload-specific query-builder inference through this branch.
+    const options = liveQueryCollectionOptions(config as any)
     return bridgeToCreateCollection(options) as CollectionForContext<
       TContext,
       TResult
@@ -163,7 +186,9 @@ export function createLiveQueryCollection<
       TContext,
       TResult
     > & { utils?: TUtils }
-    const options = liveQueryCollectionOptions<TContext, TResult>(config)
+    // Same overload implementation limitation as above: the config has already
+    // been validated by the public signatures, but the branch loses that precision.
+    const options = liveQueryCollectionOptions(config as any)
 
     // Merge custom utils if provided, preserving the getBuilder() method for dependency tracking
     if (config.utils) {

package/src/query/query-once.ts

@@ -1,6 +1,16 @@
 import { createLiveQueryCollection } from './live-query-collection.js'
-import type { InitialQueryBuilder, QueryBuilder } from './builder/index.js'
-import type { Context, InferResultType } from './builder/types.js'
+import type {
+  ExtractContext,
+  InitialQueryBuilder,
+  QueryBuilder,
+} from './builder/index.js'
+import type {
+  Context,
+  InferResultType,
+  RootObjectResultConstraint,
+  RootQueryBuilder,
+  RootQueryFn,
+} from './builder/types.js'
 
 /**
  * Configuration options for queryOnce
@@ -10,8 +20,10 @@ export interface QueryOnceConfig<TContext extends Context> {
    * Query builder function that defines the query
    */
   query:
-    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)
-    | QueryBuilder<TContext>
+    | ((
+        q: InitialQueryBuilder,
+      ) => QueryBuilder<TContext> & RootObjectResultConstraint<TContext>)
+    | (QueryBuilder<TContext> & RootObjectResultConstraint<TContext>)
   // Future: timeout, signal, etc.
 }
 
@@ -44,9 +56,12 @@ export interface QueryOnceConfig<TContext extends Context> {
  * )
  * ```
  */
-export function queryOnce<TContext extends Context>(
-  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
-): Promise<InferResultType<TContext>>
+export function queryOnce<
+  TQueryFn extends (q: InitialQueryBuilder) => QueryBuilder<any>,
+  TQuery extends QueryBuilder<any> = ReturnType<TQueryFn>,
+>(
+  queryFn: TQueryFn & RootQueryFn<TQuery>,
+): Promise<InferResultType<ExtractContext<TQuery>>>
 
 // Overload 2: Config object form returning array (non-single result)
 /**
@@ -65,15 +80,19 @@ export function queryOnce<TContext extends Context>(
  * })
  * ```
  */
-export function queryOnce<TContext extends Context>(
-  config: QueryOnceConfig<TContext>,
-): Promise<InferResultType<TContext>>
+export function queryOnce<TQuery extends QueryBuilder<any>>(
+  config: QueryOnceConfig<ExtractContext<TQuery>> & {
+    query: RootQueryFn<TQuery> | RootQueryBuilder<TQuery>
+  },
+): Promise<InferResultType<ExtractContext<TQuery>>>
 
 // Implementation
 export async function queryOnce<TContext extends Context>(
   configOrQuery:
     | QueryOnceConfig<TContext>
-    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>),
+    | ((
+        q: InitialQueryBuilder,
+      ) => QueryBuilder<TContext> & RootObjectResultConstraint<TContext>),
 ): Promise<InferResultType<TContext>> {
   // Normalize input
   const config: QueryOnceConfig<TContext> =
@@ -107,7 +126,7 @@ export async function queryOnce<TContext extends Context>(
         | undefined
       return first as InferResultType<TContext>
     }
-    return collection.toArray as InferResultType<TContext>
+    return collection.toArray as unknown as InferResultType<TContext>
   } finally {
     // Always cleanup, even on error
     await collection.cleanup()

package/src/query/subset-dedupe.ts

@@ -126,10 +126,8 @@ export class DeduplicatedLoadSubset {
       return prom
     }
 
-    // Not fully covered by existing data — load the missing subset.
-    // We need two clones: trackingOptions preserves the original predicate for
-    // accurate tracking (e.g., where=undefined means "all data"), while loadOptions
-    // may be narrowed with a difference expression for the actual backend request.
+    // Preserve the original request for tracking and in-flight dedupe, but allow
+    // the backend request to be narrowed to only the missing subset.
     const trackingOptions = cloneOptions(options)
     const loadOptions = cloneOptions(options)
     if (this.unlimitedWhere !== undefined && options.limit === undefined) {
@@ -147,7 +145,6 @@ export class DeduplicatedLoadSubset {
 
     // Handle both sync (true) and async (Promise<void>) return values
     if (resultPromise === true) {
-      // Sync return - update tracking with the original predicate
       this.updateTracking(trackingOptions)
       return true
     } else {
@@ -159,7 +156,7 @@ export class DeduplicatedLoadSubset {
 
       // We need to create a reference to the in-flight entry so we can remove it later
       const inflightEntry = {
-        options: loadOptions, // Store load options for subset matching of in-flight requests
+        options: trackingOptions,
         promise: resultPromise
           .then((result) => {
             // Only update tracking if this request is still from the current generation
@@ -238,5 +235,12 @@ export class DeduplicatedLoadSubset {
  * would reflect the mutated values rather than what was actually loaded.
  */
 export function cloneOptions(options: LoadSubsetOptions): LoadSubsetOptions {
-  return { ...options }
+  return {
+    ...options,
+    orderBy: options.orderBy?.map((clause) => ({
+      ...clause,
+      compareOptions: { ...clause.compareOptions },
+    })),
+    cursor: options.cursor ? { ...options.cursor } : undefined,
+  }
 }

package/src/types.ts

@@ -4,7 +4,9 @@ import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { Transaction } from './transactions'
 import type { BasicExpression, OrderBy } from './query/ir.js'
 import type { EventEmitter } from './event-emitter.js'
+import type { IndexConstructor } from './indexes/base-index.js'
 import type { SingleRowRefProxy } from './query/builder/ref-proxy.js'
+import type { WithVirtualProps } from './virtual-props.js'
 
 /**
  * Interface for a collection-like object that provides the necessary methods
@@ -338,6 +340,7 @@ export interface SyncConfig<
     commit: () => void
     markReady: () => void
     truncate: () => void
+    metadata?: SyncMetadataApi<TKey>
   }) => void | CleanupFn | SyncConfigRes
 
   /**
@@ -356,6 +359,25 @@ export interface SyncConfig<
   rowUpdateMode?: `partial` | `full`
 }
 
+export interface SyncMetadataApi<
+  TKey extends string | number = string | number,
+> {
+  row: {
+    get: (key: TKey) => unknown | undefined
+    set: (key: TKey, metadata: unknown) => void
+    delete: (key: TKey) => void
+  }
+  collection: {
+    get: (key: string) => unknown | undefined
+    set: (key: string, value: unknown) => void
+    delete: (key: string) => void
+    list: (prefix?: string) => ReadonlyArray<{
+      key: string
+      value: unknown
+    }>
+  }
+}
+
 export interface ChangeMessage<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
@@ -540,12 +562,27 @@ export interface BaseCollectionConfig<
   /**
    * Auto-indexing mode for the collection.
    * When enabled, indexes will be automatically created for simple where expressions.
-   * @default "eager"
+   * @default "off"
    * @description
-   * - "off": No automatic indexing
-   * - "eager": Automatically create indexes for simple where expressions in subscribeChanges (default)
+   * - "off": No automatic indexing (default). Use explicit indexes for better bundle size.
+   * - "eager": Automatically create indexes for simple where expressions in subscribeChanges.
+   *            Requires setting defaultIndexType.
    */
   autoIndex?: `off` | `eager`
+  /**
+   * Default index type to use when creating indexes without an explicit type.
+   * Required for auto-indexing. Import from '@tanstack/db'.
+   * @example
+   * ```ts
+   * import { BasicIndex } from '@tanstack/db'
+   * const collection = createCollection({
+   *   defaultIndexType: BasicIndex,
+   *   autoIndex: 'eager',
+   *   // ...
+   * })
+   * ```
+   */
+  defaultIndexType?: IndexConstructor<TKey>
   /**
    * Optional function to compare two items.
    * This is used to order the items in the collection.
@@ -739,9 +776,10 @@ export type CollectionConfigSingleRowOption<
   TUtils extends UtilsRecord = {},
 > = CollectionConfig<T, TKey, TSchema, TUtils> & MaybeSingleResult
 
-export type ChangesPayload<T extends object = Record<string, unknown>> = Array<
-  ChangeMessage<T>
->
+export type ChangesPayload<
+  T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+> = Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>>
 
 /**
  * An input row from a collection
@@ -783,6 +821,7 @@ export type NamespacedAndKeyedStream = IStreamBuilder<KeyedNamespacedRow>
  */
 export interface SubscribeChangesOptions<
   T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
 > {
   /** Whether to include the current state as initial changes */
   includeInitialState?: boolean
@@ -800,7 +839,7 @@ export interface SubscribeChangesOptions<
    * })
    * ```
    */
-  where?: (row: SingleRowRefProxy<T>) => any
+  where?: (row: SingleRowRefProxy<WithVirtualProps<T, TKey>>) => any
   /** Pre-compiled expression for filtering changes */
   whereExpression?: BasicExpression<boolean>
   /**
@@ -829,7 +868,8 @@ export interface SubscribeChangesOptions<
 
 export interface SubscribeChangesSnapshotOptions<
   T extends object = Record<string, unknown>,
-> extends Omit<SubscribeChangesOptions<T>, `includeInitialState`> {
+  TKey extends string | number = string | number,
+> extends Omit<SubscribeChangesOptions<T, TKey>, `includeInitialState`> {
   orderBy?: OrderBy
   limit?: number
 }
@@ -879,7 +919,7 @@ export interface CurrentStateAsChangesOptions {
 export type ChangeListener<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
-> = (changes: Array<ChangeMessage<T, TKey>>) => void
+> = (changes: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>>) => void
 
 // Adapted from https://github.com/sindresorhus/type-fest
 // MIT License Copyright (c) Sindre Sorhus

package/src/utils/array-utils.ts

@@ -5,6 +5,35 @@
  * @param compareFn Comparison function to use for ordering
  * @returns The index where the value should be inserted to maintain order
  */
+export function findInsertPositionInArray<T>(
+  sortedArray: Array<T>,
+  value: T,
+  compareFn: (a: T, b: T) => number,
+): number {
+  let left = 0
+  let right = sortedArray.length
+
+  while (left < right) {
+    const mid = Math.floor((left + right) / 2)
+    const comparison = compareFn(sortedArray[mid]!, value)
+
+    if (comparison < 0) {
+      left = mid + 1
+    } else {
+      right = mid
+    }
+  }
+
+  return left
+}
+
+/**
+ * Finds the correct insert position for a value in a sorted tuple array using binary search
+ * @param sortedArray The sorted tuple array to search in
+ * @param value The value to find the position for
+ * @param compareFn Comparison function to use for ordering
+ * @returns The index where the value should be inserted to maintain order
+ */
 export function findInsertPosition<T>(
   sortedArray: Array<[T, any]>,
   value: T,
@@ -26,3 +55,23 @@ export function findInsertPosition<T>(
 
   return left
 }
+
+/**
+ * Deletes a value from a sorted array while maintaining sort order
+ * @param sortedArray The sorted array to delete from
+ * @param value The value to delete
+ * @param compareFn Comparison function to use for ordering
+ * @returns True if the value was found and deleted, false otherwise
+ */
+export function deleteInSortedArray<T>(
+  sortedArray: Array<T>,
+  value: T,
+  compareFn: (a: T, b: T) => number,
+): boolean {
+  const idx = findInsertPositionInArray(sortedArray, value, compareFn)
+  if (idx < sortedArray.length && compareFn(sortedArray[idx]!, value) === 0) {
+    sortedArray.splice(idx, 1)
+    return true
+  }
+  return false
+}

package/src/utils/comparison.ts

@@ -1,3 +1,4 @@
+import { isTemporal } from '../utils'
 import type { CompareOptions } from '../query/builder/types'
 
 // WeakMap to store stable IDs for objects
@@ -54,6 +55,15 @@ export const ascComparator = (a: any, b: any, opts: CompareOptions): number => {
     return a.getTime() - b.getTime()
   }
 
+  // If both are Temporal objects of the same type, compare by string representation
+  if (isTemporal(a) && isTemporal(b)) {
+    const aStr = a.toString()
+    const bStr = b.toString()
+    if (aStr < bStr) return -1
+    if (aStr > bStr) return 1
+    return 0
+  }
+
   // If at least one of the values is an object, use stable IDs for comparison
   const aIsObject = typeof a === `object`
   const bIsObject = typeof b === `object`
@@ -154,6 +164,10 @@ export function normalizeValue(value: any): any {
     return value.getTime()
   }
 
+  if (isTemporal(value)) {
+    return `__temporal__${value[Symbol.toStringTag]}__${value.toString()}`
+  }
+
   // Normalize Uint8Arrays/Buffers to a string representation for Map key usage
   // This enables content-based equality for binary data like ULIDs
   const isUint8Array =

package/src/utils/index-optimization.ts

@@ -17,6 +17,7 @@
 
 import { DEFAULT_COMPARE_OPTIONS } from '../utils.js'
 import { ReverseIndex } from '../indexes/reverse-index.js'
+import { hasVirtualPropPath } from '../virtual-props.js'
 import type { CompareOptions } from '../query/builder/types.js'
 import type { IndexInterface, IndexOperation } from '../indexes/base-index.js'
 import type { BasicExpression } from '../query/ir.js'
@@ -38,6 +39,9 @@ export function findIndexForField<TKey extends string | number>(
   fieldPath: Array<string>,
   compareOptions?: CompareOptions,
 ): IndexInterface<TKey> | undefined {
+  if (hasVirtualPropPath(fieldPath)) {
+    return undefined
+  }
   const compareOpts = compareOptions ?? {
     ...DEFAULT_COMPARE_OPTIONS,
     ...collection.compareOptions,

package/src/utils.ts

@@ -144,8 +144,8 @@ function deepEqualsInternal(
   // Handle Temporal objects
   // Check if both are Temporal objects of the same type
   if (isTemporal(a) && isTemporal(b)) {
-    const aTag = getStringTag(a)
-    const bTag = getStringTag(b)
+    const aTag = a[Symbol.toStringTag]
+    const bTag = b[Symbol.toStringTag]
 
     // If they're different Temporal types, they're not equal
     if (aTag !== bTag) return false
@@ -211,7 +211,7 @@ function deepEqualsInternal(
   return false
 }
 
-const temporalTypes = [
+const temporalTypes = new Set([
   `Temporal.Duration`,
   `Temporal.Instant`,
   `Temporal.PlainDate`,
@@ -220,16 +220,19 @@ const temporalTypes = [
   `Temporal.PlainTime`,
   `Temporal.PlainYearMonth`,
   `Temporal.ZonedDateTime`,
-]
+])
 
-function getStringTag(a: any): any {
-  return a[Symbol.toStringTag]
+export interface TemporalLike {
+  [Symbol.toStringTag]: string
+  toString: () => string
+  equals?: (other: unknown) => boolean
 }
 
 /** Checks if the value is a Temporal object by checking for the Temporal brand */
-export function isTemporal(a: any): boolean {
-  const tag = getStringTag(a)
-  return typeof tag === `string` && temporalTypes.includes(tag)
+export function isTemporal(a: unknown): a is TemporalLike {
+  if (a == null || typeof a !== `object`) return false
+  const tag = (a as Record<symbol, unknown>)[Symbol.toStringTag]
+  return typeof tag === `string` && temporalTypes.has(tag)
 }
 
 export const DEFAULT_COMPARE_OPTIONS: CompareOptions = {