@tanstack/db 0.5.3 → 0.5.5

package/README.md

@@ -1,8 +1,8 @@
 # @tanstack/db
 
-**A reactive client store for building super fast apps on sync**
+**The reactive client store for your API**
 
-TanStack DB extends TanStack Query with collections, live queries and optimistic mutations that keep your UI reactive, consistent and blazing fast 🔥
+TanStack DB solves the problems of building fast, modern apps. It extends TanStack Query with collections, live queries and optimistic mutations that keep your UI reactive, consistent and blazing fast 🔥
 
 <p>
   <a href="https://x.com/intent/post?text=TanStack%20DB&url=https://tanstack.com/db">
@@ -21,14 +21,14 @@ TanStack DB extends TanStack Query with collections, live queries and optimistic
 
 ## 💥 Visit the [TanStack/db](https://github.com/TanStack/db) repo for docs and details!
 
-- 🔥 **blazing fast query engine**<br />
-  for sub-millisecond live queries &mdash; even for complex queries with joins and aggregates
-- 🎯 **fine-grained reactivity**<br />
-  to minimize component re-rendering
-- 💪 **robust transaction primitives**<br />
-  for easy optimistic mutations with sync and lifecycle support
-- 🌟 **normalized data**<br />
-  to keep your backend simple
+- 🚀 **Avoid endpoint sprawl**<br />
+  Load data into normalized collections instead of building custom endpoints for every view
+- 🔥 **Blazing fast queries**<br />
+  Sub-millisecond live queries with joins & aggregates—your app stays fast no matter how much data you load
+- ⚡ **Instant interactions**<br />
+  Take the network off the interaction path with optimistic writes that feel instantaneous
+- 🎯 **Fine-grained reactivity**<br />
+  Minimize component re-rendering with precise updates
 
 ---
 

package/dist/cjs/collection/subscription.cjs

@@ -13,6 +13,7 @@ class CollectionSubscription extends eventEmitter.EventEmitter {
     this.options = options;
     this.loadedInitialState = false;
     this.snapshotSent = false;
+    this.loadedSubsets = [];
     this.sentKeys = /* @__PURE__ */ new Set();
     this._status = `ready`;
     this.pendingLoadSubsetPromises = /* @__PURE__ */ new Set();
@@ -112,10 +113,12 @@ class CollectionSubscription extends eventEmitter.EventEmitter {
     } else {
       this.loadedInitialState = true;
     }
-    const syncResult = this.collection._sync.loadSubset({
+    const loadOptions = {
       where: stateOpts.where,
       subscription: this
-    });
+    };
+    const syncResult = this.collection._sync.loadSubset(loadOptions);
+    this.loadedSubsets.push(loadOptions);
     const trackLoadSubsetPromise = opts?.trackLoadSubsetPromise ?? true;
     if (trackLoadSubsetPromise) {
       this.trackLoadSubsetPromise(syncResult);
@@ -210,20 +213,24 @@ class CollectionSubscription extends eventEmitter.EventEmitter {
       const valueFilter = operator(expression, new ir.Value(minValue));
       whereWithValueFilter = where ? functions.and(where, valueFilter) : valueFilter;
     }
-    const syncResult = this.collection._sync.loadSubset({
+    const loadOptions1 = {
       where: whereWithValueFilter,
       limit,
       orderBy,
       subscription: this
-    });
+    };
+    const syncResult = this.collection._sync.loadSubset(loadOptions1);
+    this.loadedSubsets.push(loadOptions1);
     const promises = [];
     if (typeof minValue !== `undefined`) {
       const { expression } = orderBy[0];
       const exactValueFilter = functions.eq(expression, new ir.Value(minValue));
-      const equalValueResult = this.collection._sync.loadSubset({
+      const loadOptions2 = {
         where: exactValueFilter,
         subscription: this
-      });
+      };
+      const equalValueResult = this.collection._sync.loadSubset(loadOptions2);
+      this.loadedSubsets.push(loadOptions2);
       if (equalValueResult instanceof Promise) {
         promises.push(equalValueResult);
       }
@@ -274,6 +281,10 @@ class CollectionSubscription extends eventEmitter.EventEmitter {
     }
   }
   unsubscribe() {
+    for (const options of this.loadedSubsets) {
+      this.collection._sync.unloadSubset(options);
+    }
+    this.loadedSubsets = [];
     this.emitInner(`unsubscribed`, {
       type: `unsubscribed`,
       subscription: this

package/dist/cjs/collection/subscription.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"subscription.cjs","sources":["../../../src/collection/subscription.ts"],"sourcesContent":["import { ensureIndexForExpression } from \"../indexes/auto-index.js\"\nimport { and, eq, gt, lt } from \"../query/builder/functions.js\"\nimport { Value } from \"../query/ir.js\"\nimport { EventEmitter } from \"../event-emitter.js\"\nimport {\n  createFilterFunctionFromExpression,\n  createFilteredCallback,\n} from \"./change-events.js\"\nimport type { BasicExpression, OrderBy } from \"../query/ir.js\"\nimport type { IndexInterface } from \"../indexes/base-index.js\"\nimport type {\n  ChangeMessage,\n  Subscription,\n  SubscriptionEvents,\n  SubscriptionStatus,\n  SubscriptionUnsubscribedEvent,\n} from \"../types.js\"\nimport type { CollectionImpl } from \"./index.js\"\n\ntype RequestSnapshotOptions = {\n  where?: BasicExpression<boolean>\n  optimizedOnly?: boolean\n  trackLoadSubsetPromise?: boolean\n}\n\ntype RequestLimitedSnapshotOptions = {\n  orderBy: OrderBy\n  limit: number\n  minValue?: any\n}\n\ntype CollectionSubscriptionOptions = {\n  includeInitialState?: boolean\n  /** Pre-compiled expression for filtering changes */\n  whereExpression?: BasicExpression<boolean>\n  /** Callback to call when the subscription is unsubscribed */\n  onUnsubscribe?: (event: SubscriptionUnsubscribedEvent) => void\n}\n\nexport class CollectionSubscription\n  extends EventEmitter<SubscriptionEvents>\n  implements Subscription\n{\n  private loadedInitialState = false\n\n  // Flag to indicate that we have sent at least 1 snapshot.\n  // While `snapshotSent` is false we filter out all changes from subscription to the collection.\n  private snapshotSent = false\n\n  // Keep track of the keys we've sent (needed for join and orderBy optimizations)\n  private sentKeys = new Set<string | number>()\n\n  private filteredCallback: (changes: Array<ChangeMessage<any, any>>) => void\n\n  private orderByIndex: IndexInterface<string | number> | undefined\n\n  // Status tracking\n  private _status: SubscriptionStatus = `ready`\n  private pendingLoadSubsetPromises: Set<Promise<void>> = new Set()\n\n  public get status(): SubscriptionStatus {\n    return this._status\n  }\n\n  constructor(\n    private collection: CollectionImpl<any, any, any, any, any>,\n    private callback: (changes: Array<ChangeMessage<any, any>>) => void,\n    private options: CollectionSubscriptionOptions\n  ) {\n    super()\n    if (options.onUnsubscribe) {\n      this.on(`unsubscribed`, (event) => options.onUnsubscribe!(event))\n    }\n\n    // Auto-index for where expressions if enabled\n    if (options.whereExpression) {\n      ensureIndexForExpression(options.whereExpression, this.collection)\n    }\n\n    const callbackWithSentKeysTracking = (\n      changes: Array<ChangeMessage<any, any>>\n    ) => {\n      callback(changes)\n      this.trackSentKeys(changes)\n    }\n\n    this.callback = callbackWithSentKeysTracking\n\n    // Create a filtered callback if where clause is provided\n    this.filteredCallback = options.whereExpression\n      ? createFilteredCallback(this.callback, options)\n      : this.callback\n  }\n\n  setOrderByIndex(index: IndexInterface<any>) {\n    this.orderByIndex = index\n  }\n\n  /**\n   * Set subscription status and emit events if changed\n   */\n  private setStatus(newStatus: SubscriptionStatus) {\n    if (this._status === newStatus) {\n      return // No change\n    }\n\n    const previousStatus = this._status\n    this._status = newStatus\n\n    // Emit status:change event\n    this.emitInner(`status:change`, {\n      type: `status:change`,\n      subscription: this,\n      previousStatus,\n      status: newStatus,\n    })\n\n    // Emit specific status event\n    const eventKey: `status:${SubscriptionStatus}` = `status:${newStatus}`\n    this.emitInner(eventKey, {\n      type: eventKey,\n      subscription: this,\n      previousStatus,\n      status: newStatus,\n    } as SubscriptionEvents[typeof eventKey])\n  }\n\n  /**\n   * Track a loadSubset promise and manage loading status\n   */\n  private trackLoadSubsetPromise(syncResult: Promise<void> | true) {\n    // Track the promise if it's actually a promise (async work)\n    if (syncResult instanceof Promise) {\n      this.pendingLoadSubsetPromises.add(syncResult)\n      this.setStatus(`loadingSubset`)\n\n      syncResult.finally(() => {\n        this.pendingLoadSubsetPromises.delete(syncResult)\n        if (this.pendingLoadSubsetPromises.size === 0) {\n          this.setStatus(`ready`)\n        }\n      })\n    }\n  }\n\n  hasLoadedInitialState() {\n    return this.loadedInitialState\n  }\n\n  hasSentAtLeastOneSnapshot() {\n    return this.snapshotSent\n  }\n\n  emitEvents(changes: Array<ChangeMessage<any, any>>) {\n    const newChanges = this.filterAndFlipChanges(changes)\n    this.filteredCallback(newChanges)\n  }\n\n  /**\n   * Sends the snapshot to the callback.\n   * Returns a boolean indicating if it succeeded.\n   * It can only fail if there is no index to fulfill the request\n   * and the optimizedOnly option is set to true,\n   * or, the entire state was already loaded.\n   */\n  requestSnapshot(opts?: RequestSnapshotOptions): boolean {\n    if (this.loadedInitialState) {\n      // Subscription was deoptimized so we already sent the entire initial state\n      return false\n    }\n\n    const stateOpts: RequestSnapshotOptions = {\n      where: this.options.whereExpression,\n      optimizedOnly: opts?.optimizedOnly ?? false,\n    }\n\n    if (opts) {\n      if (`where` in opts) {\n        const snapshotWhereExp = opts.where\n        if (stateOpts.where) {\n          // Combine the two where expressions\n          const subWhereExp = stateOpts.where\n          const combinedWhereExp = and(subWhereExp, snapshotWhereExp)\n          stateOpts.where = combinedWhereExp\n        } else {\n          stateOpts.where = snapshotWhereExp\n        }\n      }\n    } else {\n      // No options provided so it's loading the entire initial state\n      this.loadedInitialState = true\n    }\n\n    // Request the sync layer to load more data\n    // don't await it, we will load the data into the collection when it comes in\n    const syncResult = this.collection._sync.loadSubset({\n      where: stateOpts.where,\n      subscription: this,\n    })\n\n    const trackLoadSubsetPromise = opts?.trackLoadSubsetPromise ?? true\n    if (trackLoadSubsetPromise) {\n      this.trackLoadSubsetPromise(syncResult)\n    }\n\n    // Also load data immediately from the collection\n    const snapshot = this.collection.currentStateAsChanges(stateOpts)\n\n    if (snapshot === undefined) {\n      // Couldn't load from indexes\n      return false\n    }\n\n    // Only send changes that have not been sent yet\n    const filteredSnapshot = snapshot.filter(\n      (change) => !this.sentKeys.has(change.key)\n    )\n\n    this.snapshotSent = true\n    this.callback(filteredSnapshot)\n    return true\n  }\n\n  /**\n   * Sends a snapshot that fulfills the `where` clause and all rows are bigger or equal to `minValue`.\n   * Requires a range index to be set with `setOrderByIndex` prior to calling this method.\n   * It uses that range index to load the items in the order of the index.\n   * Note 1: it may load more rows than the provided LIMIT because it loads all values equal to `minValue` + limit values greater than `minValue`.\n   *         This is needed to ensure that it does not accidentally skip duplicate values when the limit falls in the middle of some duplicated values.\n   * Note 2: it does not send keys that have already been sent before.\n   */\n  requestLimitedSnapshot({\n    orderBy,\n    limit,\n    minValue,\n  }: RequestLimitedSnapshotOptions) {\n    if (!limit) throw new Error(`limit is required`)\n\n    if (!this.orderByIndex) {\n      throw new Error(\n        `Ordered snapshot was requested but no index was found. You have to call setOrderByIndex before requesting an ordered snapshot.`\n      )\n    }\n\n    const index = this.orderByIndex\n    const where = this.options.whereExpression\n    const whereFilterFn = where\n      ? createFilterFunctionFromExpression(where)\n      : undefined\n\n    const filterFn = (key: string | number): boolean => {\n      if (this.sentKeys.has(key)) {\n        return false\n      }\n\n      const value = this.collection.get(key)\n      if (value === undefined) {\n        return false\n      }\n\n      return whereFilterFn?.(value) ?? true\n    }\n\n    let biggestObservedValue = minValue\n    const changes: Array<ChangeMessage<any, string | number>> = []\n\n    // If we have a minValue we need to handle the case\n    // where there might be duplicate values equal to minValue that we need to include\n    // because we can have data like this: [1, 2, 3, 3, 3, 4, 5]\n    // so if minValue is 3 then the previous snapshot may not have included all 3s\n    // e.g. if it was offset 0 and limit 3 it would only have loaded the first 3\n    //      so we load all rows equal to minValue first, to be sure we don't skip any duplicate values\n    let keys: Array<string | number> = []\n    if (minValue !== undefined) {\n      // First, get all items with the same value as minValue\n      const { expression } = orderBy[0]!\n      const allRowsWithMinValue = this.collection.currentStateAsChanges({\n        where: eq(expression, new Value(minValue)),\n      })\n\n      if (allRowsWithMinValue) {\n        const keysWithMinValue = allRowsWithMinValue\n          .map((change) => change.key)\n          .filter((key) => !this.sentKeys.has(key) && filterFn(key))\n\n        // Add items with the minValue first\n        keys.push(...keysWithMinValue)\n\n        // Then get items greater than minValue\n        const keysGreaterThanMin = index.take(\n          limit - keys.length,\n          minValue,\n          filterFn\n        )\n        keys.push(...keysGreaterThanMin)\n      } else {\n        keys = index.take(limit, minValue, filterFn)\n      }\n    } else {\n      keys = index.take(limit, minValue, filterFn)\n    }\n\n    const valuesNeeded = () => Math.max(limit - changes.length, 0)\n    const collectionExhausted = () => keys.length === 0\n\n    while (valuesNeeded() > 0 && !collectionExhausted()) {\n      const insertedKeys = new Set<string | number>() // Track keys we add to `changes` in this iteration\n\n      for (const key of keys) {\n        const value = this.collection.get(key)!\n        changes.push({\n          type: `insert`,\n          key,\n          value,\n        })\n        biggestObservedValue = value\n        insertedKeys.add(key) // Track this key\n      }\n\n      keys = index.take(valuesNeeded(), biggestObservedValue, filterFn)\n    }\n\n    this.callback(changes)\n\n    let whereWithValueFilter = where\n    if (typeof minValue !== `undefined`) {\n      // Only request data that we haven't seen yet (i.e. is bigger than the minValue)\n      const { expression, compareOptions } = orderBy[0]!\n      const operator = compareOptions.direction === `asc` ? gt : lt\n      const valueFilter = operator(expression, new Value(minValue))\n      whereWithValueFilter = where ? and(where, valueFilter) : valueFilter\n    }\n\n    // Request the sync layer to load more data\n    // don't await it, we will load the data into the collection when it comes in\n    const syncResult = this.collection._sync.loadSubset({\n      where: whereWithValueFilter,\n      limit,\n      orderBy,\n      subscription: this,\n    })\n\n    // Make parallel loadSubset calls for values equal to minValue and values greater than minValue\n    const promises: Array<Promise<void>> = []\n\n    // First promise: load all values equal to minValue\n    if (typeof minValue !== `undefined`) {\n      const { expression } = orderBy[0]!\n      const exactValueFilter = eq(expression, new Value(minValue))\n\n      const equalValueResult = this.collection._sync.loadSubset({\n        where: exactValueFilter,\n        subscription: this,\n      })\n\n      if (equalValueResult instanceof Promise) {\n        promises.push(equalValueResult)\n      }\n    }\n\n    // Second promise: load values greater than minValue\n    if (syncResult instanceof Promise) {\n      promises.push(syncResult)\n    }\n\n    // Track the combined promise\n    if (promises.length > 0) {\n      const combinedPromise = Promise.all(promises).then(() => {})\n      this.trackLoadSubsetPromise(combinedPromise)\n    } else {\n      this.trackLoadSubsetPromise(syncResult)\n    }\n  }\n\n  // TODO: also add similar test but that checks that it can also load it from the collection's loadSubset function\n  //       and that that also works properly (i.e. does not skip duplicate values)\n\n  /**\n   * Filters and flips changes for keys that have not been sent yet.\n   * Deletes are filtered out for keys that have not been sent yet.\n   * Updates are flipped into inserts for keys that have not been sent yet.\n   */\n  private filterAndFlipChanges(changes: Array<ChangeMessage<any, any>>) {\n    if (this.loadedInitialState) {\n      // We loaded the entire initial state\n      // so no need to filter or flip changes\n      return changes\n    }\n\n    const newChanges = []\n    for (const change of changes) {\n      let newChange = change\n      if (!this.sentKeys.has(change.key)) {\n        if (change.type === `update`) {\n          newChange = { ...change, type: `insert`, previousValue: undefined }\n        } else if (change.type === `delete`) {\n          // filter out deletes for keys that have not been sent\n          continue\n        }\n        this.sentKeys.add(change.key)\n      }\n      newChanges.push(newChange)\n    }\n    return newChanges\n  }\n\n  private trackSentKeys(changes: Array<ChangeMessage<any, string | number>>) {\n    if (this.loadedInitialState) {\n      // No need to track sent keys if we loaded the entire state.\n      // Since we sent everything, all keys must have been observed.\n      return\n    }\n\n    for (const change of changes) {\n      this.sentKeys.add(change.key)\n    }\n  }\n\n  unsubscribe() {\n    this.emitInner(`unsubscribed`, {\n      type: `unsubscribed`,\n      subscription: this,\n    })\n    // Clear all event listeners to prevent memory leaks\n    this.clearListeners()\n  }\n}\n"],"names":["EventEmitter","ensureIndexForExpression","createFilteredCallback","and","createFilterFunctionFromExpression","eq","Value","gt","lt"],"mappings":"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"}
+{"version":3,"file":"subscription.cjs","sources":["../../../src/collection/subscription.ts"],"sourcesContent":["import { ensureIndexForExpression } from \"../indexes/auto-index.js\"\nimport { and, eq, gt, lt } from \"../query/builder/functions.js\"\nimport { Value } from \"../query/ir.js\"\nimport { EventEmitter } from \"../event-emitter.js\"\nimport {\n  createFilterFunctionFromExpression,\n  createFilteredCallback,\n} from \"./change-events.js\"\nimport type { BasicExpression, OrderBy } from \"../query/ir.js\"\nimport type { IndexInterface } from \"../indexes/base-index.js\"\nimport type {\n  ChangeMessage,\n  LoadSubsetOptions,\n  Subscription,\n  SubscriptionEvents,\n  SubscriptionStatus,\n  SubscriptionUnsubscribedEvent,\n} from \"../types.js\"\nimport type { CollectionImpl } from \"./index.js\"\n\ntype RequestSnapshotOptions = {\n  where?: BasicExpression<boolean>\n  optimizedOnly?: boolean\n  trackLoadSubsetPromise?: boolean\n}\n\ntype RequestLimitedSnapshotOptions = {\n  orderBy: OrderBy\n  limit: number\n  minValue?: any\n}\n\ntype CollectionSubscriptionOptions = {\n  includeInitialState?: boolean\n  /** Pre-compiled expression for filtering changes */\n  whereExpression?: BasicExpression<boolean>\n  /** Callback to call when the subscription is unsubscribed */\n  onUnsubscribe?: (event: SubscriptionUnsubscribedEvent) => void\n}\n\nexport class CollectionSubscription\n  extends EventEmitter<SubscriptionEvents>\n  implements Subscription\n{\n  private loadedInitialState = false\n\n  // Flag to indicate that we have sent at least 1 snapshot.\n  // While `snapshotSent` is false we filter out all changes from subscription to the collection.\n  private snapshotSent = false\n\n  /**\n   * Track all loadSubset calls made by this subscription so we can unload them on cleanup.\n   * We store the exact LoadSubsetOptions we passed to loadSubset to ensure symmetric unload.\n   */\n  private loadedSubsets: Array<LoadSubsetOptions> = []\n\n  // Keep track of the keys we've sent (needed for join and orderBy optimizations)\n  private sentKeys = new Set<string | number>()\n\n  private filteredCallback: (changes: Array<ChangeMessage<any, any>>) => void\n\n  private orderByIndex: IndexInterface<string | number> | undefined\n\n  // Status tracking\n  private _status: SubscriptionStatus = `ready`\n  private pendingLoadSubsetPromises: Set<Promise<void>> = new Set()\n\n  public get status(): SubscriptionStatus {\n    return this._status\n  }\n\n  constructor(\n    private collection: CollectionImpl<any, any, any, any, any>,\n    private callback: (changes: Array<ChangeMessage<any, any>>) => void,\n    private options: CollectionSubscriptionOptions\n  ) {\n    super()\n    if (options.onUnsubscribe) {\n      this.on(`unsubscribed`, (event) => options.onUnsubscribe!(event))\n    }\n\n    // Auto-index for where expressions if enabled\n    if (options.whereExpression) {\n      ensureIndexForExpression(options.whereExpression, this.collection)\n    }\n\n    const callbackWithSentKeysTracking = (\n      changes: Array<ChangeMessage<any, any>>\n    ) => {\n      callback(changes)\n      this.trackSentKeys(changes)\n    }\n\n    this.callback = callbackWithSentKeysTracking\n\n    // Create a filtered callback if where clause is provided\n    this.filteredCallback = options.whereExpression\n      ? createFilteredCallback(this.callback, options)\n      : this.callback\n  }\n\n  setOrderByIndex(index: IndexInterface<any>) {\n    this.orderByIndex = index\n  }\n\n  /**\n   * Set subscription status and emit events if changed\n   */\n  private setStatus(newStatus: SubscriptionStatus) {\n    if (this._status === newStatus) {\n      return // No change\n    }\n\n    const previousStatus = this._status\n    this._status = newStatus\n\n    // Emit status:change event\n    this.emitInner(`status:change`, {\n      type: `status:change`,\n      subscription: this,\n      previousStatus,\n      status: newStatus,\n    })\n\n    // Emit specific status event\n    const eventKey: `status:${SubscriptionStatus}` = `status:${newStatus}`\n    this.emitInner(eventKey, {\n      type: eventKey,\n      subscription: this,\n      previousStatus,\n      status: newStatus,\n    } as SubscriptionEvents[typeof eventKey])\n  }\n\n  /**\n   * Track a loadSubset promise and manage loading status\n   */\n  private trackLoadSubsetPromise(syncResult: Promise<void> | true) {\n    // Track the promise if it's actually a promise (async work)\n    if (syncResult instanceof Promise) {\n      this.pendingLoadSubsetPromises.add(syncResult)\n      this.setStatus(`loadingSubset`)\n\n      syncResult.finally(() => {\n        this.pendingLoadSubsetPromises.delete(syncResult)\n        if (this.pendingLoadSubsetPromises.size === 0) {\n          this.setStatus(`ready`)\n        }\n      })\n    }\n  }\n\n  hasLoadedInitialState() {\n    return this.loadedInitialState\n  }\n\n  hasSentAtLeastOneSnapshot() {\n    return this.snapshotSent\n  }\n\n  emitEvents(changes: Array<ChangeMessage<any, any>>) {\n    const newChanges = this.filterAndFlipChanges(changes)\n    this.filteredCallback(newChanges)\n  }\n\n  /**\n   * Sends the snapshot to the callback.\n   * Returns a boolean indicating if it succeeded.\n   * It can only fail if there is no index to fulfill the request\n   * and the optimizedOnly option is set to true,\n   * or, the entire state was already loaded.\n   */\n  requestSnapshot(opts?: RequestSnapshotOptions): boolean {\n    if (this.loadedInitialState) {\n      // Subscription was deoptimized so we already sent the entire initial state\n      return false\n    }\n\n    const stateOpts: RequestSnapshotOptions = {\n      where: this.options.whereExpression,\n      optimizedOnly: opts?.optimizedOnly ?? false,\n    }\n\n    if (opts) {\n      if (`where` in opts) {\n        const snapshotWhereExp = opts.where\n        if (stateOpts.where) {\n          // Combine the two where expressions\n          const subWhereExp = stateOpts.where\n          const combinedWhereExp = and(subWhereExp, snapshotWhereExp)\n          stateOpts.where = combinedWhereExp\n        } else {\n          stateOpts.where = snapshotWhereExp\n        }\n      }\n    } else {\n      // No options provided so it's loading the entire initial state\n      this.loadedInitialState = true\n    }\n\n    // Request the sync layer to load more data\n    // don't await it, we will load the data into the collection when it comes in\n    const loadOptions: LoadSubsetOptions = {\n      where: stateOpts.where,\n      subscription: this,\n    }\n    const syncResult = this.collection._sync.loadSubset(loadOptions)\n\n    // Track this loadSubset call so we can unload it later\n    this.loadedSubsets.push(loadOptions)\n\n    const trackLoadSubsetPromise = opts?.trackLoadSubsetPromise ?? true\n    if (trackLoadSubsetPromise) {\n      this.trackLoadSubsetPromise(syncResult)\n    }\n\n    // Also load data immediately from the collection\n    const snapshot = this.collection.currentStateAsChanges(stateOpts)\n\n    if (snapshot === undefined) {\n      // Couldn't load from indexes\n      return false\n    }\n\n    // Only send changes that have not been sent yet\n    const filteredSnapshot = snapshot.filter(\n      (change) => !this.sentKeys.has(change.key)\n    )\n\n    this.snapshotSent = true\n    this.callback(filteredSnapshot)\n    return true\n  }\n\n  /**\n   * Sends a snapshot that fulfills the `where` clause and all rows are bigger or equal to `minValue`.\n   * Requires a range index to be set with `setOrderByIndex` prior to calling this method.\n   * It uses that range index to load the items in the order of the index.\n   * Note 1: it may load more rows than the provided LIMIT because it loads all values equal to `minValue` + limit values greater than `minValue`.\n   *         This is needed to ensure that it does not accidentally skip duplicate values when the limit falls in the middle of some duplicated values.\n   * Note 2: it does not send keys that have already been sent before.\n   */\n  requestLimitedSnapshot({\n    orderBy,\n    limit,\n    minValue,\n  }: RequestLimitedSnapshotOptions) {\n    if (!limit) throw new Error(`limit is required`)\n\n    if (!this.orderByIndex) {\n      throw new Error(\n        `Ordered snapshot was requested but no index was found. You have to call setOrderByIndex before requesting an ordered snapshot.`\n      )\n    }\n\n    const index = this.orderByIndex\n    const where = this.options.whereExpression\n    const whereFilterFn = where\n      ? createFilterFunctionFromExpression(where)\n      : undefined\n\n    const filterFn = (key: string | number): boolean => {\n      if (this.sentKeys.has(key)) {\n        return false\n      }\n\n      const value = this.collection.get(key)\n      if (value === undefined) {\n        return false\n      }\n\n      return whereFilterFn?.(value) ?? true\n    }\n\n    let biggestObservedValue = minValue\n    const changes: Array<ChangeMessage<any, string | number>> = []\n\n    // If we have a minValue we need to handle the case\n    // where there might be duplicate values equal to minValue that we need to include\n    // because we can have data like this: [1, 2, 3, 3, 3, 4, 5]\n    // so if minValue is 3 then the previous snapshot may not have included all 3s\n    // e.g. if it was offset 0 and limit 3 it would only have loaded the first 3\n    //      so we load all rows equal to minValue first, to be sure we don't skip any duplicate values\n    let keys: Array<string | number> = []\n    if (minValue !== undefined) {\n      // First, get all items with the same value as minValue\n      const { expression } = orderBy[0]!\n      const allRowsWithMinValue = this.collection.currentStateAsChanges({\n        where: eq(expression, new Value(minValue)),\n      })\n\n      if (allRowsWithMinValue) {\n        const keysWithMinValue = allRowsWithMinValue\n          .map((change) => change.key)\n          .filter((key) => !this.sentKeys.has(key) && filterFn(key))\n\n        // Add items with the minValue first\n        keys.push(...keysWithMinValue)\n\n        // Then get items greater than minValue\n        const keysGreaterThanMin = index.take(\n          limit - keys.length,\n          minValue,\n          filterFn\n        )\n        keys.push(...keysGreaterThanMin)\n      } else {\n        keys = index.take(limit, minValue, filterFn)\n      }\n    } else {\n      keys = index.take(limit, minValue, filterFn)\n    }\n\n    const valuesNeeded = () => Math.max(limit - changes.length, 0)\n    const collectionExhausted = () => keys.length === 0\n\n    while (valuesNeeded() > 0 && !collectionExhausted()) {\n      const insertedKeys = new Set<string | number>() // Track keys we add to `changes` in this iteration\n\n      for (const key of keys) {\n        const value = this.collection.get(key)!\n        changes.push({\n          type: `insert`,\n          key,\n          value,\n        })\n        biggestObservedValue = value\n        insertedKeys.add(key) // Track this key\n      }\n\n      keys = index.take(valuesNeeded(), biggestObservedValue, filterFn)\n    }\n\n    this.callback(changes)\n\n    let whereWithValueFilter = where\n    if (typeof minValue !== `undefined`) {\n      // Only request data that we haven't seen yet (i.e. is bigger than the minValue)\n      const { expression, compareOptions } = orderBy[0]!\n      const operator = compareOptions.direction === `asc` ? gt : lt\n      const valueFilter = operator(expression, new Value(minValue))\n      whereWithValueFilter = where ? and(where, valueFilter) : valueFilter\n    }\n\n    // Request the sync layer to load more data\n    // don't await it, we will load the data into the collection when it comes in\n    const loadOptions1: LoadSubsetOptions = {\n      where: whereWithValueFilter,\n      limit,\n      orderBy,\n      subscription: this,\n    }\n    const syncResult = this.collection._sync.loadSubset(loadOptions1)\n\n    // Track this loadSubset call\n    this.loadedSubsets.push(loadOptions1)\n\n    // Make parallel loadSubset calls for values equal to minValue and values greater than minValue\n    const promises: Array<Promise<void>> = []\n\n    // First promise: load all values equal to minValue\n    if (typeof minValue !== `undefined`) {\n      const { expression } = orderBy[0]!\n      const exactValueFilter = eq(expression, new Value(minValue))\n\n      const loadOptions2: LoadSubsetOptions = {\n        where: exactValueFilter,\n        subscription: this,\n      }\n      const equalValueResult = this.collection._sync.loadSubset(loadOptions2)\n\n      // Track this loadSubset call\n      this.loadedSubsets.push(loadOptions2)\n\n      if (equalValueResult instanceof Promise) {\n        promises.push(equalValueResult)\n      }\n    }\n\n    // Second promise: load values greater than minValue\n    if (syncResult instanceof Promise) {\n      promises.push(syncResult)\n    }\n\n    // Track the combined promise\n    if (promises.length > 0) {\n      const combinedPromise = Promise.all(promises).then(() => {})\n      this.trackLoadSubsetPromise(combinedPromise)\n    } else {\n      this.trackLoadSubsetPromise(syncResult)\n    }\n  }\n\n  // TODO: also add similar test but that checks that it can also load it from the collection's loadSubset function\n  //       and that that also works properly (i.e. does not skip duplicate values)\n\n  /**\n   * Filters and flips changes for keys that have not been sent yet.\n   * Deletes are filtered out for keys that have not been sent yet.\n   * Updates are flipped into inserts for keys that have not been sent yet.\n   */\n  private filterAndFlipChanges(changes: Array<ChangeMessage<any, any>>) {\n    if (this.loadedInitialState) {\n      // We loaded the entire initial state\n      // so no need to filter or flip changes\n      return changes\n    }\n\n    const newChanges = []\n    for (const change of changes) {\n      let newChange = change\n      if (!this.sentKeys.has(change.key)) {\n        if (change.type === `update`) {\n          newChange = { ...change, type: `insert`, previousValue: undefined }\n        } else if (change.type === `delete`) {\n          // filter out deletes for keys that have not been sent\n          continue\n        }\n        this.sentKeys.add(change.key)\n      }\n      newChanges.push(newChange)\n    }\n    return newChanges\n  }\n\n  private trackSentKeys(changes: Array<ChangeMessage<any, string | number>>) {\n    if (this.loadedInitialState) {\n      // No need to track sent keys if we loaded the entire state.\n      // Since we sent everything, all keys must have been observed.\n      return\n    }\n\n    for (const change of changes) {\n      this.sentKeys.add(change.key)\n    }\n  }\n\n  unsubscribe() {\n    // Unload all subsets that this subscription loaded\n    // We pass the exact same LoadSubsetOptions we used for loadSubset\n    for (const options of this.loadedSubsets) {\n      this.collection._sync.unloadSubset(options)\n    }\n    this.loadedSubsets = []\n\n    this.emitInner(`unsubscribed`, {\n      type: `unsubscribed`,\n      subscription: this,\n    })\n    // Clear all event listeners to prevent memory leaks\n    this.clearListeners()\n  }\n}\n"],"names":["EventEmitter","ensureIndexForExpression","createFilteredCallback","and","createFilterFunctionFromExpression","eq","Value","gt","lt"],"mappings":"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"}

package/dist/cjs/collection/subscription.d.cts

@@ -26,6 +26,11 @@ export declare class CollectionSubscription extends EventEmitter<SubscriptionEve
     private options;
     private loadedInitialState;
     private snapshotSent;
+    /**
+     * Track all loadSubset calls made by this subscription so we can unload them on cleanup.
+     * We store the exact LoadSubsetOptions we passed to loadSubset to ensure symmetric unload.
+     */
+    private loadedSubsets;
     private sentKeys;
     private filteredCallback;
     private orderByIndex;

package/dist/cjs/collection/sync.cjs

@@ -11,6 +11,7 @@ class CollectionSyncManager {
     this.preloadPromise = null;
     this.syncCleanupFn = null;
     this.syncLoadSubsetFn = null;
+    this.syncUnloadSubsetFn = null;
     this.pendingLoadSubsetPromises = /* @__PURE__ */ new Set();
     this.config = config;
     this.id = id;
@@ -114,6 +115,7 @@ class CollectionSyncManager {
       );
       this.syncCleanupFn = syncRes?.cleanup ?? null;
       this.syncLoadSubsetFn = syncRes?.loadSubset ?? null;
+      this.syncUnloadSubsetFn = syncRes?.unloadSubset ?? null;
       if (this.syncMode === `on-demand` && !this.syncLoadSubsetFn) {
         throw new errors.CollectionConfigurationError(
           `Collection "${this.id}" is configured with syncMode "on-demand" but the sync function did not return a loadSubset handler. Either provide a loadSubset handler or use syncMode "eager".`
@@ -132,6 +134,11 @@ class CollectionSyncManager {
     if (this.preloadPromise) {
       return this.preloadPromise;
     }
+    if (this.syncMode === `on-demand`) {
+      console.warn(
+        `${this.id ? `[${this.id}] ` : ``}Calling .preload() on a collection with syncMode "on-demand" is a no-op. In on-demand mode, data is only loaded when queries request it. Instead, create a live query and call .preload() on that to load the specific data you need. See https://tanstack.com/blog/tanstack-db-0.5-query-driven-sync for more details.`
+      );
+    }
     this.preloadPromise = new Promise((resolve, reject) => {
       if (this.lifecycle.status === `ready`) {
         resolve();
@@ -210,6 +217,15 @@ class CollectionSyncManager {
     }
     return true;
   }
+  /**
+   * Notifies the sync layer that a subset is no longer needed.
+   * @param options Options that identify what data is being unloaded
+   */
+  unloadSubset(options) {
+    if (this.syncUnloadSubsetFn) {
+      this.syncUnloadSubsetFn(options);
+    }
+  }
   cleanup() {
     try {
       if (this.syncCleanupFn) {

package/dist/cjs/collection/sync.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"sync.cjs","sources":["../../../src/collection/sync.ts"],"sourcesContent":["import {\n  CollectionConfigurationError,\n  CollectionIsInErrorStateError,\n  DuplicateKeySyncError,\n  NoPendingSyncTransactionCommitError,\n  NoPendingSyncTransactionWriteError,\n  SyncCleanupError,\n  SyncTransactionAlreadyCommittedError,\n  SyncTransactionAlreadyCommittedWriteError,\n} from \"../errors\"\nimport { deepEquals } from \"../utils\"\nimport { LIVE_QUERY_INTERNAL } from \"../query/live/internal.js\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type {\n  ChangeMessage,\n  CleanupFn,\n  CollectionConfig,\n  LoadSubsetOptions,\n  SyncConfigRes,\n} from \"../types\"\nimport type { CollectionImpl } from \"./index.js\"\nimport type { CollectionStateManager } from \"./state\"\nimport type { CollectionLifecycleManager } from \"./lifecycle\"\nimport type { CollectionEventsManager } from \"./events.js\"\nimport type { LiveQueryCollectionUtils } from \"../query/live/collection-config-builder.js\"\n\nexport class CollectionSyncManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  private _events!: CollectionEventsManager\n  private config!: CollectionConfig<TOutput, TKey, TSchema>\n  private id: string\n  private syncMode: `eager` | `on-demand`\n\n  public preloadPromise: Promise<void> | null = null\n  public syncCleanupFn: (() => void) | null = null\n  public syncLoadSubsetFn:\n    | ((options: LoadSubsetOptions) => true | Promise<void>)\n    | null = null\n\n  private pendingLoadSubsetPromises: Set<Promise<void>> = new Set()\n\n  /**\n   * Creates a new CollectionSyncManager instance\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>, id: string) {\n    this.config = config\n    this.id = id\n    this.syncMode = config.syncMode ?? `eager`\n  }\n\n  setDeps(deps: {\n    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n  }) {\n    this.collection = deps.collection\n    this.state = deps.state\n    this.lifecycle = deps.lifecycle\n    this._events = deps.events\n  }\n\n  /**\n   * Start the sync process for this collection\n   * This is called when the collection is first accessed or preloaded\n   */\n  public startSync(): void {\n    if (\n      this.lifecycle.status !== `idle` &&\n      this.lifecycle.status !== `cleaned-up`\n    ) {\n      return // Already started or in progress\n    }\n\n    this.lifecycle.setStatus(`loading`)\n\n    try {\n      const syncRes = normalizeSyncFnResult(\n        this.config.sync.sync({\n          collection: this.collection,\n          begin: () => {\n            this.state.pendingSyncedTransactions.push({\n              committed: false,\n              operations: [],\n              deletedKeys: new Set(),\n            })\n          },\n          write: (messageWithoutKey: Omit<ChangeMessage<TOutput>, `key`>) => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionWriteError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedWriteError()\n            }\n            const key = this.config.getKey(messageWithoutKey.value)\n\n            let messageType = messageWithoutKey.type\n\n            // Check if an item with this key already exists when inserting\n            if (messageWithoutKey.type === `insert`) {\n              const insertingIntoExistingSynced = this.state.syncedData.has(key)\n              const hasPendingDeleteForKey =\n                pendingTransaction.deletedKeys.has(key)\n              const isTruncateTransaction = pendingTransaction.truncate === true\n              // Allow insert after truncate in the same transaction even if it existed in syncedData\n              if (\n                insertingIntoExistingSynced &&\n                !hasPendingDeleteForKey &&\n                !isTruncateTransaction\n              ) {\n                const existingValue = this.state.syncedData.get(key)\n                if (\n                  existingValue !== undefined &&\n                  deepEquals(existingValue, messageWithoutKey.value)\n                ) {\n                  // The \"insert\" is an echo of a value we already have locally.\n                  // Treat it as an update so we preserve optimistic intent without\n                  // throwing a duplicate-key error during reconciliation.\n                  messageType = `update`\n                } else {\n                  const utils = this.config\n                    .utils as Partial<LiveQueryCollectionUtils>\n                  const internal = utils[LIVE_QUERY_INTERNAL]\n                  throw new DuplicateKeySyncError(key, this.id, {\n                    hasCustomGetKey: internal?.hasCustomGetKey ?? false,\n                    hasJoins: internal?.hasJoins ?? false,\n                  })\n                }\n              }\n            }\n\n            const message: ChangeMessage<TOutput> = {\n              ...messageWithoutKey,\n              type: messageType,\n              key,\n            }\n            pendingTransaction.operations.push(message)\n\n            if (messageType === `delete`) {\n              pendingTransaction.deletedKeys.add(key)\n            }\n          },\n          commit: () => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionCommitError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedError()\n            }\n\n            pendingTransaction.committed = true\n\n            this.state.commitPendingTransactions()\n          },\n          markReady: () => {\n            this.lifecycle.markReady()\n          },\n          truncate: () => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionWriteError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedWriteError()\n            }\n\n            // Clear all operations from the current transaction\n            pendingTransaction.operations = []\n            pendingTransaction.deletedKeys.clear()\n\n            // Mark the transaction as a truncate operation. During commit, this triggers:\n            // - Delete events for all previously synced keys (excluding optimistic-deleted keys)\n            // - Clearing of syncedData/syncedMetadata\n            // - Subsequent synced ops applied on the fresh base\n            // - Finally, optimistic mutations re-applied on top (single batch)\n            pendingTransaction.truncate = true\n\n            // Capture optimistic state NOW to preserve it even if transactions complete\n            // before this truncate transaction is committed\n            pendingTransaction.optimisticSnapshot = {\n              upserts: new Map(this.state.optimisticUpserts),\n              deletes: new Set(this.state.optimisticDeletes),\n            }\n          },\n        })\n      )\n\n      // Store cleanup function if provided\n      this.syncCleanupFn = syncRes?.cleanup ?? null\n\n      // Store loadSubset function if provided\n      this.syncLoadSubsetFn = syncRes?.loadSubset ?? null\n\n      // Validate: on-demand mode requires a loadSubset function\n      if (this.syncMode === `on-demand` && !this.syncLoadSubsetFn) {\n        throw new CollectionConfigurationError(\n          `Collection \"${this.id}\" is configured with syncMode \"on-demand\" but the sync function did not return a loadSubset handler. ` +\n            `Either provide a loadSubset handler or use syncMode \"eager\".`\n        )\n      }\n    } catch (error) {\n      this.lifecycle.setStatus(`error`)\n      throw error\n    }\n  }\n\n  /**\n   * Preload the collection data by starting sync if not already started\n   * Multiple concurrent calls will share the same promise\n   */\n  public preload(): Promise<void> {\n    if (this.preloadPromise) {\n      return this.preloadPromise\n    }\n\n    this.preloadPromise = new Promise<void>((resolve, reject) => {\n      if (this.lifecycle.status === `ready`) {\n        resolve()\n        return\n      }\n\n      if (this.lifecycle.status === `error`) {\n        reject(new CollectionIsInErrorStateError())\n        return\n      }\n\n      // Register callback BEFORE starting sync to avoid race condition\n      this.lifecycle.onFirstReady(() => {\n        resolve()\n      })\n\n      // Start sync if collection hasn't started yet or was cleaned up\n      if (\n        this.lifecycle.status === `idle` ||\n        this.lifecycle.status === `cleaned-up`\n      ) {\n        try {\n          this.startSync()\n        } catch (error) {\n          reject(error)\n          return\n        }\n      }\n    })\n\n    return this.preloadPromise\n  }\n\n  /**\n   * Gets whether the collection is currently loading more data\n   */\n  public get isLoadingSubset(): boolean {\n    return this.pendingLoadSubsetPromises.size > 0\n  }\n\n  /**\n   * Tracks a load promise for isLoadingSubset state.\n   * @internal This is for internal coordination (e.g., live-query glue code), not for general use.\n   */\n  public trackLoadPromise(promise: Promise<void>): void {\n    const loadingStarting = !this.isLoadingSubset\n    this.pendingLoadSubsetPromises.add(promise)\n\n    if (loadingStarting) {\n      this._events.emit(`loadingSubset:change`, {\n        type: `loadingSubset:change`,\n        collection: this.collection,\n        isLoadingSubset: true,\n        previousIsLoadingSubset: false,\n        loadingSubsetTransition: `start`,\n      })\n    }\n\n    promise.finally(() => {\n      const loadingEnding =\n        this.pendingLoadSubsetPromises.size === 1 &&\n        this.pendingLoadSubsetPromises.has(promise)\n      this.pendingLoadSubsetPromises.delete(promise)\n\n      if (loadingEnding) {\n        this._events.emit(`loadingSubset:change`, {\n          type: `loadingSubset:change`,\n          collection: this.collection,\n          isLoadingSubset: false,\n          previousIsLoadingSubset: true,\n          loadingSubsetTransition: `end`,\n        })\n      }\n    })\n  }\n\n  /**\n   * Requests the sync layer to load more data.\n   * @param options Options to control what data is being loaded\n   * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.\n   *          Returns true if no sync function is configured, if syncMode is 'eager', or if there is no work to do.\n   */\n  public loadSubset(options: LoadSubsetOptions): Promise<void> | true {\n    // Bypass loadSubset when syncMode is 'eager'\n    if (this.syncMode === `eager`) {\n      return true\n    }\n\n    if (this.syncLoadSubsetFn) {\n      const result = this.syncLoadSubsetFn(options)\n      // If the result is a promise, track it\n      if (result instanceof Promise) {\n        this.trackLoadPromise(result)\n        return result\n      }\n    }\n\n    return true\n  }\n\n  public cleanup(): void {\n    try {\n      if (this.syncCleanupFn) {\n        this.syncCleanupFn()\n        this.syncCleanupFn = null\n      }\n    } catch (error) {\n      // Re-throw in a microtask to surface the error after cleanup completes\n      queueMicrotask(() => {\n        if (error instanceof Error) {\n          // Preserve the original error and stack trace\n          const wrappedError = new SyncCleanupError(this.id, error)\n          wrappedError.cause = error\n          wrappedError.stack = error.stack\n          throw wrappedError\n        } else {\n          throw new SyncCleanupError(this.id, error as Error | string)\n        }\n      })\n    }\n    this.preloadPromise = null\n  }\n}\n\nfunction normalizeSyncFnResult(result: void | CleanupFn | SyncConfigRes) {\n  if (typeof result === `function`) {\n    return { cleanup: result }\n  }\n\n  if (typeof result === `object`) {\n    return result\n  }\n\n  return undefined\n}\n"],"names":["NoPendingSyncTransactionWriteError","SyncTransactionAlreadyCommittedWriteError","deepEquals","utils","internal","LIVE_QUERY_INTERNAL","DuplicateKeySyncError","NoPendingSyncTransactionCommitError","SyncTransactionAlreadyCommittedError","CollectionConfigurationError","CollectionIsInErrorStateError","SyncCleanupError"],"mappings":"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"}
+{"version":3,"file":"sync.cjs","sources":["../../../src/collection/sync.ts"],"sourcesContent":["import {\n  CollectionConfigurationError,\n  CollectionIsInErrorStateError,\n  DuplicateKeySyncError,\n  NoPendingSyncTransactionCommitError,\n  NoPendingSyncTransactionWriteError,\n  SyncCleanupError,\n  SyncTransactionAlreadyCommittedError,\n  SyncTransactionAlreadyCommittedWriteError,\n} from \"../errors\"\nimport { deepEquals } from \"../utils\"\nimport { LIVE_QUERY_INTERNAL } from \"../query/live/internal.js\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type {\n  ChangeMessage,\n  CleanupFn,\n  CollectionConfig,\n  LoadSubsetOptions,\n  SyncConfigRes,\n} from \"../types\"\nimport type { CollectionImpl } from \"./index.js\"\nimport type { CollectionStateManager } from \"./state\"\nimport type { CollectionLifecycleManager } from \"./lifecycle\"\nimport type { CollectionEventsManager } from \"./events.js\"\nimport type { LiveQueryCollectionUtils } from \"../query/live/collection-config-builder.js\"\n\nexport class CollectionSyncManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  private _events!: CollectionEventsManager\n  private config!: CollectionConfig<TOutput, TKey, TSchema>\n  private id: string\n  private syncMode: `eager` | `on-demand`\n\n  public preloadPromise: Promise<void> | null = null\n  public syncCleanupFn: (() => void) | null = null\n  public syncLoadSubsetFn:\n    | ((options: LoadSubsetOptions) => true | Promise<void>)\n    | null = null\n  public syncUnloadSubsetFn: ((options: LoadSubsetOptions) => void) | null =\n    null\n\n  private pendingLoadSubsetPromises: Set<Promise<void>> = new Set()\n\n  /**\n   * Creates a new CollectionSyncManager instance\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>, id: string) {\n    this.config = config\n    this.id = id\n    this.syncMode = config.syncMode ?? `eager`\n  }\n\n  setDeps(deps: {\n    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n  }) {\n    this.collection = deps.collection\n    this.state = deps.state\n    this.lifecycle = deps.lifecycle\n    this._events = deps.events\n  }\n\n  /**\n   * Start the sync process for this collection\n   * This is called when the collection is first accessed or preloaded\n   */\n  public startSync(): void {\n    if (\n      this.lifecycle.status !== `idle` &&\n      this.lifecycle.status !== `cleaned-up`\n    ) {\n      return // Already started or in progress\n    }\n\n    this.lifecycle.setStatus(`loading`)\n\n    try {\n      const syncRes = normalizeSyncFnResult(\n        this.config.sync.sync({\n          collection: this.collection,\n          begin: () => {\n            this.state.pendingSyncedTransactions.push({\n              committed: false,\n              operations: [],\n              deletedKeys: new Set(),\n            })\n          },\n          write: (messageWithoutKey: Omit<ChangeMessage<TOutput>, `key`>) => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionWriteError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedWriteError()\n            }\n            const key = this.config.getKey(messageWithoutKey.value)\n\n            let messageType = messageWithoutKey.type\n\n            // Check if an item with this key already exists when inserting\n            if (messageWithoutKey.type === `insert`) {\n              const insertingIntoExistingSynced = this.state.syncedData.has(key)\n              const hasPendingDeleteForKey =\n                pendingTransaction.deletedKeys.has(key)\n              const isTruncateTransaction = pendingTransaction.truncate === true\n              // Allow insert after truncate in the same transaction even if it existed in syncedData\n              if (\n                insertingIntoExistingSynced &&\n                !hasPendingDeleteForKey &&\n                !isTruncateTransaction\n              ) {\n                const existingValue = this.state.syncedData.get(key)\n                if (\n                  existingValue !== undefined &&\n                  deepEquals(existingValue, messageWithoutKey.value)\n                ) {\n                  // The \"insert\" is an echo of a value we already have locally.\n                  // Treat it as an update so we preserve optimistic intent without\n                  // throwing a duplicate-key error during reconciliation.\n                  messageType = `update`\n                } else {\n                  const utils = this.config\n                    .utils as Partial<LiveQueryCollectionUtils>\n                  const internal = utils[LIVE_QUERY_INTERNAL]\n                  throw new DuplicateKeySyncError(key, this.id, {\n                    hasCustomGetKey: internal?.hasCustomGetKey ?? false,\n                    hasJoins: internal?.hasJoins ?? false,\n                  })\n                }\n              }\n            }\n\n            const message: ChangeMessage<TOutput> = {\n              ...messageWithoutKey,\n              type: messageType,\n              key,\n            }\n            pendingTransaction.operations.push(message)\n\n            if (messageType === `delete`) {\n              pendingTransaction.deletedKeys.add(key)\n            }\n          },\n          commit: () => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionCommitError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedError()\n            }\n\n            pendingTransaction.committed = true\n\n            this.state.commitPendingTransactions()\n          },\n          markReady: () => {\n            this.lifecycle.markReady()\n          },\n          truncate: () => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionWriteError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedWriteError()\n            }\n\n            // Clear all operations from the current transaction\n            pendingTransaction.operations = []\n            pendingTransaction.deletedKeys.clear()\n\n            // Mark the transaction as a truncate operation. During commit, this triggers:\n            // - Delete events for all previously synced keys (excluding optimistic-deleted keys)\n            // - Clearing of syncedData/syncedMetadata\n            // - Subsequent synced ops applied on the fresh base\n            // - Finally, optimistic mutations re-applied on top (single batch)\n            pendingTransaction.truncate = true\n\n            // Capture optimistic state NOW to preserve it even if transactions complete\n            // before this truncate transaction is committed\n            pendingTransaction.optimisticSnapshot = {\n              upserts: new Map(this.state.optimisticUpserts),\n              deletes: new Set(this.state.optimisticDeletes),\n            }\n          },\n        })\n      )\n\n      // Store cleanup function if provided\n      this.syncCleanupFn = syncRes?.cleanup ?? null\n\n      // Store loadSubset function if provided\n      this.syncLoadSubsetFn = syncRes?.loadSubset ?? null\n\n      // Store unloadSubset function if provided\n      this.syncUnloadSubsetFn = syncRes?.unloadSubset ?? null\n\n      // Validate: on-demand mode requires a loadSubset function\n      if (this.syncMode === `on-demand` && !this.syncLoadSubsetFn) {\n        throw new CollectionConfigurationError(\n          `Collection \"${this.id}\" is configured with syncMode \"on-demand\" but the sync function did not return a loadSubset handler. ` +\n            `Either provide a loadSubset handler or use syncMode \"eager\".`\n        )\n      }\n    } catch (error) {\n      this.lifecycle.setStatus(`error`)\n      throw error\n    }\n  }\n\n  /**\n   * Preload the collection data by starting sync if not already started\n   * Multiple concurrent calls will share the same promise\n   */\n  public preload(): Promise<void> {\n    if (this.preloadPromise) {\n      return this.preloadPromise\n    }\n\n    // Warn when calling preload on an on-demand collection\n    if (this.syncMode === `on-demand`) {\n      console.warn(\n        `${this.id ? `[${this.id}] ` : ``}Calling .preload() on a collection with syncMode \"on-demand\" is a no-op. ` +\n          `In on-demand mode, data is only loaded when queries request it. ` +\n          `Instead, create a live query and call .preload() on that to load the specific data you need. ` +\n          `See https://tanstack.com/blog/tanstack-db-0.5-query-driven-sync for more details.`\n      )\n    }\n\n    this.preloadPromise = new Promise<void>((resolve, reject) => {\n      if (this.lifecycle.status === `ready`) {\n        resolve()\n        return\n      }\n\n      if (this.lifecycle.status === `error`) {\n        reject(new CollectionIsInErrorStateError())\n        return\n      }\n\n      // Register callback BEFORE starting sync to avoid race condition\n      this.lifecycle.onFirstReady(() => {\n        resolve()\n      })\n\n      // Start sync if collection hasn't started yet or was cleaned up\n      if (\n        this.lifecycle.status === `idle` ||\n        this.lifecycle.status === `cleaned-up`\n      ) {\n        try {\n          this.startSync()\n        } catch (error) {\n          reject(error)\n          return\n        }\n      }\n    })\n\n    return this.preloadPromise\n  }\n\n  /**\n   * Gets whether the collection is currently loading more data\n   */\n  public get isLoadingSubset(): boolean {\n    return this.pendingLoadSubsetPromises.size > 0\n  }\n\n  /**\n   * Tracks a load promise for isLoadingSubset state.\n   * @internal This is for internal coordination (e.g., live-query glue code), not for general use.\n   */\n  public trackLoadPromise(promise: Promise<void>): void {\n    const loadingStarting = !this.isLoadingSubset\n    this.pendingLoadSubsetPromises.add(promise)\n\n    if (loadingStarting) {\n      this._events.emit(`loadingSubset:change`, {\n        type: `loadingSubset:change`,\n        collection: this.collection,\n        isLoadingSubset: true,\n        previousIsLoadingSubset: false,\n        loadingSubsetTransition: `start`,\n      })\n    }\n\n    promise.finally(() => {\n      const loadingEnding =\n        this.pendingLoadSubsetPromises.size === 1 &&\n        this.pendingLoadSubsetPromises.has(promise)\n      this.pendingLoadSubsetPromises.delete(promise)\n\n      if (loadingEnding) {\n        this._events.emit(`loadingSubset:change`, {\n          type: `loadingSubset:change`,\n          collection: this.collection,\n          isLoadingSubset: false,\n          previousIsLoadingSubset: true,\n          loadingSubsetTransition: `end`,\n        })\n      }\n    })\n  }\n\n  /**\n   * Requests the sync layer to load more data.\n   * @param options Options to control what data is being loaded\n   * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.\n   *          Returns true if no sync function is configured, if syncMode is 'eager', or if there is no work to do.\n   */\n  public loadSubset(options: LoadSubsetOptions): Promise<void> | true {\n    // Bypass loadSubset when syncMode is 'eager'\n    if (this.syncMode === `eager`) {\n      return true\n    }\n\n    if (this.syncLoadSubsetFn) {\n      const result = this.syncLoadSubsetFn(options)\n      // If the result is a promise, track it\n      if (result instanceof Promise) {\n        this.trackLoadPromise(result)\n        return result\n      }\n    }\n\n    return true\n  }\n\n  /**\n   * Notifies the sync layer that a subset is no longer needed.\n   * @param options Options that identify what data is being unloaded\n   */\n  public unloadSubset(options: LoadSubsetOptions): void {\n    if (this.syncUnloadSubsetFn) {\n      this.syncUnloadSubsetFn(options)\n    }\n  }\n\n  public cleanup(): void {\n    try {\n      if (this.syncCleanupFn) {\n        this.syncCleanupFn()\n        this.syncCleanupFn = null\n      }\n    } catch (error) {\n      // Re-throw in a microtask to surface the error after cleanup completes\n      queueMicrotask(() => {\n        if (error instanceof Error) {\n          // Preserve the original error and stack trace\n          const wrappedError = new SyncCleanupError(this.id, error)\n          wrappedError.cause = error\n          wrappedError.stack = error.stack\n          throw wrappedError\n        } else {\n          throw new SyncCleanupError(this.id, error as Error | string)\n        }\n      })\n    }\n    this.preloadPromise = null\n  }\n}\n\nfunction normalizeSyncFnResult(result: void | CleanupFn | SyncConfigRes) {\n  if (typeof result === `function`) {\n    return { cleanup: result }\n  }\n\n  if (typeof result === `object`) {\n    return result\n  }\n\n  return undefined\n}\n"],"names":["NoPendingSyncTransactionWriteError","SyncTransactionAlreadyCommittedWriteError","deepEquals","utils","internal","LIVE_QUERY_INTERNAL","DuplicateKeySyncError","NoPendingSyncTransactionCommitError","SyncTransactionAlreadyCommittedError","CollectionConfigurationError","CollectionIsInErrorStateError","SyncCleanupError"],"mappings":"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"}

package/dist/cjs/collection/sync.d.cts

@@ -15,6 +15,7 @@ export declare class CollectionSyncManager<TOutput extends object = Record<strin
     preloadPromise: Promise<void> | null;
     syncCleanupFn: (() => void) | null;
     syncLoadSubsetFn: ((options: LoadSubsetOptions) => true | Promise<void>) | null;
+    syncUnloadSubsetFn: ((options: LoadSubsetOptions) => void) | null;
     private pendingLoadSubsetPromises;
     /**
      * Creates a new CollectionSyncManager instance
@@ -52,5 +53,10 @@ export declare class CollectionSyncManager<TOutput extends object = Record<strin
      *          Returns true if no sync function is configured, if syncMode is 'eager', or if there is no work to do.
      */
     loadSubset(options: LoadSubsetOptions): Promise<void> | true;
+    /**
+     * Notifies the sync layer that a subset is no longer needed.
+     * @param options Options that identify what data is being unloaded
+     */
+    unloadSubset(options: LoadSubsetOptions): void;
     cleanup(): void;
 }

package/dist/cjs/errors.cjs

@@ -288,6 +288,13 @@ class InvalidSourceError extends QueryBuilderError {
     );
   }
 }
+class InvalidSourceTypeError extends QueryBuilderError {
+  constructor(context, type) {
+    super(
+      `Invalid source for ${context}: Expected an object with a single key-value pair like { alias: collection }. For example: .from({ todos: todosCollection }). Got: ${type}`
+    );
+  }
+}
 class JoinConditionMustBeEqualityError extends QueryBuilderError {
   constructor() {
     super(`Join condition must be an equality expression`);
@@ -558,6 +565,7 @@ exports.InvalidJoinConditionSameSourceError = InvalidJoinConditionSameSourceErro
 exports.InvalidJoinConditionSourceMismatchError = InvalidJoinConditionSourceMismatchError;
 exports.InvalidSchemaError = InvalidSchemaError;
 exports.InvalidSourceError = InvalidSourceError;
+exports.InvalidSourceTypeError = InvalidSourceTypeError;
 exports.InvalidStorageDataFormatError = InvalidStorageDataFormatError;
 exports.InvalidStorageObjectFormatError = InvalidStorageObjectFormatError;
 exports.JoinCollectionNotFoundError = JoinCollectionNotFoundError;

package/dist/cjs/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.cjs","sources":["../../src/errors.ts"],"sourcesContent":["// Root error class for all TanStack DB errors\nexport class TanStackDBError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `TanStackDBError`\n  }\n}\n\n// Base error classes\nexport class NonRetriableError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n\n// Schema validation error (exported from index for backward compatibility)\nexport class SchemaValidationError extends TanStackDBError {\n  type: `insert` | `update`\n  issues: ReadonlyArray<{\n    message: string\n    path?: ReadonlyArray<string | number | symbol>\n  }>\n\n  constructor(\n    type: `insert` | `update`,\n    issues: ReadonlyArray<{\n      message: string\n      path?: ReadonlyArray<string | number | symbol>\n    }>,\n    message?: string\n  ) {\n    const defaultMessage = `${type === `insert` ? `Insert` : `Update`} validation failed: ${issues\n      .map((issue) => `\\n- ${issue.message} - path: ${issue.path}`)\n      .join(``)}`\n\n    super(message || defaultMessage)\n    this.name = `SchemaValidationError`\n    this.type = type\n    this.issues = issues\n  }\n}\n\n// Module Instance Errors\nexport class DuplicateDbInstanceError extends TanStackDBError {\n  constructor() {\n    super(\n      `Multiple instances of @tanstack/db detected!\\n\\n` +\n        `This causes transaction context to be lost because each instance maintains ` +\n        `its own transaction stack.\\n\\n` +\n        `Common causes:\\n` +\n        `1. Different versions of @tanstack/db installed\\n` +\n        `2. Incompatible peer dependency versions in packages\\n` +\n        `3. Module resolution issues in bundler configuration\\n\\n` +\n        `To fix:\\n` +\n        `1. Check installed versions: npm list @tanstack/db (or pnpm/yarn list)\\n` +\n        `2. Force a single version using package manager overrides:\\n` +\n        `   - npm: \"overrides\" in package.json\\n` +\n        `   - pnpm: \"pnpm.overrides\" in package.json\\n` +\n        `   - yarn: \"resolutions\" in package.json\\n` +\n        `3. Clear node_modules and lockfile, then reinstall\\n\\n` +\n        `To temporarily disable this check (not recommended):\\n` +\n        `Set environment variable: TANSTACK_DB_DISABLE_DUP_CHECK=1\\n\\n` +\n        `See: https://tanstack.com/db/latest/docs/troubleshooting#duplicate-instances`\n    )\n    this.name = `DuplicateDbInstanceError`\n  }\n}\n\n// Collection Configuration Errors\nexport class CollectionConfigurationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionConfigurationError`\n  }\n}\n\nexport class CollectionRequiresConfigError extends CollectionConfigurationError {\n  constructor() {\n    super(`Collection requires a config`)\n  }\n}\n\nexport class CollectionRequiresSyncConfigError extends CollectionConfigurationError {\n  constructor() {\n    super(`Collection requires a sync config`)\n  }\n}\n\nexport class InvalidSchemaError extends CollectionConfigurationError {\n  constructor() {\n    super(`Schema must implement the standard-schema interface`)\n  }\n}\n\nexport class SchemaMustBeSynchronousError extends CollectionConfigurationError {\n  constructor() {\n    super(`Schema validation must be synchronous`)\n  }\n}\n\n// Collection State Errors\nexport class CollectionStateError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionStateError`\n  }\n}\n\nexport class CollectionInErrorStateError extends CollectionStateError {\n  constructor(operation: string, collectionId: string) {\n    super(\n      `Cannot perform ${operation} on collection \"${collectionId}\" - collection is in error state. Try calling cleanup() and restarting the collection.`\n    )\n  }\n}\n\nexport class InvalidCollectionStatusTransitionError extends CollectionStateError {\n  constructor(from: string, to: string, collectionId: string) {\n    super(\n      `Invalid collection status transition from \"${from}\" to \"${to}\" for collection \"${collectionId}\"`\n    )\n  }\n}\n\nexport class CollectionIsInErrorStateError extends CollectionStateError {\n  constructor() {\n    super(`Collection is in error state`)\n  }\n}\n\nexport class NegativeActiveSubscribersError extends CollectionStateError {\n  constructor() {\n    super(`Active subscribers count is negative - this should never happen`)\n  }\n}\n\n// Collection Operation Errors\nexport class CollectionOperationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionOperationError`\n  }\n}\n\nexport class UndefinedKeyError extends CollectionOperationError {\n  constructor(item: any) {\n    super(\n      `An object was created without a defined key: ${JSON.stringify(item)}`\n    )\n  }\n}\n\nexport class DuplicateKeyError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `Cannot insert document with ID \"${key}\" because it already exists in the collection`\n    )\n  }\n}\n\nexport class DuplicateKeySyncError extends CollectionOperationError {\n  constructor(\n    key: string | number,\n    collectionId: string,\n    options?: { hasCustomGetKey?: boolean; hasJoins?: boolean }\n  ) {\n    const baseMessage = `Cannot insert document with key \"${key}\" from sync because it already exists in the collection \"${collectionId}\"`\n\n    // Provide enhanced guidance when custom getKey is used with joins\n    if (options?.hasCustomGetKey && options.hasJoins) {\n      super(\n        `${baseMessage}. ` +\n          `This collection uses a custom getKey with joined queries. ` +\n          `Joined queries can produce multiple rows with the same key when relationships are not 1:1. ` +\n          `Consider: (1) using a composite key in your getKey function (e.g., \\`\\${item.key1}-\\${item.key2}\\`), ` +\n          `(2) ensuring your join produces unique rows per key, or (3) removing the custom getKey ` +\n          `to use the default composite key behavior.`\n      )\n    } else {\n      super(baseMessage)\n    }\n  }\n}\n\nexport class MissingUpdateArgumentError extends CollectionOperationError {\n  constructor() {\n    super(`The first argument to update is missing`)\n  }\n}\n\nexport class NoKeysPassedToUpdateError extends CollectionOperationError {\n  constructor() {\n    super(`No keys were passed to update`)\n  }\n}\n\nexport class UpdateKeyNotFoundError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `The key \"${key}\" was passed to update but an object for this key was not found in the collection`\n    )\n  }\n}\n\nexport class KeyUpdateNotAllowedError extends CollectionOperationError {\n  constructor(originalKey: string | number, newKey: string | number) {\n    super(\n      `Updating the key of an item is not allowed. Original key: \"${originalKey}\", Attempted new key: \"${newKey}\". Please delete the old item and create a new one if a key change is necessary.`\n    )\n  }\n}\n\nexport class NoKeysPassedToDeleteError extends CollectionOperationError {\n  constructor() {\n    super(`No keys were passed to delete`)\n  }\n}\n\nexport class DeleteKeyNotFoundError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `Collection.delete was called with key '${key}' but there is no item in the collection with this key`\n    )\n  }\n}\n\n// Collection Handler Errors\nexport class MissingHandlerError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `MissingHandlerError`\n  }\n}\n\nexport class MissingInsertHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.insert called directly (not within an explicit transaction) but no 'onInsert' handler is configured.`\n    )\n  }\n}\n\nexport class MissingUpdateHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.update called directly (not within an explicit transaction) but no 'onUpdate' handler is configured.`\n    )\n  }\n}\n\nexport class MissingDeleteHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.delete called directly (not within an explicit transaction) but no 'onDelete' handler is configured.`\n    )\n  }\n}\n\n// Transaction Errors\nexport class TransactionError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `TransactionError`\n  }\n}\n\nexport class MissingMutationFunctionError extends TransactionError {\n  constructor() {\n    super(`mutationFn is required when creating a transaction`)\n  }\n}\n\nexport class OnMutateMustBeSynchronousError extends TransactionError {\n  constructor() {\n    super(\n      `onMutate must be synchronous and cannot return a promise. Remove async/await or returned promises from onMutate.`\n    )\n    this.name = `OnMutateMustBeSynchronousError`\n  }\n}\n\nexport class TransactionNotPendingMutateError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .mutate() as the transaction is no longer pending`\n    )\n  }\n}\n\nexport class TransactionAlreadyCompletedRollbackError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .rollback() as the transaction is already completed`\n    )\n  }\n}\n\nexport class TransactionNotPendingCommitError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .commit() as the transaction is no longer pending`\n    )\n  }\n}\n\nexport class NoPendingSyncTransactionWriteError extends TransactionError {\n  constructor() {\n    super(`No pending sync transaction to write to`)\n  }\n}\n\nexport class SyncTransactionAlreadyCommittedWriteError extends TransactionError {\n  constructor() {\n    super(\n      `The pending sync transaction is already committed, you can't still write to it.`\n    )\n  }\n}\n\nexport class NoPendingSyncTransactionCommitError extends TransactionError {\n  constructor() {\n    super(`No pending sync transaction to commit`)\n  }\n}\n\nexport class SyncTransactionAlreadyCommittedError extends TransactionError {\n  constructor() {\n    super(\n      `The pending sync transaction is already committed, you can't commit it again.`\n    )\n  }\n}\n\n// Query Builder Errors\nexport class QueryBuilderError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryBuilderError`\n  }\n}\n\nexport class OnlyOneSourceAllowedError extends QueryBuilderError {\n  constructor(context: string) {\n    super(`Only one source is allowed in the ${context}`)\n  }\n}\n\nexport class SubQueryMustHaveFromClauseError extends QueryBuilderError {\n  constructor(context: string) {\n    super(`A sub query passed to a ${context} must have a from clause itself`)\n  }\n}\n\nexport class InvalidSourceError extends QueryBuilderError {\n  constructor(alias: string) {\n    super(\n      `Invalid source for live query: The value provided for alias \"${alias}\" is not a Collection or subquery. Live queries only accept Collection instances or subqueries. Please ensure you're passing a valid Collection or QueryBuilder, not a plain array or other data type.`\n    )\n  }\n}\n\nexport class JoinConditionMustBeEqualityError extends QueryBuilderError {\n  constructor() {\n    super(`Join condition must be an equality expression`)\n  }\n}\n\nexport class QueryMustHaveFromClauseError extends QueryBuilderError {\n  constructor() {\n    super(`Query must have a from clause`)\n  }\n}\n\n// Query Compilation Errors\nexport class QueryCompilationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryCompilationError`\n  }\n}\n\nexport class DistinctRequiresSelectError extends QueryCompilationError {\n  constructor() {\n    super(`DISTINCT requires a SELECT clause.`)\n  }\n}\n\nexport class HavingRequiresGroupByError extends QueryCompilationError {\n  constructor() {\n    super(`HAVING clause requires GROUP BY clause`)\n  }\n}\n\nexport class LimitOffsetRequireOrderByError extends QueryCompilationError {\n  constructor() {\n    super(\n      `LIMIT and OFFSET require an ORDER BY clause to ensure deterministic results`\n    )\n  }\n}\n\n/**\n * Error thrown when a collection input stream is not found during query compilation.\n * In self-joins, each alias (e.g., 'employee', 'manager') requires its own input stream.\n */\nexport class CollectionInputNotFoundError extends QueryCompilationError {\n  constructor(\n    alias: string,\n    collectionId?: string,\n    availableKeys?: Array<string>\n  ) {\n    const details = collectionId\n      ? `alias \"${alias}\" (collection \"${collectionId}\")`\n      : `collection \"${alias}\"`\n    const availableKeysMsg = availableKeys?.length\n      ? `. Available keys: ${availableKeys.join(`, `)}`\n      : ``\n    super(`Input for ${details} not found in inputs map${availableKeysMsg}`)\n  }\n}\n\n/**\n * Error thrown when a subquery uses the same alias as its parent query.\n * This causes issues because parent and subquery would share the same input streams,\n * leading to empty results or incorrect data (aggregation cross-leaking).\n */\nexport class DuplicateAliasInSubqueryError extends QueryCompilationError {\n  constructor(alias: string, parentAliases: Array<string>) {\n    super(\n      `Subquery uses alias \"${alias}\" which is already used in the parent query. ` +\n        `Each alias must be unique across parent and subquery contexts. ` +\n        `Parent query aliases: ${parentAliases.join(`, `)}. ` +\n        `Please rename \"${alias}\" in either the parent query or subquery to avoid conflicts.`\n    )\n  }\n}\n\nexport class UnsupportedFromTypeError extends QueryCompilationError {\n  constructor(type: string) {\n    super(`Unsupported FROM type: ${type}`)\n  }\n}\n\nexport class UnknownExpressionTypeError extends QueryCompilationError {\n  constructor(type: string) {\n    super(`Unknown expression type: ${type}`)\n  }\n}\n\nexport class EmptyReferencePathError extends QueryCompilationError {\n  constructor() {\n    super(`Reference path cannot be empty`)\n  }\n}\n\nexport class UnknownFunctionError extends QueryCompilationError {\n  constructor(functionName: string) {\n    super(`Unknown function: ${functionName}`)\n  }\n}\n\nexport class JoinCollectionNotFoundError extends QueryCompilationError {\n  constructor(collectionId: string) {\n    super(`Collection \"${collectionId}\" not found during compilation of join`)\n  }\n}\n\n// JOIN Operation Errors\nexport class JoinError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `JoinError`\n  }\n}\n\nexport class UnsupportedJoinTypeError extends JoinError {\n  constructor(joinType: string) {\n    super(`Unsupported join type: ${joinType}`)\n  }\n}\n\nexport class InvalidJoinConditionSameSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: both expressions refer to the same source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinConditionSourceMismatchError extends JoinError {\n  constructor() {\n    super(`Invalid join condition: expressions must reference source aliases`)\n  }\n}\n\nexport class InvalidJoinConditionLeftSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: left expression refers to an unavailable source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinConditionRightSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: right expression does not refer to the joined source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinCondition extends JoinError {\n  constructor() {\n    super(`Invalid join condition`)\n  }\n}\n\nexport class UnsupportedJoinSourceTypeError extends JoinError {\n  constructor(type: string) {\n    super(`Unsupported join source type: ${type}`)\n  }\n}\n\n// GROUP BY and Aggregation Errors\nexport class GroupByError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `GroupByError`\n  }\n}\n\nexport class NonAggregateExpressionNotInGroupByError extends GroupByError {\n  constructor(alias: string) {\n    super(\n      `Non-aggregate expression '${alias}' in SELECT must also appear in GROUP BY clause`\n    )\n  }\n}\n\nexport class UnsupportedAggregateFunctionError extends GroupByError {\n  constructor(functionName: string) {\n    super(`Unsupported aggregate function: ${functionName}`)\n  }\n}\n\nexport class AggregateFunctionNotInSelectError extends GroupByError {\n  constructor(functionName: string) {\n    super(\n      `Aggregate function in HAVING clause must also be in SELECT clause: ${functionName}`\n    )\n  }\n}\n\nexport class UnknownHavingExpressionTypeError extends GroupByError {\n  constructor(type: string) {\n    super(`Unknown expression type in HAVING clause: ${type}`)\n  }\n}\n\n// Storage Errors\nexport class StorageError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `StorageError`\n  }\n}\n\nexport class SerializationError extends StorageError {\n  constructor(operation: string, originalError: string) {\n    super(\n      `Cannot ${operation} item because it cannot be JSON serialized: ${originalError}`\n    )\n  }\n}\n\n// LocalStorage Collection Errors\nexport class LocalStorageCollectionError extends StorageError {\n  constructor(message: string) {\n    super(message)\n    this.name = `LocalStorageCollectionError`\n  }\n}\n\nexport class StorageKeyRequiredError extends LocalStorageCollectionError {\n  constructor() {\n    super(`[LocalStorageCollection] storageKey must be provided.`)\n  }\n}\n\nexport class InvalidStorageDataFormatError extends LocalStorageCollectionError {\n  constructor(storageKey: string, key: string) {\n    super(\n      `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\" for key \"${key}\".`\n    )\n  }\n}\n\nexport class InvalidStorageObjectFormatError extends LocalStorageCollectionError {\n  constructor(storageKey: string) {\n    super(\n      `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\". Expected object format.`\n    )\n  }\n}\n\n// Sync Cleanup Errors\nexport class SyncCleanupError extends TanStackDBError {\n  constructor(collectionId: string, error: Error | string) {\n    const message = error instanceof Error ? error.message : String(error)\n    super(\n      `Collection \"${collectionId}\" sync cleanup function threw an error: ${message}`\n    )\n    this.name = `SyncCleanupError`\n  }\n}\n\n// Query Optimizer Errors\nexport class QueryOptimizerError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryOptimizerError`\n  }\n}\n\nexport class CannotCombineEmptyExpressionListError extends QueryOptimizerError {\n  constructor() {\n    super(`Cannot combine empty expression list`)\n  }\n}\n\n/**\n * Internal error when the query optimizer fails to convert a WHERE clause to a collection filter.\n */\nexport class WhereClauseConversionError extends QueryOptimizerError {\n  constructor(collectionId: string, alias: string) {\n    super(\n      `Failed to convert WHERE clause to collection filter for collection '${collectionId}' alias '${alias}'. This indicates a bug in the query optimization logic.`\n    )\n  }\n}\n\n/**\n * Error when a subscription cannot be found during lazy join processing.\n * For subqueries, aliases may be remapped (e.g., 'activeUser' → 'user').\n */\nexport class SubscriptionNotFoundError extends QueryCompilationError {\n  constructor(\n    resolvedAlias: string,\n    originalAlias: string,\n    collectionId: string,\n    availableAliases: Array<string>\n  ) {\n    super(\n      `Internal error: subscription for alias '${resolvedAlias}' (remapped from '${originalAlias}', collection '${collectionId}') is missing in join pipeline. Available aliases: ${availableAliases.join(`, `)}. This indicates a bug in alias tracking.`\n    )\n  }\n}\n\n/**\n * Error thrown when aggregate expressions are used outside of a GROUP BY context.\n */\nexport class AggregateNotSupportedError extends QueryCompilationError {\n  constructor() {\n    super(\n      `Aggregate expressions are not supported in this context. Use GROUP BY clause for aggregates.`\n    )\n  }\n}\n\n/**\n * Internal error when the compiler returns aliases that don't have corresponding input streams.\n * This should never happen since all aliases come from user declarations.\n */\nexport class MissingAliasInputsError extends QueryCompilationError {\n  constructor(missingAliases: Array<string>) {\n    super(\n      `Internal error: compiler returned aliases without inputs: ${missingAliases.join(`, `)}. ` +\n        `This indicates a bug in query compilation. Please report this issue.`\n    )\n  }\n}\n\n/**\n * Error thrown when setWindow is called on a collection without an ORDER BY clause.\n */\nexport class SetWindowRequiresOrderByError extends QueryCompilationError {\n  constructor() {\n    super(\n      `setWindow() can only be called on collections with an ORDER BY clause. ` +\n        `Add .orderBy() to your query to enable window movement.`\n    )\n  }\n}\n"],"names":[],"mappings":";;AACO,MAAM,wBAAwB,MAAM;AAAA,EACzC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAGO,MAAM,0BAA0B,gBAAgB;AAAA,EACrD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAGO,MAAM,8BAA8B,gBAAgB;AAAA,EAOzD,YACE,MACA,QAIA,SACA;AACA,UAAM,iBAAiB,GAAG,SAAS,WAAW,WAAW,QAAQ,uBAAuB,OACrF,IAAI,CAAC,UAAU;AAAA,IAAO,MAAM,OAAO,YAAY,MAAM,IAAI,EAAE,EAC3D,KAAK,EAAE,CAAC;AAEX,UAAM,WAAW,cAAc;AAC/B,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AACF;AAGO,MAAM,iCAAiC,gBAAgB;AAAA,EAC5D,cAAc;AACZ;AAAA,MACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAA;AAkBF,SAAK,OAAO;AAAA,EACd;AACF;AAGO,MAAM,qCAAqC,gBAAgB;AAAA,EAChE,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,sCAAsC,6BAA6B;AAAA,EAC9E,cAAc;AACZ,UAAM,8BAA8B;AAAA,EACtC;AACF;AAEO,MAAM,0CAA0C,6BAA6B;AAAA,EAClF,cAAc;AACZ,UAAM,mCAAmC;AAAA,EAC3C;AACF;AAEO,MAAM,2BAA2B,6BAA6B;AAAA,EACnE,cAAc;AACZ,UAAM,qDAAqD;AAAA,EAC7D;AACF;AAEO,MAAM,qCAAqC,6BAA6B;AAAA,EAC7E,cAAc;AACZ,UAAM,uCAAuC;AAAA,EAC/C;AACF;AAGO,MAAM,6BAA6B,gBAAgB;AAAA,EACxD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,oCAAoC,qBAAqB;AAAA,EACpE,YAAY,WAAmB,cAAsB;AACnD;AAAA,MACE,kBAAkB,SAAS,mBAAmB,YAAY;AAAA,IAAA;AAAA,EAE9D;AACF;AAEO,MAAM,+CAA+C,qBAAqB;AAAA,EAC/E,YAAY,MAAc,IAAY,cAAsB;AAC1D;AAAA,MACE,8CAA8C,IAAI,SAAS,EAAE,qBAAqB,YAAY;AAAA,IAAA;AAAA,EAElG;AACF;AAEO,MAAM,sCAAsC,qBAAqB;AAAA,EACtE,cAAc;AACZ,UAAM,8BAA8B;AAAA,EACtC;AACF;AAEO,MAAM,uCAAuC,qBAAqB;AAAA,EACvE,cAAc;AACZ,UAAM,iEAAiE;AAAA,EACzE;AACF;AAGO,MAAM,iCAAiC,gBAAgB;AAAA,EAC5D,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,0BAA0B,yBAAyB;AAAA,EAC9D,YAAY,MAAW;AACrB;AAAA,MACE,gDAAgD,KAAK,UAAU,IAAI,CAAC;AAAA,IAAA;AAAA,EAExE;AACF;AAEO,MAAM,0BAA0B,yBAAyB;AAAA,EAC9D,YAAY,KAAsB;AAChC;AAAA,MACE,mCAAmC,GAAG;AAAA,IAAA;AAAA,EAE1C;AACF;AAEO,MAAM,8BAA8B,yBAAyB;AAAA,EAClE,YACE,KACA,cACA,SACA;AACA,UAAM,cAAc,oCAAoC,GAAG,4DAA4D,YAAY;AAGnI,QAAI,SAAS,mBAAmB,QAAQ,UAAU;AAChD;AAAA,QACE,GAAG,WAAW;AAAA,MAAA;AAAA,IAOlB,OAAO;AACL,YAAM,WAAW;AAAA,IACnB;AAAA,EACF;AACF;AAEO,MAAM,mCAAmC,yBAAyB;AAAA,EACvE,cAAc;AACZ,UAAM,yCAAyC;AAAA,EACjD;AACF;AAEO,MAAM,kCAAkC,yBAAyB;AAAA,EACtE,cAAc;AACZ,UAAM,+BAA+B;AAAA,EACvC;AACF;AAEO,MAAM,+BAA+B,yBAAyB;AAAA,EACnE,YAAY,KAAsB;AAChC;AAAA,MACE,YAAY,GAAG;AAAA,IAAA;AAAA,EAEnB;AACF;AAEO,MAAM,iCAAiC,yBAAyB;AAAA,EACrE,YAAY,aAA8B,QAAyB;AACjE;AAAA,MACE,8DAA8D,WAAW,0BAA0B,MAAM;AAAA,IAAA;AAAA,EAE7G;AACF;AAEO,MAAM,kCAAkC,yBAAyB;AAAA,EACtE,cAAc;AACZ,UAAM,+BAA+B;AAAA,EACvC;AACF;AAEO,MAAM,+BAA+B,yBAAyB;AAAA,EACnE,YAAY,KAAsB;AAChC;AAAA,MACE,0CAA0C,GAAG;AAAA,IAAA;AAAA,EAEjD;AACF;AAGO,MAAM,4BAA4B,gBAAgB;AAAA,EACvD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,kCAAkC,oBAAoB;AAAA,EACjE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAEO,MAAM,kCAAkC,oBAAoB;AAAA,EACjE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAEO,MAAM,kCAAkC,oBAAoB;AAAA,EACjE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAGO,MAAM,yBAAyB,gBAAgB;AAAA,EACpD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,qCAAqC,iBAAiB;AAAA,EACjE,cAAc;AACZ,UAAM,oDAAoD;AAAA,EAC5D;AACF;AAEO,MAAM,uCAAuC,iBAAiB;AAAA,EACnE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAEF,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,yCAAyC,iBAAiB;AAAA,EACrE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAEO,MAAM,iDAAiD,iBAAiB;AAAA,EAC7E,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAEO,MAAM,yCAAyC,iBAAiB;AAAA,EACrE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAEO,MAAM,2CAA2C,iBAAiB;AAAA,EACvE,cAAc;AACZ,UAAM,yCAAyC;AAAA,EACjD;AACF;AAEO,MAAM,kDAAkD,iBAAiB;AAAA,EAC9E,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAEO,MAAM,4CAA4C,iBAAiB;AAAA,EACxE,cAAc;AACZ,UAAM,uCAAuC;AAAA,EAC/C;AACF;AAEO,MAAM,6CAA6C,iBAAiB;AAAA,EACzE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAGO,MAAM,0BAA0B,gBAAgB;AAAA,EACrD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,kCAAkC,kBAAkB;AAAA,EAC/D,YAAY,SAAiB;AAC3B,UAAM,qCAAqC,OAAO,EAAE;AAAA,EACtD;AACF;AAEO,MAAM,wCAAwC,kBAAkB;AAAA,EACrE,YAAY,SAAiB;AAC3B,UAAM,2BAA2B,OAAO,iCAAiC;AAAA,EAC3E;AACF;AAEO,MAAM,2BAA2B,kBAAkB;AAAA,EACxD,YAAY,OAAe;AACzB;AAAA,MACE,gEAAgE,KAAK;AAAA,IAAA;AAAA,EAEzE;AACF;AAEO,MAAM,yCAAyC,kBAAkB;AAAA,EACtE,cAAc;AACZ,UAAM,+CAA+C;AAAA,EACvD;AACF;AAEO,MAAM,qCAAqC,kBAAkB;AAAA,EAClE,cAAc;AACZ,UAAM,+BAA+B;AAAA,EACvC;AACF;AAGO,MAAM,8BAA8B,gBAAgB;AAAA,EACzD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,oCAAoC,sBAAsB;AAAA,EACrE,cAAc;AACZ,UAAM,oCAAoC;AAAA,EAC5C;AACF;AAEO,MAAM,mCAAmC,sBAAsB;AAAA,EACpE,cAAc;AACZ,UAAM,wCAAwC;AAAA,EAChD;AACF;AAEO,MAAM,uCAAuC,sBAAsB;AAAA,EACxE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAMO,MAAM,qCAAqC,sBAAsB;AAAA,EACtE,YACE,OACA,cACA,eACA;AACA,UAAM,UAAU,eACZ,UAAU,KAAK,kBAAkB,YAAY,OAC7C,eAAe,KAAK;AACxB,UAAM,mBAAmB,eAAe,SACpC,qBAAqB,cAAc,KAAK,IAAI,CAAC,KAC7C;AACJ,UAAM,aAAa,OAAO,2BAA2B,gBAAgB,EAAE;AAAA,EACzE;AACF;AAOO,MAAM,sCAAsC,sBAAsB;AAAA,EACvE,YAAY,OAAe,eAA8B;AACvD;AAAA,MACE,wBAAwB,KAAK,qIAEF,cAAc,KAAK,IAAI,CAAC,oBAC/B,KAAK;AAAA,IAAA;AAAA,EAE7B;AACF;AAEO,MAAM,iCAAiC,sBAAsB;AAAA,EAClE,YAAY,MAAc;AACxB,UAAM,0BAA0B,IAAI,EAAE;AAAA,EACxC;AACF;AAEO,MAAM,mCAAmC,sBAAsB;AAAA,EACpE,YAAY,MAAc;AACxB,UAAM,4BAA4B,IAAI,EAAE;AAAA,EAC1C;AACF;AAEO,MAAM,gCAAgC,sBAAsB;AAAA,EACjE,cAAc;AACZ,UAAM,gCAAgC;AAAA,EACxC;AACF;AAEO,MAAM,6BAA6B,sBAAsB;AAAA,EAC9D,YAAY,cAAsB;AAChC,UAAM,qBAAqB,YAAY,EAAE;AAAA,EAC3C;AACF;AAEO,MAAM,oCAAoC,sBAAsB;AAAA,EACrE,YAAY,cAAsB;AAChC,UAAM,eAAe,YAAY,wCAAwC;AAAA,EAC3E;AACF;AAGO,MAAM,kBAAkB,gBAAgB;AAAA,EAC7C,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,iCAAiC,UAAU;AAAA,EACtD,YAAY,UAAkB;AAC5B,UAAM,0BAA0B,QAAQ,EAAE;AAAA,EAC5C;AACF;AAEO,MAAM,4CAA4C,UAAU;AAAA,EACjE,YAAY,aAAqB;AAC/B;AAAA,MACE,sEAAsE,WAAW;AAAA,IAAA;AAAA,EAErF;AACF;AAEO,MAAM,gDAAgD,UAAU;AAAA,EACrE,cAAc;AACZ,UAAM,mEAAmE;AAAA,EAC3E;AACF;AAEO,MAAM,4CAA4C,UAAU;AAAA,EACjE,YAAY,aAAqB;AAC/B;AAAA,MACE,4EAA4E,WAAW;AAAA,IAAA;AAAA,EAE3F;AACF;AAEO,MAAM,6CAA6C,UAAU;AAAA,EAClE,YAAY,aAAqB;AAC/B;AAAA,MACE,iFAAiF,WAAW;AAAA,IAAA;AAAA,EAEhG;AACF;AAEO,MAAM,6BAA6B,UAAU;AAAA,EAClD,cAAc;AACZ,UAAM,wBAAwB;AAAA,EAChC;AACF;AAEO,MAAM,uCAAuC,UAAU;AAAA,EAC5D,YAAY,MAAc;AACxB,UAAM,iCAAiC,IAAI,EAAE;AAAA,EAC/C;AACF;AAGO,MAAM,qBAAqB,gBAAgB;AAAA,EAChD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,gDAAgD,aAAa;AAAA,EACxE,YAAY,OAAe;AACzB;AAAA,MACE,6BAA6B,KAAK;AAAA,IAAA;AAAA,EAEtC;AACF;AAEO,MAAM,0CAA0C,aAAa;AAAA,EAClE,YAAY,cAAsB;AAChC,UAAM,mCAAmC,YAAY,EAAE;AAAA,EACzD;AACF;AAEO,MAAM,0CAA0C,aAAa;AAAA,EAClE,YAAY,cAAsB;AAChC;AAAA,MACE,sEAAsE,YAAY;AAAA,IAAA;AAAA,EAEtF;AACF;AAEO,MAAM,yCAAyC,aAAa;AAAA,EACjE,YAAY,MAAc;AACxB,UAAM,6CAA6C,IAAI,EAAE;AAAA,EAC3D;AACF;AAGO,MAAM,qBAAqB,gBAAgB;AAAA,EAChD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,2BAA2B,aAAa;AAAA,EACnD,YAAY,WAAmB,eAAuB;AACpD;AAAA,MACE,UAAU,SAAS,+CAA+C,aAAa;AAAA,IAAA;AAAA,EAEnF;AACF;AAGO,MAAM,oCAAoC,aAAa;AAAA,EAC5D,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,gCAAgC,4BAA4B;AAAA,EACvE,cAAc;AACZ,UAAM,uDAAuD;AAAA,EAC/D;AACF;AAEO,MAAM,sCAAsC,4BAA4B;AAAA,EAC7E,YAAY,YAAoB,KAAa;AAC3C;AAAA,MACE,gEAAgE,UAAU,cAAc,GAAG;AAAA,IAAA;AAAA,EAE/F;AACF;AAEO,MAAM,wCAAwC,4BAA4B;AAAA,EAC/E,YAAY,YAAoB;AAC9B;AAAA,MACE,gEAAgE,UAAU;AAAA,IAAA;AAAA,EAE9E;AACF;AAGO,MAAM,yBAAyB,gBAAgB;AAAA,EACpD,YAAY,cAAsB,OAAuB;AACvD,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE;AAAA,MACE,eAAe,YAAY,2CAA2C,OAAO;AAAA,IAAA;AAE/E,SAAK,OAAO;AAAA,EACd;AACF;AAGO,MAAM,4BAA4B,gBAAgB;AAAA,EACvD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,8CAA8C,oBAAoB;AAAA,EAC7E,cAAc;AACZ,UAAM,sCAAsC;AAAA,EAC9C;AACF;AAKO,MAAM,mCAAmC,oBAAoB;AAAA,EAClE,YAAY,cAAsB,OAAe;AAC/C;AAAA,MACE,uEAAuE,YAAY,YAAY,KAAK;AAAA,IAAA;AAAA,EAExG;AACF;AAMO,MAAM,kCAAkC,sBAAsB;AAAA,EACnE,YACE,eACA,eACA,cACA,kBACA;AACA;AAAA,MACE,2CAA2C,aAAa,qBAAqB,aAAa,kBAAkB,YAAY,sDAAsD,iBAAiB,KAAK,IAAI,CAAC;AAAA,IAAA;AAAA,EAE7M;AACF;AAKO,MAAM,mCAAmC,sBAAsB;AAAA,EACpE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAEJ;AACF;AAMO,MAAM,gCAAgC,sBAAsB;AAAA,EACjE,YAAY,gBAA+B;AACzC;AAAA,MACE,6DAA6D,eAAe,KAAK,IAAI,CAAC;AAAA,IAAA;AAAA,EAG1F;AACF;AAKO,MAAM,sCAAsC,sBAAsB;AAAA,EACvE,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAAA,EAGJ;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"errors.cjs","sources":["../../src/errors.ts"],"sourcesContent":["// Root error class for all TanStack DB errors\nexport class TanStackDBError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `TanStackDBError`\n  }\n}\n\n// Base error classes\nexport class NonRetriableError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n\n// Schema validation error (exported from index for backward compatibility)\nexport class SchemaValidationError extends TanStackDBError {\n  type: `insert` | `update`\n  issues: ReadonlyArray<{\n    message: string\n    path?: ReadonlyArray<string | number | symbol>\n  }>\n\n  constructor(\n    type: `insert` | `update`,\n    issues: ReadonlyArray<{\n      message: string\n      path?: ReadonlyArray<string | number | symbol>\n    }>,\n    message?: string\n  ) {\n    const defaultMessage = `${type === `insert` ? `Insert` : `Update`} validation failed: ${issues\n      .map((issue) => `\\n- ${issue.message} - path: ${issue.path}`)\n      .join(``)}`\n\n    super(message || defaultMessage)\n    this.name = `SchemaValidationError`\n    this.type = type\n    this.issues = issues\n  }\n}\n\n// Module Instance Errors\nexport class DuplicateDbInstanceError extends TanStackDBError {\n  constructor() {\n    super(\n      `Multiple instances of @tanstack/db detected!\\n\\n` +\n        `This causes transaction context to be lost because each instance maintains ` +\n        `its own transaction stack.\\n\\n` +\n        `Common causes:\\n` +\n        `1. Different versions of @tanstack/db installed\\n` +\n        `2. Incompatible peer dependency versions in packages\\n` +\n        `3. Module resolution issues in bundler configuration\\n\\n` +\n        `To fix:\\n` +\n        `1. Check installed versions: npm list @tanstack/db (or pnpm/yarn list)\\n` +\n        `2. Force a single version using package manager overrides:\\n` +\n        `   - npm: \"overrides\" in package.json\\n` +\n        `   - pnpm: \"pnpm.overrides\" in package.json\\n` +\n        `   - yarn: \"resolutions\" in package.json\\n` +\n        `3. Clear node_modules and lockfile, then reinstall\\n\\n` +\n        `To temporarily disable this check (not recommended):\\n` +\n        `Set environment variable: TANSTACK_DB_DISABLE_DUP_CHECK=1\\n\\n` +\n        `See: https://tanstack.com/db/latest/docs/troubleshooting#duplicate-instances`\n    )\n    this.name = `DuplicateDbInstanceError`\n  }\n}\n\n// Collection Configuration Errors\nexport class CollectionConfigurationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionConfigurationError`\n  }\n}\n\nexport class CollectionRequiresConfigError extends CollectionConfigurationError {\n  constructor() {\n    super(`Collection requires a config`)\n  }\n}\n\nexport class CollectionRequiresSyncConfigError extends CollectionConfigurationError {\n  constructor() {\n    super(`Collection requires a sync config`)\n  }\n}\n\nexport class InvalidSchemaError extends CollectionConfigurationError {\n  constructor() {\n    super(`Schema must implement the standard-schema interface`)\n  }\n}\n\nexport class SchemaMustBeSynchronousError extends CollectionConfigurationError {\n  constructor() {\n    super(`Schema validation must be synchronous`)\n  }\n}\n\n// Collection State Errors\nexport class CollectionStateError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionStateError`\n  }\n}\n\nexport class CollectionInErrorStateError extends CollectionStateError {\n  constructor(operation: string, collectionId: string) {\n    super(\n      `Cannot perform ${operation} on collection \"${collectionId}\" - collection is in error state. Try calling cleanup() and restarting the collection.`\n    )\n  }\n}\n\nexport class InvalidCollectionStatusTransitionError extends CollectionStateError {\n  constructor(from: string, to: string, collectionId: string) {\n    super(\n      `Invalid collection status transition from \"${from}\" to \"${to}\" for collection \"${collectionId}\"`\n    )\n  }\n}\n\nexport class CollectionIsInErrorStateError extends CollectionStateError {\n  constructor() {\n    super(`Collection is in error state`)\n  }\n}\n\nexport class NegativeActiveSubscribersError extends CollectionStateError {\n  constructor() {\n    super(`Active subscribers count is negative - this should never happen`)\n  }\n}\n\n// Collection Operation Errors\nexport class CollectionOperationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionOperationError`\n  }\n}\n\nexport class UndefinedKeyError extends CollectionOperationError {\n  constructor(item: any) {\n    super(\n      `An object was created without a defined key: ${JSON.stringify(item)}`\n    )\n  }\n}\n\nexport class DuplicateKeyError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `Cannot insert document with ID \"${key}\" because it already exists in the collection`\n    )\n  }\n}\n\nexport class DuplicateKeySyncError extends CollectionOperationError {\n  constructor(\n    key: string | number,\n    collectionId: string,\n    options?: { hasCustomGetKey?: boolean; hasJoins?: boolean }\n  ) {\n    const baseMessage = `Cannot insert document with key \"${key}\" from sync because it already exists in the collection \"${collectionId}\"`\n\n    // Provide enhanced guidance when custom getKey is used with joins\n    if (options?.hasCustomGetKey && options.hasJoins) {\n      super(\n        `${baseMessage}. ` +\n          `This collection uses a custom getKey with joined queries. ` +\n          `Joined queries can produce multiple rows with the same key when relationships are not 1:1. ` +\n          `Consider: (1) using a composite key in your getKey function (e.g., \\`\\${item.key1}-\\${item.key2}\\`), ` +\n          `(2) ensuring your join produces unique rows per key, or (3) removing the custom getKey ` +\n          `to use the default composite key behavior.`\n      )\n    } else {\n      super(baseMessage)\n    }\n  }\n}\n\nexport class MissingUpdateArgumentError extends CollectionOperationError {\n  constructor() {\n    super(`The first argument to update is missing`)\n  }\n}\n\nexport class NoKeysPassedToUpdateError extends CollectionOperationError {\n  constructor() {\n    super(`No keys were passed to update`)\n  }\n}\n\nexport class UpdateKeyNotFoundError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `The key \"${key}\" was passed to update but an object for this key was not found in the collection`\n    )\n  }\n}\n\nexport class KeyUpdateNotAllowedError extends CollectionOperationError {\n  constructor(originalKey: string | number, newKey: string | number) {\n    super(\n      `Updating the key of an item is not allowed. Original key: \"${originalKey}\", Attempted new key: \"${newKey}\". Please delete the old item and create a new one if a key change is necessary.`\n    )\n  }\n}\n\nexport class NoKeysPassedToDeleteError extends CollectionOperationError {\n  constructor() {\n    super(`No keys were passed to delete`)\n  }\n}\n\nexport class DeleteKeyNotFoundError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `Collection.delete was called with key '${key}' but there is no item in the collection with this key`\n    )\n  }\n}\n\n// Collection Handler Errors\nexport class MissingHandlerError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `MissingHandlerError`\n  }\n}\n\nexport class MissingInsertHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.insert called directly (not within an explicit transaction) but no 'onInsert' handler is configured.`\n    )\n  }\n}\n\nexport class MissingUpdateHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.update called directly (not within an explicit transaction) but no 'onUpdate' handler is configured.`\n    )\n  }\n}\n\nexport class MissingDeleteHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.delete called directly (not within an explicit transaction) but no 'onDelete' handler is configured.`\n    )\n  }\n}\n\n// Transaction Errors\nexport class TransactionError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `TransactionError`\n  }\n}\n\nexport class MissingMutationFunctionError extends TransactionError {\n  constructor() {\n    super(`mutationFn is required when creating a transaction`)\n  }\n}\n\nexport class OnMutateMustBeSynchronousError extends TransactionError {\n  constructor() {\n    super(\n      `onMutate must be synchronous and cannot return a promise. Remove async/await or returned promises from onMutate.`\n    )\n    this.name = `OnMutateMustBeSynchronousError`\n  }\n}\n\nexport class TransactionNotPendingMutateError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .mutate() as the transaction is no longer pending`\n    )\n  }\n}\n\nexport class TransactionAlreadyCompletedRollbackError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .rollback() as the transaction is already completed`\n    )\n  }\n}\n\nexport class TransactionNotPendingCommitError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .commit() as the transaction is no longer pending`\n    )\n  }\n}\n\nexport class NoPendingSyncTransactionWriteError extends TransactionError {\n  constructor() {\n    super(`No pending sync transaction to write to`)\n  }\n}\n\nexport class SyncTransactionAlreadyCommittedWriteError extends TransactionError {\n  constructor() {\n    super(\n      `The pending sync transaction is already committed, you can't still write to it.`\n    )\n  }\n}\n\nexport class NoPendingSyncTransactionCommitError extends TransactionError {\n  constructor() {\n    super(`No pending sync transaction to commit`)\n  }\n}\n\nexport class SyncTransactionAlreadyCommittedError extends TransactionError {\n  constructor() {\n    super(\n      `The pending sync transaction is already committed, you can't commit it again.`\n    )\n  }\n}\n\n// Query Builder Errors\nexport class QueryBuilderError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryBuilderError`\n  }\n}\n\nexport class OnlyOneSourceAllowedError extends QueryBuilderError {\n  constructor(context: string) {\n    super(`Only one source is allowed in the ${context}`)\n  }\n}\n\nexport class SubQueryMustHaveFromClauseError extends QueryBuilderError {\n  constructor(context: string) {\n    super(`A sub query passed to a ${context} must have a from clause itself`)\n  }\n}\n\nexport class InvalidSourceError extends QueryBuilderError {\n  constructor(alias: string) {\n    super(\n      `Invalid source for live query: The value provided for alias \"${alias}\" is not a Collection or subquery. Live queries only accept Collection instances or subqueries. Please ensure you're passing a valid Collection or QueryBuilder, not a plain array or other data type.`\n    )\n  }\n}\n\nexport class InvalidSourceTypeError extends QueryBuilderError {\n  constructor(context: string, type: string) {\n    super(\n      `Invalid source for ${context}: Expected an object with a single key-value pair like { alias: collection }. ` +\n        `For example: .from({ todos: todosCollection }). Got: ${type}`\n    )\n  }\n}\n\nexport class JoinConditionMustBeEqualityError extends QueryBuilderError {\n  constructor() {\n    super(`Join condition must be an equality expression`)\n  }\n}\n\nexport class QueryMustHaveFromClauseError extends QueryBuilderError {\n  constructor() {\n    super(`Query must have a from clause`)\n  }\n}\n\n// Query Compilation Errors\nexport class QueryCompilationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryCompilationError`\n  }\n}\n\nexport class DistinctRequiresSelectError extends QueryCompilationError {\n  constructor() {\n    super(`DISTINCT requires a SELECT clause.`)\n  }\n}\n\nexport class HavingRequiresGroupByError extends QueryCompilationError {\n  constructor() {\n    super(`HAVING clause requires GROUP BY clause`)\n  }\n}\n\nexport class LimitOffsetRequireOrderByError extends QueryCompilationError {\n  constructor() {\n    super(\n      `LIMIT and OFFSET require an ORDER BY clause to ensure deterministic results`\n    )\n  }\n}\n\n/**\n * Error thrown when a collection input stream is not found during query compilation.\n * In self-joins, each alias (e.g., 'employee', 'manager') requires its own input stream.\n */\nexport class CollectionInputNotFoundError extends QueryCompilationError {\n  constructor(\n    alias: string,\n    collectionId?: string,\n    availableKeys?: Array<string>\n  ) {\n    const details = collectionId\n      ? `alias \"${alias}\" (collection \"${collectionId}\")`\n      : `collection \"${alias}\"`\n    const availableKeysMsg = availableKeys?.length\n      ? `. Available keys: ${availableKeys.join(`, `)}`\n      : ``\n    super(`Input for ${details} not found in inputs map${availableKeysMsg}`)\n  }\n}\n\n/**\n * Error thrown when a subquery uses the same alias as its parent query.\n * This causes issues because parent and subquery would share the same input streams,\n * leading to empty results or incorrect data (aggregation cross-leaking).\n */\nexport class DuplicateAliasInSubqueryError extends QueryCompilationError {\n  constructor(alias: string, parentAliases: Array<string>) {\n    super(\n      `Subquery uses alias \"${alias}\" which is already used in the parent query. ` +\n        `Each alias must be unique across parent and subquery contexts. ` +\n        `Parent query aliases: ${parentAliases.join(`, `)}. ` +\n        `Please rename \"${alias}\" in either the parent query or subquery to avoid conflicts.`\n    )\n  }\n}\n\nexport class UnsupportedFromTypeError extends QueryCompilationError {\n  constructor(type: string) {\n    super(`Unsupported FROM type: ${type}`)\n  }\n}\n\nexport class UnknownExpressionTypeError extends QueryCompilationError {\n  constructor(type: string) {\n    super(`Unknown expression type: ${type}`)\n  }\n}\n\nexport class EmptyReferencePathError extends QueryCompilationError {\n  constructor() {\n    super(`Reference path cannot be empty`)\n  }\n}\n\nexport class UnknownFunctionError extends QueryCompilationError {\n  constructor(functionName: string) {\n    super(`Unknown function: ${functionName}`)\n  }\n}\n\nexport class JoinCollectionNotFoundError extends QueryCompilationError {\n  constructor(collectionId: string) {\n    super(`Collection \"${collectionId}\" not found during compilation of join`)\n  }\n}\n\n// JOIN Operation Errors\nexport class JoinError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `JoinError`\n  }\n}\n\nexport class UnsupportedJoinTypeError extends JoinError {\n  constructor(joinType: string) {\n    super(`Unsupported join type: ${joinType}`)\n  }\n}\n\nexport class InvalidJoinConditionSameSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: both expressions refer to the same source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinConditionSourceMismatchError extends JoinError {\n  constructor() {\n    super(`Invalid join condition: expressions must reference source aliases`)\n  }\n}\n\nexport class InvalidJoinConditionLeftSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: left expression refers to an unavailable source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinConditionRightSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: right expression does not refer to the joined source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinCondition extends JoinError {\n  constructor() {\n    super(`Invalid join condition`)\n  }\n}\n\nexport class UnsupportedJoinSourceTypeError extends JoinError {\n  constructor(type: string) {\n    super(`Unsupported join source type: ${type}`)\n  }\n}\n\n// GROUP BY and Aggregation Errors\nexport class GroupByError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `GroupByError`\n  }\n}\n\nexport class NonAggregateExpressionNotInGroupByError extends GroupByError {\n  constructor(alias: string) {\n    super(\n      `Non-aggregate expression '${alias}' in SELECT must also appear in GROUP BY clause`\n    )\n  }\n}\n\nexport class UnsupportedAggregateFunctionError extends GroupByError {\n  constructor(functionName: string) {\n    super(`Unsupported aggregate function: ${functionName}`)\n  }\n}\n\nexport class AggregateFunctionNotInSelectError extends GroupByError {\n  constructor(functionName: string) {\n    super(\n      `Aggregate function in HAVING clause must also be in SELECT clause: ${functionName}`\n    )\n  }\n}\n\nexport class UnknownHavingExpressionTypeError extends GroupByError {\n  constructor(type: string) {\n    super(`Unknown expression type in HAVING clause: ${type}`)\n  }\n}\n\n// Storage Errors\nexport class StorageError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `StorageError`\n  }\n}\n\nexport class SerializationError extends StorageError {\n  constructor(operation: string, originalError: string) {\n    super(\n      `Cannot ${operation} item because it cannot be JSON serialized: ${originalError}`\n    )\n  }\n}\n\n// LocalStorage Collection Errors\nexport class LocalStorageCollectionError extends StorageError {\n  constructor(message: string) {\n    super(message)\n    this.name = `LocalStorageCollectionError`\n  }\n}\n\nexport class StorageKeyRequiredError extends LocalStorageCollectionError {\n  constructor() {\n    super(`[LocalStorageCollection] storageKey must be provided.`)\n  }\n}\n\nexport class InvalidStorageDataFormatError extends LocalStorageCollectionError {\n  constructor(storageKey: string, key: string) {\n    super(\n      `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\" for key \"${key}\".`\n    )\n  }\n}\n\nexport class InvalidStorageObjectFormatError extends LocalStorageCollectionError {\n  constructor(storageKey: string) {\n    super(\n      `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\". Expected object format.`\n    )\n  }\n}\n\n// Sync Cleanup Errors\nexport class SyncCleanupError extends TanStackDBError {\n  constructor(collectionId: string, error: Error | string) {\n    const message = error instanceof Error ? error.message : String(error)\n    super(\n      `Collection \"${collectionId}\" sync cleanup function threw an error: ${message}`\n    )\n    this.name = `SyncCleanupError`\n  }\n}\n\n// Query Optimizer Errors\nexport class QueryOptimizerError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryOptimizerError`\n  }\n}\n\nexport class CannotCombineEmptyExpressionListError extends QueryOptimizerError {\n  constructor() {\n    super(`Cannot combine empty expression list`)\n  }\n}\n\n/**\n * Internal error when the query optimizer fails to convert a WHERE clause to a collection filter.\n */\nexport class WhereClauseConversionError extends QueryOptimizerError {\n  constructor(collectionId: string, alias: string) {\n    super(\n      `Failed to convert WHERE clause to collection filter for collection '${collectionId}' alias '${alias}'. This indicates a bug in the query optimization logic.`\n    )\n  }\n}\n\n/**\n * Error when a subscription cannot be found during lazy join processing.\n * For subqueries, aliases may be remapped (e.g., 'activeUser' → 'user').\n */\nexport class SubscriptionNotFoundError extends QueryCompilationError {\n  constructor(\n    resolvedAlias: string,\n    originalAlias: string,\n    collectionId: string,\n    availableAliases: Array<string>\n  ) {\n    super(\n      `Internal error: subscription for alias '${resolvedAlias}' (remapped from '${originalAlias}', collection '${collectionId}') is missing in join pipeline. Available aliases: ${availableAliases.join(`, `)}. This indicates a bug in alias tracking.`\n    )\n  }\n}\n\n/**\n * Error thrown when aggregate expressions are used outside of a GROUP BY context.\n */\nexport class AggregateNotSupportedError extends QueryCompilationError {\n  constructor() {\n    super(\n      `Aggregate expressions are not supported in this context. Use GROUP BY clause for aggregates.`\n    )\n  }\n}\n\n/**\n * Internal error when the compiler returns aliases that don't have corresponding input streams.\n * This should never happen since all aliases come from user declarations.\n */\nexport class MissingAliasInputsError extends QueryCompilationError {\n  constructor(missingAliases: Array<string>) {\n    super(\n      `Internal error: compiler returned aliases without inputs: ${missingAliases.join(`, `)}. ` +\n        `This indicates a bug in query compilation. Please report this issue.`\n    )\n  }\n}\n\n/**\n * Error thrown when setWindow is called on a collection without an ORDER BY clause.\n */\nexport class SetWindowRequiresOrderByError extends QueryCompilationError {\n  constructor() {\n    super(\n      `setWindow() can only be called on collections with an ORDER BY clause. ` +\n        `Add .orderBy() to your query to enable window movement.`\n    )\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/cjs/errors.d.cts

@@ -135,6 +135,9 @@ export declare class SubQueryMustHaveFromClauseError extends QueryBuilderError {
 export declare class InvalidSourceError extends QueryBuilderError {
     constructor(alias: string);
 }
+export declare class InvalidSourceTypeError extends QueryBuilderError {
+    constructor(context: string, type: string);
+}
 export declare class JoinConditionMustBeEqualityError extends QueryBuilderError {
     constructor();
 }

package/dist/cjs/index.cjs

@@ -64,6 +64,7 @@ exports.InvalidJoinConditionSameSourceError = errors.InvalidJoinConditionSameSou
 exports.InvalidJoinConditionSourceMismatchError = errors.InvalidJoinConditionSourceMismatchError;
 exports.InvalidSchemaError = errors.InvalidSchemaError;
 exports.InvalidSourceError = errors.InvalidSourceError;
+exports.InvalidSourceTypeError = errors.InvalidSourceTypeError;
 exports.InvalidStorageDataFormatError = errors.InvalidStorageDataFormatError;
 exports.InvalidStorageObjectFormatError = errors.InvalidStorageObjectFormatError;
 exports.JoinCollectionNotFoundError = errors.JoinCollectionNotFoundError;

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/query/builder/index.cjs

@@ -16,10 +16,26 @@ class BaseQueryBuilder {
    * @returns A tuple of [alias, ref] where alias is the source key and ref is the created reference
    */
   _createRefForSource(source, context) {
-    if (Object.keys(source).length !== 1) {
+    let keys;
+    try {
+      keys = Object.keys(source);
+    } catch {
+      const type = source === null ? `null` : `undefined`;
+      throw new errors.InvalidSourceTypeError(context, type);
+    }
+    if (Array.isArray(source)) {
+      throw new errors.InvalidSourceTypeError(context, `array`);
+    }
+    if (keys.length !== 1) {
+      if (keys.length === 0) {
+        throw new errors.InvalidSourceTypeError(context, `empty object`);
+      }
+      if (keys.every((k) => !isNaN(Number(k)))) {
+        throw new errors.InvalidSourceTypeError(context, `string`);
+      }
       throw new errors.OnlyOneSourceAllowedError(context);
     }
-    const alias = Object.keys(source)[0];
+    const alias = keys[0];
     const sourceValue = source[alias];
     let ref;
     if (sourceValue instanceof index.CollectionImpl) {