@tanstack/db 0.0.26 → 0.0.29

package/dist/esm/collection.js

@@ -1,6 +1,12 @@
 import { withArrayChangeTracking, withChangeTracking } from "./proxy.js";
-import { getActiveTransaction, createTransaction } from "./transactions.js";
 import { SortedMap } from "./SortedMap.js";
+import { createSingleRowRefProxy, toExpression } from "./query/builder/ref-proxy.js";
+import { OrderedIndex } from "./indexes/ordered-index.js";
+import { LazyIndexWrapper, IndexProxy } from "./indexes/lazy-index.js";
+import { ensureIndexForExpression } from "./indexes/auto-index.js";
+import { getActiveTransaction, createTransaction } from "./transactions.js";
+import { MissingInsertHandlerError, DuplicateKeyError, MissingDeleteHandlerError, NoKeysPassedToDeleteError, DeleteKeyNotFoundError, CollectionRequiresConfigError, CollectionRequiresSyncConfigError, CollectionInErrorStateError, InvalidCollectionStatusTransitionError, NoPendingSyncTransactionCommitError, SyncTransactionAlreadyCommittedError, NoPendingSyncTransactionWriteError, SyncTransactionAlreadyCommittedWriteError, DuplicateKeySyncError, CollectionIsInErrorStateError, SyncCleanupError, NegativeActiveSubscribersError, InvalidSchemaError, UndefinedKeyError, SchemaMustBeSynchronousError, SchemaValidationError, MissingUpdateArgumentError, MissingUpdateHandlerError, NoKeysPassedToUpdateError, UpdateKeyNotFoundError, KeyUpdateNotAllowedError } from "./errors.js";
+import { currentStateAsChanges, createFilteredCallback } from "./change-events.js";
 const collectionsStore = /* @__PURE__ */ new Map();
 function createCollection(options) {
   const collection = new CollectionImpl(options);
@@ -11,16 +17,6 @@ function createCollection(options) {
   }
   return collection;
 }
-class SchemaValidationError extends Error {
-  constructor(type, issues, message) {
-    const defaultMessage = `${type === `insert` ? `Insert` : `Update`} validation failed: ${issues.map((issue) => `
-- ${issue.message} - path: ${issue.path}`).join(``)}`;
-    super(message || defaultMessage);
-    this.name = `SchemaValidationError`;
-    this.type = type;
-    this.issues = issues;
-  }
-}
 class CollectionImpl {
   /**
    * Creates a new Collection instance
@@ -34,6 +30,10 @@ class CollectionImpl {
     this.optimisticUpserts = /* @__PURE__ */ new Map();
     this.optimisticDeletes = /* @__PURE__ */ new Set();
     this._size = 0;
+    this.lazyIndexes = /* @__PURE__ */ new Map();
+    this.resolvedIndexes = /* @__PURE__ */ new Map();
+    this.isIndexesResolved = false;
+    this.indexCounter = 0;
     this.changeListeners = /* @__PURE__ */ new Set();
     this.changeKeyListeners = /* @__PURE__ */ new Map();
     this.utils = {};
@@ -192,6 +192,9 @@ class CollectionImpl {
           }
         }
         this._size = this.calculateSize();
+        if (events.length > 0) {
+          this.updateIndexes(events);
+        }
         this.emitEvents(events, true);
         this.pendingSyncedTransactions = [];
         this.preSyncVisibleState.clear();
@@ -210,9 +213,7 @@ class CollectionImpl {
       this.validateCollectionUsable(`insert`);
       const ambientTransaction = getActiveTransaction();
       if (!ambientTransaction && !this.config.onInsert) {
-        throw new Error(
-          `Collection.insert called directly (not within an explicit transaction) but no 'onInsert' handler is configured.`
-        );
+        throw new MissingInsertHandlerError();
       }
       const items = Array.isArray(data) ? data : [data];
       const mutations = [];
@@ -221,7 +222,7 @@ class CollectionImpl {
         const validatedData = this.validateData(item, `insert`);
         const key = this.getKeyFromItem(validatedData);
         if (this.has(key)) {
-          throw `Cannot insert document with ID "${key}" because it already exists in the collection`;
+          throw new DuplicateKeyError(key);
         }
         const globalKey = this.generateGlobalKey(key, item);
         const mutation = {
@@ -274,20 +275,16 @@ class CollectionImpl {
       this.validateCollectionUsable(`delete`);
       const ambientTransaction = getActiveTransaction();
       if (!ambientTransaction && !this.config.onDelete) {
-        throw new Error(
-          `Collection.delete called directly (not within an explicit transaction) but no 'onDelete' handler is configured.`
-        );
+        throw new MissingDeleteHandlerError();
       }
       if (Array.isArray(keys) && keys.length === 0) {
-        throw new Error(`No keys were passed to delete`);
+        throw new NoKeysPassedToDeleteError();
       }
       const keysArray = Array.isArray(keys) ? keys : [keys];
       const mutations = [];
       for (const key of keysArray) {
         if (!this.has(key)) {
-          throw new Error(
-            `Collection.delete was called with key '${key}' but there is no item in the collection with this key`
-          );
+          throw new DeleteKeyNotFoundError(key);
         }
         const globalKey = this.generateGlobalKey(key, this.get(key));
         const mutation = {
@@ -329,7 +326,7 @@ class CollectionImpl {
       return directOpTransaction;
     };
     if (!config) {
-      throw new Error(`Collection requires a config`);
+      throw new CollectionRequiresConfigError();
     }
     if (config.id) {
       this.id = config.id;
@@ -337,12 +334,15 @@ class CollectionImpl {
       this.id = crypto.randomUUID();
     }
     if (!config.sync) {
-      throw new Error(`Collection requires a sync config`);
+      throw new CollectionRequiresSyncConfigError();
     }
     this.transactions = new SortedMap(
       (a, b) => a.compareCreatedAt(b)
     );
-    this.config = config;
+    this.config = {
+      ...config,
+      autoIndex: config.autoIndex ?? `eager`
+    };
     collectionsStore.set(this.id, this);
     if (this.config.compare) {
       this.syncedData = new SortedMap(this.config.compare);
@@ -418,13 +418,10 @@ class CollectionImpl {
   validateCollectionUsable(operation) {
     switch (this._status) {
       case `error`:
-        throw new Error(
-          `Cannot perform ${operation} on collection "${this.id}" - collection is in error state. Try calling cleanup() and restarting the collection.`
-        );
+        throw new CollectionInErrorStateError(operation, this.id);
       case `cleaned-up`:
-        throw new Error(
-          `Cannot perform ${operation} on collection "${this.id}" - collection has been cleaned up. The collection will automatically restart on next access.`
-        );
+        this.startSync();
+        break;
     }
   }
   /**
@@ -444,9 +441,7 @@ class CollectionImpl {
       "cleaned-up": [`loading`, `error`]
     };
     if (!validTransitions[from].includes(to)) {
-      throw new Error(
-        `Invalid collection status transition from "${from}" to "${to}" for collection "${this.id}"`
-      );
+      throw new InvalidCollectionStatusTransitionError(from, to, this.id);
     }
   }
   /**
@@ -456,6 +451,11 @@ class CollectionImpl {
   setStatus(newStatus) {
     this.validateStatusTransition(this._status, newStatus);
     this._status = newStatus;
+    if (newStatus === `ready` && !this.isIndexesResolved) {
+      this.resolveAllIndexes().catch((error) => {
+        console.warn(`Failed to resolve indexes:`, error);
+      });
+    }
   }
   /**
    * Start sync immediately - internal method for compiled queries
@@ -485,21 +485,17 @@ class CollectionImpl {
         write: (messageWithoutKey) => {
           const pendingTransaction = this.pendingSyncedTransactions[this.pendingSyncedTransactions.length - 1];
           if (!pendingTransaction) {
-            throw new Error(`No pending sync transaction to write to`);
+            throw new NoPendingSyncTransactionWriteError();
           }
           if (pendingTransaction.committed) {
-            throw new Error(
-              `The pending sync transaction is already committed, you can't still write to it.`
-            );
+            throw new SyncTransactionAlreadyCommittedWriteError();
           }
           const key = this.getKeyFromItem(messageWithoutKey.value);
           if (messageWithoutKey.type === `insert`) {
             if (this.syncedData.has(key) && !pendingTransaction.operations.some(
               (op) => op.key === key && op.type === `delete`
             )) {
-              throw new Error(
-                `Cannot insert document with key "${key}" from sync because it already exists in the collection "${this.id}"`
-              );
+              throw new DuplicateKeySyncError(key, this.id);
             }
           }
           const message = {
@@ -511,12 +507,10 @@ class CollectionImpl {
         commit: () => {
           const pendingTransaction = this.pendingSyncedTransactions[this.pendingSyncedTransactions.length - 1];
           if (!pendingTransaction) {
-            throw new Error(`No pending sync transaction to commit`);
+            throw new NoPendingSyncTransactionCommitError();
           }
           if (pendingTransaction.committed) {
-            throw new Error(
-              `The pending sync transaction is already committed, you can't commit it again.`
-            );
+            throw new SyncTransactionAlreadyCommittedError();
           }
           pendingTransaction.committed = true;
           if (this._status === `loading`) {
@@ -548,7 +542,7 @@ class CollectionImpl {
         return;
       }
       if (this._status === `error`) {
-        reject(new Error(`Collection is in error state`));
+        reject(new CollectionIsInErrorStateError());
         return;
       }
       this.onFirstReady(() => {
@@ -582,16 +576,12 @@ class CollectionImpl {
     } catch (error) {
       queueMicrotask(() => {
         if (error instanceof Error) {
-          const wrappedError = new Error(
-            `Collection "${this.id}" sync cleanup function threw an error: ${error.message}`
-          );
+          const wrappedError = new SyncCleanupError(this.id, error);
           wrappedError.cause = error;
           wrappedError.stack = error.stack;
           throw wrappedError;
         } else {
-          throw new Error(
-            `Collection "${this.id}" sync cleanup function threw an error: ${String(error)}`
-          );
+          throw new SyncCleanupError(this.id, error);
         }
       });
     }
@@ -655,9 +645,7 @@ class CollectionImpl {
       this.activeSubscribersCount = 0;
       this.startGCTimer();
     } else if (this.activeSubscribersCount < 0) {
-      throw new Error(
-        `Active subscribers count is negative - this should never happen`
-      );
+      throw new NegativeActiveSubscribersError();
     }
   }
   /**
@@ -731,8 +719,14 @@ class CollectionImpl {
         }
         return true;
       });
+      if (filteredEvents.length > 0) {
+        this.updateIndexes(filteredEvents);
+      }
       this.emitEvents(filteredEvents);
     } else {
+      if (filteredEventsBySyncStatus.length > 0) {
+        this.updateIndexes(filteredEventsBySyncStatus);
+      }
       this.emitEvents(filteredEventsBySyncStatus);
     }
   }
@@ -926,24 +920,147 @@ class CollectionImpl {
     return result;
   }
   ensureStandardSchema(schema) {
-    if (schema && typeof schema === `object` && `~standard` in schema) {
+    if (schema && `~standard` in schema) {
       return schema;
     }
-    throw new Error(
-      `Schema must either implement the standard-schema interface or be a Zod schema`
-    );
+    throw new InvalidSchemaError();
   }
   getKeyFromItem(item) {
     return this.config.getKey(item);
   }
   generateGlobalKey(key, item) {
     if (typeof key === `undefined`) {
-      throw new Error(
-        `An object was created without a defined key: ${JSON.stringify(item)}`
-      );
+      throw new UndefinedKeyError(item);
     }
     return `KEY::${this.id}/${key}`;
   }
+  /**
+   * 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(indexCallback, config = {}) {
+    this.validateCollectionUsable(`createIndex`);
+    const indexId = ++this.indexCounter;
+    const singleRowRefProxy = createSingleRowRefProxy();
+    const indexExpression = indexCallback(singleRowRefProxy);
+    const expression = toExpression(indexExpression);
+    const resolver = config.indexType ?? OrderedIndex;
+    const lazyIndex = new LazyIndexWrapper(
+      indexId,
+      expression,
+      config.name,
+      resolver,
+      config.options,
+      this.entries()
+    );
+    this.lazyIndexes.set(indexId, lazyIndex);
+    if (resolver === OrderedIndex) {
+      try {
+        const resolvedIndex = lazyIndex.getResolved();
+        this.resolvedIndexes.set(indexId, resolvedIndex);
+      } catch (error) {
+        console.warn(`Failed to resolve OrderedIndex:`, error);
+      }
+    } else if (typeof resolver === `function` && resolver.prototype) {
+      try {
+        const resolvedIndex = lazyIndex.getResolved();
+        this.resolvedIndexes.set(indexId, resolvedIndex);
+      } catch {
+        this.resolveSingleIndex(indexId, lazyIndex).catch((error) => {
+          console.warn(`Failed to resolve single index:`, error);
+        });
+      }
+    } else if (this.isIndexesResolved) {
+      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)
+   * @private
+   */
+  async resolveAllIndexes() {
+    if (this.isIndexesResolved) return;
+    const resolutionPromises = Array.from(this.lazyIndexes.entries()).map(
+      async ([indexId, lazyIndex]) => {
+        const resolvedIndex = await lazyIndex.resolve();
+        resolvedIndex.build(this.entries());
+        this.resolvedIndexes.set(indexId, resolvedIndex);
+        return { indexId, resolvedIndex };
+      }
+    );
+    await Promise.all(resolutionPromises);
+    this.isIndexesResolved = true;
+  }
+  /**
+   * Resolve a single index immediately
+   * @private
+   */
+  async resolveSingleIndex(indexId, lazyIndex) {
+    const resolvedIndex = await lazyIndex.resolve();
+    resolvedIndex.build(this.entries());
+    this.resolvedIndexes.set(indexId, resolvedIndex);
+    return resolvedIndex;
+  }
+  /**
+   * Get resolved indexes for query optimization
+   */
+  get indexes() {
+    return this.resolvedIndexes;
+  }
+  /**
+   * Updates all indexes when the collection changes
+   * @private
+   */
+  updateIndexes(changes) {
+    for (const index of this.resolvedIndexes.values()) {
+      for (const change of changes) {
+        switch (change.type) {
+          case `insert`:
+            index.add(change.key, change.value);
+            break;
+          case `update`:
+            if (change.previousValue) {
+              index.update(change.key, change.previousValue, change.value);
+            } else {
+              index.add(change.key, change.value);
+            }
+            break;
+          case `delete`:
+            index.remove(change.key, change.value);
+            break;
+        }
+      }
+    }
+  }
   deepEqual(a, b) {
     if (a === b) return true;
     if (a == null || b == null) return false;
@@ -971,7 +1088,7 @@ class CollectionImpl {
         const mergedData = Object.assign({}, existingData, data);
         const result2 = standardSchema[`~standard`].validate(mergedData);
         if (result2 instanceof Promise) {
-          throw new TypeError(`Schema validation must be synchronous`);
+          throw new SchemaMustBeSynchronousError();
         }
         if (`issues` in result2 && result2.issues) {
           const typedIssues = result2.issues.map((issue) => {
@@ -988,7 +1105,7 @@ class CollectionImpl {
     }
     const result = standardSchema[`~standard`].validate(data);
     if (result instanceof Promise) {
-      throw new TypeError(`Schema validation must be synchronous`);
+      throw new SchemaMustBeSynchronousError();
     }
     if (`issues` in result && result.issues) {
       const typedIssues = result.issues.map((issue) => {
@@ -1004,28 +1121,24 @@ class CollectionImpl {
   }
   update(keys, configOrCallback, maybeCallback) {
     if (typeof keys === `undefined`) {
-      throw new Error(`The first argument to update is missing`);
+      throw new MissingUpdateArgumentError();
     }
     this.validateCollectionUsable(`update`);
     const ambientTransaction = getActiveTransaction();
     if (!ambientTransaction && !this.config.onUpdate) {
-      throw new Error(
-        `Collection.update called directly (not within an explicit transaction) but no 'onUpdate' handler is configured.`
-      );
+      throw new MissingUpdateHandlerError();
     }
     const isArray = Array.isArray(keys);
     const keysArray = isArray ? keys : [keys];
     if (isArray && keysArray.length === 0) {
-      throw new Error(`No keys were passed to update`);
+      throw new NoKeysPassedToUpdateError();
     }
     const callback = typeof configOrCallback === `function` ? configOrCallback : maybeCallback;
     const config = typeof configOrCallback === `function` ? {} : configOrCallback;
     const currentObjects = keysArray.map((key) => {
       const item = this.get(key);
       if (!item) {
-        throw new Error(
-          `The key "${key}" was passed to update but an object for this key was not found in the collection`
-        );
+        throw new UpdateKeyNotFoundError(key);
       }
       return item;
     });
@@ -1061,9 +1174,7 @@ class CollectionImpl {
       const originalItemId = this.getKeyFromItem(originalItem);
       const modifiedItemId = this.getKeyFromItem(modifiedItem);
       if (originalItemId !== modifiedItemId) {
-        throw new Error(
-          `Updating the key of an item is not allowed. Original key: "${originalItemId}", Attempted new key: "${modifiedItemId}". Please delete the old item and create a new one if a key change is necessary.`
-        );
+        throw new KeyUpdateNotAllowedError(originalItemId, modifiedItemId);
       }
       const globalKey = this.generateGlobalKey(modifiedItemId, modifiedItem);
       return {
@@ -1175,19 +1286,29 @@ class CollectionImpl {
   }
   /**
    * 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() {
-    return Array.from(this.entries()).map(([key, value]) => ({
-      type: `insert`,
-      key,
-      value
-    }));
+  currentStateAsChanges(options = {}) {
+    return currentStateAsChanges(this, options);
   }
   /**
    * 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
@@ -1204,15 +1325,41 @@ class CollectionImpl {
    * 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, { includeInitialState = false } = {}) {
+  subscribeChanges(callback, options = {}) {
     this.addSubscriber();
-    if (includeInitialState) {
-      callback(this.currentStateAsChanges());
+    if (options.whereExpression) {
+      ensureIndexForExpression(options.whereExpression, this);
+    }
+    const filteredCallback = options.where || options.whereExpression ? createFilteredCallback(callback, options) : callback;
+    if (options.includeInitialState) {
+      const initialChanges = this.currentStateAsChanges({
+        where: options.where,
+        whereExpression: options.whereExpression
+      });
+      filteredCallback(initialChanges);
     }
-    this.changeListeners.add(callback);
+    this.changeListeners.add(filteredCallback);
     return () => {
-      this.changeListeners.delete(callback);
+      this.changeListeners.delete(filteredCallback);
       this.removeSubscriber();
     };
   }
@@ -1280,7 +1427,6 @@ class CollectionImpl {
 }
 export {
   CollectionImpl,
-  SchemaValidationError,
   collectionsStore,
   createCollection
 };