@tanstack/db 0.0.26 → 0.0.29

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 * 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 {\n  CollectionRef as CollectionRefClass,\n  Func,\n  QueryRef as QueryRefClass,\n} from \"./ir.js\"\nimport type { BasicExpression, From, QueryIR } 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 * 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 A new QueryIR with optimizations applied (or original if no optimization possible)\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 optimized = optimizeQuery(originalQuery)\n * // Result: Single-source clauses moved to deepest possible subqueries\n * ```\n */\nexport function optimizeQuery(query: QueryIR): QueryIR {\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 cleaned\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  // Step 1: Split all AND clauses at the root level for granular optimization\n  const splitWhereClauses = splitAndClauses(query.where)\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  return applyOptimizations(query, groupedClauses)\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<BasicExpression<boolean>>\n): Array<BasicExpression<boolean>> {\n  const result: Array<BasicExpression<boolean>> = []\n\n  for (const clause of whereClauses) {\n    if (clause.type === `func` && clause.name === `and`) {\n      // Recursively split nested AND clauses to handle complex expressions\n      const splitArgs = splitAndClauses(\n        clause.args as Array<BasicExpression<boolean>>\n      )\n      result.push(...splitArgs)\n    } else {\n      // Preserve non-AND clauses as-is (including OR clauses)\n      result.push(clause)\n    }\n  }\n\n  return result\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 + any single-source that weren't optimized\n  const remainingWhereClauses: Array<BasicExpression<boolean>> = []\n\n  // Add multi-source clauses\n  if (groupedClauses.multiSource) {\n    remainingWhereClauses.push(groupedClauses.multiSource)\n  }\n\n  // Add single-source clauses that weren't actually optimized\n  for (const [source, clause] of groupedClauses.singleSource) {\n    if (!actuallyOptimized.has(source)) {\n      remainingWhereClauses.push(clause)\n    }\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    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)) {\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\n/**\n * Determines if it's safe to push WHERE clauses into an existing subquery.\n *\n * Pushing WHERE clauses into existing subqueries can break semantics in several cases:\n *\n * 1. **Aggregates**: Pushing predicates before GROUP BY changes what gets aggregated\n * 2. **ORDER BY + LIMIT/OFFSET**: Pushing predicates before sorting+limiting changes the result set\n * 3. **HAVING clauses**: These operate on aggregated data, predicates should not be pushed past them\n * 4. **Functional operations**: fnSelect, fnWhere, fnHaving could have side effects\n *\n * Note: This safety check only applies when pushing WHERE clauses into existing subqueries.\n * Creating new subqueries from collection references is always safe.\n *\n * @param query - The existing subquery to check for safety\n * @returns True if it's safe to push WHERE clauses into this subquery, false otherwise\n *\n * @example\n * ```typescript\n * // UNSAFE: has GROUP BY - pushing WHERE could change aggregation\n * { from: users, groupBy: [dept], select: { count: agg('count', '*') } }\n *\n * // UNSAFE: has ORDER BY + LIMIT - pushing WHERE could change \"top 10\"\n * { from: users, orderBy: [salary desc], limit: 10 }\n *\n * // SAFE: plain SELECT without aggregates/limits\n * { from: users, select: { id, name } }\n * ```\n */\nfunction isSafeToPushIntoExistingSubquery(query: QueryIR): boolean {\n  // Check for aggregates in SELECT clause\n  if (query.select) {\n    const hasAggregates = Object.values(query.select).some(\n      (expr) => expr.type === `agg`\n    )\n    if (hasAggregates) {\n      return false\n    }\n  }\n\n  // Check for GROUP BY clause\n  if (query.groupBy && query.groupBy.length > 0) {\n    return false\n  }\n\n  // Check for HAVING clause\n  if (query.having && query.having.length > 0) {\n    return false\n  }\n\n  // Check for ORDER BY with LIMIT or OFFSET (dangerous combination)\n  if (query.orderBy && query.orderBy.length > 0) {\n    if (query.limit !== undefined || query.offset !== undefined) {\n      return false\n    }\n  }\n\n  // Check for functional variants that might have side effects\n  if (\n    query.fnSelect ||\n    (query.fnWhere && query.fnWhere.length > 0) ||\n    (query.fnHaving && query.fnHaving.length > 0)\n  ) {\n    return false\n  }\n\n  // If none of the unsafe conditions are present, it's safe to optimize\n  return true\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 Error(`Cannot combine empty expression list`)\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 * 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  QueryRef as QueryRefClass,\n} from \"./ir.js\"\nimport { isConvertibleToCollectionFilter } from \"./compiler/expressions.js\"\nimport type { BasicExpression, From, QueryIR } 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  // Step 1: Split all AND clauses at the root level for granular optimization\n  const splitWhereClauses = splitAndClauses(query.where)\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  return applyOptimizations(query, groupedClauses)\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<BasicExpression<boolean>>\n): Array<BasicExpression<boolean>> {\n  const result: Array<BasicExpression<boolean>> = []\n\n  for (const clause of whereClauses) {\n    if (clause.type === `func` && clause.name === `and`) {\n      // Recursively split nested AND clauses to handle complex expressions\n      const splitArgs = splitAndClauses(\n        clause.args as Array<BasicExpression<boolean>>\n      )\n      result.push(...splitArgs)\n    } else {\n      // Preserve non-AND clauses as-is (including OR clauses)\n      result.push(clause)\n    }\n  }\n\n  return result\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 + any single-source that weren't optimized\n  const remainingWhereClauses: Array<BasicExpression<boolean>> = []\n\n  // Add multi-source clauses\n  if (groupedClauses.multiSource) {\n    remainingWhereClauses.push(groupedClauses.multiSource)\n  }\n\n  // Add single-source clauses that weren't actually optimized\n  for (const [source, clause] of groupedClauses.singleSource) {\n    if (!actuallyOptimized.has(source)) {\n      remainingWhereClauses.push(clause)\n    }\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    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)) {\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\n/**\n * Determines if it's safe to push WHERE clauses into an existing subquery.\n *\n * Pushing WHERE clauses into existing subqueries can break semantics in several cases:\n *\n * 1. **Aggregates**: Pushing predicates before GROUP BY changes what gets aggregated\n * 2. **ORDER BY + LIMIT/OFFSET**: Pushing predicates before sorting+limiting changes the result set\n * 3. **HAVING clauses**: These operate on aggregated data, predicates should not be pushed past them\n * 4. **Functional operations**: fnSelect, fnWhere, fnHaving could have side effects\n *\n * Note: This safety check only applies when pushing WHERE clauses into existing subqueries.\n * Creating new subqueries from collection references is always safe.\n *\n * @param query - The existing subquery to check for safety\n * @returns True if it's safe to push WHERE clauses into this subquery, false otherwise\n *\n * @example\n * ```typescript\n * // UNSAFE: has GROUP BY - pushing WHERE could change aggregation\n * { from: users, groupBy: [dept], select: { count: agg('count', '*') } }\n *\n * // UNSAFE: has ORDER BY + LIMIT - pushing WHERE could change \"top 10\"\n * { from: users, orderBy: [salary desc], limit: 10 }\n *\n * // SAFE: plain SELECT without aggregates/limits\n * { from: users, select: { id, name } }\n * ```\n */\nfunction isSafeToPushIntoExistingSubquery(query: QueryIR): boolean {\n  // Check for aggregates in SELECT clause\n  if (query.select) {\n    const hasAggregates = Object.values(query.select).some(\n      (expr) => expr.type === `agg`\n    )\n    if (hasAggregates) {\n      return false\n    }\n  }\n\n  // Check for GROUP BY clause\n  if (query.groupBy && query.groupBy.length > 0) {\n    return false\n  }\n\n  // Check for HAVING clause\n  if (query.having && query.having.length > 0) {\n    return false\n  }\n\n  // Check for ORDER BY with LIMIT or OFFSET (dangerous combination)\n  if (query.orderBy && query.orderBy.length > 0) {\n    if (query.limit !== undefined || query.offset !== undefined) {\n      return false\n    }\n  }\n\n  // Check for functional variants that might have side effects\n  if (\n    query.fnSelect ||\n    (query.fnWhere && query.fnWhere.length > 0) ||\n    (query.fnHaving && query.fnHaving.length > 0)\n  ) {\n    return false\n  }\n\n  // If none of the unsafe conditions are present, it's safe to optimize\n  return true\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/transactions.js

@@ -1,4 +1,5 @@
 import { createDeferred } from "./deferred.js";
+import { MissingMutationFunctionError, TransactionNotPendingMutateError, TransactionAlreadyCompletedRollbackError, TransactionNotPendingCommitError } from "./errors.js";
 const transactions = [];
 let transactionStack = [];
 let sequenceNumber = 0;
@@ -29,7 +30,7 @@ function removeFromPendingList(tx) {
 class Transaction {
   constructor(config) {
     if (typeof config.mutationFn === `undefined`) {
-      throw `mutationFn is required when creating a transaction`;
+      throw new MissingMutationFunctionError();
     }
     this.id = config.id ?? crypto.randomUUID();
     this.mutationFn = config.mutationFn;
@@ -88,7 +89,7 @@ class Transaction {
    */
   mutate(callback) {
     if (this.state !== `pending`) {
-      throw `You can no longer call .mutate() as the transaction is no longer pending`;
+      throw new TransactionNotPendingMutateError();
     }
     registerTransaction(this);
     try {
@@ -155,7 +156,7 @@ class Transaction {
     var _a;
     const isSecondaryRollback = (config == null ? void 0 : config.isSecondaryRollback) ?? false;
     if (this.state === `completed`) {
-      throw `You can no longer call .rollback() as the transaction is already completed`;
+      throw new TransactionAlreadyCompletedRollbackError();
     }
     this.setState(`failed`);
     if (!isSecondaryRollback) {
@@ -223,7 +224,7 @@ class Transaction {
    */
   async commit() {
     if (this.state !== `pending`) {
-      throw `You can no longer call .commit() as the transaction is no longer pending`;
+      throw new TransactionNotPendingCommitError();
     }
     this.setState(`persisting`);
     if (this.mutations.length === 0) {

package/dist/esm/transactions.js.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.js","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n  TransactionWithMutations,\n} from \"./types\"\n\nconst transactions: Array<Transaction<any>> = []\nlet transactionStack: Array<Transaction<any>> = []\n\nlet sequenceNumber = 0\n\n/**\n * Creates a new transaction for grouping multiple collection operations\n * @param config - Transaction configuration with mutation function\n * @returns A new Transaction instance\n * @example\n * // Basic transaction usage\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Send all mutations to API\n *     await api.saveChanges(transaction.mutations)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n *   collection.update(\"2\", draft => { draft.completed = true })\n * })\n *\n * await tx.isPersisted.promise\n *\n * @example\n * // Handle transaction errors\n * try {\n *   const tx = createTransaction({\n *     mutationFn: async () => { throw new Error(\"API failed\") }\n *   })\n *\n *   tx.mutate(() => {\n *     collection.insert({ id: \"1\", text: \"New item\" })\n *   })\n *\n *   await tx.isPersisted.promise\n * } catch (error) {\n *   console.log('Transaction failed:', error)\n * }\n *\n * @example\n * // Manual commit control\n * const tx = createTransaction({\n *   autoCommit: false,\n *   mutationFn: async () => {\n *     // API call\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Item\" })\n * })\n *\n * // Commit later\n * await tx.commit()\n */\nexport function createTransaction<T extends object = Record<string, unknown>>(\n  config: TransactionConfig<T>\n): Transaction<T> {\n  const newTransaction = new Transaction<T>(config)\n  transactions.push(newTransaction)\n  return newTransaction\n}\n\n/**\n * Gets the currently active ambient transaction, if any\n * Used internally by collection operations to join existing transactions\n * @returns The active transaction or undefined if none is active\n * @example\n * // Check if operations will join an ambient transaction\n * const ambientTx = getActiveTransaction()\n * if (ambientTx) {\n *   console.log('Operations will join transaction:', ambientTx.id)\n * }\n */\nexport function getActiveTransaction(): Transaction | undefined {\n  if (transactionStack.length > 0) {\n    return transactionStack.slice(-1)[0]\n  } else {\n    return undefined\n  }\n}\n\nfunction registerTransaction(tx: Transaction<any>) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction<any>) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nclass Transaction<T extends object = Record<string, unknown>> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T>>\n  public isPersisted: Deferred<Transaction<T>>\n  public autoCommit: boolean\n  public createdAt: Date\n  public sequenceNumber: number\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig<T>) {\n    if (typeof config.mutationFn === `undefined`) {\n      throw `mutationFn is required when creating a transaction`\n    }\n    this.id = config.id ?? crypto.randomUUID()\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred<Transaction<T>>()\n    this.autoCommit = config.autoCommit ?? true\n    this.createdAt = new Date()\n    this.sequenceNumber = sequenceNumber++\n    this.metadata = config.metadata ?? {}\n  }\n\n  setState(newState: TransactionState) {\n    this.state = newState\n\n    if (newState === `completed` || newState === `failed`) {\n      removeFromPendingList(this)\n    }\n  }\n\n  /**\n   * Execute collection operations within this transaction\n   * @param callback - Function containing collection operations to group together\n   * @returns This transaction for chaining\n   * @example\n   * // Group multiple operations\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   *   collection.update(\"2\", draft => { draft.completed = true })\n   *   collection.delete(\"3\")\n   * })\n   *\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle mutate errors\n   * try {\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"invalid\" }) // This might throw\n   *   })\n   * } catch (error) {\n   *   console.log('Mutation failed:', error)\n   * }\n   *\n   * @example\n   * // Manual commit control\n   * const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Item\" })\n   * })\n   *\n   * // Commit later when ready\n   * await tx.commit()\n   */\n  mutate(callback: () => void): Transaction<T> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .mutate() as the transaction is no longer pending`\n    }\n\n    registerTransaction(this)\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit()\n    }\n\n    return this\n  }\n\n  applyMutations(mutations: Array<PendingMutation<any>>): void {\n    for (const newMutation of mutations) {\n      const existingIndex = this.mutations.findIndex(\n        (m) => m.globalKey === newMutation.globalKey\n      )\n\n      if (existingIndex >= 0) {\n        // Replace existing mutation\n        this.mutations[existingIndex] = newMutation\n      } else {\n        // Insert new mutation\n        this.mutations.push(newMutation)\n      }\n    }\n  }\n\n  /**\n   * Rollback the transaction and any conflicting transactions\n   * @param config - Configuration for rollback behavior\n   * @returns This transaction for chaining\n   * @example\n   * // Manual rollback\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * // Rollback if needed\n   * if (shouldCancel) {\n   *   tx.rollback()\n   * }\n   *\n   * @example\n   * // Handle rollback cascade (automatic)\n   * const tx1 = createTransaction({ mutationFn: async () => {} })\n   * const tx2 = createTransaction({ mutationFn: async () => {} })\n   *\n   * tx1.mutate(() => collection.update(\"1\", draft => { draft.value = \"A\" }))\n   * tx2.mutate(() => collection.update(\"1\", draft => { draft.value = \"B\" })) // Same item\n   *\n   * tx1.rollback() // This will also rollback tx2 due to conflict\n   *\n   * @example\n   * // Handle rollback in error scenarios\n   * try {\n   *   await tx.isPersisted.promise\n   * } catch (error) {\n   *   console.log('Transaction was rolled back:', error)\n   *   // Transaction automatically rolled back on mutation function failure\n   * }\n   */\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T> {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw `You can no longer call .rollback() as the transaction is already completed`\n    }\n\n    this.setState(`failed`)\n\n    // See if there's any other transactions w/ mutations on the same ids\n    // and roll them back as well.\n    if (!isSecondaryRollback) {\n      const mutationIds = new Set()\n      this.mutations.forEach((m) => mutationIds.add(m.globalKey))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.globalKey)) &&\n          t.rollback({ isSecondaryRollback: true })\n      }\n    }\n\n    // Reject the promise\n    this.isPersisted.reject(this.error?.error)\n    this.touchCollection()\n\n    return this\n  }\n\n  // Tell collection that something has changed with the transaction\n  touchCollection(): void {\n    const hasCalled = new Set()\n    for (const mutation of this.mutations) {\n      if (!hasCalled.has(mutation.collection.id)) {\n        mutation.collection.onTransactionStateChange()\n\n        // Only call commitPendingTransactions if there are pending sync transactions\n        if (mutation.collection.pendingSyncedTransactions.length > 0) {\n          mutation.collection.commitPendingTransactions()\n        }\n\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  /**\n   * Commit the transaction and execute the mutation function\n   * @returns Promise that resolves to this transaction when complete\n   * @example\n   * // Manual commit (when autoCommit is false)\n   * const tx = createTransaction({\n   *   autoCommit: false,\n   *   mutationFn: async ({ transaction }) => {\n   *     await api.saveChanges(transaction.mutations)\n   *   }\n   * })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * await tx.commit() // Manually commit\n   *\n   * @example\n   * // Handle commit errors\n   * try {\n   *   const tx = createTransaction({\n   *     mutationFn: async () => { throw new Error(\"API failed\") }\n   *   })\n   *\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"1\", text: \"Item\" })\n   *   })\n   *\n   *   await tx.commit()\n   * } catch (error) {\n   *   console.log('Commit failed, transaction rolled back:', error)\n   * }\n   *\n   * @example\n   * // Check transaction state after commit\n   * await tx.commit()\n   * console.log(tx.state) // \"completed\" or \"failed\"\n   */\n  async commit(): Promise<Transaction<T>> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .commit() as the transaction is no longer pending`\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n\n      return this\n    }\n\n    // Run mutationFn\n    try {\n      // At this point we know there's at least one mutation\n      // We've already verified mutations is non-empty, so this cast is safe\n      // Use a direct type assertion instead of object spreading to preserve the original type\n      await this.mutationFn({\n        transaction: this as unknown as TransactionWithMutations<T>,\n      })\n\n      this.setState(`completed`)\n      this.touchCollection()\n\n      this.isPersisted.resolve(this)\n    } catch (error) {\n      // Update transaction with error information\n      this.error = {\n        message: error instanceof Error ? error.message : String(error),\n        error: error instanceof Error ? error : new Error(String(error)),\n      }\n\n      // rollback the transaction\n      return this.rollback()\n    }\n\n    return this\n  }\n\n  /**\n   * Compare two transactions by their createdAt time and sequence number in order\n   * to sort them in the order they were created.\n   * @param other - The other transaction to compare to\n   * @returns -1 if this transaction was created before the other, 1 if it was created after, 0 if they were created at the same time\n   */\n  compareCreatedAt(other: Transaction<any>): number {\n    const createdAtComparison =\n      this.createdAt.getTime() - other.createdAt.getTime()\n    if (createdAtComparison !== 0) {\n      return createdAtComparison\n    }\n    return this.sequenceNumber - other.sequenceNumber\n  }\n}\n\nexport type { Transaction }\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"transactions.js","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport {\n  MissingMutationFunctionError,\n  TransactionAlreadyCompletedRollbackError,\n  TransactionNotPendingCommitError,\n  TransactionNotPendingMutateError,\n} from \"./errors\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n  TransactionWithMutations,\n} from \"./types\"\n\nconst transactions: Array<Transaction<any>> = []\nlet transactionStack: Array<Transaction<any>> = []\n\nlet sequenceNumber = 0\n\n/**\n * Creates a new transaction for grouping multiple collection operations\n * @param config - Transaction configuration with mutation function\n * @returns A new Transaction instance\n * @example\n * // Basic transaction usage\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Send all mutations to API\n *     await api.saveChanges(transaction.mutations)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n *   collection.update(\"2\", draft => { draft.completed = true })\n * })\n *\n * await tx.isPersisted.promise\n *\n * @example\n * // Handle transaction errors\n * try {\n *   const tx = createTransaction({\n *     mutationFn: async () => { throw new Error(\"API failed\") }\n *   })\n *\n *   tx.mutate(() => {\n *     collection.insert({ id: \"1\", text: \"New item\" })\n *   })\n *\n *   await tx.isPersisted.promise\n * } catch (error) {\n *   console.log('Transaction failed:', error)\n * }\n *\n * @example\n * // Manual commit control\n * const tx = createTransaction({\n *   autoCommit: false,\n *   mutationFn: async () => {\n *     // API call\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Item\" })\n * })\n *\n * // Commit later\n * await tx.commit()\n */\nexport function createTransaction<T extends object = Record<string, unknown>>(\n  config: TransactionConfig<T>\n): Transaction<T> {\n  const newTransaction = new Transaction<T>(config)\n  transactions.push(newTransaction)\n  return newTransaction\n}\n\n/**\n * Gets the currently active ambient transaction, if any\n * Used internally by collection operations to join existing transactions\n * @returns The active transaction or undefined if none is active\n * @example\n * // Check if operations will join an ambient transaction\n * const ambientTx = getActiveTransaction()\n * if (ambientTx) {\n *   console.log('Operations will join transaction:', ambientTx.id)\n * }\n */\nexport function getActiveTransaction(): Transaction | undefined {\n  if (transactionStack.length > 0) {\n    return transactionStack.slice(-1)[0]\n  } else {\n    return undefined\n  }\n}\n\nfunction registerTransaction(tx: Transaction<any>) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction<any>) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nclass Transaction<T extends object = Record<string, unknown>> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T>>\n  public isPersisted: Deferred<Transaction<T>>\n  public autoCommit: boolean\n  public createdAt: Date\n  public sequenceNumber: number\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig<T>) {\n    if (typeof config.mutationFn === `undefined`) {\n      throw new MissingMutationFunctionError()\n    }\n    this.id = config.id ?? crypto.randomUUID()\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred<Transaction<T>>()\n    this.autoCommit = config.autoCommit ?? true\n    this.createdAt = new Date()\n    this.sequenceNumber = sequenceNumber++\n    this.metadata = config.metadata ?? {}\n  }\n\n  setState(newState: TransactionState) {\n    this.state = newState\n\n    if (newState === `completed` || newState === `failed`) {\n      removeFromPendingList(this)\n    }\n  }\n\n  /**\n   * Execute collection operations within this transaction\n   * @param callback - Function containing collection operations to group together\n   * @returns This transaction for chaining\n   * @example\n   * // Group multiple operations\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   *   collection.update(\"2\", draft => { draft.completed = true })\n   *   collection.delete(\"3\")\n   * })\n   *\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle mutate errors\n   * try {\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"invalid\" }) // This might throw\n   *   })\n   * } catch (error) {\n   *   console.log('Mutation failed:', error)\n   * }\n   *\n   * @example\n   * // Manual commit control\n   * const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Item\" })\n   * })\n   *\n   * // Commit later when ready\n   * await tx.commit()\n   */\n  mutate(callback: () => void): Transaction<T> {\n    if (this.state !== `pending`) {\n      throw new TransactionNotPendingMutateError()\n    }\n\n    registerTransaction(this)\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit()\n    }\n\n    return this\n  }\n\n  applyMutations(mutations: Array<PendingMutation<any>>): void {\n    for (const newMutation of mutations) {\n      const existingIndex = this.mutations.findIndex(\n        (m) => m.globalKey === newMutation.globalKey\n      )\n\n      if (existingIndex >= 0) {\n        // Replace existing mutation\n        this.mutations[existingIndex] = newMutation\n      } else {\n        // Insert new mutation\n        this.mutations.push(newMutation)\n      }\n    }\n  }\n\n  /**\n   * Rollback the transaction and any conflicting transactions\n   * @param config - Configuration for rollback behavior\n   * @returns This transaction for chaining\n   * @example\n   * // Manual rollback\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * // Rollback if needed\n   * if (shouldCancel) {\n   *   tx.rollback()\n   * }\n   *\n   * @example\n   * // Handle rollback cascade (automatic)\n   * const tx1 = createTransaction({ mutationFn: async () => {} })\n   * const tx2 = createTransaction({ mutationFn: async () => {} })\n   *\n   * tx1.mutate(() => collection.update(\"1\", draft => { draft.value = \"A\" }))\n   * tx2.mutate(() => collection.update(\"1\", draft => { draft.value = \"B\" })) // Same item\n   *\n   * tx1.rollback() // This will also rollback tx2 due to conflict\n   *\n   * @example\n   * // Handle rollback in error scenarios\n   * try {\n   *   await tx.isPersisted.promise\n   * } catch (error) {\n   *   console.log('Transaction was rolled back:', error)\n   *   // Transaction automatically rolled back on mutation function failure\n   * }\n   */\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T> {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw new TransactionAlreadyCompletedRollbackError()\n    }\n\n    this.setState(`failed`)\n\n    // See if there's any other transactions w/ mutations on the same ids\n    // and roll them back as well.\n    if (!isSecondaryRollback) {\n      const mutationIds = new Set()\n      this.mutations.forEach((m) => mutationIds.add(m.globalKey))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.globalKey)) &&\n          t.rollback({ isSecondaryRollback: true })\n      }\n    }\n\n    // Reject the promise\n    this.isPersisted.reject(this.error?.error)\n    this.touchCollection()\n\n    return this\n  }\n\n  // Tell collection that something has changed with the transaction\n  touchCollection(): void {\n    const hasCalled = new Set()\n    for (const mutation of this.mutations) {\n      if (!hasCalled.has(mutation.collection.id)) {\n        mutation.collection.onTransactionStateChange()\n\n        // Only call commitPendingTransactions if there are pending sync transactions\n        if (mutation.collection.pendingSyncedTransactions.length > 0) {\n          mutation.collection.commitPendingTransactions()\n        }\n\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  /**\n   * Commit the transaction and execute the mutation function\n   * @returns Promise that resolves to this transaction when complete\n   * @example\n   * // Manual commit (when autoCommit is false)\n   * const tx = createTransaction({\n   *   autoCommit: false,\n   *   mutationFn: async ({ transaction }) => {\n   *     await api.saveChanges(transaction.mutations)\n   *   }\n   * })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * await tx.commit() // Manually commit\n   *\n   * @example\n   * // Handle commit errors\n   * try {\n   *   const tx = createTransaction({\n   *     mutationFn: async () => { throw new Error(\"API failed\") }\n   *   })\n   *\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"1\", text: \"Item\" })\n   *   })\n   *\n   *   await tx.commit()\n   * } catch (error) {\n   *   console.log('Commit failed, transaction rolled back:', error)\n   * }\n   *\n   * @example\n   * // Check transaction state after commit\n   * await tx.commit()\n   * console.log(tx.state) // \"completed\" or \"failed\"\n   */\n  async commit(): Promise<Transaction<T>> {\n    if (this.state !== `pending`) {\n      throw new TransactionNotPendingCommitError()\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n\n      return this\n    }\n\n    // Run mutationFn\n    try {\n      // At this point we know there's at least one mutation\n      // We've already verified mutations is non-empty, so this cast is safe\n      // Use a direct type assertion instead of object spreading to preserve the original type\n      await this.mutationFn({\n        transaction: this as unknown as TransactionWithMutations<T>,\n      })\n\n      this.setState(`completed`)\n      this.touchCollection()\n\n      this.isPersisted.resolve(this)\n    } catch (error) {\n      // Update transaction with error information\n      this.error = {\n        message: error instanceof Error ? error.message : String(error),\n        error: error instanceof Error ? error : new Error(String(error)),\n      }\n\n      // rollback the transaction\n      return this.rollback()\n    }\n\n    return this\n  }\n\n  /**\n   * Compare two transactions by their createdAt time and sequence number in order\n   * to sort them in the order they were created.\n   * @param other - The other transaction to compare to\n   * @returns -1 if this transaction was created before the other, 1 if it was created after, 0 if they were created at the same time\n   */\n  compareCreatedAt(other: Transaction<any>): number {\n    const createdAtComparison =\n      this.createdAt.getTime() - other.createdAt.getTime()\n    if (createdAtComparison !== 0) {\n      return createdAtComparison\n    }\n    return this.sequenceNumber - other.sequenceNumber\n  }\n}\n\nexport type { Transaction }\n"],"names":[],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -2,6 +2,8 @@ import { IStreamBuilder } from '@electric-sql/d2mini';
 import { Collection } from './collection.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Transaction } from './transactions.js';
+import { SingleRowRefProxy } from './query/builder/ref-proxy.js';
+import { BasicExpression } from './query/ir.js';
 /**
  * Helper type to extract the output type from a standard schema
  *
@@ -239,6 +241,15 @@ export interface CollectionConfig<T extends object = Record<string, unknown>, TK
      * Defaults to false for lazy loading. Set to true to immediately sync.
      */
     startSync?: boolean;
+    /**
+     * Auto-indexing mode for the collection.
+     * When enabled, indexes will be automatically created for simple where expressions.
+     * @default "eager"
+     * @description
+     * - "off": No automatic indexing
+     * - "eager": Automatically create indexes for simple where expressions in subscribeChanges (default)
+     */
+    autoIndex?: `off` | `eager`;
     /**
      * Optional function to compare two items.
      * This is used to order the items in the collection.
@@ -409,6 +420,26 @@ export type KeyedNamespacedRow = [unknown, NamespacedRow];
  * a `select` clause.
  */
 export type NamespacedAndKeyedStream = IStreamBuilder<KeyedNamespacedRow>;
+/**
+ * Options for subscribing to collection changes
+ */
+export interface SubscribeChangesOptions<T extends object = Record<string, unknown>> {
+    /** Whether to include the current state as initial changes */
+    includeInitialState?: boolean;
+    /** Filter changes using a where expression */
+    where?: (row: SingleRowRefProxy<T>) => any;
+    /** Pre-compiled expression for filtering changes */
+    whereExpression?: BasicExpression<boolean>;
+}
+/**
+ * Options for getting current state as changes
+ */
+export interface CurrentStateAsChangesOptions<T extends object = Record<string, unknown>> {
+    /** Filter the current state using a where expression */
+    where?: (row: SingleRowRefProxy<T>) => any;
+    /** Pre-compiled expression for filtering the current state */
+    whereExpression?: BasicExpression<boolean>;
+}
 /**
  * Function type for listening to collection changes
  * @param changes - Array of change messages describing what happened

package/dist/esm/utils/array-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Finds the correct insert position for a value in a sorted array using binary search
+ * @param sortedArray The sorted array to search in
+ * @param value The value to find the position for
+ * @param compareFn Comparison function to use for ordering
+ * @returns The index where the value should be inserted to maintain order
+ */
+export declare function findInsertPosition<T>(sortedArray: Array<[T, any]>, value: T, compareFn: (a: T, b: T) => number): number;

package/dist/esm/utils/array-utils.js

@@ -0,0 +1,18 @@
+function findInsertPosition(sortedArray, value, compareFn) {
+  let left = 0;
+  let right = sortedArray.length;
+  while (left < right) {
+    const mid = Math.floor((left + right) / 2);
+    const comparison = compareFn(sortedArray[mid][0], value);
+    if (comparison < 0) {
+      left = mid + 1;
+    } else {
+      right = mid;
+    }
+  }
+  return left;
+}
+export {
+  findInsertPosition
+};
+//# sourceMappingURL=array-utils.js.map

package/dist/esm/utils/array-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-utils.js","sources":["../../../src/utils/array-utils.ts"],"sourcesContent":["/**\n * Finds the correct insert position for a value in a sorted array using binary search\n * @param sortedArray The sorted array to search in\n * @param value The value to find the position for\n * @param compareFn Comparison function to use for ordering\n * @returns The index where the value should be inserted to maintain order\n */\nexport function findInsertPosition<T>(\n  sortedArray: Array<[T, any]>,\n  value: T,\n  compareFn: (a: T, b: T) => number\n): number {\n  let left = 0\n  let right = sortedArray.length\n\n  while (left < right) {\n    const mid = Math.floor((left + right) / 2)\n    const comparison = compareFn(sortedArray[mid]![0], value)\n\n    if (comparison < 0) {\n      left = mid + 1\n    } else {\n      right = mid\n    }\n  }\n\n  return left\n}\n"],"names":[],"mappings":"AAOO,SAAS,mBACd,aACA,OACA,WACQ;AACR,MAAI,OAAO;AACX,MAAI,QAAQ,YAAY;AAExB,SAAO,OAAO,OAAO;AACnB,UAAM,MAAM,KAAK,OAAO,OAAO,SAAS,CAAC;AACzC,UAAM,aAAa,UAAU,YAAY,GAAG,EAAG,CAAC,GAAG,KAAK;AAExD,QAAI,aAAa,GAAG;AAClB,aAAO,MAAM;AAAA,IACf,OAAO;AACL,cAAQ;AAAA,IACV;AAAA,EACF;AAEA,SAAO;AACT;"}

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

@@ -0,0 +1,11 @@
+/**
+ * Universal comparison function for all data types
+ * Handles null/undefined, strings, arrays, dates, objects, and primitives
+ * Always sorts null/undefined values first
+ */
+export declare const ascComparator: (a: any, b: any) => number;
+/**
+ * Descending comparator function for ordering values
+ * Handles null/undefined as largest values (opposite of ascending)
+ */
+export declare const descComparator: (a: unknown, b: unknown) => number;

package/dist/esm/utils/comparison.js

@@ -0,0 +1,52 @@
+const objectIds = /* @__PURE__ */ new WeakMap();
+let nextObjectId = 1;
+function getObjectId(obj) {
+  if (objectIds.has(obj)) {
+    return objectIds.get(obj);
+  }
+  const id = nextObjectId++;
+  objectIds.set(obj, id);
+  return id;
+}
+const ascComparator = (a, b) => {
+  if (a == null && b == null) return 0;
+  if (a == null) return -1;
+  if (b == null) return 1;
+  if (typeof a === `string` && typeof b === `string`) {
+    return a.localeCompare(b);
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+      const result = ascComparator(a[i], b[i]);
+      if (result !== 0) {
+        return result;
+      }
+    }
+    return a.length - b.length;
+  }
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+  const aIsObject = typeof a === `object`;
+  const bIsObject = typeof b === `object`;
+  if (aIsObject || bIsObject) {
+    if (aIsObject && bIsObject) {
+      const aId = getObjectId(a);
+      const bId = getObjectId(b);
+      return aId - bId;
+    }
+    if (aIsObject) return 1;
+    if (bIsObject) return -1;
+  }
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+};
+const descComparator = (a, b) => {
+  return ascComparator(b, a);
+};
+export {
+  ascComparator,
+  descComparator
+};
+//# sourceMappingURL=comparison.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comparison.js","sources":["../../../src/utils/comparison.ts"],"sourcesContent":["// 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): number => {\n  // Handle null/undefined\n  if (a == null && b == null) return 0\n  if (a == null) return -1\n  if (b == null) return 1\n\n  // if a and b are both strings, compare them based on locale\n  if (typeof a === `string` && typeof b === `string`) {\n    return a.localeCompare(b)\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])\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 = (a: unknown, b: unknown): number => {\n  return ascComparator(b, a)\n}\n"],"names":[],"mappings":"AACA,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,MAAmB;AAEvD,MAAI,KAAK,QAAQ,KAAK,KAAM,QAAO;AACnC,MAAI,KAAK,KAAM,QAAO;AACtB,MAAI,KAAK,KAAM,QAAO;AAGtB,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAClD,WAAO,EAAE,cAAc,CAAC;AAAA,EAC1B;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,CAAC;AACvC,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,CAAC,GAAY,MAAuB;AAChE,SAAO,cAAc,GAAG,CAAC;AAC3B;"}

package/dist/esm/utils/index-optimization.d.ts

@@ -0,0 +1,29 @@
+import { BaseIndex } from '../indexes/base-index.js';
+import { BasicExpression } from '../query/ir.js';
+/**
+ * Result of index-based query optimization
+ */
+export interface OptimizationResult<TKey> {
+    canOptimize: boolean;
+    matchingKeys: Set<TKey>;
+}
+/**
+ * Finds an index that matches a given field path
+ */
+export declare function findIndexForField<TKey extends string | number>(indexes: Map<number, BaseIndex<TKey>>, fieldPath: Array<string>): BaseIndex<TKey> | undefined;
+/**
+ * Intersects multiple sets (AND logic)
+ */
+export declare function intersectSets<T>(sets: Array<Set<T>>): Set<T>;
+/**
+ * Unions multiple sets (OR logic)
+ */
+export declare function unionSets<T>(sets: Array<Set<T>>): Set<T>;
+/**
+ * Optimizes a query expression using available indexes to find matching keys
+ */
+export declare function optimizeExpressionWithIndexes<TKey extends string | number>(expression: BasicExpression, indexes: Map<number, BaseIndex<TKey>>): OptimizationResult<TKey>;
+/**
+ * Checks if an expression can be optimized
+ */
+export declare function canOptimizeExpression<TKey extends string | number>(expression: BasicExpression, indexes: Map<number, BaseIndex<TKey>>): boolean;