@tanstack/db 0.5.33 → 0.6.0

package/src/collection/indexes.ts

@@ -1,16 +1,210 @@
-import { IndexProxy, LazyIndexWrapper } from '../indexes/lazy-index'
 import {
   createSingleRowRefProxy,
   toExpression,
 } from '../query/builder/ref-proxy'
-import { BTreeIndex } from '../indexes/btree-index'
+import { CollectionConfigurationError } from '../errors'
 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'
 import type { CollectionLifecycleManager } from './lifecycle'
 import type { CollectionStateManager } from './state'
+import type { BasicExpression } from '../query/ir'
+import type {
+  CollectionEventsManager,
+  CollectionIndexMetadata,
+  CollectionIndexResolverMetadata,
+  CollectionIndexSerializableValue,
+} from './events'
+
+const INDEX_SIGNATURE_VERSION = 1 as const
+
+function compareStringsCodePoint(left: string, right: string): number {
+  if (left === right) {
+    return 0
+  }
+
+  return left < right ? -1 : 1
+}
+
+function resolveResolverMetadata<TKey extends string | number>(
+  resolver: IndexConstructor<TKey>,
+): CollectionIndexResolverMetadata {
+  return {
+    kind: `constructor`,
+    ...(resolver.name ? { name: resolver.name } : {}),
+  }
+}
+
+function toSerializableIndexValue(
+  value: unknown,
+): CollectionIndexSerializableValue | undefined {
+  if (value == null) {
+    return value
+  }
+
+  switch (typeof value) {
+    case `string`:
+    case `boolean`:
+      return value
+    case `number`:
+      return Number.isFinite(value) ? value : null
+    case `bigint`:
+      return { __type: `bigint`, value: value.toString() }
+    case `function`:
+    case `symbol`:
+      // Function and symbol identity are process-local and not stable across runtimes.
+      // Dropping them keeps signatures deterministic; we may skip index reuse, which is acceptable.
+      return undefined
+    case `undefined`:
+      return undefined
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => toSerializableIndexValue(entry) ?? null)
+  }
+
+  if (value instanceof Date) {
+    return {
+      __type: `date`,
+      value: value.toISOString(),
+    }
+  }
+
+  if (value instanceof Set) {
+    const serializedValues = Array.from(value)
+      .map((entry) => toSerializableIndexValue(entry) ?? null)
+      .sort((a, b) =>
+        compareStringsCodePoint(
+          stableStringifyCollectionIndexValue(a),
+          stableStringifyCollectionIndexValue(b),
+        ),
+      )
+    return {
+      __type: `set`,
+      values: serializedValues,
+    }
+  }
+
+  if (value instanceof Map) {
+    const serializedEntries = Array.from(value.entries())
+      .map(([mapKey, mapValue]) => ({
+        key: toSerializableIndexValue(mapKey) ?? null,
+        value: toSerializableIndexValue(mapValue) ?? null,
+      }))
+      .sort((a, b) =>
+        compareStringsCodePoint(
+          stableStringifyCollectionIndexValue(a.key),
+          stableStringifyCollectionIndexValue(b.key),
+        ),
+      )
+
+    return {
+      __type: `map`,
+      entries: serializedEntries,
+    }
+  }
+
+  if (value instanceof RegExp) {
+    return {
+      __type: `regexp`,
+      value: value.toString(),
+    }
+  }
+
+  const serializedObject: Record<string, CollectionIndexSerializableValue> = {}
+  const entries = Object.entries(value as Record<string, unknown>).sort(
+    ([leftKey], [rightKey]) => compareStringsCodePoint(leftKey, rightKey),
+  )
+
+  for (const [key, entryValue] of entries) {
+    const serializedEntry = toSerializableIndexValue(entryValue)
+    if (serializedEntry !== undefined) {
+      serializedObject[key] = serializedEntry
+    }
+  }
+
+  return serializedObject
+}
+
+function stableStringifyCollectionIndexValue(
+  value: CollectionIndexSerializableValue,
+): string {
+  if (value === null) {
+    return `null`
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringifyCollectionIndexValue).join(`,`)}]`
+  }
+
+  if (typeof value !== `object`) {
+    return JSON.stringify(value)
+  }
+
+  const sortedKeys = Object.keys(value).sort((left, right) =>
+    compareStringsCodePoint(left, right),
+  )
+  const serializedEntries = sortedKeys.map(
+    (key) =>
+      `${JSON.stringify(key)}:${stableStringifyCollectionIndexValue(value[key]!)}`,
+  )
+  return `{${serializedEntries.join(`,`)}}`
+}
+
+function createCollectionIndexMetadata<TKey extends string | number>(
+  indexId: number,
+  expression: BasicExpression,
+  name: string | undefined,
+  resolver: IndexConstructor<TKey>,
+  options: unknown,
+): CollectionIndexMetadata {
+  const resolverMetadata = resolveResolverMetadata(resolver)
+  const serializedExpression = toSerializableIndexValue(expression) ?? null
+  const serializedOptions = toSerializableIndexValue(options)
+  const signatureInput = toSerializableIndexValue({
+    signatureVersion: INDEX_SIGNATURE_VERSION,
+    expression: serializedExpression,
+    options: serializedOptions ?? null,
+  })
+  const normalizedSignatureInput = signatureInput ?? null
+  const signature = stableStringifyCollectionIndexValue(
+    normalizedSignatureInput,
+  )
+
+  return {
+    signatureVersion: INDEX_SIGNATURE_VERSION,
+    signature,
+    indexId,
+    name,
+    expression,
+    resolver: resolverMetadata,
+    ...(serializedOptions === undefined ? {} : { options: serializedOptions }),
+  }
+}
+
+function cloneSerializableIndexValue(
+  value: CollectionIndexSerializableValue,
+): CollectionIndexSerializableValue {
+  if (value === null || typeof value !== `object`) {
+    return value
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneSerializableIndexValue(entry))
+  }
+
+  const cloned: Record<string, CollectionIndexSerializableValue> = {}
+  for (const [key, entryValue] of Object.entries(value)) {
+    cloned[key] = cloneSerializableIndexValue(entryValue)
+  }
+  return cloned
+}
+
+function cloneExpression(expression: BasicExpression): BasicExpression {
+  return JSON.parse(JSON.stringify(expression)) as BasicExpression
+}
 
 export class CollectionIndexesManager<
   TOutput extends object = Record<string, unknown>,
@@ -20,10 +214,11 @@ export class CollectionIndexesManager<
 > {
   private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>
   private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>
+  private defaultIndexType: IndexConstructor<TKey> | undefined
+  private events!: CollectionEventsManager
 
-  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 indexMetadata = new Map<number, CollectionIndexMetadata>()
   public indexCounter = 0
 
   constructor() {}
@@ -31,18 +226,32 @@ export class CollectionIndexesManager<
   setDeps(deps: {
     state: CollectionStateManager<TOutput, TKey, TSchema, TInput>
     lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>
+    defaultIndexType?: IndexConstructor<TKey>
+    events: CollectionEventsManager
   }) {
     this.state = deps.state
     this.lifecycle = deps.lifecycle
+    this.defaultIndexType = deps.defaultIndexType
+    this.events = deps.events
   }
 
   /**
    * Creates an index on a collection for faster queries.
+   *
+   * @example
+   * ```ts
+   * // With explicit index type (recommended for tree-shaking)
+   * import { BasicIndex } from '@tanstack/db'
+   * collection.createIndex((row) => row.userId, { indexType: BasicIndex })
+   *
+   * // With collection's default index type
+   * collection.createIndex((row) => row.userId)
+   * ```
    */
-  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> {
     this.lifecycle.validateCollectionUsable(`createIndex`)
 
     const indexId = ++this.indexCounter
@@ -50,97 +259,96 @@ export class CollectionIndexesManager<
     const indexExpression = indexCallback(singleRowRefProxy)
     const expression = toExpression(indexExpression)
 
-    // Default to BTreeIndex if no type specified
-    const resolver = config.indexType ?? (BTreeIndex 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 CollectionConfigurationError(
+        `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'\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)
+    // Build with current data
+    index.build(this.state.entries())
 
-    // For BTreeIndex, resolve immediately and synchronously
-    if ((resolver as unknown) === BTreeIndex) {
-      try {
-        const resolvedIndex = lazyIndex.getResolved()
-        this.resolvedIndexes.set(indexId, resolvedIndex)
-      } catch (error) {
-        console.warn(`Failed to resolve BTreeIndex:`, error)
-      }
-    } else if (typeof resolver === `function` && resolver.prototype) {
-      // Other synchronous constructors - resolve immediately
-      try {
-        const resolvedIndex = lazyIndex.getResolved()
-        this.resolvedIndexes.set(indexId, resolvedIndex)
-      } catch {
-        // Fallback to async resolution
-        this.resolveSingleIndex(indexId, lazyIndex).catch((error) => {
-          console.warn(`Failed to resolve single 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)
-      })
-    }
+    this.indexes.set(indexId, index)
 
-    return new IndexProxy(indexId, lazyIndex)
+    // Track metadata and emit event
+    const metadata = createCollectionIndexMetadata(
+      indexId,
+      expression,
+      config.name,
+      IndexType,
+      config.options,
+    )
+    this.indexMetadata.set(indexId, metadata)
+    this.events.emitIndexAdded(metadata)
+
+    return index
   }
 
   /**
-   * Resolve all lazy indexes (called when collection first syncs)
+   * Removes an index from this collection.
+   * Returns true when an index existed and was removed, false otherwise.
    */
-  public async resolveAllIndexes(): Promise<void> {
-    if (this.isIndexesResolved) return
+  public removeIndex(indexOrId: BaseIndex<TKey> | number): boolean {
+    this.lifecycle.validateCollectionUsable(`removeIndex`)
 
-    const resolutionPromises = Array.from(this.lazyIndexes.entries()).map(
-      async ([indexId, lazyIndex]) => {
-        const resolvedIndex = await lazyIndex.resolve()
+    const indexId = typeof indexOrId === `number` ? indexOrId : indexOrId.id
+    const index = this.indexes.get(indexId)
+    if (!index) {
+      return false
+    }
 
-        // Build index with current data
-        resolvedIndex.build(this.state.entries())
+    if (typeof indexOrId !== `number` && index !== indexOrId) {
+      // Passed a different index instance with the same id — do not remove.
+      return false
+    }
 
-        this.resolvedIndexes.set(indexId, resolvedIndex)
-        return { indexId, resolvedIndex }
-      },
-    )
+    this.indexes.delete(indexId)
 
-    await Promise.all(resolutionPromises)
-    this.isIndexesResolved = true
-  }
+    const metadata = this.indexMetadata.get(indexId)
+    this.indexMetadata.delete(indexId)
+    if (metadata) {
+      this.events.emitIndexRemoved(metadata)
+    }
 
-  /**
-   * 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
+    return true
   }
 
   /**
-   * Get resolved indexes for query optimization
+   * Returns a sorted snapshot of index metadata.
+   * This allows persisted wrappers to bootstrap from indexes that were created
+   * before they attached lifecycle listeners.
    */
-  get indexes(): Map<number, BaseIndex<TKey>> {
-    return this.resolvedIndexes
+  public getIndexMetadataSnapshot(): Array<CollectionIndexMetadata> {
+    return Array.from(this.indexMetadata.values())
+      .sort((left, right) => left.indexId - right.indexId)
+      .map((metadata) => ({
+        ...metadata,
+        expression: cloneExpression(metadata.expression),
+        resolver: { ...metadata.resolver },
+        ...(metadata.options === undefined
+          ? {}
+          : { options: cloneSerializableIndexValue(metadata.options) }),
+      }))
   }
 
   /**
    * 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`:
@@ -162,11 +370,10 @@ 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()
+    this.indexMetadata.clear()
   }
 }

package/src/collection/lifecycle.ts

@@ -7,6 +7,7 @@ import {
   safeCancelIdleCallback,
   safeRequestIdleCallback,
 } from '../utils/browser-polyfills'
+import { CleanupQueue } from './cleanup-queue'
 import type { IdleCallbackDeadline } from '../utils/browser-polyfills'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { CollectionConfig, CollectionStatus } from '../types'
@@ -34,7 +35,6 @@ export class CollectionLifecycleManager<
   public hasBeenReady = false
   public hasReceivedFirstCommit = false
   public onFirstReadyCallbacks: Array<() => void> = []
-  public gcTimeoutId: ReturnType<typeof setTimeout> | null = null
   private idleCallbackId: number | null = null
 
   /**
@@ -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)
   }
@@ -174,10 +163,6 @@ export class CollectionLifecycleManager<
    * Called when the collection becomes inactive (no subscribers)
    */
   public startGCTimer(): void {
-    if (this.gcTimeoutId) {
-      clearTimeout(this.gcTimeoutId)
-    }
-
     const gcTime = this.config.gcTime ?? 300000 // 5 minutes default
 
     // If gcTime is 0, negative, or non-finite (Infinity, -Infinity, NaN), GC is disabled.
@@ -187,12 +172,12 @@ export class CollectionLifecycleManager<
       return
     }
 
-    this.gcTimeoutId = setTimeout(() => {
+    CleanupQueue.getInstance().schedule(this, gcTime, () => {
       if (this.changes.activeSubscribersCount === 0) {
         // Schedule cleanup during idle time to avoid blocking the UI thread
         this.scheduleIdleCleanup()
       }
-    }, gcTime)
+    })
   }
 
   /**
@@ -200,10 +185,7 @@ export class CollectionLifecycleManager<
    * Called when the collection becomes active again
    */
   public cancelGCTimer(): void {
-    if (this.gcTimeoutId) {
-      clearTimeout(this.gcTimeoutId)
-      this.gcTimeoutId = null
-    }
+    CleanupQueue.getInstance().cancel(this)
     // Also cancel any pending idle cleanup
     if (this.idleCallbackId !== null) {
       safeCancelIdleCallback(this.idleCallbackId)
@@ -258,10 +240,7 @@ export class CollectionLifecycleManager<
       this.changes.cleanup()
       this.indexes.cleanup()
 
-      if (this.gcTimeoutId) {
-        clearTimeout(this.gcTimeoutId)
-        this.gcTimeoutId = null
-      }
+      CleanupQueue.getInstance().cancel(this)
 
       this.hasBeenReady = false
 

package/src/collection/mutations.ts

@@ -17,6 +17,7 @@ import {
   UndefinedKeyError,
   UpdateKeyNotFoundError,
 } from '../errors'
+import { DIRECT_TRANSACTION_METADATA_KEY } from './transaction-metadata.js'
 import type { Collection, CollectionImpl } from './index.js'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type {
@@ -153,6 +154,14 @@ export class CollectionMutationsManager<
     return `KEY::${this.id}/${key}`
   }
 
+  private markPendingLocalOrigins(
+    mutations: Array<PendingMutation<TOutput>>,
+  ): void {
+    for (const mutation of mutations) {
+      this.state.pendingLocalOrigins.add(mutation.key as TKey)
+    }
+  }
+
   /**
    * Inserts one or more items into the collection
    */
@@ -222,6 +231,9 @@ export class CollectionMutationsManager<
     } else {
       // Create a new transaction with a mutation function that calls the onInsert handler
       const directOpTransaction = createTransaction<TOutput>({
+        metadata: {
+          [DIRECT_TRANSACTION_METADATA_KEY]: true,
+        },
         mutationFn: async (params) => {
           // Call the onInsert handler with the transaction and collection
           return await this.config.onInsert!({
@@ -237,6 +249,7 @@ export class CollectionMutationsManager<
 
       // Apply mutations to the new transaction
       directOpTransaction.applyMutations(mutations)
+      this.markPendingLocalOrigins(mutations)
       // Errors still reject tx.isPersisted.promise; this catch only prevents global unhandled rejections
       directOpTransaction.commit().catch(() => undefined)
 
@@ -417,6 +430,9 @@ export class CollectionMutationsManager<
 
     // Create a new transaction with a mutation function that calls the onUpdate handler
     const directOpTransaction = createTransaction<TOutput>({
+      metadata: {
+        [DIRECT_TRANSACTION_METADATA_KEY]: true,
+      },
       mutationFn: async (params) => {
         // Call the onUpdate handler with the transaction and collection
         return this.config.onUpdate!({
@@ -432,6 +448,7 @@ export class CollectionMutationsManager<
 
     // Apply mutations to the new transaction
     directOpTransaction.applyMutations(mutations)
+    this.markPendingLocalOrigins(mutations)
     // Errors still hit tx.isPersisted.promise; avoid leaking an unhandled rejection from the fire-and-forget commit
     directOpTransaction.commit().catch(() => undefined)
 
@@ -519,6 +536,9 @@ export class CollectionMutationsManager<
     // Create a new transaction with a mutation function that calls the onDelete handler
     const directOpTransaction = createTransaction<TOutput>({
       autoCommit: true,
+      metadata: {
+        [DIRECT_TRANSACTION_METADATA_KEY]: true,
+      },
       mutationFn: async (params) => {
         // Call the onDelete handler with the transaction and collection
         return this.config.onDelete!({
@@ -534,6 +554,7 @@ export class CollectionMutationsManager<
 
     // Apply mutations to the new transaction
     directOpTransaction.applyMutations(mutations)
+    this.markPendingLocalOrigins(mutations)
     // Errors still reject tx.isPersisted.promise; silence the internal commit promise to prevent test noise
     directOpTransaction.commit().catch(() => undefined)