@tanstack/db 0.0.27 → 0.0.29

package/dist/esm/collection.d.ts

@@ -1,7 +1,12 @@
 import { SortedMap } from './SortedMap.js';
+import { OrderedIndex } from './indexes/ordered-index.js';
+import { IndexProxy } from './indexes/lazy-index.js';
 import { Transaction } from './transactions.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { ChangeListener, ChangeMessage, CollectionConfig, CollectionStatus, Fn, InsertConfig, OperationConfig, OptimisticChangeMessage, ResolveInsertInput, ResolveType, Transaction as TransactionType, UtilsRecord } from './types.js';
+import { SingleRowRefProxy } from './query/builder/ref-proxy.js';
+import { ChangeListener, ChangeMessage, CollectionConfig, CollectionStatus, CurrentStateAsChangesOptions, Fn, InsertConfig, OperationConfig, OptimisticChangeMessage, ResolveInsertInput, ResolveType, SubscribeChangesOptions, Transaction as TransactionType, UtilsRecord } from './types.js';
+import { IndexOptions } from './indexes/index-options.js';
+import { BaseIndex, IndexResolver } from './indexes/base-index.js';
 export declare const collectionsStore: Map<string, CollectionImpl<any, any, any, StandardSchemaV1<unknown, unknown>, any>>;
 interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
     committed: boolean;
@@ -93,20 +98,6 @@ export interface Collection<T extends object = Record<string, unknown>, TKey ext
 export declare function createCollection<TExplicit = unknown, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}, TSchema extends StandardSchemaV1 = StandardSchemaV1, TFallback extends object = Record<string, unknown>>(options: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey, TSchema, ResolveInsertInput<TExplicit, TSchema, TFallback>> & {
     utils?: TUtils;
 }): Collection<ResolveType<TExplicit, TSchema, TFallback>, TKey, TUtils, TSchema, ResolveInsertInput<TExplicit, TSchema, TFallback>>;
-/**
- * Custom error class for schema validation errors
- */
-export declare class SchemaValidationError extends Error {
-    type: `insert` | `update`;
-    issues: ReadonlyArray<{
-        message: string;
-        path?: ReadonlyArray<string | number | symbol>;
-    }>;
-    constructor(type: `insert` | `update`, issues: ReadonlyArray<{
-        message: string;
-        path?: ReadonlyArray<string | number | symbol>;
-    }>, message?: string);
-}
 export declare class CollectionImpl<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInsertInput extends object = T> {
     config: CollectionConfig<T, TKey, TSchema, TInsertInput>;
     transactions: SortedMap<string, Transaction<any>>;
@@ -116,6 +107,10 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
     optimisticUpserts: Map<TKey, T>;
     optimisticDeletes: Set<TKey>;
     private _size;
+    private lazyIndexes;
+    private resolvedIndexes;
+    private isIndexesResolved;
+    private indexCounter;
     private changeListeners;
     private changeKeyListeners;
     utils: Record<string, Fn>;
@@ -293,6 +288,56 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
     private ensureStandardSchema;
     getKeyFromItem(item: T): TKey;
     generateGlobalKey(key: any, item: any): string;
+    /**
+     * Creates an index on a collection for faster queries.
+     * Indexes significantly improve query performance by allowing binary search
+     * and 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
+     *
+     * @example
+     * // Create a default ordered index
+     * const ageIndex = collection.createIndex((row) => row.age)
+     *
+     * // Create a ordered index with custom options
+     * const ageIndex = collection.createIndex((row) => row.age, {
+     *   indexType: OrderedIndex,
+     *   options: { compareFn: customComparator },
+     *   name: 'age_btree'
+     * })
+     *
+     * // 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' }
+     * })
+     */
+    createIndex<TResolver extends IndexResolver<TKey> = typeof OrderedIndex>(indexCallback: (row: SingleRowRefProxy<T>) => any, config?: IndexOptions<TResolver>): IndexProxy<TKey>;
+    /**
+     * Resolve all lazy indexes (called when collection first syncs)
+     * @private
+     */
+    private resolveAllIndexes;
+    /**
+     * Resolve a single index immediately
+     * @private
+     */
+    private resolveSingleIndex;
+    /**
+     * Get resolved indexes for query optimization
+     */
+    get indexes(): Map<number, BaseIndex<TKey>>;
+    /**
+     * Updates all indexes when the collection changes
+     * @private
+     */
+    private updateIndexes;
     private deepEqual;
     private validateData;
     /**
@@ -445,13 +490,27 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
     toArrayWhenReady(): Promise<Array<T>>;
     /**
      * Returns the current state of the collection as an array of changes
+     * @param options - Options including optional where filter
      * @returns An array of changes
+     * @example
+     * // Get all items as changes
+     * const allChanges = collection.currentStateAsChanges()
+     *
+     * // Get only items matching a condition
+     * const activeChanges = collection.currentStateAsChanges({
+     *   where: (row) => row.status === 'active'
+     * })
+     *
+     * // Get only items using a pre-compiled expression
+     * const activeChanges = collection.currentStateAsChanges({
+     *   whereExpression: eq(row.status, 'active')
+     * })
      */
-    currentStateAsChanges(): Array<ChangeMessage<T>>;
+    currentStateAsChanges(options?: CurrentStateAsChangesOptions<T>): Array<ChangeMessage<T>>;
     /**
      * Subscribe to changes in the collection
      * @param callback - Function called when items change
-     * @param options.includeInitialState - If true, immediately calls callback with current data
+     * @param options - Subscription options including includeInitialState and where filter
      * @returns Unsubscribe function - Call this to stop listening for changes
      * @example
      * // Basic subscription
@@ -468,10 +527,26 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
      * const unsubscribe = collection.subscribeChanges((changes) => {
      *   updateUI(changes)
      * }, { includeInitialState: true })
+     *
+     * @example
+     * // Subscribe only to changes matching a condition
+     * const unsubscribe = collection.subscribeChanges((changes) => {
+     *   updateUI(changes)
+     * }, {
+     *   includeInitialState: true,
+     *   where: (row) => row.status === 'active'
+     * })
+     *
+     * @example
+     * // Subscribe using a pre-compiled expression
+     * const unsubscribe = collection.subscribeChanges((changes) => {
+     *   updateUI(changes)
+     * }, {
+     *   includeInitialState: true,
+     *   whereExpression: eq(row.status, 'active')
+     * })
      */
-    subscribeChanges(callback: (changes: Array<ChangeMessage<T>>) => void, { includeInitialState }?: {
-        includeInitialState?: boolean;
-    }): () => void;
+    subscribeChanges(callback: (changes: Array<ChangeMessage<T>>) => void, options?: SubscribeChangesOptions<T>): () => void;
     /**
      * Subscribe to changes for a specific key
      */