@tanstack/db 0.5.33 → 0.6.0

package/src/collection/events.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from '../event-emitter.js'
 import type { Collection } from './index.js'
 import type { CollectionStatus } from '../types.js'
+import type { BasicExpression } from '../query/ir.js'
 
 /**
  * Event emitted when the collection status changes
@@ -51,11 +52,57 @@ export interface CollectionTruncateEvent {
   collection: Collection<any, any, any, any, any>
 }
 
+export type CollectionIndexSerializableValue =
+  | string
+  | number
+  | boolean
+  | null
+  | Array<CollectionIndexSerializableValue>
+  | {
+      [key: string]: CollectionIndexSerializableValue
+    }
+
+export interface CollectionIndexResolverMetadata {
+  kind: `constructor` | `async`
+  name?: string
+}
+
+export interface CollectionIndexMetadata {
+  /**
+   * Version for the signature serialization contract.
+   */
+  signatureVersion: 1
+  /**
+   * Stable signature derived from expression + serializable options.
+   * Non-serializable option fields are intentionally omitted.
+   */
+  signature: string
+  indexId: number
+  name?: string
+  expression: BasicExpression
+  resolver: CollectionIndexResolverMetadata
+  options?: CollectionIndexSerializableValue
+}
+
+export interface CollectionIndexAddedEvent {
+  type: `index:added`
+  collection: Collection<any, any, any, any, any>
+  index: CollectionIndexMetadata
+}
+
+export interface CollectionIndexRemovedEvent {
+  type: `index:removed`
+  collection: Collection<any, any, any, any, any>
+  index: CollectionIndexMetadata
+}
+
 export type AllCollectionEvents = {
   'status:change': CollectionStatusChangeEvent
   'subscribers:change': CollectionSubscribersChangeEvent
   'loadingSubset:change': CollectionLoadingSubsetChangeEvent
   truncate: CollectionTruncateEvent
+  'index:added': CollectionIndexAddedEvent
+  'index:removed': CollectionIndexRemovedEvent
 } & {
   [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>
 }
@@ -66,6 +113,8 @@ export type CollectionEvent =
   | CollectionSubscribersChangeEvent
   | CollectionLoadingSubsetChangeEvent
   | CollectionTruncateEvent
+  | CollectionIndexAddedEvent
+  | CollectionIndexRemovedEvent
 
 export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (
   event: AllCollectionEvents[T],
@@ -126,6 +175,22 @@ export class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
     })
   }
 
+  emitIndexAdded(index: CollectionIndexMetadata) {
+    this.emit(`index:added`, {
+      type: `index:added`,
+      collection: this.collection,
+      index,
+    })
+  }
+
+  emitIndexRemoved(index: CollectionIndexMetadata) {
+    this.emit(`index:removed`, {
+      type: `index:removed`,
+      collection: this.collection,
+      index,
+    })
+  }
+
   cleanup() {
     this.clearListeners()
   }

package/src/collection/index.ts

@@ -1,4 +1,5 @@
 import {
+  CollectionConfigurationError,
   CollectionRequiresConfigError,
   CollectionRequiresSyncConfigError,
 } from '../errors'
@@ -12,8 +13,12 @@ import { CollectionIndexesManager } from './indexes'
 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 {
+  AllCollectionEvents,
+  CollectionEventHandler,
+  CollectionIndexMetadata,
+} from './events.js'
+import type { BaseIndex, IndexConstructor } from '../indexes/base-index.js'
 import type { IndexOptions } from '../indexes/index-options.js'
 import type {
   ChangeMessage,
@@ -35,8 +40,9 @@ 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'
+import type { WithVirtualProps } from '../virtual-props.js'
+
+export type { CollectionIndexMetadata } from './events.js'
 
 /**
  * Enhanced Collection interface that includes both data type T and utilities TUtils
@@ -294,6 +300,13 @@ export class CollectionImpl<
   // and for debugging
   public _state: CollectionStateManager<TOutput, TKey, TSchema, TInput>
 
+  /**
+   * When set, collection consumers should defer processing incoming data
+   * refreshes until this promise resolves. This prevents stale data from
+   * overwriting optimistic state while pending writes are being applied.
+   */
+  public deferDataRefresh: Promise<void> | null = null
+
   private comparisonOpts: StringCollationConfig
 
   /**
@@ -322,7 +335,16 @@ export class CollectionImpl<
     // Set default values for optional config properties
     this.config = {
       ...config,
-      autoIndex: config.autoIndex ?? `eager`,
+      autoIndex: config.autoIndex ?? `off`,
+    }
+
+    if (this.config.autoIndex === `eager` && !config.defaultIndexType) {
+      throw new CollectionConfigurationError(
+        `autoIndex: 'eager' requires defaultIndexType to be set. ` +
+          `Import an index type and set it:\n` +
+          `  import { BasicIndex } from '@tanstack/db'\n` +
+          `  createCollection({ defaultIndexType: BasicIndex, autoIndex: 'eager', ... })`,
+      )
     }
 
     this._changes = new CollectionChangesManager()
@@ -340,6 +362,7 @@ export class CollectionImpl<
       lifecycle: this._lifecycle,
       sync: this._sync,
       events: this._events,
+      state: this._state, // Required for enriching changes with virtual properties
     })
     this._events.setDeps({
       collection: this, // Required for adding to emitted events
@@ -347,6 +370,8 @@ export class CollectionImpl<
     this._indexes.setDeps({
       state: this._state,
       lifecycle: this._lifecycle,
+      defaultIndexType: config.defaultIndexType,
+      events: this._events,
     })
     this._lifecycle.setDeps({
       changes: this._changes,
@@ -451,8 +476,8 @@ export class CollectionImpl<
   /**
    * Get the current value for a key (virtual derived state)
    */
-  public get(key: TKey): TOutput | undefined {
-    return this._state.get(key)
+  public get(key: TKey): WithVirtualProps<TOutput, TKey> | undefined {
+    return this._state.getWithVirtualProps(key)
   }
 
   /**
@@ -479,40 +504,68 @@ export class CollectionImpl<
   /**
    * Get all values (virtual derived state)
    */
-  public *values(): IterableIterator<TOutput> {
-    yield* this._state.values()
+  public *values(): IterableIterator<WithVirtualProps<TOutput, TKey>> {
+    for (const key of this._state.keys()) {
+      const value = this.get(key)
+      if (value !== undefined) {
+        yield value
+      }
+    }
   }
 
   /**
    * Get all entries (virtual derived state)
    */
-  public *entries(): IterableIterator<[TKey, TOutput]> {
-    yield* this._state.entries()
+  public *entries(): IterableIterator<[TKey, WithVirtualProps<TOutput, TKey>]> {
+    for (const key of this._state.keys()) {
+      const value = this.get(key)
+      if (value !== undefined) {
+        yield [key, value]
+      }
+    }
   }
 
   /**
    * Get all entries (virtual derived state)
    */
-  public *[Symbol.iterator](): IterableIterator<[TKey, TOutput]> {
-    yield* this._state[Symbol.iterator]()
+  public *[Symbol.iterator](): IterableIterator<
+    [TKey, WithVirtualProps<TOutput, TKey>]
+  > {
+    yield* this.entries()
   }
 
   /**
    * Execute a callback for each entry in the collection
    */
   public forEach(
-    callbackfn: (value: TOutput, key: TKey, index: number) => void,
+    callbackfn: (
+      value: WithVirtualProps<TOutput, TKey>,
+      key: TKey,
+      index: number,
+    ) => void,
   ): void {
-    return this._state.forEach(callbackfn)
+    let index = 0
+    for (const [key, value] of this.entries()) {
+      callbackfn(value, key, index++)
+    }
   }
 
   /**
    * Create a new array with the results of calling a function for each entry in the collection
    */
   public map<U>(
-    callbackfn: (value: TOutput, key: TKey, index: number) => U,
+    callbackfn: (
+      value: WithVirtualProps<TOutput, TKey>,
+      key: TKey,
+      index: number,
+    ) => U,
   ): Array<U> {
-    return this._state.map(callbackfn)
+    const result: Array<U> = []
+    let index = 0
+    for (const [key, value] of this.entries()) {
+      result.push(callbackfn(value, key, index++))
+    }
+    return result
   }
 
   public getKeyFromItem(item: TOutput): TKey {
@@ -524,41 +577,51 @@ 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'
    *
-   * // 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)
   }
 
+  /**
+   * Removes an index created with createIndex.
+   * Returns true when an index existed and was removed.
+   *
+   * Best-effort semantics: removing an index guarantees it is detached from
+   * collection query planning. Existing index proxy references should be treated
+   * as invalid after removal.
+   */
+  public removeIndex(indexOrId: BaseIndex<TKey> | number): boolean {
+    return this._indexes.removeIndex(indexOrId)
+  }
+
+  /**
+   * Returns a snapshot of current index metadata sorted by indexId.
+   * Persistence wrappers can use this to bootstrap index state if indexes were
+   * created before event listeners were attached.
+   */
+  public getIndexMetadata(): Array<CollectionIndexMetadata> {
+    return this._indexes.getIndexMetadataSnapshot()
+  }
+
   /**
    * Get resolved indexes for query optimization
    */
@@ -755,7 +818,7 @@ export class CollectionImpl<
    * }
    */
   get state() {
-    const result = new Map<TKey, TOutput>()
+    const result = new Map<TKey, WithVirtualProps<TOutput, TKey>>()
     for (const [key, value] of this.entries()) {
       result.set(key, value)
     }
@@ -768,7 +831,7 @@ export class CollectionImpl<
    *
    * @returns Promise that resolves to a Map containing all items in the collection
    */
-  stateWhenReady(): Promise<Map<TKey, TOutput>> {
+  stateWhenReady(): Promise<Map<TKey, WithVirtualProps<TOutput, TKey>>> {
     // If we already have data or collection is ready, resolve immediately
     if (this.size > 0 || this.isReady()) {
       return Promise.resolve(this.state)
@@ -793,7 +856,7 @@ export class CollectionImpl<
    *
    * @returns Promise that resolves to an Array containing all items in the collection
    */
-  toArrayWhenReady(): Promise<Array<TOutput>> {
+  toArrayWhenReady(): Promise<Array<WithVirtualProps<TOutput, TKey>>> {
     // If we already have data or collection is ready, resolve immediately
     if (this.size > 0 || this.isReady()) {
       return Promise.resolve(this.toArray)
@@ -823,7 +886,7 @@ export class CollectionImpl<
    */
   public currentStateAsChanges(
     options: CurrentStateAsChangesOptions = {},
-  ): Array<ChangeMessage<TOutput>> | void {
+  ): Array<ChangeMessage<WithVirtualProps<TOutput, TKey>>> | void {
     return currentStateAsChanges(this, options)
   }
 
@@ -870,8 +933,10 @@ export class CollectionImpl<
    * })
    */
   public subscribeChanges(
-    callback: (changes: Array<ChangeMessage<TOutput>>) => void,
-    options: SubscribeChangesOptions<TOutput> = {},
+    callback: (
+      changes: Array<ChangeMessage<WithVirtualProps<TOutput, TKey>>>,
+    ) => void,
+    options: SubscribeChangesOptions<TOutput, TKey> = {},
   ): CollectionSubscription {
     return this._changes.subscribeChanges(callback, options)
   }