@tanstack/db 0.5.31 → 0.5.33

package/dist/esm/index.js

@@ -6,13 +6,14 @@ import { createArrayChangeProxy, createChangeProxy, withArrayChangeTracking, wit
 import { createOptimisticAction } from "./optimistic-action.js";
 import { localOnlyCollectionOptions } from "./local-only.js";
 import { localStorageCollectionOptions } from "./local-storage.js";
-import { AggregateFunctionNotInSelectError, AggregateNotSupportedError, CannotCombineEmptyExpressionListError, CollectionConfigurationError, CollectionInErrorStateError, CollectionInputNotFoundError, CollectionIsInErrorStateError, CollectionOperationError, CollectionRequiresConfigError, CollectionRequiresSyncConfigError, CollectionStateError, DeleteKeyNotFoundError, DistinctRequiresSelectError, DuplicateAliasInSubqueryError, DuplicateDbInstanceError, DuplicateKeyError, DuplicateKeySyncError, EmptyReferencePathError, GroupByError, HavingRequiresGroupByError, InvalidCollectionStatusTransitionError, InvalidJoinCondition, InvalidJoinConditionLeftSourceError, InvalidJoinConditionRightSourceError, InvalidJoinConditionSameSourceError, InvalidJoinConditionSourceMismatchError, InvalidKeyError, InvalidSchemaError, InvalidSourceError, InvalidSourceTypeError, InvalidStorageDataFormatError, InvalidStorageObjectFormatError, InvalidWhereExpressionError, JoinCollectionNotFoundError, JoinConditionMustBeEqualityError, JoinError, KeyUpdateNotAllowedError, LimitOffsetRequireOrderByError, LocalStorageCollectionError, MissingAliasInputsError, MissingDeleteHandlerError, MissingHandlerError, MissingInsertHandlerError, MissingMutationFunctionError, MissingUpdateArgumentError, MissingUpdateHandlerError, NegativeActiveSubscribersError, NoKeysPassedToDeleteError, NoKeysPassedToUpdateError, NoPendingSyncTransactionCommitError, NoPendingSyncTransactionWriteError, NonAggregateExpressionNotInGroupByError, NonRetriableError, OnMutateMustBeSynchronousError, OnlyOneSourceAllowedError, QueryBuilderError, QueryCompilationError, QueryMustHaveFromClauseError, QueryOptimizerError, SchemaMustBeSynchronousError, SchemaValidationError, SerializationError, SetWindowRequiresOrderByError, StorageError, StorageKeyRequiredError, SubQueryMustHaveFromClauseError, SubscriptionNotFoundError, SyncCleanupError, SyncTransactionAlreadyCommittedError, SyncTransactionAlreadyCommittedWriteError, TanStackDBError, TransactionAlreadyCompletedRollbackError, TransactionError, TransactionNotPendingCommitError, TransactionNotPendingMutateError, UndefinedKeyError, UnknownExpressionTypeError, UnknownFunctionError, UnknownHavingExpressionTypeError, UnsupportedAggregateFunctionError, UnsupportedFromTypeError, UnsupportedJoinSourceTypeError, UnsupportedJoinTypeError, UpdateKeyNotFoundError, WhereClauseConversionError } from "./errors.js";
+import { AggregateFunctionNotInSelectError, AggregateNotSupportedError, CannotCombineEmptyExpressionListError, CollectionConfigurationError, CollectionInErrorStateError, CollectionInputNotFoundError, CollectionIsInErrorStateError, CollectionOperationError, CollectionRequiresConfigError, CollectionRequiresSyncConfigError, CollectionStateError, DeleteKeyNotFoundError, DistinctRequiresSelectError, DuplicateAliasInSubqueryError, DuplicateDbInstanceError, DuplicateKeyError, DuplicateKeySyncError, EmptyReferencePathError, FnSelectWithGroupByError, GroupByError, HavingRequiresGroupByError, InvalidCollectionStatusTransitionError, InvalidJoinCondition, InvalidJoinConditionLeftSourceError, InvalidJoinConditionRightSourceError, InvalidJoinConditionSameSourceError, InvalidJoinConditionSourceMismatchError, InvalidKeyError, InvalidSchemaError, InvalidSourceError, InvalidSourceTypeError, InvalidStorageDataFormatError, InvalidStorageObjectFormatError, InvalidWhereExpressionError, JoinCollectionNotFoundError, JoinConditionMustBeEqualityError, JoinError, KeyUpdateNotAllowedError, LimitOffsetRequireOrderByError, LocalStorageCollectionError, MissingAliasInputsError, MissingDeleteHandlerError, MissingHandlerError, MissingInsertHandlerError, MissingMutationFunctionError, MissingUpdateArgumentError, MissingUpdateHandlerError, NegativeActiveSubscribersError, NoKeysPassedToDeleteError, NoKeysPassedToUpdateError, NoPendingSyncTransactionCommitError, NoPendingSyncTransactionWriteError, NonAggregateExpressionNotInGroupByError, NonRetriableError, OnMutateMustBeSynchronousError, OnlyOneSourceAllowedError, QueryBuilderError, QueryCompilationError, QueryMustHaveFromClauseError, QueryOptimizerError, SchemaMustBeSynchronousError, SchemaValidationError, SerializationError, SetWindowRequiresOrderByError, StorageError, StorageKeyRequiredError, SubQueryMustHaveFromClauseError, SubscriptionNotFoundError, SyncCleanupError, SyncTransactionAlreadyCommittedError, SyncTransactionAlreadyCommittedWriteError, TanStackDBError, TransactionAlreadyCompletedRollbackError, TransactionError, TransactionNotPendingCommitError, TransactionNotPendingMutateError, UndefinedKeyError, UnknownExpressionTypeError, UnknownFunctionError, UnknownHavingExpressionTypeError, UnsupportedAggregateFunctionError, UnsupportedFromTypeError, UnsupportedJoinSourceTypeError, UnsupportedJoinTypeError, UpdateKeyNotFoundError, WhereClauseConversionError } from "./errors.js";
 import { deepEquals } from "./utils.js";
 import { createPacedMutations } from "./paced-mutations.js";
 import { BaseIndex, IndexOperation } from "./indexes/base-index.js";
 import { BTreeIndex } from "./indexes/btree-index.js";
 import { IndexProxy, LazyIndexWrapper } from "./indexes/lazy-index.js";
 import { extractFieldPath, extractSimpleComparisons, extractValue, parseLoadSubsetOptions, parseOrderByExpression, parseWhereExpression, walkExpression } from "./query/expression-helpers.js";
+import { createEffect } from "./query/effect.js";
 import { add, and, avg, coalesce, concat, count, eq, gt, gte, ilike, inArray, isNull, isUndefined, length, like, lower, lt, lte, max, min, not, operators, or, sum, upper } from "./query/builder/functions.js";
 import { BaseQueryBuilder, Query } from "./query/builder/index.js";
 import { DeduplicatedLoadSubset } from "./query/subset-dedupe.js";
@@ -20,6 +21,7 @@ import { compileQuery } from "./query/compiler/index.js";
 import { createLiveQueryCollection, liveQueryCollectionOptions } from "./query/live-query-collection.js";
 import { debounceStrategy } from "./strategies/debounceStrategy.js";
 import { isLimitSubset, isOffsetLimitSubset, isOrderBySubset, isPredicateSubset, isWhereSubset, minusWherePredicates, unionWherePredicates } from "./query/predicate-utils.js";
+import { queryOnce } from "./query/query-once.js";
 import { queueStrategy } from "./strategies/queueStrategy.js";
 import { throttleStrategy } from "./strategies/throttleStrategy.js";
 export {
@@ -46,6 +48,7 @@ export {
   DuplicateKeyError,
   DuplicateKeySyncError,
   EmptyReferencePathError,
+  FnSelectWithGroupByError,
   GroupByError,
   HavingRequiresGroupByError,
   ir as IR,
@@ -129,6 +132,7 @@ export {
   createArrayChangeProxy,
   createChangeProxy,
   createCollection,
+  createEffect,
   createLiveQueryCollection,
   createOptimisticAction,
   createPacedMutations,
@@ -168,6 +172,7 @@ export {
   parseLoadSubsetOptions,
   parseOrderByExpression,
   parseWhereExpression,
+  queryOnce,
   queueStrategy,
   sum,
   throttleStrategy,

package/dist/esm/index.js.map

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

package/dist/esm/query/builder/types.d.ts

@@ -181,7 +181,7 @@ export type SelectObject<T extends SelectShape = SelectShape> = T;
  * ```
  */
 export type ResultTypeFromSelect<TSelectObject> = WithoutRefBrand<Prettify<{
-    [K in keyof TSelectObject]: NeedsExtraction<TSelectObject[K]> extends true ? ExtractExpressionType<TSelectObject[K]> : TSelectObject[K] extends Ref<infer _T> ? ExtractRef<TSelectObject[K]> : TSelectObject[K] extends RefLeaf<infer T> ? T : TSelectObject[K] extends RefLeaf<infer T> | undefined ? T | undefined : TSelectObject[K] extends RefLeaf<infer T> | null ? T | null : TSelectObject[K] extends Ref<infer _T> | undefined ? ExtractRef<TSelectObject[K]> | undefined : TSelectObject[K] extends Ref<infer _T> | null ? ExtractRef<TSelectObject[K]> | null : TSelectObject[K] extends Aggregate<infer T> ? T : TSelectObject[K] extends string | number | boolean | null | undefined ? TSelectObject[K] : TSelectObject[K] extends Record<string, any> ? ResultTypeFromSelect<TSelectObject[K]> : never;
+    [K in keyof TSelectObject]: NeedsExtraction<TSelectObject[K]> extends true ? ExtractExpressionType<TSelectObject[K]> : TSelectObject[K] extends Ref<infer _T> ? ExtractRef<TSelectObject[K]> : TSelectObject[K] extends RefLeaf<infer T> ? IsNullableRef<TSelectObject[K]> extends true ? T | undefined : T : TSelectObject[K] extends RefLeaf<infer T> | undefined ? T | undefined : TSelectObject[K] extends RefLeaf<infer T> | null ? IsNullableRef<Exclude<TSelectObject[K], null>> extends true ? T | null | undefined : T | null : TSelectObject[K] extends Ref<infer _T> | undefined ? ExtractRef<Exclude<TSelectObject[K], undefined>> | undefined : TSelectObject[K] extends Ref<infer _T> | null ? ExtractRef<Exclude<TSelectObject[K], null>> | null : TSelectObject[K] extends Aggregate<infer T> ? T : TSelectObject[K] extends string | number | boolean | null | undefined ? TSelectObject[K] : TSelectObject[K] extends Record<string, any> ? ResultTypeFromSelect<TSelectObject[K]> : never;
 }>>;
 type ExtractRef<T> = Prettify<ResultTypeFromSelect<WithoutRefBrand<T>>>;
 type ExtractExpressionType<T> = T extends PropRef<infer U> ? U : T extends Value<infer U> ? U : T extends Func<infer U> ? U : T extends Aggregate<infer U> ? U : T extends BasicExpression<infer U> ? U : T;
@@ -260,33 +260,23 @@ export type FunctionalHavingRow<TContext extends Context> = TContext[`schema`] &
     $selected: TContext[`result`];
 } : {});
 /**
- * RefProxyForContext - Creates ref proxies for all tables/collections in a query context
+ * RefsForContext - Creates ref proxies for all tables/collections in a query context
  *
  * This is the main entry point for creating ref objects in query builder callbacks.
- * It handles optionality by placing undefined/null OUTSIDE the RefProxy to enable
- * JavaScript's optional chaining operator (?.):
+ * For nullable join sides (left/right/full joins), it produces `Ref<T, true>` instead
+ * of `Ref<T> | undefined`. This accurately reflects that the proxy object is always
+ * present at build time (it's a truthy proxy that records property access paths),
+ * while the `Nullable` flag ensures the result type correctly includes `| undefined`.
  *
  * Examples:
- * - Required field: `RefProxy<User>` → user.name works
- * - Optional field: `RefProxy<User> | undefined` → user?.name works
- * - Nullable field: `RefProxy<User> | null` → user?.name works
- * - Both optional and nullable: `RefProxy<User> | undefined` → user?.name works
- *
- * The key insight is that `RefProxy<User | undefined>` would NOT allow `user?.name`
- * because the undefined is "inside" the proxy, but `RefProxy<User> | undefined`
- * does allow it because the undefined is "outside" the proxy.
- *
- * The logic prioritizes optional chaining by always placing `undefined` outside when
- * a type is both optional and nullable (e.g., `string | null | undefined`).
+ * - Required field: `Ref<User>` → user.name works, result is T
+ * - Nullable join side: `Ref<User, true>` → user.name works, result is T | undefined
  *
  * After `select()` is called, this type also includes `$selected` which provides access
  * to the SELECT result fields via `$selected.fieldName` syntax.
  */
 export type RefsForContext<TContext extends Context> = {
-    [K in keyof TContext[`schema`]]: IsNonExactOptional<TContext[`schema`][K]> extends true ? IsNonExactNullable<TContext[`schema`][K]> extends true ? // T is both non-exact optional and non-exact nullable (e.g., string | null | undefined)
-    Ref<NonNullable<TContext[`schema`][K]>> | undefined : // T is optional (T | undefined) but not exactly undefined, and not nullable
-    Ref<NonUndefined<TContext[`schema`][K]>> | undefined : IsNonExactNullable<TContext[`schema`][K]> extends true ? // T is nullable (T | null) but not exactly null, and not optional
-    Ref<NonNull<TContext[`schema`][K]>> | null : Ref<TContext[`schema`][K]>;
+    [K in keyof TContext[`schema`]]: IsNonExactOptional<TContext[`schema`][K]> extends true ? IsNonExactNullable<TContext[`schema`][K]> extends true ? Ref<NonNullable<TContext[`schema`][K]>, true> : Ref<NonUndefined<TContext[`schema`][K]>, true> : IsNonExactNullable<TContext[`schema`][K]> extends true ? Ref<NonNull<TContext[`schema`][K]>, true> : Ref<TContext[`schema`][K]>;
 } & (TContext[`result`] extends object ? {
     $selected: Ref<TContext[`result`]>;
 } : {});
@@ -331,23 +321,26 @@ type NonNull<T> = T extends null ? never : T;
  * It provides a recursive interface that allows nested property access while
  * preserving optionality and nullability correctly.
  *
- * When spread in select clauses, it correctly produces the underlying data type
- * without Ref wrappers, enabling clean spread operations.
+ * The `Nullable` parameter indicates whether this ref comes from a nullable
+ * join side (left/right/full). When `true`, the `Nullable` flag propagates
+ * through all nested property accesses, ensuring the result type includes
+ * `| undefined` for all fields accessed through this ref.
  *
  * Example usage:
  * ```typescript
- * // Clean interface - no internal properties visible
- * const users: Ref<{ id: number; profile?: { bio: string } }> = { ... }
- * users.id // Ref<number> - clean display
- * users.profile?.bio // Ref<string> - nested optional access works
+ * // Non-nullable ref (inner join or from table):
+ * select(({ user }) => ({ name: user.name })) // result: string
+ *
+ * // Nullable ref (left join right side):
+ * select(({ dept }) => ({ name: dept.name })) // result: string | undefined
  *
  * // Spread operations work cleanly:
  * select(({ user }) => ({ ...user })) // Returns User type, not Ref types
  * ```
  */
-export type Ref<T = any> = {
-    [K in keyof T]: IsNonExactOptional<T[K]> extends true ? IsNonExactNullable<T[K]> extends true ? IsPlainObject<NonNullable<T[K]>> extends true ? Ref<NonNullable<T[K]>> | undefined : RefLeaf<NonNullable<T[K]>> | undefined : IsPlainObject<NonUndefined<T[K]>> extends true ? Ref<NonUndefined<T[K]>> | undefined : RefLeaf<NonUndefined<T[K]>> | undefined : IsNonExactNullable<T[K]> extends true ? IsPlainObject<NonNull<T[K]>> extends true ? Ref<NonNull<T[K]>> | null : RefLeaf<NonNull<T[K]>> | null : IsPlainObject<T[K]> extends true ? Ref<T[K]> : RefLeaf<T[K]>;
-} & RefLeaf<T>;
+export type Ref<T = any, Nullable extends boolean = false> = {
+    [K in keyof T]: IsNonExactOptional<T[K]> extends true ? IsNonExactNullable<T[K]> extends true ? IsPlainObject<NonNullable<T[K]>> extends true ? Ref<NonNullable<T[K]>, Nullable> | undefined : RefLeaf<NonNullable<T[K]>, Nullable> | undefined : IsPlainObject<NonUndefined<T[K]>> extends true ? Ref<NonUndefined<T[K]>, Nullable> | undefined : RefLeaf<NonUndefined<T[K]>, Nullable> | undefined : IsNonExactNullable<T[K]> extends true ? IsPlainObject<NonNull<T[K]>> extends true ? Ref<NonNull<T[K]>, Nullable> | null : RefLeaf<NonNull<T[K]>, Nullable> | null : IsPlainObject<T[K]> extends true ? Ref<T[K], Nullable> : RefLeaf<T[K], Nullable>;
+} & RefLeaf<T, Nullable>;
 /**
  * Ref - The user-facing ref type with clean IDE display
  *
@@ -360,10 +353,14 @@ export type Ref<T = any> = {
  * - No internal properties like __refProxy, __path, __type are visible
  */
 declare const RefBrand: unique symbol;
-export type RefLeaf<T = any> = {
+declare const NullableBrand: unique symbol;
+export type RefLeaf<T = any, Nullable extends boolean = false> = {
     readonly [RefBrand]?: T;
-};
-type WithoutRefBrand<T> = T extends Record<string, any> ? Omit<T, typeof RefBrand> : T;
+} & ([Nullable] extends [true] ? {
+    readonly [NullableBrand]?: true;
+} : {});
+type IsNullableRef<T> = typeof NullableBrand extends keyof T ? true : false;
+type WithoutRefBrand<T> = T extends Record<string, any> ? Omit<T, typeof RefBrand | typeof NullableBrand> : T;
 /**
  * PreserveSingleResultFlag - Conditionally includes the singleResult flag
  *

package/dist/esm/query/compiler/index.js

@@ -1,6 +1,6 @@
 import { map, filter, distinct } from "@tanstack/db-ivm";
 import { optimizeQuery } from "../optimizer.js";
-import { DistinctRequiresSelectError, HavingRequiresGroupByError, LimitOffsetRequireOrderByError, DuplicateAliasInSubqueryError, UnsupportedFromTypeError, CollectionInputNotFoundError } from "../../errors.js";
+import { DistinctRequiresSelectError, FnSelectWithGroupByError, HavingRequiresGroupByError, LimitOffsetRequireOrderByError, DuplicateAliasInSubqueryError, UnsupportedFromTypeError, CollectionInputNotFoundError } from "../../errors.js";
 import { getWhereExpression, Value } from "../ir.js";
 import { compileExpression, toBooleanPredicate } from "./evaluators.js";
 import { processJoins } from "./joins.js";
@@ -92,6 +92,9 @@ function compileQuery(rawQuery, inputs, collections, subscriptions, callbacks, l
   if (query.distinct && !query.fnSelect && !query.select) {
     throw new DistinctRequiresSelectError();
   }
+  if (query.fnSelect && query.groupBy && query.groupBy.length > 0) {
+    throw new FnSelectWithGroupByError();
+  }
   if (query.fnSelect) {
     pipeline = pipeline.pipe(
       map(([key, namespacedRow]) => {

package/dist/esm/query/compiler/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/query/compiler/index.ts"],"sourcesContent":["import { distinct, filter, map } from '@tanstack/db-ivm'\nimport { optimizeQuery } from '../optimizer.js'\nimport {\n  CollectionInputNotFoundError,\n  DistinctRequiresSelectError,\n  DuplicateAliasInSubqueryError,\n  HavingRequiresGroupByError,\n  LimitOffsetRequireOrderByError,\n  UnsupportedFromTypeError,\n} from '../../errors.js'\nimport { PropRef, Value as ValClass, getWhereExpression } from '../ir.js'\nimport { compileExpression, toBooleanPredicate } from './evaluators.js'\nimport { processJoins } from './joins.js'\nimport { containsAggregate, processGroupBy } from './group-by.js'\nimport { processOrderBy } from './order-by.js'\nimport { processSelect } from './select.js'\nimport type { CollectionSubscription } from '../../collection/subscription.js'\nimport type { OrderByOptimizationInfo } from './order-by.js'\nimport type {\n  BasicExpression,\n  CollectionRef,\n  QueryIR,\n  QueryRef,\n} from '../ir.js'\nimport type { LazyCollectionCallbacks } from './joins.js'\nimport type { Collection } from '../../collection/index.js'\nimport type {\n  KeyedStream,\n  NamespacedAndKeyedStream,\n  ResultStream,\n} from '../../types.js'\nimport type { QueryCache, QueryMapping, WindowOptions } from './types.js'\n\nexport type { WindowOptions } from './types.js'\n\n/**\n * Result of query compilation including both the pipeline and source-specific WHERE clauses\n */\nexport interface CompilationResult {\n  /** The ID of the main collection */\n  collectionId: string\n\n  /** The compiled query pipeline (D2 stream) */\n  pipeline: ResultStream\n\n  /** Map of source aliases to their WHERE clauses for index optimization */\n  sourceWhereClauses: Map<string, BasicExpression<boolean>>\n\n  /**\n   * Maps each source alias to its collection ID. Enables per-alias subscriptions for self-joins.\n   * Example: `{ employee: 'employees-col-id', manager: 'employees-col-id' }`\n   */\n  aliasToCollectionId: Record<string, string>\n\n  /**\n   * Flattened mapping from outer alias to innermost alias for subqueries.\n   * Always provides one-hop lookups, never recursive chains.\n   *\n   * Example: `{ activeUser: 'user' }` when `.from({ activeUser: subquery })`\n   * where the subquery uses `.from({ user: collection })`.\n   *\n   * For deeply nested subqueries, the mapping goes directly to the innermost alias:\n   * `{ author: 'user' }` (not `{ author: 'activeUser' }`), so `aliasRemapping[alias]`\n   * always resolves in a single lookup.\n   *\n   * Used to resolve subscriptions during lazy loading when join aliases differ from\n   * the inner aliases where collection subscriptions were created.\n   */\n  aliasRemapping: Record<string, string>\n}\n\n/**\n * Compiles a query IR into a D2 pipeline\n * @param rawQuery The query IR to compile\n * @param inputs Mapping of source aliases to input streams (e.g., `{ employee: input1, manager: input2 }`)\n * @param collections Mapping of collection IDs to Collection instances\n * @param subscriptions Mapping of source aliases to CollectionSubscription instances\n * @param callbacks Mapping of source aliases to lazy loading callbacks\n * @param lazySources Set of source aliases that should load data lazily\n * @param optimizableOrderByCollections Map of collection IDs to order-by optimization info\n * @param cache Optional cache for compiled subqueries (used internally for recursion)\n * @param queryMapping Optional mapping from optimized queries to original queries\n * @returns A CompilationResult with the pipeline, source WHERE clauses, and alias metadata\n */\nexport function compileQuery(\n  rawQuery: QueryIR,\n  inputs: Record<string, KeyedStream>,\n  collections: Record<string, Collection<any, any, any, any, any>>,\n  subscriptions: Record<string, CollectionSubscription>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazySources: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,\n  cache: QueryCache = new WeakMap(),\n  queryMapping: QueryMapping = new WeakMap(),\n): CompilationResult {\n  // Check if the original raw query has already been compiled\n  const cachedResult = cache.get(rawQuery)\n  if (cachedResult) {\n    return cachedResult\n  }\n\n  // Validate the raw query BEFORE optimization to check user's original structure.\n  // This must happen before optimization because the optimizer may create internal\n  // subqueries (e.g., for predicate pushdown) that reuse aliases, which is fine.\n  validateQueryStructure(rawQuery)\n\n  // Optimize the query before compilation\n  const { optimizedQuery: query, sourceWhereClauses } = optimizeQuery(rawQuery)\n\n  // Create mapping from optimized query to original for caching\n  queryMapping.set(query, rawQuery)\n  mapNestedQueries(query, rawQuery, queryMapping)\n\n  // Create a copy of the inputs map to avoid modifying the original\n  const allInputs = { ...inputs }\n\n  // Track alias to collection id relationships discovered during compilation.\n  // This includes all user-declared aliases plus inner aliases from subqueries.\n  const aliasToCollectionId: Record<string, string> = {}\n\n  // Track alias remapping for subqueries (outer alias → inner alias)\n  // e.g., when .join({ activeUser: subquery }) where subquery uses .from({ user: collection })\n  // we store: aliasRemapping['activeUser'] = 'user'\n  const aliasRemapping: Record<string, string> = {}\n\n  // Create a map of source aliases to input streams.\n  // Inputs MUST be keyed by alias (e.g., `{ employee: input1, manager: input2 }`),\n  // not by collection ID. This enables per-alias subscriptions where different aliases\n  // of the same collection (e.g., self-joins) maintain independent filtered streams.\n  const sources: Record<string, KeyedStream> = {}\n\n  // Process the FROM clause to get the main source\n  const {\n    alias: mainSource,\n    input: mainInput,\n    collectionId: mainCollectionId,\n  } = processFrom(\n    query.from,\n    allInputs,\n    collections,\n    subscriptions,\n    callbacks,\n    lazySources,\n    optimizableOrderByCollections,\n    setWindowFn,\n    cache,\n    queryMapping,\n    aliasToCollectionId,\n    aliasRemapping,\n    sourceWhereClauses,\n  )\n  sources[mainSource] = mainInput\n\n  // Prepare the initial pipeline with the main source wrapped in its alias\n  let pipeline: NamespacedAndKeyedStream = mainInput.pipe(\n    map(([key, row]) => {\n      // Initialize the record with a nested structure\n      const ret = [key, { [mainSource]: row }] as [\n        string,\n        Record<string, typeof row>,\n      ]\n      return ret\n    }),\n  )\n\n  // Process JOIN clauses if they exist\n  if (query.join && query.join.length > 0) {\n    pipeline = processJoins(\n      pipeline,\n      query.join,\n      sources,\n      mainCollectionId,\n      mainSource,\n      allInputs,\n      cache,\n      queryMapping,\n      collections,\n      subscriptions,\n      callbacks,\n      lazySources,\n      optimizableOrderByCollections,\n      setWindowFn,\n      rawQuery,\n      compileQuery,\n      aliasToCollectionId,\n      aliasRemapping,\n      sourceWhereClauses,\n    )\n  }\n\n  // Process the WHERE clause if it exists\n  if (query.where && query.where.length > 0) {\n    // Apply each WHERE condition as a filter (they are ANDed together)\n    for (const where of query.where) {\n      const whereExpression = getWhereExpression(where)\n      const compiledWhere = compileExpression(whereExpression)\n      pipeline = pipeline.pipe(\n        filter(([_key, namespacedRow]) => {\n          return toBooleanPredicate(compiledWhere(namespacedRow))\n        }),\n      )\n    }\n  }\n\n  // Process functional WHERE clauses if they exist\n  if (query.fnWhere && query.fnWhere.length > 0) {\n    for (const fnWhere of query.fnWhere) {\n      pipeline = pipeline.pipe(\n        filter(([_key, namespacedRow]) => {\n          return toBooleanPredicate(fnWhere(namespacedRow))\n        }),\n      )\n    }\n  }\n\n  if (query.distinct && !query.fnSelect && !query.select) {\n    throw new DistinctRequiresSelectError()\n  }\n\n  // Process the SELECT clause early - always create $selected\n  // This eliminates duplication and allows for DISTINCT implementation\n  if (query.fnSelect) {\n    // Handle functional select - apply the function to transform the row\n    pipeline = pipeline.pipe(\n      map(([key, namespacedRow]) => {\n        const selectResults = query.fnSelect!(namespacedRow)\n        return [\n          key,\n          {\n            ...namespacedRow,\n            $selected: selectResults,\n          },\n        ] as [string, typeof namespacedRow & { $selected: any }]\n      }),\n    )\n  } else if (query.select) {\n    pipeline = processSelect(pipeline, query.select, allInputs)\n  } else {\n    // If no SELECT clause, create $selected with the main table data\n    pipeline = pipeline.pipe(\n      map(([key, namespacedRow]) => {\n        const selectResults =\n          !query.join && !query.groupBy\n            ? namespacedRow[mainSource]\n            : namespacedRow\n\n        return [\n          key,\n          {\n            ...namespacedRow,\n            $selected: selectResults,\n          },\n        ] as [string, typeof namespacedRow & { $selected: any }]\n      }),\n    )\n  }\n\n  // Process the GROUP BY clause if it exists\n  if (query.groupBy && query.groupBy.length > 0) {\n    pipeline = processGroupBy(\n      pipeline,\n      query.groupBy,\n      query.having,\n      query.select,\n      query.fnHaving,\n    )\n  } else if (query.select) {\n    // Check if SELECT contains aggregates but no GROUP BY (implicit single-group aggregation)\n    const hasAggregates = Object.values(query.select).some(\n      (expr) => expr.type === `agg` || containsAggregate(expr),\n    )\n    if (hasAggregates) {\n      // Handle implicit single-group aggregation\n      pipeline = processGroupBy(\n        pipeline,\n        [], // Empty group by means single group\n        query.having,\n        query.select,\n        query.fnHaving,\n      )\n    }\n  }\n\n  // Process the HAVING clause if it exists (only applies after GROUP BY)\n  if (query.having && (!query.groupBy || query.groupBy.length === 0)) {\n    // Check if we have aggregates in SELECT that would trigger implicit grouping\n    const hasAggregates = query.select\n      ? Object.values(query.select).some((expr) => expr.type === `agg`)\n      : false\n\n    if (!hasAggregates) {\n      throw new HavingRequiresGroupByError()\n    }\n  }\n\n  // Process functional HAVING clauses outside of GROUP BY (treat as additional WHERE filters)\n  if (\n    query.fnHaving &&\n    query.fnHaving.length > 0 &&\n    (!query.groupBy || query.groupBy.length === 0)\n  ) {\n    // If there's no GROUP BY but there are fnHaving clauses, apply them as filters\n    for (const fnHaving of query.fnHaving) {\n      pipeline = pipeline.pipe(\n        filter(([_key, namespacedRow]) => {\n          return fnHaving(namespacedRow)\n        }),\n      )\n    }\n  }\n\n  // Process the DISTINCT clause if it exists\n  if (query.distinct) {\n    pipeline = pipeline.pipe(distinct(([_key, row]) => row.$selected))\n  }\n\n  // Process orderBy parameter if it exists\n  if (query.orderBy && query.orderBy.length > 0) {\n    const orderedPipeline = processOrderBy(\n      rawQuery,\n      pipeline,\n      query.orderBy,\n      query.select || {},\n      collections[mainCollectionId]!,\n      optimizableOrderByCollections,\n      setWindowFn,\n      query.limit,\n      query.offset,\n    )\n\n    // Final step: extract the $selected and include orderBy index\n    const resultPipeline = orderedPipeline.pipe(\n      map(([key, [row, orderByIndex]]) => {\n        // Extract the final results from $selected and include orderBy index\n        const raw = (row as any).$selected\n        const finalResults = unwrapValue(raw)\n        return [key, [finalResults, orderByIndex]] as [unknown, [any, string]]\n      }),\n    )\n\n    const result = resultPipeline\n    // Cache the result before returning (use original query as key)\n    const compilationResult = {\n      collectionId: mainCollectionId,\n      pipeline: result,\n      sourceWhereClauses,\n      aliasToCollectionId,\n      aliasRemapping,\n    }\n    cache.set(rawQuery, compilationResult)\n\n    return compilationResult\n  } else if (query.limit !== undefined || query.offset !== undefined) {\n    // If there's a limit or offset without orderBy, throw an error\n    throw new LimitOffsetRequireOrderByError()\n  }\n\n  // Final step: extract the $selected and return tuple format (no orderBy)\n  const resultPipeline: ResultStream = pipeline.pipe(\n    map(([key, row]) => {\n      // Extract the final results from $selected and return [key, [results, undefined]]\n      const raw = (row as any).$selected\n      const finalResults = unwrapValue(raw)\n      return [key, [finalResults, undefined]] as [\n        unknown,\n        [any, string | undefined],\n      ]\n    }),\n  )\n\n  const result = resultPipeline\n  // Cache the result before returning (use original query as key)\n  const compilationResult = {\n    collectionId: mainCollectionId,\n    pipeline: result,\n    sourceWhereClauses,\n    aliasToCollectionId,\n    aliasRemapping,\n  }\n  cache.set(rawQuery, compilationResult)\n\n  return compilationResult\n}\n\n/**\n * Collects aliases used for DIRECT collection references (not subqueries).\n * Used to validate that subqueries don't reuse parent query collection aliases.\n * Only direct CollectionRef aliases matter - QueryRef aliases don't cause conflicts.\n */\nfunction collectDirectCollectionAliases(query: QueryIR): Set<string> {\n  const aliases = new Set<string>()\n\n  // Collect FROM alias only if it's a direct collection reference\n  if (query.from.type === `collectionRef`) {\n    aliases.add(query.from.alias)\n  }\n\n  // Collect JOIN aliases only for direct collection references\n  if (query.join) {\n    for (const joinClause of query.join) {\n      if (joinClause.from.type === `collectionRef`) {\n        aliases.add(joinClause.from.alias)\n      }\n    }\n  }\n\n  return aliases\n}\n\n/**\n * Validates the structure of a query and its subqueries.\n * Checks that subqueries don't reuse collection aliases from parent queries.\n * This must be called on the RAW query before optimization.\n */\nfunction validateQueryStructure(\n  query: QueryIR,\n  parentCollectionAliases: Set<string> = new Set(),\n): void {\n  // Collect direct collection aliases from this query level\n  const currentLevelAliases = collectDirectCollectionAliases(query)\n\n  // Check if any current alias conflicts with parent aliases\n  for (const alias of currentLevelAliases) {\n    if (parentCollectionAliases.has(alias)) {\n      throw new DuplicateAliasInSubqueryError(\n        alias,\n        Array.from(parentCollectionAliases),\n      )\n    }\n  }\n\n  // Combine parent and current aliases for checking nested subqueries\n  const combinedAliases = new Set([\n    ...parentCollectionAliases,\n    ...currentLevelAliases,\n  ])\n\n  // Recursively validate FROM subquery\n  if (query.from.type === `queryRef`) {\n    validateQueryStructure(query.from.query, combinedAliases)\n  }\n\n  // Recursively validate JOIN subqueries\n  if (query.join) {\n    for (const joinClause of query.join) {\n      if (joinClause.from.type === `queryRef`) {\n        validateQueryStructure(joinClause.from.query, combinedAliases)\n      }\n    }\n  }\n}\n\n/**\n * Processes the FROM clause, handling direct collection references and subqueries.\n * Populates `aliasToCollectionId` and `aliasRemapping` for per-alias subscription tracking.\n */\nfunction processFrom(\n  from: CollectionRef | QueryRef,\n  allInputs: Record<string, KeyedStream>,\n  collections: Record<string, Collection>,\n  subscriptions: Record<string, CollectionSubscription>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazySources: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,\n  cache: QueryCache,\n  queryMapping: QueryMapping,\n  aliasToCollectionId: Record<string, string>,\n  aliasRemapping: Record<string, string>,\n  sourceWhereClauses: Map<string, BasicExpression<boolean>>,\n): { alias: string; input: KeyedStream; collectionId: string } {\n  switch (from.type) {\n    case `collectionRef`: {\n      const input = allInputs[from.alias]\n      if (!input) {\n        throw new CollectionInputNotFoundError(\n          from.alias,\n          from.collection.id,\n          Object.keys(allInputs),\n        )\n      }\n      aliasToCollectionId[from.alias] = from.collection.id\n      return { alias: from.alias, input, collectionId: from.collection.id }\n    }\n    case `queryRef`: {\n      // Find the original query for caching purposes\n      const originalQuery = queryMapping.get(from.query) || from.query\n\n      // Recursively compile the sub-query with cache\n      const subQueryResult = compileQuery(\n        originalQuery,\n        allInputs,\n        collections,\n        subscriptions,\n        callbacks,\n        lazySources,\n        optimizableOrderByCollections,\n        setWindowFn,\n        cache,\n        queryMapping,\n      )\n\n      // Pull up alias mappings from subquery to parent scope.\n      // This includes both the innermost alias-to-collection mappings AND\n      // any existing remappings from nested subquery levels.\n      Object.assign(aliasToCollectionId, subQueryResult.aliasToCollectionId)\n      Object.assign(aliasRemapping, subQueryResult.aliasRemapping)\n\n      // Pull up source WHERE clauses from subquery to parent scope.\n      // This enables loadSubset to receive the correct where clauses for subquery collections.\n      //\n      // IMPORTANT: Skip pull-up for optimizer-created subqueries. These are detected when:\n      // 1. The outer alias (from.alias) matches the inner alias (from.query.from.alias)\n      // 2. The subquery was found in queryMapping (it's a user-defined subquery, not optimizer-created)\n      //\n      // For optimizer-created subqueries, the parent already has the sourceWhereClauses\n      // extracted from the original raw query, so pulling up would be redundant.\n      // More importantly, pulling up for optimizer-created subqueries can cause issues\n      // when the optimizer has restructured the query.\n      const isUserDefinedSubquery = queryMapping.has(from.query)\n      const subqueryFromAlias = from.query.from.alias\n      const isOptimizerCreated =\n        !isUserDefinedSubquery && from.alias === subqueryFromAlias\n\n      if (!isOptimizerCreated) {\n        for (const [alias, whereClause] of subQueryResult.sourceWhereClauses) {\n          sourceWhereClauses.set(alias, whereClause)\n        }\n      }\n\n      // Create a FLATTENED remapping from outer alias to innermost alias.\n      // For nested subqueries, this ensures one-hop lookups (not recursive chains).\n      //\n      // Example with 3-level nesting:\n      //   Inner:  .from({ user: usersCollection })\n      //   Middle: .from({ activeUser: innerSubquery })     → creates: activeUser → user\n      //   Outer:  .from({ author: middleSubquery })        → creates: author → user (not author → activeUser)\n      //\n      // The key insight: We search through the PULLED-UP aliasToCollectionId (which contains\n      // the innermost 'user' alias), so we always map directly to the deepest level.\n      // This means aliasRemapping[alias] is always a single lookup, never recursive.\n      // Needed for subscription resolution during lazy loading.\n      const innerAlias = Object.keys(subQueryResult.aliasToCollectionId).find(\n        (alias) =>\n          subQueryResult.aliasToCollectionId[alias] ===\n          subQueryResult.collectionId,\n      )\n      if (innerAlias && innerAlias !== from.alias) {\n        aliasRemapping[from.alias] = innerAlias\n      }\n\n      // Extract the pipeline from the compilation result\n      const subQueryInput = subQueryResult.pipeline\n\n      // Subqueries may return [key, [value, orderByIndex]] (with ORDER BY) or [key, value] (without ORDER BY)\n      // We need to extract just the value for use in parent queries\n      const extractedInput = subQueryInput.pipe(\n        map((data: any) => {\n          const [key, [value, _orderByIndex]] = data\n          // Unwrap Value expressions that might have leaked through as the entire row\n          const unwrapped = unwrapValue(value)\n          return [key, unwrapped] as [unknown, any]\n        }),\n      )\n\n      return {\n        alias: from.alias,\n        input: extractedInput,\n        collectionId: subQueryResult.collectionId,\n      }\n    }\n    default:\n      throw new UnsupportedFromTypeError((from as any).type)\n  }\n}\n\n// Helper to check if a value is a Value expression\nfunction isValue(raw: any): boolean {\n  return (\n    raw instanceof ValClass ||\n    (raw && typeof raw === `object` && `type` in raw && raw.type === `val`)\n  )\n}\n\n// Helper to unwrap a Value expression or return the value itself\nfunction unwrapValue(value: any): any {\n  return isValue(value) ? value.value : value\n}\n\n/**\n * Recursively maps optimized subqueries to their original queries for proper caching.\n * This ensures that when we encounter the same QueryRef object in different contexts,\n * we can find the original query to check the cache.\n */\nfunction mapNestedQueries(\n  optimizedQuery: QueryIR,\n  originalQuery: QueryIR,\n  queryMapping: QueryMapping,\n): void {\n  // Map the FROM clause if it's a QueryRef\n  if (\n    optimizedQuery.from.type === `queryRef` &&\n    originalQuery.from.type === `queryRef`\n  ) {\n    queryMapping.set(optimizedQuery.from.query, originalQuery.from.query)\n    // Recursively map nested queries\n    mapNestedQueries(\n      optimizedQuery.from.query,\n      originalQuery.from.query,\n      queryMapping,\n    )\n  }\n\n  // Map JOIN clauses if they exist\n  if (optimizedQuery.join && originalQuery.join) {\n    for (\n      let i = 0;\n      i < optimizedQuery.join.length && i < originalQuery.join.length;\n      i++\n    ) {\n      const optimizedJoin = optimizedQuery.join[i]!\n      const originalJoin = originalQuery.join[i]!\n\n      if (\n        optimizedJoin.from.type === `queryRef` &&\n        originalJoin.from.type === `queryRef`\n      ) {\n        queryMapping.set(optimizedJoin.from.query, originalJoin.from.query)\n        // Recursively map nested queries in joins\n        mapNestedQueries(\n          optimizedJoin.from.query,\n          originalJoin.from.query,\n          queryMapping,\n        )\n      }\n    }\n  }\n}\n\nfunction getRefFromAlias(\n  query: QueryIR,\n  alias: string,\n): CollectionRef | QueryRef | void {\n  if (query.from.alias === alias) {\n    return query.from\n  }\n\n  for (const join of query.join || []) {\n    if (join.from.alias === alias) {\n      return join.from\n    }\n  }\n}\n\n/**\n * Follows the given reference in a query\n * until its finds the root field the reference points to.\n * @returns The collection, its alias, and the path to the root field in this collection\n */\nexport function followRef(\n  query: QueryIR,\n  ref: PropRef<any>,\n  collection: Collection,\n): { collection: Collection; path: Array<string> } | void {\n  if (ref.path.length === 0) {\n    return\n  }\n\n  if (ref.path.length === 1) {\n    // This field should be part of this collection\n    const field = ref.path[0]!\n    // is it part of the select clause?\n    if (query.select) {\n      const selectedField = query.select[field]\n      if (selectedField && selectedField.type === `ref`) {\n        return followRef(query, selectedField, collection)\n      }\n    }\n\n    // Either this field is not part of the select clause\n    // and thus it must be part of the collection itself\n    // or it is part of the select but is not a reference\n    // so we can stop here and don't have to follow it\n    return { collection, path: [field] }\n  }\n\n  if (ref.path.length > 1) {\n    // This is a nested field\n    const [alias, ...rest] = ref.path\n    const aliasRef = getRefFromAlias(query, alias!)\n    if (!aliasRef) {\n      return\n    }\n\n    if (aliasRef.type === `queryRef`) {\n      return followRef(aliasRef.query, new PropRef(rest), collection)\n    } else {\n      // This is a reference to a collection\n      // we can't follow it further\n      // so the field must be on the collection itself\n      return { collection: aliasRef.collection, path: rest }\n    }\n  }\n}\n\nexport type CompileQueryFn = typeof compileQuery\n"],"names":["resultPipeline","result","compilationResult","ValClass"],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../../src/query/compiler/index.ts"],"sourcesContent":["import { distinct, filter, map } from '@tanstack/db-ivm'\nimport { optimizeQuery } from '../optimizer.js'\nimport {\n  CollectionInputNotFoundError,\n  DistinctRequiresSelectError,\n  DuplicateAliasInSubqueryError,\n  FnSelectWithGroupByError,\n  HavingRequiresGroupByError,\n  LimitOffsetRequireOrderByError,\n  UnsupportedFromTypeError,\n} from '../../errors.js'\nimport { PropRef, Value as ValClass, getWhereExpression } from '../ir.js'\nimport { compileExpression, toBooleanPredicate } from './evaluators.js'\nimport { processJoins } from './joins.js'\nimport { containsAggregate, processGroupBy } from './group-by.js'\nimport { processOrderBy } from './order-by.js'\nimport { processSelect } from './select.js'\nimport type { CollectionSubscription } from '../../collection/subscription.js'\nimport type { OrderByOptimizationInfo } from './order-by.js'\nimport type {\n  BasicExpression,\n  CollectionRef,\n  QueryIR,\n  QueryRef,\n} from '../ir.js'\nimport type { LazyCollectionCallbacks } from './joins.js'\nimport type { Collection } from '../../collection/index.js'\nimport type {\n  KeyedStream,\n  NamespacedAndKeyedStream,\n  ResultStream,\n} from '../../types.js'\nimport type { QueryCache, QueryMapping, WindowOptions } from './types.js'\n\nexport type { WindowOptions } from './types.js'\n\n/**\n * Result of query compilation including both the pipeline and source-specific WHERE clauses\n */\nexport interface CompilationResult {\n  /** The ID of the main collection */\n  collectionId: string\n\n  /** The compiled query pipeline (D2 stream) */\n  pipeline: ResultStream\n\n  /** Map of source aliases to their WHERE clauses for index optimization */\n  sourceWhereClauses: Map<string, BasicExpression<boolean>>\n\n  /**\n   * Maps each source alias to its collection ID. Enables per-alias subscriptions for self-joins.\n   * Example: `{ employee: 'employees-col-id', manager: 'employees-col-id' }`\n   */\n  aliasToCollectionId: Record<string, string>\n\n  /**\n   * Flattened mapping from outer alias to innermost alias for subqueries.\n   * Always provides one-hop lookups, never recursive chains.\n   *\n   * Example: `{ activeUser: 'user' }` when `.from({ activeUser: subquery })`\n   * where the subquery uses `.from({ user: collection })`.\n   *\n   * For deeply nested subqueries, the mapping goes directly to the innermost alias:\n   * `{ author: 'user' }` (not `{ author: 'activeUser' }`), so `aliasRemapping[alias]`\n   * always resolves in a single lookup.\n   *\n   * Used to resolve subscriptions during lazy loading when join aliases differ from\n   * the inner aliases where collection subscriptions were created.\n   */\n  aliasRemapping: Record<string, string>\n}\n\n/**\n * Compiles a query IR into a D2 pipeline\n * @param rawQuery The query IR to compile\n * @param inputs Mapping of source aliases to input streams (e.g., `{ employee: input1, manager: input2 }`)\n * @param collections Mapping of collection IDs to Collection instances\n * @param subscriptions Mapping of source aliases to CollectionSubscription instances\n * @param callbacks Mapping of source aliases to lazy loading callbacks\n * @param lazySources Set of source aliases that should load data lazily\n * @param optimizableOrderByCollections Map of collection IDs to order-by optimization info\n * @param cache Optional cache for compiled subqueries (used internally for recursion)\n * @param queryMapping Optional mapping from optimized queries to original queries\n * @returns A CompilationResult with the pipeline, source WHERE clauses, and alias metadata\n */\nexport function compileQuery(\n  rawQuery: QueryIR,\n  inputs: Record<string, KeyedStream>,\n  collections: Record<string, Collection<any, any, any, any, any>>,\n  subscriptions: Record<string, CollectionSubscription>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazySources: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,\n  cache: QueryCache = new WeakMap(),\n  queryMapping: QueryMapping = new WeakMap(),\n): CompilationResult {\n  // Check if the original raw query has already been compiled\n  const cachedResult = cache.get(rawQuery)\n  if (cachedResult) {\n    return cachedResult\n  }\n\n  // Validate the raw query BEFORE optimization to check user's original structure.\n  // This must happen before optimization because the optimizer may create internal\n  // subqueries (e.g., for predicate pushdown) that reuse aliases, which is fine.\n  validateQueryStructure(rawQuery)\n\n  // Optimize the query before compilation\n  const { optimizedQuery: query, sourceWhereClauses } = optimizeQuery(rawQuery)\n\n  // Create mapping from optimized query to original for caching\n  queryMapping.set(query, rawQuery)\n  mapNestedQueries(query, rawQuery, queryMapping)\n\n  // Create a copy of the inputs map to avoid modifying the original\n  const allInputs = { ...inputs }\n\n  // Track alias to collection id relationships discovered during compilation.\n  // This includes all user-declared aliases plus inner aliases from subqueries.\n  const aliasToCollectionId: Record<string, string> = {}\n\n  // Track alias remapping for subqueries (outer alias → inner alias)\n  // e.g., when .join({ activeUser: subquery }) where subquery uses .from({ user: collection })\n  // we store: aliasRemapping['activeUser'] = 'user'\n  const aliasRemapping: Record<string, string> = {}\n\n  // Create a map of source aliases to input streams.\n  // Inputs MUST be keyed by alias (e.g., `{ employee: input1, manager: input2 }`),\n  // not by collection ID. This enables per-alias subscriptions where different aliases\n  // of the same collection (e.g., self-joins) maintain independent filtered streams.\n  const sources: Record<string, KeyedStream> = {}\n\n  // Process the FROM clause to get the main source\n  const {\n    alias: mainSource,\n    input: mainInput,\n    collectionId: mainCollectionId,\n  } = processFrom(\n    query.from,\n    allInputs,\n    collections,\n    subscriptions,\n    callbacks,\n    lazySources,\n    optimizableOrderByCollections,\n    setWindowFn,\n    cache,\n    queryMapping,\n    aliasToCollectionId,\n    aliasRemapping,\n    sourceWhereClauses,\n  )\n  sources[mainSource] = mainInput\n\n  // Prepare the initial pipeline with the main source wrapped in its alias\n  let pipeline: NamespacedAndKeyedStream = mainInput.pipe(\n    map(([key, row]) => {\n      // Initialize the record with a nested structure\n      const ret = [key, { [mainSource]: row }] as [\n        string,\n        Record<string, typeof row>,\n      ]\n      return ret\n    }),\n  )\n\n  // Process JOIN clauses if they exist\n  if (query.join && query.join.length > 0) {\n    pipeline = processJoins(\n      pipeline,\n      query.join,\n      sources,\n      mainCollectionId,\n      mainSource,\n      allInputs,\n      cache,\n      queryMapping,\n      collections,\n      subscriptions,\n      callbacks,\n      lazySources,\n      optimizableOrderByCollections,\n      setWindowFn,\n      rawQuery,\n      compileQuery,\n      aliasToCollectionId,\n      aliasRemapping,\n      sourceWhereClauses,\n    )\n  }\n\n  // Process the WHERE clause if it exists\n  if (query.where && query.where.length > 0) {\n    // Apply each WHERE condition as a filter (they are ANDed together)\n    for (const where of query.where) {\n      const whereExpression = getWhereExpression(where)\n      const compiledWhere = compileExpression(whereExpression)\n      pipeline = pipeline.pipe(\n        filter(([_key, namespacedRow]) => {\n          return toBooleanPredicate(compiledWhere(namespacedRow))\n        }),\n      )\n    }\n  }\n\n  // Process functional WHERE clauses if they exist\n  if (query.fnWhere && query.fnWhere.length > 0) {\n    for (const fnWhere of query.fnWhere) {\n      pipeline = pipeline.pipe(\n        filter(([_key, namespacedRow]) => {\n          return toBooleanPredicate(fnWhere(namespacedRow))\n        }),\n      )\n    }\n  }\n\n  if (query.distinct && !query.fnSelect && !query.select) {\n    throw new DistinctRequiresSelectError()\n  }\n\n  if (query.fnSelect && query.groupBy && query.groupBy.length > 0) {\n    throw new FnSelectWithGroupByError()\n  }\n\n  // Process the SELECT clause early - always create $selected\n  // This eliminates duplication and allows for DISTINCT implementation\n  if (query.fnSelect) {\n    // Handle functional select - apply the function to transform the row\n    pipeline = pipeline.pipe(\n      map(([key, namespacedRow]) => {\n        const selectResults = query.fnSelect!(namespacedRow)\n        return [\n          key,\n          {\n            ...namespacedRow,\n            $selected: selectResults,\n          },\n        ] as [string, typeof namespacedRow & { $selected: any }]\n      }),\n    )\n  } else if (query.select) {\n    pipeline = processSelect(pipeline, query.select, allInputs)\n  } else {\n    // If no SELECT clause, create $selected with the main table data\n    pipeline = pipeline.pipe(\n      map(([key, namespacedRow]) => {\n        const selectResults =\n          !query.join && !query.groupBy\n            ? namespacedRow[mainSource]\n            : namespacedRow\n\n        return [\n          key,\n          {\n            ...namespacedRow,\n            $selected: selectResults,\n          },\n        ] as [string, typeof namespacedRow & { $selected: any }]\n      }),\n    )\n  }\n\n  // Process the GROUP BY clause if it exists\n  if (query.groupBy && query.groupBy.length > 0) {\n    pipeline = processGroupBy(\n      pipeline,\n      query.groupBy,\n      query.having,\n      query.select,\n      query.fnHaving,\n    )\n  } else if (query.select) {\n    // Check if SELECT contains aggregates but no GROUP BY (implicit single-group aggregation)\n    const hasAggregates = Object.values(query.select).some(\n      (expr) => expr.type === `agg` || containsAggregate(expr),\n    )\n    if (hasAggregates) {\n      // Handle implicit single-group aggregation\n      pipeline = processGroupBy(\n        pipeline,\n        [], // Empty group by means single group\n        query.having,\n        query.select,\n        query.fnHaving,\n      )\n    }\n  }\n\n  // Process the HAVING clause if it exists (only applies after GROUP BY)\n  if (query.having && (!query.groupBy || query.groupBy.length === 0)) {\n    // Check if we have aggregates in SELECT that would trigger implicit grouping\n    const hasAggregates = query.select\n      ? Object.values(query.select).some((expr) => expr.type === `agg`)\n      : false\n\n    if (!hasAggregates) {\n      throw new HavingRequiresGroupByError()\n    }\n  }\n\n  // Process functional HAVING clauses outside of GROUP BY (treat as additional WHERE filters)\n  if (\n    query.fnHaving &&\n    query.fnHaving.length > 0 &&\n    (!query.groupBy || query.groupBy.length === 0)\n  ) {\n    // If there's no GROUP BY but there are fnHaving clauses, apply them as filters\n    for (const fnHaving of query.fnHaving) {\n      pipeline = pipeline.pipe(\n        filter(([_key, namespacedRow]) => {\n          return fnHaving(namespacedRow)\n        }),\n      )\n    }\n  }\n\n  // Process the DISTINCT clause if it exists\n  if (query.distinct) {\n    pipeline = pipeline.pipe(distinct(([_key, row]) => row.$selected))\n  }\n\n  // Process orderBy parameter if it exists\n  if (query.orderBy && query.orderBy.length > 0) {\n    const orderedPipeline = processOrderBy(\n      rawQuery,\n      pipeline,\n      query.orderBy,\n      query.select || {},\n      collections[mainCollectionId]!,\n      optimizableOrderByCollections,\n      setWindowFn,\n      query.limit,\n      query.offset,\n    )\n\n    // Final step: extract the $selected and include orderBy index\n    const resultPipeline = orderedPipeline.pipe(\n      map(([key, [row, orderByIndex]]) => {\n        // Extract the final results from $selected and include orderBy index\n        const raw = (row as any).$selected\n        const finalResults = unwrapValue(raw)\n        return [key, [finalResults, orderByIndex]] as [unknown, [any, string]]\n      }),\n    )\n\n    const result = resultPipeline\n    // Cache the result before returning (use original query as key)\n    const compilationResult = {\n      collectionId: mainCollectionId,\n      pipeline: result,\n      sourceWhereClauses,\n      aliasToCollectionId,\n      aliasRemapping,\n    }\n    cache.set(rawQuery, compilationResult)\n\n    return compilationResult\n  } else if (query.limit !== undefined || query.offset !== undefined) {\n    // If there's a limit or offset without orderBy, throw an error\n    throw new LimitOffsetRequireOrderByError()\n  }\n\n  // Final step: extract the $selected and return tuple format (no orderBy)\n  const resultPipeline: ResultStream = pipeline.pipe(\n    map(([key, row]) => {\n      // Extract the final results from $selected and return [key, [results, undefined]]\n      const raw = (row as any).$selected\n      const finalResults = unwrapValue(raw)\n      return [key, [finalResults, undefined]] as [\n        unknown,\n        [any, string | undefined],\n      ]\n    }),\n  )\n\n  const result = resultPipeline\n  // Cache the result before returning (use original query as key)\n  const compilationResult = {\n    collectionId: mainCollectionId,\n    pipeline: result,\n    sourceWhereClauses,\n    aliasToCollectionId,\n    aliasRemapping,\n  }\n  cache.set(rawQuery, compilationResult)\n\n  return compilationResult\n}\n\n/**\n * Collects aliases used for DIRECT collection references (not subqueries).\n * Used to validate that subqueries don't reuse parent query collection aliases.\n * Only direct CollectionRef aliases matter - QueryRef aliases don't cause conflicts.\n */\nfunction collectDirectCollectionAliases(query: QueryIR): Set<string> {\n  const aliases = new Set<string>()\n\n  // Collect FROM alias only if it's a direct collection reference\n  if (query.from.type === `collectionRef`) {\n    aliases.add(query.from.alias)\n  }\n\n  // Collect JOIN aliases only for direct collection references\n  if (query.join) {\n    for (const joinClause of query.join) {\n      if (joinClause.from.type === `collectionRef`) {\n        aliases.add(joinClause.from.alias)\n      }\n    }\n  }\n\n  return aliases\n}\n\n/**\n * Validates the structure of a query and its subqueries.\n * Checks that subqueries don't reuse collection aliases from parent queries.\n * This must be called on the RAW query before optimization.\n */\nfunction validateQueryStructure(\n  query: QueryIR,\n  parentCollectionAliases: Set<string> = new Set(),\n): void {\n  // Collect direct collection aliases from this query level\n  const currentLevelAliases = collectDirectCollectionAliases(query)\n\n  // Check if any current alias conflicts with parent aliases\n  for (const alias of currentLevelAliases) {\n    if (parentCollectionAliases.has(alias)) {\n      throw new DuplicateAliasInSubqueryError(\n        alias,\n        Array.from(parentCollectionAliases),\n      )\n    }\n  }\n\n  // Combine parent and current aliases for checking nested subqueries\n  const combinedAliases = new Set([\n    ...parentCollectionAliases,\n    ...currentLevelAliases,\n  ])\n\n  // Recursively validate FROM subquery\n  if (query.from.type === `queryRef`) {\n    validateQueryStructure(query.from.query, combinedAliases)\n  }\n\n  // Recursively validate JOIN subqueries\n  if (query.join) {\n    for (const joinClause of query.join) {\n      if (joinClause.from.type === `queryRef`) {\n        validateQueryStructure(joinClause.from.query, combinedAliases)\n      }\n    }\n  }\n}\n\n/**\n * Processes the FROM clause, handling direct collection references and subqueries.\n * Populates `aliasToCollectionId` and `aliasRemapping` for per-alias subscription tracking.\n */\nfunction processFrom(\n  from: CollectionRef | QueryRef,\n  allInputs: Record<string, KeyedStream>,\n  collections: Record<string, Collection>,\n  subscriptions: Record<string, CollectionSubscription>,\n  callbacks: Record<string, LazyCollectionCallbacks>,\n  lazySources: Set<string>,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,\n  cache: QueryCache,\n  queryMapping: QueryMapping,\n  aliasToCollectionId: Record<string, string>,\n  aliasRemapping: Record<string, string>,\n  sourceWhereClauses: Map<string, BasicExpression<boolean>>,\n): { alias: string; input: KeyedStream; collectionId: string } {\n  switch (from.type) {\n    case `collectionRef`: {\n      const input = allInputs[from.alias]\n      if (!input) {\n        throw new CollectionInputNotFoundError(\n          from.alias,\n          from.collection.id,\n          Object.keys(allInputs),\n        )\n      }\n      aliasToCollectionId[from.alias] = from.collection.id\n      return { alias: from.alias, input, collectionId: from.collection.id }\n    }\n    case `queryRef`: {\n      // Find the original query for caching purposes\n      const originalQuery = queryMapping.get(from.query) || from.query\n\n      // Recursively compile the sub-query with cache\n      const subQueryResult = compileQuery(\n        originalQuery,\n        allInputs,\n        collections,\n        subscriptions,\n        callbacks,\n        lazySources,\n        optimizableOrderByCollections,\n        setWindowFn,\n        cache,\n        queryMapping,\n      )\n\n      // Pull up alias mappings from subquery to parent scope.\n      // This includes both the innermost alias-to-collection mappings AND\n      // any existing remappings from nested subquery levels.\n      Object.assign(aliasToCollectionId, subQueryResult.aliasToCollectionId)\n      Object.assign(aliasRemapping, subQueryResult.aliasRemapping)\n\n      // Pull up source WHERE clauses from subquery to parent scope.\n      // This enables loadSubset to receive the correct where clauses for subquery collections.\n      //\n      // IMPORTANT: Skip pull-up for optimizer-created subqueries. These are detected when:\n      // 1. The outer alias (from.alias) matches the inner alias (from.query.from.alias)\n      // 2. The subquery was found in queryMapping (it's a user-defined subquery, not optimizer-created)\n      //\n      // For optimizer-created subqueries, the parent already has the sourceWhereClauses\n      // extracted from the original raw query, so pulling up would be redundant.\n      // More importantly, pulling up for optimizer-created subqueries can cause issues\n      // when the optimizer has restructured the query.\n      const isUserDefinedSubquery = queryMapping.has(from.query)\n      const subqueryFromAlias = from.query.from.alias\n      const isOptimizerCreated =\n        !isUserDefinedSubquery && from.alias === subqueryFromAlias\n\n      if (!isOptimizerCreated) {\n        for (const [alias, whereClause] of subQueryResult.sourceWhereClauses) {\n          sourceWhereClauses.set(alias, whereClause)\n        }\n      }\n\n      // Create a FLATTENED remapping from outer alias to innermost alias.\n      // For nested subqueries, this ensures one-hop lookups (not recursive chains).\n      //\n      // Example with 3-level nesting:\n      //   Inner:  .from({ user: usersCollection })\n      //   Middle: .from({ activeUser: innerSubquery })     → creates: activeUser → user\n      //   Outer:  .from({ author: middleSubquery })        → creates: author → user (not author → activeUser)\n      //\n      // The key insight: We search through the PULLED-UP aliasToCollectionId (which contains\n      // the innermost 'user' alias), so we always map directly to the deepest level.\n      // This means aliasRemapping[alias] is always a single lookup, never recursive.\n      // Needed for subscription resolution during lazy loading.\n      const innerAlias = Object.keys(subQueryResult.aliasToCollectionId).find(\n        (alias) =>\n          subQueryResult.aliasToCollectionId[alias] ===\n          subQueryResult.collectionId,\n      )\n      if (innerAlias && innerAlias !== from.alias) {\n        aliasRemapping[from.alias] = innerAlias\n      }\n\n      // Extract the pipeline from the compilation result\n      const subQueryInput = subQueryResult.pipeline\n\n      // Subqueries may return [key, [value, orderByIndex]] (with ORDER BY) or [key, value] (without ORDER BY)\n      // We need to extract just the value for use in parent queries\n      const extractedInput = subQueryInput.pipe(\n        map((data: any) => {\n          const [key, [value, _orderByIndex]] = data\n          // Unwrap Value expressions that might have leaked through as the entire row\n          const unwrapped = unwrapValue(value)\n          return [key, unwrapped] as [unknown, any]\n        }),\n      )\n\n      return {\n        alias: from.alias,\n        input: extractedInput,\n        collectionId: subQueryResult.collectionId,\n      }\n    }\n    default:\n      throw new UnsupportedFromTypeError((from as any).type)\n  }\n}\n\n// Helper to check if a value is a Value expression\nfunction isValue(raw: any): boolean {\n  return (\n    raw instanceof ValClass ||\n    (raw && typeof raw === `object` && `type` in raw && raw.type === `val`)\n  )\n}\n\n// Helper to unwrap a Value expression or return the value itself\nfunction unwrapValue(value: any): any {\n  return isValue(value) ? value.value : value\n}\n\n/**\n * Recursively maps optimized subqueries to their original queries for proper caching.\n * This ensures that when we encounter the same QueryRef object in different contexts,\n * we can find the original query to check the cache.\n */\nfunction mapNestedQueries(\n  optimizedQuery: QueryIR,\n  originalQuery: QueryIR,\n  queryMapping: QueryMapping,\n): void {\n  // Map the FROM clause if it's a QueryRef\n  if (\n    optimizedQuery.from.type === `queryRef` &&\n    originalQuery.from.type === `queryRef`\n  ) {\n    queryMapping.set(optimizedQuery.from.query, originalQuery.from.query)\n    // Recursively map nested queries\n    mapNestedQueries(\n      optimizedQuery.from.query,\n      originalQuery.from.query,\n      queryMapping,\n    )\n  }\n\n  // Map JOIN clauses if they exist\n  if (optimizedQuery.join && originalQuery.join) {\n    for (\n      let i = 0;\n      i < optimizedQuery.join.length && i < originalQuery.join.length;\n      i++\n    ) {\n      const optimizedJoin = optimizedQuery.join[i]!\n      const originalJoin = originalQuery.join[i]!\n\n      if (\n        optimizedJoin.from.type === `queryRef` &&\n        originalJoin.from.type === `queryRef`\n      ) {\n        queryMapping.set(optimizedJoin.from.query, originalJoin.from.query)\n        // Recursively map nested queries in joins\n        mapNestedQueries(\n          optimizedJoin.from.query,\n          originalJoin.from.query,\n          queryMapping,\n        )\n      }\n    }\n  }\n}\n\nfunction getRefFromAlias(\n  query: QueryIR,\n  alias: string,\n): CollectionRef | QueryRef | void {\n  if (query.from.alias === alias) {\n    return query.from\n  }\n\n  for (const join of query.join || []) {\n    if (join.from.alias === alias) {\n      return join.from\n    }\n  }\n}\n\n/**\n * Follows the given reference in a query\n * until its finds the root field the reference points to.\n * @returns The collection, its alias, and the path to the root field in this collection\n */\nexport function followRef(\n  query: QueryIR,\n  ref: PropRef<any>,\n  collection: Collection,\n): { collection: Collection; path: Array<string> } | void {\n  if (ref.path.length === 0) {\n    return\n  }\n\n  if (ref.path.length === 1) {\n    // This field should be part of this collection\n    const field = ref.path[0]!\n    // is it part of the select clause?\n    if (query.select) {\n      const selectedField = query.select[field]\n      if (selectedField && selectedField.type === `ref`) {\n        return followRef(query, selectedField, collection)\n      }\n    }\n\n    // Either this field is not part of the select clause\n    // and thus it must be part of the collection itself\n    // or it is part of the select but is not a reference\n    // so we can stop here and don't have to follow it\n    return { collection, path: [field] }\n  }\n\n  if (ref.path.length > 1) {\n    // This is a nested field\n    const [alias, ...rest] = ref.path\n    const aliasRef = getRefFromAlias(query, alias!)\n    if (!aliasRef) {\n      return\n    }\n\n    if (aliasRef.type === `queryRef`) {\n      return followRef(aliasRef.query, new PropRef(rest), collection)\n    } else {\n      // This is a reference to a collection\n      // we can't follow it further\n      // so the field must be on the collection itself\n      return { collection: aliasRef.collection, path: rest }\n    }\n  }\n}\n\nexport type CompileQueryFn = typeof compileQuery\n"],"names":["resultPipeline","result","compilationResult","ValClass"],"mappings":"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"}

package/dist/esm/query/effect.d.ts

@@ -0,0 +1,94 @@
+import { InitialQueryBuilder, QueryBuilder } from './builder/index.js';
+import { Context } from './builder/types.js';
+/** Event types for query result deltas */
+export type DeltaType = 'enter' | 'exit' | 'update';
+/** Delta event emitted when a row enters, exits, or updates within a query result */
+export type DeltaEvent<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number> = {
+    type: 'enter';
+    key: TKey;
+    /** Current value for the entering row */
+    value: TRow;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'exit';
+    key: TKey;
+    /** Current value for the exiting row */
+    value: TRow;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'update';
+    key: TKey;
+    /** Current value after the update */
+    value: TRow;
+    /** Previous value before the batch */
+    previousValue: TRow;
+    metadata?: Record<string, unknown>;
+};
+/** Context passed to effect handlers */
+export interface EffectContext {
+    /** ID of this effect (auto-generated if not provided) */
+    effectId: string;
+    /** Aborted when effect.dispose() is called */
+    signal: AbortSignal;
+}
+/** Query input - can be a builder function or a prebuilt query */
+export type EffectQueryInput<TContext extends Context> = ((q: InitialQueryBuilder) => QueryBuilder<TContext>) | QueryBuilder<TContext>;
+type EffectEventHandler<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number> = (event: DeltaEvent<TRow, TKey>, ctx: EffectContext) => void | Promise<void>;
+type EffectBatchHandler<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number> = (events: Array<DeltaEvent<TRow, TKey>>, ctx: EffectContext) => void | Promise<void>;
+/** Effect configuration */
+export interface EffectConfig<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+    /** Optional ID for debugging/tracing */
+    id?: string;
+    /** Query to watch for deltas */
+    query: EffectQueryInput<any>;
+    /** Called once for each row entering the query result */
+    onEnter?: EffectEventHandler<TRow, TKey>;
+    /** Called once for each row updating within the query result */
+    onUpdate?: EffectEventHandler<TRow, TKey>;
+    /** Called once for each row exiting the query result */
+    onExit?: EffectEventHandler<TRow, TKey>;
+    /** Called once per graph run with all delta events from that batch */
+    onBatch?: EffectBatchHandler<TRow, TKey>;
+    /** Error handler for exceptions thrown by effect callbacks */
+    onError?: (error: Error, event: DeltaEvent<TRow, TKey>) => void;
+    /**
+     * Called when a source collection enters an error or cleaned-up state.
+     * The effect is automatically disposed after this callback fires.
+     * If not provided, the error is logged to console.error.
+     */
+    onSourceError?: (error: Error) => void;
+    /**
+     * Skip deltas during initial collection load.
+     * Defaults to false (process all deltas including initial sync).
+     * Set to true for effects that should only process new changes.
+     */
+    skipInitial?: boolean;
+}
+/** Handle returned by createEffect */
+export interface Effect {
+    /** Dispose the effect. Returns a promise that resolves when in-flight handlers complete. */
+    dispose: () => Promise<void>;
+    /** Whether this effect has been disposed */
+    readonly disposed: boolean;
+}
+/**
+ * Creates a reactive effect that fires handlers when rows enter, exit, or
+ * update within a query result. Effects process deltas only — they do not
+ * maintain or require the full materialised query result.
+ *
+ * @example
+ * ```typescript
+ * const effect = createEffect({
+ *   query: (q) => q.from({ msg: messagesCollection })
+ *     .where(({ msg }) => eq(msg.role, 'user')),
+ *   onEnter: async (event) => {
+ *     await generateResponse(event.value)
+ *   },
+ * })
+ *
+ * // Later: stop the effect
+ * await effect.dispose()
+ * ```
+ */
+export declare function createEffect<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number>(config: EffectConfig<TRow, TKey>): Effect;
+export {};