@tanstack/db 0.4.19 → 0.5.0

package/dist/cjs/utils/index-optimization.cjs

@@ -2,10 +2,14 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const utils = require("../utils.cjs");
 const reverseIndex = require("../indexes/reverse-index.cjs");
-function findIndexForField(indexes, fieldPath, compareOptions = utils.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 ?? {
+    ...utils.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.ReverseIndex(index);
       }
       return index;
@@ -37,10 +41,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`:
@@ -48,18 +52,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() };
   }
@@ -109,7 +113,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;
@@ -155,7 +159,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() };
   }
@@ -187,7 +191,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;
@@ -200,17 +204,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);
     }
@@ -222,13 +226,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);
     }
@@ -240,7 +244,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() };
   }
@@ -249,7 +253,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/cjs/utils/index-optimization.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index-optimization.cjs","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":["DEFAULT_COMPARE_OPTIONS","ReverseIndex"],"mappings":"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"}
+{"version":3,"file":"index-optimization.cjs","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":["DEFAULT_COMPARE_OPTIONS","ReverseIndex"],"mappings":"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"}

package/dist/cjs/utils/index-optimization.d.cts

@@ -1,6 +1,7 @@
 import { CompareOptions } from '../query/builder/types.js';
-import { BaseIndex, IndexInterface } from '../indexes/base-index.js';
+import { IndexInterface } from '../indexes/base-index.js';
 import { BasicExpression } from '../query/ir.js';
+import { CollectionLike } from '../types.js';
 /**
  * Result of index-based query optimization
  */
@@ -11,7 +12,7 @@ export interface OptimizationResult<TKey> {
 /**
  * Finds an index that matches a given field path
  */
-export declare function findIndexForField<TKey extends string | number>(indexes: Map<number, IndexInterface<TKey>>, fieldPath: Array<string>, compareOptions?: CompareOptions): IndexInterface<TKey> | undefined;
+export declare function findIndexForField<TKey extends string | number>(collection: CollectionLike<any, TKey>, fieldPath: Array<string>, compareOptions?: CompareOptions): IndexInterface<TKey> | undefined;
 /**
  * Intersects multiple sets (AND logic)
  */
@@ -23,8 +24,8 @@ export declare function unionSets<T>(sets: Array<Set<T>>): Set<T>;
 /**
  * Optimizes a query expression using available indexes to find matching keys
  */
-export declare function optimizeExpressionWithIndexes<TKey extends string | number>(expression: BasicExpression, indexes: Map<number, BaseIndex<TKey>>): OptimizationResult<TKey>;
+export declare function optimizeExpressionWithIndexes<T extends object, TKey extends string | number>(expression: BasicExpression, collection: CollectionLike<T, TKey>): OptimizationResult<TKey>;
 /**
  * Checks if an expression can be optimized
  */
-export declare function canOptimizeExpression<TKey extends string | number>(expression: BasicExpression, indexes: Map<number, BaseIndex<TKey>>): boolean;
+export declare function canOptimizeExpression<T extends object, TKey extends string | number>(expression: BasicExpression, collection: CollectionLike<T, TKey>): boolean;

package/dist/esm/collection/change-events.d.ts

@@ -1,13 +1,6 @@
-import { ChangeMessage, CurrentStateAsChangesOptions, SubscribeChangesOptions } from '../types.js';
-import { Collection } from './index.js';
+import { ChangeMessage, CollectionLike, CurrentStateAsChangesOptions, SubscribeChangesOptions } from '../types.js';
 import { SingleRowRefProxy } from '../query/builder/ref-proxy.js';
 import { BasicExpression } 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

package/dist/esm/collection/change-events.js

@@ -1,7 +1,8 @@
-import { compileSingleRowExpression } from "../query/compiler/evaluators.js";
+import { compileSingleRowExpression, toBooleanPredicate } from "../query/compiler/evaluators.js";
 import { optimizeExpressionWithIndexes, findIndexForField } 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.js";
 function currentStateAsChanges(collection, options = {}) {
   const collectFilteredResults = (filterFn) => {
     const result = [];
@@ -51,7 +52,7 @@ function currentStateAsChanges(collection, options = {}) {
     const expression = options.where;
     const optimizationResult = optimizeExpressionWithIndexes(
       expression,
-      collection.indexes
+      collection
     );
     if (optimizationResult.canOptimize) {
       const result = [];
@@ -90,7 +91,7 @@ function createFilterFunctionFromExpression(expression) {
     try {
       const evaluator = compileSingleRowExpression(expression);
       const result = evaluator(item);
-      return Boolean(result);
+      return toBooleanPredicate(result);
     } catch {
       return false;
     }
@@ -141,17 +142,14 @@ function getOrderedKeys(collection, orderBy, limit, whereFilter, optimizedOnly)
     if (orderByExpression.type === `ref`) {
       const propRef = orderByExpression;
       const fieldPath = propRef.path;
+      const compareOpts = buildCompareOptions(clause, collection);
       ensureIndexForField(
         fieldPath[0],
         fieldPath,
         collection,
-        clause.compareOptions
-      );
-      const index = findIndexForField(
-        collection.indexes,
-        fieldPath,
-        clause.compareOptions
+        compareOpts
       );
+      const index = findIndexForField(collection, fieldPath, compareOpts);
       if (index && index.supports(`gt`)) {
         const filterFn = (key) => {
           const value = collection.get(key);

package/dist/esm/collection/change-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"change-events.js","sources":["../../../src/collection/change-events.ts"],"sourcesContent":["import {\n  createSingleRowRefProxy,\n  toExpression,\n} from \"../query/builder/ref-proxy\"\nimport { compileSingleRowExpression } from \"../query/compiler/evaluators.js\"\nimport {\n  findIndexForField,\n  optimizeExpressionWithIndexes,\n} from \"../utils/index-optimization.js\"\nimport { ensureIndexForField } from \"../indexes/auto-index.js\"\nimport { makeComparator } from \"../utils/comparison.js\"\nimport type {\n  ChangeMessage,\n  CurrentStateAsChangesOptions,\n  SubscribeChangesOptions,\n} from \"../types\"\nimport type { Collection, CollectionImpl } from \"./index.js\"\nimport type { SingleRowRefProxy } from \"../query/builder/ref-proxy\"\nimport type { BasicExpression, OrderBy } from \"../query/ir.js\"\n\n/**\n * Interface for a collection-like object that provides the necessary methods\n * for the change events system to work\n */\nexport interface CollectionLike<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n> extends Pick<\n    Collection<T, TKey>,\n    `get` | `has` | `entries` | `indexes` | `id`\n  > {}\n\n/**\n * Returns the current state of the collection as an array of changes\n * @param collection - The collection to get changes from\n * @param options - Options including optional where filter, orderBy, and limit\n * @returns An array of changes\n * @example\n * // Get all items as changes\n * const allChanges = currentStateAsChanges(collection)\n *\n * // Get only items matching a condition\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: (row) => row.status === 'active'\n * })\n *\n * // Get only items using a pre-compiled expression\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active')\n * })\n *\n * // Get items ordered by name with limit\n * const topUsers = currentStateAsChanges(collection, {\n *   orderBy: [{ expression: row.name, compareOptions: { direction: 'asc' } }],\n *   limit: 10\n * })\n *\n * // Get active users ordered by score (highest score first)\n * const topActiveUsers = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active'),\n *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],\n * })\n */\nexport function currentStateAsChanges<\n  T extends object,\n  TKey extends string | number,\n>(\n  collection: CollectionLike<T, TKey>,\n  options: CurrentStateAsChangesOptions = {}\n): Array<ChangeMessage<T>> | void {\n  // Helper function to collect filtered results\n  const collectFilteredResults = (\n    filterFn?: (value: T) => boolean\n  ): Array<ChangeMessage<T>> => {\n    const result: Array<ChangeMessage<T>> = []\n    for (const [key, value] of collection.entries()) {\n      // If no filter function is provided, include all items\n      if (filterFn?.(value) ?? true) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // Validate that limit without orderBy doesn't happen\n  if (options.limit !== undefined && !options.orderBy) {\n    throw new Error(`limit cannot be used without orderBy`)\n  }\n\n  // First check if orderBy is present (optionally with limit)\n  if (options.orderBy) {\n    // Create where filter function if present\n    const whereFilter = options.where\n      ? createFilterFunctionFromExpression(options.where)\n      : undefined\n\n    // Get ordered keys using index optimization when possible\n    const orderedKeys = getOrderedKeys(\n      collection,\n      options.orderBy,\n      options.limit,\n      whereFilter,\n      options.optimizedOnly\n    )\n\n    if (orderedKeys === undefined) {\n      // `getOrderedKeys` returned undefined because we asked for `optimizedOnly` and there was no index to use\n      return\n    }\n\n    // Convert keys to change messages\n    const result: Array<ChangeMessage<T>> = []\n    for (const key of orderedKeys) {\n      const value = collection.get(key)\n      if (value !== undefined) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // If no orderBy OR orderBy optimization failed, use where clause optimization\n  if (!options.where) {\n    // No filtering, return all items\n    return collectFilteredResults()\n  }\n\n  // There's a where clause, let's see if we can use an index\n  try {\n    const expression: BasicExpression<boolean> = options.where\n\n    // Try to optimize the query using indexes\n    const optimizationResult = optimizeExpressionWithIndexes(\n      expression,\n      collection.indexes\n    )\n\n    if (optimizationResult.canOptimize) {\n      // Use index optimization\n      const result: Array<ChangeMessage<T>> = []\n      for (const key of optimizationResult.matchingKeys) {\n        const value = collection.get(key)\n        if (value !== undefined) {\n          result.push({\n            type: `insert`,\n            key,\n            value,\n          })\n        }\n      }\n      return result\n    } else {\n      if (options.optimizedOnly) {\n        return\n      }\n\n      const filterFn = createFilterFunctionFromExpression(expression)\n      return collectFilteredResults(filterFn)\n    }\n  } catch (error) {\n    // If anything goes wrong with the where clause, fall back to full scan\n    console.warn(\n      `${collection.id ? `[${collection.id}] ` : ``}Error processing where clause, falling back to full scan:`,\n      error\n    )\n\n    const filterFn = createFilterFunctionFromExpression(options.where)\n\n    if (options.optimizedOnly) {\n      return\n    }\n\n    return collectFilteredResults(filterFn)\n  }\n}\n\n/**\n * Creates a filter function from a where callback\n * @param whereCallback - The callback function that defines the filter condition\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunction<T extends object>(\n  whereCallback: (row: SingleRowRefProxy<T>) => any\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      // First try the RefProxy approach for query builder functions\n      const singleRowRefProxy = createSingleRowRefProxy<T>()\n      const whereExpression = whereCallback(singleRowRefProxy)\n      const expression = toExpression(whereExpression)\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      // WHERE clauses should always evaluate to boolean predicates (Kevin's feedback)\n      return result\n    } catch {\n      // If RefProxy approach fails (e.g., arithmetic operations), fall back to direct evaluation\n      try {\n        // Create a simple proxy that returns actual values for arithmetic operations\n        const simpleProxy = new Proxy(item as any, {\n          get(target, prop) {\n            return target[prop]\n          },\n        }) as SingleRowRefProxy<T>\n\n        const result = whereCallback(simpleProxy)\n        return result\n      } catch {\n        // If both approaches fail, exclude the item\n        return false\n      }\n    }\n  }\n}\n\n/**\n * Creates a filter function from a pre-compiled expression\n * @param expression - The pre-compiled expression to evaluate\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunctionFromExpression<T extends object>(\n  expression: BasicExpression<boolean>\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      return Boolean(result)\n    } catch {\n      // If evaluation fails, exclude the item\n      return false\n    }\n  }\n}\n\n/**\n * Creates a filtered callback that only calls the original callback with changes that match the where clause\n * @param originalCallback - The original callback to filter\n * @param options - The subscription options containing the where clause\n * @returns A filtered callback function\n */\nexport function createFilteredCallback<T extends object>(\n  originalCallback: (changes: Array<ChangeMessage<T>>) => void,\n  options: SubscribeChangesOptions\n): (changes: Array<ChangeMessage<T>>) => void {\n  const filterFn = createFilterFunctionFromExpression(options.whereExpression!)\n\n  return (changes: Array<ChangeMessage<T>>) => {\n    const filteredChanges: Array<ChangeMessage<T>> = []\n\n    for (const change of changes) {\n      if (change.type === `insert`) {\n        // For inserts, check if the new value matches the filter\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      } else if (change.type === `update`) {\n        // For updates, we need to check both old and new values\n        const newValueMatches = filterFn(change.value)\n        const oldValueMatches = change.previousValue\n          ? filterFn(change.previousValue)\n          : false\n\n        if (newValueMatches && oldValueMatches) {\n          // Both old and new match: emit update\n          filteredChanges.push(change)\n        } else if (newValueMatches && !oldValueMatches) {\n          // New matches but old didn't: emit insert\n          filteredChanges.push({\n            ...change,\n            type: `insert`,\n          })\n        } else if (!newValueMatches && oldValueMatches) {\n          // Old matched but new doesn't: emit delete\n          filteredChanges.push({\n            ...change,\n            type: `delete`,\n            value: change.previousValue!, // Use the previous value for the delete\n          })\n        }\n        // If neither matches, don't emit anything\n      } else {\n        // For deletes, include if the previous value would have matched\n        // (so subscribers know something they were tracking was deleted)\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      }\n    }\n\n    // Always call the original callback if we have filtered changes OR\n    // if the original changes array was empty (which indicates a ready signal)\n    if (filteredChanges.length > 0 || changes.length === 0) {\n      originalCallback(filteredChanges)\n    }\n  }\n}\n\n/**\n * Gets ordered keys from a collection using index optimization when possible\n * @param collection - The collection to get keys from\n * @param orderBy - The order by clause\n * @param limit - Optional limit on number of keys to return\n * @param whereFilter - Optional filter function to apply while traversing\n * @returns Array of keys in sorted order\n */\nfunction getOrderedKeys<T extends object, TKey extends string | number>(\n  collection: CollectionLike<T, TKey>,\n  orderBy: OrderBy,\n  limit?: number,\n  whereFilter?: (item: T) => boolean,\n  optimizedOnly?: boolean\n): Array<TKey> | undefined {\n  // For single-column orderBy on a ref expression, try index optimization\n  if (orderBy.length === 1) {\n    const clause = orderBy[0]!\n    const orderByExpression = clause.expression\n\n    if (orderByExpression.type === `ref`) {\n      const propRef = orderByExpression\n      const fieldPath = propRef.path\n\n      // Ensure index exists for this field\n      ensureIndexForField(\n        fieldPath[0]!,\n        fieldPath,\n        collection as CollectionImpl<T, TKey>,\n        clause.compareOptions\n      )\n\n      // Find the index\n      const index = findIndexForField(\n        collection.indexes,\n        fieldPath,\n        clause.compareOptions\n      )\n\n      if (index && index.supports(`gt`)) {\n        // Use index optimization\n        const filterFn = (key: TKey): boolean => {\n          const value = collection.get(key)\n          if (value === undefined) {\n            return false\n          }\n          return whereFilter?.(value) ?? true\n        }\n\n        // Take the keys that match the filter and limit\n        // if no limit is provided `index.keyCount` is used,\n        // i.e. we will take all keys that match the filter\n        return index.take(limit ?? index.keyCount, undefined, filterFn)\n      }\n    }\n  }\n\n  if (optimizedOnly) {\n    return\n  }\n\n  // Fallback: collect all items and sort in memory\n  const allItems: Array<{ key: TKey; value: T }> = []\n  for (const [key, value] of collection.entries()) {\n    if (whereFilter?.(value) ?? true) {\n      allItems.push({ key, value })\n    }\n  }\n\n  // Sort using makeComparator\n  const compare = (a: { key: TKey; value: T }, b: { key: TKey; value: T }) => {\n    for (const clause of orderBy) {\n      const compareFn = makeComparator(clause.compareOptions)\n\n      // Extract values for comparison\n      const aValue = extractValueFromItem(a.value, clause.expression)\n      const bValue = extractValueFromItem(b.value, clause.expression)\n\n      const result = compareFn(aValue, bValue)\n      if (result !== 0) {\n        return result\n      }\n    }\n    return 0\n  }\n\n  allItems.sort(compare)\n  const sortedKeys = allItems.map((item) => item.key)\n\n  // Apply limit if provided\n  if (limit !== undefined) {\n    return sortedKeys.slice(0, limit)\n  }\n\n  // if no limit is provided, we will return all keys\n  return sortedKeys\n}\n\n/**\n * Helper function to extract a value from an item based on an expression\n */\nfunction extractValueFromItem(item: any, expression: BasicExpression): any {\n  if (expression.type === `ref`) {\n    const propRef = expression\n    let value = item\n    for (const pathPart of propRef.path) {\n      value = value?.[pathPart]\n    }\n    return value\n  } else if (expression.type === `val`) {\n    return expression.value\n  } else {\n    // It must be a function\n    const evaluator = compileSingleRowExpression(expression)\n    return evaluator(item as Record<string, unknown>)\n  }\n}\n"],"names":[],"mappings":";;;;AA+DO,SAAS,sBAId,YACA,UAAwC,IACR;AAEhC,QAAM,yBAAyB,CAC7B,aAC4B;AAC5B,UAAM,SAAkC,CAAA;AACxC,eAAW,CAAC,KAAK,KAAK,KAAK,WAAW,WAAW;AAE/C,UAAI,WAAW,KAAK,KAAK,MAAM;AAC7B,eAAO,KAAK;AAAA,UACV,MAAM;AAAA,UACN;AAAA,UACA;AAAA,QAAA,CACD;AAAA,MACH;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAGA,MAAI,QAAQ,UAAU,UAAa,CAAC,QAAQ,SAAS;AACnD,UAAM,IAAI,MAAM,sCAAsC;AAAA,EACxD;AAGA,MAAI,QAAQ,SAAS;AAEnB,UAAM,cAAc,QAAQ,QACxB,mCAAmC,QAAQ,KAAK,IAChD;AAGJ,UAAM,cAAc;AAAA,MAClB;AAAA,MACA,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR;AAAA,MACA,QAAQ;AAAA,IAAA;AAGV,QAAI,gBAAgB,QAAW;AAE7B;AAAA,IACF;AAGA,UAAM,SAAkC,CAAA;AACxC,eAAW,OAAO,aAAa;AAC7B,YAAM,QAAQ,WAAW,IAAI,GAAG;AAChC,UAAI,UAAU,QAAW;AACvB,eAAO,KAAK;AAAA,UACV,MAAM;AAAA,UACN;AAAA,UACA;AAAA,QAAA,CACD;AAAA,MACH;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAGA,MAAI,CAAC,QAAQ,OAAO;AAElB,WAAO,uBAAA;AAAA,EACT;AAGA,MAAI;AACF,UAAM,aAAuC,QAAQ;AAGrD,UAAM,qBAAqB;AAAA,MACzB;AAAA,MACA,WAAW;AAAA,IAAA;AAGb,QAAI,mBAAmB,aAAa;AAElC,YAAM,SAAkC,CAAA;AACxC,iBAAW,OAAO,mBAAmB,cAAc;AACjD,cAAM,QAAQ,WAAW,IAAI,GAAG;AAChC,YAAI,UAAU,QAAW;AACvB,iBAAO,KAAK;AAAA,YACV,MAAM;AAAA,YACN;AAAA,YACA;AAAA,UAAA,CACD;AAAA,QACH;AAAA,MACF;AACA,aAAO;AAAA,IACT,OAAO;AACL,UAAI,QAAQ,eAAe;AACzB;AAAA,MACF;AAEA,YAAM,WAAW,mCAAmC,UAAU;AAC9D,aAAO,uBAAuB,QAAQ;AAAA,IACxC;AAAA,EACF,SAAS,OAAO;AAEd,YAAQ;AAAA,MACN,GAAG,WAAW,KAAK,IAAI,WAAW,EAAE,OAAO,EAAE;AAAA,MAC7C;AAAA,IAAA;AAGF,UAAM,WAAW,mCAAmC,QAAQ,KAAK;AAEjE,QAAI,QAAQ,eAAe;AACzB;AAAA,IACF;AAEA,WAAO,uBAAuB,QAAQ;AAAA,EACxC;AACF;AA6CO,SAAS,mCACd,YACsB;AACtB,SAAO,CAAC,SAAqB;AAC3B,QAAI;AACF,YAAM,YAAY,2BAA2B,UAAU;AACvD,YAAM,SAAS,UAAU,IAA+B;AACxD,aAAO,QAAQ,MAAM;AAAA,IACvB,QAAQ;AAEN,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAQO,SAAS,uBACd,kBACA,SAC4C;AAC5C,QAAM,WAAW,mCAAmC,QAAQ,eAAgB;AAE5E,SAAO,CAAC,YAAqC;AAC3C,UAAM,kBAA2C,CAAA;AAEjD,eAAW,UAAU,SAAS;AAC5B,UAAI,OAAO,SAAS,UAAU;AAE5B,YAAI,SAAS,OAAO,KAAK,GAAG;AAC1B,0BAAgB,KAAK,MAAM;AAAA,QAC7B;AAAA,MACF,WAAW,OAAO,SAAS,UAAU;AAEnC,cAAM,kBAAkB,SAAS,OAAO,KAAK;AAC7C,cAAM,kBAAkB,OAAO,gBAC3B,SAAS,OAAO,aAAa,IAC7B;AAEJ,YAAI,mBAAmB,iBAAiB;AAEtC,0BAAgB,KAAK,MAAM;AAAA,QAC7B,WAAW,mBAAmB,CAAC,iBAAiB;AAE9C,0BAAgB,KAAK;AAAA,YACnB,GAAG;AAAA,YACH,MAAM;AAAA,UAAA,CACP;AAAA,QACH,WAAW,CAAC,mBAAmB,iBAAiB;AAE9C,0BAAgB,KAAK;AAAA,YACnB,GAAG;AAAA,YACH,MAAM;AAAA,YACN,OAAO,OAAO;AAAA;AAAA,UAAA,CACf;AAAA,QACH;AAAA,MAEF,OAAO;AAGL,YAAI,SAAS,OAAO,KAAK,GAAG;AAC1B,0BAAgB,KAAK,MAAM;AAAA,QAC7B;AAAA,MACF;AAAA,IACF;AAIA,QAAI,gBAAgB,SAAS,KAAK,QAAQ,WAAW,GAAG;AACtD,uBAAiB,eAAe;AAAA,IAClC;AAAA,EACF;AACF;AAUA,SAAS,eACP,YACA,SACA,OACA,aACA,eACyB;AAEzB,MAAI,QAAQ,WAAW,GAAG;AACxB,UAAM,SAAS,QAAQ,CAAC;AACxB,UAAM,oBAAoB,OAAO;AAEjC,QAAI,kBAAkB,SAAS,OAAO;AACpC,YAAM,UAAU;AAChB,YAAM,YAAY,QAAQ;AAG1B;AAAA,QACE,UAAU,CAAC;AAAA,QACX;AAAA,QACA;AAAA,QACA,OAAO;AAAA,MAAA;AAIT,YAAM,QAAQ;AAAA,QACZ,WAAW;AAAA,QACX;AAAA,QACA,OAAO;AAAA,MAAA;AAGT,UAAI,SAAS,MAAM,SAAS,IAAI,GAAG;AAEjC,cAAM,WAAW,CAAC,QAAuB;AACvC,gBAAM,QAAQ,WAAW,IAAI,GAAG;AAChC,cAAI,UAAU,QAAW;AACvB,mBAAO;AAAA,UACT;AACA,iBAAO,cAAc,KAAK,KAAK;AAAA,QACjC;AAKA,eAAO,MAAM,KAAK,SAAS,MAAM,UAAU,QAAW,QAAQ;AAAA,MAChE;AAAA,IACF;AAAA,EACF;AAEA,MAAI,eAAe;AACjB;AAAA,EACF;AAGA,QAAM,WAA2C,CAAA;AACjD,aAAW,CAAC,KAAK,KAAK,KAAK,WAAW,WAAW;AAC/C,QAAI,cAAc,KAAK,KAAK,MAAM;AAChC,eAAS,KAAK,EAAE,KAAK,MAAA,CAAO;AAAA,IAC9B;AAAA,EACF;AAGA,QAAM,UAAU,CAAC,GAA4B,MAA+B;AAC1E,eAAW,UAAU,SAAS;AAC5B,YAAM,YAAY,eAAe,OAAO,cAAc;AAGtD,YAAM,SAAS,qBAAqB,EAAE,OAAO,OAAO,UAAU;AAC9D,YAAM,SAAS,qBAAqB,EAAE,OAAO,OAAO,UAAU;AAE9D,YAAM,SAAS,UAAU,QAAQ,MAAM;AACvC,UAAI,WAAW,GAAG;AAChB,eAAO;AAAA,MACT;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,WAAS,KAAK,OAAO;AACrB,QAAM,aAAa,SAAS,IAAI,CAAC,SAAS,KAAK,GAAG;AAGlD,MAAI,UAAU,QAAW;AACvB,WAAO,WAAW,MAAM,GAAG,KAAK;AAAA,EAClC;AAGA,SAAO;AACT;AAKA,SAAS,qBAAqB,MAAW,YAAkC;AACzE,MAAI,WAAW,SAAS,OAAO;AAC7B,UAAM,UAAU;AAChB,QAAI,QAAQ;AACZ,eAAW,YAAY,QAAQ,MAAM;AACnC,cAAQ,QAAQ,QAAQ;AAAA,IAC1B;AACA,WAAO;AAAA,EACT,WAAW,WAAW,SAAS,OAAO;AACpC,WAAO,WAAW;AAAA,EACpB,OAAO;AAEL,UAAM,YAAY,2BAA2B,UAAU;AACvD,WAAO,UAAU,IAA+B;AAAA,EAClD;AACF;"}
+{"version":3,"file":"change-events.js","sources":["../../../src/collection/change-events.ts"],"sourcesContent":["import {\n  createSingleRowRefProxy,\n  toExpression,\n} from \"../query/builder/ref-proxy\"\nimport {\n  compileSingleRowExpression,\n  toBooleanPredicate,\n} from \"../query/compiler/evaluators.js\"\nimport {\n  findIndexForField,\n  optimizeExpressionWithIndexes,\n} from \"../utils/index-optimization.js\"\nimport { ensureIndexForField } from \"../indexes/auto-index.js\"\nimport { makeComparator } from \"../utils/comparison.js\"\nimport { buildCompareOptions } from \"../query/compiler/order-by\"\nimport type {\n  ChangeMessage,\n  CollectionLike,\n  CurrentStateAsChangesOptions,\n  SubscribeChangesOptions,\n} from \"../types\"\nimport type { CollectionImpl } from \"./index.js\"\nimport type { SingleRowRefProxy } from \"../query/builder/ref-proxy\"\nimport type { BasicExpression, OrderBy } from \"../query/ir.js\"\n\n/**\n * Returns the current state of the collection as an array of changes\n * @param collection - The collection to get changes from\n * @param options - Options including optional where filter, orderBy, and limit\n * @returns An array of changes\n * @example\n * // Get all items as changes\n * const allChanges = currentStateAsChanges(collection)\n *\n * // Get only items matching a condition\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: (row) => row.status === 'active'\n * })\n *\n * // Get only items using a pre-compiled expression\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active')\n * })\n *\n * // Get items ordered by name with limit\n * const topUsers = currentStateAsChanges(collection, {\n *   orderBy: [{ expression: row.name, compareOptions: { direction: 'asc' } }],\n *   limit: 10\n * })\n *\n * // Get active users ordered by score (highest score first)\n * const topActiveUsers = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active'),\n *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],\n * })\n */\nexport function currentStateAsChanges<\n  T extends object,\n  TKey extends string | number,\n>(\n  collection: CollectionLike<T, TKey>,\n  options: CurrentStateAsChangesOptions = {}\n): Array<ChangeMessage<T>> | void {\n  // Helper function to collect filtered results\n  const collectFilteredResults = (\n    filterFn?: (value: T) => boolean\n  ): Array<ChangeMessage<T>> => {\n    const result: Array<ChangeMessage<T>> = []\n    for (const [key, value] of collection.entries()) {\n      // If no filter function is provided, include all items\n      if (filterFn?.(value) ?? true) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // Validate that limit without orderBy doesn't happen\n  if (options.limit !== undefined && !options.orderBy) {\n    throw new Error(`limit cannot be used without orderBy`)\n  }\n\n  // First check if orderBy is present (optionally with limit)\n  if (options.orderBy) {\n    // Create where filter function if present\n    const whereFilter = options.where\n      ? createFilterFunctionFromExpression(options.where)\n      : undefined\n\n    // Get ordered keys using index optimization when possible\n    const orderedKeys = getOrderedKeys(\n      collection,\n      options.orderBy,\n      options.limit,\n      whereFilter,\n      options.optimizedOnly\n    )\n\n    if (orderedKeys === undefined) {\n      // `getOrderedKeys` returned undefined because we asked for `optimizedOnly` and there was no index to use\n      return\n    }\n\n    // Convert keys to change messages\n    const result: Array<ChangeMessage<T>> = []\n    for (const key of orderedKeys) {\n      const value = collection.get(key)\n      if (value !== undefined) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // If no orderBy OR orderBy optimization failed, use where clause optimization\n  if (!options.where) {\n    // No filtering, return all items\n    return collectFilteredResults()\n  }\n\n  // There's a where clause, let's see if we can use an index\n  try {\n    const expression: BasicExpression<boolean> = options.where\n\n    // Try to optimize the query using indexes\n    const optimizationResult = optimizeExpressionWithIndexes(\n      expression,\n      collection\n    )\n\n    if (optimizationResult.canOptimize) {\n      // Use index optimization\n      const result: Array<ChangeMessage<T>> = []\n      for (const key of optimizationResult.matchingKeys) {\n        const value = collection.get(key)\n        if (value !== undefined) {\n          result.push({\n            type: `insert`,\n            key,\n            value,\n          })\n        }\n      }\n      return result\n    } else {\n      if (options.optimizedOnly) {\n        return\n      }\n\n      const filterFn = createFilterFunctionFromExpression(expression)\n      return collectFilteredResults(filterFn)\n    }\n  } catch (error) {\n    // If anything goes wrong with the where clause, fall back to full scan\n    console.warn(\n      `${collection.id ? `[${collection.id}] ` : ``}Error processing where clause, falling back to full scan:`,\n      error\n    )\n\n    const filterFn = createFilterFunctionFromExpression(options.where)\n\n    if (options.optimizedOnly) {\n      return\n    }\n\n    return collectFilteredResults(filterFn)\n  }\n}\n\n/**\n * Creates a filter function from a where callback\n * @param whereCallback - The callback function that defines the filter condition\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunction<T extends object>(\n  whereCallback: (row: SingleRowRefProxy<T>) => any\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      // First try the RefProxy approach for query builder functions\n      const singleRowRefProxy = createSingleRowRefProxy<T>()\n      const whereExpression = whereCallback(singleRowRefProxy)\n      const expression = toExpression(whereExpression)\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      // WHERE clauses should always evaluate to boolean predicates (Kevin's feedback)\n      return toBooleanPredicate(result)\n    } catch {\n      // If RefProxy approach fails (e.g., arithmetic operations), fall back to direct evaluation\n      try {\n        // Create a simple proxy that returns actual values for arithmetic operations\n        const simpleProxy = new Proxy(item as any, {\n          get(target, prop) {\n            return target[prop]\n          },\n        }) as SingleRowRefProxy<T>\n\n        const result = whereCallback(simpleProxy)\n        return toBooleanPredicate(result)\n      } catch {\n        // If both approaches fail, exclude the item\n        return false\n      }\n    }\n  }\n}\n\n/**\n * Creates a filter function from a pre-compiled expression\n * @param expression - The pre-compiled expression to evaluate\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunctionFromExpression<T extends object>(\n  expression: BasicExpression<boolean>\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      return toBooleanPredicate(result)\n    } catch {\n      // If evaluation fails, exclude the item\n      return false\n    }\n  }\n}\n\n/**\n * Creates a filtered callback that only calls the original callback with changes that match the where clause\n * @param originalCallback - The original callback to filter\n * @param options - The subscription options containing the where clause\n * @returns A filtered callback function\n */\nexport function createFilteredCallback<T extends object>(\n  originalCallback: (changes: Array<ChangeMessage<T>>) => void,\n  options: SubscribeChangesOptions\n): (changes: Array<ChangeMessage<T>>) => void {\n  const filterFn = createFilterFunctionFromExpression(options.whereExpression!)\n\n  return (changes: Array<ChangeMessage<T>>) => {\n    const filteredChanges: Array<ChangeMessage<T>> = []\n\n    for (const change of changes) {\n      if (change.type === `insert`) {\n        // For inserts, check if the new value matches the filter\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      } else if (change.type === `update`) {\n        // For updates, we need to check both old and new values\n        const newValueMatches = filterFn(change.value)\n        const oldValueMatches = change.previousValue\n          ? filterFn(change.previousValue)\n          : false\n\n        if (newValueMatches && oldValueMatches) {\n          // Both old and new match: emit update\n          filteredChanges.push(change)\n        } else if (newValueMatches && !oldValueMatches) {\n          // New matches but old didn't: emit insert\n          filteredChanges.push({\n            ...change,\n            type: `insert`,\n          })\n        } else if (!newValueMatches && oldValueMatches) {\n          // Old matched but new doesn't: emit delete\n          filteredChanges.push({\n            ...change,\n            type: `delete`,\n            value: change.previousValue!, // Use the previous value for the delete\n          })\n        }\n        // If neither matches, don't emit anything\n      } else {\n        // For deletes, include if the previous value would have matched\n        // (so subscribers know something they were tracking was deleted)\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      }\n    }\n\n    // Always call the original callback if we have filtered changes OR\n    // if the original changes array was empty (which indicates a ready signal)\n    if (filteredChanges.length > 0 || changes.length === 0) {\n      originalCallback(filteredChanges)\n    }\n  }\n}\n\n/**\n * Gets ordered keys from a collection using index optimization when possible\n * @param collection - The collection to get keys from\n * @param orderBy - The order by clause\n * @param limit - Optional limit on number of keys to return\n * @param whereFilter - Optional filter function to apply while traversing\n * @returns Array of keys in sorted order\n */\nfunction getOrderedKeys<T extends object, TKey extends string | number>(\n  collection: CollectionLike<T, TKey>,\n  orderBy: OrderBy,\n  limit?: number,\n  whereFilter?: (item: T) => boolean,\n  optimizedOnly?: boolean\n): Array<TKey> | undefined {\n  // For single-column orderBy on a ref expression, try index optimization\n  if (orderBy.length === 1) {\n    const clause = orderBy[0]!\n    const orderByExpression = clause.expression\n\n    if (orderByExpression.type === `ref`) {\n      const propRef = orderByExpression\n      const fieldPath = propRef.path\n      const compareOpts = buildCompareOptions(clause, collection)\n\n      // Ensure index exists for this field\n      ensureIndexForField(\n        fieldPath[0]!,\n        fieldPath,\n        collection as CollectionImpl<T, TKey>,\n        compareOpts\n      )\n\n      // Find the index\n      const index = findIndexForField(collection, fieldPath, compareOpts)\n\n      if (index && index.supports(`gt`)) {\n        // Use index optimization\n        const filterFn = (key: TKey): boolean => {\n          const value = collection.get(key)\n          if (value === undefined) {\n            return false\n          }\n          return whereFilter?.(value) ?? true\n        }\n\n        // Take the keys that match the filter and limit\n        // if no limit is provided `index.keyCount` is used,\n        // i.e. we will take all keys that match the filter\n        return index.take(limit ?? index.keyCount, undefined, filterFn)\n      }\n    }\n  }\n\n  if (optimizedOnly) {\n    return\n  }\n\n  // Fallback: collect all items and sort in memory\n  const allItems: Array<{ key: TKey; value: T }> = []\n  for (const [key, value] of collection.entries()) {\n    if (whereFilter?.(value) ?? true) {\n      allItems.push({ key, value })\n    }\n  }\n\n  // Sort using makeComparator\n  const compare = (a: { key: TKey; value: T }, b: { key: TKey; value: T }) => {\n    for (const clause of orderBy) {\n      const compareFn = makeComparator(clause.compareOptions)\n\n      // Extract values for comparison\n      const aValue = extractValueFromItem(a.value, clause.expression)\n      const bValue = extractValueFromItem(b.value, clause.expression)\n\n      const result = compareFn(aValue, bValue)\n      if (result !== 0) {\n        return result\n      }\n    }\n    return 0\n  }\n\n  allItems.sort(compare)\n  const sortedKeys = allItems.map((item) => item.key)\n\n  // Apply limit if provided\n  if (limit !== undefined) {\n    return sortedKeys.slice(0, limit)\n  }\n\n  // if no limit is provided, we will return all keys\n  return sortedKeys\n}\n\n/**\n * Helper function to extract a value from an item based on an expression\n */\nfunction extractValueFromItem(item: any, expression: BasicExpression): any {\n  if (expression.type === `ref`) {\n    const propRef = expression\n    let value = item\n    for (const pathPart of propRef.path) {\n      value = value?.[pathPart]\n    }\n    return value\n  } else if (expression.type === `val`) {\n    return expression.value\n  } else {\n    // It must be a function\n    const evaluator = compileSingleRowExpression(expression)\n    return evaluator(item as Record<string, unknown>)\n  }\n}\n"],"names":[],"mappings":"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"}

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

@@ -5,7 +5,7 @@ import { CollectionSubscription } from './subscription.js';
 import { AllCollectionEvents, CollectionEventHandler } from './events.js';
 import { BaseIndex, IndexResolver } from '../indexes/base-index.js';
 import { IndexOptions } from '../indexes/index-options.js';
-import { ChangeMessage, CollectionConfig, CollectionStatus, CurrentStateAsChangesOptions, Fn, InferSchemaInput, InferSchemaOutput, InsertConfig, NonSingleResult, OperationConfig, SingleResult, SubscribeChangesOptions, Transaction as TransactionType, UtilsRecord, WritableDeep } from '../types.js';
+import { ChangeMessage, CollectionConfig, CollectionStatus, CurrentStateAsChangesOptions, Fn, InferSchemaInput, InferSchemaOutput, InsertConfig, NonSingleResult, OperationConfig, SingleResult, StringCollationConfig, SubscribeChangesOptions, Transaction as TransactionType, UtilsRecord, WritableDeep } from '../types.js';
 import { SingleRowRefProxy } from '../query/builder/ref-proxy.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { BTreeIndex } from '../indexes/btree-index.js';
@@ -91,19 +91,19 @@ export interface Collection<T extends object = Record<string, unknown>, TKey ext
  * })
  *
  */
-export declare function createCollection<T extends StandardSchemaV1, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+export declare function createCollection<T extends StandardSchemaV1, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<InferSchemaOutput<T>, TKey, T, TUtils> & {
     schema: T;
     utils?: TUtils;
 } & NonSingleResult): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & NonSingleResult;
-export declare function createCollection<T extends StandardSchemaV1, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+export declare function createCollection<T extends StandardSchemaV1, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<InferSchemaOutput<T>, TKey, T, TUtils> & {
     schema: T;
     utils?: TUtils;
 } & SingleResult): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & SingleResult;
-export declare function createCollection<T extends object, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<T, TKey, never> & {
+export declare function createCollection<T extends object, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<T, TKey, never, TUtils> & {
     schema?: never;
     utils?: TUtils;
 } & NonSingleResult): Collection<T, TKey, TUtils, never, T> & NonSingleResult;
-export declare function createCollection<T extends object, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<T, TKey, never> & {
+export declare function createCollection<T extends object, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<T, TKey, never, TUtils> & {
     schema?: never;
     utils?: TUtils;
 } & SingleResult): Collection<T, TKey, TUtils, never, T> & SingleResult;
@@ -118,6 +118,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
     private _indexes;
     private _mutations;
     _state: CollectionStateManager<TOutput, TKey, TSchema, TInput>;
+    private comparisonOpts;
     /**
      * Creates a new Collection instance
      *
@@ -251,6 +252,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * Validates the data against the schema
      */
     validateData(data: unknown, type: `insert` | `update`, key?: TKey): TOutput | never;
+    get compareOptions(): StringCollationConfig;
     /**
      * Inserts one or more items into the collection
      * @param items - Single item or array of items to insert

package/dist/esm/collection/index.js

@@ -12,7 +12,7 @@ function createCollection(options) {
     options
   );
   if (options.utils) {
-    collection.utils = { ...options.utils };
+    collection.utils = options.utils;
   } else {
     collection.utils = {};
   }
@@ -55,6 +55,7 @@ class CollectionImpl {
     this._mutations = new CollectionMutationsManager(config, this.id);
     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
@@ -267,6 +268,9 @@ class CollectionImpl {
   validateData(data, type, key) {
     return this._mutations.validateData(data, type, key);
   }
+  get compareOptions() {
+    return { ...this.comparisonOpts };
+  }
   update(keys, configOrCallback, maybeCallback) {
     return this._mutations.update(keys, configOrCallback, maybeCallback);
   }
@@ -421,6 +425,20 @@ class CollectionImpl {
     return Promise.resolve();
   }
 }
+function buildCompareOptionsFromConfig(config) {
+  if (config.defaultStringCollation) {
+    const options = config.defaultStringCollation;
+    return {
+      stringSort: options.stringSort ?? `locale`,
+      locale: options.stringSort === `locale` ? options.locale : void 0,
+      localeOptions: options.stringSort === `locale` ? options.localeOptions : void 0
+    };
+  } else {
+    return {
+      stringSort: `locale`
+    };
+  }
+}
 export {
   CollectionImpl,
   createCollection