@tanstack/db 0.4.0 → 0.4.2

package/dist/esm/utils/comparison.js.map

@@ -1 +1 @@
-{"version":3,"file":"comparison.js","sources":["../../../src/utils/comparison.ts"],"sourcesContent":["import type { CompareOptions } from \"../query/builder/types\"\n\n// WeakMap to store stable IDs for objects\nconst objectIds = new WeakMap<object, number>()\nlet nextObjectId = 1\n\n/**\n * Get or create a stable ID for an object\n */\nfunction getObjectId(obj: object): number {\n  if (objectIds.has(obj)) {\n    return objectIds.get(obj)!\n  }\n  const id = nextObjectId++\n  objectIds.set(obj, id)\n  return id\n}\n\n/**\n * Universal comparison function for all data types\n * Handles null/undefined, strings, arrays, dates, objects, and primitives\n * Always sorts null/undefined values first\n */\nexport const ascComparator = (a: any, b: any, opts: CompareOptions): number => {\n  const { nulls } = opts\n\n  // Handle null/undefined\n  if (a == null && b == null) return 0\n  if (a == null) return nulls === `first` ? -1 : 1\n  if (b == null) return nulls === `first` ? 1 : -1\n\n  // if a and b are both strings, compare them based on locale\n  if (typeof a === `string` && typeof b === `string`) {\n    if (opts.stringSort === `locale`) {\n      return a.localeCompare(b, opts.locale, opts.localeOptions)\n    }\n    // For lexical sort we rely on direct comparison for primitive values\n  }\n\n  // if a and b are both arrays, compare them element by element\n  if (Array.isArray(a) && Array.isArray(b)) {\n    for (let i = 0; i < Math.min(a.length, b.length); i++) {\n      const result = ascComparator(a[i], b[i], opts)\n      if (result !== 0) {\n        return result\n      }\n    }\n    // All elements are equal up to the minimum length\n    return a.length - b.length\n  }\n\n  // If both are dates, compare them\n  if (a instanceof Date && b instanceof Date) {\n    return a.getTime() - b.getTime()\n  }\n\n  // If at least one of the values is an object, use stable IDs for comparison\n  const aIsObject = typeof a === `object`\n  const bIsObject = typeof b === `object`\n\n  if (aIsObject || bIsObject) {\n    // If both are objects, compare their stable IDs\n    if (aIsObject && bIsObject) {\n      const aId = getObjectId(a)\n      const bId = getObjectId(b)\n      return aId - bId\n    }\n\n    // If only one is an object, objects come after primitives\n    if (aIsObject) return 1\n    if (bIsObject) return -1\n  }\n\n  // For primitive values, use direct comparison\n  if (a < b) return -1\n  if (a > b) return 1\n  return 0\n}\n\n/**\n * Descending comparator function for ordering values\n * Handles null/undefined as largest values (opposite of ascending)\n */\nexport const descComparator = (\n  a: unknown,\n  b: unknown,\n  opts: CompareOptions\n): number => {\n  return ascComparator(b, a, {\n    ...opts,\n    nulls: opts.nulls === `first` ? `last` : `first`,\n  })\n}\n\nexport function makeComparator(\n  opts: CompareOptions\n): (a: any, b: any) => number {\n  return (a, b) => {\n    if (opts.direction === `asc`) {\n      return ascComparator(a, b, opts)\n    } else {\n      return descComparator(a, b, opts)\n    }\n  }\n}\n\n/** Default comparator orders values in ascending order with nulls first and locale string comparison. */\nexport const defaultComparator = makeComparator({\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n})\n"],"names":[],"mappings":"AAGA,MAAM,gCAAgB,QAAA;AACtB,IAAI,eAAe;AAKnB,SAAS,YAAY,KAAqB;AACxC,MAAI,UAAU,IAAI,GAAG,GAAG;AACtB,WAAO,UAAU,IAAI,GAAG;AAAA,EAC1B;AACA,QAAM,KAAK;AACX,YAAU,IAAI,KAAK,EAAE;AACrB,SAAO;AACT;AAOO,MAAM,gBAAgB,CAAC,GAAQ,GAAQ,SAAiC;AAC7E,QAAM,EAAE,UAAU;AAGlB,MAAI,KAAK,QAAQ,KAAK,KAAM,QAAO;AACnC,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,KAAK;AAC/C,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,IAAI;AAG9C,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAClD,QAAI,KAAK,eAAe,UAAU;AAChC,aAAO,EAAE,cAAc,GAAG,KAAK,QAAQ,KAAK,aAAa;AAAA,IAC3D;AAAA,EAEF;AAGA,MAAI,MAAM,QAAQ,CAAC,KAAK,MAAM,QAAQ,CAAC,GAAG;AACxC,aAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK;AACrD,YAAM,SAAS,cAAc,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;AAC7C,UAAI,WAAW,GAAG;AAChB,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO,EAAE,SAAS,EAAE;AAAA,EACtB;AAGA,MAAI,aAAa,QAAQ,aAAa,MAAM;AAC1C,WAAO,EAAE,YAAY,EAAE,QAAA;AAAA,EACzB;AAGA,QAAM,YAAY,OAAO,MAAM;AAC/B,QAAM,YAAY,OAAO,MAAM;AAE/B,MAAI,aAAa,WAAW;AAE1B,QAAI,aAAa,WAAW;AAC1B,YAAM,MAAM,YAAY,CAAC;AACzB,YAAM,MAAM,YAAY,CAAC;AACzB,aAAO,MAAM;AAAA,IACf;AAGA,QAAI,UAAW,QAAO;AACtB,QAAI,UAAW,QAAO;AAAA,EACxB;AAGA,MAAI,IAAI,EAAG,QAAO;AAClB,MAAI,IAAI,EAAG,QAAO;AAClB,SAAO;AACT;AAMO,MAAM,iBAAiB,CAC5B,GACA,GACA,SACW;AACX,SAAO,cAAc,GAAG,GAAG;AAAA,IACzB,GAAG;AAAA,IACH,OAAO,KAAK,UAAU,UAAU,SAAS;AAAA,EAAA,CAC1C;AACH;AAEO,SAAS,eACd,MAC4B;AAC5B,SAAO,CAAC,GAAG,MAAM;AACf,QAAI,KAAK,cAAc,OAAO;AAC5B,aAAO,cAAc,GAAG,GAAG,IAAI;AAAA,IACjC,OAAO;AACL,aAAO,eAAe,GAAG,GAAG,IAAI;AAAA,IAClC;AAAA,EACF;AACF;AAGO,MAAM,oBAAoB,eAAe;AAAA,EAC9C,WAAW;AAAA,EACX,OAAO;AAAA,EACP,YAAY;AACd,CAAC;"}
+{"version":3,"file":"comparison.js","sources":["../../../src/utils/comparison.ts"],"sourcesContent":["import type { CompareOptions } from \"../query/builder/types\"\n\n// WeakMap to store stable IDs for objects\nconst objectIds = new WeakMap<object, number>()\nlet nextObjectId = 1\n\n/**\n * Get or create a stable ID for an object\n */\nfunction getObjectId(obj: object): number {\n  if (objectIds.has(obj)) {\n    return objectIds.get(obj)!\n  }\n  const id = nextObjectId++\n  objectIds.set(obj, id)\n  return id\n}\n\n/**\n * Universal comparison function for all data types\n * Handles null/undefined, strings, arrays, dates, objects, and primitives\n * Always sorts null/undefined values first\n */\nexport const ascComparator = (a: any, b: any, opts: CompareOptions): number => {\n  const { nulls } = opts\n\n  // Handle null/undefined\n  if (a == null && b == null) return 0\n  if (a == null) return nulls === `first` ? -1 : 1\n  if (b == null) return nulls === `first` ? 1 : -1\n\n  // if a and b are both strings, compare them based on locale\n  if (typeof a === `string` && typeof b === `string`) {\n    if (opts.stringSort === `locale`) {\n      return a.localeCompare(b, opts.locale, opts.localeOptions)\n    }\n    // For lexical sort we rely on direct comparison for primitive values\n  }\n\n  // if a and b are both arrays, compare them element by element\n  if (Array.isArray(a) && Array.isArray(b)) {\n    for (let i = 0; i < Math.min(a.length, b.length); i++) {\n      const result = ascComparator(a[i], b[i], opts)\n      if (result !== 0) {\n        return result\n      }\n    }\n    // All elements are equal up to the minimum length\n    return a.length - b.length\n  }\n\n  // If both are dates, compare them\n  if (a instanceof Date && b instanceof Date) {\n    return a.getTime() - b.getTime()\n  }\n\n  // If at least one of the values is an object, use stable IDs for comparison\n  const aIsObject = typeof a === `object`\n  const bIsObject = typeof b === `object`\n\n  if (aIsObject || bIsObject) {\n    // If both are objects, compare their stable IDs\n    if (aIsObject && bIsObject) {\n      const aId = getObjectId(a)\n      const bId = getObjectId(b)\n      return aId - bId\n    }\n\n    // If only one is an object, objects come after primitives\n    if (aIsObject) return 1\n    if (bIsObject) return -1\n  }\n\n  // For primitive values, use direct comparison\n  if (a < b) return -1\n  if (a > b) return 1\n  return 0\n}\n\n/**\n * Descending comparator function for ordering values\n * Handles null/undefined as largest values (opposite of ascending)\n */\nexport const descComparator = (\n  a: unknown,\n  b: unknown,\n  opts: CompareOptions\n): number => {\n  return ascComparator(b, a, {\n    ...opts,\n    nulls: opts.nulls === `first` ? `last` : `first`,\n  })\n}\n\nexport function makeComparator(\n  opts: CompareOptions\n): (a: any, b: any) => number {\n  return (a, b) => {\n    if (opts.direction === `asc`) {\n      return ascComparator(a, b, opts)\n    } else {\n      return descComparator(a, b, opts)\n    }\n  }\n}\n\n/** Default comparator orders values in ascending order with nulls first and locale string comparison. */\nexport const defaultComparator = makeComparator({\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n})\n\n/**\n * Normalize a value for comparison\n */\nexport function normalizeValue(value: any): any {\n  if (value instanceof Date) {\n    return value.getTime()\n  }\n  return value\n}\n"],"names":[],"mappings":"AAGA,MAAM,gCAAgB,QAAA;AACtB,IAAI,eAAe;AAKnB,SAAS,YAAY,KAAqB;AACxC,MAAI,UAAU,IAAI,GAAG,GAAG;AACtB,WAAO,UAAU,IAAI,GAAG;AAAA,EAC1B;AACA,QAAM,KAAK;AACX,YAAU,IAAI,KAAK,EAAE;AACrB,SAAO;AACT;AAOO,MAAM,gBAAgB,CAAC,GAAQ,GAAQ,SAAiC;AAC7E,QAAM,EAAE,UAAU;AAGlB,MAAI,KAAK,QAAQ,KAAK,KAAM,QAAO;AACnC,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,KAAK;AAC/C,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,IAAI;AAG9C,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAClD,QAAI,KAAK,eAAe,UAAU;AAChC,aAAO,EAAE,cAAc,GAAG,KAAK,QAAQ,KAAK,aAAa;AAAA,IAC3D;AAAA,EAEF;AAGA,MAAI,MAAM,QAAQ,CAAC,KAAK,MAAM,QAAQ,CAAC,GAAG;AACxC,aAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK;AACrD,YAAM,SAAS,cAAc,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;AAC7C,UAAI,WAAW,GAAG;AAChB,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO,EAAE,SAAS,EAAE;AAAA,EACtB;AAGA,MAAI,aAAa,QAAQ,aAAa,MAAM;AAC1C,WAAO,EAAE,YAAY,EAAE,QAAA;AAAA,EACzB;AAGA,QAAM,YAAY,OAAO,MAAM;AAC/B,QAAM,YAAY,OAAO,MAAM;AAE/B,MAAI,aAAa,WAAW;AAE1B,QAAI,aAAa,WAAW;AAC1B,YAAM,MAAM,YAAY,CAAC;AACzB,YAAM,MAAM,YAAY,CAAC;AACzB,aAAO,MAAM;AAAA,IACf;AAGA,QAAI,UAAW,QAAO;AACtB,QAAI,UAAW,QAAO;AAAA,EACxB;AAGA,MAAI,IAAI,EAAG,QAAO;AAClB,MAAI,IAAI,EAAG,QAAO;AAClB,SAAO;AACT;AAMO,MAAM,iBAAiB,CAC5B,GACA,GACA,SACW;AACX,SAAO,cAAc,GAAG,GAAG;AAAA,IACzB,GAAG;AAAA,IACH,OAAO,KAAK,UAAU,UAAU,SAAS;AAAA,EAAA,CAC1C;AACH;AAEO,SAAS,eACd,MAC4B;AAC5B,SAAO,CAAC,GAAG,MAAM;AACf,QAAI,KAAK,cAAc,OAAO;AAC5B,aAAO,cAAc,GAAG,GAAG,IAAI;AAAA,IACjC,OAAO;AACL,aAAO,eAAe,GAAG,GAAG,IAAI;AAAA,IAClC;AAAA,EACF;AACF;AAGO,MAAM,oBAAoB,eAAe;AAAA,EAC9C,WAAW;AAAA,EACX,OAAO;AAAA,EACP,YAAY;AACd,CAAC;AAKM,SAAS,eAAe,OAAiB;AAC9C,MAAI,iBAAiB,MAAM;AACzB,WAAO,MAAM,QAAA;AAAA,EACf;AACA,SAAO;AACT;"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@tanstack/db-ivm": "0.1.8"
+    "@tanstack/db-ivm": "0.1.9"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^3.2.4",

package/src/collection/events.ts

@@ -70,7 +70,7 @@ export class CollectionEventsManager {
     this.listeners.get(event)!.add(callback)
 
     return () => {
-      this.listeners.get(event)!.delete(callback)
+      this.listeners.get(event)?.delete(callback)
     }
   }
 

package/src/collection/lifecycle.ts

@@ -1,7 +1,13 @@
 import {
   CollectionInErrorStateError,
+  CollectionStateError,
   InvalidCollectionStatusTransitionError,
 } from "../errors"
+import {
+  safeCancelIdleCallback,
+  safeRequestIdleCallback,
+} from "../utils/browser-polyfills"
+import type { IdleCallbackDeadline } from "../utils/browser-polyfills"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { CollectionConfig, CollectionStatus } from "../types"
 import type { CollectionEventsManager } from "./events"
@@ -29,6 +35,7 @@ export class CollectionLifecycleManager<
   public hasReceivedFirstCommit = false
   public onFirstReadyCallbacks: Array<() => void> = []
   public gcTimeoutId: ReturnType<typeof setTimeout> | null = null
+  private idleCallbackId: number | null = null
 
   /**
    * Creates a new CollectionLifecycleManager instance
@@ -84,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
@@ -123,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) {
@@ -140,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()
+      }
     }
   }
 
@@ -167,9 +185,8 @@ export class CollectionLifecycleManager<
 
     this.gcTimeoutId = setTimeout(() => {
       if (this.changes.activeSubscribersCount === 0) {
-        // We call the main collection cleanup, not just the one for the
-        // lifecycle manager
-        this.cleanup()
+        // Schedule cleanup during idle time to avoid blocking the UI thread
+        this.scheduleIdleCleanup()
       }
     }, gcTime)
   }
@@ -183,6 +200,77 @@ export class CollectionLifecycleManager<
       clearTimeout(this.gcTimeoutId)
       this.gcTimeoutId = null
     }
+    // Also cancel any pending idle cleanup
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId)
+      this.idleCallbackId = null
+    }
+  }
+
+  /**
+   * Schedule cleanup to run during browser idle time
+   * This prevents blocking the UI thread during cleanup operations
+   */
+  private scheduleIdleCleanup(): void {
+    // Cancel any existing idle callback
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId)
+    }
+
+    // Schedule cleanup with a timeout of 1 second
+    // This ensures cleanup happens even if the browser is busy
+    this.idleCallbackId = safeRequestIdleCallback(
+      (deadline) => {
+        // Perform cleanup if we still have no subscribers
+        if (this.changes.activeSubscribersCount === 0) {
+          const cleanupCompleted = this.performCleanup(deadline)
+          // Only clear the callback ID if cleanup actually completed
+          if (cleanupCompleted) {
+            this.idleCallbackId = null
+          }
+        } else {
+          // No need to cleanup, clear the callback ID
+          this.idleCallbackId = null
+        }
+      },
+      { timeout: 1000 }
+    )
+  }
+
+  /**
+   * Perform cleanup operations, optionally in chunks during idle time
+   * @returns true if cleanup was completed, false if it was rescheduled
+   */
+  private performCleanup(deadline?: IdleCallbackDeadline): boolean {
+    // If we have a deadline, we can potentially split cleanup into chunks
+    // For now, we'll do all cleanup at once but check if we have time
+    const hasTime =
+      !deadline || deadline.timeRemaining() > 0 || deadline.didTimeout
+
+    if (hasTime) {
+      // Perform all cleanup operations
+      this.events.cleanup()
+      this.sync.cleanup()
+      this.state.cleanup()
+      this.changes.cleanup()
+      this.indexes.cleanup()
+
+      if (this.gcTimeoutId) {
+        clearTimeout(this.gcTimeoutId)
+        this.gcTimeoutId = null
+      }
+
+      this.hasBeenReady = false
+      this.onFirstReadyCallbacks = []
+
+      // Set status to cleaned-up
+      this.setStatus(`cleaned-up`)
+      return true
+    } else {
+      // If we don't have time, reschedule for the next idle period
+      this.scheduleIdleCleanup()
+      return false
+    }
   }
 
   /**
@@ -201,21 +289,13 @@ export class CollectionLifecycleManager<
   }
 
   public cleanup(): void {
-    this.events.cleanup()
-    this.sync.cleanup()
-    this.state.cleanup()
-    this.changes.cleanup()
-    this.indexes.cleanup()
-
-    if (this.gcTimeoutId) {
-      clearTimeout(this.gcTimeoutId)
-      this.gcTimeoutId = null
+    // Cancel any pending idle cleanup
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId)
+      this.idleCallbackId = null
     }
 
-    this.hasBeenReady = false
-    this.onFirstReadyCallbacks = []
-
-    // Set status to cleaned-up
-    this.setStatus(`cleaned-up`)
+    // Perform cleanup immediately (used when explicitly called)
+    this.performCleanup()
   }
 }

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/browser-polyfills.ts

@@ -0,0 +1,39 @@
+// Type definitions for requestIdleCallback - compatible with existing browser types
+export type IdleCallbackDeadline = {
+  didTimeout: boolean
+  timeRemaining: () => number
+}
+
+export type IdleCallbackFunction = (deadline: IdleCallbackDeadline) => void
+
+const requestIdleCallbackPolyfill = (
+  callback: IdleCallbackFunction
+): number => {
+  // Use a very small timeout for the polyfill to simulate idle time
+  const timeout = 0
+  const timeoutId = setTimeout(() => {
+    callback({
+      didTimeout: true, // Always indicate timeout for the polyfill
+      timeRemaining: () => 50, // Return some time remaining for polyfill
+    })
+  }, timeout)
+  return timeoutId as unknown as number
+}
+
+const cancelIdleCallbackPolyfill = (id: number): void => {
+  clearTimeout(id as unknown as ReturnType<typeof setTimeout>)
+}
+
+export const safeRequestIdleCallback: (
+  callback: IdleCallbackFunction,
+  options?: { timeout?: number }
+) => number =
+  typeof window !== `undefined` && `requestIdleCallback` in window
+    ? (callback, options) =>
+        (window as any).requestIdleCallback(callback, options)
+    : (callback, _options) => requestIdleCallbackPolyfill(callback)
+
+export const safeCancelIdleCallback: (id: number) => void =
+  typeof window !== `undefined` && `cancelIdleCallback` in window
+    ? (id) => (window as any).cancelIdleCallback(id)
+    : cancelIdleCallbackPolyfill

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
+}