@tanstack/db 0.5.1 → 0.5.3

package/dist/cjs/query/optimizer.cjs

@@ -3,7 +3,6 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const utils = require("../utils.cjs");
 const errors = require("../errors.cjs");
 const ir = require("./ir.cjs");
-const expressions = require("./compiler/expressions.cjs");
 function optimizeQuery(query) {
   const sourceWhereClauses = extractSourceWhereClauses(query);
   let optimized = query;
@@ -33,9 +32,7 @@ function extractSourceWhereClauses(query) {
   const groupedClauses = groupWhereClauses(analyzedClauses);
   for (const [sourceAlias, whereClause] of groupedClauses.singleSource) {
     if (isCollectionReference(query, sourceAlias)) {
-      if (expressions.isConvertibleToCollectionFilter(whereClause)) {
-        sourceWhereClauses.set(sourceAlias, whereClause);
-      }
+      sourceWhereClauses.set(sourceAlias, whereClause);
     }
   }
   return sourceWhereClauses;
@@ -427,14 +424,14 @@ function referencesAliasWithRemappedSelect(subquery, whereClause, outerAlias) {
   }
   return false;
 }
-function combineWithAnd(expressions2) {
-  if (expressions2.length === 0) {
+function combineWithAnd(expressions) {
+  if (expressions.length === 0) {
     throw new errors.CannotCombineEmptyExpressionListError();
   }
-  if (expressions2.length === 1) {
-    return expressions2[0];
+  if (expressions.length === 1) {
+    return expressions[0];
   }
-  return new ir.Func(`and`, expressions2);
+  return new ir.Func(`and`, expressions);
 }
 exports.optimizeQuery = optimizeQuery;
 //# sourceMappingURL=optimizer.cjs.map

package/dist/cjs/query/optimizer.cjs.map

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

package/dist/cjs/types.d.cts

@@ -89,7 +89,26 @@ export type NonEmptyArray<T> = [T, ...Array<T>];
  * Utility type for a Transaction with at least one mutation
  * This is used internally by the Transaction.commit method
  */
-export type TransactionWithMutations<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = Transaction<T> & {
+export type TransactionWithMutations<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = Omit<Transaction<T>, `mutations`> & {
+    /**
+     * We must omit the `mutations` property from `Transaction<T>` before intersecting
+     * because TypeScript intersects property types when the same property appears on
+     * both sides of an intersection.
+     *
+     * Without `Omit`:
+     * - `Transaction<T>` has `mutations: Array<PendingMutation<T>>`
+     * - The intersection would create: `Array<PendingMutation<T>> & NonEmptyArray<PendingMutation<T, TOperation>>`
+     * - When mapping over this array, TypeScript widens `TOperation` from the specific literal
+     *   (e.g., `"delete"`) to the union `OperationType` (`"insert" | "update" | "delete"`)
+     * - This causes `PendingMutation<T, OperationType>` to evaluate the conditional type
+     *   `original: TOperation extends 'insert' ? {} : T` as `{} | T` instead of just `T`
+     *
+     * With `Omit`:
+     * - We remove `mutations` from `Transaction<T>` first
+     * - Then add back `mutations: NonEmptyArray<PendingMutation<T, TOperation>>`
+     * - TypeScript can properly narrow `TOperation` to the specific literal type
+     * - This ensures `mutation.original` is correctly typed as `T` (not `{} | T`) when mapping
+     */
     mutations: NonEmptyArray<PendingMutation<T, TOperation>>;
 };
 export interface TransactionConfig<T extends object = Record<string, unknown>> {

package/dist/esm/collection/index.d.ts

@@ -289,7 +289,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      *   console.log('Insert failed:', error)
      * }
      */
-    insert: (data: TInput | Array<TInput>, config?: InsertConfig) => TransactionType<Record<string, unknown>> | TransactionType<TOutput>;
+    insert: (data: TInput | Array<TInput>, config?: InsertConfig) => TransactionType<Record<string, unknown>>;
     /**
      * Updates one or more items in the collection using a callback function
      * @param keys - Single key or array of keys to update

package/dist/esm/collection/mutations.d.ts

@@ -21,11 +21,11 @@ export declare class CollectionMutationsManager<TOutput extends object = Record<
     /**
      * Inserts one or more items into the collection
      */
-    insert: (data: TInput | Array<TInput>, config?: InsertConfig) => TransactionType<Record<string, unknown>> | TransactionType<TOutput>;
+    insert: (data: TInput | Array<TInput>, config?: InsertConfig) => TransactionType<Record<string, unknown>>;
     /**
      * Updates one or more items in the collection using a callback function
      */
-    update(keys: (TKey | unknown) | Array<TKey | unknown>, configOrCallback: ((draft: WritableDeep<TInput>) => void) | ((drafts: Array<WritableDeep<TInput>>) => void) | OperationConfig, maybeCallback?: ((draft: WritableDeep<TInput>) => void) | ((drafts: Array<WritableDeep<TInput>>) => void)): TransactionType<Record<string, unknown>> | TransactionType<TOutput>;
+    update(keys: (TKey | unknown) | Array<TKey | unknown>, configOrCallback: ((draft: WritableDeep<TInput>) => void) | ((drafts: Array<WritableDeep<TInput>>) => void) | OperationConfig, maybeCallback?: ((draft: WritableDeep<TInput>) => void) | ((drafts: Array<WritableDeep<TInput>>) => void)): TransactionType<Record<string, unknown>>;
     /**
      * Deletes one or more items from the collection
      */

package/dist/esm/local-storage.js

@@ -12,6 +12,21 @@ function validateJsonSerializable(parser, value, operation) {
 function generateUuid() {
   return crypto.randomUUID();
 }
+function encodeStorageKey(key) {
+  if (typeof key === `number`) {
+    return `n:${key}`;
+  }
+  return `s:${key}`;
+}
+function decodeStorageKey(encodedKey) {
+  if (encodedKey.startsWith(`n:`)) {
+    return Number(encodedKey.slice(2));
+  }
+  if (encodedKey.startsWith(`s:`)) {
+    return encodedKey.slice(2);
+  }
+  return encodedKey;
+}
 function createInMemoryStorage() {
   const storage = /* @__PURE__ */ new Map();
   return {
@@ -54,7 +69,7 @@ function localStorageCollectionOptions(config) {
     try {
       const objectData = {};
       dataMap.forEach((storedItem, key) => {
-        objectData[String(key)] = storedItem;
+        objectData[encodeStorageKey(key)] = storedItem;
       });
       const serialized = parser.stringify(objectData);
       storage.setItem(config.storageKey, serialized);
@@ -82,12 +97,11 @@ function localStorageCollectionOptions(config) {
       handlerResult = await config.onInsert(params) ?? {};
     }
     params.transaction.mutations.forEach((mutation) => {
-      const key = mutation.key;
       const storedItem = {
         versionKey: generateUuid(),
         data: mutation.modified
       };
-      lastKnownData.set(key, storedItem);
+      lastKnownData.set(mutation.key, storedItem);
     });
     saveToStorage(lastKnownData);
     sync.confirmOperationsSync(params.transaction.mutations);
@@ -102,12 +116,11 @@ function localStorageCollectionOptions(config) {
       handlerResult = await config.onUpdate(params) ?? {};
     }
     params.transaction.mutations.forEach((mutation) => {
-      const key = mutation.key;
       const storedItem = {
         versionKey: generateUuid(),
         data: mutation.modified
       };
-      lastKnownData.set(key, storedItem);
+      lastKnownData.set(mutation.key, storedItem);
     });
     saveToStorage(lastKnownData);
     sync.confirmOperationsSync(params.transaction.mutations);
@@ -119,8 +132,7 @@ function localStorageCollectionOptions(config) {
       handlerResult = await config.onDelete(params) ?? {};
     }
     params.transaction.mutations.forEach((mutation) => {
-      const key = mutation.key;
-      lastKnownData.delete(key);
+      lastKnownData.delete(mutation.key);
     });
     saveToStorage(lastKnownData);
     sync.confirmOperationsSync(params.transaction.mutations);
@@ -159,7 +171,6 @@ function localStorageCollectionOptions(config) {
       }
     }
     for (const mutation of collectionMutations) {
-      const key = mutation.key;
       switch (mutation.type) {
         case `insert`:
         case `update`: {
@@ -167,11 +178,11 @@ function localStorageCollectionOptions(config) {
             versionKey: generateUuid(),
             data: mutation.modified
           };
-          lastKnownData.set(key, storedItem);
+          lastKnownData.set(mutation.key, storedItem);
           break;
         }
         case `delete`: {
-          lastKnownData.delete(key);
+          lastKnownData.delete(mutation.key);
           break;
         }
       }
@@ -202,12 +213,13 @@ function loadFromStorage(storageKey, storage, parser) {
     const parsed = parser.parse(rawData);
     const dataMap = /* @__PURE__ */ new Map();
     if (typeof parsed === `object` && parsed !== null && !Array.isArray(parsed)) {
-      Object.entries(parsed).forEach(([key, value]) => {
+      Object.entries(parsed).forEach(([encodedKey, value]) => {
         if (value && typeof value === `object` && `versionKey` in value && `data` in value) {
           const storedItem = value;
-          dataMap.set(key, storedItem);
+          const decodedKey = decodeStorageKey(encodedKey);
+          dataMap.set(decodedKey, storedItem);
         } else {
-          throw new InvalidStorageDataFormatError(storageKey, key);
+          throw new InvalidStorageDataFormatError(storageKey, encodedKey);
         }
       });
     } else {

package/dist/esm/local-storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"local-storage.js","sources":["../../src/local-storage.ts"],"sourcesContent":["import {\n  InvalidStorageDataFormatError,\n  InvalidStorageObjectFormatError,\n  SerializationError,\n  StorageKeyRequiredError,\n} from \"./errors\"\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InferSchemaOutput,\n  InsertMutationFnParams,\n  PendingMutation,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"./types\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n/**\n * Storage API interface - subset of DOM Storage that we need\n */\nexport type StorageApi = Pick<Storage, `getItem` | `setItem` | `removeItem`>\n\n/**\n * Storage event API - subset of Window for 'storage' events only\n */\nexport type StorageEventApi = {\n  addEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n  removeEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n}\n\n/**\n * Internal storage format that includes version tracking\n */\ninterface StoredItem<T> {\n  versionKey: string\n  data: T\n}\n\nexport interface Parser {\n  parse: (data: string) => unknown\n  stringify: (data: unknown) => string\n}\n\n/**\n * Configuration interface for localStorage collection options\n * @template T - The type of items in the collection\n * @template TSchema - The schema type for validation\n * @template TKey - The type of the key returned by `getKey`\n */\nexport interface LocalStorageCollectionConfig<\n  T extends object = object,\n  TSchema extends StandardSchemaV1 = never,\n  TKey extends string | number = string | number,\n> extends BaseCollectionConfig<T, TKey, TSchema> {\n  /**\n   * The key to use for storing the collection data in localStorage/sessionStorage\n   */\n  storageKey: string\n\n  /**\n   * Storage API to use (defaults to window.localStorage)\n   * Can be any object that implements the Storage interface (e.g., sessionStorage)\n   */\n  storage?: StorageApi\n\n  /**\n   * Storage event API to use for cross-tab synchronization (defaults to window)\n   * Can be any object that implements addEventListener/removeEventListener for storage events\n   */\n  storageEventApi?: StorageEventApi\n\n  /**\n   * Parser to use for serializing and deserializing data to and from storage\n   * Defaults to JSON\n   */\n  parser?: Parser\n}\n\n/**\n * Type for the clear utility function\n */\nexport type ClearStorageFn = () => void\n\n/**\n * Type for the getStorageSize utility function\n */\nexport type GetStorageSizeFn = () => number\n\n/**\n * LocalStorage collection utilities type\n */\nexport interface LocalStorageCollectionUtils extends UtilsRecord {\n  clearStorage: ClearStorageFn\n  getStorageSize: GetStorageSizeFn\n  /**\n   * Accepts mutations from a transaction that belong to this collection and persists them to localStorage.\n   * This should be called in your transaction's mutationFn to persist local-storage data.\n   *\n   * @param transaction - The transaction containing mutations to accept\n   * @example\n   * const localSettings = createCollection(localStorageCollectionOptions({...}))\n   *\n   * const tx = createTransaction({\n   *   mutationFn: async ({ transaction }) => {\n   *     // Make API call first\n   *     await api.save(...)\n   *     // Then persist local-storage mutations after success\n   *     localSettings.utils.acceptMutations(transaction)\n   *   }\n   * })\n   */\n  acceptMutations: (transaction: {\n    mutations: Array<PendingMutation<Record<string, unknown>>>\n  }) => void\n}\n\n/**\n * Validates that a value can be JSON serialized\n * @param parser - The parser to use for serialization\n * @param value - The value to validate for JSON serialization\n * @param operation - The operation type being performed (for error messages)\n * @throws Error if the value cannot be JSON serialized\n */\nfunction validateJsonSerializable(\n  parser: Parser,\n  value: any,\n  operation: string\n): void {\n  try {\n    parser.stringify(value)\n  } catch (error) {\n    throw new SerializationError(\n      operation,\n      error instanceof Error ? error.message : String(error)\n    )\n  }\n}\n\n/**\n * Generate a UUID for version tracking\n * @returns A unique identifier string for tracking data versions\n */\nfunction generateUuid(): string {\n  return crypto.randomUUID()\n}\n\n/**\n * Creates an in-memory storage implementation that mimics the StorageApi interface\n * Used as a fallback when localStorage is not available (e.g., server-side rendering)\n * @returns An object implementing the StorageApi interface using an in-memory Map\n */\nfunction createInMemoryStorage(): StorageApi {\n  const storage = new Map<string, string>()\n\n  return {\n    getItem(key: string): string | null {\n      return storage.get(key) ?? null\n    },\n    setItem(key: string, value: string): void {\n      storage.set(key, value)\n    },\n    removeItem(key: string): void {\n      storage.delete(key)\n    },\n  }\n}\n\n/**\n * Creates a no-op storage event API for environments without window (e.g., server-side)\n * This provides the required interface but doesn't actually listen to any events\n * since cross-tab synchronization is not possible in server environments\n * @returns An object implementing the StorageEventApi interface with no-op methods\n */\nfunction createNoOpStorageEventApi(): StorageEventApi {\n  return {\n    addEventListener: () => {\n      // No-op: cannot listen to storage events without window\n    },\n    removeEventListener: () => {\n      // No-op: cannot remove listeners without window\n    },\n  }\n}\n\n/**\n * Creates localStorage collection options for use with a standard Collection\n *\n * This function creates a collection that persists data to localStorage/sessionStorage\n * and synchronizes changes across browser tabs using storage events.\n *\n * **Fallback Behavior:**\n *\n * When localStorage is not available (e.g., in server-side rendering environments),\n * this function automatically falls back to an in-memory storage implementation.\n * This prevents errors during module initialization and allows the collection to\n * work in any environment, though data will not persist across page reloads or\n * be shared across tabs when using the in-memory fallback.\n *\n * **Using with Manual Transactions:**\n *\n * For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`\n * to persist changes made during `tx.mutate()`. This is necessary because local-storage collections\n * don't participate in the standard mutation handler flow for manual transactions.\n *\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @param config - Configuration options for the localStorage collection\n * @returns Collection options with utilities including clearStorage, getStorageSize, and acceptMutations\n *\n * @example\n * // Basic localStorage collection\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with custom storage\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     storage: window.sessionStorage, // Use sessionStorage instead\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with mutation handlers\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       console.log('Item inserted:', transaction.mutations[0].modified)\n *     },\n *   })\n * )\n *\n * @example\n * // Using with manual transactions\n * const localSettings = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'user-settings',\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Use settings data in API call\n *     const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)\n *     await api.updateUserProfile({ settings: settingsMutations[0]?.modified })\n *\n *     // Persist local-storage mutations after API success\n *     localSettings.utils.acceptMutations(transaction)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   localSettings.insert({ id: 'theme', value: 'dark' })\n *   apiCollection.insert({ id: 2, data: 'profile data' })\n * })\n *\n * await tx.commit()\n */\n\n// Overload for when schema is provided\nexport function localStorageCollectionOptions<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {\n    schema: T\n  }\n): CollectionConfig<\n  InferSchemaOutput<T>,\n  TKey,\n  T,\n  LocalStorageCollectionUtils\n> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema: T\n}\n\n// Overload for when no schema is provided\n// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config\nexport function localStorageCollectionOptions<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<T, never, TKey> & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey, never, LocalStorageCollectionUtils> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: never // no schema in the result\n}\n\nexport function localStorageCollectionOptions(\n  config: LocalStorageCollectionConfig<any, any, string | number>\n): Omit<\n  CollectionConfig<any, string | number, any, LocalStorageCollectionUtils>,\n  `id`\n> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: StandardSchemaV1\n} {\n  // Validate required parameters\n  if (!config.storageKey) {\n    throw new StorageKeyRequiredError()\n  }\n\n  // Default to window.localStorage if no storage is provided\n  // Fall back to in-memory storage if localStorage is not available (e.g., server-side rendering)\n  const storage =\n    config.storage ||\n    (typeof window !== `undefined` ? window.localStorage : null) ||\n    createInMemoryStorage()\n\n  // Default to window for storage events if not provided\n  // Fall back to no-op storage event API if window is not available (e.g., server-side rendering)\n  const storageEventApi =\n    config.storageEventApi ||\n    (typeof window !== `undefined` ? window : null) ||\n    createNoOpStorageEventApi()\n\n  // Default to JSON parser if no parser is provided\n  const parser = config.parser || JSON\n\n  // Track the last known state to detect changes\n  const lastKnownData = new Map<string | number, StoredItem<any>>()\n\n  // Create the sync configuration\n  const sync = createLocalStorageSync<any>(\n    config.storageKey,\n    storage,\n    storageEventApi,\n    parser,\n    config.getKey,\n    lastKnownData\n  )\n\n  /**\n   * Save data to storage\n   * @param dataMap - Map of items with version tracking to save to storage\n   */\n  const saveToStorage = (\n    dataMap: Map<string | number, StoredItem<any>>\n  ): void => {\n    try {\n      // Convert Map to object format for storage\n      const objectData: Record<string, StoredItem<any>> = {}\n      dataMap.forEach((storedItem, key) => {\n        objectData[String(key)] = storedItem\n      })\n      const serialized = parser.stringify(objectData)\n      storage.setItem(config.storageKey, serialized)\n    } catch (error) {\n      console.error(\n        `[LocalStorageCollection] Error saving data to storage key \"${config.storageKey}\":`,\n        error\n      )\n      throw error\n    }\n  }\n\n  /**\n   * Removes all collection data from the configured storage\n   */\n  const clearStorage: ClearStorageFn = (): void => {\n    storage.removeItem(config.storageKey)\n  }\n\n  /**\n   * Get the size of the stored data in bytes (approximate)\n   * @returns The approximate size in bytes of the stored collection data\n   */\n  const getStorageSize: GetStorageSizeFn = (): number => {\n    const data = storage.getItem(config.storageKey)\n    return data ? new Blob([data]).size : 0\n  }\n\n  /*\n   * Create wrapper handlers for direct persistence operations that perform actual storage operations\n   * Wraps the user's onInsert handler to also save changes to localStorage\n   */\n  const wrappedOnInsert = async (params: InsertMutationFnParams<any>) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(parser, mutation.modified, `insert`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onInsert) {\n      handlerResult = (await config.onInsert(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Add new items with version keys\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const key = mutation.key\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      lastKnownData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  const wrappedOnUpdate = async (params: UpdateMutationFnParams<any>) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(parser, mutation.modified, `update`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onUpdate) {\n      handlerResult = (await config.onUpdate(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Update items with new version keys\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const key = mutation.key\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      lastKnownData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  const wrappedOnDelete = async (params: DeleteMutationFnParams<any>) => {\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onDelete) {\n      handlerResult = (await config.onDelete(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Remove items\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const key = mutation.key\n      lastKnownData.delete(key)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  // Extract standard Collection config properties\n  const {\n    storageKey: _storageKey,\n    storage: _storage,\n    storageEventApi: _storageEventApi,\n    onInsert: _onInsert,\n    onUpdate: _onUpdate,\n    onDelete: _onDelete,\n    id,\n    ...restConfig\n  } = config\n\n  // Default id to a pattern based on storage key if not provided\n  const collectionId = id ?? `local-collection:${config.storageKey}`\n\n  /**\n   * Accepts mutations from a transaction that belong to this collection and persists them to storage\n   */\n  const acceptMutations = (transaction: {\n    mutations: Array<PendingMutation<Record<string, unknown>>>\n  }) => {\n    // Filter mutations that belong to this collection\n    // Use collection ID for filtering if collection reference isn't available yet\n    const collectionMutations = transaction.mutations.filter((m) => {\n      // Try to match by collection reference first\n      if (sync.collection && m.collection === sync.collection) {\n        return true\n      }\n      // Fall back to matching by collection ID\n      return m.collection.id === collectionId\n    })\n\n    if (collectionMutations.length === 0) {\n      return\n    }\n\n    // Validate all mutations can be serialized before modifying storage\n    for (const mutation of collectionMutations) {\n      switch (mutation.type) {\n        case `insert`:\n        case `update`:\n          validateJsonSerializable(parser, mutation.modified, mutation.type)\n          break\n        case `delete`:\n          validateJsonSerializable(parser, mutation.original, mutation.type)\n          break\n      }\n    }\n\n    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Apply each mutation\n    for (const mutation of collectionMutations) {\n      // Use the engine's pre-computed key to avoid key derivation issues\n      const key = mutation.key\n\n      switch (mutation.type) {\n        case `insert`:\n        case `update`: {\n          const storedItem: StoredItem<Record<string, unknown>> = {\n            versionKey: generateUuid(),\n            data: mutation.modified,\n          }\n          lastKnownData.set(key, storedItem)\n          break\n        }\n        case `delete`: {\n          lastKnownData.delete(key)\n          break\n        }\n      }\n    }\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm the mutations in the collection to move them from optimistic to synced state\n    // This writes them through the sync interface to make them \"synced\" instead of \"optimistic\"\n    sync.confirmOperationsSync(collectionMutations)\n  }\n\n  return {\n    ...restConfig,\n    id: collectionId,\n    sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      clearStorage,\n      getStorageSize,\n      acceptMutations,\n    },\n  }\n}\n\n/**\n * Load data from storage and return as a Map\n * @param parser - The parser to use for deserializing the data\n * @param storageKey - The key used to store data in the storage API\n * @param storage - The storage API to load from (localStorage, sessionStorage, etc.)\n * @returns Map of stored items with version tracking, or empty Map if loading fails\n */\nfunction loadFromStorage<T extends object>(\n  storageKey: string,\n  storage: StorageApi,\n  parser: Parser\n): Map<string | number, StoredItem<T>> {\n  try {\n    const rawData = storage.getItem(storageKey)\n    if (!rawData) {\n      return new Map()\n    }\n\n    const parsed = parser.parse(rawData)\n    const dataMap = new Map<string | number, StoredItem<T>>()\n\n    // Handle object format where keys map to StoredItem values\n    if (\n      typeof parsed === `object` &&\n      parsed !== null &&\n      !Array.isArray(parsed)\n    ) {\n      Object.entries(parsed).forEach(([key, value]) => {\n        // Runtime check to ensure the value has the expected StoredItem structure\n        if (\n          value &&\n          typeof value === `object` &&\n          `versionKey` in value &&\n          `data` in value\n        ) {\n          const storedItem = value as StoredItem<T>\n          dataMap.set(key, storedItem)\n        } else {\n          throw new InvalidStorageDataFormatError(storageKey, key)\n        }\n      })\n    } else {\n      throw new InvalidStorageObjectFormatError(storageKey)\n    }\n\n    return dataMap\n  } catch (error) {\n    console.warn(\n      `[LocalStorageCollection] Error loading data from storage key \"${storageKey}\":`,\n      error\n    )\n    return new Map()\n  }\n}\n\n/**\n * Internal function to create localStorage sync configuration\n * Creates a sync configuration that handles localStorage persistence and cross-tab synchronization\n * @param storageKey - The key used for storing data in localStorage\n * @param storage - The storage API to use (localStorage, sessionStorage, etc.)\n * @param storageEventApi - The event API for listening to storage changes\n * @param getKey - Function to extract the key from an item\n * @param lastKnownData - Map tracking the last known state for change detection\n * @returns Sync configuration with manual trigger capability\n */\nfunction createLocalStorageSync<T extends object>(\n  storageKey: string,\n  storage: StorageApi,\n  storageEventApi: StorageEventApi,\n  parser: Parser,\n  _getKey: (item: T) => string | number,\n  lastKnownData: Map<string | number, StoredItem<T>>\n): SyncConfig<T> & {\n  manualTrigger?: () => void\n  collection: any\n  confirmOperationsSync: (mutations: Array<any>) => void\n} {\n  let syncParams: Parameters<SyncConfig<T>[`sync`]>[0] | null = null\n  let collection: any = null\n\n  /**\n   * Compare two Maps to find differences using version keys\n   * @param oldData - The previous state of stored items\n   * @param newData - The current state of stored items\n   * @returns Array of changes with type, key, and value information\n   */\n  const findChanges = (\n    oldData: Map<string | number, StoredItem<T>>,\n    newData: Map<string | number, StoredItem<T>>\n  ): Array<{\n    type: `insert` | `update` | `delete`\n    key: string | number\n    value?: T\n  }> => {\n    const changes: Array<{\n      type: `insert` | `update` | `delete`\n      key: string | number\n      value?: T\n    }> = []\n\n    // Check for deletions and updates\n    oldData.forEach((oldStoredItem, key) => {\n      const newStoredItem = newData.get(key)\n      if (!newStoredItem) {\n        changes.push({ type: `delete`, key, value: oldStoredItem.data })\n      } else if (oldStoredItem.versionKey !== newStoredItem.versionKey) {\n        changes.push({ type: `update`, key, value: newStoredItem.data })\n      }\n    })\n\n    // Check for insertions\n    newData.forEach((newStoredItem, key) => {\n      if (!oldData.has(key)) {\n        changes.push({ type: `insert`, key, value: newStoredItem.data })\n      }\n    })\n\n    return changes\n  }\n\n  /**\n   * Process storage changes and update collection\n   * Loads new data from storage, compares with last known state, and applies changes\n   */\n  const processStorageChanges = () => {\n    if (!syncParams) return\n\n    const { begin, write, commit } = syncParams\n\n    // Load the new data\n    const newData = loadFromStorage<T>(storageKey, storage, parser)\n\n    // Find the specific changes\n    const changes = findChanges(lastKnownData, newData)\n\n    if (changes.length > 0) {\n      begin()\n      changes.forEach(({ type, value }) => {\n        if (value) {\n          validateJsonSerializable(parser, value, type)\n          write({ type, value })\n        }\n      })\n      commit()\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      newData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n    }\n  }\n\n  const syncConfig: SyncConfig<T> & {\n    manualTrigger?: () => void\n    collection: any\n  } = {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady } = params\n\n      // Store sync params and collection for later use\n      syncParams = params\n      collection = params.collection\n\n      // Initial load\n      const initialData = loadFromStorage<T>(storageKey, storage, parser)\n      if (initialData.size > 0) {\n        begin()\n        initialData.forEach((storedItem) => {\n          validateJsonSerializable(parser, storedItem.data, `load`)\n          write({ type: `insert`, value: storedItem.data })\n        })\n        commit()\n      }\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      initialData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n\n      // Mark collection as ready after initial load\n      markReady()\n\n      // Listen for storage events from other tabs\n      const handleStorageEvent = (event: StorageEvent) => {\n        // Only respond to changes to our specific key and from our storage\n        if (event.key !== storageKey || event.storageArea !== storage) {\n          return\n        }\n\n        processStorageChanges()\n      }\n\n      // Add storage event listener for cross-tab sync\n      storageEventApi.addEventListener(`storage`, handleStorageEvent)\n\n      // Note: Cleanup is handled automatically by the collection when it's disposed\n    },\n\n    /**\n     * Get sync metadata - returns storage key information\n     * @returns Object containing storage key and storage type metadata\n     */\n    getSyncMetadata: () => ({\n      storageKey,\n      storageType:\n        storage === (typeof window !== `undefined` ? window.localStorage : null)\n          ? `localStorage`\n          : `custom`,\n    }),\n\n    // Manual trigger function for local updates\n    manualTrigger: processStorageChanges,\n\n    // Collection instance reference\n    collection,\n  }\n\n  /**\n   * Confirms mutations by writing them through the sync interface\n   * This moves mutations from optimistic to synced state\n   * @param mutations - Array of mutation objects to confirm\n   */\n  const confirmOperationsSync = (mutations: Array<any>) => {\n    if (!syncParams) {\n      // Sync not initialized yet, mutations will be handled on next sync\n      return\n    }\n\n    const { begin, write, commit } = syncParams\n\n    // Write the mutations through sync to confirm them\n    begin()\n    mutations.forEach((mutation: any) => {\n      write({\n        type: mutation.type,\n        value:\n          mutation.type === `delete` ? mutation.original : mutation.modified,\n      })\n    })\n    commit()\n  }\n\n  return {\n    ...syncConfig,\n    confirmOperationsSync,\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"local-storage.js","sources":["../../src/local-storage.ts"],"sourcesContent":["import {\n  InvalidStorageDataFormatError,\n  InvalidStorageObjectFormatError,\n  SerializationError,\n  StorageKeyRequiredError,\n} from \"./errors\"\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InferSchemaOutput,\n  InsertMutationFnParams,\n  PendingMutation,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"./types\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n/**\n * Storage API interface - subset of DOM Storage that we need\n */\nexport type StorageApi = Pick<Storage, `getItem` | `setItem` | `removeItem`>\n\n/**\n * Storage event API - subset of Window for 'storage' events only\n */\nexport type StorageEventApi = {\n  addEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n  removeEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n}\n\n/**\n * Internal storage format that includes version tracking\n */\ninterface StoredItem<T> {\n  versionKey: string\n  data: T\n}\n\nexport interface Parser {\n  parse: (data: string) => unknown\n  stringify: (data: unknown) => string\n}\n\n/**\n * Configuration interface for localStorage collection options\n * @template T - The type of items in the collection\n * @template TSchema - The schema type for validation\n * @template TKey - The type of the key returned by `getKey`\n */\nexport interface LocalStorageCollectionConfig<\n  T extends object = object,\n  TSchema extends StandardSchemaV1 = never,\n  TKey extends string | number = string | number,\n> extends BaseCollectionConfig<T, TKey, TSchema> {\n  /**\n   * The key to use for storing the collection data in localStorage/sessionStorage\n   */\n  storageKey: string\n\n  /**\n   * Storage API to use (defaults to window.localStorage)\n   * Can be any object that implements the Storage interface (e.g., sessionStorage)\n   */\n  storage?: StorageApi\n\n  /**\n   * Storage event API to use for cross-tab synchronization (defaults to window)\n   * Can be any object that implements addEventListener/removeEventListener for storage events\n   */\n  storageEventApi?: StorageEventApi\n\n  /**\n   * Parser to use for serializing and deserializing data to and from storage\n   * Defaults to JSON\n   */\n  parser?: Parser\n}\n\n/**\n * Type for the clear utility function\n */\nexport type ClearStorageFn = () => void\n\n/**\n * Type for the getStorageSize utility function\n */\nexport type GetStorageSizeFn = () => number\n\n/**\n * LocalStorage collection utilities type\n */\nexport interface LocalStorageCollectionUtils extends UtilsRecord {\n  clearStorage: ClearStorageFn\n  getStorageSize: GetStorageSizeFn\n  /**\n   * Accepts mutations from a transaction that belong to this collection and persists them to localStorage.\n   * This should be called in your transaction's mutationFn to persist local-storage data.\n   *\n   * @param transaction - The transaction containing mutations to accept\n   * @example\n   * const localSettings = createCollection(localStorageCollectionOptions({...}))\n   *\n   * const tx = createTransaction({\n   *   mutationFn: async ({ transaction }) => {\n   *     // Make API call first\n   *     await api.save(...)\n   *     // Then persist local-storage mutations after success\n   *     localSettings.utils.acceptMutations(transaction)\n   *   }\n   * })\n   */\n  acceptMutations: (transaction: {\n    mutations: Array<PendingMutation<Record<string, unknown>>>\n  }) => void\n}\n\n/**\n * Validates that a value can be JSON serialized\n * @param parser - The parser to use for serialization\n * @param value - The value to validate for JSON serialization\n * @param operation - The operation type being performed (for error messages)\n * @throws Error if the value cannot be JSON serialized\n */\nfunction validateJsonSerializable(\n  parser: Parser,\n  value: any,\n  operation: string\n): void {\n  try {\n    parser.stringify(value)\n  } catch (error) {\n    throw new SerializationError(\n      operation,\n      error instanceof Error ? error.message : String(error)\n    )\n  }\n}\n\n/**\n * Generate a UUID for version tracking\n * @returns A unique identifier string for tracking data versions\n */\nfunction generateUuid(): string {\n  return crypto.randomUUID()\n}\n\n/**\n * Encodes a key (string or number) into a storage-safe string format.\n * This prevents collisions between numeric and string keys by prefixing with type information.\n *\n * Examples:\n *   - number 1 → \"n:1\"\n *   - string \"1\" → \"s:1\"\n *   - string \"n:1\" → \"s:n:1\"\n *\n * @param key - The key to encode (string or number)\n * @returns Type-prefixed string that is safe for storage\n */\nfunction encodeStorageKey(key: string | number): string {\n  if (typeof key === `number`) {\n    return `n:${key}`\n  }\n  return `s:${key}`\n}\n\n/**\n * Decodes a storage key back to its original form.\n * This is the inverse of encodeStorageKey.\n *\n * @param encodedKey - The encoded key from storage\n * @returns The original key (string or number)\n */\nfunction decodeStorageKey(encodedKey: string): string | number {\n  if (encodedKey.startsWith(`n:`)) {\n    return Number(encodedKey.slice(2))\n  }\n  if (encodedKey.startsWith(`s:`)) {\n    return encodedKey.slice(2)\n  }\n  // Fallback for legacy data without encoding\n  return encodedKey\n}\n\n/**\n * Creates an in-memory storage implementation that mimics the StorageApi interface\n * Used as a fallback when localStorage is not available (e.g., server-side rendering)\n * @returns An object implementing the StorageApi interface using an in-memory Map\n */\nfunction createInMemoryStorage(): StorageApi {\n  const storage = new Map<string, string>()\n\n  return {\n    getItem(key: string): string | null {\n      return storage.get(key) ?? null\n    },\n    setItem(key: string, value: string): void {\n      storage.set(key, value)\n    },\n    removeItem(key: string): void {\n      storage.delete(key)\n    },\n  }\n}\n\n/**\n * Creates a no-op storage event API for environments without window (e.g., server-side)\n * This provides the required interface but doesn't actually listen to any events\n * since cross-tab synchronization is not possible in server environments\n * @returns An object implementing the StorageEventApi interface with no-op methods\n */\nfunction createNoOpStorageEventApi(): StorageEventApi {\n  return {\n    addEventListener: () => {\n      // No-op: cannot listen to storage events without window\n    },\n    removeEventListener: () => {\n      // No-op: cannot remove listeners without window\n    },\n  }\n}\n\n/**\n * Creates localStorage collection options for use with a standard Collection\n *\n * This function creates a collection that persists data to localStorage/sessionStorage\n * and synchronizes changes across browser tabs using storage events.\n *\n * **Fallback Behavior:**\n *\n * When localStorage is not available (e.g., in server-side rendering environments),\n * this function automatically falls back to an in-memory storage implementation.\n * This prevents errors during module initialization and allows the collection to\n * work in any environment, though data will not persist across page reloads or\n * be shared across tabs when using the in-memory fallback.\n *\n * **Using with Manual Transactions:**\n *\n * For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`\n * to persist changes made during `tx.mutate()`. This is necessary because local-storage collections\n * don't participate in the standard mutation handler flow for manual transactions.\n *\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @param config - Configuration options for the localStorage collection\n * @returns Collection options with utilities including clearStorage, getStorageSize, and acceptMutations\n *\n * @example\n * // Basic localStorage collection\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with custom storage\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     storage: window.sessionStorage, // Use sessionStorage instead\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with mutation handlers\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       console.log('Item inserted:', transaction.mutations[0].modified)\n *     },\n *   })\n * )\n *\n * @example\n * // Using with manual transactions\n * const localSettings = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'user-settings',\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Use settings data in API call\n *     const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)\n *     await api.updateUserProfile({ settings: settingsMutations[0]?.modified })\n *\n *     // Persist local-storage mutations after API success\n *     localSettings.utils.acceptMutations(transaction)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   localSettings.insert({ id: 'theme', value: 'dark' })\n *   apiCollection.insert({ id: 2, data: 'profile data' })\n * })\n *\n * await tx.commit()\n */\n\n// Overload for when schema is provided\nexport function localStorageCollectionOptions<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {\n    schema: T\n  }\n): CollectionConfig<\n  InferSchemaOutput<T>,\n  TKey,\n  T,\n  LocalStorageCollectionUtils\n> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema: T\n}\n\n// Overload for when no schema is provided\n// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config\nexport function localStorageCollectionOptions<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<T, never, TKey> & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey, never, LocalStorageCollectionUtils> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: never // no schema in the result\n}\n\nexport function localStorageCollectionOptions(\n  config: LocalStorageCollectionConfig<any, any, string | number>\n): Omit<\n  CollectionConfig<any, string | number, any, LocalStorageCollectionUtils>,\n  `id`\n> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: StandardSchemaV1\n} {\n  // Validate required parameters\n  if (!config.storageKey) {\n    throw new StorageKeyRequiredError()\n  }\n\n  // Default to window.localStorage if no storage is provided\n  // Fall back to in-memory storage if localStorage is not available (e.g., server-side rendering)\n  const storage =\n    config.storage ||\n    (typeof window !== `undefined` ? window.localStorage : null) ||\n    createInMemoryStorage()\n\n  // Default to window for storage events if not provided\n  // Fall back to no-op storage event API if window is not available (e.g., server-side rendering)\n  const storageEventApi =\n    config.storageEventApi ||\n    (typeof window !== `undefined` ? window : null) ||\n    createNoOpStorageEventApi()\n\n  // Default to JSON parser if no parser is provided\n  const parser = config.parser || JSON\n\n  // Track the last known state to detect changes\n  const lastKnownData = new Map<string | number, StoredItem<any>>()\n\n  // Create the sync configuration\n  const sync = createLocalStorageSync<any>(\n    config.storageKey,\n    storage,\n    storageEventApi,\n    parser,\n    config.getKey,\n    lastKnownData\n  )\n\n  /**\n   * Save data to storage\n   * @param dataMap - Map of items with version tracking to save to storage\n   */\n  const saveToStorage = (\n    dataMap: Map<string | number, StoredItem<any>>\n  ): void => {\n    try {\n      // Convert Map to object format for storage\n      const objectData: Record<string, StoredItem<any>> = {}\n      dataMap.forEach((storedItem, key) => {\n        objectData[encodeStorageKey(key)] = storedItem\n      })\n      const serialized = parser.stringify(objectData)\n      storage.setItem(config.storageKey, serialized)\n    } catch (error) {\n      console.error(\n        `[LocalStorageCollection] Error saving data to storage key \"${config.storageKey}\":`,\n        error\n      )\n      throw error\n    }\n  }\n\n  /**\n   * Removes all collection data from the configured storage\n   */\n  const clearStorage: ClearStorageFn = (): void => {\n    storage.removeItem(config.storageKey)\n  }\n\n  /**\n   * Get the size of the stored data in bytes (approximate)\n   * @returns The approximate size in bytes of the stored collection data\n   */\n  const getStorageSize: GetStorageSizeFn = (): number => {\n    const data = storage.getItem(config.storageKey)\n    return data ? new Blob([data]).size : 0\n  }\n\n  /*\n   * Create wrapper handlers for direct persistence operations that perform actual storage operations\n   * Wraps the user's onInsert handler to also save changes to localStorage\n   */\n  const wrappedOnInsert = async (params: InsertMutationFnParams<any>) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(parser, mutation.modified, `insert`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onInsert) {\n      handlerResult = (await config.onInsert(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Add new items with version keys\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      lastKnownData.set(mutation.key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  const wrappedOnUpdate = async (params: UpdateMutationFnParams<any>) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(parser, mutation.modified, `update`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onUpdate) {\n      handlerResult = (await config.onUpdate(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Update items with new version keys\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      lastKnownData.set(mutation.key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  const wrappedOnDelete = async (params: DeleteMutationFnParams<any>) => {\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onDelete) {\n      handlerResult = (await config.onDelete(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Remove items\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      lastKnownData.delete(mutation.key)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  // Extract standard Collection config properties\n  const {\n    storageKey: _storageKey,\n    storage: _storage,\n    storageEventApi: _storageEventApi,\n    onInsert: _onInsert,\n    onUpdate: _onUpdate,\n    onDelete: _onDelete,\n    id,\n    ...restConfig\n  } = config\n\n  // Default id to a pattern based on storage key if not provided\n  const collectionId = id ?? `local-collection:${config.storageKey}`\n\n  /**\n   * Accepts mutations from a transaction that belong to this collection and persists them to storage\n   */\n  const acceptMutations = (transaction: {\n    mutations: Array<PendingMutation<Record<string, unknown>>>\n  }) => {\n    // Filter mutations that belong to this collection\n    // Use collection ID for filtering if collection reference isn't available yet\n    const collectionMutations = transaction.mutations.filter((m) => {\n      // Try to match by collection reference first\n      if (sync.collection && m.collection === sync.collection) {\n        return true\n      }\n      // Fall back to matching by collection ID\n      return m.collection.id === collectionId\n    })\n\n    if (collectionMutations.length === 0) {\n      return\n    }\n\n    // Validate all mutations can be serialized before modifying storage\n    for (const mutation of collectionMutations) {\n      switch (mutation.type) {\n        case `insert`:\n        case `update`:\n          validateJsonSerializable(parser, mutation.modified, mutation.type)\n          break\n        case `delete`:\n          validateJsonSerializable(parser, mutation.original, mutation.type)\n          break\n      }\n    }\n\n    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Apply each mutation\n    for (const mutation of collectionMutations) {\n      // Use the engine's pre-computed key to avoid key derivation issues\n      switch (mutation.type) {\n        case `insert`:\n        case `update`: {\n          const storedItem: StoredItem<Record<string, unknown>> = {\n            versionKey: generateUuid(),\n            data: mutation.modified,\n          }\n          lastKnownData.set(mutation.key, storedItem)\n          break\n        }\n        case `delete`: {\n          lastKnownData.delete(mutation.key)\n          break\n        }\n      }\n    }\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm the mutations in the collection to move them from optimistic to synced state\n    // This writes them through the sync interface to make them \"synced\" instead of \"optimistic\"\n    sync.confirmOperationsSync(collectionMutations)\n  }\n\n  return {\n    ...restConfig,\n    id: collectionId,\n    sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      clearStorage,\n      getStorageSize,\n      acceptMutations,\n    },\n  }\n}\n\n/**\n * Load data from storage and return as a Map\n * @param parser - The parser to use for deserializing the data\n * @param storageKey - The key used to store data in the storage API\n * @param storage - The storage API to load from (localStorage, sessionStorage, etc.)\n * @returns Map of stored items with version tracking, or empty Map if loading fails\n */\nfunction loadFromStorage<T extends object>(\n  storageKey: string,\n  storage: StorageApi,\n  parser: Parser\n): Map<string | number, StoredItem<T>> {\n  try {\n    const rawData = storage.getItem(storageKey)\n    if (!rawData) {\n      return new Map()\n    }\n\n    const parsed = parser.parse(rawData)\n    const dataMap = new Map<string | number, StoredItem<T>>()\n\n    // Handle object format where keys map to StoredItem values\n    if (\n      typeof parsed === `object` &&\n      parsed !== null &&\n      !Array.isArray(parsed)\n    ) {\n      Object.entries(parsed).forEach(([encodedKey, value]) => {\n        // Runtime check to ensure the value has the expected StoredItem structure\n        if (\n          value &&\n          typeof value === `object` &&\n          `versionKey` in value &&\n          `data` in value\n        ) {\n          const storedItem = value as StoredItem<T>\n          const decodedKey = decodeStorageKey(encodedKey)\n          dataMap.set(decodedKey, storedItem)\n        } else {\n          throw new InvalidStorageDataFormatError(storageKey, encodedKey)\n        }\n      })\n    } else {\n      throw new InvalidStorageObjectFormatError(storageKey)\n    }\n\n    return dataMap\n  } catch (error) {\n    console.warn(\n      `[LocalStorageCollection] Error loading data from storage key \"${storageKey}\":`,\n      error\n    )\n    return new Map()\n  }\n}\n\n/**\n * Internal function to create localStorage sync configuration\n * Creates a sync configuration that handles localStorage persistence and cross-tab synchronization\n * @param storageKey - The key used for storing data in localStorage\n * @param storage - The storage API to use (localStorage, sessionStorage, etc.)\n * @param storageEventApi - The event API for listening to storage changes\n * @param getKey - Function to extract the key from an item\n * @param lastKnownData - Map tracking the last known state for change detection\n * @returns Sync configuration with manual trigger capability\n */\nfunction createLocalStorageSync<T extends object>(\n  storageKey: string,\n  storage: StorageApi,\n  storageEventApi: StorageEventApi,\n  parser: Parser,\n  _getKey: (item: T) => string | number,\n  lastKnownData: Map<string | number, StoredItem<T>>\n): SyncConfig<T> & {\n  manualTrigger?: () => void\n  collection: any\n  confirmOperationsSync: (mutations: Array<any>) => void\n} {\n  let syncParams: Parameters<SyncConfig<T>[`sync`]>[0] | null = null\n  let collection: any = null\n\n  /**\n   * Compare two Maps to find differences using version keys\n   * @param oldData - The previous state of stored items\n   * @param newData - The current state of stored items\n   * @returns Array of changes with type, key, and value information\n   */\n  const findChanges = (\n    oldData: Map<string | number, StoredItem<T>>,\n    newData: Map<string | number, StoredItem<T>>\n  ): Array<{\n    type: `insert` | `update` | `delete`\n    key: string | number\n    value?: T\n  }> => {\n    const changes: Array<{\n      type: `insert` | `update` | `delete`\n      key: string | number\n      value?: T\n    }> = []\n\n    // Check for deletions and updates\n    oldData.forEach((oldStoredItem, key) => {\n      const newStoredItem = newData.get(key)\n      if (!newStoredItem) {\n        changes.push({ type: `delete`, key, value: oldStoredItem.data })\n      } else if (oldStoredItem.versionKey !== newStoredItem.versionKey) {\n        changes.push({ type: `update`, key, value: newStoredItem.data })\n      }\n    })\n\n    // Check for insertions\n    newData.forEach((newStoredItem, key) => {\n      if (!oldData.has(key)) {\n        changes.push({ type: `insert`, key, value: newStoredItem.data })\n      }\n    })\n\n    return changes\n  }\n\n  /**\n   * Process storage changes and update collection\n   * Loads new data from storage, compares with last known state, and applies changes\n   */\n  const processStorageChanges = () => {\n    if (!syncParams) return\n\n    const { begin, write, commit } = syncParams\n\n    // Load the new data\n    const newData = loadFromStorage<T>(storageKey, storage, parser)\n\n    // Find the specific changes\n    const changes = findChanges(lastKnownData, newData)\n\n    if (changes.length > 0) {\n      begin()\n      changes.forEach(({ type, value }) => {\n        if (value) {\n          validateJsonSerializable(parser, value, type)\n          write({ type, value })\n        }\n      })\n      commit()\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      newData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n    }\n  }\n\n  const syncConfig: SyncConfig<T> & {\n    manualTrigger?: () => void\n    collection: any\n  } = {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady } = params\n\n      // Store sync params and collection for later use\n      syncParams = params\n      collection = params.collection\n\n      // Initial load\n      const initialData = loadFromStorage<T>(storageKey, storage, parser)\n      if (initialData.size > 0) {\n        begin()\n        initialData.forEach((storedItem) => {\n          validateJsonSerializable(parser, storedItem.data, `load`)\n          write({ type: `insert`, value: storedItem.data })\n        })\n        commit()\n      }\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      initialData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n\n      // Mark collection as ready after initial load\n      markReady()\n\n      // Listen for storage events from other tabs\n      const handleStorageEvent = (event: StorageEvent) => {\n        // Only respond to changes to our specific key and from our storage\n        if (event.key !== storageKey || event.storageArea !== storage) {\n          return\n        }\n\n        processStorageChanges()\n      }\n\n      // Add storage event listener for cross-tab sync\n      storageEventApi.addEventListener(`storage`, handleStorageEvent)\n\n      // Note: Cleanup is handled automatically by the collection when it's disposed\n    },\n\n    /**\n     * Get sync metadata - returns storage key information\n     * @returns Object containing storage key and storage type metadata\n     */\n    getSyncMetadata: () => ({\n      storageKey,\n      storageType:\n        storage === (typeof window !== `undefined` ? window.localStorage : null)\n          ? `localStorage`\n          : `custom`,\n    }),\n\n    // Manual trigger function for local updates\n    manualTrigger: processStorageChanges,\n\n    // Collection instance reference\n    collection,\n  }\n\n  /**\n   * Confirms mutations by writing them through the sync interface\n   * This moves mutations from optimistic to synced state\n   * @param mutations - Array of mutation objects to confirm\n   */\n  const confirmOperationsSync = (mutations: Array<any>) => {\n    if (!syncParams) {\n      // Sync not initialized yet, mutations will be handled on next sync\n      return\n    }\n\n    const { begin, write, commit } = syncParams\n\n    // Write the mutations through sync to confirm them\n    begin()\n    mutations.forEach((mutation: any) => {\n      write({\n        type: mutation.type,\n        value:\n          mutation.type === `delete` ? mutation.original : mutation.modified,\n      })\n    })\n    commit()\n  }\n\n  return {\n    ...syncConfig,\n    confirmOperationsSync,\n  }\n}\n"],"names":[],"mappings":"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"}