@tanstack/db 0.4.7 → 0.4.9

package/dist/cjs/query/live/collection-config-builder.d.cts

@@ -1,37 +1,128 @@
+import { SchedulerContextId } from '../../scheduler.js';
 import { CollectionSubscription } from '../../collection/subscription.js';
 import { OrderByOptimizationInfo } from '../compiler/order-by.js';
-import { CollectionConfigSingleRowOption, SyncConfig } from '../../types.js';
+import { CollectionConfigSingleRowOption, SyncConfig, UtilsRecord } from '../../types.js';
 import { Context, GetResult } from '../builder/types.js';
 import { BasicExpression, QueryIR } from '../ir.js';
 import { LazyCollectionCallbacks } from '../compiler/joins.js';
 import { FullSyncState, LiveQueryCollectionConfig } from './types.js';
+export type LiveQueryCollectionUtils = UtilsRecord & {
+    getRunCount: () => number;
+    getBuilder: () => CollectionConfigBuilder<any, any>;
+};
 export declare class CollectionConfigBuilder<TContext extends Context, TResult extends object = GetResult<TContext>> {
     private readonly config;
     private readonly id;
     readonly query: QueryIR;
     private readonly collections;
+    private readonly collectionByAlias;
+    private compiledAliasToCollectionId;
     private readonly resultKeys;
     private readonly orderByIndices;
     private readonly compare?;
     private isGraphRunning;
+    private runCount;
+    currentSyncConfig: Parameters<SyncConfig<TResult>[`sync`]>[0] | undefined;
+    currentSyncState: FullSyncState | undefined;
+    private isInErrorState;
+    private liveQueryCollection?;
+    private readonly aliasDependencies;
+    private readonly builderDependencies;
+    private readonly pendingGraphRuns;
+    private unsubscribeFromSchedulerClears?;
     private graphCache;
     private inputsCache;
     private pipelineCache;
-    collectionWhereClausesCache: Map<string, BasicExpression<boolean>> | undefined;
+    sourceWhereClausesCache: Map<string, BasicExpression<boolean>> | undefined;
     readonly subscriptions: Record<string, CollectionSubscription>;
-    lazyCollectionsCallbacks: Record<string, LazyCollectionCallbacks>;
-    readonly lazyCollections: Set<string>;
+    lazySourcesCallbacks: Record<string, LazyCollectionCallbacks>;
+    readonly lazySources: Set<string>;
     optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>;
     constructor(config: LiveQueryCollectionConfig<TContext, TResult>);
-    getConfig(): CollectionConfigSingleRowOption<TResult>;
-    maybeRunGraph(config: Parameters<SyncConfig<TResult>[`sync`]>[0], syncState: FullSyncState, callback?: () => boolean): void;
+    getConfig(): CollectionConfigSingleRowOption<TResult> & {
+        utils: LiveQueryCollectionUtils;
+    };
+    /**
+     * Resolves a collection alias to its collection ID.
+     *
+     * Uses a two-tier lookup strategy:
+     * 1. First checks compiled aliases (includes subquery inner aliases)
+     * 2. Falls back to declared aliases from the query's from/join clauses
+     *
+     * @param alias - The alias to resolve (e.g., "employee", "manager")
+     * @returns The collection ID that the alias references
+     * @throws {Error} If the alias is not found in either lookup
+     */
+    getCollectionIdForAlias(alias: string): string;
+    isLazyAlias(alias: string): boolean;
+    maybeRunGraph(callback?: () => boolean): void;
+    /**
+     * Schedules a graph run with the transaction-scoped scheduler.
+     * Ensures each builder runs at most once per transaction, with automatic dependency tracking
+     * to run parent queries before child queries. Outside a transaction, runs immediately.
+     *
+     * Multiple calls during a transaction are coalesced into a single execution.
+     * Dependencies are auto-discovered from subscribed live queries, or can be overridden.
+     * Load callbacks are combined when entries merge.
+     *
+     * Uses the current sync session's config and syncState from instance properties.
+     *
+     * @param callback - Optional callback to load more data if needed (returns true when done)
+     * @param options - Optional scheduling configuration
+     * @param options.contextId - Transaction ID to group work; defaults to active transaction
+     * @param options.jobId - Unique identifier for this job; defaults to this builder instance
+     * @param options.alias - Source alias that triggered this schedule; adds alias-specific dependencies
+     * @param options.dependencies - Explicit dependency list; overrides auto-discovered dependencies
+     */
+    scheduleGraphRun(callback?: () => boolean, options?: {
+        contextId?: SchedulerContextId;
+        jobId?: unknown;
+        alias?: string;
+        dependencies?: Array<CollectionConfigBuilder<any, any>>;
+    }): void;
+    /**
+     * Clears pending graph run state for a specific context.
+     * Called when the scheduler clears a context (e.g., transaction rollback/abort).
+     */
+    clearPendingGraphRun(contextId: SchedulerContextId): void;
+    /**
+     * Executes a pending graph run. Called by the scheduler when dependencies are satisfied.
+     * Clears the pending state BEFORE execution so that any re-schedules during the run
+     * create fresh state and don't interfere with the current execution.
+     * Uses instance sync state - if sync has ended, gracefully returns without executing.
+     *
+     * @param contextId - Optional context ID to look up pending state
+     * @param pendingParam - For immediate execution (no context), pending state is passed directly
+     */
+    private executeGraphRun;
     private getSyncConfig;
+    incrementRunCount(): void;
+    getRunCount(): number;
     private syncFn;
+    /**
+     * Compiles the query pipeline with all declared aliases.
+     */
     private compileBasePipeline;
     private maybeCompileBasePipeline;
     private extendPipelineWithChangeProcessing;
     private applyChanges;
+    /**
+     * Handle status changes from source collections
+     */
+    private handleSourceStatusChange;
+    /**
+     * Update the live query status based on source collection statuses
+     */
+    private updateLiveQueryStatus;
+    /**
+     * Transition the live query to error state
+     */
+    private transitionToError;
     private allCollectionsReady;
-    private allCollectionsReadyOrInitialCommit;
+    /**
+     * Creates per-alias subscriptions enabling self-join support.
+     * Each alias gets its own subscription with independent filters, even for the same collection.
+     * Example: `{ employee: col, manager: col }` creates two separate subscriptions.
+     */
     private subscribeToAllCollections;
 }

package/dist/cjs/query/live/collection-registry.cjs

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const collectionBuilderRegistry = /* @__PURE__ */ new WeakMap();
+function getBuilderFromConfig(config) {
+  return config.utils?.getBuilder?.();
+}
+function registerCollectionBuilder(collection, builder) {
+  collectionBuilderRegistry.set(collection, builder);
+}
+function getCollectionBuilder(collection) {
+  return collectionBuilderRegistry.get(collection);
+}
+exports.getBuilderFromConfig = getBuilderFromConfig;
+exports.getCollectionBuilder = getCollectionBuilder;
+exports.registerCollectionBuilder = registerCollectionBuilder;
+//# sourceMappingURL=collection-registry.cjs.map

package/dist/cjs/query/live/collection-registry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-registry.cjs","sources":["../../../../src/query/live/collection-registry.ts"],"sourcesContent":["import type { Collection } from \"../../collection/index.js\"\nimport type { CollectionConfigBuilder } from \"./collection-config-builder.js\"\n\nconst collectionBuilderRegistry = new WeakMap<\n  Collection<any, any, any>,\n  CollectionConfigBuilder<any, any>\n>()\n\n/**\n * Retrieves the builder attached to a config object via its utils.getBuilder() method.\n *\n * @param config - The collection config object\n * @returns The attached builder, or `undefined` if none exists\n */\nexport function getBuilderFromConfig(\n  config: object\n): CollectionConfigBuilder<any, any> | undefined {\n  return (config as any).utils?.getBuilder?.()\n}\n\n/**\n * Registers a builder for a collection in the global registry.\n * Used to detect when a live query depends on another live query,\n * enabling the scheduler to ensure parent queries run first.\n *\n * @param collection - The collection to register the builder for\n * @param builder - The builder that produces this collection\n */\nexport function registerCollectionBuilder(\n  collection: Collection<any, any, any>,\n  builder: CollectionConfigBuilder<any, any>\n): void {\n  collectionBuilderRegistry.set(collection, builder)\n}\n\n/**\n * Retrieves the builder registered for a collection.\n * Used to discover dependencies when a live query subscribes to another live query.\n *\n * @param collection - The collection to look up\n * @returns The registered builder, or `undefined` if none exists\n */\nexport function getCollectionBuilder(\n  collection: Collection<any, any, any>\n): CollectionConfigBuilder<any, any> | undefined {\n  return collectionBuilderRegistry.get(collection)\n}\n"],"names":[],"mappings":";;AAGA,MAAM,gDAAgC,QAAA;AAW/B,SAAS,qBACd,QAC+C;AAC/C,SAAQ,OAAe,OAAO,aAAA;AAChC;AAUO,SAAS,0BACd,YACA,SACM;AACN,4BAA0B,IAAI,YAAY,OAAO;AACnD;AASO,SAAS,qBACd,YAC+C;AAC/C,SAAO,0BAA0B,IAAI,UAAU;AACjD;;;;"}

package/dist/cjs/query/live/collection-registry.d.cts

@@ -0,0 +1,26 @@
+import { Collection } from '../../collection/index.js';
+import { CollectionConfigBuilder } from './collection-config-builder.js';
+/**
+ * Retrieves the builder attached to a config object via its utils.getBuilder() method.
+ *
+ * @param config - The collection config object
+ * @returns The attached builder, or `undefined` if none exists
+ */
+export declare function getBuilderFromConfig(config: object): CollectionConfigBuilder<any, any> | undefined;
+/**
+ * Registers a builder for a collection in the global registry.
+ * Used to detect when a live query depends on another live query,
+ * enabling the scheduler to ensure parent queries run first.
+ *
+ * @param collection - The collection to register the builder for
+ * @param builder - The builder that produces this collection
+ */
+export declare function registerCollectionBuilder(collection: Collection<any, any, any>, builder: CollectionConfigBuilder<any, any>): void;
+/**
+ * Retrieves the builder registered for a collection.
+ * Used to discover dependencies when a live query subscribes to another live query.
+ *
+ * @param collection - The collection to look up
+ * @returns The registered builder, or `undefined` if none exists
+ */
+export declare function getCollectionBuilder(collection: Collection<any, any, any>): CollectionConfigBuilder<any, any> | undefined;

package/dist/cjs/query/live/collection-subscriber.cjs

@@ -2,46 +2,41 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const dbIvm = require("@tanstack/db-ivm");
 const expressions = require("../compiler/expressions.cjs");
+const errors = require("../../errors.cjs");
+const loadMoreCallbackSymbol = Symbol.for(
+  `@tanstack/db.collection-config-builder`
+);
 class CollectionSubscriber {
-  constructor(collectionId, collection, config, syncState, collectionConfigBuilder) {
+  constructor(alias, collectionId, collection, collectionConfigBuilder) {
+    this.alias = alias;
     this.collectionId = collectionId;
     this.collection = collection;
-    this.config = config;
-    this.syncState = syncState;
     this.collectionConfigBuilder = collectionConfigBuilder;
     this.biggest = void 0;
-    this.collectionAlias = findCollectionAlias(
-      this.collectionId,
-      this.collectionConfigBuilder.query
-    );
   }
   subscribe() {
-    const whereClause = this.getWhereClauseFromAlias(this.collectionAlias);
+    const whereClause = this.getWhereClauseForAlias();
     if (whereClause) {
-      const whereExpression = expressions.convertToBasicExpression(
-        whereClause,
-        this.collectionAlias
-      );
+      const whereExpression = expressions.convertToBasicExpression(whereClause, this.alias);
       if (whereExpression) {
         return this.subscribeToChanges(whereExpression);
-      } else {
-        throw new Error(
-          `Failed to convert WHERE clause to collection filter for collection '${this.collectionId}'. This indicates a bug in the query optimization logic.`
-        );
       }
-    } else {
-      return this.subscribeToChanges();
+      throw new errors.WhereClauseConversionError(this.collectionId, this.alias);
     }
+    return this.subscribeToChanges();
   }
   subscribeToChanges(whereExpression) {
     let subscription;
-    if (Object.hasOwn(
-      this.collectionConfigBuilder.optimizableOrderByCollections,
-      this.collectionId
-    )) {
-      subscription = this.subscribeToOrderedChanges(whereExpression);
+    const orderByInfo = this.getOrderByInfo();
+    if (orderByInfo) {
+      subscription = this.subscribeToOrderedChanges(
+        whereExpression,
+        orderByInfo
+      );
     } else {
-      const includeInitialState = !this.collectionConfigBuilder.lazyCollections.has(this.collectionId);
+      const includeInitialState = !this.collectionConfigBuilder.isLazyAlias(
+        this.alias
+      );
       subscription = this.subscribeToMatchingChanges(
         whereExpression,
         includeInitialState
@@ -50,22 +45,22 @@ class CollectionSubscriber {
     const unsubscribe = () => {
       subscription.unsubscribe();
     };
-    this.syncState.unsubscribeCallbacks.add(unsubscribe);
+    this.collectionConfigBuilder.currentSyncState.unsubscribeCallbacks.add(
+      unsubscribe
+    );
     return subscription;
   }
   sendChangesToPipeline(changes, callback) {
-    const input = this.syncState.inputs[this.collectionId];
+    const input = this.collectionConfigBuilder.currentSyncState.inputs[this.alias];
     const sentChanges = sendChangesToInput(
       input,
       changes,
       this.collection.config.getKey
     );
     const dataLoader = sentChanges > 0 ? callback : void 0;
-    this.collectionConfigBuilder.maybeRunGraph(
-      this.config,
-      this.syncState,
-      dataLoader
-    );
+    this.collectionConfigBuilder.scheduleGraphRun(dataLoader, {
+      alias: this.alias
+    });
   }
   subscribeToMatchingChanges(whereExpression, includeInitialState = false) {
     const sendChanges = (changes) => {
@@ -77,12 +72,12 @@ class CollectionSubscriber {
     });
     return subscription;
   }
-  subscribeToOrderedChanges(whereExpression) {
-    const { orderBy, offset, limit, comparator, dataNeeded, index } = this.collectionConfigBuilder.optimizableOrderByCollections[this.collectionId];
+  subscribeToOrderedChanges(whereExpression, orderByInfo) {
+    const { orderBy, offset, limit, comparator, dataNeeded, index } = orderByInfo;
     const sendChangesInRange = (changes) => {
       const splittedChanges = splitUpdates(changes);
       let filteredChanges = splittedChanges;
-      if (dataNeeded() === 0) {
+      if (dataNeeded && dataNeeded() === 0) {
         filteredChanges = filterChangesSmallerOrEqualToMax(
           splittedChanges,
           comparator,
@@ -97,7 +92,7 @@ class CollectionSubscriber {
     subscription.setOrderByIndex(index);
     const normalizedOrderBy = expressions.convertOrderByToBasicExpression(
       orderBy,
-      this.collectionAlias
+      this.alias
     );
     subscription.requestLimitedSnapshot({
       limit: offset + limit,
@@ -109,7 +104,7 @@ class CollectionSubscriber {
   // after each iteration of the query pipeline
   // to ensure that the orderBy operator has enough data to work with
   loadMoreIfNeeded(subscription) {
-    const orderByInfo = this.collectionConfigBuilder.optimizableOrderByCollections[this.collectionId];
+    const orderByInfo = this.getOrderByInfo();
     if (!orderByInfo) {
       return true;
     }
@@ -126,22 +121,32 @@ class CollectionSubscriber {
     return true;
   }
   sendChangesToPipelineWithTracking(changes, subscription) {
-    const { comparator } = this.collectionConfigBuilder.optimizableOrderByCollections[this.collectionId];
-    const trackedChanges = this.trackSentValues(changes, comparator);
+    const orderByInfo = this.getOrderByInfo();
+    if (!orderByInfo) {
+      this.sendChangesToPipeline(changes);
+      return;
+    }
+    const trackedChanges = this.trackSentValues(changes, orderByInfo.comparator);
+    const subscriptionWithLoader = subscription;
+    subscriptionWithLoader[loadMoreCallbackSymbol] ??= this.loadMoreIfNeeded.bind(this, subscription);
     this.sendChangesToPipeline(
       trackedChanges,
-      this.loadMoreIfNeeded.bind(this, subscription)
+      subscriptionWithLoader[loadMoreCallbackSymbol]
     );
   }
   // Loads the next `n` items from the collection
   // starting from the biggest item it has sent
   loadNextItems(n, subscription) {
-    const { orderBy, valueExtractorForRawRow } = this.collectionConfigBuilder.optimizableOrderByCollections[this.collectionId];
+    const orderByInfo = this.getOrderByInfo();
+    if (!orderByInfo) {
+      return;
+    }
+    const { orderBy, valueExtractorForRawRow } = orderByInfo;
     const biggestSentRow = this.biggest;
     const biggestSentValue = biggestSentRow ? valueExtractorForRawRow(biggestSentRow) : biggestSentRow;
     const normalizedOrderBy = expressions.convertOrderByToBasicExpression(
       orderBy,
-      this.collectionAlias
+      this.alias
     );
     subscription.requestLimitedSnapshot({
       orderBy: normalizedOrderBy,
@@ -149,10 +154,17 @@ class CollectionSubscriber {
       minValue: biggestSentValue
     });
   }
-  getWhereClauseFromAlias(collectionAlias) {
-    const collectionWhereClausesCache = this.collectionConfigBuilder.collectionWhereClausesCache;
-    if (collectionAlias && collectionWhereClausesCache) {
-      return collectionWhereClausesCache.get(collectionAlias);
+  getWhereClauseForAlias() {
+    const sourceWhereClausesCache = this.collectionConfigBuilder.sourceWhereClausesCache;
+    if (!sourceWhereClausesCache) {
+      return void 0;
+    }
+    return sourceWhereClausesCache.get(this.alias);
+  }
+  getOrderByInfo() {
+    const info = this.collectionConfigBuilder.optimizableOrderByCollections[this.collectionId];
+    if (info && info.alias === this.alias) {
+      return info;
     }
     return void 0;
   }
@@ -167,19 +179,6 @@ class CollectionSubscriber {
     }
   }
 }
-function findCollectionAlias(collectionId, query) {
-  if (query.from?.type === `collectionRef` && query.from.collection?.id === collectionId) {
-    return query.from.alias;
-  }
-  if (query.join) {
-    for (const joinClause of query.join) {
-      if (joinClause.from?.type === `collectionRef` && joinClause.from.collection?.id === collectionId) {
-        return joinClause.from.alias;
-      }
-    }
-  }
-  return void 0;
-}
 function sendChangesToInput(input, changes, getKey) {
   const multiSetArray = [];
   for (const change of changes) {

package/dist/cjs/query/live/collection-subscriber.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"collection-subscriber.cjs","sources":["../../../../src/query/live/collection-subscriber.ts"],"sourcesContent":["import { MultiSet } from \"@tanstack/db-ivm\"\nimport {\n  convertOrderByToBasicExpression,\n  convertToBasicExpression,\n} from \"../compiler/expressions.js\"\nimport type { FullSyncState } from \"./types.js\"\nimport type { MultiSetArray, RootStreamBuilder } from \"@tanstack/db-ivm\"\nimport type { Collection } from \"../../collection/index.js\"\nimport type { ChangeMessage, SyncConfig } from \"../../types.js\"\nimport type { Context, GetResult } from \"../builder/types.js\"\nimport type { BasicExpression } from \"../ir.js\"\nimport type { CollectionConfigBuilder } from \"./collection-config-builder.js\"\nimport type { CollectionSubscription } from \"../../collection/subscription.js\"\n\nexport class CollectionSubscriber<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n> {\n  // Keep track of the biggest value we've sent so far (needed for orderBy optimization)\n  private biggest: any = undefined\n\n  private collectionAlias: string\n\n  constructor(\n    private collectionId: string,\n    private collection: Collection,\n    private config: Parameters<SyncConfig<TResult>[`sync`]>[0],\n    private syncState: FullSyncState,\n    private collectionConfigBuilder: CollectionConfigBuilder<TContext, TResult>\n  ) {\n    this.collectionAlias = findCollectionAlias(\n      this.collectionId,\n      this.collectionConfigBuilder.query\n    )!\n  }\n\n  subscribe(): CollectionSubscription {\n    const whereClause = this.getWhereClauseFromAlias(this.collectionAlias)\n\n    if (whereClause) {\n      // Convert WHERE clause to BasicExpression format for collection subscription\n      const whereExpression = convertToBasicExpression(\n        whereClause,\n        this.collectionAlias\n      )\n\n      if (whereExpression) {\n        // Use index optimization for this collection\n        return this.subscribeToChanges(whereExpression)\n      } else {\n        // This should not happen - if we have a whereClause but can't create whereExpression,\n        // it indicates a bug in our optimization logic\n        throw new Error(\n          `Failed to convert WHERE clause to collection filter for collection '${this.collectionId}'. ` +\n            `This indicates a bug in the query optimization logic.`\n        )\n      }\n    } else {\n      // No WHERE clause for this collection, use regular subscription\n      return this.subscribeToChanges()\n    }\n  }\n\n  private subscribeToChanges(whereExpression?: BasicExpression<boolean>) {\n    let subscription: CollectionSubscription\n    if (\n      Object.hasOwn(\n        this.collectionConfigBuilder.optimizableOrderByCollections,\n        this.collectionId\n      )\n    ) {\n      subscription = this.subscribeToOrderedChanges(whereExpression)\n    } else {\n      // If the collection is lazy then we should not include the initial state\n      const includeInitialState =\n        !this.collectionConfigBuilder.lazyCollections.has(this.collectionId)\n\n      subscription = this.subscribeToMatchingChanges(\n        whereExpression,\n        includeInitialState\n      )\n    }\n    const unsubscribe = () => {\n      subscription.unsubscribe()\n    }\n    this.syncState.unsubscribeCallbacks.add(unsubscribe)\n    return subscription\n  }\n\n  private sendChangesToPipeline(\n    changes: Iterable<ChangeMessage<any, string | number>>,\n    callback?: () => boolean\n  ) {\n    const input = this.syncState.inputs[this.collectionId]!\n    const sentChanges = sendChangesToInput(\n      input,\n      changes,\n      this.collection.config.getKey\n    )\n\n    // Do not provide the callback that loads more data\n    // if there's no more data to load\n    // otherwise we end up in an infinite loop trying to load more data\n    const dataLoader = sentChanges > 0 ? callback : undefined\n\n    // We need to call `maybeRunGraph` even if there's no data to load\n    // because we need to mark the collection as ready if it's not already\n    // and that's only done in `maybeRunGraph`\n    this.collectionConfigBuilder.maybeRunGraph(\n      this.config,\n      this.syncState,\n      dataLoader\n    )\n  }\n\n  private subscribeToMatchingChanges(\n    whereExpression: BasicExpression<boolean> | undefined,\n    includeInitialState: boolean = false\n  ) {\n    const sendChanges = (\n      changes: Array<ChangeMessage<any, string | number>>\n    ) => {\n      this.sendChangesToPipeline(changes)\n    }\n\n    const subscription = this.collection.subscribeChanges(sendChanges, {\n      includeInitialState,\n      whereExpression,\n    })\n\n    return subscription\n  }\n\n  private subscribeToOrderedChanges(\n    whereExpression: BasicExpression<boolean> | undefined\n  ) {\n    const { orderBy, offset, limit, comparator, dataNeeded, index } =\n      this.collectionConfigBuilder.optimizableOrderByCollections[\n        this.collectionId\n      ]!\n\n    const sendChangesInRange = (\n      changes: Iterable<ChangeMessage<any, string | number>>\n    ) => {\n      // Split live updates into a delete of the old value and an insert of the new value\n      // and filter out changes that are bigger than the biggest value we've sent so far\n      // because they can't affect the topK (and if later we need more data, we will dynamically load more data)\n      const splittedChanges = splitUpdates(changes)\n      let filteredChanges = splittedChanges\n      if (dataNeeded!() === 0) {\n        // If the topK is full [..., maxSentValue] then we do not need to send changes > maxSentValue\n        // because they can never make it into the topK.\n        // However, if the topK isn't full yet, we need to also send changes > maxSentValue\n        // because they will make it into the topK\n        filteredChanges = filterChangesSmallerOrEqualToMax(\n          splittedChanges,\n          comparator,\n          this.biggest\n        )\n      }\n\n      this.sendChangesToPipelineWithTracking(filteredChanges, subscription)\n    }\n\n    // Subscribe to changes and only send changes that are smaller than the biggest value we've sent so far\n    // values that are bigger don't need to be sent because they can't affect the topK\n    const subscription = this.collection.subscribeChanges(sendChangesInRange, {\n      whereExpression,\n    })\n\n    subscription.setOrderByIndex(index)\n\n    // Normalize the orderBy clauses such that the references are relative to the collection\n    const normalizedOrderBy = convertOrderByToBasicExpression(\n      orderBy,\n      this.collectionAlias\n    )\n\n    // Load the first `offset + limit` values from the index\n    // i.e. the K items from the collection that fall into the requested range: [offset, offset + limit[\n    subscription.requestLimitedSnapshot({\n      limit: offset + limit,\n      orderBy: normalizedOrderBy,\n    })\n\n    return subscription\n  }\n\n  // This function is called by maybeRunGraph\n  // after each iteration of the query pipeline\n  // to ensure that the orderBy operator has enough data to work with\n  loadMoreIfNeeded(subscription: CollectionSubscription) {\n    const orderByInfo =\n      this.collectionConfigBuilder.optimizableOrderByCollections[\n        this.collectionId\n      ]\n\n    if (!orderByInfo) {\n      // This query has no orderBy operator\n      // so there's no data to load\n      return true\n    }\n\n    const { dataNeeded } = orderByInfo\n\n    if (!dataNeeded) {\n      // This should never happen because the topK operator should always set the size callback\n      // which in turn should lead to the orderBy operator setting the dataNeeded callback\n      throw new Error(\n        `Missing dataNeeded callback for collection ${this.collectionId}`\n      )\n    }\n\n    // `dataNeeded` probes the orderBy operator to see if it needs more data\n    // if it needs more data, it returns the number of items it needs\n    const n = dataNeeded()\n    if (n > 0) {\n      this.loadNextItems(n, subscription)\n    }\n    return true\n  }\n\n  private sendChangesToPipelineWithTracking(\n    changes: Iterable<ChangeMessage<any, string | number>>,\n    subscription: CollectionSubscription\n  ) {\n    const { comparator } =\n      this.collectionConfigBuilder.optimizableOrderByCollections[\n        this.collectionId\n      ]!\n    const trackedChanges = this.trackSentValues(changes, comparator)\n    this.sendChangesToPipeline(\n      trackedChanges,\n      this.loadMoreIfNeeded.bind(this, subscription)\n    )\n  }\n\n  // Loads the next `n` items from the collection\n  // starting from the biggest item it has sent\n  private loadNextItems(n: number, subscription: CollectionSubscription) {\n    const { orderBy, valueExtractorForRawRow } =\n      this.collectionConfigBuilder.optimizableOrderByCollections[\n        this.collectionId\n      ]!\n    const biggestSentRow = this.biggest\n    const biggestSentValue = biggestSentRow\n      ? valueExtractorForRawRow(biggestSentRow)\n      : biggestSentRow\n\n    // Normalize the orderBy clauses such that the references are relative to the collection\n    const normalizedOrderBy = convertOrderByToBasicExpression(\n      orderBy,\n      this.collectionAlias\n    )\n\n    // Take the `n` items after the biggest sent value\n    subscription.requestLimitedSnapshot({\n      orderBy: normalizedOrderBy,\n      limit: n,\n      minValue: biggestSentValue,\n    })\n  }\n\n  private getWhereClauseFromAlias(\n    collectionAlias: string | undefined\n  ): BasicExpression<boolean> | undefined {\n    const collectionWhereClausesCache =\n      this.collectionConfigBuilder.collectionWhereClausesCache\n    if (collectionAlias && collectionWhereClausesCache) {\n      return collectionWhereClausesCache.get(collectionAlias)\n    }\n    return undefined\n  }\n\n  private *trackSentValues(\n    changes: Iterable<ChangeMessage<any, string | number>>,\n    comparator: (a: any, b: any) => number\n  ) {\n    for (const change of changes) {\n      if (!this.biggest) {\n        this.biggest = change.value\n      } else if (comparator(this.biggest, change.value) < 0) {\n        this.biggest = change.value\n      }\n\n      yield change\n    }\n  }\n}\n\n/**\n * Finds the alias for a collection ID in the query\n */\nfunction findCollectionAlias(\n  collectionId: string,\n  query: any\n): string | undefined {\n  // Check FROM clause\n  if (\n    query.from?.type === `collectionRef` &&\n    query.from.collection?.id === collectionId\n  ) {\n    return query.from.alias\n  }\n\n  // Check JOIN clauses\n  if (query.join) {\n    for (const joinClause of query.join) {\n      if (\n        joinClause.from?.type === `collectionRef` &&\n        joinClause.from.collection?.id === collectionId\n      ) {\n        return joinClause.from.alias\n      }\n    }\n  }\n\n  return undefined\n}\n\n/**\n * Helper function to send changes to a D2 input stream\n */\nfunction sendChangesToInput(\n  input: RootStreamBuilder<unknown>,\n  changes: Iterable<ChangeMessage>,\n  getKey: (item: ChangeMessage[`value`]) => any\n): number {\n  const multiSetArray: MultiSetArray<unknown> = []\n  for (const change of changes) {\n    const key = getKey(change.value)\n    if (change.type === `insert`) {\n      multiSetArray.push([[key, change.value], 1])\n    } else if (change.type === `update`) {\n      multiSetArray.push([[key, change.previousValue], -1])\n      multiSetArray.push([[key, change.value], 1])\n    } else {\n      // change.type === `delete`\n      multiSetArray.push([[key, change.value], -1])\n    }\n  }\n\n  if (multiSetArray.length !== 0) {\n    input.sendData(new MultiSet(multiSetArray))\n  }\n\n  return multiSetArray.length\n}\n\n/** Splits updates into a delete of the old value and an insert of the new value */\nfunction* splitUpdates<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n>(\n  changes: Iterable<ChangeMessage<T, TKey>>\n): Generator<ChangeMessage<T, TKey>> {\n  for (const change of changes) {\n    if (change.type === `update`) {\n      yield { type: `delete`, key: change.key, value: change.previousValue! }\n      yield { type: `insert`, key: change.key, value: change.value }\n    } else {\n      yield change\n    }\n  }\n}\n\nfunction* filterChanges<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n>(\n  changes: Iterable<ChangeMessage<T, TKey>>,\n  f: (change: ChangeMessage<T, TKey>) => boolean\n): Generator<ChangeMessage<T, TKey>> {\n  for (const change of changes) {\n    if (f(change)) {\n      yield change\n    }\n  }\n}\n\n/**\n * Filters changes to only include those that are smaller or equal to the provided max value\n * @param changes - Iterable of changes to filter\n * @param comparator - Comparator function to use for filtering\n * @param maxValue - Range to filter changes within (range boundaries are exclusive)\n * @returns Iterable of changes that fall within the range\n */\nfunction* filterChangesSmallerOrEqualToMax<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n>(\n  changes: Iterable<ChangeMessage<T, TKey>>,\n  comparator: (a: any, b: any) => number,\n  maxValue: any\n): Generator<ChangeMessage<T, TKey>> {\n  yield* filterChanges(changes, (change) => {\n    return !maxValue || comparator(change.value, maxValue) <= 0\n  })\n}\n"],"names":["convertToBasicExpression","convertOrderByToBasicExpression","MultiSet"],"mappings":"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"}
+{"version":3,"file":"collection-subscriber.cjs","sources":["../../../../src/query/live/collection-subscriber.ts"],"sourcesContent":["import { MultiSet } from \"@tanstack/db-ivm\"\nimport {\n  convertOrderByToBasicExpression,\n  convertToBasicExpression,\n} from \"../compiler/expressions.js\"\nimport { WhereClauseConversionError } from \"../../errors.js\"\nimport type { MultiSetArray, RootStreamBuilder } from \"@tanstack/db-ivm\"\nimport type { Collection } from \"../../collection/index.js\"\nimport type { ChangeMessage } from \"../../types.js\"\nimport type { Context, GetResult } from \"../builder/types.js\"\nimport type { BasicExpression } from \"../ir.js\"\nimport type { OrderByOptimizationInfo } from \"../compiler/order-by.js\"\nimport type { CollectionConfigBuilder } from \"./collection-config-builder.js\"\nimport type { CollectionSubscription } from \"../../collection/subscription.js\"\n\nconst loadMoreCallbackSymbol = Symbol.for(\n  `@tanstack/db.collection-config-builder`\n)\n\nexport class CollectionSubscriber<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n> {\n  // Keep track of the biggest value we've sent so far (needed for orderBy optimization)\n  private biggest: any = undefined\n\n  constructor(\n    private alias: string,\n    private collectionId: string,\n    private collection: Collection,\n    private collectionConfigBuilder: CollectionConfigBuilder<TContext, TResult>\n  ) {}\n\n  subscribe(): CollectionSubscription {\n    const whereClause = this.getWhereClauseForAlias()\n\n    if (whereClause) {\n      const whereExpression = convertToBasicExpression(whereClause, this.alias)\n\n      if (whereExpression) {\n        return this.subscribeToChanges(whereExpression)\n      }\n\n      throw new WhereClauseConversionError(this.collectionId, this.alias)\n    }\n\n    return this.subscribeToChanges()\n  }\n\n  private subscribeToChanges(whereExpression?: BasicExpression<boolean>) {\n    let subscription: CollectionSubscription\n    const orderByInfo = this.getOrderByInfo()\n    if (orderByInfo) {\n      subscription = this.subscribeToOrderedChanges(\n        whereExpression,\n        orderByInfo\n      )\n    } else {\n      // If the source alias is lazy then we should not include the initial state\n      const includeInitialState = !this.collectionConfigBuilder.isLazyAlias(\n        this.alias\n      )\n\n      subscription = this.subscribeToMatchingChanges(\n        whereExpression,\n        includeInitialState\n      )\n    }\n    const unsubscribe = () => {\n      subscription.unsubscribe()\n    }\n    // currentSyncState is always defined when subscribe() is called\n    // (called during sync session setup)\n    this.collectionConfigBuilder.currentSyncState!.unsubscribeCallbacks.add(\n      unsubscribe\n    )\n    return subscription\n  }\n\n  private sendChangesToPipeline(\n    changes: Iterable<ChangeMessage<any, string | number>>,\n    callback?: () => boolean\n  ) {\n    // currentSyncState and input are always defined when this method is called\n    // (only called from active subscriptions during a sync session)\n    const input =\n      this.collectionConfigBuilder.currentSyncState!.inputs[this.alias]!\n    const sentChanges = sendChangesToInput(\n      input,\n      changes,\n      this.collection.config.getKey\n    )\n\n    // Do not provide the callback that loads more data\n    // if there's no more data to load\n    // otherwise we end up in an infinite loop trying to load more data\n    const dataLoader = sentChanges > 0 ? callback : undefined\n\n    // We need to schedule a graph run even if there's no data to load\n    // because we need to mark the collection as ready if it's not already\n    // and that's only done in `scheduleGraphRun`\n    this.collectionConfigBuilder.scheduleGraphRun(dataLoader, {\n      alias: this.alias,\n    })\n  }\n\n  private subscribeToMatchingChanges(\n    whereExpression: BasicExpression<boolean> | undefined,\n    includeInitialState: boolean = false\n  ) {\n    const sendChanges = (\n      changes: Array<ChangeMessage<any, string | number>>\n    ) => {\n      this.sendChangesToPipeline(changes)\n    }\n\n    const subscription = this.collection.subscribeChanges(sendChanges, {\n      includeInitialState,\n      whereExpression,\n    })\n\n    return subscription\n  }\n\n  private subscribeToOrderedChanges(\n    whereExpression: BasicExpression<boolean> | undefined,\n    orderByInfo: OrderByOptimizationInfo\n  ) {\n    const { orderBy, offset, limit, comparator, dataNeeded, index } =\n      orderByInfo\n\n    const sendChangesInRange = (\n      changes: Iterable<ChangeMessage<any, string | number>>\n    ) => {\n      // Split live updates into a delete of the old value and an insert of the new value\n      // and filter out changes that are bigger than the biggest value we've sent so far\n      // because they can't affect the topK (and if later we need more data, we will dynamically load more data)\n      const splittedChanges = splitUpdates(changes)\n      let filteredChanges = splittedChanges\n      if (dataNeeded && dataNeeded() === 0) {\n        // If the topK is full [..., maxSentValue] then we do not need to send changes > maxSentValue\n        // because they can never make it into the topK.\n        // However, if the topK isn't full yet, we need to also send changes > maxSentValue\n        // because they will make it into the topK\n        filteredChanges = filterChangesSmallerOrEqualToMax(\n          splittedChanges,\n          comparator,\n          this.biggest\n        )\n      }\n\n      this.sendChangesToPipelineWithTracking(filteredChanges, subscription)\n    }\n\n    // Subscribe to changes and only send changes that are smaller than the biggest value we've sent so far\n    // values that are bigger don't need to be sent because they can't affect the topK\n    const subscription = this.collection.subscribeChanges(sendChangesInRange, {\n      whereExpression,\n    })\n\n    subscription.setOrderByIndex(index)\n\n    // Normalize the orderBy clauses such that the references are relative to the collection\n    const normalizedOrderBy = convertOrderByToBasicExpression(\n      orderBy,\n      this.alias\n    )\n\n    // Load the first `offset + limit` values from the index\n    // i.e. the K items from the collection that fall into the requested range: [offset, offset + limit[\n    subscription.requestLimitedSnapshot({\n      limit: offset + limit,\n      orderBy: normalizedOrderBy,\n    })\n\n    return subscription\n  }\n\n  // This function is called by maybeRunGraph\n  // after each iteration of the query pipeline\n  // to ensure that the orderBy operator has enough data to work with\n  loadMoreIfNeeded(subscription: CollectionSubscription) {\n    const orderByInfo = this.getOrderByInfo()\n\n    if (!orderByInfo) {\n      // This query has no orderBy operator\n      // so there's no data to load\n      return true\n    }\n\n    const { dataNeeded } = orderByInfo\n\n    if (!dataNeeded) {\n      // This should never happen because the topK operator should always set the size callback\n      // which in turn should lead to the orderBy operator setting the dataNeeded callback\n      throw new Error(\n        `Missing dataNeeded callback for collection ${this.collectionId}`\n      )\n    }\n\n    // `dataNeeded` probes the orderBy operator to see if it needs more data\n    // if it needs more data, it returns the number of items it needs\n    const n = dataNeeded()\n    if (n > 0) {\n      this.loadNextItems(n, subscription)\n    }\n    return true\n  }\n\n  private sendChangesToPipelineWithTracking(\n    changes: Iterable<ChangeMessage<any, string | number>>,\n    subscription: CollectionSubscription\n  ) {\n    const orderByInfo = this.getOrderByInfo()\n    if (!orderByInfo) {\n      this.sendChangesToPipeline(changes)\n      return\n    }\n\n    const trackedChanges = this.trackSentValues(changes, orderByInfo.comparator)\n\n    // Cache the loadMoreIfNeeded callback on the subscription using a symbol property.\n    // This ensures we pass the same function instance to the scheduler each time,\n    // allowing it to deduplicate callbacks when multiple changes arrive during a transaction.\n    type SubscriptionWithLoader = CollectionSubscription & {\n      [loadMoreCallbackSymbol]?: () => boolean\n    }\n\n    const subscriptionWithLoader = subscription as SubscriptionWithLoader\n\n    subscriptionWithLoader[loadMoreCallbackSymbol] ??=\n      this.loadMoreIfNeeded.bind(this, subscription)\n\n    this.sendChangesToPipeline(\n      trackedChanges,\n      subscriptionWithLoader[loadMoreCallbackSymbol]\n    )\n  }\n\n  // Loads the next `n` items from the collection\n  // starting from the biggest item it has sent\n  private loadNextItems(n: number, subscription: CollectionSubscription) {\n    const orderByInfo = this.getOrderByInfo()\n    if (!orderByInfo) {\n      return\n    }\n    const { orderBy, valueExtractorForRawRow } = orderByInfo\n    const biggestSentRow = this.biggest\n    const biggestSentValue = biggestSentRow\n      ? valueExtractorForRawRow(biggestSentRow)\n      : biggestSentRow\n\n    // Normalize the orderBy clauses such that the references are relative to the collection\n    const normalizedOrderBy = convertOrderByToBasicExpression(\n      orderBy,\n      this.alias\n    )\n\n    // Take the `n` items after the biggest sent value\n    subscription.requestLimitedSnapshot({\n      orderBy: normalizedOrderBy,\n      limit: n,\n      minValue: biggestSentValue,\n    })\n  }\n\n  private getWhereClauseForAlias(): BasicExpression<boolean> | undefined {\n    const sourceWhereClausesCache =\n      this.collectionConfigBuilder.sourceWhereClausesCache\n    if (!sourceWhereClausesCache) {\n      return undefined\n    }\n    return sourceWhereClausesCache.get(this.alias)\n  }\n\n  private getOrderByInfo(): OrderByOptimizationInfo | undefined {\n    const info =\n      this.collectionConfigBuilder.optimizableOrderByCollections[\n        this.collectionId\n      ]\n    if (info && info.alias === this.alias) {\n      return info\n    }\n    return undefined\n  }\n\n  private *trackSentValues(\n    changes: Iterable<ChangeMessage<any, string | number>>,\n    comparator: (a: any, b: any) => number\n  ) {\n    for (const change of changes) {\n      if (!this.biggest) {\n        this.biggest = change.value\n      } else if (comparator(this.biggest, change.value) < 0) {\n        this.biggest = change.value\n      }\n\n      yield change\n    }\n  }\n}\n\n/**\n * Helper function to send changes to a D2 input stream\n */\nfunction sendChangesToInput(\n  input: RootStreamBuilder<unknown>,\n  changes: Iterable<ChangeMessage>,\n  getKey: (item: ChangeMessage[`value`]) => any\n): number {\n  const multiSetArray: MultiSetArray<unknown> = []\n  for (const change of changes) {\n    const key = getKey(change.value)\n    if (change.type === `insert`) {\n      multiSetArray.push([[key, change.value], 1])\n    } else if (change.type === `update`) {\n      multiSetArray.push([[key, change.previousValue], -1])\n      multiSetArray.push([[key, change.value], 1])\n    } else {\n      // change.type === `delete`\n      multiSetArray.push([[key, change.value], -1])\n    }\n  }\n\n  if (multiSetArray.length !== 0) {\n    input.sendData(new MultiSet(multiSetArray))\n  }\n\n  return multiSetArray.length\n}\n\n/** Splits updates into a delete of the old value and an insert of the new value */\nfunction* splitUpdates<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n>(\n  changes: Iterable<ChangeMessage<T, TKey>>\n): Generator<ChangeMessage<T, TKey>> {\n  for (const change of changes) {\n    if (change.type === `update`) {\n      yield { type: `delete`, key: change.key, value: change.previousValue! }\n      yield { type: `insert`, key: change.key, value: change.value }\n    } else {\n      yield change\n    }\n  }\n}\n\nfunction* filterChanges<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n>(\n  changes: Iterable<ChangeMessage<T, TKey>>,\n  f: (change: ChangeMessage<T, TKey>) => boolean\n): Generator<ChangeMessage<T, TKey>> {\n  for (const change of changes) {\n    if (f(change)) {\n      yield change\n    }\n  }\n}\n\n/**\n * Filters changes to only include those that are smaller or equal to the provided max value\n * @param changes - Iterable of changes to filter\n * @param comparator - Comparator function to use for filtering\n * @param maxValue - Range to filter changes within (range boundaries are exclusive)\n * @returns Iterable of changes that fall within the range\n */\nfunction* filterChangesSmallerOrEqualToMax<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n>(\n  changes: Iterable<ChangeMessage<T, TKey>>,\n  comparator: (a: any, b: any) => number,\n  maxValue: any\n): Generator<ChangeMessage<T, TKey>> {\n  yield* filterChanges(changes, (change) => {\n    return !maxValue || comparator(change.value, maxValue) <= 0\n  })\n}\n"],"names":["convertToBasicExpression","WhereClauseConversionError","convertOrderByToBasicExpression","MultiSet"],"mappings":"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"}

package/dist/cjs/query/live/collection-subscriber.d.cts

@@ -1,18 +1,14 @@
-import { FullSyncState } from './types.js';
 import { Collection } from '../../collection/index.js';
-import { SyncConfig } from '../../types.js';
 import { Context, GetResult } from '../builder/types.js';
 import { CollectionConfigBuilder } from './collection-config-builder.js';
 import { CollectionSubscription } from '../../collection/subscription.js';
 export declare class CollectionSubscriber<TContext extends Context, TResult extends object = GetResult<TContext>> {
+    private alias;
     private collectionId;
     private collection;
-    private config;
-    private syncState;
     private collectionConfigBuilder;
     private biggest;
-    private collectionAlias;
-    constructor(collectionId: string, collection: Collection, config: Parameters<SyncConfig<TResult>[`sync`]>[0], syncState: FullSyncState, collectionConfigBuilder: CollectionConfigBuilder<TContext, TResult>);
+    constructor(alias: string, collectionId: string, collection: Collection, collectionConfigBuilder: CollectionConfigBuilder<TContext, TResult>);
     subscribe(): CollectionSubscription;
     private subscribeToChanges;
     private sendChangesToPipeline;
@@ -21,6 +17,7 @@ export declare class CollectionSubscriber<TContext extends Context, TResult exte
     loadMoreIfNeeded(subscription: CollectionSubscription): boolean;
     private sendChangesToPipelineWithTracking;
     private loadNextItems;
-    private getWhereClauseFromAlias;
+    private getWhereClauseForAlias;
+    private getOrderByInfo;
     private trackSentValues;
 }

package/dist/cjs/query/live-query-collection.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const index = require("../collection/index.cjs");
 const collectionConfigBuilder = require("./live/collection-config-builder.cjs");
+const collectionRegistry = require("./live/collection-registry.cjs");
 function liveQueryCollectionOptions(config) {
   const collectionConfigBuilder$1 = new collectionConfigBuilder.CollectionConfigBuilder(config);
   return collectionConfigBuilder$1.getConfig();
@@ -16,14 +17,19 @@ function createLiveQueryCollection(configOrQuery) {
   } else {
     const config = configOrQuery;
     const options = liveQueryCollectionOptions(config);
-    return bridgeToCreateCollection({
-      ...options,
-      utils: config.utils
-    });
+    if (config.utils) {
+      options.utils = { ...options.utils, ...config.utils };
+    }
+    return bridgeToCreateCollection(options);
   }
 }
 function bridgeToCreateCollection(options) {
-  return index.createCollection(options);
+  const collection = index.createCollection(options);
+  const builder = collectionRegistry.getBuilderFromConfig(options);
+  if (builder) {
+    collectionRegistry.registerCollectionBuilder(collection, builder);
+  }
+  return collection;
 }
 exports.createLiveQueryCollection = createLiveQueryCollection;
 exports.liveQueryCollectionOptions = liveQueryCollectionOptions;

package/dist/cjs/query/live-query-collection.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"live-query-collection.cjs","sources":["../../../src/query/live-query-collection.ts"],"sourcesContent":["import { createCollection } from \"../collection/index.js\"\nimport { CollectionConfigBuilder } from \"./live/collection-config-builder.js\"\nimport type { LiveQueryCollectionConfig } from \"./live/types.js\"\nimport type { InitialQueryBuilder, QueryBuilder } from \"./builder/index.js\"\nimport type { Collection } from \"../collection/index.js\"\nimport type {\n  CollectionConfig,\n  CollectionConfigSingleRowOption,\n  NonSingleResult,\n  SingleResult,\n  UtilsRecord,\n} from \"../types.js\"\nimport type { Context, GetResult } from \"./builder/types.js\"\n\ntype CollectionConfigForContext<\n  TContext extends Context,\n  TResult extends object,\n> = TContext extends SingleResult\n  ? CollectionConfigSingleRowOption<TResult> & SingleResult\n  : CollectionConfigSingleRowOption<TResult> & NonSingleResult\n\ntype CollectionForContext<\n  TContext extends Context,\n  TResult extends object,\n> = TContext extends SingleResult\n  ? Collection<TResult> & SingleResult\n  : Collection<TResult> & NonSingleResult\n\n/**\n * Creates live query collection options for use with createCollection\n *\n * @example\n * ```typescript\n * const options = liveQueryCollectionOptions({\n *   // id is optional - will auto-generate if not provided\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => eq(post.published, true))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       content: post.content,\n *     })),\n *   // getKey is optional - will use stream key if not provided\n * })\n *\n * const collection = createCollection(options)\n * ```\n *\n * @param config - Configuration options for the live query collection\n * @returns Collection options that can be passed to createCollection\n */\nexport function liveQueryCollectionOptions<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult>\n): CollectionConfigForContext<TContext, TResult> {\n  const collectionConfigBuilder = new CollectionConfigBuilder<\n    TContext,\n    TResult\n  >(config)\n  return collectionConfigBuilder.getConfig() as CollectionConfigForContext<\n    TContext,\n    TResult\n  >\n}\n\n/**\n * Creates a live query collection directly\n *\n * @example\n * ```typescript\n * // Minimal usage - just pass a query function\n * const activeUsers = createLiveQueryCollection(\n *   (q) => q\n *     .from({ user: usersCollection })\n *     .where(({ user }) => eq(user.active, true))\n *     .select(({ user }) => ({ id: user.id, name: user.name }))\n * )\n *\n * // Full configuration with custom options\n * const searchResults = createLiveQueryCollection({\n *   id: \"search-results\", // Custom ID (auto-generated if omitted)\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => like(post.title, `%${searchTerm}%`))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       excerpt: post.excerpt,\n *     })),\n *   getKey: (item) => item.id, // Custom key function (uses stream key if omitted)\n *   utils: {\n *     updateSearchTerm: (newTerm: string) => {\n *       // Custom utility functions\n *     }\n *   }\n * })\n * ```\n */\n\n// Overload 1: Accept just the query function\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  query: (q: InitialQueryBuilder) => QueryBuilder<TContext>\n): CollectionForContext<TContext, TResult>\n\n// Overload 2: Accept full config object with optional utilities\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils }\n): CollectionForContext<TContext, TResult>\n\n// Implementation\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  configOrQuery:\n    | (LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils })\n    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)\n): CollectionForContext<TContext, TResult> {\n  // Determine if the argument is a function (query) or a config object\n  if (typeof configOrQuery === `function`) {\n    // Simple query function case\n    const config: LiveQueryCollectionConfig<TContext, TResult> = {\n      query: configOrQuery as (\n        q: InitialQueryBuilder\n      ) => QueryBuilder<TContext>,\n    }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n    return bridgeToCreateCollection(options) as CollectionForContext<\n      TContext,\n      TResult\n    >\n  } else {\n    // Config object case\n    const config = configOrQuery as LiveQueryCollectionConfig<\n      TContext,\n      TResult\n    > & { utils?: TUtils }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n    return bridgeToCreateCollection({\n      ...options,\n      utils: config.utils,\n    }) as CollectionForContext<TContext, TResult>\n  }\n}\n\n/**\n * Bridge function that handles the type compatibility between query2's TResult\n * and core collection's output type without exposing ugly type assertions to users\n */\nfunction bridgeToCreateCollection<\n  TResult extends object,\n  TUtils extends UtilsRecord = {},\n>(\n  options: CollectionConfig<TResult> & { utils?: TUtils }\n): Collection<TResult, string | number, TUtils> {\n  // This is the only place we need a type assertion, hidden from user API\n  return createCollection(options as any) as unknown as Collection<\n    TResult,\n    string | number,\n    TUtils\n  >\n}\n"],"names":["collectionConfigBuilder","CollectionConfigBuilder","createCollection"],"mappings":";;;;AAoDO,SAAS,2BAId,QAC+C;AAC/C,QAAMA,4BAA0B,IAAIC,wBAAAA,wBAGlC,MAAM;AACR,SAAOD,0BAAwB,UAAA;AAIjC;AAsDO,SAAS,0BAKd,eAGyC;AAEzC,MAAI,OAAO,kBAAkB,YAAY;AAEvC,UAAM,SAAuD;AAAA,MAC3D,OAAO;AAAA,IAAA;AAIT,UAAM,UAAU,2BAA8C,MAAM;AACpE,WAAO,yBAAyB,OAAO;AAAA,EAIzC,OAAO;AAEL,UAAM,SAAS;AAIf,UAAM,UAAU,2BAA8C,MAAM;AACpE,WAAO,yBAAyB;AAAA,MAC9B,GAAG;AAAA,MACH,OAAO,OAAO;AAAA,IAAA,CACf;AAAA,EACH;AACF;AAMA,SAAS,yBAIP,SAC8C;AAE9C,SAAOE,MAAAA,iBAAiB,OAAc;AAKxC;;;"}
+{"version":3,"file":"live-query-collection.cjs","sources":["../../../src/query/live-query-collection.ts"],"sourcesContent":["import { createCollection } from \"../collection/index.js\"\nimport { CollectionConfigBuilder } from \"./live/collection-config-builder.js\"\nimport {\n  getBuilderFromConfig,\n  registerCollectionBuilder,\n} from \"./live/collection-registry.js\"\nimport type { LiveQueryCollectionUtils } from \"./live/collection-config-builder.js\"\nimport type { LiveQueryCollectionConfig } from \"./live/types.js\"\nimport type { InitialQueryBuilder, QueryBuilder } from \"./builder/index.js\"\nimport type { Collection } from \"../collection/index.js\"\nimport type {\n  CollectionConfig,\n  CollectionConfigSingleRowOption,\n  NonSingleResult,\n  SingleResult,\n  UtilsRecord,\n} from \"../types.js\"\nimport type { Context, GetResult } from \"./builder/types.js\"\n\ntype CollectionConfigForContext<\n  TContext extends Context,\n  TResult extends object,\n> = TContext extends SingleResult\n  ? CollectionConfigSingleRowOption<TResult> & SingleResult\n  : CollectionConfigSingleRowOption<TResult> & NonSingleResult\n\ntype CollectionForContext<\n  TContext extends Context,\n  TResult extends object,\n> = TContext extends SingleResult\n  ? Collection<TResult> & SingleResult\n  : Collection<TResult> & NonSingleResult\n\n/**\n * Creates live query collection options for use with createCollection\n *\n * @example\n * ```typescript\n * const options = liveQueryCollectionOptions({\n *   // id is optional - will auto-generate if not provided\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => eq(post.published, true))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       content: post.content,\n *     })),\n *   // getKey is optional - will use stream key if not provided\n * })\n *\n * const collection = createCollection(options)\n * ```\n *\n * @param config - Configuration options for the live query collection\n * @returns Collection options that can be passed to createCollection\n */\nexport function liveQueryCollectionOptions<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult>\n): CollectionConfigForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils\n} {\n  const collectionConfigBuilder = new CollectionConfigBuilder<\n    TContext,\n    TResult\n  >(config)\n  return collectionConfigBuilder.getConfig() as CollectionConfigForContext<\n    TContext,\n    TResult\n  > & { utils: LiveQueryCollectionUtils }\n}\n\n/**\n * Creates a live query collection directly\n *\n * @example\n * ```typescript\n * // Minimal usage - just pass a query function\n * const activeUsers = createLiveQueryCollection(\n *   (q) => q\n *     .from({ user: usersCollection })\n *     .where(({ user }) => eq(user.active, true))\n *     .select(({ user }) => ({ id: user.id, name: user.name }))\n * )\n *\n * // Full configuration with custom options\n * const searchResults = createLiveQueryCollection({\n *   id: \"search-results\", // Custom ID (auto-generated if omitted)\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => like(post.title, `%${searchTerm}%`))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       excerpt: post.excerpt,\n *     })),\n *   getKey: (item) => item.id, // Custom key function (uses stream key if omitted)\n *   utils: {\n *     updateSearchTerm: (newTerm: string) => {\n *       // Custom utility functions\n *     }\n *   }\n * })\n * ```\n */\n\n// Overload 1: Accept just the query function\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  query: (q: InitialQueryBuilder) => QueryBuilder<TContext>\n): CollectionForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils\n}\n\n// Overload 2: Accept full config object with optional utilities\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils }\n): CollectionForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils & TUtils\n}\n\n// Implementation\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  configOrQuery:\n    | (LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils })\n    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)\n): CollectionForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils & TUtils\n} {\n  // Determine if the argument is a function (query) or a config object\n  if (typeof configOrQuery === `function`) {\n    // Simple query function case\n    const config: LiveQueryCollectionConfig<TContext, TResult> = {\n      query: configOrQuery as (\n        q: InitialQueryBuilder\n      ) => QueryBuilder<TContext>,\n    }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n    return bridgeToCreateCollection(options) as CollectionForContext<\n      TContext,\n      TResult\n    > & { utils: LiveQueryCollectionUtils & TUtils }\n  } else {\n    // Config object case\n    const config = configOrQuery as LiveQueryCollectionConfig<\n      TContext,\n      TResult\n    > & { utils?: TUtils }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n\n    // Merge custom utils if provided, preserving the getBuilder() method for dependency tracking\n    if (config.utils) {\n      options.utils = { ...options.utils, ...config.utils }\n    }\n\n    return bridgeToCreateCollection(options) as CollectionForContext<\n      TContext,\n      TResult\n    > & { utils: LiveQueryCollectionUtils & TUtils }\n  }\n}\n\n/**\n * Bridge function that handles the type compatibility between query2's TResult\n * and core collection's output type without exposing ugly type assertions to users\n */\nfunction bridgeToCreateCollection<\n  TResult extends object,\n  TUtils extends UtilsRecord = {},\n>(\n  options: CollectionConfig<TResult> & { utils: TUtils }\n): Collection<TResult, string | number, TUtils> {\n  const collection = createCollection(options as any) as unknown as Collection<\n    TResult,\n    string | number,\n    LiveQueryCollectionUtils\n  >\n\n  const builder = getBuilderFromConfig(options)\n  if (builder) {\n    registerCollectionBuilder(collection, builder)\n  }\n\n  return collection as unknown as Collection<TResult, string | number, TUtils>\n}\n"],"names":["collectionConfigBuilder","CollectionConfigBuilder","createCollection","getBuilderFromConfig","registerCollectionBuilder"],"mappings":";;;;;AAyDO,SAAS,2BAId,QAGA;AACA,QAAMA,4BAA0B,IAAIC,wBAAAA,wBAGlC,MAAM;AACR,SAAOD,0BAAwB,UAAA;AAIjC;AA0DO,SAAS,0BAKd,eAKA;AAEA,MAAI,OAAO,kBAAkB,YAAY;AAEvC,UAAM,SAAuD;AAAA,MAC3D,OAAO;AAAA,IAAA;AAIT,UAAM,UAAU,2BAA8C,MAAM;AACpE,WAAO,yBAAyB,OAAO;AAAA,EAIzC,OAAO;AAEL,UAAM,SAAS;AAIf,UAAM,UAAU,2BAA8C,MAAM;AAGpE,QAAI,OAAO,OAAO;AAChB,cAAQ,QAAQ,EAAE,GAAG,QAAQ,OAAO,GAAG,OAAO,MAAA;AAAA,IAChD;AAEA,WAAO,yBAAyB,OAAO;AAAA,EAIzC;AACF;AAMA,SAAS,yBAIP,SAC8C;AAC9C,QAAM,aAAaE,MAAAA,iBAAiB,OAAc;AAMlD,QAAM,UAAUC,mBAAAA,qBAAqB,OAAO;AAC5C,MAAI,SAAS;AACXC,uBAAAA,0BAA0B,YAAY,OAAO;AAAA,EAC/C;AAEA,SAAO;AACT;;;"}

package/dist/cjs/query/live-query-collection.d.cts

@@ -1,3 +1,4 @@
+import { LiveQueryCollectionUtils } from './live/collection-config-builder.js';
 import { LiveQueryCollectionConfig } from './live/types.js';
 import { InitialQueryBuilder, QueryBuilder } from './builder/index.js';
 import { Collection } from '../collection/index.js';
@@ -29,7 +30,9 @@ type CollectionForContext<TContext extends Context, TResult extends object> = TC
  * @param config - Configuration options for the live query collection
  * @returns Collection options that can be passed to createCollection
  */
-export declare function liveQueryCollectionOptions<TContext extends Context, TResult extends object = GetResult<TContext>>(config: LiveQueryCollectionConfig<TContext, TResult>): CollectionConfigForContext<TContext, TResult>;
+export declare function liveQueryCollectionOptions<TContext extends Context, TResult extends object = GetResult<TContext>>(config: LiveQueryCollectionConfig<TContext, TResult>): CollectionConfigForContext<TContext, TResult> & {
+    utils: LiveQueryCollectionUtils;
+};
 /**
  * Creates a live query collection directly
  *
@@ -63,8 +66,12 @@ export declare function liveQueryCollectionOptions<TContext extends Context, TRe
  * })
  * ```
  */
-export declare function createLiveQueryCollection<TContext extends Context, TResult extends object = GetResult<TContext>>(query: (q: InitialQueryBuilder) => QueryBuilder<TContext>): CollectionForContext<TContext, TResult>;
+export declare function createLiveQueryCollection<TContext extends Context, TResult extends object = GetResult<TContext>>(query: (q: InitialQueryBuilder) => QueryBuilder<TContext>): CollectionForContext<TContext, TResult> & {
+    utils: LiveQueryCollectionUtils;
+};
 export declare function createLiveQueryCollection<TContext extends Context, TResult extends object = GetResult<TContext>, TUtils extends UtilsRecord = {}>(config: LiveQueryCollectionConfig<TContext, TResult> & {
     utils?: TUtils;
-}): CollectionForContext<TContext, TResult>;
+}): CollectionForContext<TContext, TResult> & {
+    utils: LiveQueryCollectionUtils & TUtils;
+};
 export {};