@tanstack/db 0.4.1 → 0.4.2

package/src/collection/lifecycle.ts

@@ -1,5 +1,6 @@
 import {
   CollectionInErrorStateError,
+  CollectionStateError,
   InvalidCollectionStatusTransitionError,
 } from "../errors"
 import {
@@ -90,7 +91,18 @@ export class CollectionLifecycleManager<
    * Safely update the collection status with validation
    * @private
    */
-  public setStatus(newStatus: CollectionStatus): void {
+  public setStatus(
+    newStatus: CollectionStatus,
+    allowReady: boolean = false
+  ): void {
+    if (newStatus === `ready` && !allowReady) {
+      // setStatus('ready') is an internal method that should not be called directly
+      // Instead, use markReady to transition to ready triggering the necessary events
+      // and side effects.
+      throw new CollectionStateError(
+        `You can't directly call "setStatus('ready'). You must use markReady instead.`
+      )
+    }
     this.validateStatusTransition(this.status, newStatus)
     const previousStatus = this.status
     this.status = newStatus
@@ -129,9 +141,10 @@ export class CollectionLifecycleManager<
    * @private - Should only be called by sync implementations
    */
   public markReady(): void {
+    this.validateStatusTransition(this.status, `ready`)
     // Can transition to ready from loading or initialCommit states
     if (this.status === `loading` || this.status === `initialCommit`) {
-      this.setStatus(`ready`)
+      this.setStatus(`ready`, true)
 
       // Call any registered first ready callbacks (only on first time becoming ready)
       if (!this.hasBeenReady) {
@@ -146,12 +159,11 @@ export class CollectionLifecycleManager<
         this.onFirstReadyCallbacks = []
         callbacks.forEach((callback) => callback())
       }
-    }
-
-    // Always notify dependents when markReady is called, after status is set
-    // This ensures live queries get notified when their dependencies become ready
-    if (this.changes.changeSubscriptions.size > 0) {
-      this.changes.emitEmptyReadyEvent()
+      // Notify dependents when markReady is called, after status is set
+      // This ensures live queries get notified when their dependencies become ready
+      if (this.changes.changeSubscriptions.size > 0) {
+        this.changes.emitEmptyReadyEvent()
+      }
     }
   }
 

package/src/collection/state.ts

@@ -644,7 +644,7 @@ export class CollectionStateManager<
 
         // Ensure listeners are active before emitting this critical batch
         if (this.lifecycle.status !== `ready`) {
-          this.lifecycle.setStatus(`ready`)
+          this.lifecycle.markReady()
         }
       }
 

package/src/indexes/btree-index.ts

@@ -1,5 +1,5 @@
 import { BTree } from "../utils/btree.js"
-import { defaultComparator } from "../utils/comparison.js"
+import { defaultComparator, normalizeValue } from "../utils/comparison.js"
 import { BaseIndex } from "./base-index.js"
 import type { BasicExpression } from "../query/ir.js"
 import type { IndexOperation } from "./base-index.js"
@@ -71,15 +71,18 @@ export class BTreeIndex<
       )
     }
 
+    // Normalize the value for Map key usage
+    const normalizedValue = normalizeValue(indexedValue)
+
     // Check if this value already exists
-    if (this.valueMap.has(indexedValue)) {
+    if (this.valueMap.has(normalizedValue)) {
       // Add to existing set
-      this.valueMap.get(indexedValue)!.add(key)
+      this.valueMap.get(normalizedValue)!.add(key)
     } else {
       // Create new set for this value
       const keySet = new Set<TKey>([key])
-      this.valueMap.set(indexedValue, keySet)
-      this.orderedEntries.set(indexedValue, undefined)
+      this.valueMap.set(normalizedValue, keySet)
+      this.orderedEntries.set(normalizedValue, undefined)
     }
 
     this.indexedKeys.add(key)
@@ -101,16 +104,19 @@ export class BTreeIndex<
       return
     }
 
-    if (this.valueMap.has(indexedValue)) {
-      const keySet = this.valueMap.get(indexedValue)!
+    // Normalize the value for Map key usage
+    const normalizedValue = normalizeValue(indexedValue)
+
+    if (this.valueMap.has(normalizedValue)) {
+      const keySet = this.valueMap.get(normalizedValue)!
       keySet.delete(key)
 
       // If set is now empty, remove the entry entirely
       if (keySet.size === 0) {
-        this.valueMap.delete(indexedValue)
+        this.valueMap.delete(normalizedValue)
 
         // Remove from ordered entries
-        this.orderedEntries.delete(indexedValue)
+        this.orderedEntries.delete(normalizedValue)
       }
     }
 
@@ -195,7 +201,8 @@ export class BTreeIndex<
    * Performs an equality lookup
    */
   equalityLookup(value: any): Set<TKey> {
-    return new Set(this.valueMap.get(value) ?? [])
+    const normalizedValue = normalizeValue(value)
+    return new Set(this.valueMap.get(normalizedValue) ?? [])
   }
 
   /**
@@ -206,8 +213,10 @@ export class BTreeIndex<
     const { from, to, fromInclusive = true, toInclusive = true } = options
     const result = new Set<TKey>()
 
-    const fromKey = from ?? this.orderedEntries.minKey()
-    const toKey = to ?? this.orderedEntries.maxKey()
+    const normalizedFrom = normalizeValue(from)
+    const normalizedTo = normalizeValue(to)
+    const fromKey = normalizedFrom ?? this.orderedEntries.minKey()
+    const toKey = normalizedTo ?? this.orderedEntries.maxKey()
 
     this.orderedEntries.forRange(
       fromKey,
@@ -240,7 +249,7 @@ export class BTreeIndex<
     const keysInResult: Set<TKey> = new Set()
     const result: Array<TKey> = []
     const nextKey = (k?: any) => this.orderedEntries.nextHigherKey(k)
-    let key = from
+    let key = normalizeValue(from)
 
     while ((key = nextKey(key)) && result.length < n) {
       const keys = this.valueMap.get(key)
@@ -266,7 +275,8 @@ export class BTreeIndex<
     const result = new Set<TKey>()
 
     for (const value of values) {
-      const keys = this.valueMap.get(value)
+      const normalizedValue = normalizeValue(value)
+      const keys = this.valueMap.get(normalizedValue)
       if (keys) {
         keys.forEach((key) => result.add(key))
       }

package/src/query/builder/functions.ts

@@ -53,10 +53,10 @@ type ExtractType<T> =
 // Helper type to determine aggregate return type based on input nullability
 type AggregateReturnType<T> =
   ExtractType<T> extends infer U
-    ? U extends number | undefined | null
+    ? U extends number | undefined | null | Date | bigint
       ? Aggregate<U>
-      : Aggregate<number | undefined | null>
-    : Aggregate<number | undefined | null>
+      : Aggregate<number | undefined | null | Date | bigint>
+    : Aggregate<number | undefined | null | Date | bigint>
 
 // Helper type to determine string function return type based on input nullability
 type StringFunctionReturnType<T> =

package/src/query/compiler/evaluators.ts

@@ -3,6 +3,7 @@ import {
   UnknownExpressionTypeError,
   UnknownFunctionError,
 } from "../../errors.js"
+import { normalizeValue } from "../../utils/comparison.js"
 import type { BasicExpression, Func, PropRef } from "../ir.js"
 import type { NamespacedRow } from "../../types.js"
 
@@ -142,8 +143,8 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
       return (data) => {
-        const a = argA(data)
-        const b = argB(data)
+        const a = normalizeValue(argA(data))
+        const b = normalizeValue(argB(data))
         return a === b
       }
     }

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

@@ -349,6 +349,19 @@ function getAggregateFunction(aggExpr: Aggregate) {
     return typeof value === `number` ? value : value != null ? Number(value) : 0
   }
 
+  // Create a value extractor function for the expression to aggregate
+  const valueExtractorWithDate = ([, namespacedRow]: [
+    string,
+    NamespacedRow,
+  ]) => {
+    const value = compiledExpr(namespacedRow)
+    return typeof value === `number` || value instanceof Date
+      ? value
+      : value != null
+        ? Number(value)
+        : 0
+  }
+
   // Create a raw value extractor function for the expression to aggregate
   const rawValueExtractor = ([, namespacedRow]: [string, NamespacedRow]) => {
     return compiledExpr(namespacedRow)
@@ -363,9 +376,9 @@ function getAggregateFunction(aggExpr: Aggregate) {
     case `avg`:
       return avg(valueExtractor)
     case `min`:
-      return min(valueExtractor)
+      return min(valueExtractorWithDate)
     case `max`:
-      return max(valueExtractor)
+      return max(valueExtractorWithDate)
     default:
       throw new UnsupportedAggregateFunctionError(aggExpr.name)
   }

package/src/query/compiler/joins.ts

@@ -204,7 +204,12 @@ function processJoin(
       lazyFrom.type === `queryRef` &&
       (lazyFrom.query.limit || lazyFrom.query.offset)
 
-    if (!limitedSubquery) {
+    // If join expressions contain computed values (like concat functions)
+    // we don't optimize the join because we don't have an index over the computed values
+    const hasComputedJoinExpr =
+      mainExpr.type === `func` || joinedExpr.type === `func`
+
+    if (!limitedSubquery && !hasComputedJoinExpr) {
       // This join can be optimized by having the active collection
       // dynamically load keys into the lazy collection
       // based on the value of the joinKey and by looking up

package/src/query/optimizer.ts

@@ -142,6 +142,8 @@ export interface AnalyzedWhereClause {
   expression: BasicExpression<boolean>
   /** Set of table/source aliases that this WHERE clause touches */
   touchedSources: Set<string>
+  /** Whether this clause contains namespace-only references that prevent pushdown */
+  hasNamespaceOnlyRef: boolean
 }
 
 /**
@@ -486,19 +488,31 @@ function splitAndClausesRecursive(
  * This determines whether a clause can be pushed down to a specific table
  * or must remain in the main query (for multi-source clauses like join conditions).
  *
+ * Special handling for namespace-only references in outer joins:
+ * WHERE clauses that reference only a table namespace (e.g., isUndefined(special), eq(special, value))
+ * rather than specific properties (e.g., isUndefined(special.id), eq(special.id, value)) are treated as
+ * multi-source to prevent incorrect predicate pushdown that would change join semantics.
+ *
  * @param clause - The WHERE expression to analyze
  * @returns Analysis result with the expression and touched source aliases
  *
  * @example
  * ```typescript
- * // eq(users.department_id, 1) -> touches ['users']
- * // eq(users.id, posts.user_id) -> touches ['users', 'posts']
+ * // eq(users.department_id, 1) -> touches ['users'], hasNamespaceOnlyRef: false
+ * // eq(users.id, posts.user_id) -> touches ['users', 'posts'], hasNamespaceOnlyRef: false
+ * // isUndefined(special) -> touches ['special'], hasNamespaceOnlyRef: true (prevents pushdown)
+ * // eq(special, someValue) -> touches ['special'], hasNamespaceOnlyRef: true (prevents pushdown)
+ * // isUndefined(special.id) -> touches ['special'], hasNamespaceOnlyRef: false (allows pushdown)
+ * // eq(special.id, 5) -> touches ['special'], hasNamespaceOnlyRef: false (allows pushdown)
  * ```
  */
 function analyzeWhereClause(
   clause: BasicExpression<boolean>
 ): AnalyzedWhereClause {
+  // Track which table aliases this WHERE clause touches
   const touchedSources = new Set<string>()
+  // Track whether this clause contains namespace-only references that prevent pushdown
+  let hasNamespaceOnlyRef = false
 
   /**
    * Recursively collect all table aliases referenced in an expression
@@ -511,6 +525,13 @@ function analyzeWhereClause(
           const firstElement = expr.path[0]
           if (firstElement) {
             touchedSources.add(firstElement)
+
+            // If the path has only one element (just the namespace),
+            // this is a namespace-only reference that should not be pushed down
+            // This applies to ANY function, not just existence-checking functions
+            if (expr.path.length === 1) {
+              hasNamespaceOnlyRef = true
+            }
           }
         }
         break
@@ -537,6 +558,7 @@ function analyzeWhereClause(
   return {
     expression: clause,
     touchedSources,
+    hasNamespaceOnlyRef,
   }
 }
 
@@ -557,15 +579,15 @@ function groupWhereClauses(
 
   // Categorize each clause based on how many sources it touches
   for (const clause of analyzedClauses) {
-    if (clause.touchedSources.size === 1) {
-      // Single source clause - can be optimized
+    if (clause.touchedSources.size === 1 && !clause.hasNamespaceOnlyRef) {
+      // Single source clause without namespace-only references - can be optimized
       const source = Array.from(clause.touchedSources)[0]!
       if (!singleSource.has(source)) {
         singleSource.set(source, [])
       }
       singleSource.get(source)!.push(clause.expression)
-    } else if (clause.touchedSources.size > 1) {
-      // Multi-source clause - must stay in main query
+    } else if (clause.touchedSources.size > 1 || clause.hasNamespaceOnlyRef) {
+      // Multi-source clause or namespace-only reference - must stay in main query
       multiSource.push(clause.expression)
     }
     // Skip clauses that touch no sources (constants) - they don't need optimization

package/src/types.ts

@@ -334,8 +334,14 @@ export interface BaseCollectionConfig<
    */
   gcTime?: number
   /**
-   * Whether to start syncing immediately when the collection is created.
-   * Defaults to false for lazy loading. Set to true to immediately sync.
+   * Whether to eagerly start syncing on collection creation.
+   * When true, syncing begins immediately. When false, syncing starts when the first subscriber attaches.
+   *
+   * Note: Even with startSync=true, collections will pause syncing when there are no active
+   * subscribers (typically when components querying the collection unmount), resuming when new
+   * subscribers attach. This preserves normal staleTime/gcTime behavior.
+   *
+   * @default false
    */
   startSync?: boolean
   /**

package/src/utils/comparison.ts

@@ -110,3 +110,13 @@ export const defaultComparator = makeComparator({
   nulls: `first`,
   stringSort: `locale`,
 })
+
+/**
+ * Normalize a value for comparison
+ */
+export function normalizeValue(value: any): any {
+  if (value instanceof Date) {
+    return value.getTime()
+  }
+  return value
+}