@tanstack/db 0.4.1 → 0.4.3

package/dist/esm/query/optimizer.js.map

@@ -1 +1 @@
-{"version":3,"file":"optimizer.js","sources":["../../../src/query/optimizer.ts"],"sourcesContent":["/**\n * # Query Optimizer\n *\n * The query optimizer improves query performance by implementing predicate pushdown optimization.\n * It rewrites the intermediate representation (IR) to push WHERE clauses as close to the data\n * source as possible, reducing the amount of data processed during joins.\n *\n * ## How It Works\n *\n * The optimizer follows a 4-step process:\n *\n * ### 1. AND Clause Splitting\n * Splits AND clauses at the root level into separate WHERE clauses for granular optimization.\n * ```javascript\n * // Before: WHERE and(eq(users.department_id, 1), gt(users.age, 25))\n * // After:  WHERE eq(users.department_id, 1) + WHERE gt(users.age, 25)\n * ```\n *\n * ### 2. Source Analysis\n * Analyzes each WHERE clause to determine which table sources it references:\n * - Single-source clauses: Touch only one table (e.g., `users.department_id = 1`)\n * - Multi-source clauses: Touch multiple tables (e.g., `users.id = posts.user_id`)\n *\n * ### 3. Clause Grouping\n * Groups WHERE clauses by the sources they touch:\n * - Single-source clauses are grouped by their respective table\n * - Multi-source clauses are combined for the main query\n *\n * ### 4. Subquery Creation\n * Lifts single-source WHERE clauses into subqueries that wrap the original table references.\n *\n * ## Safety & Edge Cases\n *\n * The optimizer includes targeted safety checks to prevent predicate pushdown when it could\n * break query semantics:\n *\n * ### Always Safe Operations\n * - **Creating new subqueries**: Wrapping collection references in subqueries with WHERE clauses\n * - **Main query optimizations**: Moving single-source WHERE clauses from main query to subqueries\n * - **Queries with aggregates/ORDER BY/HAVING**: Can still create new filtered subqueries\n *\n * ### Unsafe Operations (blocked by safety checks)\n * Pushing WHERE clauses **into existing subqueries** that have:\n * - **Aggregates**: GROUP BY, HAVING, or aggregate functions in SELECT (would change aggregation)\n * - **Ordering + Limits**: ORDER BY combined with LIMIT/OFFSET (would change result set)\n * - **Functional Operations**: fnSelect, fnWhere, fnHaving (potential side effects)\n *\n * ### Residual WHERE Clauses\n * For outer joins (LEFT, RIGHT, FULL), WHERE clauses are copied to subqueries for optimization\n * but also kept as \"residual\" clauses in the main query to preserve semantics. This ensures\n * that NULL values from outer joins are properly filtered according to SQL standards.\n *\n * The optimizer tracks which clauses were actually optimized and only removes those from the\n * main query. Subquery reuse is handled safely through immutable query copies.\n *\n * ## Example Optimizations\n *\n * ### Basic Query with Joins\n * **Original Query:**\n * ```javascript\n * query\n *   .from({ users: usersCollection })\n *   .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.user_id))\n *   .where(({users}) => eq(users.department_id, 1))\n *   .where(({posts}) => gt(posts.views, 100))\n *   .where(({users, posts}) => eq(users.id, posts.author_id))\n * ```\n *\n * **Optimized Query:**\n * ```javascript\n * query\n *   .from({\n *     users: subquery\n *       .from({ users: usersCollection })\n *       .where(({users}) => eq(users.department_id, 1))\n *   })\n *   .join({\n *     posts: subquery\n *       .from({ posts: postsCollection })\n *       .where(({posts}) => gt(posts.views, 100))\n *   }, ({users, posts}) => eq(users.id, posts.user_id))\n *   .where(({users, posts}) => eq(users.id, posts.author_id))\n * ```\n *\n * ### Query with Aggregates (Now Optimizable!)\n * **Original Query:**\n * ```javascript\n * query\n *   .from({ users: usersCollection })\n *   .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.user_id))\n *   .where(({users}) => eq(users.department_id, 1))\n *   .groupBy(['users.department_id'])\n *   .select({ count: agg('count', '*') })\n * ```\n *\n * **Optimized Query:**\n * ```javascript\n * query\n *   .from({\n *     users: subquery\n *       .from({ users: usersCollection })\n *       .where(({users}) => eq(users.department_id, 1))\n *   })\n *   .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.user_id))\n *   .groupBy(['users.department_id'])\n *   .select({ count: agg('count', '*') })\n * ```\n *\n * ## Benefits\n *\n * - **Reduced Data Processing**: Filters applied before joins reduce intermediate result size\n * - **Better Performance**: Smaller datasets lead to faster query execution\n * - **Automatic Optimization**: No manual query rewriting required\n * - **Preserves Semantics**: Optimized queries return identical results\n * - **Safe by Design**: Comprehensive checks prevent semantic-breaking optimizations\n *\n * ## Integration\n *\n * The optimizer is automatically called during query compilation before the IR is\n * transformed into a D2Mini pipeline.\n */\n\nimport { deepEquals } from \"../utils.js\"\nimport { CannotCombineEmptyExpressionListError } from \"../errors.js\"\nimport {\n  CollectionRef as CollectionRefClass,\n  Func,\n  PropRef,\n  QueryRef as QueryRefClass,\n  createResidualWhere,\n  getWhereExpression,\n  isResidualWhere,\n} from \"./ir.js\"\nimport { isConvertibleToCollectionFilter } from \"./compiler/expressions.js\"\nimport type { BasicExpression, From, QueryIR, Select, Where } from \"./ir.js\"\n\n/**\n * Represents a WHERE clause after source analysis\n */\nexport interface AnalyzedWhereClause {\n  /** The WHERE expression */\n  expression: BasicExpression<boolean>\n  /** Set of table/source aliases that this WHERE clause touches */\n  touchedSources: Set<string>\n}\n\n/**\n * Represents WHERE clauses grouped by the sources they touch\n */\nexport interface GroupedWhereClauses {\n  /** WHERE clauses that touch only a single source, grouped by source alias */\n  singleSource: Map<string, BasicExpression<boolean>>\n  /** WHERE clauses that touch multiple sources, combined into one expression */\n  multiSource?: BasicExpression<boolean>\n}\n\n/**\n * Result of query optimization including both the optimized query and collection-specific WHERE clauses\n */\nexport interface OptimizationResult {\n  /** The optimized query with WHERE clauses potentially moved to subqueries */\n  optimizedQuery: QueryIR\n  /** Map of collection aliases to their extracted WHERE clauses for index optimization */\n  collectionWhereClauses: Map<string, BasicExpression<boolean>>\n}\n\n/**\n * Main query optimizer entry point that lifts WHERE clauses into subqueries.\n *\n * This function implements multi-level predicate pushdown optimization by recursively\n * moving WHERE clauses through nested subqueries to get them as close to the data\n * sources as possible, then removing redundant subqueries.\n *\n * @param query - The QueryIR to optimize\n * @returns An OptimizationResult with the optimized query and collection WHERE clause mapping\n *\n * @example\n * ```typescript\n * const originalQuery = {\n *   from: new CollectionRef(users, 'u'),\n *   join: [{ from: new CollectionRef(posts, 'p'), ... }],\n *   where: [eq(u.dept_id, 1), gt(p.views, 100)]\n * }\n *\n * const { optimizedQuery, collectionWhereClauses } = optimizeQuery(originalQuery)\n * // Result: Single-source clauses moved to deepest possible subqueries\n * // collectionWhereClauses: Map { 'u' => eq(u.dept_id, 1), 'p' => gt(p.views, 100) }\n * ```\n */\nexport function optimizeQuery(query: QueryIR): OptimizationResult {\n  // First, extract collection WHERE clauses before optimization\n  const collectionWhereClauses = extractCollectionWhereClauses(query)\n\n  // Apply multi-level predicate pushdown with iterative convergence\n  let optimized = query\n  let previousOptimized: QueryIR | undefined\n  let iterations = 0\n  const maxIterations = 10 // Prevent infinite loops\n\n  // Keep optimizing until no more changes occur or max iterations reached\n  while (\n    iterations < maxIterations &&\n    !deepEquals(optimized, previousOptimized)\n  ) {\n    previousOptimized = optimized\n    optimized = applyRecursiveOptimization(optimized)\n    iterations++\n  }\n\n  // Remove redundant subqueries\n  const cleaned = removeRedundantSubqueries(optimized)\n\n  return {\n    optimizedQuery: cleaned,\n    collectionWhereClauses,\n  }\n}\n\n/**\n * Extracts collection-specific WHERE clauses from a query for index optimization.\n * This analyzes the original query to identify WHERE clauses that can be pushed down\n * to specific collections, but only for simple queries without joins.\n *\n * @param query - The original QueryIR to analyze\n * @returns Map of collection aliases to their WHERE clauses\n */\nfunction extractCollectionWhereClauses(\n  query: QueryIR\n): Map<string, BasicExpression<boolean>> {\n  const collectionWhereClauses = new Map<string, BasicExpression<boolean>>()\n\n  // Only analyze queries that have WHERE clauses\n  if (!query.where || query.where.length === 0) {\n    return collectionWhereClauses\n  }\n\n  // Split all AND clauses at the root level for granular analysis\n  const splitWhereClauses = splitAndClauses(query.where)\n\n  // Analyze each WHERE clause to determine which sources it touches\n  const analyzedClauses = splitWhereClauses.map((clause) =>\n    analyzeWhereClause(clause)\n  )\n\n  // Group clauses by single-source vs multi-source\n  const groupedClauses = groupWhereClauses(analyzedClauses)\n\n  // Only include single-source clauses that reference collections directly\n  // and can be converted to BasicExpression format for collection indexes\n  for (const [sourceAlias, whereClause] of groupedClauses.singleSource) {\n    // Check if this source alias corresponds to a collection reference\n    if (isCollectionReference(query, sourceAlias)) {\n      // Check if the WHERE clause can be converted to collection-compatible format\n      if (isConvertibleToCollectionFilter(whereClause)) {\n        collectionWhereClauses.set(sourceAlias, whereClause)\n      }\n    }\n  }\n\n  return collectionWhereClauses\n}\n\n/**\n * Determines if a source alias refers to a collection reference (not a subquery).\n * This is used to identify WHERE clauses that can be pushed down to collection subscriptions.\n *\n * @param query - The query to analyze\n * @param sourceAlias - The source alias to check\n * @returns True if the alias refers to a collection reference\n */\nfunction isCollectionReference(query: QueryIR, sourceAlias: string): boolean {\n  // Check the FROM clause\n  if (query.from.alias === sourceAlias) {\n    return query.from.type === `collectionRef`\n  }\n\n  // Check JOIN clauses\n  if (query.join) {\n    for (const joinClause of query.join) {\n      if (joinClause.from.alias === sourceAlias) {\n        return joinClause.from.type === `collectionRef`\n      }\n    }\n  }\n\n  return false\n}\n\n/**\n * Applies recursive predicate pushdown optimization.\n *\n * @param query - The QueryIR to optimize\n * @returns A new QueryIR with optimizations applied\n */\nfunction applyRecursiveOptimization(query: QueryIR): QueryIR {\n  // First, recursively optimize any existing subqueries\n  const subqueriesOptimized = {\n    ...query,\n    from:\n      query.from.type === `queryRef`\n        ? new QueryRefClass(\n            applyRecursiveOptimization(query.from.query),\n            query.from.alias\n          )\n        : query.from,\n    join: query.join?.map((joinClause) => ({\n      ...joinClause,\n      from:\n        joinClause.from.type === `queryRef`\n          ? new QueryRefClass(\n              applyRecursiveOptimization(joinClause.from.query),\n              joinClause.from.alias\n            )\n          : joinClause.from,\n    })),\n  }\n\n  // Then apply single-level optimization to this query\n  return applySingleLevelOptimization(subqueriesOptimized)\n}\n\n/**\n * Applies single-level predicate pushdown optimization (existing logic)\n */\nfunction applySingleLevelOptimization(query: QueryIR): QueryIR {\n  // Skip optimization if no WHERE clauses exist\n  if (!query.where || query.where.length === 0) {\n    return query\n  }\n\n  // Skip optimization if there are no joins - predicate pushdown only benefits joins\n  // Single-table queries don't benefit from this optimization\n  if (!query.join || query.join.length === 0) {\n    return query\n  }\n\n  // Filter out residual WHERE clauses to prevent them from being optimized again\n  const nonResidualWhereClauses = query.where.filter(\n    (where) => !isResidualWhere(where)\n  )\n\n  // Step 1: Split all AND clauses at the root level for granular optimization\n  const splitWhereClauses = splitAndClauses(nonResidualWhereClauses)\n\n  // Step 2: Analyze each WHERE clause to determine which sources it touches\n  const analyzedClauses = splitWhereClauses.map((clause) =>\n    analyzeWhereClause(clause)\n  )\n\n  // Step 3: Group clauses by single-source vs multi-source\n  const groupedClauses = groupWhereClauses(analyzedClauses)\n\n  // Step 4: Apply optimizations by lifting single-source clauses into subqueries\n  const optimizedQuery = applyOptimizations(query, groupedClauses)\n\n  // Add back any residual WHERE clauses that were filtered out\n  const residualWhereClauses = query.where.filter((where) =>\n    isResidualWhere(where)\n  )\n  if (residualWhereClauses.length > 0) {\n    optimizedQuery.where = [\n      ...(optimizedQuery.where || []),\n      ...residualWhereClauses,\n    ]\n  }\n\n  return optimizedQuery\n}\n\n/**\n * Removes redundant subqueries that don't add value.\n * A subquery is redundant if it only wraps another query without adding\n * WHERE, SELECT, GROUP BY, HAVING, ORDER BY, or LIMIT/OFFSET clauses.\n *\n * @param query - The QueryIR to process\n * @returns A new QueryIR with redundant subqueries removed\n */\nfunction removeRedundantSubqueries(query: QueryIR): QueryIR {\n  return {\n    ...query,\n    from: removeRedundantFromClause(query.from),\n    join: query.join?.map((joinClause) => ({\n      ...joinClause,\n      from: removeRedundantFromClause(joinClause.from),\n    })),\n  }\n}\n\n/**\n * Removes redundant subqueries from a FROM clause.\n *\n * @param from - The FROM clause to process\n * @returns A FROM clause with redundant subqueries removed\n */\nfunction removeRedundantFromClause(from: From): From {\n  if (from.type === `collectionRef`) {\n    return from\n  }\n\n  const processedQuery = removeRedundantSubqueries(from.query)\n\n  // Check if this subquery is redundant\n  if (isRedundantSubquery(processedQuery)) {\n    // Return the inner query's FROM clause with this alias\n    const innerFrom = removeRedundantFromClause(processedQuery.from)\n    if (innerFrom.type === `collectionRef`) {\n      return new CollectionRefClass(innerFrom.collection, from.alias)\n    } else {\n      return new QueryRefClass(innerFrom.query, from.alias)\n    }\n  }\n\n  return new QueryRefClass(processedQuery, from.alias)\n}\n\n/**\n * Determines if a subquery is redundant (adds no value).\n *\n * @param query - The query to check\n * @returns True if the query is redundant and can be removed\n */\nfunction isRedundantSubquery(query: QueryIR): boolean {\n  return (\n    (!query.where || query.where.length === 0) &&\n    !query.select &&\n    (!query.groupBy || query.groupBy.length === 0) &&\n    (!query.having || query.having.length === 0) &&\n    (!query.orderBy || query.orderBy.length === 0) &&\n    (!query.join || query.join.length === 0) &&\n    query.limit === undefined &&\n    query.offset === undefined &&\n    !query.fnSelect &&\n    (!query.fnWhere || query.fnWhere.length === 0) &&\n    (!query.fnHaving || query.fnHaving.length === 0)\n  )\n}\n\n/**\n * Step 1: Split all AND clauses recursively into separate WHERE clauses.\n *\n * This enables more granular optimization by treating each condition independently.\n * OR clauses are preserved as they cannot be split without changing query semantics.\n *\n * @param whereClauses - Array of WHERE expressions to split\n * @returns Flattened array with AND clauses split into separate expressions\n *\n * @example\n * ```typescript\n * // Input: [and(eq(a, 1), gt(b, 2)), eq(c, 3)]\n * // Output: [eq(a, 1), gt(b, 2), eq(c, 3)]\n * ```\n */\nfunction splitAndClauses(\n  whereClauses: Array<Where>\n): Array<BasicExpression<boolean>> {\n  const result: Array<BasicExpression<boolean>> = []\n\n  for (const whereClause of whereClauses) {\n    const clause = getWhereExpression(whereClause)\n    result.push(...splitAndClausesRecursive(clause))\n  }\n\n  return result\n}\n\n// Helper function for recursive splitting of BasicExpression arrays\nfunction splitAndClausesRecursive(\n  clause: BasicExpression<boolean>\n): Array<BasicExpression<boolean>> {\n  if (clause.type === `func` && clause.name === `and`) {\n    // Recursively split nested AND clauses to handle complex expressions\n    const result: Array<BasicExpression<boolean>> = []\n    for (const arg of clause.args as Array<BasicExpression<boolean>>) {\n      result.push(...splitAndClausesRecursive(arg))\n    }\n    return result\n  } else {\n    // Preserve non-AND clauses as-is (including OR clauses)\n    return [clause]\n  }\n}\n\n/**\n * Step 2: Analyze which table sources a WHERE clause touches.\n *\n * This determines whether a clause can be pushed down to a specific table\n * or must remain in the main query (for multi-source clauses like join conditions).\n *\n * @param clause - The WHERE expression to analyze\n * @returns Analysis result with the expression and touched source aliases\n *\n * @example\n * ```typescript\n * // eq(users.department_id, 1) -> touches ['users']\n * // eq(users.id, posts.user_id) -> touches ['users', 'posts']\n * ```\n */\nfunction analyzeWhereClause(\n  clause: BasicExpression<boolean>\n): AnalyzedWhereClause {\n  const touchedSources = new Set<string>()\n\n  /**\n   * Recursively collect all table aliases referenced in an expression\n   */\n  function collectSources(expr: BasicExpression | any): void {\n    switch (expr.type) {\n      case `ref`:\n        // PropRef path has the table alias as the first element\n        if (expr.path && expr.path.length > 0) {\n          const firstElement = expr.path[0]\n          if (firstElement) {\n            touchedSources.add(firstElement)\n          }\n        }\n        break\n      case `func`:\n        // Recursively analyze function arguments (e.g., eq, gt, and, or)\n        if (expr.args) {\n          expr.args.forEach(collectSources)\n        }\n        break\n      case `val`:\n        // Values don't reference any sources\n        break\n      case `agg`:\n        // Aggregates can reference sources in their arguments\n        if (expr.args) {\n          expr.args.forEach(collectSources)\n        }\n        break\n    }\n  }\n\n  collectSources(clause)\n\n  return {\n    expression: clause,\n    touchedSources,\n  }\n}\n\n/**\n * Step 3: Group WHERE clauses by the sources they touch.\n *\n * Single-source clauses can be pushed down to subqueries for optimization.\n * Multi-source clauses must remain in the main query to preserve join semantics.\n *\n * @param analyzedClauses - Array of analyzed WHERE clauses\n * @returns Grouped clauses ready for optimization\n */\nfunction groupWhereClauses(\n  analyzedClauses: Array<AnalyzedWhereClause>\n): GroupedWhereClauses {\n  const singleSource = new Map<string, Array<BasicExpression<boolean>>>()\n  const multiSource: Array<BasicExpression<boolean>> = []\n\n  // Categorize each clause based on how many sources it touches\n  for (const clause of analyzedClauses) {\n    if (clause.touchedSources.size === 1) {\n      // Single source clause - can be optimized\n      const source = Array.from(clause.touchedSources)[0]!\n      if (!singleSource.has(source)) {\n        singleSource.set(source, [])\n      }\n      singleSource.get(source)!.push(clause.expression)\n    } else if (clause.touchedSources.size > 1) {\n      // Multi-source clause - must stay in main query\n      multiSource.push(clause.expression)\n    }\n    // Skip clauses that touch no sources (constants) - they don't need optimization\n  }\n\n  // Combine multiple clauses for each source with AND\n  const combinedSingleSource = new Map<string, BasicExpression<boolean>>()\n  for (const [source, clauses] of singleSource) {\n    combinedSingleSource.set(source, combineWithAnd(clauses))\n  }\n\n  // Combine multi-source clauses with AND\n  const combinedMultiSource =\n    multiSource.length > 0 ? combineWithAnd(multiSource) : undefined\n\n  return {\n    singleSource: combinedSingleSource,\n    multiSource: combinedMultiSource,\n  }\n}\n\n/**\n * Step 4: Apply optimizations by lifting single-source clauses into subqueries.\n *\n * Creates a new QueryIR with single-source WHERE clauses moved to subqueries\n * that wrap the original table references. This ensures immutability and prevents\n * infinite recursion issues.\n *\n * @param query - Original QueryIR to optimize\n * @param groupedClauses - WHERE clauses grouped by optimization strategy\n * @returns New QueryIR with optimizations applied\n */\nfunction applyOptimizations(\n  query: QueryIR,\n  groupedClauses: GroupedWhereClauses\n): QueryIR {\n  // Track which single-source clauses were actually optimized\n  const actuallyOptimized = new Set<string>()\n\n  // Optimize the main FROM clause and track what was optimized\n  const optimizedFrom = optimizeFromWithTracking(\n    query.from,\n    groupedClauses.singleSource,\n    actuallyOptimized\n  )\n\n  // Optimize JOIN clauses and track what was optimized\n  const optimizedJoins = query.join\n    ? query.join.map((joinClause) => ({\n        ...joinClause,\n        from: optimizeFromWithTracking(\n          joinClause.from,\n          groupedClauses.singleSource,\n          actuallyOptimized\n        ),\n      }))\n    : undefined\n\n  // Build the remaining WHERE clauses: multi-source + residual single-source clauses\n  const remainingWhereClauses: Array<Where> = []\n\n  // Add multi-source clauses\n  if (groupedClauses.multiSource) {\n    remainingWhereClauses.push(groupedClauses.multiSource)\n  }\n\n  // Determine if we need residual clauses (when query has outer JOINs)\n  const hasOuterJoins =\n    query.join &&\n    query.join.some(\n      (join) =>\n        join.type === `left` || join.type === `right` || join.type === `full`\n    )\n\n  // Add single-source clauses\n  for (const [source, clause] of groupedClauses.singleSource) {\n    if (!actuallyOptimized.has(source)) {\n      // Wasn't optimized at all - keep as regular WHERE clause\n      remainingWhereClauses.push(clause)\n    } else if (hasOuterJoins) {\n      // Was optimized AND query has outer JOINs - keep as residual WHERE clause\n      remainingWhereClauses.push(createResidualWhere(clause))\n    }\n    // If optimized and no outer JOINs - don't keep (original behavior)\n  }\n\n  // Create a completely new query object to ensure immutability\n  const optimizedQuery: QueryIR = {\n    // Copy all non-optimized fields as-is\n    select: query.select,\n    groupBy: query.groupBy ? [...query.groupBy] : undefined,\n    having: query.having ? [...query.having] : undefined,\n    orderBy: query.orderBy ? [...query.orderBy] : undefined,\n    limit: query.limit,\n    offset: query.offset,\n    distinct: query.distinct,\n    fnSelect: query.fnSelect,\n    fnWhere: query.fnWhere ? [...query.fnWhere] : undefined,\n    fnHaving: query.fnHaving ? [...query.fnHaving] : undefined,\n\n    // Use the optimized FROM and JOIN clauses\n    from: optimizedFrom,\n    join: optimizedJoins,\n\n    // Only include WHERE clauses that weren't successfully optimized\n    where: remainingWhereClauses.length > 0 ? remainingWhereClauses : [],\n  }\n\n  return optimizedQuery\n}\n\n/**\n * Helper function to create a deep copy of a QueryIR object for immutability.\n *\n * This ensures that all optimizations create new objects rather than modifying\n * existing ones, preventing infinite recursion and shared reference issues.\n *\n * @param query - QueryIR to deep copy\n * @returns New QueryIR object with all nested objects copied\n */\nfunction deepCopyQuery(query: QueryIR): QueryIR {\n  return {\n    // Recursively copy the FROM clause\n    from:\n      query.from.type === `collectionRef`\n        ? new CollectionRefClass(query.from.collection, query.from.alias)\n        : new QueryRefClass(deepCopyQuery(query.from.query), query.from.alias),\n\n    // Copy all other fields, creating new arrays where necessary\n    select: query.select,\n    join: query.join\n      ? query.join.map((joinClause) => ({\n          type: joinClause.type,\n          left: joinClause.left,\n          right: joinClause.right,\n          from:\n            joinClause.from.type === `collectionRef`\n              ? new CollectionRefClass(\n                  joinClause.from.collection,\n                  joinClause.from.alias\n                )\n              : new QueryRefClass(\n                  deepCopyQuery(joinClause.from.query),\n                  joinClause.from.alias\n                ),\n        }))\n      : undefined,\n    where: query.where ? [...query.where] : undefined,\n    groupBy: query.groupBy ? [...query.groupBy] : undefined,\n    having: query.having ? [...query.having] : undefined,\n    orderBy: query.orderBy ? [...query.orderBy] : undefined,\n    limit: query.limit,\n    offset: query.offset,\n    fnSelect: query.fnSelect,\n    fnWhere: query.fnWhere ? [...query.fnWhere] : undefined,\n    fnHaving: query.fnHaving ? [...query.fnHaving] : undefined,\n  }\n}\n\n/**\n * Helper function to optimize a FROM clause while tracking what was actually optimized.\n *\n * @param from - FROM clause to optimize\n * @param singleSourceClauses - Map of source aliases to their WHERE clauses\n * @param actuallyOptimized - Set to track which sources were actually optimized\n * @returns New FROM clause, potentially wrapped in a subquery\n */\nfunction optimizeFromWithTracking(\n  from: From,\n  singleSourceClauses: Map<string, BasicExpression<boolean>>,\n  actuallyOptimized: Set<string>\n): From {\n  const whereClause = singleSourceClauses.get(from.alias)\n\n  if (!whereClause) {\n    // No optimization needed, but return a copy to maintain immutability\n    if (from.type === `collectionRef`) {\n      return new CollectionRefClass(from.collection, from.alias)\n    }\n    // Must be queryRef due to type system\n    return new QueryRefClass(deepCopyQuery(from.query), from.alias)\n  }\n\n  if (from.type === `collectionRef`) {\n    // Create a new subquery with the WHERE clause for the collection\n    // This is always safe since we're creating a new subquery\n    const subQuery: QueryIR = {\n      from: new CollectionRefClass(from.collection, from.alias),\n      where: [whereClause],\n    }\n    actuallyOptimized.add(from.alias) // Mark as successfully optimized\n    return new QueryRefClass(subQuery, from.alias)\n  }\n\n  // Must be queryRef due to type system\n\n  // SAFETY CHECK: Only check safety when pushing WHERE clauses into existing subqueries\n  // We need to be careful about pushing WHERE clauses into subqueries that already have\n  // aggregates, HAVING, or ORDER BY + LIMIT since that could change their semantics\n  if (!isSafeToPushIntoExistingSubquery(from.query, whereClause, from.alias)) {\n    // Return a copy without optimization to maintain immutability\n    // Do NOT mark as optimized since we didn't actually optimize it\n    return new QueryRefClass(deepCopyQuery(from.query), from.alias)\n  }\n\n  // Add the WHERE clause to the existing subquery\n  // Create a deep copy to ensure immutability\n  const existingWhere = from.query.where || []\n  const optimizedSubQuery: QueryIR = {\n    ...deepCopyQuery(from.query),\n    where: [...existingWhere, whereClause],\n  }\n  actuallyOptimized.add(from.alias) // Mark as successfully optimized\n  return new QueryRefClass(optimizedSubQuery, from.alias)\n}\n\nfunction unsafeSelect(\n  query: QueryIR,\n  whereClause: BasicExpression<boolean>,\n  outerAlias: string\n): boolean {\n  if (!query.select) return false\n\n  return (\n    selectHasAggregates(query.select) ||\n    whereReferencesComputedSelectFields(query.select, whereClause, outerAlias)\n  )\n}\n\nfunction unsafeGroupBy(query: QueryIR) {\n  return query.groupBy && query.groupBy.length > 0\n}\n\nfunction unsafeHaving(query: QueryIR) {\n  return query.having && query.having.length > 0\n}\n\nfunction unsafeOrderBy(query: QueryIR) {\n  return (\n    query.orderBy &&\n    query.orderBy.length > 0 &&\n    (query.limit !== undefined || query.offset !== undefined)\n  )\n}\n\nfunction unsafeFnSelect(query: QueryIR) {\n  return (\n    query.fnSelect ||\n    (query.fnWhere && query.fnWhere.length > 0) ||\n    (query.fnHaving && query.fnHaving.length > 0)\n  )\n}\n\nfunction isSafeToPushIntoExistingSubquery(\n  query: QueryIR,\n  whereClause: BasicExpression<boolean>,\n  outerAlias: string\n): boolean {\n  return !(\n    unsafeSelect(query, whereClause, outerAlias) ||\n    unsafeGroupBy(query) ||\n    unsafeHaving(query) ||\n    unsafeOrderBy(query) ||\n    unsafeFnSelect(query)\n  )\n}\n\n/**\n * Detects whether a SELECT projection contains any aggregate expressions.\n * Recursively traverses nested select objects.\n *\n * @param select - The SELECT object from the IR\n * @returns True if any field is an aggregate, false otherwise\n */\nfunction selectHasAggregates(select: Select): boolean {\n  for (const value of Object.values(select)) {\n    if (typeof value === `object`) {\n      const v: any = value\n      if (v.type === `agg`) return true\n      if (!(`type` in v)) {\n        if (selectHasAggregates(v as unknown as Select)) return true\n      }\n    }\n  }\n  return false\n}\n\n/**\n * Recursively collects all PropRef references from an expression.\n *\n * @param expr - The expression to traverse\n * @returns Array of PropRef references found in the expression\n */\nfunction collectRefs(expr: any): Array<PropRef> {\n  const refs: Array<PropRef> = []\n\n  if (expr == null || typeof expr !== `object`) return refs\n\n  switch (expr.type) {\n    case `ref`:\n      refs.push(expr as PropRef)\n      break\n    case `func`:\n    case `agg`:\n      for (const arg of expr.args ?? []) {\n        refs.push(...collectRefs(arg))\n      }\n      break\n    default:\n      break\n  }\n\n  return refs\n}\n\n/**\n * Determines whether the provided WHERE clause references fields that are\n * computed by a subquery SELECT rather than pass-through properties.\n *\n * If true, pushing the WHERE clause into the subquery could change semantics\n * (since computed fields do not necessarily exist at the subquery input level),\n * so predicate pushdown must be avoided.\n *\n * @param select - The subquery SELECT map\n * @param whereClause - The WHERE expression to analyze\n * @param outerAlias - The alias of the subquery in the outer query\n * @returns True if WHERE references computed fields, otherwise false\n */\nfunction whereReferencesComputedSelectFields(\n  select: Select,\n  whereClause: BasicExpression<boolean>,\n  outerAlias: string\n): boolean {\n  // Build a set of computed field names at the top-level of the subquery output\n  const computed = new Set<string>()\n  for (const [key, value] of Object.entries(select)) {\n    if (key.startsWith(`__SPREAD_SENTINEL__`)) continue\n    if (value instanceof PropRef) continue\n    // Nested object or non-PropRef expression counts as computed\n    computed.add(key)\n  }\n\n  const refs = collectRefs(whereClause)\n\n  for (const ref of refs) {\n    const path = (ref as any).path as Array<string>\n    if (!Array.isArray(path) || path.length < 2) continue\n    const alias = path[0]\n    const field = path[1] as string\n    if (alias !== outerAlias) continue\n    if (computed.has(field)) return true\n  }\n  return false\n}\n\n/**\n * Helper function to combine multiple expressions with AND.\n *\n * If there's only one expression, it's returned as-is.\n * If there are multiple expressions, they're combined with an AND function.\n *\n * @param expressions - Array of expressions to combine\n * @returns Single expression representing the AND combination\n * @throws Error if the expressions array is empty\n */\nfunction combineWithAnd(\n  expressions: Array<BasicExpression<boolean>>\n): BasicExpression<boolean> {\n  if (expressions.length === 0) {\n    throw new CannotCombineEmptyExpressionListError()\n  }\n\n  if (expressions.length === 1) {\n    return expressions[0]!\n  }\n\n  // Create an AND function with all expressions as arguments\n  return new Func(`and`, expressions)\n}\n"],"names":["QueryRefClass","CollectionRefClass"],"mappings":"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"}
+{"version":3,"file":"optimizer.js","sources":["../../../src/query/optimizer.ts"],"sourcesContent":["/**\n * # Query Optimizer\n *\n * The query optimizer improves query performance by implementing predicate pushdown optimization.\n * It rewrites the intermediate representation (IR) to push WHERE clauses as close to the data\n * source as possible, reducing the amount of data processed during joins.\n *\n * ## How It Works\n *\n * The optimizer follows a 4-step process:\n *\n * ### 1. AND Clause Splitting\n * Splits AND clauses at the root level into separate WHERE clauses for granular optimization.\n * ```javascript\n * // Before: WHERE and(eq(users.department_id, 1), gt(users.age, 25))\n * // After:  WHERE eq(users.department_id, 1) + WHERE gt(users.age, 25)\n * ```\n *\n * ### 2. Source Analysis\n * Analyzes each WHERE clause to determine which table sources it references:\n * - Single-source clauses: Touch only one table (e.g., `users.department_id = 1`)\n * - Multi-source clauses: Touch multiple tables (e.g., `users.id = posts.user_id`)\n *\n * ### 3. Clause Grouping\n * Groups WHERE clauses by the sources they touch:\n * - Single-source clauses are grouped by their respective table\n * - Multi-source clauses are combined for the main query\n *\n * ### 4. Subquery Creation\n * Lifts single-source WHERE clauses into subqueries that wrap the original table references.\n *\n * ## Safety & Edge Cases\n *\n * The optimizer includes targeted safety checks to prevent predicate pushdown when it could\n * break query semantics:\n *\n * ### Always Safe Operations\n * - **Creating new subqueries**: Wrapping collection references in subqueries with WHERE clauses\n * - **Main query optimizations**: Moving single-source WHERE clauses from main query to subqueries\n * - **Queries with aggregates/ORDER BY/HAVING**: Can still create new filtered subqueries\n *\n * ### Unsafe Operations (blocked by safety checks)\n * Pushing WHERE clauses **into existing subqueries** that have:\n * - **Aggregates**: GROUP BY, HAVING, or aggregate functions in SELECT (would change aggregation)\n * - **Ordering + Limits**: ORDER BY combined with LIMIT/OFFSET (would change result set)\n * - **Functional Operations**: fnSelect, fnWhere, fnHaving (potential side effects)\n *\n * ### Residual WHERE Clauses\n * For outer joins (LEFT, RIGHT, FULL), WHERE clauses are copied to subqueries for optimization\n * but also kept as \"residual\" clauses in the main query to preserve semantics. This ensures\n * that NULL values from outer joins are properly filtered according to SQL standards.\n *\n * The optimizer tracks which clauses were actually optimized and only removes those from the\n * main query. Subquery reuse is handled safely through immutable query copies.\n *\n * ## Example Optimizations\n *\n * ### Basic Query with Joins\n * **Original Query:**\n * ```javascript\n * query\n *   .from({ users: usersCollection })\n *   .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.user_id))\n *   .where(({users}) => eq(users.department_id, 1))\n *   .where(({posts}) => gt(posts.views, 100))\n *   .where(({users, posts}) => eq(users.id, posts.author_id))\n * ```\n *\n * **Optimized Query:**\n * ```javascript\n * query\n *   .from({\n *     users: subquery\n *       .from({ users: usersCollection })\n *       .where(({users}) => eq(users.department_id, 1))\n *   })\n *   .join({\n *     posts: subquery\n *       .from({ posts: postsCollection })\n *       .where(({posts}) => gt(posts.views, 100))\n *   }, ({users, posts}) => eq(users.id, posts.user_id))\n *   .where(({users, posts}) => eq(users.id, posts.author_id))\n * ```\n *\n * ### Query with Aggregates (Now Optimizable!)\n * **Original Query:**\n * ```javascript\n * query\n *   .from({ users: usersCollection })\n *   .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.user_id))\n *   .where(({users}) => eq(users.department_id, 1))\n *   .groupBy(['users.department_id'])\n *   .select({ count: agg('count', '*') })\n * ```\n *\n * **Optimized Query:**\n * ```javascript\n * query\n *   .from({\n *     users: subquery\n *       .from({ users: usersCollection })\n *       .where(({users}) => eq(users.department_id, 1))\n *   })\n *   .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.user_id))\n *   .groupBy(['users.department_id'])\n *   .select({ count: agg('count', '*') })\n * ```\n *\n * ## Benefits\n *\n * - **Reduced Data Processing**: Filters applied before joins reduce intermediate result size\n * - **Better Performance**: Smaller datasets lead to faster query execution\n * - **Automatic Optimization**: No manual query rewriting required\n * - **Preserves Semantics**: Optimized queries return identical results\n * - **Safe by Design**: Comprehensive checks prevent semantic-breaking optimizations\n *\n * ## Integration\n *\n * The optimizer is automatically called during query compilation before the IR is\n * transformed into a D2Mini pipeline.\n */\n\nimport { deepEquals } from \"../utils.js\"\nimport { CannotCombineEmptyExpressionListError } from \"../errors.js\"\nimport {\n  CollectionRef as CollectionRefClass,\n  Func,\n  PropRef,\n  QueryRef as QueryRefClass,\n  createResidualWhere,\n  getWhereExpression,\n  isResidualWhere,\n} from \"./ir.js\"\nimport { isConvertibleToCollectionFilter } from \"./compiler/expressions.js\"\nimport type { BasicExpression, From, QueryIR, Select, Where } from \"./ir.js\"\n\n/**\n * Represents a WHERE clause after source analysis\n */\nexport interface AnalyzedWhereClause {\n  /** The WHERE expression */\n  expression: BasicExpression<boolean>\n  /** Set of table/source aliases that this WHERE clause touches */\n  touchedSources: Set<string>\n  /** Whether this clause contains namespace-only references that prevent pushdown */\n  hasNamespaceOnlyRef: boolean\n}\n\n/**\n * Represents WHERE clauses grouped by the sources they touch\n */\nexport interface GroupedWhereClauses {\n  /** WHERE clauses that touch only a single source, grouped by source alias */\n  singleSource: Map<string, BasicExpression<boolean>>\n  /** WHERE clauses that touch multiple sources, combined into one expression */\n  multiSource?: BasicExpression<boolean>\n}\n\n/**\n * Result of query optimization including both the optimized query and collection-specific WHERE clauses\n */\nexport interface OptimizationResult {\n  /** The optimized query with WHERE clauses potentially moved to subqueries */\n  optimizedQuery: QueryIR\n  /** Map of collection aliases to their extracted WHERE clauses for index optimization */\n  collectionWhereClauses: Map<string, BasicExpression<boolean>>\n}\n\n/**\n * Main query optimizer entry point that lifts WHERE clauses into subqueries.\n *\n * This function implements multi-level predicate pushdown optimization by recursively\n * moving WHERE clauses through nested subqueries to get them as close to the data\n * sources as possible, then removing redundant subqueries.\n *\n * @param query - The QueryIR to optimize\n * @returns An OptimizationResult with the optimized query and collection WHERE clause mapping\n *\n * @example\n * ```typescript\n * const originalQuery = {\n *   from: new CollectionRef(users, 'u'),\n *   join: [{ from: new CollectionRef(posts, 'p'), ... }],\n *   where: [eq(u.dept_id, 1), gt(p.views, 100)]\n * }\n *\n * const { optimizedQuery, collectionWhereClauses } = optimizeQuery(originalQuery)\n * // Result: Single-source clauses moved to deepest possible subqueries\n * // collectionWhereClauses: Map { 'u' => eq(u.dept_id, 1), 'p' => gt(p.views, 100) }\n * ```\n */\nexport function optimizeQuery(query: QueryIR): OptimizationResult {\n  // First, extract collection WHERE clauses before optimization\n  const collectionWhereClauses = extractCollectionWhereClauses(query)\n\n  // Apply multi-level predicate pushdown with iterative convergence\n  let optimized = query\n  let previousOptimized: QueryIR | undefined\n  let iterations = 0\n  const maxIterations = 10 // Prevent infinite loops\n\n  // Keep optimizing until no more changes occur or max iterations reached\n  while (\n    iterations < maxIterations &&\n    !deepEquals(optimized, previousOptimized)\n  ) {\n    previousOptimized = optimized\n    optimized = applyRecursiveOptimization(optimized)\n    iterations++\n  }\n\n  // Remove redundant subqueries\n  const cleaned = removeRedundantSubqueries(optimized)\n\n  return {\n    optimizedQuery: cleaned,\n    collectionWhereClauses,\n  }\n}\n\n/**\n * Extracts collection-specific WHERE clauses from a query for index optimization.\n * This analyzes the original query to identify WHERE clauses that can be pushed down\n * to specific collections, but only for simple queries without joins.\n *\n * @param query - The original QueryIR to analyze\n * @returns Map of collection aliases to their WHERE clauses\n */\nfunction extractCollectionWhereClauses(\n  query: QueryIR\n): Map<string, BasicExpression<boolean>> {\n  const collectionWhereClauses = new Map<string, BasicExpression<boolean>>()\n\n  // Only analyze queries that have WHERE clauses\n  if (!query.where || query.where.length === 0) {\n    return collectionWhereClauses\n  }\n\n  // Split all AND clauses at the root level for granular analysis\n  const splitWhereClauses = splitAndClauses(query.where)\n\n  // Analyze each WHERE clause to determine which sources it touches\n  const analyzedClauses = splitWhereClauses.map((clause) =>\n    analyzeWhereClause(clause)\n  )\n\n  // Group clauses by single-source vs multi-source\n  const groupedClauses = groupWhereClauses(analyzedClauses)\n\n  // Only include single-source clauses that reference collections directly\n  // and can be converted to BasicExpression format for collection indexes\n  for (const [sourceAlias, whereClause] of groupedClauses.singleSource) {\n    // Check if this source alias corresponds to a collection reference\n    if (isCollectionReference(query, sourceAlias)) {\n      // Check if the WHERE clause can be converted to collection-compatible format\n      if (isConvertibleToCollectionFilter(whereClause)) {\n        collectionWhereClauses.set(sourceAlias, whereClause)\n      }\n    }\n  }\n\n  return collectionWhereClauses\n}\n\n/**\n * Determines if a source alias refers to a collection reference (not a subquery).\n * This is used to identify WHERE clauses that can be pushed down to collection subscriptions.\n *\n * @param query - The query to analyze\n * @param sourceAlias - The source alias to check\n * @returns True if the alias refers to a collection reference\n */\nfunction isCollectionReference(query: QueryIR, sourceAlias: string): boolean {\n  // Check the FROM clause\n  if (query.from.alias === sourceAlias) {\n    return query.from.type === `collectionRef`\n  }\n\n  // Check JOIN clauses\n  if (query.join) {\n    for (const joinClause of query.join) {\n      if (joinClause.from.alias === sourceAlias) {\n        return joinClause.from.type === `collectionRef`\n      }\n    }\n  }\n\n  return false\n}\n\n/**\n * Applies recursive predicate pushdown optimization.\n *\n * @param query - The QueryIR to optimize\n * @returns A new QueryIR with optimizations applied\n */\nfunction applyRecursiveOptimization(query: QueryIR): QueryIR {\n  // First, recursively optimize any existing subqueries\n  const subqueriesOptimized = {\n    ...query,\n    from:\n      query.from.type === `queryRef`\n        ? new QueryRefClass(\n            applyRecursiveOptimization(query.from.query),\n            query.from.alias\n          )\n        : query.from,\n    join: query.join?.map((joinClause) => ({\n      ...joinClause,\n      from:\n        joinClause.from.type === `queryRef`\n          ? new QueryRefClass(\n              applyRecursiveOptimization(joinClause.from.query),\n              joinClause.from.alias\n            )\n          : joinClause.from,\n    })),\n  }\n\n  // Then apply single-level optimization to this query\n  return applySingleLevelOptimization(subqueriesOptimized)\n}\n\n/**\n * Applies single-level predicate pushdown optimization (existing logic)\n */\nfunction applySingleLevelOptimization(query: QueryIR): QueryIR {\n  // Skip optimization if no WHERE clauses exist\n  if (!query.where || query.where.length === 0) {\n    return query\n  }\n\n  // Skip optimization if there are no joins - predicate pushdown only benefits joins\n  // Single-table queries don't benefit from this optimization\n  if (!query.join || query.join.length === 0) {\n    return query\n  }\n\n  // Filter out residual WHERE clauses to prevent them from being optimized again\n  const nonResidualWhereClauses = query.where.filter(\n    (where) => !isResidualWhere(where)\n  )\n\n  // Step 1: Split all AND clauses at the root level for granular optimization\n  const splitWhereClauses = splitAndClauses(nonResidualWhereClauses)\n\n  // Step 2: Analyze each WHERE clause to determine which sources it touches\n  const analyzedClauses = splitWhereClauses.map((clause) =>\n    analyzeWhereClause(clause)\n  )\n\n  // Step 3: Group clauses by single-source vs multi-source\n  const groupedClauses = groupWhereClauses(analyzedClauses)\n\n  // Step 4: Apply optimizations by lifting single-source clauses into subqueries\n  const optimizedQuery = applyOptimizations(query, groupedClauses)\n\n  // Add back any residual WHERE clauses that were filtered out\n  const residualWhereClauses = query.where.filter((where) =>\n    isResidualWhere(where)\n  )\n  if (residualWhereClauses.length > 0) {\n    optimizedQuery.where = [\n      ...(optimizedQuery.where || []),\n      ...residualWhereClauses,\n    ]\n  }\n\n  return optimizedQuery\n}\n\n/**\n * Removes redundant subqueries that don't add value.\n * A subquery is redundant if it only wraps another query without adding\n * WHERE, SELECT, GROUP BY, HAVING, ORDER BY, or LIMIT/OFFSET clauses.\n *\n * @param query - The QueryIR to process\n * @returns A new QueryIR with redundant subqueries removed\n */\nfunction removeRedundantSubqueries(query: QueryIR): QueryIR {\n  return {\n    ...query,\n    from: removeRedundantFromClause(query.from),\n    join: query.join?.map((joinClause) => ({\n      ...joinClause,\n      from: removeRedundantFromClause(joinClause.from),\n    })),\n  }\n}\n\n/**\n * Removes redundant subqueries from a FROM clause.\n *\n * @param from - The FROM clause to process\n * @returns A FROM clause with redundant subqueries removed\n */\nfunction removeRedundantFromClause(from: From): From {\n  if (from.type === `collectionRef`) {\n    return from\n  }\n\n  const processedQuery = removeRedundantSubqueries(from.query)\n\n  // Check if this subquery is redundant\n  if (isRedundantSubquery(processedQuery)) {\n    // Return the inner query's FROM clause with this alias\n    const innerFrom = removeRedundantFromClause(processedQuery.from)\n    if (innerFrom.type === `collectionRef`) {\n      return new CollectionRefClass(innerFrom.collection, from.alias)\n    } else {\n      return new QueryRefClass(innerFrom.query, from.alias)\n    }\n  }\n\n  return new QueryRefClass(processedQuery, from.alias)\n}\n\n/**\n * Determines if a subquery is redundant (adds no value).\n *\n * @param query - The query to check\n * @returns True if the query is redundant and can be removed\n */\nfunction isRedundantSubquery(query: QueryIR): boolean {\n  return (\n    (!query.where || query.where.length === 0) &&\n    !query.select &&\n    (!query.groupBy || query.groupBy.length === 0) &&\n    (!query.having || query.having.length === 0) &&\n    (!query.orderBy || query.orderBy.length === 0) &&\n    (!query.join || query.join.length === 0) &&\n    query.limit === undefined &&\n    query.offset === undefined &&\n    !query.fnSelect &&\n    (!query.fnWhere || query.fnWhere.length === 0) &&\n    (!query.fnHaving || query.fnHaving.length === 0)\n  )\n}\n\n/**\n * Step 1: Split all AND clauses recursively into separate WHERE clauses.\n *\n * This enables more granular optimization by treating each condition independently.\n * OR clauses are preserved as they cannot be split without changing query semantics.\n *\n * @param whereClauses - Array of WHERE expressions to split\n * @returns Flattened array with AND clauses split into separate expressions\n *\n * @example\n * ```typescript\n * // Input: [and(eq(a, 1), gt(b, 2)), eq(c, 3)]\n * // Output: [eq(a, 1), gt(b, 2), eq(c, 3)]\n * ```\n */\nfunction splitAndClauses(\n  whereClauses: Array<Where>\n): Array<BasicExpression<boolean>> {\n  const result: Array<BasicExpression<boolean>> = []\n\n  for (const whereClause of whereClauses) {\n    const clause = getWhereExpression(whereClause)\n    result.push(...splitAndClausesRecursive(clause))\n  }\n\n  return result\n}\n\n// Helper function for recursive splitting of BasicExpression arrays\nfunction splitAndClausesRecursive(\n  clause: BasicExpression<boolean>\n): Array<BasicExpression<boolean>> {\n  if (clause.type === `func` && clause.name === `and`) {\n    // Recursively split nested AND clauses to handle complex expressions\n    const result: Array<BasicExpression<boolean>> = []\n    for (const arg of clause.args as Array<BasicExpression<boolean>>) {\n      result.push(...splitAndClausesRecursive(arg))\n    }\n    return result\n  } else {\n    // Preserve non-AND clauses as-is (including OR clauses)\n    return [clause]\n  }\n}\n\n/**\n * Step 2: Analyze which table sources a WHERE clause touches.\n *\n * This determines whether a clause can be pushed down to a specific table\n * or must remain in the main query (for multi-source clauses like join conditions).\n *\n * Special handling for namespace-only references in outer joins:\n * WHERE clauses that reference only a table namespace (e.g., isUndefined(special), eq(special, value))\n * rather than specific properties (e.g., isUndefined(special.id), eq(special.id, value)) are treated as\n * multi-source to prevent incorrect predicate pushdown that would change join semantics.\n *\n * @param clause - The WHERE expression to analyze\n * @returns Analysis result with the expression and touched source aliases\n *\n * @example\n * ```typescript\n * // eq(users.department_id, 1) -> touches ['users'], hasNamespaceOnlyRef: false\n * // eq(users.id, posts.user_id) -> touches ['users', 'posts'], hasNamespaceOnlyRef: false\n * // isUndefined(special) -> touches ['special'], hasNamespaceOnlyRef: true (prevents pushdown)\n * // eq(special, someValue) -> touches ['special'], hasNamespaceOnlyRef: true (prevents pushdown)\n * // isUndefined(special.id) -> touches ['special'], hasNamespaceOnlyRef: false (allows pushdown)\n * // eq(special.id, 5) -> touches ['special'], hasNamespaceOnlyRef: false (allows pushdown)\n * ```\n */\nfunction analyzeWhereClause(\n  clause: BasicExpression<boolean>\n): AnalyzedWhereClause {\n  // Track which table aliases this WHERE clause touches\n  const touchedSources = new Set<string>()\n  // Track whether this clause contains namespace-only references that prevent pushdown\n  let hasNamespaceOnlyRef = false\n\n  /**\n   * Recursively collect all table aliases referenced in an expression\n   */\n  function collectSources(expr: BasicExpression | any): void {\n    switch (expr.type) {\n      case `ref`:\n        // PropRef path has the table alias as the first element\n        if (expr.path && expr.path.length > 0) {\n          const firstElement = expr.path[0]\n          if (firstElement) {\n            touchedSources.add(firstElement)\n\n            // If the path has only one element (just the namespace),\n            // this is a namespace-only reference that should not be pushed down\n            // This applies to ANY function, not just existence-checking functions\n            if (expr.path.length === 1) {\n              hasNamespaceOnlyRef = true\n            }\n          }\n        }\n        break\n      case `func`:\n        // Recursively analyze function arguments (e.g., eq, gt, and, or)\n        if (expr.args) {\n          expr.args.forEach(collectSources)\n        }\n        break\n      case `val`:\n        // Values don't reference any sources\n        break\n      case `agg`:\n        // Aggregates can reference sources in their arguments\n        if (expr.args) {\n          expr.args.forEach(collectSources)\n        }\n        break\n    }\n  }\n\n  collectSources(clause)\n\n  return {\n    expression: clause,\n    touchedSources,\n    hasNamespaceOnlyRef,\n  }\n}\n\n/**\n * Step 3: Group WHERE clauses by the sources they touch.\n *\n * Single-source clauses can be pushed down to subqueries for optimization.\n * Multi-source clauses must remain in the main query to preserve join semantics.\n *\n * @param analyzedClauses - Array of analyzed WHERE clauses\n * @returns Grouped clauses ready for optimization\n */\nfunction groupWhereClauses(\n  analyzedClauses: Array<AnalyzedWhereClause>\n): GroupedWhereClauses {\n  const singleSource = new Map<string, Array<BasicExpression<boolean>>>()\n  const multiSource: Array<BasicExpression<boolean>> = []\n\n  // Categorize each clause based on how many sources it touches\n  for (const clause of analyzedClauses) {\n    if (clause.touchedSources.size === 1 && !clause.hasNamespaceOnlyRef) {\n      // Single source clause without namespace-only references - can be optimized\n      const source = Array.from(clause.touchedSources)[0]!\n      if (!singleSource.has(source)) {\n        singleSource.set(source, [])\n      }\n      singleSource.get(source)!.push(clause.expression)\n    } else if (clause.touchedSources.size > 1 || clause.hasNamespaceOnlyRef) {\n      // Multi-source clause or namespace-only reference - must stay in main query\n      multiSource.push(clause.expression)\n    }\n    // Skip clauses that touch no sources (constants) - they don't need optimization\n  }\n\n  // Combine multiple clauses for each source with AND\n  const combinedSingleSource = new Map<string, BasicExpression<boolean>>()\n  for (const [source, clauses] of singleSource) {\n    combinedSingleSource.set(source, combineWithAnd(clauses))\n  }\n\n  // Combine multi-source clauses with AND\n  const combinedMultiSource =\n    multiSource.length > 0 ? combineWithAnd(multiSource) : undefined\n\n  return {\n    singleSource: combinedSingleSource,\n    multiSource: combinedMultiSource,\n  }\n}\n\n/**\n * Step 4: Apply optimizations by lifting single-source clauses into subqueries.\n *\n * Creates a new QueryIR with single-source WHERE clauses moved to subqueries\n * that wrap the original table references. This ensures immutability and prevents\n * infinite recursion issues.\n *\n * @param query - Original QueryIR to optimize\n * @param groupedClauses - WHERE clauses grouped by optimization strategy\n * @returns New QueryIR with optimizations applied\n */\nfunction applyOptimizations(\n  query: QueryIR,\n  groupedClauses: GroupedWhereClauses\n): QueryIR {\n  // Track which single-source clauses were actually optimized\n  const actuallyOptimized = new Set<string>()\n\n  // Optimize the main FROM clause and track what was optimized\n  const optimizedFrom = optimizeFromWithTracking(\n    query.from,\n    groupedClauses.singleSource,\n    actuallyOptimized\n  )\n\n  // Optimize JOIN clauses and track what was optimized\n  const optimizedJoins = query.join\n    ? query.join.map((joinClause) => ({\n        ...joinClause,\n        from: optimizeFromWithTracking(\n          joinClause.from,\n          groupedClauses.singleSource,\n          actuallyOptimized\n        ),\n      }))\n    : undefined\n\n  // Build the remaining WHERE clauses: multi-source + residual single-source clauses\n  const remainingWhereClauses: Array<Where> = []\n\n  // Add multi-source clauses\n  if (groupedClauses.multiSource) {\n    remainingWhereClauses.push(groupedClauses.multiSource)\n  }\n\n  // Determine if we need residual clauses (when query has outer JOINs)\n  const hasOuterJoins =\n    query.join &&\n    query.join.some(\n      (join) =>\n        join.type === `left` || join.type === `right` || join.type === `full`\n    )\n\n  // Add single-source clauses\n  for (const [source, clause] of groupedClauses.singleSource) {\n    if (!actuallyOptimized.has(source)) {\n      // Wasn't optimized at all - keep as regular WHERE clause\n      remainingWhereClauses.push(clause)\n    } else if (hasOuterJoins) {\n      // Was optimized AND query has outer JOINs - keep as residual WHERE clause\n      remainingWhereClauses.push(createResidualWhere(clause))\n    }\n    // If optimized and no outer JOINs - don't keep (original behavior)\n  }\n\n  // Create a completely new query object to ensure immutability\n  const optimizedQuery: QueryIR = {\n    // Copy all non-optimized fields as-is\n    select: query.select,\n    groupBy: query.groupBy ? [...query.groupBy] : undefined,\n    having: query.having ? [...query.having] : undefined,\n    orderBy: query.orderBy ? [...query.orderBy] : undefined,\n    limit: query.limit,\n    offset: query.offset,\n    distinct: query.distinct,\n    fnSelect: query.fnSelect,\n    fnWhere: query.fnWhere ? [...query.fnWhere] : undefined,\n    fnHaving: query.fnHaving ? [...query.fnHaving] : undefined,\n\n    // Use the optimized FROM and JOIN clauses\n    from: optimizedFrom,\n    join: optimizedJoins,\n\n    // Only include WHERE clauses that weren't successfully optimized\n    where: remainingWhereClauses.length > 0 ? remainingWhereClauses : [],\n  }\n\n  return optimizedQuery\n}\n\n/**\n * Helper function to create a deep copy of a QueryIR object for immutability.\n *\n * This ensures that all optimizations create new objects rather than modifying\n * existing ones, preventing infinite recursion and shared reference issues.\n *\n * @param query - QueryIR to deep copy\n * @returns New QueryIR object with all nested objects copied\n */\nfunction deepCopyQuery(query: QueryIR): QueryIR {\n  return {\n    // Recursively copy the FROM clause\n    from:\n      query.from.type === `collectionRef`\n        ? new CollectionRefClass(query.from.collection, query.from.alias)\n        : new QueryRefClass(deepCopyQuery(query.from.query), query.from.alias),\n\n    // Copy all other fields, creating new arrays where necessary\n    select: query.select,\n    join: query.join\n      ? query.join.map((joinClause) => ({\n          type: joinClause.type,\n          left: joinClause.left,\n          right: joinClause.right,\n          from:\n            joinClause.from.type === `collectionRef`\n              ? new CollectionRefClass(\n                  joinClause.from.collection,\n                  joinClause.from.alias\n                )\n              : new QueryRefClass(\n                  deepCopyQuery(joinClause.from.query),\n                  joinClause.from.alias\n                ),\n        }))\n      : undefined,\n    where: query.where ? [...query.where] : undefined,\n    groupBy: query.groupBy ? [...query.groupBy] : undefined,\n    having: query.having ? [...query.having] : undefined,\n    orderBy: query.orderBy ? [...query.orderBy] : undefined,\n    limit: query.limit,\n    offset: query.offset,\n    fnSelect: query.fnSelect,\n    fnWhere: query.fnWhere ? [...query.fnWhere] : undefined,\n    fnHaving: query.fnHaving ? [...query.fnHaving] : undefined,\n  }\n}\n\n/**\n * Helper function to optimize a FROM clause while tracking what was actually optimized.\n *\n * @param from - FROM clause to optimize\n * @param singleSourceClauses - Map of source aliases to their WHERE clauses\n * @param actuallyOptimized - Set to track which sources were actually optimized\n * @returns New FROM clause, potentially wrapped in a subquery\n */\nfunction optimizeFromWithTracking(\n  from: From,\n  singleSourceClauses: Map<string, BasicExpression<boolean>>,\n  actuallyOptimized: Set<string>\n): From {\n  const whereClause = singleSourceClauses.get(from.alias)\n\n  if (!whereClause) {\n    // No optimization needed, but return a copy to maintain immutability\n    if (from.type === `collectionRef`) {\n      return new CollectionRefClass(from.collection, from.alias)\n    }\n    // Must be queryRef due to type system\n    return new QueryRefClass(deepCopyQuery(from.query), from.alias)\n  }\n\n  if (from.type === `collectionRef`) {\n    // Create a new subquery with the WHERE clause for the collection\n    // This is always safe since we're creating a new subquery\n    const subQuery: QueryIR = {\n      from: new CollectionRefClass(from.collection, from.alias),\n      where: [whereClause],\n    }\n    actuallyOptimized.add(from.alias) // Mark as successfully optimized\n    return new QueryRefClass(subQuery, from.alias)\n  }\n\n  // Must be queryRef due to type system\n\n  // SAFETY CHECK: Only check safety when pushing WHERE clauses into existing subqueries\n  // We need to be careful about pushing WHERE clauses into subqueries that already have\n  // aggregates, HAVING, or ORDER BY + LIMIT since that could change their semantics\n  if (!isSafeToPushIntoExistingSubquery(from.query, whereClause, from.alias)) {\n    // Return a copy without optimization to maintain immutability\n    // Do NOT mark as optimized since we didn't actually optimize it\n    return new QueryRefClass(deepCopyQuery(from.query), from.alias)\n  }\n\n  // Add the WHERE clause to the existing subquery\n  // Create a deep copy to ensure immutability\n  const existingWhere = from.query.where || []\n  const optimizedSubQuery: QueryIR = {\n    ...deepCopyQuery(from.query),\n    where: [...existingWhere, whereClause],\n  }\n  actuallyOptimized.add(from.alias) // Mark as successfully optimized\n  return new QueryRefClass(optimizedSubQuery, from.alias)\n}\n\nfunction unsafeSelect(\n  query: QueryIR,\n  whereClause: BasicExpression<boolean>,\n  outerAlias: string\n): boolean {\n  if (!query.select) return false\n\n  return (\n    selectHasAggregates(query.select) ||\n    whereReferencesComputedSelectFields(query.select, whereClause, outerAlias)\n  )\n}\n\nfunction unsafeGroupBy(query: QueryIR) {\n  return query.groupBy && query.groupBy.length > 0\n}\n\nfunction unsafeHaving(query: QueryIR) {\n  return query.having && query.having.length > 0\n}\n\nfunction unsafeOrderBy(query: QueryIR) {\n  return (\n    query.orderBy &&\n    query.orderBy.length > 0 &&\n    (query.limit !== undefined || query.offset !== undefined)\n  )\n}\n\nfunction unsafeFnSelect(query: QueryIR) {\n  return (\n    query.fnSelect ||\n    (query.fnWhere && query.fnWhere.length > 0) ||\n    (query.fnHaving && query.fnHaving.length > 0)\n  )\n}\n\nfunction isSafeToPushIntoExistingSubquery(\n  query: QueryIR,\n  whereClause: BasicExpression<boolean>,\n  outerAlias: string\n): boolean {\n  return !(\n    unsafeSelect(query, whereClause, outerAlias) ||\n    unsafeGroupBy(query) ||\n    unsafeHaving(query) ||\n    unsafeOrderBy(query) ||\n    unsafeFnSelect(query)\n  )\n}\n\n/**\n * Detects whether a SELECT projection contains any aggregate expressions.\n * Recursively traverses nested select objects.\n *\n * @param select - The SELECT object from the IR\n * @returns True if any field is an aggregate, false otherwise\n */\nfunction selectHasAggregates(select: Select): boolean {\n  for (const value of Object.values(select)) {\n    if (typeof value === `object`) {\n      const v: any = value\n      if (v.type === `agg`) return true\n      if (!(`type` in v)) {\n        if (selectHasAggregates(v as unknown as Select)) return true\n      }\n    }\n  }\n  return false\n}\n\n/**\n * Recursively collects all PropRef references from an expression.\n *\n * @param expr - The expression to traverse\n * @returns Array of PropRef references found in the expression\n */\nfunction collectRefs(expr: any): Array<PropRef> {\n  const refs: Array<PropRef> = []\n\n  if (expr == null || typeof expr !== `object`) return refs\n\n  switch (expr.type) {\n    case `ref`:\n      refs.push(expr as PropRef)\n      break\n    case `func`:\n    case `agg`:\n      for (const arg of expr.args ?? []) {\n        refs.push(...collectRefs(arg))\n      }\n      break\n    default:\n      break\n  }\n\n  return refs\n}\n\n/**\n * Determines whether the provided WHERE clause references fields that are\n * computed by a subquery SELECT rather than pass-through properties.\n *\n * If true, pushing the WHERE clause into the subquery could change semantics\n * (since computed fields do not necessarily exist at the subquery input level),\n * so predicate pushdown must be avoided.\n *\n * @param select - The subquery SELECT map\n * @param whereClause - The WHERE expression to analyze\n * @param outerAlias - The alias of the subquery in the outer query\n * @returns True if WHERE references computed fields, otherwise false\n */\nfunction whereReferencesComputedSelectFields(\n  select: Select,\n  whereClause: BasicExpression<boolean>,\n  outerAlias: string\n): boolean {\n  // Build a set of computed field names at the top-level of the subquery output\n  const computed = new Set<string>()\n  for (const [key, value] of Object.entries(select)) {\n    if (key.startsWith(`__SPREAD_SENTINEL__`)) continue\n    if (value instanceof PropRef) continue\n    // Nested object or non-PropRef expression counts as computed\n    computed.add(key)\n  }\n\n  const refs = collectRefs(whereClause)\n\n  for (const ref of refs) {\n    const path = (ref as any).path as Array<string>\n    if (!Array.isArray(path) || path.length < 2) continue\n    const alias = path[0]\n    const field = path[1] as string\n    if (alias !== outerAlias) continue\n    if (computed.has(field)) return true\n  }\n  return false\n}\n\n/**\n * Helper function to combine multiple expressions with AND.\n *\n * If there's only one expression, it's returned as-is.\n * If there are multiple expressions, they're combined with an AND function.\n *\n * @param expressions - Array of expressions to combine\n * @returns Single expression representing the AND combination\n * @throws Error if the expressions array is empty\n */\nfunction combineWithAnd(\n  expressions: Array<BasicExpression<boolean>>\n): BasicExpression<boolean> {\n  if (expressions.length === 0) {\n    throw new CannotCombineEmptyExpressionListError()\n  }\n\n  if (expressions.length === 1) {\n    return expressions[0]!\n  }\n\n  // Create an AND function with all expressions as arguments\n  return new Func(`and`, expressions)\n}\n"],"names":["QueryRefClass","CollectionRefClass"],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -213,8 +213,14 @@ export interface BaseCollectionConfig<T extends object = Record<string, unknown>
      */
     gcTime?: number;
     /**
-     * Whether to start syncing immediately when the collection is created.
-     * Defaults to false for lazy loading. Set to true to immediately sync.
+     * Whether to eagerly start syncing on collection creation.
+     * When true, syncing begins immediately. When false, syncing starts when the first subscriber attaches.
+     *
+     * Note: Even with startSync=true, collections will pause syncing when there are no active
+     * subscribers (typically when components querying the collection unmount), resuming when new
+     * subscribers attach. This preserves normal staleTime/gcTime behavior.
+     *
+     * @default false
      */
     startSync?: boolean;
     /**

package/dist/esm/utils/comparison.d.ts

@@ -13,3 +13,7 @@ export declare const descComparator: (a: unknown, b: unknown, opts: CompareOptio
 export declare function makeComparator(opts: CompareOptions): (a: any, b: any) => number;
 /** Default comparator orders values in ascending order with nulls first and locale string comparison. */
 export declare const defaultComparator: (a: any, b: any) => number;
+/**
+ * Normalize a value for comparison
+ */
+export declare function normalizeValue(value: any): any;

package/dist/esm/utils/comparison.js

@@ -65,10 +65,17 @@ const defaultComparator = makeComparator({
   nulls: `first`,
   stringSort: `locale`
 });
+function normalizeValue(value) {
+  if (value instanceof Date) {
+    return value.getTime();
+  }
+  return value;
+}
 export {
   ascComparator,
   defaultComparator,
   descComparator,
-  makeComparator
+  makeComparator,
+  normalizeValue
 };
 //# sourceMappingURL=comparison.js.map

package/dist/esm/utils/comparison.js.map

@@ -1 +1 @@
-{"version":3,"file":"comparison.js","sources":["../../../src/utils/comparison.ts"],"sourcesContent":["import type { CompareOptions } from \"../query/builder/types\"\n\n// WeakMap to store stable IDs for objects\nconst objectIds = new WeakMap<object, number>()\nlet nextObjectId = 1\n\n/**\n * Get or create a stable ID for an object\n */\nfunction getObjectId(obj: object): number {\n  if (objectIds.has(obj)) {\n    return objectIds.get(obj)!\n  }\n  const id = nextObjectId++\n  objectIds.set(obj, id)\n  return id\n}\n\n/**\n * Universal comparison function for all data types\n * Handles null/undefined, strings, arrays, dates, objects, and primitives\n * Always sorts null/undefined values first\n */\nexport const ascComparator = (a: any, b: any, opts: CompareOptions): number => {\n  const { nulls } = opts\n\n  // Handle null/undefined\n  if (a == null && b == null) return 0\n  if (a == null) return nulls === `first` ? -1 : 1\n  if (b == null) return nulls === `first` ? 1 : -1\n\n  // if a and b are both strings, compare them based on locale\n  if (typeof a === `string` && typeof b === `string`) {\n    if (opts.stringSort === `locale`) {\n      return a.localeCompare(b, opts.locale, opts.localeOptions)\n    }\n    // For lexical sort we rely on direct comparison for primitive values\n  }\n\n  // if a and b are both arrays, compare them element by element\n  if (Array.isArray(a) && Array.isArray(b)) {\n    for (let i = 0; i < Math.min(a.length, b.length); i++) {\n      const result = ascComparator(a[i], b[i], opts)\n      if (result !== 0) {\n        return result\n      }\n    }\n    // All elements are equal up to the minimum length\n    return a.length - b.length\n  }\n\n  // If both are dates, compare them\n  if (a instanceof Date && b instanceof Date) {\n    return a.getTime() - b.getTime()\n  }\n\n  // If at least one of the values is an object, use stable IDs for comparison\n  const aIsObject = typeof a === `object`\n  const bIsObject = typeof b === `object`\n\n  if (aIsObject || bIsObject) {\n    // If both are objects, compare their stable IDs\n    if (aIsObject && bIsObject) {\n      const aId = getObjectId(a)\n      const bId = getObjectId(b)\n      return aId - bId\n    }\n\n    // If only one is an object, objects come after primitives\n    if (aIsObject) return 1\n    if (bIsObject) return -1\n  }\n\n  // For primitive values, use direct comparison\n  if (a < b) return -1\n  if (a > b) return 1\n  return 0\n}\n\n/**\n * Descending comparator function for ordering values\n * Handles null/undefined as largest values (opposite of ascending)\n */\nexport const descComparator = (\n  a: unknown,\n  b: unknown,\n  opts: CompareOptions\n): number => {\n  return ascComparator(b, a, {\n    ...opts,\n    nulls: opts.nulls === `first` ? `last` : `first`,\n  })\n}\n\nexport function makeComparator(\n  opts: CompareOptions\n): (a: any, b: any) => number {\n  return (a, b) => {\n    if (opts.direction === `asc`) {\n      return ascComparator(a, b, opts)\n    } else {\n      return descComparator(a, b, opts)\n    }\n  }\n}\n\n/** Default comparator orders values in ascending order with nulls first and locale string comparison. */\nexport const defaultComparator = makeComparator({\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n})\n"],"names":[],"mappings":"AAGA,MAAM,gCAAgB,QAAA;AACtB,IAAI,eAAe;AAKnB,SAAS,YAAY,KAAqB;AACxC,MAAI,UAAU,IAAI,GAAG,GAAG;AACtB,WAAO,UAAU,IAAI,GAAG;AAAA,EAC1B;AACA,QAAM,KAAK;AACX,YAAU,IAAI,KAAK,EAAE;AACrB,SAAO;AACT;AAOO,MAAM,gBAAgB,CAAC,GAAQ,GAAQ,SAAiC;AAC7E,QAAM,EAAE,UAAU;AAGlB,MAAI,KAAK,QAAQ,KAAK,KAAM,QAAO;AACnC,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,KAAK;AAC/C,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,IAAI;AAG9C,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAClD,QAAI,KAAK,eAAe,UAAU;AAChC,aAAO,EAAE,cAAc,GAAG,KAAK,QAAQ,KAAK,aAAa;AAAA,IAC3D;AAAA,EAEF;AAGA,MAAI,MAAM,QAAQ,CAAC,KAAK,MAAM,QAAQ,CAAC,GAAG;AACxC,aAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK;AACrD,YAAM,SAAS,cAAc,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;AAC7C,UAAI,WAAW,GAAG;AAChB,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO,EAAE,SAAS,EAAE;AAAA,EACtB;AAGA,MAAI,aAAa,QAAQ,aAAa,MAAM;AAC1C,WAAO,EAAE,YAAY,EAAE,QAAA;AAAA,EACzB;AAGA,QAAM,YAAY,OAAO,MAAM;AAC/B,QAAM,YAAY,OAAO,MAAM;AAE/B,MAAI,aAAa,WAAW;AAE1B,QAAI,aAAa,WAAW;AAC1B,YAAM,MAAM,YAAY,CAAC;AACzB,YAAM,MAAM,YAAY,CAAC;AACzB,aAAO,MAAM;AAAA,IACf;AAGA,QAAI,UAAW,QAAO;AACtB,QAAI,UAAW,QAAO;AAAA,EACxB;AAGA,MAAI,IAAI,EAAG,QAAO;AAClB,MAAI,IAAI,EAAG,QAAO;AAClB,SAAO;AACT;AAMO,MAAM,iBAAiB,CAC5B,GACA,GACA,SACW;AACX,SAAO,cAAc,GAAG,GAAG;AAAA,IACzB,GAAG;AAAA,IACH,OAAO,KAAK,UAAU,UAAU,SAAS;AAAA,EAAA,CAC1C;AACH;AAEO,SAAS,eACd,MAC4B;AAC5B,SAAO,CAAC,GAAG,MAAM;AACf,QAAI,KAAK,cAAc,OAAO;AAC5B,aAAO,cAAc,GAAG,GAAG,IAAI;AAAA,IACjC,OAAO;AACL,aAAO,eAAe,GAAG,GAAG,IAAI;AAAA,IAClC;AAAA,EACF;AACF;AAGO,MAAM,oBAAoB,eAAe;AAAA,EAC9C,WAAW;AAAA,EACX,OAAO;AAAA,EACP,YAAY;AACd,CAAC;"}
+{"version":3,"file":"comparison.js","sources":["../../../src/utils/comparison.ts"],"sourcesContent":["import type { CompareOptions } from \"../query/builder/types\"\n\n// WeakMap to store stable IDs for objects\nconst objectIds = new WeakMap<object, number>()\nlet nextObjectId = 1\n\n/**\n * Get or create a stable ID for an object\n */\nfunction getObjectId(obj: object): number {\n  if (objectIds.has(obj)) {\n    return objectIds.get(obj)!\n  }\n  const id = nextObjectId++\n  objectIds.set(obj, id)\n  return id\n}\n\n/**\n * Universal comparison function for all data types\n * Handles null/undefined, strings, arrays, dates, objects, and primitives\n * Always sorts null/undefined values first\n */\nexport const ascComparator = (a: any, b: any, opts: CompareOptions): number => {\n  const { nulls } = opts\n\n  // Handle null/undefined\n  if (a == null && b == null) return 0\n  if (a == null) return nulls === `first` ? -1 : 1\n  if (b == null) return nulls === `first` ? 1 : -1\n\n  // if a and b are both strings, compare them based on locale\n  if (typeof a === `string` && typeof b === `string`) {\n    if (opts.stringSort === `locale`) {\n      return a.localeCompare(b, opts.locale, opts.localeOptions)\n    }\n    // For lexical sort we rely on direct comparison for primitive values\n  }\n\n  // if a and b are both arrays, compare them element by element\n  if (Array.isArray(a) && Array.isArray(b)) {\n    for (let i = 0; i < Math.min(a.length, b.length); i++) {\n      const result = ascComparator(a[i], b[i], opts)\n      if (result !== 0) {\n        return result\n      }\n    }\n    // All elements are equal up to the minimum length\n    return a.length - b.length\n  }\n\n  // If both are dates, compare them\n  if (a instanceof Date && b instanceof Date) {\n    return a.getTime() - b.getTime()\n  }\n\n  // If at least one of the values is an object, use stable IDs for comparison\n  const aIsObject = typeof a === `object`\n  const bIsObject = typeof b === `object`\n\n  if (aIsObject || bIsObject) {\n    // If both are objects, compare their stable IDs\n    if (aIsObject && bIsObject) {\n      const aId = getObjectId(a)\n      const bId = getObjectId(b)\n      return aId - bId\n    }\n\n    // If only one is an object, objects come after primitives\n    if (aIsObject) return 1\n    if (bIsObject) return -1\n  }\n\n  // For primitive values, use direct comparison\n  if (a < b) return -1\n  if (a > b) return 1\n  return 0\n}\n\n/**\n * Descending comparator function for ordering values\n * Handles null/undefined as largest values (opposite of ascending)\n */\nexport const descComparator = (\n  a: unknown,\n  b: unknown,\n  opts: CompareOptions\n): number => {\n  return ascComparator(b, a, {\n    ...opts,\n    nulls: opts.nulls === `first` ? `last` : `first`,\n  })\n}\n\nexport function makeComparator(\n  opts: CompareOptions\n): (a: any, b: any) => number {\n  return (a, b) => {\n    if (opts.direction === `asc`) {\n      return ascComparator(a, b, opts)\n    } else {\n      return descComparator(a, b, opts)\n    }\n  }\n}\n\n/** Default comparator orders values in ascending order with nulls first and locale string comparison. */\nexport const defaultComparator = makeComparator({\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n})\n\n/**\n * Normalize a value for comparison\n */\nexport function normalizeValue(value: any): any {\n  if (value instanceof Date) {\n    return value.getTime()\n  }\n  return value\n}\n"],"names":[],"mappings":"AAGA,MAAM,gCAAgB,QAAA;AACtB,IAAI,eAAe;AAKnB,SAAS,YAAY,KAAqB;AACxC,MAAI,UAAU,IAAI,GAAG,GAAG;AACtB,WAAO,UAAU,IAAI,GAAG;AAAA,EAC1B;AACA,QAAM,KAAK;AACX,YAAU,IAAI,KAAK,EAAE;AACrB,SAAO;AACT;AAOO,MAAM,gBAAgB,CAAC,GAAQ,GAAQ,SAAiC;AAC7E,QAAM,EAAE,UAAU;AAGlB,MAAI,KAAK,QAAQ,KAAK,KAAM,QAAO;AACnC,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,KAAK;AAC/C,MAAI,KAAK,KAAM,QAAO,UAAU,UAAU,IAAI;AAG9C,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAClD,QAAI,KAAK,eAAe,UAAU;AAChC,aAAO,EAAE,cAAc,GAAG,KAAK,QAAQ,KAAK,aAAa;AAAA,IAC3D;AAAA,EAEF;AAGA,MAAI,MAAM,QAAQ,CAAC,KAAK,MAAM,QAAQ,CAAC,GAAG;AACxC,aAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK;AACrD,YAAM,SAAS,cAAc,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;AAC7C,UAAI,WAAW,GAAG;AAChB,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO,EAAE,SAAS,EAAE;AAAA,EACtB;AAGA,MAAI,aAAa,QAAQ,aAAa,MAAM;AAC1C,WAAO,EAAE,YAAY,EAAE,QAAA;AAAA,EACzB;AAGA,QAAM,YAAY,OAAO,MAAM;AAC/B,QAAM,YAAY,OAAO,MAAM;AAE/B,MAAI,aAAa,WAAW;AAE1B,QAAI,aAAa,WAAW;AAC1B,YAAM,MAAM,YAAY,CAAC;AACzB,YAAM,MAAM,YAAY,CAAC;AACzB,aAAO,MAAM;AAAA,IACf;AAGA,QAAI,UAAW,QAAO;AACtB,QAAI,UAAW,QAAO;AAAA,EACxB;AAGA,MAAI,IAAI,EAAG,QAAO;AAClB,MAAI,IAAI,EAAG,QAAO;AAClB,SAAO;AACT;AAMO,MAAM,iBAAiB,CAC5B,GACA,GACA,SACW;AACX,SAAO,cAAc,GAAG,GAAG;AAAA,IACzB,GAAG;AAAA,IACH,OAAO,KAAK,UAAU,UAAU,SAAS;AAAA,EAAA,CAC1C;AACH;AAEO,SAAS,eACd,MAC4B;AAC5B,SAAO,CAAC,GAAG,MAAM;AACf,QAAI,KAAK,cAAc,OAAO;AAC5B,aAAO,cAAc,GAAG,GAAG,IAAI;AAAA,IACjC,OAAO;AACL,aAAO,eAAe,GAAG,GAAG,IAAI;AAAA,IAClC;AAAA,EACF;AACF;AAGO,MAAM,oBAAoB,eAAe;AAAA,EAC9C,WAAW;AAAA,EACX,OAAO;AAAA,EACP,YAAY;AACd,CAAC;AAKM,SAAS,eAAe,OAAiB;AAC9C,MAAI,iBAAiB,MAAM;AACzB,WAAO,MAAM,QAAA;AAAA,EACf;AACA,SAAO;AACT;"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@tanstack/db-ivm": "0.1.8"
+    "@tanstack/db-ivm": "0.1.9"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^3.2.4",

package/src/collection/events.ts

@@ -70,7 +70,7 @@ export class CollectionEventsManager {
     this.listeners.get(event)!.add(callback)
 
     return () => {
-      this.listeners.get(event)!.delete(callback)
+      this.listeners.get(event)?.delete(callback)
     }
   }
 

package/src/collection/lifecycle.ts

@@ -1,5 +1,6 @@
 import {
   CollectionInErrorStateError,
+  CollectionStateError,
   InvalidCollectionStatusTransitionError,
 } from "../errors"
 import {
@@ -90,7 +91,18 @@ export class CollectionLifecycleManager<
    * Safely update the collection status with validation
    * @private
    */
-  public setStatus(newStatus: CollectionStatus): void {
+  public setStatus(
+    newStatus: CollectionStatus,
+    allowReady: boolean = false
+  ): void {
+    if (newStatus === `ready` && !allowReady) {
+      // setStatus('ready') is an internal method that should not be called directly
+      // Instead, use markReady to transition to ready triggering the necessary events
+      // and side effects.
+      throw new CollectionStateError(
+        `You can't directly call "setStatus('ready'). You must use markReady instead.`
+      )
+    }
     this.validateStatusTransition(this.status, newStatus)
     const previousStatus = this.status
     this.status = newStatus
@@ -129,9 +141,10 @@ export class CollectionLifecycleManager<
    * @private - Should only be called by sync implementations
    */
   public markReady(): void {
+    this.validateStatusTransition(this.status, `ready`)
     // Can transition to ready from loading or initialCommit states
     if (this.status === `loading` || this.status === `initialCommit`) {
-      this.setStatus(`ready`)
+      this.setStatus(`ready`, true)
 
       // Call any registered first ready callbacks (only on first time becoming ready)
       if (!this.hasBeenReady) {
@@ -146,12 +159,11 @@ export class CollectionLifecycleManager<
         this.onFirstReadyCallbacks = []
         callbacks.forEach((callback) => callback())
       }
-    }
-
-    // Always notify dependents when markReady is called, after status is set
-    // This ensures live queries get notified when their dependencies become ready
-    if (this.changes.changeSubscriptions.size > 0) {
-      this.changes.emitEmptyReadyEvent()
+      // Notify dependents when markReady is called, after status is set
+      // This ensures live queries get notified when their dependencies become ready
+      if (this.changes.changeSubscriptions.size > 0) {
+        this.changes.emitEmptyReadyEvent()
+      }
     }
   }
 

package/src/collection/state.ts

@@ -644,7 +644,7 @@ export class CollectionStateManager<
 
         // Ensure listeners are active before emitting this critical batch
         if (this.lifecycle.status !== `ready`) {
-          this.lifecycle.setStatus(`ready`)
+          this.lifecycle.markReady()
         }
       }
 

package/src/collection/subscription.ts

@@ -1,5 +1,5 @@
 import { ensureIndexForExpression } from "../indexes/auto-index.js"
-import { and } from "../query/index.js"
+import { and } from "../query/builder/functions.js"
 import {
   createFilterFunctionFromExpression,
   createFilteredCallback,

package/src/indexes/btree-index.ts

@@ -1,5 +1,5 @@
 import { BTree } from "../utils/btree.js"
-import { defaultComparator } from "../utils/comparison.js"
+import { defaultComparator, normalizeValue } from "../utils/comparison.js"
 import { BaseIndex } from "./base-index.js"
 import type { BasicExpression } from "../query/ir.js"
 import type { IndexOperation } from "./base-index.js"
@@ -71,15 +71,18 @@ export class BTreeIndex<
       )
     }
 
+    // Normalize the value for Map key usage
+    const normalizedValue = normalizeValue(indexedValue)
+
     // Check if this value already exists
-    if (this.valueMap.has(indexedValue)) {
+    if (this.valueMap.has(normalizedValue)) {
       // Add to existing set
-      this.valueMap.get(indexedValue)!.add(key)
+      this.valueMap.get(normalizedValue)!.add(key)
     } else {
       // Create new set for this value
       const keySet = new Set<TKey>([key])
-      this.valueMap.set(indexedValue, keySet)
-      this.orderedEntries.set(indexedValue, undefined)
+      this.valueMap.set(normalizedValue, keySet)
+      this.orderedEntries.set(normalizedValue, undefined)
     }
 
     this.indexedKeys.add(key)
@@ -101,16 +104,19 @@ export class BTreeIndex<
       return
     }
 
-    if (this.valueMap.has(indexedValue)) {
-      const keySet = this.valueMap.get(indexedValue)!
+    // Normalize the value for Map key usage
+    const normalizedValue = normalizeValue(indexedValue)
+
+    if (this.valueMap.has(normalizedValue)) {
+      const keySet = this.valueMap.get(normalizedValue)!
       keySet.delete(key)
 
       // If set is now empty, remove the entry entirely
       if (keySet.size === 0) {
-        this.valueMap.delete(indexedValue)
+        this.valueMap.delete(normalizedValue)
 
         // Remove from ordered entries
-        this.orderedEntries.delete(indexedValue)
+        this.orderedEntries.delete(normalizedValue)
       }
     }
 
@@ -195,7 +201,8 @@ export class BTreeIndex<
    * Performs an equality lookup
    */
   equalityLookup(value: any): Set<TKey> {
-    return new Set(this.valueMap.get(value) ?? [])
+    const normalizedValue = normalizeValue(value)
+    return new Set(this.valueMap.get(normalizedValue) ?? [])
   }
 
   /**
@@ -206,8 +213,10 @@ export class BTreeIndex<
     const { from, to, fromInclusive = true, toInclusive = true } = options
     const result = new Set<TKey>()
 
-    const fromKey = from ?? this.orderedEntries.minKey()
-    const toKey = to ?? this.orderedEntries.maxKey()
+    const normalizedFrom = normalizeValue(from)
+    const normalizedTo = normalizeValue(to)
+    const fromKey = normalizedFrom ?? this.orderedEntries.minKey()
+    const toKey = normalizedTo ?? this.orderedEntries.maxKey()
 
     this.orderedEntries.forRange(
       fromKey,
@@ -240,7 +249,7 @@ export class BTreeIndex<
     const keysInResult: Set<TKey> = new Set()
     const result: Array<TKey> = []
     const nextKey = (k?: any) => this.orderedEntries.nextHigherKey(k)
-    let key = from
+    let key = normalizeValue(from)
 
     while ((key = nextKey(key)) && result.length < n) {
       const keys = this.valueMap.get(key)
@@ -266,7 +275,8 @@ export class BTreeIndex<
     const result = new Set<TKey>()
 
     for (const value of values) {
-      const keys = this.valueMap.get(value)
+      const normalizedValue = normalizeValue(value)
+      const keys = this.valueMap.get(normalizedValue)
       if (keys) {
         keys.forEach((key) => result.add(key))
       }

package/src/query/builder/functions.ts

@@ -53,10 +53,10 @@ type ExtractType<T> =
 // Helper type to determine aggregate return type based on input nullability
 type AggregateReturnType<T> =
   ExtractType<T> extends infer U
-    ? U extends number | undefined | null
+    ? U extends number | undefined | null | Date | bigint
       ? Aggregate<U>
-      : Aggregate<number | undefined | null>
-    : Aggregate<number | undefined | null>
+      : Aggregate<number | undefined | null | Date | bigint>
+    : Aggregate<number | undefined | null | Date | bigint>
 
 // Helper type to determine string function return type based on input nullability
 type StringFunctionReturnType<T> =

package/src/query/compiler/evaluators.ts

@@ -3,6 +3,7 @@ import {
   UnknownExpressionTypeError,
   UnknownFunctionError,
 } from "../../errors.js"
+import { normalizeValue } from "../../utils/comparison.js"
 import type { BasicExpression, Func, PropRef } from "../ir.js"
 import type { NamespacedRow } from "../../types.js"
 
@@ -142,8 +143,8 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
       return (data) => {
-        const a = argA(data)
-        const b = argB(data)
+        const a = normalizeValue(argA(data))
+        const b = normalizeValue(argB(data))
         return a === b
       }
     }

package/src/query/compiler/group-by.ts

@@ -349,6 +349,19 @@ function getAggregateFunction(aggExpr: Aggregate) {
     return typeof value === `number` ? value : value != null ? Number(value) : 0
   }
 
+  // Create a value extractor function for the expression to aggregate
+  const valueExtractorWithDate = ([, namespacedRow]: [
+    string,
+    NamespacedRow,
+  ]) => {
+    const value = compiledExpr(namespacedRow)
+    return typeof value === `number` || value instanceof Date
+      ? value
+      : value != null
+        ? Number(value)
+        : 0
+  }
+
   // Create a raw value extractor function for the expression to aggregate
   const rawValueExtractor = ([, namespacedRow]: [string, NamespacedRow]) => {
     return compiledExpr(namespacedRow)
@@ -363,9 +376,9 @@ function getAggregateFunction(aggExpr: Aggregate) {
     case `avg`:
       return avg(valueExtractor)
     case `min`:
-      return min(valueExtractor)
+      return min(valueExtractorWithDate)
     case `max`:
-      return max(valueExtractor)
+      return max(valueExtractorWithDate)
     default:
       throw new UnsupportedAggregateFunctionError(aggExpr.name)
   }

package/src/query/compiler/index.ts

@@ -127,7 +127,8 @@ export function compileQuery(
       callbacks,
       lazyCollections,
       optimizableOrderByCollections,
-      rawQuery
+      rawQuery,
+      compileQuery
     )
   }
 
@@ -512,3 +513,5 @@ export function followRef(
     }
   }
 }
+
+export type CompileQueryFn = typeof compileQuery