Method createIndex

packages/db/src/collection/indexes.ts:251–298

* 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

(
    indexCallback: (row: SingleRowRefProxy<TOutput>) => any,
    config: IndexOptions<TIndexType> = {},
  )

   * ```
   */
  public createIndex<TIndexType extends IndexConstructor<TKey>>(
    indexCallback: (row: SingleRowRefProxy<TOutput>) => any,
    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 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 index synchronously
    const index = new IndexType(
      indexId,
      expression,
      config.name,
      config.options,
    )

    // Build with current data
    index.build(this.state.entries())

    this.indexes.set(indexId, index)

    // 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
  }

  /**
   * Removes an index from this collection.