refactor(db): simplify indexing with BasicIndex and explicit defaultIndexType

- Add BasicIndex using Map + sorted Array for both equality and range queries
- Remove registry pattern - pass defaultIndexType to collection constructor instead
- Remove lazy index infrastructure (LazyIndexWrapper, IndexProxy)
- Simplify indexing.ts entry point to just export BasicIndex and BTreeIndex
- Update all tests to explicitly set defaultIndexType where needed
- Update changeset to reflect simplified approach

Breaking changes:
- createIndex() requires defaultIndexType on collection or indexType in config
- enableIndexing()/enableBTreeIndexing() removed, use defaultIndexType instead

Author: claude

.changeset/optional-indexing.md

@@ -2,43 +2,59 @@
 "@tanstack/db": minor
 ---
 
-Make indexing optional with two index types for different use cases
+Make indexing explicit with two index types for different use cases
 
 **Breaking Changes:**
 - `autoIndex` now defaults to `off` instead of `eager`
 - `BTreeIndex` is no longer exported from `@tanstack/db` main entry point
+- To use `createIndex()` or `autoIndex: 'eager'`, you must set `defaultIndexType` on the collection
 
 **Changes:**
 - New `@tanstack/db/indexing` entry point for tree-shakeable indexing
-- **MapIndex** - Lightweight index for equality lookups (`eq`, `in`). Range queries (`gt`, `lt`, etc.) fall back to scanning.
-- **BTreeIndex** - Full-featured index with range queries and sorted iteration for ORDER BY optimization
-- `enableIndexing()` - Uses MapIndex (lightweight, for most use cases)
-- `enableBTreeIndexing()` - Uses BTreeIndex (for ORDER BY on large collections 10k+ items)
+- **BasicIndex** - Lightweight index using Map + sorted Array for both equality and range queries (`eq`, `in`, `gt`, `gte`, `lt`, `lte`). O(n) updates but fast reads.
+- **BTreeIndex** - Full-featured index with O(log n) updates and sorted iteration for ORDER BY optimization on large collections (10k+ items)
 - Dev mode suggestions (ON by default) warn when indexes would help
 
 **Migration:**
 
-If you were relying on auto-indexing, choose an approach based on your needs:
+If you were relying on auto-indexing, set `defaultIndexType` on your collections:
 
-1. **Lightweight indexing** (equality lookups, range queries fall back to scan):
+1. **Lightweight indexing** (good for most use cases):
 ```ts
-import { enableIndexing } from '@tanstack/db/indexing'
-enableIndexing()  // Uses MapIndex - supports eq, in
+import { BasicIndex } from '@tanstack/db/indexing'
+
+const collection = createCollection({
+  defaultIndexType: BasicIndex,
+  autoIndex: 'eager',
+  // ...
+})
 ```
 
 2. **Full BTree indexing** (for ORDER BY optimization on large collections):
 ```ts
-import { enableBTreeIndexing } from '@tanstack/db/indexing'
-enableBTreeIndexing()  // Uses BTreeIndex - supports sorted iteration
+import { BTreeIndex } from '@tanstack/db/indexing'
+
+const collection = createCollection({
+  defaultIndexType: BTreeIndex,
+  autoIndex: 'eager',
+  // ...
+})
 ```
 
-3. **Per-collection explicit indexes** (best tree-shaking):
+3. **Per-index explicit type** (mix index types):
 ```ts
-import { BTreeIndex } from '@tanstack/db/indexing'
-collection.createIndex((row) => row.userId, { indexType: BTreeIndex })
+import { BasicIndex, BTreeIndex } from '@tanstack/db/indexing'
+
+const collection = createCollection({
+  defaultIndexType: BasicIndex,  // Default for createIndex()
+  // ...
+})
+
+// Override for specific indexes
+collection.createIndex((row) => row.date, { indexType: BTreeIndex })
 ```
 
 **Bundle Size Impact:**
 - No indexing: ~30% smaller bundle
-- MapIndex: ~5 KB (~1.3 KB gzipped)
+- BasicIndex: ~5 KB (~1.3 KB gzipped)
 - BTreeIndex: ~33 KB (~7.8 KB gzipped)

packages/db/src/collection/index.ts

@@ -13,7 +13,7 @@ import { CollectionMutationsManager } from "./mutations"
 import { CollectionEventsManager } from "./events.js"
 import type { CollectionSubscription } from "./subscription"
 import type { AllCollectionEvents, CollectionEventHandler } from "./events.js"
-import type { BaseIndex, IndexResolver } from "../indexes/base-index.js"
+import type { BaseIndex, IndexConstructor } from "../indexes/base-index.js"
 import type { IndexOptions } from "../indexes/index-options.js"
 import type {
   ChangeMessage,
@@ -35,8 +35,6 @@ import type {
 } from "../types"
 import type { SingleRowRefProxy } from "../query/builder/ref-proxy"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type { BTreeIndex } from "../indexes/btree-index.js"
-import type { IndexProxy } from "../indexes/lazy-index.js"
 
 /**
  * Enhanced Collection interface that includes both data type T and utilities TUtils
@@ -347,6 +345,7 @@ export class CollectionImpl<
     this._indexes.setDeps({
       state: this._state,
       lifecycle: this._lifecycle,
+      defaultIndexType: config.defaultIndexType,
     })
     this._lifecycle.setDeps({
       changes: this._changes,
@@ -523,38 +522,27 @@ export class CollectionImpl<
    * Indexes significantly improve query performance by allowing constant time lookups
    * and logarithmic time range queries instead of full scans.
    *
-   * @template TResolver - The type of the index resolver (constructor or async loader)
    * @param indexCallback - Function that extracts the indexed value from each item
    * @param config - Configuration including index type and type-specific options
-   * @returns An index proxy that provides access to the index when ready
+   * @returns The created index
    *
    * @example
-   * // Create a default B+ tree index
-   * const ageIndex = collection.createIndex((row) => row.age)
+   * ```ts
+   * import { BasicIndex } from '@tanstack/db/indexing'
    *
-   * // Create a ordered index with custom options
+   * // Create an index with explicit type
    * const ageIndex = collection.createIndex((row) => row.age, {
-   *   indexType: BTreeIndex,
-   *   options: {
-   *     compareFn: customComparator,
-   *     compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' }
-   *   },
-   *   name: 'age_btree'
+   *   indexType: BasicIndex
    * })
    *
-   * // Create an async-loaded index
-   * const textIndex = collection.createIndex((row) => row.content, {
-   *   indexType: async () => {
-   *     const { FullTextIndex } = await import('./indexes/fulltext.js')
-   *     return FullTextIndex
-   *   },
-   *   options: { language: 'en' }
-   * })
+   * // Create an index with collection's default type
+   * const nameIndex = collection.createIndex((row) => row.name)
+   * ```
    */
-  public createIndex<TResolver extends IndexResolver<TKey> = typeof BTreeIndex>(
+  public createIndex<TIndexType extends IndexConstructor<TKey>>(
     indexCallback: (row: SingleRowRefProxy<TOutput>) => any,
-    config: IndexOptions<TResolver> = {}
-  ): IndexProxy<TKey> {
+    config: IndexOptions<TIndexType> = {}
+  ): BaseIndex<TKey> {
     return this._indexes.createIndex(indexCallback, config)
   }
 

packages/db/src/collection/indexes.ts

@@ -1,11 +1,9 @@
-import { IndexProxy, LazyIndexWrapper } from "../indexes/lazy-index"
 import {
   createSingleRowRefProxy,
   toExpression,
 } from "../query/builder/ref-proxy"
-import { getDefaultIndexType } from "../indexes/index-registry"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type { BaseIndex, IndexResolver } from "../indexes/base-index"
+import type { BaseIndex, IndexConstructor } from "../indexes/base-index"
 import type { ChangeMessage } from "../types"
 import type { IndexOptions } from "../indexes/index-options"
 import type { SingleRowRefProxy } from "../query/builder/ref-proxy"
@@ -20,146 +18,79 @@ export class CollectionIndexesManager<
 > {
   private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>
   private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>
+  private defaultIndexType: IndexConstructor<TKey> | undefined
 
-  public lazyIndexes = new Map<number, LazyIndexWrapper<TKey>>()
-  public resolvedIndexes = new Map<number, BaseIndex<TKey>>()
-  public isIndexesResolved = false
+  public indexes = new Map<number, BaseIndex<TKey>>()
   public indexCounter = 0
 
   constructor() {}
 
   setDeps(deps: {
     state: CollectionStateManager<TOutput, TKey, TSchema, TInput>
     lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>
+    defaultIndexType?: IndexConstructor<TKey>
   }) {
     this.state = deps.state
     this.lifecycle = deps.lifecycle
+    this.defaultIndexType = deps.defaultIndexType
   }
 
   /**
    * Creates an index on a collection for faster queries.
    *
-   * Note: If no indexType is specified, this will use the registered default
-   * index type. If no default is registered, an error will be thrown.
-   *
    * @example
    * ```ts
    * // With explicit index type (recommended for tree-shaking)
-   * import { BTreeIndex } from '@tanstack/db/indexing'
-   * collection.createIndex((row) => row.userId, { indexType: BTreeIndex })
+   * import { BasicIndex } from '@tanstack/db/indexing'
+   * collection.createIndex((row) => row.userId, { indexType: BasicIndex })
    *
-   * // With registered default (requires registerDefaultIndexType)
+   * // With collection's default index type
    * collection.createIndex((row) => row.userId)
    * ```
    */
-  public createIndex<TResolver extends IndexResolver<TKey>>(
+  public createIndex<TIndexType extends IndexConstructor<TKey>>(
     indexCallback: (row: SingleRowRefProxy<TOutput>) => any,
-    config: IndexOptions<TResolver> = {}
-  ): IndexProxy<TKey> {
+    config: IndexOptions<TIndexType> = {}
+  ): BaseIndex<TKey> {
     this.lifecycle.validateCollectionUsable(`createIndex`)
 
     const indexId = ++this.indexCounter
     const singleRowRefProxy = createSingleRowRefProxy<TOutput>()
     const indexExpression = indexCallback(singleRowRefProxy)
     const expression = toExpression(indexExpression)
 
-    // Use provided index type, or fall back to registered default
-    let resolver: TResolver
-    if (config.indexType) {
-      resolver = config.indexType
-    } else {
-      const defaultType = getDefaultIndexType()
-      if (!defaultType) {
-        throw new Error(
-          `No index type specified and no default index type registered. ` +
-            `Either pass indexType in config, or register a default:\n` +
-            `  import { registerDefaultIndexType, BTreeIndex } from '@tanstack/db/indexing'\n` +
-            `  registerDefaultIndexType(BTreeIndex)`
-        )
-      }
-      resolver = defaultType as unknown as TResolver
+    // Use provided index type, or fall back to collection's default
+    const IndexType = config.indexType ?? this.defaultIndexType
+    if (!IndexType) {
+      throw new Error(
+        `No index type specified and no defaultIndexType set on collection. ` +
+          `Either pass indexType in config, or set defaultIndexType on the collection:\n` +
+          `  import { BasicIndex } from '@tanstack/db/indexing'\n` +
+          `  createCollection({ defaultIndexType: BasicIndex, ... })`
+      )
     }
 
-    // Create lazy wrapper
-    const lazyIndex = new LazyIndexWrapper<TKey>(
+    // Create index synchronously
+    const index = new IndexType(
       indexId,
       expression,
       config.name,
-      resolver,
-      config.options,
-      this.state.entries()
-    )
-
-    this.lazyIndexes.set(indexId, lazyIndex)
-
-    // For synchronous index constructors (like BTreeIndex), resolve immediately
-    if (typeof resolver === `function` && resolver.prototype) {
-      try {
-        const resolvedIndex = lazyIndex.getResolved()
-        this.resolvedIndexes.set(indexId, resolvedIndex)
-      } catch {
-        // Fallback to async resolution if sync resolution fails
-        this.resolveSingleIndex(indexId, lazyIndex).catch((error) => {
-          console.warn(`Failed to resolve index:`, error)
-        })
-      }
-    } else if (this.isIndexesResolved) {
-      // Async loader but indexes are already resolved - resolve this one
-      this.resolveSingleIndex(indexId, lazyIndex).catch((error) => {
-        console.warn(`Failed to resolve single index:`, error)
-      })
-    }
-
-    return new IndexProxy(indexId, lazyIndex)
-  }
-
-  /**
-   * Resolve all lazy indexes (called when collection first syncs)
-   */
-  public async resolveAllIndexes(): Promise<void> {
-    if (this.isIndexesResolved) return
-
-    const resolutionPromises = Array.from(this.lazyIndexes.entries()).map(
-      async ([indexId, lazyIndex]) => {
-        const resolvedIndex = await lazyIndex.resolve()
-
-        // Build index with current data
-        resolvedIndex.build(this.state.entries())
-
-        this.resolvedIndexes.set(indexId, resolvedIndex)
-        return { indexId, resolvedIndex }
-      }
+      config.options
     )
 
-    await Promise.all(resolutionPromises)
-    this.isIndexesResolved = true
-  }
+    // Build with current data
+    index.build(this.state.entries())
 
-  /**
-   * Resolve a single index immediately
-   */
-  private async resolveSingleIndex(
-    indexId: number,
-    lazyIndex: LazyIndexWrapper<TKey>
-  ): Promise<BaseIndex<TKey>> {
-    const resolvedIndex = await lazyIndex.resolve()
-    resolvedIndex.build(this.state.entries())
-    this.resolvedIndexes.set(indexId, resolvedIndex)
-    return resolvedIndex
-  }
+    this.indexes.set(indexId, index)
 
-  /**
-   * Get resolved indexes for query optimization
-   */
-  get indexes(): Map<number, BaseIndex<TKey>> {
-    return this.resolvedIndexes
+    return index
   }
 
   /**
    * Updates all indexes when the collection changes
    */
   public updateIndexes(changes: Array<ChangeMessage<TOutput, TKey>>): void {
-    for (const index of this.resolvedIndexes.values()) {
+    for (const index of this.indexes.values()) {
       for (const change of changes) {
         switch (change.type) {
           case `insert`:
@@ -181,11 +112,9 @@ export class CollectionIndexesManager<
   }
 
   /**
-   * Clean up the collection by stopping sync and clearing data
-   * This can be called manually or automatically by garbage collection
+   * Clean up indexes
    */
   public cleanup(): void {
-    this.lazyIndexes.clear()
-    this.resolvedIndexes.clear()
+    this.indexes.clear()
   }
 }

packages/db/src/collection/lifecycle.ts

@@ -106,17 +106,6 @@ export class CollectionLifecycleManager<
     const previousStatus = this.status
     this.status = newStatus
 
-    // Resolve indexes when collection becomes ready
-    if (newStatus === `ready` && !this.indexes.isIndexesResolved) {
-      // Resolve indexes asynchronously without blocking
-      this.indexes.resolveAllIndexes().catch((error) => {
-        console.warn(
-          `${this.config.id ? `[${this.config.id}] ` : ``}Failed to resolve indexes:`,
-          error
-        )
-      })
-    }
-
     // Emit event
     this.events.emitStatusChange(newStatus, previousStatus)
   }

packages/db/src/index.ts

@@ -17,22 +17,18 @@ export * from "./paced-mutations"
 export * from "./strategies/index.js"
 
 // Index system exports - types only from main entry
-// For BTreeIndex and other index implementations, import from '@tanstack/db/indexing'
+// For BasicIndex, BTreeIndex and other index implementations, import from '@tanstack/db/indexing'
 export type {
   IndexInterface,
   IndexConstructor,
-  IndexResolver,
   IndexStats,
   IndexOperation,
 } from "./indexes/base-index.js"
 export { BaseIndex } from "./indexes/base-index.js"
-export type { IndexProxy } from "./indexes/lazy-index.js"
 export { type IndexOptions } from "./indexes/index-options.js"
 
-// Index registry - allows checking if indexing is available
+// Dev mode utilities
 export {
-  registerDefaultIndexType,
-  isIndexingAvailable,
   configureIndexDevMode,
   isDevModeEnabled,
 } from "./indexes/index-registry.js"