@tanstack/db 0.5.10 → 0.5.12

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 { 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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"}
+{"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":";;AAmCO,SAAS,kBACd,YACA,WACA,gBACkC;AAClC,QAAM,cAAc,kBAAkB;AAAA,IACpC,GAAG;AAAA,IACH,GAAG,WAAW;AAAA,EAAA;AAGhB,aAAW,SAAS,WAAW,QAAQ,OAAA,GAAU;AAC/C,QACE,MAAM,aAAa,SAAS,KAC5B,MAAM,sBAAsB,WAAW,GACvC;AACA,UAAI,CAAC,MAAM,iBAAiB,YAAY,SAAS,GAAG;AAClD,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,8BAId,YACA,YAC0B;AAC1B,SAAO,uBAAuB,YAAY,UAAU;AACtD;AAKA,SAAS,uBACP,YACA,YAC0B;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,UAAU;AAAA,MAExD,KAAK;AACH,eAAO,sBAAsB,YAAY,UAAU;AAAA,MAErD,KAAK;AACH,eAAO,qBAAqB,YAAY,UAAU;AAAA,MAEpD,KAAK;AACH,eAAO,0BAA0B,YAAY,UAAU;AAAA,IAAA;AAAA,EAE7D;AAEA,SAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AACrD;AAoCA,SAAS,2BAIP,YACA,YAC0B;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,YAAY,SAAS;AAErD,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,yBAIP,YACA,YAC0B;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,YAAY,SAAS;AAErD,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,YAC0B;AAC1B,MAAI,WAAW,SAAS,UAAU,WAAW,KAAK,SAAS,GAAG;AAC5D,WAAO,EAAE,aAAa,OAAO,cAAc,oBAAI,MAAI;AAAA,EACrD;AAGA,QAAM,sBAAsB,2BAA2B,YAAY,UAAU;AAC7E,MAAI,oBAAoB,aAAa;AACnC,WAAO;AAAA,EACT;AAEA,QAAM,UAA2C,CAAA;AAGjD,aAAW,OAAO,WAAW,MAAM;AACjC,UAAM,SAAS,uBAAuB,KAAK,UAAU;AACrD,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,YAC0B;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,UAAU;AACrD,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,0BAIP,YACA,YAC0B;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,YAAY,SAAS;AAErD,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;"}

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["/**\n * Generic utility functions\n */\n\nimport type { CompareOptions } from \"./query/builder/types\"\n\ninterface TypedArray {\n  length: number\n  [index: number]: number\n}\n\n/**\n * Deep equality function that compares two values recursively\n * Handles primitives, objects, arrays, Date, RegExp, Map, Set, TypedArrays, and Temporal objects\n *\n * @param a - First value to compare\n * @param b - Second value to compare\n * @returns True if the values are deeply equal, false otherwise\n *\n * @example\n * ```typescript\n * deepEquals({ a: 1, b: 2 }, { b: 2, a: 1 }) // true (property order doesn't matter)\n * deepEquals([1, { x: 2 }], [1, { x: 2 }]) // true\n * deepEquals({ a: 1 }, { a: 2 }) // false\n * deepEquals(new Date('2023-01-01'), new Date('2023-01-01')) // true\n * deepEquals(new Map([['a', 1]]), new Map([['a', 1]])) // true\n * ```\n */\nexport function deepEquals(a: any, b: any): boolean {\n  return deepEqualsInternal(a, b, new Map())\n}\n\n/**\n * Internal implementation with cycle detection to prevent infinite recursion\n */\nfunction deepEqualsInternal(\n  a: any,\n  b: any,\n  visited: Map<object, object>\n): boolean {\n  // Handle strict equality (primitives, same reference)\n  if (a === b) return true\n\n  // Handle null/undefined\n  if (a == null || b == null) return false\n\n  // Handle different types\n  if (typeof a !== typeof b) return false\n\n  // Handle Date objects\n  if (a instanceof Date) {\n    if (!(b instanceof Date)) return false\n    return a.getTime() === b.getTime()\n  }\n\n  // Handle RegExp objects\n  if (a instanceof RegExp) {\n    if (!(b instanceof RegExp)) return false\n    return a.source === b.source && a.flags === b.flags\n  }\n\n  // Handle Map objects - only if both are Maps\n  if (a instanceof Map) {\n    if (!(b instanceof Map)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const entries = Array.from(a.entries())\n    const result = entries.every(([key, val]) => {\n      return b.has(key) && deepEqualsInternal(val, b.get(key), visited)\n    })\n\n    visited.delete(a)\n    return result\n  }\n\n  // Handle Set objects - only if both are Sets\n  if (a instanceof Set) {\n    if (!(b instanceof Set)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Convert to arrays for comparison\n    const aValues = Array.from(a)\n    const bValues = Array.from(b)\n\n    // Simple comparison for primitive values\n    if (aValues.every((val) => typeof val !== `object`)) {\n      visited.delete(a)\n      return aValues.every((val) => b.has(val))\n    }\n\n    // For objects in sets, we need to do a more complex comparison\n    // This is a simplified approach and may not work for all cases\n    const result = aValues.length === bValues.length\n    visited.delete(a)\n    return result\n  }\n\n  // Handle TypedArrays\n  if (\n    ArrayBuffer.isView(a) &&\n    ArrayBuffer.isView(b) &&\n    !(a instanceof DataView) &&\n    !(b instanceof DataView)\n  ) {\n    const typedA = a as unknown as TypedArray\n    const typedB = b as unknown as TypedArray\n    if (typedA.length !== typedB.length) return false\n\n    for (let i = 0; i < typedA.length; i++) {\n      if (typedA[i] !== typedB[i]) return false\n    }\n\n    return true\n  }\n\n  // Handle Temporal objects\n  // Check if both are Temporal objects of the same type\n  if (isTemporal(a) && isTemporal(b)) {\n    const aTag = getStringTag(a)\n    const bTag = getStringTag(b)\n\n    // If they're different Temporal types, they're not equal\n    if (aTag !== bTag) return false\n\n    // Use Temporal's built-in equals method if available\n    if (typeof a.equals === `function`) {\n      return a.equals(b)\n    }\n\n    // Fallback to toString comparison for other types\n    return a.toString() === b.toString()\n  }\n\n  // Handle arrays\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b) || a.length !== b.length) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const result = a.every((item, index) =>\n      deepEqualsInternal(item, b[index], visited)\n    )\n    visited.delete(a)\n    return result\n  }\n\n  // Handle objects\n  if (typeof a === `object`) {\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Get all keys from both objects\n    const keysA = Object.keys(a)\n    const keysB = Object.keys(b)\n\n    // Check if they have the same number of keys\n    if (keysA.length !== keysB.length) {\n      visited.delete(a)\n      return false\n    }\n\n    // Check if all keys exist in both objects and their values are equal\n    const result = keysA.every(\n      (key) => key in b && deepEqualsInternal(a[key], b[key], visited)\n    )\n\n    visited.delete(a)\n    return result\n  }\n\n  // For primitives that aren't strictly equal\n  return false\n}\n\nconst temporalTypes = [\n  `Temporal.Duration`,\n  `Temporal.Instant`,\n  `Temporal.PlainDate`,\n  `Temporal.PlainDateTime`,\n  `Temporal.PlainMonthDay`,\n  `Temporal.PlainTime`,\n  `Temporal.PlainYearMonth`,\n  `Temporal.ZonedDateTime`,\n]\n\nfunction getStringTag(a: any): any {\n  return a[Symbol.toStringTag]\n}\n\n/** Checks if the value is a Temporal object by checking for the Temporal brand */\nexport function isTemporal(a: any): boolean {\n  const tag = getStringTag(a)\n  return typeof tag === `string` && temporalTypes.includes(tag)\n}\n\nexport const DEFAULT_COMPARE_OPTIONS: CompareOptions = {\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["/**\n * Generic utility functions\n */\n\nimport type { CompareOptions } from './query/builder/types'\n\ninterface TypedArray {\n  length: number\n  [index: number]: number\n}\n\n/**\n * Deep equality function that compares two values recursively\n * Handles primitives, objects, arrays, Date, RegExp, Map, Set, TypedArrays, and Temporal objects\n *\n * @param a - First value to compare\n * @param b - Second value to compare\n * @returns True if the values are deeply equal, false otherwise\n *\n * @example\n * ```typescript\n * deepEquals({ a: 1, b: 2 }, { b: 2, a: 1 }) // true (property order doesn't matter)\n * deepEquals([1, { x: 2 }], [1, { x: 2 }]) // true\n * deepEquals({ a: 1 }, { a: 2 }) // false\n * deepEquals(new Date('2023-01-01'), new Date('2023-01-01')) // true\n * deepEquals(new Map([['a', 1]]), new Map([['a', 1]])) // true\n * ```\n */\nexport function deepEquals(a: any, b: any): boolean {\n  return deepEqualsInternal(a, b, new Map())\n}\n\n/**\n * Internal implementation with cycle detection to prevent infinite recursion\n */\nfunction deepEqualsInternal(\n  a: any,\n  b: any,\n  visited: Map<object, object>,\n): boolean {\n  // Handle strict equality (primitives, same reference)\n  if (a === b) return true\n\n  // Handle null/undefined\n  if (a == null || b == null) return false\n\n  // Handle different types\n  if (typeof a !== typeof b) return false\n\n  // Handle Date objects\n  if (a instanceof Date) {\n    if (!(b instanceof Date)) return false\n    return a.getTime() === b.getTime()\n  }\n\n  // Handle RegExp objects\n  if (a instanceof RegExp) {\n    if (!(b instanceof RegExp)) return false\n    return a.source === b.source && a.flags === b.flags\n  }\n\n  // Handle Map objects - only if both are Maps\n  if (a instanceof Map) {\n    if (!(b instanceof Map)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const entries = Array.from(a.entries())\n    const result = entries.every(([key, val]) => {\n      return b.has(key) && deepEqualsInternal(val, b.get(key), visited)\n    })\n\n    visited.delete(a)\n    return result\n  }\n\n  // Handle Set objects - only if both are Sets\n  if (a instanceof Set) {\n    if (!(b instanceof Set)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Convert to arrays for comparison\n    const aValues = Array.from(a)\n    const bValues = Array.from(b)\n\n    // Simple comparison for primitive values\n    if (aValues.every((val) => typeof val !== `object`)) {\n      visited.delete(a)\n      return aValues.every((val) => b.has(val))\n    }\n\n    // For objects in sets, we need to do a more complex comparison\n    // This is a simplified approach and may not work for all cases\n    const result = aValues.length === bValues.length\n    visited.delete(a)\n    return result\n  }\n\n  // Handle TypedArrays\n  if (\n    ArrayBuffer.isView(a) &&\n    ArrayBuffer.isView(b) &&\n    !(a instanceof DataView) &&\n    !(b instanceof DataView)\n  ) {\n    const typedA = a as unknown as TypedArray\n    const typedB = b as unknown as TypedArray\n    if (typedA.length !== typedB.length) return false\n\n    for (let i = 0; i < typedA.length; i++) {\n      if (typedA[i] !== typedB[i]) return false\n    }\n\n    return true\n  }\n\n  // Handle Temporal objects\n  // Check if both are Temporal objects of the same type\n  if (isTemporal(a) && isTemporal(b)) {\n    const aTag = getStringTag(a)\n    const bTag = getStringTag(b)\n\n    // If they're different Temporal types, they're not equal\n    if (aTag !== bTag) return false\n\n    // Use Temporal's built-in equals method if available\n    if (typeof a.equals === `function`) {\n      return a.equals(b)\n    }\n\n    // Fallback to toString comparison for other types\n    return a.toString() === b.toString()\n  }\n\n  // Handle arrays\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b) || a.length !== b.length) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const result = a.every((item, index) =>\n      deepEqualsInternal(item, b[index], visited),\n    )\n    visited.delete(a)\n    return result\n  }\n\n  // Handle objects\n  if (typeof a === `object`) {\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Get all keys from both objects\n    const keysA = Object.keys(a)\n    const keysB = Object.keys(b)\n\n    // Check if they have the same number of keys\n    if (keysA.length !== keysB.length) {\n      visited.delete(a)\n      return false\n    }\n\n    // Check if all keys exist in both objects and their values are equal\n    const result = keysA.every(\n      (key) => key in b && deepEqualsInternal(a[key], b[key], visited),\n    )\n\n    visited.delete(a)\n    return result\n  }\n\n  // For primitives that aren't strictly equal\n  return false\n}\n\nconst temporalTypes = [\n  `Temporal.Duration`,\n  `Temporal.Instant`,\n  `Temporal.PlainDate`,\n  `Temporal.PlainDateTime`,\n  `Temporal.PlainMonthDay`,\n  `Temporal.PlainTime`,\n  `Temporal.PlainYearMonth`,\n  `Temporal.ZonedDateTime`,\n]\n\nfunction getStringTag(a: any): any {\n  return a[Symbol.toStringTag]\n}\n\n/** Checks if the value is a Temporal object by checking for the Temporal brand */\nexport function isTemporal(a: any): boolean {\n  const tag = getStringTag(a)\n  return typeof tag === `string` && temporalTypes.includes(tag)\n}\n\nexport const DEFAULT_COMPARE_OPTIONS: CompareOptions = {\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "@tanstack/db",
+  "version": "0.5.12",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.5.10",
-  "dependencies": {
-    "@standard-schema/spec": "^1.0.0",
-    "@tanstack/pacer-lite": "^0.1.0",
-    "@tanstack/db-ivm": "0.1.13"
-  },
-  "devDependencies": {
-    "@vitest/coverage-istanbul": "^3.2.4",
-    "arktype": "^2.1.27",
-    "superjson": "^2.2.6",
-    "temporal-polyfill": "^0.3.0"
+  "author": "Kyle Mathews",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/db.git",
+    "directory": "packages/db"
   },
+  "homepage": "https://tanstack.com/db",
+  "keywords": [
+    "optimistic",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
   "exports": {
     ".": {
       "import": {
@@ -26,35 +31,32 @@
     },
     "./package.json": "./package.json"
   },
+  "sideEffects": false,
   "files": [
     "dist",
     "src"
   ],
-  "main": "dist/cjs/index.cjs",
-  "module": "dist/esm/index.js",
+  "dependencies": {
+    "@standard-schema/spec": "^1.0.0",
+    "@tanstack/pacer-lite": "^0.1.1",
+    "@tanstack/db-ivm": "0.1.14"
+  },
   "peerDependencies": {
     "typescript": ">=4.7"
   },
-  "author": "Kyle Mathews",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/TanStack/db.git",
-    "directory": "packages/db"
+  "devDependencies": {
+    "@tanstack/config": "^0.22.2",
+    "@vitest/coverage-istanbul": "^3.2.4",
+    "arktype": "^2.1.28",
+    "mitt": "^3.0.1",
+    "superjson": "^2.2.6",
+    "temporal-polyfill": "^0.3.0"
   },
-  "homepage": "https://tanstack.com/db",
-  "keywords": [
-    "optimistic",
-    "typescript"
-  ],
-  "sideEffects": false,
-  "type": "module",
-  "types": "dist/esm/index.d.ts",
   "scripts": {
     "build": "vite build",
     "build:minified": "vite build --minify",
     "dev": "vite build --watch",
     "lint": "eslint . --fix",
-    "test": "npx vitest --run"
+    "test": "vitest --run"
   }
 }

package/src/SortedMap.ts

@@ -1,62 +1,81 @@
+import { compareKeys } from '@tanstack/db-ivm'
+
 /**
  * A Map implementation that keeps its entries sorted based on a comparator function
- * @template TKey - The type of keys in the map
+ * @template TKey - The type of keys in the map (must be string | number)
  * @template TValue - The type of values in the map
  */
-export class SortedMap<TKey, TValue> {
+export class SortedMap<TKey extends string | number, TValue> {
   private map: Map<TKey, TValue>
   private sortedKeys: Array<TKey>
-  private comparator: (a: TValue, b: TValue) => number
+  private comparator: ((a: TValue, b: TValue) => number) | undefined
 
   /**
    * Creates a new SortedMap instance
    *
-   * @param comparator - Optional function to compare values for sorting
+   * @param comparator - Optional function to compare values for sorting.
+   *                     If not provided, entries are sorted by key only.
    */
   constructor(comparator?: (a: TValue, b: TValue) => number) {
     this.map = new Map<TKey, TValue>()
     this.sortedKeys = []
-    this.comparator = comparator || this.defaultComparator
-  }
-
-  /**
-   * Default comparator function used when none is provided
-   *
-   * @param a - First value to compare
-   * @param b - Second value to compare
-   * @returns -1 if a < b, 1 if a > b, 0 if equal
-   */
-  private defaultComparator(a: TValue, b: TValue): number {
-    if (a < b) return -1
-    if (a > b) return 1
-    return 0
+    this.comparator = comparator
   }
 
   /**
    * Finds the index where a key-value pair should be inserted to maintain sort order.
-   * Uses binary search to find the correct position based on the value.
-   * Hence, it is in O(log n) time.
+   * Uses binary search to find the correct position based on the value (if comparator provided),
+   * with key-based tie-breaking for deterministic ordering when values compare as equal.
+   * If no comparator is provided, sorts by key only.
+   * Runs in O(log n) time.
    *
-   * @param key - The key to find position for
-   * @param value - The value to compare against
+   * @param key - The key to find position for (used as tie-breaker or primary sort when no comparator)
+   * @param value - The value to compare against (only used if comparator is provided)
    * @returns The index where the key should be inserted
    */
-  private indexOf(value: TValue): number {
+  private indexOf(key: TKey, value: TValue): number {
     let left = 0
     let right = this.sortedKeys.length
 
+    // Fast path: no comparator means sort by key only
+    if (!this.comparator) {
+      while (left < right) {
+        const mid = Math.floor((left + right) / 2)
+        const midKey = this.sortedKeys[mid]!
+        const keyComparison = compareKeys(key, midKey)
+        if (keyComparison < 0) {
+          right = mid
+        } else if (keyComparison > 0) {
+          left = mid + 1
+        } else {
+          return mid
+        }
+      }
+      return left
+    }
+
+    // With comparator: sort by value first, then key as tie-breaker
     while (left < right) {
       const mid = Math.floor((left + right) / 2)
       const midKey = this.sortedKeys[mid]!
       const midValue = this.map.get(midKey)!
-      const comparison = this.comparator(value, midValue)
+      const valueComparison = this.comparator(value, midValue)
 
-      if (comparison < 0) {
+      if (valueComparison < 0) {
         right = mid
-      } else if (comparison > 0) {
+      } else if (valueComparison > 0) {
         left = mid + 1
       } else {
-        return mid
+        // Values are equal, use key as tie-breaker for deterministic ordering
+        const keyComparison = compareKeys(key, midKey)
+        if (keyComparison < 0) {
+          right = mid
+        } else if (keyComparison > 0) {
+          left = mid + 1
+        } else {
+          // Same key (shouldn't happen during insert, but handle for lookups)
+          return mid
+        }
       }
     }
 
@@ -74,12 +93,12 @@ export class SortedMap<TKey, TValue> {
     if (this.map.has(key)) {
       // Need to remove the old key from the sorted keys array
       const oldValue = this.map.get(key)!
-      const oldIndex = this.indexOf(oldValue)
+      const oldIndex = this.indexOf(key, oldValue)
       this.sortedKeys.splice(oldIndex, 1)
     }
 
     // Insert the new key at the correct position
-    const index = this.indexOf(value)
+    const index = this.indexOf(key, value)
     this.sortedKeys.splice(index, 0, key)
 
     this.map.set(key, value)
@@ -106,7 +125,7 @@ export class SortedMap<TKey, TValue> {
   delete(key: TKey): boolean {
     if (this.map.has(key)) {
       const oldValue = this.map.get(key)
-      const index = this.indexOf(oldValue!)
+      const index = this.indexOf(key, oldValue!)
       this.sortedKeys.splice(index, 1)
       return this.map.delete(key)
     }
@@ -187,7 +206,7 @@ export class SortedMap<TKey, TValue> {
    * @param callbackfn - Function to execute for each entry
    */
   forEach(
-    callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void
+    callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void,
   ): void {
     for (const key of this.sortedKeys) {
       callbackfn(this.map.get(key)!, key, this.map)

package/src/collection/change-events.ts

@@ -1,27 +1,27 @@
 import {
   createSingleRowRefProxy,
   toExpression,
-} from "../query/builder/ref-proxy"
+} from '../query/builder/ref-proxy'
 import {
   compileSingleRowExpression,
   toBooleanPredicate,
-} from "../query/compiler/evaluators.js"
+} 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"
+} 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 { CollectionImpl } from "./index.js"
-import type { SingleRowRefProxy } from "../query/builder/ref-proxy"
-import type { BasicExpression, OrderBy } from "../query/ir.js"
+} from '../types'
+import type { CollectionImpl } from './index.js'
+import type { SingleRowRefProxy } from '../query/builder/ref-proxy'
+import type { BasicExpression, OrderBy } from '../query/ir.js'
 
 /**
  * Returns the current state of the collection as an array of changes
@@ -59,11 +59,11 @@ export function currentStateAsChanges<
   TKey extends string | number,
 >(
   collection: CollectionLike<T, TKey>,
-  options: CurrentStateAsChangesOptions = {}
+  options: CurrentStateAsChangesOptions = {},
 ): Array<ChangeMessage<T>> | void {
   // Helper function to collect filtered results
   const collectFilteredResults = (
-    filterFn?: (value: T) => boolean
+    filterFn?: (value: T) => boolean,
   ): Array<ChangeMessage<T>> => {
     const result: Array<ChangeMessage<T>> = []
     for (const [key, value] of collection.entries()) {
@@ -97,7 +97,7 @@ export function currentStateAsChanges<
       options.orderBy,
       options.limit,
       whereFilter,
-      options.optimizedOnly
+      options.optimizedOnly,
     )
 
     if (orderedKeys === undefined) {
@@ -133,7 +133,7 @@ export function currentStateAsChanges<
     // Try to optimize the query using indexes
     const optimizationResult = optimizeExpressionWithIndexes(
       expression,
-      collection
+      collection,
     )
 
     if (optimizationResult.canOptimize) {
@@ -162,7 +162,7 @@ export function currentStateAsChanges<
     // If anything goes wrong with the where clause, fall back to full scan
     console.warn(
       `${collection.id ? `[${collection.id}] ` : ``}Error processing where clause, falling back to full scan:`,
-      error
+      error,
     )
 
     const filterFn = createFilterFunctionFromExpression(options.where)
@@ -181,7 +181,7 @@ export function currentStateAsChanges<
  * @returns A function that takes an item and returns true if it matches the filter
  */
 export function createFilterFunction<T extends object>(
-  whereCallback: (row: SingleRowRefProxy<T>) => any
+  whereCallback: (row: SingleRowRefProxy<T>) => any,
 ): (item: T) => boolean {
   return (item: T): boolean => {
     try {
@@ -219,11 +219,13 @@ export function createFilterFunction<T extends object>(
  * @returns A function that takes an item and returns true if it matches the filter
  */
 export function createFilterFunctionFromExpression<T extends object>(
-  expression: BasicExpression<boolean>
+  expression: BasicExpression<boolean>,
 ): (item: T) => boolean {
+  // Compile expression once when filter function is created, not on every invocation
+  const evaluator = compileSingleRowExpression(expression)
+
   return (item: T): boolean => {
     try {
-      const evaluator = compileSingleRowExpression(expression)
       const result = evaluator(item as Record<string, unknown>)
       return toBooleanPredicate(result)
     } catch {
@@ -241,7 +243,7 @@ export function createFilterFunctionFromExpression<T extends object>(
  */
 export function createFilteredCallback<T extends object>(
   originalCallback: (changes: Array<ChangeMessage<T>>) => void,
-  options: SubscribeChangesOptions
+  options: SubscribeChangesOptions,
 ): (changes: Array<ChangeMessage<T>>) => void {
   const filterFn = createFilterFunctionFromExpression(options.whereExpression!)
 
@@ -309,7 +311,7 @@ function getOrderedKeys<T extends object, TKey extends string | number>(
   orderBy: OrderBy,
   limit?: number,
   whereFilter?: (item: T) => boolean,
-  optimizedOnly?: boolean
+  optimizedOnly?: boolean,
 ): Array<TKey> | undefined {
   // For single-column orderBy on a ref expression, try index optimization
   if (orderBy.length === 1) {
@@ -326,7 +328,7 @@ function getOrderedKeys<T extends object, TKey extends string | number>(
         fieldPath[0]!,
         fieldPath,
         collection as CollectionImpl<T, TKey>,
-        compareOpts
+        compareOpts,
       )
 
       // Find the index

package/src/collection/changes.ts

@@ -1,11 +1,11 @@
-import { NegativeActiveSubscribersError } from "../errors"
-import { CollectionSubscription } from "./subscription.js"
-import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type { ChangeMessage, SubscribeChangesOptions } from "../types"
-import type { CollectionLifecycleManager } from "./lifecycle.js"
-import type { CollectionSyncManager } from "./sync.js"
-import type { CollectionEventsManager } from "./events.js"
-import type { CollectionImpl } from "./index.js"
+import { NegativeActiveSubscribersError } from '../errors'
+import { CollectionSubscription } from './subscription.js'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { ChangeMessage, SubscribeChangesOptions } from '../types'
+import type { CollectionLifecycleManager } from './lifecycle.js'
+import type { CollectionSyncManager } from './sync.js'
+import type { CollectionEventsManager } from './events.js'
+import type { CollectionImpl } from './index.js'
 
 export class CollectionChangesManager<
   TOutput extends object = Record<string, unknown>,
@@ -56,7 +56,7 @@ export class CollectionChangesManager<
    */
   public emitEvents(
     changes: Array<ChangeMessage<TOutput, TKey>>,
-    forceEmit = false
+    forceEmit = false,
   ): void {
     // Skip batching for user actions (forceEmit=true) to keep UI responsive
     if (this.shouldBatchEvents && !forceEmit) {
@@ -94,7 +94,7 @@ export class CollectionChangesManager<
    */
   public subscribeChanges(
     callback: (changes: Array<ChangeMessage<TOutput>>) => void,
-    options: SubscribeChangesOptions = {}
+    options: SubscribeChangesOptions = {},
   ): CollectionSubscription {
     // Start sync and track subscriber
     this.addSubscriber()
@@ -135,7 +135,7 @@ export class CollectionChangesManager<
 
     this.events.emitSubscribersChange(
       this.activeSubscribersCount,
-      previousSubscriberCount
+      previousSubscriberCount,
     )
   }
 
@@ -154,7 +154,7 @@ export class CollectionChangesManager<
 
     this.events.emitSubscribersChange(
       this.activeSubscribersCount,
-      previousSubscriberCount
+      previousSubscriberCount,
     )
   }
 

package/src/collection/events.ts

@@ -1,6 +1,6 @@
-import { EventEmitter } from "../event-emitter.js"
-import type { Collection } from "./index.js"
-import type { CollectionStatus } from "../types.js"
+import { EventEmitter } from '../event-emitter.js'
+import type { Collection } from './index.js'
+import type { CollectionStatus } from '../types.js'
 
 /**
  * Event emitted when the collection status changes
@@ -43,10 +43,19 @@ export interface CollectionLoadingSubsetChangeEvent {
   loadingSubsetTransition: `start` | `end`
 }
 
+/**
+ * Event emitted when the collection is truncated (all data cleared)
+ */
+export interface CollectionTruncateEvent {
+  type: `truncate`
+  collection: Collection<any, any, any, any, any>
+}
+
 export type AllCollectionEvents = {
-  "status:change": CollectionStatusChangeEvent
-  "subscribers:change": CollectionSubscribersChangeEvent
-  "loadingSubset:change": CollectionLoadingSubsetChangeEvent
+  'status:change': CollectionStatusChangeEvent
+  'subscribers:change': CollectionSubscribersChangeEvent
+  'loadingSubset:change': CollectionLoadingSubsetChangeEvent
+  truncate: CollectionTruncateEvent
 } & {
   [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>
 }
@@ -56,9 +65,10 @@ export type CollectionEvent =
   | CollectionStatusChangeEvent
   | CollectionSubscribersChangeEvent
   | CollectionLoadingSubsetChangeEvent
+  | CollectionTruncateEvent
 
 export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (
-  event: AllCollectionEvents[T]
+  event: AllCollectionEvents[T],
 ) => void
 
 export class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
@@ -78,14 +88,14 @@ export class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
    */
   emit<T extends keyof AllCollectionEvents>(
     event: T,
-    eventPayload: AllCollectionEvents[T]
+    eventPayload: AllCollectionEvents[T],
   ): void {
     this.emitInner(event, eventPayload)
   }
 
   emitStatusChange<T extends CollectionStatus>(
     status: T,
-    previousStatus: CollectionStatus
+    previousStatus: CollectionStatus,
   ) {
     this.emit(`status:change`, {
       type: `status:change`,
@@ -106,7 +116,7 @@ export class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
 
   emitSubscribersChange(
     subscriberCount: number,
-    previousSubscriberCount: number
+    previousSubscriberCount: number,
   ) {
     this.emit(`subscribers:change`, {
       type: `subscribers:change`,