@tanstack/db 0.4.2 → 0.4.4

package/src/query/compiler/joins.ts

@@ -17,10 +17,10 @@ import {
   UnsupportedJoinTypeError,
 } from "../../errors.js"
 import { ensureIndexForField } from "../../indexes/auto-index.js"
-import { PropRef } from "../ir.js"
+import { PropRef, followRef } from "../ir.js"
 import { inArray } from "../builder/functions.js"
 import { compileExpression } from "./evaluators.js"
-import { compileQuery, followRef } from "./index.js"
+import type { CompileQueryFn } from "./index.js"
 import type { OrderByOptimizationInfo } from "./order-by.js"
 import type {
   BasicExpression,
@@ -62,7 +62,8 @@ export function processJoins(
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazyCollections: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
-  rawQuery: QueryIR
+  rawQuery: QueryIR,
+  onCompileSubquery: CompileQueryFn
 ): NamespacedAndKeyedStream {
   let resultPipeline = pipeline
 
@@ -81,7 +82,8 @@ export function processJoins(
       callbacks,
       lazyCollections,
       optimizableOrderByCollections,
-      rawQuery
+      rawQuery,
+      onCompileSubquery
     )
   }
 
@@ -105,7 +107,8 @@ function processJoin(
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazyCollections: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
-  rawQuery: QueryIR
+  rawQuery: QueryIR,
+  onCompileSubquery: CompileQueryFn
 ): NamespacedAndKeyedStream {
   // Get the joined table alias and input stream
   const {
@@ -121,7 +124,8 @@ function processJoin(
     lazyCollections,
     optimizableOrderByCollections,
     cache,
-    queryMapping
+    queryMapping,
+    onCompileSubquery
   )
 
   // Add the joined table to the tables map
@@ -392,7 +396,8 @@ function processJoinSource(
   lazyCollections: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
   cache: QueryCache,
-  queryMapping: QueryMapping
+  queryMapping: QueryMapping,
+  onCompileSubquery: CompileQueryFn
 ): { alias: string; input: KeyedStream; collectionId: string } {
   switch (from.type) {
     case `collectionRef`: {
@@ -407,7 +412,7 @@ function processJoinSource(
       const originalQuery = queryMapping.get(from.query) || from.query
 
       // Recursively compile the sub-query with cache
-      const subQueryResult = compileQuery(
+      const subQueryResult = onCompileSubquery(
         originalQuery,
         allInputs,
         collections,

package/src/query/compiler/order-by.ts

@@ -1,16 +1,15 @@
 import { orderByWithFractionalIndex } from "@tanstack/db-ivm"
 import { defaultComparator, makeComparator } from "../../utils/comparison.js"
-import { PropRef } from "../ir.js"
+import { PropRef, followRef } from "../ir.js"
 import { ensureIndexForField } from "../../indexes/auto-index.js"
 import { findIndexForField } from "../../utils/index-optimization.js"
 import { compileExpression } from "./evaluators.js"
 import { replaceAggregatesByRefs } from "./group-by.js"
-import { followRef } from "./index.js"
 import type { CompiledSingleRowExpression } from "./evaluators.js"
 import type { OrderByClause, QueryIR, Select } from "../ir.js"
 import type { NamespacedAndKeyedStream, NamespacedRow } from "../../types.js"
 import type { IStreamBuilder, KeyValue } from "@tanstack/db-ivm"
-import type { BaseIndex } from "../../indexes/base-index.js"
+import type { IndexInterface } from "../../indexes/base-index.js"
 import type { Collection } from "../../collection/index.js"
 
 export type OrderByOptimizationInfo = {
@@ -21,7 +20,7 @@ export type OrderByOptimizationInfo = {
     b: Record<string, unknown> | null | undefined
   ) => number
   valueExtractorForRawRow: (row: Record<string, unknown>) => any
-  index: BaseIndex<string | number>
+  index: IndexInterface<string | number>
   dataNeeded?: () => number
 }
 
@@ -55,18 +54,12 @@ export function processOrderBy(
 
   // Create a value extractor function for the orderBy operator
   const valueExtractor = (row: NamespacedRow & { __select_results?: any }) => {
-    // For ORDER BY expressions, we need to provide access to both:
-    // 1. The original namespaced row data (for direct table column references)
-    // 2. The __select_results (for SELECT alias references)
-
-    // Create a merged context for expression evaluation
-    const orderByContext = { ...row }
-
-    // If there are select results, merge them at the top level for alias access
-    if (row.__select_results) {
-      // Add select results as top-level properties for alias access
-      Object.assign(orderByContext, row.__select_results)
-    }
+    // The namespaced row contains:
+    // 1. Table aliases as top-level properties (e.g., row["tableName"])
+    // 2. SELECT results in __select_results (e.g., row.__select_results["aggregateAlias"])
+    // The replaceAggregatesByRefs function has already transformed any aggregate expressions
+    // that match SELECT aggregates to use the __select_results namespace.
+    const orderByContext = row
 
     if (orderByClause.length > 1) {
       // For multiple orderBy columns, create a composite key
@@ -133,6 +126,7 @@ export function processOrderBy(
           fieldName,
           followRefResult.path,
           followRefCollection,
+          clause.compareOptions,
           compare
         )
       }
@@ -151,10 +145,12 @@ export function processOrderBy(
         return compare(extractedA, extractedB)
       }
 
-      const index: BaseIndex<string | number> | undefined = findIndexForField(
-        followRefCollection.indexes,
-        followRefResult.path
-      )
+      const index: IndexInterface<string | number> | undefined =
+        findIndexForField(
+          followRefCollection.indexes,
+          followRefResult.path,
+          clause.compareOptions
+        )
 
       if (index && index.supports(`gt`)) {
         // We found an index that we can use to lazily load ordered data

package/src/query/index.ts

@@ -9,6 +9,7 @@ export {
   type Context,
   type Source,
   type GetResult,
+  type InferResultType,
 } from "./builder/index.js"
 
 // Expression functions exports

package/src/query/ir.ts

@@ -3,7 +3,7 @@ This is the intermediate representation of the query.
 */
 
 import type { CompareOptions } from "./builder/types"
-import type { CollectionImpl } from "../collection/index.js"
+import type { Collection, CollectionImpl } from "../collection/index.js"
 import type { NamespacedRow } from "../types"
 
 export interface QueryIR {
@@ -17,6 +17,7 @@ export interface QueryIR {
   limit?: Limit
   offset?: Offset
   distinct?: true
+  singleResult?: true
 
   // Functional variants
   fnSelect?: (row: NamespacedRow) => any
@@ -188,3 +189,69 @@ export function createResidualWhere(
 ): Where {
   return { expression, residual: true }
 }
+
+function getRefFromAlias(
+  query: QueryIR,
+  alias: string
+): CollectionRef | QueryRef | void {
+  if (query.from.alias === alias) {
+    return query.from
+  }
+
+  for (const join of query.join || []) {
+    if (join.from.alias === alias) {
+      return join.from
+    }
+  }
+}
+
+/**
+ * Follows the given reference in a query
+ * until its finds the root field the reference points to.
+ * @returns The collection, its alias, and the path to the root field in this collection
+ */
+export function followRef(
+  query: QueryIR,
+  ref: PropRef<any>,
+  collection: Collection
+): { collection: Collection; path: Array<string> } | void {
+  if (ref.path.length === 0) {
+    return
+  }
+
+  if (ref.path.length === 1) {
+    // This field should be part of this collection
+    const field = ref.path[0]!
+    // is it part of the select clause?
+    if (query.select) {
+      const selectedField = query.select[field]
+      if (selectedField && selectedField.type === `ref`) {
+        return followRef(query, selectedField, collection)
+      }
+    }
+
+    // Either this field is not part of the select clause
+    // and thus it must be part of the collection itself
+    // or it is part of the select but is not a reference
+    // so we can stop here and don't have to follow it
+    return { collection, path: [field] }
+  }
+
+  if (ref.path.length > 1) {
+    // This is a nested field
+    const [alias, ...rest] = ref.path
+    const aliasRef = getRefFromAlias(query, alias!)
+    if (!aliasRef) {
+      return
+    }
+
+    if (aliasRef.type === `queryRef`) {
+      return followRef(aliasRef.query, new PropRef(rest), collection)
+    } else {
+      // This is a reference to a collection
+      // we can't follow it further
+      // so the field must be on the collection itself
+      return { collection: aliasRef.collection, path: rest }
+    }
+  }
+}

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

@@ -7,7 +7,7 @@ import type { RootStreamBuilder } from "@tanstack/db-ivm"
 import type { OrderByOptimizationInfo } from "../compiler/order-by.js"
 import type { Collection } from "../../collection/index.js"
 import type {
-  CollectionConfig,
+  CollectionConfigSingleRowOption,
   KeyedStream,
   ResultStream,
   SyncConfig,
@@ -79,7 +79,7 @@ export class CollectionConfigBuilder<
     this.compileBasePipeline()
   }
 
-  getConfig(): CollectionConfig<TResult> {
+  getConfig(): CollectionConfigSingleRowOption<TResult> {
     return {
       id: this.id,
       getKey:
@@ -93,6 +93,7 @@ export class CollectionConfigBuilder<
       onUpdate: this.config.onUpdate,
       onDelete: this.config.onDelete,
       startSync: this.config.startSync,
+      singleResult: this.query.singleResult,
     }
   }
 

package/src/query/live/types.ts

@@ -90,4 +90,9 @@ export interface LiveQueryCollectionConfig<
    * GC time for the collection
    */
   gcTime?: number
+
+  /**
+   * If enabled the collection will return a single object instead of an array
+   */
+  singleResult?: true
 }

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

@@ -3,9 +3,29 @@ import { CollectionConfigBuilder } from "./live/collection-config-builder.js"
 import type { LiveQueryCollectionConfig } from "./live/types.js"
 import type { InitialQueryBuilder, QueryBuilder } from "./builder/index.js"
 import type { Collection } from "../collection/index.js"
-import type { CollectionConfig, UtilsRecord } from "../types.js"
+import type {
+  CollectionConfig,
+  CollectionConfigSingleRowOption,
+  NonSingleResult,
+  SingleResult,
+  UtilsRecord,
+} from "../types.js"
 import type { Context, GetResult } from "./builder/types.js"
 
+type CollectionConfigForContext<
+  TContext extends Context,
+  TResult extends object,
+> = TContext extends SingleResult
+  ? CollectionConfigSingleRowOption<TResult> & SingleResult
+  : CollectionConfigSingleRowOption<TResult> & NonSingleResult
+
+type CollectionForContext<
+  TContext extends Context,
+  TResult extends object,
+> = TContext extends SingleResult
+  ? Collection<TResult> & SingleResult
+  : Collection<TResult> & NonSingleResult
+
 /**
  * Creates live query collection options for use with createCollection
  *
@@ -35,12 +55,15 @@ export function liveQueryCollectionOptions<
   TResult extends object = GetResult<TContext>,
 >(
   config: LiveQueryCollectionConfig<TContext, TResult>
-): CollectionConfig<TResult> {
+): CollectionConfigForContext<TContext, TResult> {
   const collectionConfigBuilder = new CollectionConfigBuilder<
     TContext,
     TResult
   >(config)
-  return collectionConfigBuilder.getConfig()
+  return collectionConfigBuilder.getConfig() as CollectionConfigForContext<
+    TContext,
+    TResult
+  >
 }
 
 /**
@@ -83,7 +106,7 @@ export function createLiveQueryCollection<
   TResult extends object = GetResult<TContext>,
 >(
   query: (q: InitialQueryBuilder) => QueryBuilder<TContext>
-): Collection<TResult, string | number, {}>
+): CollectionForContext<TContext, TResult>
 
 // Overload 2: Accept full config object with optional utilities
 export function createLiveQueryCollection<
@@ -92,7 +115,7 @@ export function createLiveQueryCollection<
   TUtils extends UtilsRecord = {},
 >(
   config: LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils }
-): Collection<TResult, string | number, TUtils>
+): CollectionForContext<TContext, TResult>
 
 // Implementation
 export function createLiveQueryCollection<
@@ -103,7 +126,7 @@ export function createLiveQueryCollection<
   configOrQuery:
     | (LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils })
     | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)
-): Collection<TResult, string | number, TUtils> {
+): CollectionForContext<TContext, TResult> {
   // Determine if the argument is a function (query) or a config object
   if (typeof configOrQuery === `function`) {
     // Simple query function case
@@ -113,7 +136,10 @@ export function createLiveQueryCollection<
       ) => QueryBuilder<TContext>,
     }
     const options = liveQueryCollectionOptions<TContext, TResult>(config)
-    return bridgeToCreateCollection(options)
+    return bridgeToCreateCollection(options) as CollectionForContext<
+      TContext,
+      TResult
+    >
   } else {
     // Config object case
     const config = configOrQuery as LiveQueryCollectionConfig<
@@ -124,7 +150,7 @@ export function createLiveQueryCollection<
     return bridgeToCreateCollection({
       ...options,
       utils: config.utils,
-    })
+    }) as CollectionForContext<TContext, TResult>
   }
 }
 

package/src/types.ts

@@ -503,6 +503,28 @@ export interface CollectionConfig<
   sync: SyncConfig<T, TKey>
 }
 
+export type SingleResult = {
+  singleResult: true
+}
+
+export type NonSingleResult = {
+  singleResult?: never
+}
+
+export type MaybeSingleResult = {
+  /**
+   * If enabled the collection will return a single object instead of an array
+   */
+  singleResult?: true
+}
+
+// Only used for live query collections
+export type CollectionConfigSingleRowOption<
+  T extends object = Record<string, unknown>,
+  TKey extends string | number = string | number,
+  TSchema extends StandardSchemaV1 = never,
+> = CollectionConfig<T, TKey, TSchema> & MaybeSingleResult
+
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<
   ChangeMessage<T>
 >

package/src/utils/index-optimization.ts

@@ -15,7 +15,14 @@
  * - Optimizes IN array expressions
  */
 
-import type { BaseIndex, IndexOperation } from "../indexes/base-index.js"
+import { DEFAULT_COMPARE_OPTIONS } from "../utils.js"
+import { ReverseIndex } from "../indexes/reverse-index.js"
+import type { CompareOptions } from "../query/builder/types.js"
+import type {
+  BaseIndex,
+  IndexInterface,
+  IndexOperation,
+} from "../indexes/base-index.js"
 import type { BasicExpression } from "../query/ir.js"
 
 /**
@@ -30,11 +37,18 @@ export interface OptimizationResult<TKey> {
  * Finds an index that matches a given field path
  */
 export function findIndexForField<TKey extends string | number>(
-  indexes: Map<number, BaseIndex<TKey>>,
-  fieldPath: Array<string>
-): BaseIndex<TKey> | undefined {
+  indexes: Map<number, IndexInterface<TKey>>,
+  fieldPath: Array<string>,
+  compareOptions: CompareOptions = DEFAULT_COMPARE_OPTIONS
+): IndexInterface<TKey> | undefined {
   for (const index of indexes.values()) {
-    if (index.matchesField(fieldPath)) {
+    if (
+      index.matchesField(fieldPath) &&
+      index.matchesCompareOptions(compareOptions)
+    ) {
+      if (!index.matchesDirection(compareOptions.direction)) {
+        return new ReverseIndex(index)
+      }
       return index
     }
   }

package/src/utils.ts

@@ -2,6 +2,8 @@
  * Generic utility functions
  */
 
+import type { CompareOptions } from "./query/builder/types"
+
 interface TypedArray {
   length: number
   [index: number]: number
@@ -209,3 +211,9 @@ export function isTemporal(a: any): boolean {
   const tag = getStringTag(a)
   return typeof tag === `string` && temporalTypes.includes(tag)
 }
+
+export const DEFAULT_COMPARE_OPTIONS: CompareOptions = {
+  direction: `asc`,
+  nulls: `first`,
+  stringSort: `locale`,
+}