@tanstack/db 0.5.32 → 0.6.0

package/src/collection/subscription.ts

@@ -256,6 +256,13 @@ export class CollectionSubscription
     this.orderByIndex = index
   }
 
+  /**
+   * Check if an orderBy index has been set for this subscription
+   */
+  hasOrderByIndex(): boolean {
+    return this.orderByIndex !== undefined
+  }
+
   /**
    * Set subscription status and emit events if changed
    */

package/src/collection/sync.ts

@@ -18,6 +18,7 @@ import type {
   LoadSubsetOptions,
   OptimisticChangeMessage,
   SyncConfigRes,
+  SyncMetadataApi,
 } from '../types'
 import type { CollectionImpl } from './index.js'
 import type { CollectionStateManager } from './state'
@@ -93,6 +94,8 @@ export class CollectionSyncManager<
               committed: false,
               operations: [],
               deletedKeys: new Set(),
+              rowMetadataWrites: new Map(),
+              collectionMetadataWrites: new Map(),
               immediate: options?.immediate,
             })
           },
@@ -120,6 +123,10 @@ export class CollectionSyncManager<
               key = this.config.getKey(messageWithOptionalKey.value)
             }
 
+            if (this.state.pendingLocalChanges.has(key)) {
+              this.state.pendingLocalOrigins.add(key)
+            }
+
             let messageType = messageWithOptionalKey.type
 
             // Check if an item with this key already exists when inserting
@@ -165,6 +172,23 @@ export class CollectionSyncManager<
 
             if (messageType === `delete`) {
               pendingTransaction.deletedKeys.add(key)
+              pendingTransaction.rowMetadataWrites.set(key, { type: `delete` })
+            } else if (messageType === `insert`) {
+              if (message.metadata !== undefined) {
+                pendingTransaction.rowMetadataWrites.set(key, {
+                  type: `set`,
+                  value: message.metadata,
+                })
+              } else {
+                pendingTransaction.rowMetadataWrites.set(key, {
+                  type: `delete`,
+                })
+              }
+            } else if (message.metadata !== undefined) {
+              pendingTransaction.rowMetadataWrites.set(key, {
+                type: `set`,
+                value: message.metadata,
+              })
             }
           },
           commit: () => {
@@ -201,6 +225,11 @@ export class CollectionSyncManager<
             // Clear all operations from the current transaction
             pendingTransaction.operations = []
             pendingTransaction.deletedKeys.clear()
+            pendingTransaction.rowMetadataWrites.clear()
+            // Intentionally preserve collectionMetadataWrites across truncate.
+            // Collection-scoped metadata (for example persisted resume/reset
+            // state) can be staged before truncate and should commit atomically
+            // with the truncate transaction.
 
             // Mark the transaction as a truncate operation. During commit, this triggers:
             // - Delete events for all previously synced keys (excluding optimistic-deleted keys)
@@ -216,6 +245,7 @@ export class CollectionSyncManager<
               deletes: new Set(this.state.optimisticDeletes),
             }
           },
+          metadata: this.createSyncMetadataApi(),
         }),
       )
 
@@ -241,6 +271,113 @@ export class CollectionSyncManager<
     }
   }
 
+  private getActivePendingSyncTransaction() {
+    const pendingTransaction =
+      this.state.pendingSyncedTransactions[
+        this.state.pendingSyncedTransactions.length - 1
+      ]
+
+    if (!pendingTransaction) {
+      throw new NoPendingSyncTransactionWriteError()
+    }
+    if (pendingTransaction.committed) {
+      throw new SyncTransactionAlreadyCommittedWriteError()
+    }
+
+    return pendingTransaction
+  }
+
+  private createSyncMetadataApi(): SyncMetadataApi<TKey> {
+    return {
+      row: {
+        get: (key) => {
+          const pendingTransaction =
+            this.state.pendingSyncedTransactions[
+              this.state.pendingSyncedTransactions.length - 1
+            ]
+          const pendingWrite = pendingTransaction?.rowMetadataWrites.get(key)
+          if (pendingWrite) {
+            return pendingWrite.type === `delete`
+              ? undefined
+              : pendingWrite.value
+          }
+          if (pendingTransaction?.truncate) {
+            return undefined
+          }
+          return this.state.syncedMetadata.get(key)
+        },
+        set: (key, metadata) => {
+          const pendingTransaction = this.getActivePendingSyncTransaction()
+          pendingTransaction.rowMetadataWrites.set(key, {
+            type: `set`,
+            value: metadata,
+          })
+        },
+        delete: (key) => {
+          const pendingTransaction = this.getActivePendingSyncTransaction()
+          pendingTransaction.rowMetadataWrites.set(key, {
+            type: `delete`,
+          })
+        },
+      },
+      collection: {
+        get: (key) => {
+          const pendingTransaction =
+            this.state.pendingSyncedTransactions[
+              this.state.pendingSyncedTransactions.length - 1
+            ]
+          const pendingWrite =
+            pendingTransaction?.collectionMetadataWrites.get(key)
+          if (pendingWrite) {
+            return pendingWrite.type === `delete`
+              ? undefined
+              : pendingWrite.value
+          }
+          return this.state.syncedCollectionMetadata.get(key)
+        },
+        set: (key, value) => {
+          const pendingTransaction = this.getActivePendingSyncTransaction()
+          pendingTransaction.collectionMetadataWrites.set(key, {
+            type: `set`,
+            value,
+          })
+        },
+        delete: (key) => {
+          const pendingTransaction = this.getActivePendingSyncTransaction()
+          pendingTransaction.collectionMetadataWrites.set(key, {
+            type: `delete`,
+          })
+        },
+        list: (prefix) => {
+          const merged = new Map(this.state.syncedCollectionMetadata)
+          const pendingTransaction =
+            this.state.pendingSyncedTransactions[
+              this.state.pendingSyncedTransactions.length - 1
+            ]
+          if (pendingTransaction) {
+            for (const [
+              key,
+              pendingWrite,
+            ] of pendingTransaction.collectionMetadataWrites) {
+              if (pendingWrite.type === `delete`) {
+                merged.delete(key)
+              } else {
+                merged.set(key, pendingWrite.value)
+              }
+            }
+          }
+
+          return Array.from(merged.entries())
+            .filter(([key]) => (prefix ? key.startsWith(prefix) : true))
+            .map(([key, value]) => ({
+              key,
+              value,
+            }))
+        },
+      },
+    }
+  }
+
   /**
    * Preload the collection data by starting sync if not already started
    * Multiple concurrent calls will share the same promise

package/src/collection/transaction-metadata.ts

@@ -0,0 +1 @@
+export const DIRECT_TRANSACTION_METADATA_KEY = `__tanstack_db_direct`

package/src/errors.ts

@@ -444,6 +444,15 @@ export class FnSelectWithGroupByError extends QueryCompilationError {
   }
 }
 
+export class UnsupportedRootScalarSelectError extends QueryCompilationError {
+  constructor() {
+    super(
+      `Top-level scalar select() is not supported by createLiveQueryCollection() or queryOnce(). ` +
+        `Return an object from .select(), or use the scalar query inside toArray(...) or concat(toArray(...)).`,
+    )
+  }
+}
+
 export class HavingRequiresGroupByError extends QueryCompilationError {
   constructor() {
     super(`HAVING clause requires GROUP BY clause`)

package/src/index.ts

@@ -17,15 +17,69 @@ export { deepEquals } from './utils'
 export * from './paced-mutations'
 export * from './strategies/index.js'
 
+// Virtual properties exports
+export {
+  type VirtualRowProps,
+  type VirtualOrigin,
+  type WithVirtualProps,
+  type WithoutVirtualProps,
+  hasVirtualProps,
+} from './virtual-props.js'
+
 // Index system exports
-export * from './indexes/base-index.js'
-export * from './indexes/btree-index.js'
-export * from './indexes/lazy-index.js'
+export { BaseIndex } from './indexes/base-index.js'
+export type {
+  IndexInterface,
+  IndexConstructor,
+  IndexStats,
+  IndexOperation,
+} from './indexes/base-index.js'
 export { type IndexOptions } from './indexes/index-options.js'
 
+// Index implementations
+export { BasicIndex } from './indexes/basic-index.js'
+export type {
+  BasicIndexOptions,
+  RangeQueryOptions,
+} from './indexes/basic-index.js'
+export { BTreeIndex } from './indexes/btree-index.js'
+export type { RangeQueryOptions as BTreeRangeQueryOptions } from './indexes/btree-index.js'
+export { ReverseIndex } from './indexes/reverse-index.js'
+
+// Index optimization utilities
+export {
+  optimizeExpressionWithIndexes,
+  findIndexForField,
+} from './utils/index-optimization.js'
+
+// Dev mode utilities
+export {
+  configureIndexDevMode,
+  isDevModeEnabled,
+  getIndexDevModeConfig,
+  trackQuery,
+  clearQueryPatterns,
+  getQueryPatterns,
+} from './indexes/index-registry.js'
+export type {
+  IndexDevModeConfig,
+  IndexSuggestion,
+} from './indexes/index-registry.js'
+
 // Expression helpers
 export * from './query/expression-helpers.js'
 
+// Reactive effects
+export {
+  createEffect,
+  type DeltaEvent,
+  type DeltaType,
+  type EffectConfig,
+  type EffectContext,
+  type Effect,
+  type EffectQueryInput,
+} from './query/effect.js'
+
 // Re-export some stuff explicitly to ensure the type & value is exported
 export type { Collection } from './collection/index.js'
 export { IR }

package/src/indexes/auto-index.ts

@@ -1,5 +1,6 @@
 import { DEFAULT_COMPARE_OPTIONS } from '../utils'
-import { BTreeIndex } from './btree-index'
+import { hasVirtualPropPath } from '../virtual-props'
+import { checkCollectionSizeForIndex, isDevModeEnabled } from './index-registry'
 import type { CompareOptions } from '../query/builder/types'
 import type { BasicExpression } from '../query/ir'
 import type { CollectionImpl } from '../collection/index.js'
@@ -10,11 +11,9 @@ export interface AutoIndexConfig {
 
 function shouldAutoIndex(collection: CollectionImpl<any, any, any, any, any>) {
   // Only proceed if auto-indexing is enabled
-  if (collection.config.autoIndex !== `eager`) {
-    return false
-  }
-
-  return true
+  // Note: autoIndex: 'eager' without defaultIndexType is caught at construction time
+  // in CollectionImpl, so we don't need to check for it here.
+  return collection.config.autoIndex === `eager`
 }
 
 export function ensureIndexForField<
@@ -27,6 +26,9 @@ export function ensureIndexForField<
   compareOptions?: CompareOptions,
   compareFn?: (a: any, b: any) => number,
 ) {
+  if (hasVirtualPropPath(fieldPath)) {
+    return
+  }
   if (!shouldAutoIndex(collection)) {
     return
   }
@@ -46,9 +48,18 @@ export function ensureIndexForField<
     return // Index already exists
   }
 
+  // Dev mode: check if collection size warrants an index suggestion
+  if (isDevModeEnabled()) {
+    checkCollectionSizeForIndex(
+      collection.id || `unknown`,
+      collection.size,
+      fieldPath,
+    )
+  }
+
   // Create a new index for this field using the collection's createIndex method
+  // The collection will use its defaultIndexType
   try {
-    // Use the proxy-based approach to create the proper accessor for nested paths
     collection.createIndex(
       (row) => {
         // Navigate through the field path
@@ -60,7 +71,6 @@ export function ensureIndexForField<
       },
       {
         name: `auto:${fieldPath.join(`.`)}`,
-        indexType: BTreeIndex,
         options: compareFn ? { compareFn, compareOptions: compareOpts } : {},
       },
     )

package/src/indexes/base-index.ts

@@ -26,7 +26,7 @@ export interface IndexStats {
 }
 
 export interface IndexInterface<
-  TKey extends string | number | undefined = string | number | undefined,
+  TKey extends string | number = string | number,
 > {
   add: (key: TKey, item: any) => void
   remove: (key: TKey, item: any) => void
@@ -79,7 +79,7 @@ export interface IndexInterface<
  * Base abstract class that all index types extend
  */
 export abstract class BaseIndex<
-  TKey extends string | number | undefined = string | number | undefined,
+  TKey extends string | number = string | number,
 > implements IndexInterface<TKey> {
   public readonly id: number
   public readonly name?: string
@@ -189,7 +189,6 @@ export abstract class BaseIndex<
     }
   }
 
-  // Protected methods for subclasses
   protected abstract initialize(options?: any): void
 
   protected evaluateIndexExpression(item: any): any {
@@ -218,10 +217,3 @@ export type IndexConstructor<TKey extends string | number = string | number> =
     name?: string,
     options?: any,
   ) => BaseIndex<TKey>
-
-/**
- * Index resolver can be either a class constructor or async loader
- */
-export type IndexResolver<TKey extends string | number = string | number> =
-  | IndexConstructor<TKey>
-  | (() => Promise<IndexConstructor<TKey>>)