@tanstack/db 0.6.1 → 0.6.3

package/src/query/builder/ref-proxy.ts

@@ -284,8 +284,10 @@ export function createRefProxyWithSelected<T extends Record<string, any>>(
 }
 
 /**
- * Converts a value to an Expression
- * If it's a RefProxy, creates a Ref, otherwise creates a Value
+ * Converts a value to an Expression.
+ * If it's a RefProxy, creates a PropRef. Throws if the value is a
+ * ToArrayWrapper or ConcatToArrayWrapper (these must be used as direct
+ * select fields). Otherwise wraps it as a Value.
  */
 export function toExpression<T = any>(value: T): BasicExpression<T>
 export function toExpression(value: RefProxy<any>): BasicExpression<any>
@@ -293,6 +295,20 @@ export function toExpression(value: any): BasicExpression<any> {
   if (isRefProxy(value)) {
     return new PropRef(value.__path)
   }
+  // toArray() and concat(toArray()) must be used as direct select fields, not inside expressions
+  if (
+    value &&
+    typeof value === `object` &&
+    (value.__brand === `ToArrayWrapper` ||
+      value.__brand === `ConcatToArrayWrapper`)
+  ) {
+    const name =
+      value.__brand === `ToArrayWrapper` ? `toArray()` : `concat(toArray())`
+    throw new Error(
+      `${name} cannot be used inside expressions (e.g., coalesce(), eq(), not()). ` +
+        `Use ${name} directly as a select field value instead.`,
+    )
+  }
   // If it's already an Expression (Func, Ref, Value) or Agg, return it directly
   if (
     value &&

package/src/query/compiler/joins.ts

@@ -302,8 +302,20 @@ function processJoin(
             return
           }
 
-          // Request filtered snapshot from lazy collection for matching join keys
-          const joinKeys = data.getInner().map(([[joinKey]]) => joinKey)
+          // Deduplicate and filter null keys before requesting snapshot
+          const joinKeys = [
+            ...new Set(
+              data
+                .getInner()
+                .map(([[joinKey]]) => joinKey)
+                .filter((key) => key != null),
+            ),
+          ]
+
+          if (joinKeys.length === 0) {
+            return
+          }
+
           const lazyJoinRef = new PropRef(followRefResult.path)
           const loaded = lazySourceSubscription.requestSnapshot({
             where: inArray(lazyJoinRef, joinKeys),
@@ -312,6 +324,14 @@ function processJoin(
 
           if (!loaded) {
             // Snapshot wasn't sent because it could not be loaded from the indexes
+            const collectionId = followRefCollection.id
+            const fieldPath = followRefResult.path.join(`.`)
+            console.warn(
+              `[TanStack DB]${collectionId ? ` [${collectionId}]` : ``} Join requires an index on "${fieldPath}" for efficient loading. ` +
+                `Falling back to loading all data. ` +
+                `Consider creating an index on the collection with collection.createIndex((row) => row.${fieldPath}) ` +
+                `or enable auto-indexing with autoIndex: 'eager' and a defaultIndexType.`,
+            )
             lazySourceSubscription.requestSnapshot()
           }
         }),

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

@@ -191,6 +191,17 @@ export function processOrderBy(
           index = undefined
         }
 
+        if (!index) {
+          const collectionId = followRefCollection.id
+          const fieldPath = followRefResult.path.join(`.`)
+          console.warn(
+            `[TanStack DB]${collectionId ? ` [${collectionId}]` : ``} orderBy with limit requires an index on "${fieldPath}" for efficient lazy loading. ` +
+              `Falling back to loading all data. ` +
+              `Consider creating an index on the collection with collection.createIndex((row) => row.${fieldPath}) ` +
+              `or enable auto-indexing with autoIndex: 'eager' and a defaultIndexType.`,
+          )
+        }
+
         orderByAlias =
           firstOrderByExpression.path.length > 1
             ? String(firstOrderByExpression.path[0])
@@ -292,12 +303,16 @@ export function processOrderBy(
 
       // Set up lazy loading callback to track how much more data is needed
       // This is used by loadMoreIfNeeded to determine if more data should be loaded
-      setSizeCallback = (getSize: () => number) => {
-        optimizableOrderByCollections[targetCollectionId]![`dataNeeded`] =
-          () => {
-            const size = getSize()
-            return Math.max(0, orderByOptimizationInfo!.limit - size)
-          }
+      // Only enable when an index exists — without an index, lazy loading can't work
+      // and all data is loaded eagerly via requestSnapshot instead.
+      if (index) {
+        setSizeCallback = (getSize: () => number) => {
+          optimizableOrderByCollections[targetCollectionId]![`dataNeeded`] =
+            () => {
+              const size = getSize()
+              return Math.max(0, orderByOptimizationInfo!.limit - size)
+            }
+        }
       }
     }
   }

package/src/query/effect.ts

@@ -883,7 +883,7 @@ class EffectPipelineRunner<TRow extends object, TKey extends string | number> {
     for (const [, orderByInfo] of Object.entries(
       this.optimizableOrderByCollections,
     )) {
-      if (!orderByInfo.dataNeeded) continue
+      if (!orderByInfo.dataNeeded || !orderByInfo.index) continue
 
       if (this.pendingOrderedLoadPromise) {
         // Wait for in-flight loads to complete before requesting more

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

@@ -227,7 +227,8 @@ export class CollectionConfigBuilder<
       id: this.id,
       getKey:
         this.config.getKey ||
-        ((item) => this.resultKeys.get(item) as string | number),
+        ((item: any) =>
+          (this.resultKeys.get(item) ?? item.$key) as string | number),
       sync: this.getSyncConfig(),
       compare: this.compare,
       defaultStringCollation: this.compareOptions,
@@ -1515,6 +1516,7 @@ function createChildCollectionEntry(
       },
     },
     startSync: true,
+    gcTime: 0,
   })
 
   const entry: ChildCollectionEntry = {
@@ -1697,6 +1699,30 @@ function flushIncludesState(
         )
       }
     }
+    // Finally: entries with deep nested buffer changes (grandchild-or-deeper buffers
+    // have pending data, but neither this level nor the immediate child level changed).
+    // Without this pass, changes at depth 3+ are stranded because drainNestedBuffers
+    // only drains one level and Phase 4 only flushes entries dirty from Phase 2/3.
+    const deepBufferDirty = new Set<unknown>()
+    if (state.nestedSetups) {
+      for (const [correlationKey, entry] of state.childRegistry) {
+        if (entriesWithChildChanges.has(correlationKey)) continue
+        if (dirtyFromBuffers.has(correlationKey)) continue
+        if (
+          entry.includesStates &&
+          hasPendingIncludesChanges(entry.includesStates)
+        ) {
+          flushIncludesState(
+            entry.includesStates,
+            entry.collection,
+            entry.collection.id,
+            null,
+            entry.syncMethods,
+          )
+          deepBufferDirty.add(correlationKey)
+        }
+      }
+    }
 
     // For inline materializations: re-emit affected parents with updated snapshots.
     // We mutate items in-place (so collection.get() reflects changes immediately)
@@ -1705,7 +1731,11 @@ function flushIncludesState(
     // deepEquals, but in-place mutation means both sides reference the same
     // object, so the comparison always returns true and suppresses the event.
     const inlineReEmitKeys = materializesInline(state)
-      ? new Set([...(affectedCorrelationKeys || []), ...dirtyFromBuffers])
+      ? new Set([
+          ...(affectedCorrelationKeys || []),
+          ...dirtyFromBuffers,
+          ...deepBufferDirty,
+        ])
       : null
     if (parentSyncMethods && inlineReEmitKeys && inlineReEmitKeys.size > 0) {
       const events: Array<ChangeMessage<any>> = []

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

@@ -332,12 +332,12 @@ export class CollectionSubscriber<
       return true
     }
 
-    const { dataNeeded } = orderByInfo
+    const { dataNeeded, index } = orderByInfo
 
-    if (!dataNeeded) {
-      // dataNeeded is not set when there's no index (e.g., non-ref expression).
-      // In this case, we've already loaded all data via requestSnapshot
-      // and don't need to lazily load more.
+    if (!dataNeeded || !index) {
+      // dataNeeded is not set when there's no index (e.g., non-ref expression
+      // or auto-indexing is disabled). Without an index, lazy loading can't work —
+      // all data was already loaded eagerly via requestSnapshot.
       return true
     }