@tanstack/db 0.4.20 → 0.5.0

package/dist/esm/utils/index-optimization.js

@@ -1,9 +1,13 @@
 import { DEFAULT_COMPARE_OPTIONS } from "../utils.js";
 import { ReverseIndex } from "../indexes/reverse-index.js";
-function findIndexForField(indexes, fieldPath, compareOptions = DEFAULT_COMPARE_OPTIONS) {
-  for (const index of indexes.values()) {
-    if (index.matchesField(fieldPath) && index.matchesCompareOptions(compareOptions)) {
-      if (!index.matchesDirection(compareOptions.direction)) {
+function findIndexForField(collection, fieldPath, compareOptions) {
+  const compareOpts = compareOptions ?? {
+    ...DEFAULT_COMPARE_OPTIONS,
+    ...collection.compareOptions
+  };
+  for (const index of collection.indexes.values()) {
+    if (index.matchesField(fieldPath) && index.matchesCompareOptions(compareOpts)) {
+      if (!index.matchesDirection(compareOpts.direction)) {
         return new ReverseIndex(index);
       }
       return index;
@@ -35,10 +39,10 @@ function unionSets(sets) {
   }
   return result;
 }
-function optimizeExpressionWithIndexes(expression, indexes) {
-  return optimizeQueryRecursive(expression, indexes);
+function optimizeExpressionWithIndexes(expression, collection) {
+  return optimizeQueryRecursive(expression, collection);
 }
-function optimizeQueryRecursive(expression, indexes) {
+function optimizeQueryRecursive(expression, collection) {
   if (expression.type === `func`) {
     switch (expression.name) {
       case `eq`:
@@ -46,18 +50,18 @@ function optimizeQueryRecursive(expression, indexes) {
       case `gte`:
       case `lt`:
       case `lte`:
-        return optimizeSimpleComparison(expression, indexes);
+        return optimizeSimpleComparison(expression, collection);
       case `and`:
-        return optimizeAndExpression(expression, indexes);
+        return optimizeAndExpression(expression, collection);
       case `or`:
-        return optimizeOrExpression(expression, indexes);
+        return optimizeOrExpression(expression, collection);
       case `in`:
-        return optimizeInArrayExpression(expression, indexes);
+        return optimizeInArrayExpression(expression, collection);
     }
   }
   return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
 }
-function optimizeCompoundRangeQuery(expression, indexes) {
+function optimizeCompoundRangeQuery(expression, collection) {
   if (expression.type !== `func` || expression.args.length < 2) {
     return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
   }
@@ -107,7 +111,7 @@ function optimizeCompoundRangeQuery(expression, indexes) {
   for (const [fieldKey, operations] of fieldOperations) {
     if (operations.length >= 2) {
       const fieldPath = fieldKey.split(`.`);
-      const index = findIndexForField(indexes, fieldPath);
+      const index = findIndexForField(collection, fieldPath);
       if (index && index.supports(`gt`) && index.supports(`lt`)) {
         let from = void 0;
         let to = void 0;
@@ -153,7 +157,7 @@ function optimizeCompoundRangeQuery(expression, indexes) {
   }
   return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
 }
-function optimizeSimpleComparison(expression, indexes) {
+function optimizeSimpleComparison(expression, collection) {
   if (expression.type !== `func` || expression.args.length !== 2) {
     return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
   }
@@ -185,7 +189,7 @@ function optimizeSimpleComparison(expression, indexes) {
   }
   if (fieldArg && valueArg) {
     const fieldPath = fieldArg.path;
-    const index = findIndexForField(indexes, fieldPath);
+    const index = findIndexForField(collection, fieldPath);
     if (index) {
       const queryValue = valueArg.value;
       const indexOperation = operation;
@@ -198,17 +202,17 @@ function optimizeSimpleComparison(expression, indexes) {
   }
   return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
 }
-function optimizeAndExpression(expression, indexes) {
+function optimizeAndExpression(expression, collection) {
   if (expression.type !== `func` || expression.args.length < 2) {
     return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
   }
-  const compoundRangeResult = optimizeCompoundRangeQuery(expression, indexes);
+  const compoundRangeResult = optimizeCompoundRangeQuery(expression, collection);
   if (compoundRangeResult.canOptimize) {
     return compoundRangeResult;
   }
   const results = [];
   for (const arg of expression.args) {
-    const result = optimizeQueryRecursive(arg, indexes);
+    const result = optimizeQueryRecursive(arg, collection);
     if (result.canOptimize) {
       results.push(result);
     }
@@ -220,13 +224,13 @@ function optimizeAndExpression(expression, indexes) {
   }
   return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
 }
-function optimizeOrExpression(expression, indexes) {
+function optimizeOrExpression(expression, collection) {
   if (expression.type !== `func` || expression.args.length < 2) {
     return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
   }
   const results = [];
   for (const arg of expression.args) {
-    const result = optimizeQueryRecursive(arg, indexes);
+    const result = optimizeQueryRecursive(arg, collection);
     if (result.canOptimize) {
       results.push(result);
     }
@@ -238,7 +242,7 @@ function optimizeOrExpression(expression, indexes) {
   }
   return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
 }
-function optimizeInArrayExpression(expression, indexes) {
+function optimizeInArrayExpression(expression, collection) {
   if (expression.type !== `func` || expression.args.length !== 2) {
     return { canOptimize: false, matchingKeys: /* @__PURE__ */ new Set() };
   }
@@ -247,7 +251,7 @@ function optimizeInArrayExpression(expression, indexes) {
   if (fieldArg.type === `ref` && arrayArg.type === `val` && Array.isArray(arrayArg.value)) {
     const fieldPath = fieldArg.path;
     const values = arrayArg.value;
-    const index = findIndexForField(indexes, fieldPath);
+    const index = findIndexForField(collection, fieldPath);
     if (index) {
       if (index.supports(`in`)) {
         const matchingKeys = index.lookup(`in`, values);

package/dist/esm/utils/index-optimization.js.map

@@ -1 +1 @@
-{"version":3,"file":"index-optimization.js","sources":["../../../src/utils/index-optimization.ts"],"sourcesContent":["/**\n * # Index-Based Query Optimization\n *\n * This module provides utilities for optimizing query expressions by leveraging\n * available indexes to quickly find matching keys instead of scanning all data.\n *\n * This is different from the query structure optimizer in `query/optimizer.ts`\n * which rewrites query IR structure. This module focuses on using indexes during\n * query execution to speed up data filtering.\n *\n * ## Key Features:\n * - Uses indexes to find matching keys for WHERE conditions\n * - Supports AND/OR logic with set operations\n * - Handles range queries (eq, gt, gte, lt, lte)\n * - Optimizes IN array expressions\n */\n\nimport { DEFAULT_COMPARE_OPTIONS } from \"../utils.js\"\nimport { ReverseIndex } from \"../indexes/reverse-index.js\"\nimport type { CompareOptions } from \"../query/builder/types.js\"\nimport type {\n  BaseIndex,\n  IndexInterface,\n  IndexOperation,\n} from \"../indexes/base-index.js\"\nimport type { BasicExpression } from \"../query/ir.js\"\n\n/**\n * Result of index-based query optimization\n */\nexport interface OptimizationResult<TKey> {\n  canOptimize: boolean\n  matchingKeys: Set<TKey>\n}\n\n/**\n * Finds an index that matches a given field path\n */\nexport function findIndexForField<TKey extends string | number>(\n  indexes: Map<number, IndexInterface<TKey>>,\n  fieldPath: Array<string>,\n  compareOptions: CompareOptions = DEFAULT_COMPARE_OPTIONS\n): IndexInterface<TKey> | undefined {\n  for (const index of indexes.values()) {\n    if (\n      index.matchesField(fieldPath) &&\n      index.matchesCompareOptions(compareOptions)\n    ) {\n      if (!index.matchesDirection(compareOptions.direction)) {\n        return new ReverseIndex(index)\n      }\n      return index\n    }\n  }\n  return undefined\n}\n\n/**\n * Intersects multiple sets (AND logic)\n */\nexport function intersectSets<T>(sets: Array<Set<T>>): Set<T> {\n  if (sets.length === 0) return new Set()\n  if (sets.length === 1) return new Set(sets[0])\n\n  let result = new Set(sets[0])\n  for (let i = 1; i < sets.length; i++) {\n    const newResult = new Set<T>()\n    for (const item of result) {\n      if (sets[i]!.has(item)) {\n        newResult.add(item)\n      }\n    }\n    result = newResult\n  }\n  return result\n}\n\n/**\n * Unions multiple sets (OR logic)\n */\nexport function unionSets<T>(sets: Array<Set<T>>): Set<T> {\n  const result = new Set<T>()\n  for (const set of sets) {\n    for (const item of set) {\n      result.add(item)\n    }\n  }\n  return result\n}\n\n/**\n * Optimizes a query expression using available indexes to find matching keys\n */\nexport function optimizeExpressionWithIndexes<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): OptimizationResult<TKey> {\n  return optimizeQueryRecursive(expression, indexes)\n}\n\n/**\n * Recursively optimizes query expressions\n */\nfunction optimizeQueryRecursive<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): OptimizationResult<TKey> {\n  if (expression.type === `func`) {\n    switch (expression.name) {\n      case `eq`:\n      case `gt`:\n      case `gte`:\n      case `lt`:\n      case `lte`:\n        return optimizeSimpleComparison(expression, indexes)\n\n      case `and`:\n        return optimizeAndExpression(expression, indexes)\n\n      case `or`:\n        return optimizeOrExpression(expression, indexes)\n\n      case `in`:\n        return optimizeInArrayExpression(expression, indexes)\n    }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if an expression can be optimized\n */\nexport function canOptimizeExpression<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): boolean {\n  if (expression.type === `func`) {\n    switch (expression.name) {\n      case `eq`:\n      case `gt`:\n      case `gte`:\n      case `lt`:\n      case `lte`:\n        return canOptimizeSimpleComparison(expression, indexes)\n\n      case `and`:\n        return canOptimizeAndExpression(expression, indexes)\n\n      case `or`:\n        return canOptimizeOrExpression(expression, indexes)\n\n      case `in`:\n        return canOptimizeInArrayExpression(expression, indexes)\n    }\n  }\n\n  return false\n}\n\n/**\n * Optimizes compound range queries on the same field\n * Example: WHERE age > 5 AND age < 10\n */\nfunction optimizeCompoundRangeQuery<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  // Group range operations by field\n  const fieldOperations = new Map<\n    string,\n    Array<{\n      operation: `gt` | `gte` | `lt` | `lte`\n      value: any\n    }>\n  >()\n\n  // Collect all range operations from AND arguments\n  for (const arg of expression.args) {\n    if (arg.type === `func` && [`gt`, `gte`, `lt`, `lte`].includes(arg.name)) {\n      const rangeOp = arg as any\n      if (rangeOp.args.length === 2) {\n        const leftArg = rangeOp.args[0]!\n        const rightArg = rangeOp.args[1]!\n\n        // Check both directions: field op value AND value op field\n        let fieldArg: BasicExpression | null = null\n        let valueArg: BasicExpression | null = null\n        let operation = rangeOp.name as `gt` | `gte` | `lt` | `lte`\n\n        if (leftArg.type === `ref` && rightArg.type === `val`) {\n          // field op value\n          fieldArg = leftArg\n          valueArg = rightArg\n        } else if (leftArg.type === `val` && rightArg.type === `ref`) {\n          // value op field - need to flip the operation\n          fieldArg = rightArg\n          valueArg = leftArg\n\n          // Flip the operation for reverse comparison\n          switch (operation) {\n            case `gt`:\n              operation = `lt`\n              break\n            case `gte`:\n              operation = `lte`\n              break\n            case `lt`:\n              operation = `gt`\n              break\n            case `lte`:\n              operation = `gte`\n              break\n          }\n        }\n\n        if (fieldArg && valueArg) {\n          const fieldPath = (fieldArg as any).path\n          const fieldKey = fieldPath.join(`.`)\n          const value = (valueArg as any).value\n\n          if (!fieldOperations.has(fieldKey)) {\n            fieldOperations.set(fieldKey, [])\n          }\n          fieldOperations.get(fieldKey)!.push({ operation, value })\n        }\n      }\n    }\n  }\n\n  // Check if we have multiple operations on the same field\n  for (const [fieldKey, operations] of fieldOperations) {\n    if (operations.length >= 2) {\n      const fieldPath = fieldKey.split(`.`)\n      const index = findIndexForField(indexes, fieldPath)\n\n      if (index && index.supports(`gt`) && index.supports(`lt`)) {\n        // Build range query options\n        let from: any = undefined\n        let to: any = undefined\n        let fromInclusive = true\n        let toInclusive = true\n\n        for (const { operation, value } of operations) {\n          switch (operation) {\n            case `gt`:\n              if (from === undefined || value > from) {\n                from = value\n                fromInclusive = false\n              }\n              break\n            case `gte`:\n              if (from === undefined || value > from) {\n                from = value\n                fromInclusive = true\n              }\n              break\n            case `lt`:\n              if (to === undefined || value < to) {\n                to = value\n                toInclusive = false\n              }\n              break\n            case `lte`:\n              if (to === undefined || value < to) {\n                to = value\n                toInclusive = true\n              }\n              break\n          }\n        }\n\n        const matchingKeys = (index as any).rangeQuery({\n          from,\n          to,\n          fromInclusive,\n          toInclusive,\n        })\n\n        return { canOptimize: true, matchingKeys }\n      }\n    }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Optimizes simple comparison expressions (eq, gt, gte, lt, lte)\n */\nfunction optimizeSimpleComparison<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length !== 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  const leftArg = expression.args[0]!\n  const rightArg = expression.args[1]!\n\n  // Check both directions: field op value AND value op field\n  let fieldArg: BasicExpression | null = null\n  let valueArg: BasicExpression | null = null\n  let operation = expression.name as `eq` | `gt` | `gte` | `lt` | `lte`\n\n  if (leftArg.type === `ref` && rightArg.type === `val`) {\n    // field op value\n    fieldArg = leftArg\n    valueArg = rightArg\n  } else if (leftArg.type === `val` && rightArg.type === `ref`) {\n    // value op field - need to flip the operation\n    fieldArg = rightArg\n    valueArg = leftArg\n\n    // Flip the operation for reverse comparison\n    switch (operation) {\n      case `gt`:\n        operation = `lt`\n        break\n      case `gte`:\n        operation = `lte`\n        break\n      case `lt`:\n        operation = `gt`\n        break\n      case `lte`:\n        operation = `gte`\n        break\n      // eq stays the same\n    }\n  }\n\n  if (fieldArg && valueArg) {\n    const fieldPath = (fieldArg as any).path\n    const index = findIndexForField(indexes, fieldPath)\n\n    if (index) {\n      const queryValue = (valueArg as any).value\n\n      // Map operation to IndexOperation enum\n      const indexOperation = operation as IndexOperation\n\n      // Check if the index supports this operation\n      if (!index.supports(indexOperation)) {\n        return { canOptimize: false, matchingKeys: new Set() }\n      }\n\n      const matchingKeys = index.lookup(indexOperation, queryValue)\n      return { canOptimize: true, matchingKeys }\n    }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if a simple comparison can be optimized\n */\nfunction canOptimizeSimpleComparison<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): boolean {\n  if (expression.type !== `func` || expression.args.length !== 2) {\n    return false\n  }\n\n  const leftArg = expression.args[0]!\n  const rightArg = expression.args[1]!\n\n  // Check both directions: field op value AND value op field\n  let fieldPath: Array<string> | null = null\n\n  if (leftArg.type === `ref` && rightArg.type === `val`) {\n    fieldPath = (leftArg as any).path\n  } else if (leftArg.type === `val` && rightArg.type === `ref`) {\n    fieldPath = (rightArg as any).path\n  }\n\n  if (fieldPath) {\n    const index = findIndexForField(indexes, fieldPath)\n    return index !== undefined\n  }\n\n  return false\n}\n\n/**\n * Optimizes AND expressions\n */\nfunction optimizeAndExpression<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  // First, try to optimize compound range queries on the same field\n  const compoundRangeResult = optimizeCompoundRangeQuery(expression, indexes)\n  if (compoundRangeResult.canOptimize) {\n    return compoundRangeResult\n  }\n\n  const results: Array<OptimizationResult<TKey>> = []\n\n  // Try to optimize each part, keep the optimizable ones\n  for (const arg of expression.args) {\n    const result = optimizeQueryRecursive(arg, indexes)\n    if (result.canOptimize) {\n      results.push(result)\n    }\n  }\n\n  if (results.length > 0) {\n    // Use intersectSets utility for AND logic\n    const allMatchingSets = results.map((r) => r.matchingKeys)\n    const intersectedKeys = intersectSets(allMatchingSets)\n    return { canOptimize: true, matchingKeys: intersectedKeys }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if an AND expression can be optimized\n */\nfunction canOptimizeAndExpression<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): boolean {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return false\n  }\n\n  // If any argument can be optimized, we can gain some speedup\n  return expression.args.some((arg) => canOptimizeExpression(arg, indexes))\n}\n\n/**\n * Optimizes OR expressions\n */\nfunction optimizeOrExpression<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  const results: Array<OptimizationResult<TKey>> = []\n\n  // Try to optimize each part, keep the optimizable ones\n  for (const arg of expression.args) {\n    const result = optimizeQueryRecursive(arg, indexes)\n    if (result.canOptimize) {\n      results.push(result)\n    }\n  }\n\n  if (results.length > 0) {\n    // Use unionSets utility for OR logic\n    const allMatchingSets = results.map((r) => r.matchingKeys)\n    const unionedKeys = unionSets(allMatchingSets)\n    return { canOptimize: true, matchingKeys: unionedKeys }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if an OR expression can be optimized\n */\nfunction canOptimizeOrExpression<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): boolean {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return false\n  }\n\n  // If any argument can be optimized, we can gain some speedup\n  return expression.args.some((arg) => canOptimizeExpression(arg, indexes))\n}\n\n/**\n * Optimizes IN array expressions\n */\nfunction optimizeInArrayExpression<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length !== 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  const fieldArg = expression.args[0]!\n  const arrayArg = expression.args[1]!\n\n  if (\n    fieldArg.type === `ref` &&\n    arrayArg.type === `val` &&\n    Array.isArray((arrayArg as any).value)\n  ) {\n    const fieldPath = (fieldArg as any).path\n    const values = (arrayArg as any).value\n    const index = findIndexForField(indexes, fieldPath)\n\n    if (index) {\n      // Check if the index supports IN operation\n      if (index.supports(`in`)) {\n        const matchingKeys = index.lookup(`in`, values)\n        return { canOptimize: true, matchingKeys }\n      } else if (index.supports(`eq`)) {\n        // Fallback to multiple equality lookups\n        const matchingKeys = new Set<TKey>()\n        for (const value of values) {\n          const keysForValue = index.lookup(`eq`, value)\n          for (const key of keysForValue) {\n            matchingKeys.add(key)\n          }\n        }\n        return { canOptimize: true, matchingKeys }\n      }\n    }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if an IN array expression can be optimized\n */\nfunction canOptimizeInArrayExpression<TKey extends string | number>(\n  expression: BasicExpression,\n  indexes: Map<number, BaseIndex<TKey>>\n): boolean {\n  if (expression.type !== `func` || expression.args.length !== 2) {\n    return false\n  }\n\n  const fieldArg = expression.args[0]!\n  const arrayArg = expression.args[1]!\n\n  if (\n    fieldArg.type === `ref` &&\n    arrayArg.type === `val` &&\n    Array.isArray((arrayArg as any).value)\n  ) {\n    const fieldPath = (fieldArg as any).path\n    const index = findIndexForField(indexes, fieldPath)\n    return index !== undefined\n  }\n\n  return false\n}\n"],"names":[],"mappings":";;AAsCO,SAAS,kBACd,SACA,WACA,iBAAiC,yBACC;AAClC,aAAW,SAAS,QAAQ,UAAU;AACpC,QACE,MAAM,aAAa,SAAS,KAC5B,MAAM,sBAAsB,cAAc,GAC1C;AACA,UAAI,CAAC,MAAM,iBAAiB,eAAe,SAAS,GAAG;AACrD,eAAO,IAAI,aAAa,KAAK;AAAA,MAC/B;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAKO,SAAS,cAAiB,MAA6B;AAC5D,MAAI,KAAK,WAAW,EAAG,4BAAW,IAAA;AAClC,MAAI,KAAK,WAAW,EAAG,QAAO,IAAI,IAAI,KAAK,CAAC,CAAC;AAE7C,MAAI,SAAS,IAAI,IAAI,KAAK,CAAC,CAAC;AAC5B,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,UAAM,gCAAgB,IAAA;AACtB,eAAW,QAAQ,QAAQ;AACzB,UAAI,KAAK,CAAC,EAAG,IAAI,IAAI,GAAG;AACtB,kBAAU,IAAI,IAAI;AAAA,MACpB;AAAA,IACF;AACA,aAAS;AAAA,EACX;AACA,SAAO;AACT;AAKO,SAAS,UAAa,MAA6B;AACxD,QAAM,6BAAa,IAAA;AACnB,aAAW,OAAO,MAAM;AACtB,eAAW,QAAQ,KAAK;AACtB,aAAO,IAAI,IAAI;AAAA,IACjB;AAAA,EACF;AACA,SAAO;AACT;AAKO,SAAS,8BACd,YACA,SAC0B;AAC1B,SAAO,uBAAuB,YAAY,OAAO;AACnD;AAKA,SAAS,uBACP,YACA,SAC0B;AAC1B,MAAI,WAAW,SAAS,QAAQ;AAC9B,YAAQ,WAAW,MAAA;AAAA,MACjB,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AACH,eAAO,yBAAyB,YAAY,OAAO;AAAA,MAErD,KAAK;AACH,eAAO,sBAAsB,YAAY,OAAO;AAAA,MAElD,KAAK;AACH,eAAO,qBAAqB,YAAY,OAAO;AAAA,MAEjD,KAAK;AACH,eAAO,0BAA0B,YAAY,OAAO;AAAA,IAAA;AAAA,EAE1D;AAEA,SAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AACrD;AAoCA,SAAS,2BACP,YACA,SAC0B;AAC1B,MAAI,WAAW,SAAS,UAAU,WAAW,KAAK,SAAS,GAAG;AAC5D,WAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AAAA,EACrD;AAGA,QAAM,sCAAsB,IAAA;AAS5B,aAAW,OAAO,WAAW,MAAM;AACjC,QAAI,IAAI,SAAS,UAAU,CAAC,MAAM,OAAO,MAAM,KAAK,EAAE,SAAS,IAAI,IAAI,GAAG;AACxE,YAAM,UAAU;AAChB,UAAI,QAAQ,KAAK,WAAW,GAAG;AAC7B,cAAM,UAAU,QAAQ,KAAK,CAAC;AAC9B,cAAM,WAAW,QAAQ,KAAK,CAAC;AAG/B,YAAI,WAAmC;AACvC,YAAI,WAAmC;AACvC,YAAI,YAAY,QAAQ;AAExB,YAAI,QAAQ,SAAS,SAAS,SAAS,SAAS,OAAO;AAErD,qBAAW;AACX,qBAAW;AAAA,QACb,WAAW,QAAQ,SAAS,SAAS,SAAS,SAAS,OAAO;AAE5D,qBAAW;AACX,qBAAW;AAGX,kBAAQ,WAAA;AAAA,YACN,KAAK;AACH,0BAAY;AACZ;AAAA,YACF,KAAK;AACH,0BAAY;AACZ;AAAA,YACF,KAAK;AACH,0BAAY;AACZ;AAAA,YACF,KAAK;AACH,0BAAY;AACZ;AAAA,UAAA;AAAA,QAEN;AAEA,YAAI,YAAY,UAAU;AACxB,gBAAM,YAAa,SAAiB;AACpC,gBAAM,WAAW,UAAU,KAAK,GAAG;AACnC,gBAAM,QAAS,SAAiB;AAEhC,cAAI,CAAC,gBAAgB,IAAI,QAAQ,GAAG;AAClC,4BAAgB,IAAI,UAAU,EAAE;AAAA,UAClC;AACA,0BAAgB,IAAI,QAAQ,EAAG,KAAK,EAAE,WAAW,OAAO;AAAA,QAC1D;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAGA,aAAW,CAAC,UAAU,UAAU,KAAK,iBAAiB;AACpD,QAAI,WAAW,UAAU,GAAG;AAC1B,YAAM,YAAY,SAAS,MAAM,GAAG;AACpC,YAAM,QAAQ,kBAAkB,SAAS,SAAS;AAElD,UAAI,SAAS,MAAM,SAAS,IAAI,KAAK,MAAM,SAAS,IAAI,GAAG;AAEzD,YAAI,OAAY;AAChB,YAAI,KAAU;AACd,YAAI,gBAAgB;AACpB,YAAI,cAAc;AAElB,mBAAW,EAAE,WAAW,MAAA,KAAW,YAAY;AAC7C,kBAAQ,WAAA;AAAA,YACN,KAAK;AACH,kBAAI,SAAS,UAAa,QAAQ,MAAM;AACtC,uBAAO;AACP,gCAAgB;AAAA,cAClB;AACA;AAAA,YACF,KAAK;AACH,kBAAI,SAAS,UAAa,QAAQ,MAAM;AACtC,uBAAO;AACP,gCAAgB;AAAA,cAClB;AACA;AAAA,YACF,KAAK;AACH,kBAAI,OAAO,UAAa,QAAQ,IAAI;AAClC,qBAAK;AACL,8BAAc;AAAA,cAChB;AACA;AAAA,YACF,KAAK;AACH,kBAAI,OAAO,UAAa,QAAQ,IAAI;AAClC,qBAAK;AACL,8BAAc;AAAA,cAChB;AACA;AAAA,UAAA;AAAA,QAEN;AAEA,cAAM,eAAgB,MAAc,WAAW;AAAA,UAC7C;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,QAAA,CACD;AAED,eAAO,EAAE,aAAa,MAAM,aAAA;AAAA,MAC9B;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AACrD;AAKA,SAAS,yBACP,YACA,SAC0B;AAC1B,MAAI,WAAW,SAAS,UAAU,WAAW,KAAK,WAAW,GAAG;AAC9D,WAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AAAA,EACrD;AAEA,QAAM,UAAU,WAAW,KAAK,CAAC;AACjC,QAAM,WAAW,WAAW,KAAK,CAAC;AAGlC,MAAI,WAAmC;AACvC,MAAI,WAAmC;AACvC,MAAI,YAAY,WAAW;AAE3B,MAAI,QAAQ,SAAS,SAAS,SAAS,SAAS,OAAO;AAErD,eAAW;AACX,eAAW;AAAA,EACb,WAAW,QAAQ,SAAS,SAAS,SAAS,SAAS,OAAO;AAE5D,eAAW;AACX,eAAW;AAGX,YAAQ,WAAA;AAAA,MACN,KAAK;AACH,oBAAY;AACZ;AAAA,MACF,KAAK;AACH,oBAAY;AACZ;AAAA,MACF,KAAK;AACH,oBAAY;AACZ;AAAA,MACF,KAAK;AACH,oBAAY;AACZ;AAAA,IAAA;AAAA,EAGN;AAEA,MAAI,YAAY,UAAU;AACxB,UAAM,YAAa,SAAiB;AACpC,UAAM,QAAQ,kBAAkB,SAAS,SAAS;AAElD,QAAI,OAAO;AACT,YAAM,aAAc,SAAiB;AAGrC,YAAM,iBAAiB;AAGvB,UAAI,CAAC,MAAM,SAAS,cAAc,GAAG;AACnC,eAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AAAA,MACrD;AAEA,YAAM,eAAe,MAAM,OAAO,gBAAgB,UAAU;AAC5D,aAAO,EAAE,aAAa,MAAM,aAAA;AAAA,IAC9B;AAAA,EACF;AAEA,SAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AACrD;AAoCA,SAAS,sBACP,YACA,SAC0B;AAC1B,MAAI,WAAW,SAAS,UAAU,WAAW,KAAK,SAAS,GAAG;AAC5D,WAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AAAA,EACrD;AAGA,QAAM,sBAAsB,2BAA2B,YAAY,OAAO;AAC1E,MAAI,oBAAoB,aAAa;AACnC,WAAO;AAAA,EACT;AAEA,QAAM,UAA2C,CAAA;AAGjD,aAAW,OAAO,WAAW,MAAM;AACjC,UAAM,SAAS,uBAAuB,KAAK,OAAO;AAClD,QAAI,OAAO,aAAa;AACtB,cAAQ,KAAK,MAAM;AAAA,IACrB;AAAA,EACF;AAEA,MAAI,QAAQ,SAAS,GAAG;AAEtB,UAAM,kBAAkB,QAAQ,IAAI,CAAC,MAAM,EAAE,YAAY;AACzD,UAAM,kBAAkB,cAAc,eAAe;AACrD,WAAO,EAAE,aAAa,MAAM,cAAc,gBAAA;AAAA,EAC5C;AAEA,SAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AACrD;AAoBA,SAAS,qBACP,YACA,SAC0B;AAC1B,MAAI,WAAW,SAAS,UAAU,WAAW,KAAK,SAAS,GAAG;AAC5D,WAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AAAA,EACrD;AAEA,QAAM,UAA2C,CAAA;AAGjD,aAAW,OAAO,WAAW,MAAM;AACjC,UAAM,SAAS,uBAAuB,KAAK,OAAO;AAClD,QAAI,OAAO,aAAa;AACtB,cAAQ,KAAK,MAAM;AAAA,IACrB;AAAA,EACF;AAEA,MAAI,QAAQ,SAAS,GAAG;AAEtB,UAAM,kBAAkB,QAAQ,IAAI,CAAC,MAAM,EAAE,YAAY;AACzD,UAAM,cAAc,UAAU,eAAe;AAC7C,WAAO,EAAE,aAAa,MAAM,cAAc,YAAA;AAAA,EAC5C;AAEA,SAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AACrD;AAoBA,SAAS,0BACP,YACA,SAC0B;AAC1B,MAAI,WAAW,SAAS,UAAU,WAAW,KAAK,WAAW,GAAG;AAC9D,WAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AAAA,EACrD;AAEA,QAAM,WAAW,WAAW,KAAK,CAAC;AAClC,QAAM,WAAW,WAAW,KAAK,CAAC;AAElC,MACE,SAAS,SAAS,SAClB,SAAS,SAAS,SAClB,MAAM,QAAS,SAAiB,KAAK,GACrC;AACA,UAAM,YAAa,SAAiB;AACpC,UAAM,SAAU,SAAiB;AACjC,UAAM,QAAQ,kBAAkB,SAAS,SAAS;AAElD,QAAI,OAAO;AAET,UAAI,MAAM,SAAS,IAAI,GAAG;AACxB,cAAM,eAAe,MAAM,OAAO,MAAM,MAAM;AAC9C,eAAO,EAAE,aAAa,MAAM,aAAA;AAAA,MAC9B,WAAW,MAAM,SAAS,IAAI,GAAG;AAE/B,cAAM,mCAAmB,IAAA;AACzB,mBAAW,SAAS,QAAQ;AAC1B,gBAAM,eAAe,MAAM,OAAO,MAAM,KAAK;AAC7C,qBAAW,OAAO,cAAc;AAC9B,yBAAa,IAAI,GAAG;AAAA,UACtB;AAAA,QACF;AACA,eAAO,EAAE,aAAa,MAAM,aAAA;AAAA,MAC9B;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AACrD;"}
+{"version":3,"file":"index-optimization.js","sources":["../../../src/utils/index-optimization.ts"],"sourcesContent":["/**\n * # Index-Based Query Optimization\n *\n * This module provides utilities for optimizing query expressions by leveraging\n * available indexes to quickly find matching keys instead of scanning all data.\n *\n * This is different from the query structure optimizer in `query/optimizer.ts`\n * which rewrites query IR structure. This module focuses on using indexes during\n * query execution to speed up data filtering.\n *\n * ## Key Features:\n * - Uses indexes to find matching keys for WHERE conditions\n * - Supports AND/OR logic with set operations\n * - Handles range queries (eq, gt, gte, lt, lte)\n * - Optimizes IN array expressions\n */\n\nimport { DEFAULT_COMPARE_OPTIONS } from \"../utils.js\"\nimport { ReverseIndex } from \"../indexes/reverse-index.js\"\nimport type { CompareOptions } from \"../query/builder/types.js\"\nimport type { IndexInterface, IndexOperation } from \"../indexes/base-index.js\"\nimport type { BasicExpression } from \"../query/ir.js\"\nimport type { CollectionLike } from \"../types.js\"\n\n/**\n * Result of index-based query optimization\n */\nexport interface OptimizationResult<TKey> {\n  canOptimize: boolean\n  matchingKeys: Set<TKey>\n}\n\n/**\n * Finds an index that matches a given field path\n */\nexport function findIndexForField<TKey extends string | number>(\n  collection: CollectionLike<any, TKey>,\n  fieldPath: Array<string>,\n  compareOptions?: CompareOptions\n): IndexInterface<TKey> | undefined {\n  const compareOpts = compareOptions ?? {\n    ...DEFAULT_COMPARE_OPTIONS,\n    ...collection.compareOptions,\n  }\n\n  for (const index of collection.indexes.values()) {\n    if (\n      index.matchesField(fieldPath) &&\n      index.matchesCompareOptions(compareOpts)\n    ) {\n      if (!index.matchesDirection(compareOpts.direction)) {\n        return new ReverseIndex(index)\n      }\n      return index\n    }\n  }\n  return undefined\n}\n\n/**\n * Intersects multiple sets (AND logic)\n */\nexport function intersectSets<T>(sets: Array<Set<T>>): Set<T> {\n  if (sets.length === 0) return new Set()\n  if (sets.length === 1) return new Set(sets[0])\n\n  let result = new Set(sets[0])\n  for (let i = 1; i < sets.length; i++) {\n    const newResult = new Set<T>()\n    for (const item of result) {\n      if (sets[i]!.has(item)) {\n        newResult.add(item)\n      }\n    }\n    result = newResult\n  }\n  return result\n}\n\n/**\n * Unions multiple sets (OR logic)\n */\nexport function unionSets<T>(sets: Array<Set<T>>): Set<T> {\n  const result = new Set<T>()\n  for (const set of sets) {\n    for (const item of set) {\n      result.add(item)\n    }\n  }\n  return result\n}\n\n/**\n * Optimizes a query expression using available indexes to find matching keys\n */\nexport function optimizeExpressionWithIndexes<\n  T extends object,\n  TKey extends string | number,\n>(\n  expression: BasicExpression,\n  collection: CollectionLike<T, TKey>\n): OptimizationResult<TKey> {\n  return optimizeQueryRecursive(expression, collection)\n}\n\n/**\n * Recursively optimizes query expressions\n */\nfunction optimizeQueryRecursive<T extends object, TKey extends string | number>(\n  expression: BasicExpression,\n  collection: CollectionLike<T, TKey>\n): OptimizationResult<TKey> {\n  if (expression.type === `func`) {\n    switch (expression.name) {\n      case `eq`:\n      case `gt`:\n      case `gte`:\n      case `lt`:\n      case `lte`:\n        return optimizeSimpleComparison(expression, collection)\n\n      case `and`:\n        return optimizeAndExpression(expression, collection)\n\n      case `or`:\n        return optimizeOrExpression(expression, collection)\n\n      case `in`:\n        return optimizeInArrayExpression(expression, collection)\n    }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if an expression can be optimized\n */\nexport function canOptimizeExpression<\n  T extends object,\n  TKey extends string | number,\n>(expression: BasicExpression, collection: CollectionLike<T, TKey>): boolean {\n  if (expression.type === `func`) {\n    switch (expression.name) {\n      case `eq`:\n      case `gt`:\n      case `gte`:\n      case `lt`:\n      case `lte`:\n        return canOptimizeSimpleComparison(expression, collection)\n\n      case `and`:\n        return canOptimizeAndExpression(expression, collection)\n\n      case `or`:\n        return canOptimizeOrExpression(expression, collection)\n\n      case `in`:\n        return canOptimizeInArrayExpression(expression, collection)\n    }\n  }\n\n  return false\n}\n\n/**\n * Optimizes compound range queries on the same field\n * Example: WHERE age > 5 AND age < 10\n */\nfunction optimizeCompoundRangeQuery<\n  T extends object,\n  TKey extends string | number,\n>(\n  expression: BasicExpression,\n  collection: CollectionLike<T, TKey>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  // Group range operations by field\n  const fieldOperations = new Map<\n    string,\n    Array<{\n      operation: `gt` | `gte` | `lt` | `lte`\n      value: any\n    }>\n  >()\n\n  // Collect all range operations from AND arguments\n  for (const arg of expression.args) {\n    if (arg.type === `func` && [`gt`, `gte`, `lt`, `lte`].includes(arg.name)) {\n      const rangeOp = arg as any\n      if (rangeOp.args.length === 2) {\n        const leftArg = rangeOp.args[0]!\n        const rightArg = rangeOp.args[1]!\n\n        // Check both directions: field op value AND value op field\n        let fieldArg: BasicExpression | null = null\n        let valueArg: BasicExpression | null = null\n        let operation = rangeOp.name as `gt` | `gte` | `lt` | `lte`\n\n        if (leftArg.type === `ref` && rightArg.type === `val`) {\n          // field op value\n          fieldArg = leftArg\n          valueArg = rightArg\n        } else if (leftArg.type === `val` && rightArg.type === `ref`) {\n          // value op field - need to flip the operation\n          fieldArg = rightArg\n          valueArg = leftArg\n\n          // Flip the operation for reverse comparison\n          switch (operation) {\n            case `gt`:\n              operation = `lt`\n              break\n            case `gte`:\n              operation = `lte`\n              break\n            case `lt`:\n              operation = `gt`\n              break\n            case `lte`:\n              operation = `gte`\n              break\n          }\n        }\n\n        if (fieldArg && valueArg) {\n          const fieldPath = (fieldArg as any).path\n          const fieldKey = fieldPath.join(`.`)\n          const value = (valueArg as any).value\n\n          if (!fieldOperations.has(fieldKey)) {\n            fieldOperations.set(fieldKey, [])\n          }\n          fieldOperations.get(fieldKey)!.push({ operation, value })\n        }\n      }\n    }\n  }\n\n  // Check if we have multiple operations on the same field\n  for (const [fieldKey, operations] of fieldOperations) {\n    if (operations.length >= 2) {\n      const fieldPath = fieldKey.split(`.`)\n      const index = findIndexForField(collection, fieldPath)\n\n      if (index && index.supports(`gt`) && index.supports(`lt`)) {\n        // Build range query options\n        let from: any = undefined\n        let to: any = undefined\n        let fromInclusive = true\n        let toInclusive = true\n\n        for (const { operation, value } of operations) {\n          switch (operation) {\n            case `gt`:\n              if (from === undefined || value > from) {\n                from = value\n                fromInclusive = false\n              }\n              break\n            case `gte`:\n              if (from === undefined || value > from) {\n                from = value\n                fromInclusive = true\n              }\n              break\n            case `lt`:\n              if (to === undefined || value < to) {\n                to = value\n                toInclusive = false\n              }\n              break\n            case `lte`:\n              if (to === undefined || value < to) {\n                to = value\n                toInclusive = true\n              }\n              break\n          }\n        }\n\n        const matchingKeys = (index as any).rangeQuery({\n          from,\n          to,\n          fromInclusive,\n          toInclusive,\n        })\n\n        return { canOptimize: true, matchingKeys }\n      }\n    }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Optimizes simple comparison expressions (eq, gt, gte, lt, lte)\n */\nfunction optimizeSimpleComparison<\n  T extends object,\n  TKey extends string | number,\n>(\n  expression: BasicExpression,\n  collection: CollectionLike<T, TKey>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length !== 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  const leftArg = expression.args[0]!\n  const rightArg = expression.args[1]!\n\n  // Check both directions: field op value AND value op field\n  let fieldArg: BasicExpression | null = null\n  let valueArg: BasicExpression | null = null\n  let operation = expression.name as `eq` | `gt` | `gte` | `lt` | `lte`\n\n  if (leftArg.type === `ref` && rightArg.type === `val`) {\n    // field op value\n    fieldArg = leftArg\n    valueArg = rightArg\n  } else if (leftArg.type === `val` && rightArg.type === `ref`) {\n    // value op field - need to flip the operation\n    fieldArg = rightArg\n    valueArg = leftArg\n\n    // Flip the operation for reverse comparison\n    switch (operation) {\n      case `gt`:\n        operation = `lt`\n        break\n      case `gte`:\n        operation = `lte`\n        break\n      case `lt`:\n        operation = `gt`\n        break\n      case `lte`:\n        operation = `gte`\n        break\n      // eq stays the same\n    }\n  }\n\n  if (fieldArg && valueArg) {\n    const fieldPath = (fieldArg as any).path\n    const index = findIndexForField(collection, fieldPath)\n\n    if (index) {\n      const queryValue = (valueArg as any).value\n\n      // Map operation to IndexOperation enum\n      const indexOperation = operation as IndexOperation\n\n      // Check if the index supports this operation\n      if (!index.supports(indexOperation)) {\n        return { canOptimize: false, matchingKeys: new Set() }\n      }\n\n      const matchingKeys = index.lookup(indexOperation, queryValue)\n      return { canOptimize: true, matchingKeys }\n    }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if a simple comparison can be optimized\n */\nfunction canOptimizeSimpleComparison<\n  T extends object,\n  TKey extends string | number,\n>(expression: BasicExpression, collection: CollectionLike<T, TKey>): boolean {\n  if (expression.type !== `func` || expression.args.length !== 2) {\n    return false\n  }\n\n  const leftArg = expression.args[0]!\n  const rightArg = expression.args[1]!\n\n  // Check both directions: field op value AND value op field\n  let fieldPath: Array<string> | null = null\n\n  if (leftArg.type === `ref` && rightArg.type === `val`) {\n    fieldPath = (leftArg as any).path\n  } else if (leftArg.type === `val` && rightArg.type === `ref`) {\n    fieldPath = (rightArg as any).path\n  }\n\n  if (fieldPath) {\n    const index = findIndexForField(collection, fieldPath)\n    return index !== undefined\n  }\n\n  return false\n}\n\n/**\n * Optimizes AND expressions\n */\nfunction optimizeAndExpression<T extends object, TKey extends string | number>(\n  expression: BasicExpression,\n  collection: CollectionLike<T, TKey>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  // First, try to optimize compound range queries on the same field\n  const compoundRangeResult = optimizeCompoundRangeQuery(expression, collection)\n  if (compoundRangeResult.canOptimize) {\n    return compoundRangeResult\n  }\n\n  const results: Array<OptimizationResult<TKey>> = []\n\n  // Try to optimize each part, keep the optimizable ones\n  for (const arg of expression.args) {\n    const result = optimizeQueryRecursive(arg, collection)\n    if (result.canOptimize) {\n      results.push(result)\n    }\n  }\n\n  if (results.length > 0) {\n    // Use intersectSets utility for AND logic\n    const allMatchingSets = results.map((r) => r.matchingKeys)\n    const intersectedKeys = intersectSets(allMatchingSets)\n    return { canOptimize: true, matchingKeys: intersectedKeys }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if an AND expression can be optimized\n */\nfunction canOptimizeAndExpression<\n  T extends object,\n  TKey extends string | number,\n>(expression: BasicExpression, collection: CollectionLike<T, TKey>): boolean {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return false\n  }\n\n  // If any argument can be optimized, we can gain some speedup\n  return expression.args.some((arg) => canOptimizeExpression(arg, collection))\n}\n\n/**\n * Optimizes OR expressions\n */\nfunction optimizeOrExpression<T extends object, TKey extends string | number>(\n  expression: BasicExpression,\n  collection: CollectionLike<T, TKey>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  const results: Array<OptimizationResult<TKey>> = []\n\n  // Try to optimize each part, keep the optimizable ones\n  for (const arg of expression.args) {\n    const result = optimizeQueryRecursive(arg, collection)\n    if (result.canOptimize) {\n      results.push(result)\n    }\n  }\n\n  if (results.length > 0) {\n    // Use unionSets utility for OR logic\n    const allMatchingSets = results.map((r) => r.matchingKeys)\n    const unionedKeys = unionSets(allMatchingSets)\n    return { canOptimize: true, matchingKeys: unionedKeys }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if an OR expression can be optimized\n */\nfunction canOptimizeOrExpression<\n  T extends object,\n  TKey extends string | number,\n>(expression: BasicExpression, collection: CollectionLike<T, TKey>): boolean {\n  if (expression.type !== `func` || expression.args.length < 2) {\n    return false\n  }\n\n  // If any argument can be optimized, we can gain some speedup\n  return expression.args.some((arg) => canOptimizeExpression(arg, collection))\n}\n\n/**\n * Optimizes IN array expressions\n */\nfunction optimizeInArrayExpression<\n  T extends object,\n  TKey extends string | number,\n>(\n  expression: BasicExpression,\n  collection: CollectionLike<T, TKey>\n): OptimizationResult<TKey> {\n  if (expression.type !== `func` || expression.args.length !== 2) {\n    return { canOptimize: false, matchingKeys: new Set() }\n  }\n\n  const fieldArg = expression.args[0]!\n  const arrayArg = expression.args[1]!\n\n  if (\n    fieldArg.type === `ref` &&\n    arrayArg.type === `val` &&\n    Array.isArray((arrayArg as any).value)\n  ) {\n    const fieldPath = (fieldArg as any).path\n    const values = (arrayArg as any).value\n    const index = findIndexForField(collection, fieldPath)\n\n    if (index) {\n      // Check if the index supports IN operation\n      if (index.supports(`in`)) {\n        const matchingKeys = index.lookup(`in`, values)\n        return { canOptimize: true, matchingKeys }\n      } else if (index.supports(`eq`)) {\n        // Fallback to multiple equality lookups\n        const matchingKeys = new Set<TKey>()\n        for (const value of values) {\n          const keysForValue = index.lookup(`eq`, value)\n          for (const key of keysForValue) {\n            matchingKeys.add(key)\n          }\n        }\n        return { canOptimize: true, matchingKeys }\n      }\n    }\n  }\n\n  return { canOptimize: false, matchingKeys: new Set() }\n}\n\n/**\n * Checks if an IN array expression can be optimized\n */\nfunction canOptimizeInArrayExpression<\n  T extends object,\n  TKey extends string | number,\n>(expression: BasicExpression, collection: CollectionLike<T, TKey>): boolean {\n  if (expression.type !== `func` || expression.args.length !== 2) {\n    return false\n  }\n\n  const fieldArg = expression.args[0]!\n  const arrayArg = expression.args[1]!\n\n  if (\n    fieldArg.type === `ref` &&\n    arrayArg.type === `val` &&\n    Array.isArray((arrayArg as any).value)\n  ) {\n    const fieldPath = (fieldArg as any).path\n    const index = findIndexForField(collection, fieldPath)\n    return index !== undefined\n  }\n\n  return false\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.4.20",
+  "version": "0.5.0",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/pacer": "^0.1.0",
-    "@tanstack/db-ivm": "0.1.12"
+    "@tanstack/db-ivm": "0.1.13"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^3.2.4",

package/src/collection/change-events.ts

@@ -2,34 +2,27 @@ import {
   createSingleRowRefProxy,
   toExpression,
 } from "../query/builder/ref-proxy"
-import { compileSingleRowExpression } from "../query/compiler/evaluators.js"
+import {
+  compileSingleRowExpression,
+  toBooleanPredicate,
+} from "../query/compiler/evaluators.js"
 import {
   findIndexForField,
   optimizeExpressionWithIndexes,
 } from "../utils/index-optimization.js"
 import { ensureIndexForField } from "../indexes/auto-index.js"
 import { makeComparator } from "../utils/comparison.js"
+import { buildCompareOptions } from "../query/compiler/order-by"
 import type {
   ChangeMessage,
+  CollectionLike,
   CurrentStateAsChangesOptions,
   SubscribeChangesOptions,
 } from "../types"
-import type { Collection, CollectionImpl } from "./index.js"
+import type { CollectionImpl } from "./index.js"
 import type { SingleRowRefProxy } from "../query/builder/ref-proxy"
 import type { BasicExpression, OrderBy } from "../query/ir.js"
 
-/**
- * Interface for a collection-like object that provides the necessary methods
- * for the change events system to work
- */
-export interface CollectionLike<
-  T extends object = Record<string, unknown>,
-  TKey extends string | number = string | number,
-> extends Pick<
-    Collection<T, TKey>,
-    `get` | `has` | `entries` | `indexes` | `id`
-  > {}
-
 /**
  * Returns the current state of the collection as an array of changes
  * @param collection - The collection to get changes from
@@ -140,7 +133,7 @@ export function currentStateAsChanges<
     // Try to optimize the query using indexes
     const optimizationResult = optimizeExpressionWithIndexes(
       expression,
-      collection.indexes
+      collection
     )
 
     if (optimizationResult.canOptimize) {
@@ -199,7 +192,7 @@ export function createFilterFunction<T extends object>(
       const evaluator = compileSingleRowExpression(expression)
       const result = evaluator(item as Record<string, unknown>)
       // WHERE clauses should always evaluate to boolean predicates (Kevin's feedback)
-      return result
+      return toBooleanPredicate(result)
     } catch {
       // If RefProxy approach fails (e.g., arithmetic operations), fall back to direct evaluation
       try {
@@ -211,7 +204,7 @@ export function createFilterFunction<T extends object>(
         }) as SingleRowRefProxy<T>
 
         const result = whereCallback(simpleProxy)
-        return result
+        return toBooleanPredicate(result)
       } catch {
         // If both approaches fail, exclude the item
         return false
@@ -232,7 +225,7 @@ export function createFilterFunctionFromExpression<T extends object>(
     try {
       const evaluator = compileSingleRowExpression(expression)
       const result = evaluator(item as Record<string, unknown>)
-      return Boolean(result)
+      return toBooleanPredicate(result)
     } catch {
       // If evaluation fails, exclude the item
       return false
@@ -326,21 +319,18 @@ function getOrderedKeys<T extends object, TKey extends string | number>(
     if (orderByExpression.type === `ref`) {
       const propRef = orderByExpression
       const fieldPath = propRef.path
+      const compareOpts = buildCompareOptions(clause, collection)
 
       // Ensure index exists for this field
       ensureIndexForField(
         fieldPath[0]!,
         fieldPath,
         collection as CollectionImpl<T, TKey>,
-        clause.compareOptions
+        compareOpts
       )
 
       // Find the index
-      const index = findIndexForField(
-        collection.indexes,
-        fieldPath,
-        clause.compareOptions
-      )
+      const index = findIndexForField(collection, fieldPath, compareOpts)
 
       if (index && index.supports(`gt`)) {
         // Use index optimization

package/src/collection/index.ts

@@ -27,6 +27,7 @@ import type {
   NonSingleResult,
   OperationConfig,
   SingleResult,
+  StringCollationConfig,
   SubscribeChangesOptions,
   Transaction as TransactionType,
   UtilsRecord,
@@ -132,7 +133,7 @@ export function createCollection<
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = UtilsRecord,
 >(
-  options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+  options: CollectionConfig<InferSchemaOutput<T>, TKey, T, TUtils> & {
     schema: T
     utils?: TUtils
   } & NonSingleResult
@@ -145,7 +146,7 @@ export function createCollection<
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = UtilsRecord,
 >(
-  options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+  options: CollectionConfig<InferSchemaOutput<T>, TKey, T, TUtils> & {
     schema: T
     utils?: TUtils
   } & SingleResult
@@ -159,7 +160,7 @@ export function createCollection<
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = UtilsRecord,
 >(
-  options: CollectionConfig<T, TKey, never> & {
+  options: CollectionConfig<T, TKey, never, TUtils> & {
     schema?: never // prohibit schema if an explicit type is provided
     utils?: TUtils
   } & NonSingleResult
@@ -172,7 +173,7 @@ export function createCollection<
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = UtilsRecord,
 >(
-  options: CollectionConfig<T, TKey, never> & {
+  options: CollectionConfig<T, TKey, never, TUtils> & {
     schema?: never // prohibit schema if an explicit type is provided
     utils?: TUtils
   } & SingleResult
@@ -230,6 +231,8 @@ export class CollectionImpl<
   // and for debugging
   public _state: CollectionStateManager<TOutput, TKey, TSchema, TInput>
 
+  private comparisonOpts: StringCollationConfig
+
   /**
    * Creates a new Collection instance
    *
@@ -267,6 +270,8 @@ export class CollectionImpl<
     this._state = new CollectionStateManager(config)
     this._sync = new CollectionSyncManager(config, this.id)
 
+    this.comparisonOpts = buildCompareOptionsFromConfig(config)
+
     this._changes.setDeps({
       collection: this, // Required for passing to CollectionSubscription
       lifecycle: this._lifecycle,
@@ -508,6 +513,11 @@ export class CollectionImpl<
     return this._mutations.validateData(data, type, key)
   }
 
+  get compareOptions(): StringCollationConfig {
+    // return a copy such that no one can mutate the internal comparison object
+    return { ...this.comparisonOpts }
+  }
+
   /**
    * Inserts one or more items into the collection
    * @param items - Single item or array of items to insert
@@ -848,3 +858,21 @@ export class CollectionImpl<
     return Promise.resolve()
   }
 }
+
+function buildCompareOptionsFromConfig(
+  config: CollectionConfig<any, any, any>
+): StringCollationConfig {
+  if (config.defaultStringCollation) {
+    const options = config.defaultStringCollation
+    return {
+      stringSort: options.stringSort ?? `locale`,
+      locale: options.stringSort === `locale` ? options.locale : undefined,
+      localeOptions:
+        options.stringSort === `locale` ? options.localeOptions : undefined,
+    }
+  } else {
+    return {
+      stringSort: `locale`,
+    }
+  }
+}

package/src/index.ts

@@ -22,6 +22,10 @@ export * from "./indexes/btree-index.js"
 export * from "./indexes/lazy-index.js"
 export { type IndexOptions } from "./indexes/index-options.js"
 
+// Expression helpers
+export * from "./query/expression-helpers.js"
+
 // Re-export some stuff explicitly to ensure the type & value is exported
 export type { Collection } from "./collection/index.js"
 export { IR }
+export { operators, type OperatorName } from "./query/builder/functions.js"

package/src/indexes/auto-index.ts

@@ -24,18 +24,22 @@ export function ensureIndexForField<
   fieldName: string,
   fieldPath: Array<string>,
   collection: CollectionImpl<T, TKey, any, any, any>,
-  compareOptions: CompareOptions = DEFAULT_COMPARE_OPTIONS,
+  compareOptions?: CompareOptions,
   compareFn?: (a: any, b: any) => number
 ) {
   if (!shouldAutoIndex(collection)) {
     return
   }
 
+  const compareOpts = compareOptions ?? {
+    ...DEFAULT_COMPARE_OPTIONS,
+    ...collection.compareOptions,
+  }
+
   // Check if we already have an index for this field
   const existingIndex = Array.from(collection.indexes.values()).find(
     (index) =>
-      index.matchesField(fieldPath) &&
-      index.matchesCompareOptions(compareOptions)
+      index.matchesField(fieldPath) && index.matchesCompareOptions(compareOpts)
   )
 
   if (existingIndex) {
@@ -57,7 +61,7 @@ export function ensureIndexForField<
       {
         name: `auto:${fieldPath.join(`.`)}`,
         indexType: BTreeIndex,
-        options: compareFn ? { compareFn, compareOptions } : {},
+        options: compareFn ? { compareFn, compareOptions: compareOpts } : {},
       }
     )
   } catch (error) {

package/src/local-storage.ts

@@ -283,7 +283,12 @@ export function localStorageCollectionOptions<
   config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {
     schema: T
   }
-): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+): CollectionConfig<
+  InferSchemaOutput<T>,
+  TKey,
+  T,
+  LocalStorageCollectionUtils
+> & {
   id: string
   utils: LocalStorageCollectionUtils
   schema: T
@@ -298,7 +303,7 @@ export function localStorageCollectionOptions<
   config: LocalStorageCollectionConfig<T, never, TKey> & {
     schema?: never // prohibit schema
   }
-): CollectionConfig<T, TKey> & {
+): CollectionConfig<T, TKey, never, LocalStorageCollectionUtils> & {
   id: string
   utils: LocalStorageCollectionUtils
   schema?: never // no schema in the result
@@ -306,7 +311,10 @@ export function localStorageCollectionOptions<
 
 export function localStorageCollectionOptions(
   config: LocalStorageCollectionConfig<any, any, string | number>
-): Omit<CollectionConfig<any, string | number, any>, `id`> & {
+): Omit<
+  CollectionConfig<any, string | number, any, LocalStorageCollectionUtils>,
+  `id`
+> & {
   id: string
   utils: LocalStorageCollectionUtils
   schema?: StandardSchemaV1

package/src/query/builder/functions.ts

@@ -337,3 +337,42 @@ export const comparisonFunctions = [
   `like`,
   `ilike`,
 ] as const
+
+/**
+ * All supported operator names in TanStack DB expressions
+ */
+export const operators = [
+  // Comparison operators
+  `eq`,
+  `gt`,
+  `gte`,
+  `lt`,
+  `lte`,
+  `in`,
+  `like`,
+  `ilike`,
+  // Logical operators
+  `and`,
+  `or`,
+  `not`,
+  // Null checking
+  `isNull`,
+  `isUndefined`,
+  // String functions
+  `upper`,
+  `lower`,
+  `length`,
+  `concat`,
+  // Numeric functions
+  `add`,
+  // Utility functions
+  `coalesce`,
+  // Aggregate functions
+  `count`,
+  `avg`,
+  `sum`,
+  `min`,
+  `max`,
+] as const
+
+export type OperatorName = (typeof operators)[number]

package/src/query/builder/index.ts

@@ -469,11 +469,11 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
 
     const opts: CompareOptions =
       typeof options === `string`
-        ? { direction: options, nulls: `first`, stringSort: `locale` }
+        ? { direction: options, nulls: `first` }
         : {
             direction: options.direction ?? `asc`,
             nulls: options.nulls ?? `first`,
-            stringSort: options.stringSort ?? `locale`,
+            stringSort: options.stringSort,
             locale:
               options.stringSort === `locale` ? options.locale : undefined,
             localeOptions:

package/src/query/builder/types.ts

@@ -1,5 +1,5 @@
 import type { CollectionImpl } from "../../collection/index.js"
-import type { SingleResult } from "../../types.js"
+import type { SingleResult, StringCollationConfig } from "../../types.js"
 import type {
   Aggregate,
   BasicExpression,
@@ -303,26 +303,7 @@ export type OrderByCallback<TContext extends Context> = (
 export type OrderByOptions = {
   direction?: OrderByDirection
   nulls?: `first` | `last`
-} & StringSortOpts
-
-/**
- * StringSortOpts - Options for string sorting behavior
- *
- * This discriminated union allows for two types of string sorting:
- * - **Lexical**: Simple character-by-character comparison (default)
- * - **Locale**: Locale-aware sorting with optional customization
- *
- * The union ensures that locale options are only available when locale sorting is selected.
- */
-export type StringSortOpts =
-  | {
-      stringSort?: `lexical`
-    }
-  | {
-      stringSort?: `locale`
-      locale?: string
-      localeOptions?: object
-    }
+} & StringCollationConfig
 
 /**
  * CompareOptions - Final resolved options for comparison operations
@@ -331,12 +312,9 @@ export type StringSortOpts =
  * to their concrete values. Unlike OrderByOptions, all fields are required
  * since defaults have been applied.
  */
-export type CompareOptions = {
+export type CompareOptions = StringCollationConfig & {
   direction: OrderByDirection
   nulls: `first` | `last`
-  stringSort: `lexical` | `locale`
-  locale?: string
-  localeOptions?: object
 }
 
 /**