@tanstack/db 0.4.20 → 0.5.0

package/dist/cjs/query/compiler/order-by.cjs

@@ -16,7 +16,7 @@ function processOrderBy(rawQuery, pipeline, orderByClause, selectClause, collect
     );
     return {
       compiledExpression: evaluators.compileExpression(clauseWithoutAggregates),
-      compareOptions: clause.compareOptions
+      compareOptions: buildCompareOptions(clause, collection)
     };
   });
   const valueExtractor = (row) => {
@@ -36,7 +36,7 @@ function processOrderBy(rawQuery, pipeline, orderByClause, selectClause, collect
       const arrayA = a;
       const arrayB = b;
       for (let i = 0; i < orderByClause.length; i++) {
-        const clause = orderByClause[i];
+        const clause = compiledOrderBy[i];
         const compareFn = comparison.makeComparator(clause.compareOptions);
         const result = compareFn(arrayA[i], arrayB[i]);
         if (result !== 0) {
@@ -46,7 +46,7 @@ function processOrderBy(rawQuery, pipeline, orderByClause, selectClause, collect
       return arrayA.length - arrayB.length;
     }
     if (orderByClause.length === 1) {
-      const clause = orderByClause[0];
+      const clause = compiledOrderBy[0];
       const compareFn = comparison.makeComparator(clause.compareOptions);
       return compareFn(a, b);
     }
@@ -65,12 +65,13 @@ function processOrderBy(rawQuery, pipeline, orderByClause, selectClause, collect
       );
       const followRefCollection = followRefResult.collection;
       const fieldName = followRefResult.path[0];
+      const compareOpts = buildCompareOptions(clause, followRefCollection);
       if (fieldName) {
         autoIndex.ensureIndexForField(
           fieldName,
           followRefResult.path,
           followRefCollection,
-          clause.compareOptions,
+          compareOpts,
           compare
         );
       }
@@ -84,9 +85,9 @@ function processOrderBy(rawQuery, pipeline, orderByClause, selectClause, collect
         return compare(extractedA, extractedB);
       };
       const index = indexOptimization.findIndexForField(
-        followRefCollection.indexes,
+        followRefCollection,
         followRefResult.path,
-        clause.compareOptions
+        compareOpts
       );
       if (index && index.supports(`gt`)) {
         const orderByAlias = orderByExpression.path.length > 1 ? String(orderByExpression.path[0]) : rawQuery.from.alias;
@@ -132,5 +133,16 @@ function processOrderBy(rawQuery, pipeline, orderByClause, selectClause, collect
     // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format
   );
 }
+function buildCompareOptions(clause, collection) {
+  if (clause.compareOptions.stringSort !== void 0) {
+    return clause.compareOptions;
+  }
+  return {
+    ...collection.compareOptions,
+    direction: clause.compareOptions.direction,
+    nulls: clause.compareOptions.nulls
+  };
+}
+exports.buildCompareOptions = buildCompareOptions;
 exports.processOrderBy = processOrderBy;
 //# sourceMappingURL=order-by.cjs.map

package/dist/cjs/query/compiler/order-by.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"order-by.cjs","sources":["../../../../src/query/compiler/order-by.ts"],"sourcesContent":["import { orderByWithFractionalIndex } from \"@tanstack/db-ivm\"\nimport { defaultComparator, makeComparator } from \"../../utils/comparison.js\"\nimport { PropRef, followRef } from \"../ir.js\"\nimport { ensureIndexForField } from \"../../indexes/auto-index.js\"\nimport { findIndexForField } from \"../../utils/index-optimization.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport { replaceAggregatesByRefs } from \"./group-by.js\"\nimport type { WindowOptions } from \"./types.js\"\nimport type { CompiledSingleRowExpression } from \"./evaluators.js\"\nimport type { OrderBy, OrderByClause, QueryIR, Select } from \"../ir.js\"\nimport type { NamespacedAndKeyedStream, NamespacedRow } from \"../../types.js\"\nimport type { IStreamBuilder, KeyValue } from \"@tanstack/db-ivm\"\nimport type { IndexInterface } from \"../../indexes/base-index.js\"\nimport type { Collection } from \"../../collection/index.js\"\n\nexport type OrderByOptimizationInfo = {\n  alias: string\n  orderBy: OrderBy\n  offset: number\n  limit: number\n  comparator: (\n    a: Record<string, unknown> | null | undefined,\n    b: Record<string, unknown> | null | undefined\n  ) => number\n  valueExtractorForRawRow: (row: Record<string, unknown>) => any\n  index: IndexInterface<string | number>\n  dataNeeded?: () => number\n}\n\n/**\n * Processes the ORDER BY clause\n * Works with the new structure that has both namespaced row data and __select_results\n * Always uses fractional indexing and adds the index as __ordering_index to the result\n */\nexport function processOrderBy(\n  rawQuery: QueryIR,\n  pipeline: NamespacedAndKeyedStream,\n  orderByClause: Array<OrderByClause>,\n  selectClause: Select,\n  collection: Collection,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,\n  limit?: number,\n  offset?: number\n): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>> {\n  // Pre-compile all order by expressions\n  const compiledOrderBy = orderByClause.map((clause) => {\n    const clauseWithoutAggregates = replaceAggregatesByRefs(\n      clause.expression,\n      selectClause,\n      `__select_results`\n    )\n    return {\n      compiledExpression: compileExpression(clauseWithoutAggregates),\n      compareOptions: clause.compareOptions,\n    }\n  })\n\n  // Create a value extractor function for the orderBy operator\n  const valueExtractor = (row: NamespacedRow & { __select_results?: any }) => {\n    // The namespaced row contains:\n    // 1. Table aliases as top-level properties (e.g., row[\"tableName\"])\n    // 2. SELECT results in __select_results (e.g., row.__select_results[\"aggregateAlias\"])\n    // The replaceAggregatesByRefs function has already transformed any aggregate expressions\n    // that match SELECT aggregates to use the __select_results namespace.\n    const orderByContext = row\n\n    if (orderByClause.length > 1) {\n      // For multiple orderBy columns, create a composite key\n      return compiledOrderBy.map((compiled) =>\n        compiled.compiledExpression(orderByContext)\n      )\n    } else if (orderByClause.length === 1) {\n      // For a single orderBy column, use the value directly\n      const compiled = compiledOrderBy[0]!\n      return compiled.compiledExpression(orderByContext)\n    }\n\n    // Default case - no ordering\n    return null\n  }\n\n  // Create a multi-property comparator that respects the order and direction of each property\n  const compare = (a: unknown, b: unknown) => {\n    // If we're comparing arrays (multiple properties), compare each property in order\n    if (orderByClause.length > 1) {\n      const arrayA = a as Array<unknown>\n      const arrayB = b as Array<unknown>\n      for (let i = 0; i < orderByClause.length; i++) {\n        const clause = orderByClause[i]!\n        const compareFn = makeComparator(clause.compareOptions)\n        const result = compareFn(arrayA[i], arrayB[i])\n        if (result !== 0) {\n          return result\n        }\n      }\n      return arrayA.length - arrayB.length\n    }\n\n    // Single property comparison\n    if (orderByClause.length === 1) {\n      const clause = orderByClause[0]!\n      const compareFn = makeComparator(clause.compareOptions)\n      return compareFn(a, b)\n    }\n\n    return defaultComparator(a, b)\n  }\n\n  let setSizeCallback: ((getSize: () => number) => void) | undefined\n\n  let orderByOptimizationInfo: OrderByOptimizationInfo | undefined\n\n  // Optimize the orderBy operator to lazily load elements\n  // by using the range index of the collection.\n  // Only for orderBy clause on a single column for now (no composite ordering)\n  if (limit && orderByClause.length === 1) {\n    const clause = orderByClause[0]!\n    const orderByExpression = clause.expression\n\n    if (orderByExpression.type === `ref`) {\n      const followRefResult = followRef(\n        rawQuery,\n        orderByExpression,\n        collection\n      )!\n\n      const followRefCollection = followRefResult.collection\n      const fieldName = followRefResult.path[0]\n      if (fieldName) {\n        ensureIndexForField(\n          fieldName,\n          followRefResult.path,\n          followRefCollection,\n          clause.compareOptions,\n          compare\n        )\n      }\n\n      const valueExtractorForRawRow = compileExpression(\n        new PropRef(followRefResult.path),\n        true\n      ) as CompiledSingleRowExpression\n\n      const comparator = (\n        a: Record<string, unknown> | null | undefined,\n        b: Record<string, unknown> | null | undefined\n      ) => {\n        const extractedA = a ? valueExtractorForRawRow(a) : a\n        const extractedB = b ? valueExtractorForRawRow(b) : b\n        return compare(extractedA, extractedB)\n      }\n\n      const index: IndexInterface<string | number> | undefined =\n        findIndexForField(\n          followRefCollection.indexes,\n          followRefResult.path,\n          clause.compareOptions\n        )\n\n      if (index && index.supports(`gt`)) {\n        // We found an index that we can use to lazily load ordered data\n        const orderByAlias =\n          orderByExpression.path.length > 1\n            ? String(orderByExpression.path[0])\n            : rawQuery.from.alias\n\n        orderByOptimizationInfo = {\n          alias: orderByAlias,\n          offset: offset ?? 0,\n          limit,\n          comparator,\n          valueExtractorForRawRow,\n          index,\n          orderBy: orderByClause,\n        }\n\n        optimizableOrderByCollections[followRefCollection.id] =\n          orderByOptimizationInfo\n\n        setSizeCallback = (getSize: () => number) => {\n          optimizableOrderByCollections[followRefCollection.id]![`dataNeeded`] =\n            () => {\n              const size = getSize()\n              return Math.max(0, orderByOptimizationInfo!.limit - size)\n            }\n        }\n      }\n    }\n  }\n\n  // Use fractional indexing and return the tuple [value, index]\n  return pipeline.pipe(\n    orderByWithFractionalIndex(valueExtractor, {\n      limit,\n      offset,\n      comparator: compare,\n      setSizeCallback,\n      setWindowFn: (\n        windowFn: (options: { offset?: number; limit?: number }) => void\n      ) => {\n        setWindowFn(\n          // We wrap the move function such that we update the orderByOptimizationInfo\n          // because that is used by the `dataNeeded` callback to determine if we need to load more data\n          (options) => {\n            windowFn(options)\n            if (orderByOptimizationInfo) {\n              orderByOptimizationInfo.offset =\n                options.offset ?? orderByOptimizationInfo.offset\n              orderByOptimizationInfo.limit =\n                options.limit ?? orderByOptimizationInfo.limit\n            }\n          }\n        )\n      },\n    })\n    // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format\n  )\n}\n"],"names":["replaceAggregatesByRefs","compileExpression","makeComparator","defaultComparator","followRef","ensureIndexForField","PropRef","findIndexForField","orderByWithFractionalIndex"],"mappings":"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"}
+{"version":3,"file":"order-by.cjs","sources":["../../../../src/query/compiler/order-by.ts"],"sourcesContent":["import { orderByWithFractionalIndex } from \"@tanstack/db-ivm\"\nimport { defaultComparator, makeComparator } from \"../../utils/comparison.js\"\nimport { PropRef, followRef } from \"../ir.js\"\nimport { ensureIndexForField } from \"../../indexes/auto-index.js\"\nimport { findIndexForField } from \"../../utils/index-optimization.js\"\nimport { compileExpression } from \"./evaluators.js\"\nimport { replaceAggregatesByRefs } from \"./group-by.js\"\nimport type { CompareOptions } from \"../builder/types.js\"\nimport type { WindowOptions } from \"./types.js\"\nimport type { CompiledSingleRowExpression } from \"./evaluators.js\"\nimport type { OrderBy, OrderByClause, QueryIR, Select } from \"../ir.js\"\nimport type {\n  CollectionLike,\n  NamespacedAndKeyedStream,\n  NamespacedRow,\n} from \"../../types.js\"\nimport type { IStreamBuilder, KeyValue } from \"@tanstack/db-ivm\"\nimport type { IndexInterface } from \"../../indexes/base-index.js\"\nimport type { Collection } from \"../../collection/index.js\"\n\nexport type OrderByOptimizationInfo = {\n  alias: string\n  orderBy: OrderBy\n  offset: number\n  limit: number\n  comparator: (\n    a: Record<string, unknown> | null | undefined,\n    b: Record<string, unknown> | null | undefined\n  ) => number\n  valueExtractorForRawRow: (row: Record<string, unknown>) => any\n  index: IndexInterface<string | number>\n  dataNeeded?: () => number\n}\n\n/**\n * Processes the ORDER BY clause\n * Works with the new structure that has both namespaced row data and __select_results\n * Always uses fractional indexing and adds the index as __ordering_index to the result\n */\nexport function processOrderBy(\n  rawQuery: QueryIR,\n  pipeline: NamespacedAndKeyedStream,\n  orderByClause: Array<OrderByClause>,\n  selectClause: Select,\n  collection: Collection,\n  optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,\n  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,\n  limit?: number,\n  offset?: number\n): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>> {\n  // Pre-compile all order by expressions\n  const compiledOrderBy = orderByClause.map((clause) => {\n    const clauseWithoutAggregates = replaceAggregatesByRefs(\n      clause.expression,\n      selectClause,\n      `__select_results`\n    )\n\n    return {\n      compiledExpression: compileExpression(clauseWithoutAggregates),\n      compareOptions: buildCompareOptions(clause, collection),\n    }\n  })\n\n  // Create a value extractor function for the orderBy operator\n  const valueExtractor = (row: NamespacedRow & { __select_results?: any }) => {\n    // The namespaced row contains:\n    // 1. Table aliases as top-level properties (e.g., row[\"tableName\"])\n    // 2. SELECT results in __select_results (e.g., row.__select_results[\"aggregateAlias\"])\n    // The replaceAggregatesByRefs function has already transformed any aggregate expressions\n    // that match SELECT aggregates to use the __select_results namespace.\n    const orderByContext = row\n\n    if (orderByClause.length > 1) {\n      // For multiple orderBy columns, create a composite key\n      return compiledOrderBy.map((compiled) =>\n        compiled.compiledExpression(orderByContext)\n      )\n    } else if (orderByClause.length === 1) {\n      // For a single orderBy column, use the value directly\n      const compiled = compiledOrderBy[0]!\n      return compiled.compiledExpression(orderByContext)\n    }\n\n    // Default case - no ordering\n    return null\n  }\n\n  // Create a multi-property comparator that respects the order and direction of each property\n  const compare = (a: unknown, b: unknown) => {\n    // If we're comparing arrays (multiple properties), compare each property in order\n    if (orderByClause.length > 1) {\n      const arrayA = a as Array<unknown>\n      const arrayB = b as Array<unknown>\n      for (let i = 0; i < orderByClause.length; i++) {\n        const clause = compiledOrderBy[i]!\n        const compareFn = makeComparator(clause.compareOptions)\n        const result = compareFn(arrayA[i], arrayB[i])\n        if (result !== 0) {\n          return result\n        }\n      }\n      return arrayA.length - arrayB.length\n    }\n\n    // Single property comparison\n    if (orderByClause.length === 1) {\n      const clause = compiledOrderBy[0]!\n      const compareFn = makeComparator(clause.compareOptions)\n      return compareFn(a, b)\n    }\n\n    return defaultComparator(a, b)\n  }\n\n  let setSizeCallback: ((getSize: () => number) => void) | undefined\n\n  let orderByOptimizationInfo: OrderByOptimizationInfo | undefined\n\n  // Optimize the orderBy operator to lazily load elements\n  // by using the range index of the collection.\n  // Only for orderBy clause on a single column for now (no composite ordering)\n  if (limit && orderByClause.length === 1) {\n    const clause = orderByClause[0]!\n    const orderByExpression = clause.expression\n\n    if (orderByExpression.type === `ref`) {\n      const followRefResult = followRef(\n        rawQuery,\n        orderByExpression,\n        collection\n      )!\n\n      const followRefCollection = followRefResult.collection\n      const fieldName = followRefResult.path[0]\n      const compareOpts = buildCompareOptions(clause, followRefCollection)\n      if (fieldName) {\n        ensureIndexForField(\n          fieldName,\n          followRefResult.path,\n          followRefCollection,\n          compareOpts,\n          compare\n        )\n      }\n\n      const valueExtractorForRawRow = compileExpression(\n        new PropRef(followRefResult.path),\n        true\n      ) as CompiledSingleRowExpression\n\n      const comparator = (\n        a: Record<string, unknown> | null | undefined,\n        b: Record<string, unknown> | null | undefined\n      ) => {\n        const extractedA = a ? valueExtractorForRawRow(a) : a\n        const extractedB = b ? valueExtractorForRawRow(b) : b\n        return compare(extractedA, extractedB)\n      }\n\n      const index: IndexInterface<string | number> | undefined =\n        findIndexForField(\n          followRefCollection,\n          followRefResult.path,\n          compareOpts\n        )\n\n      if (index && index.supports(`gt`)) {\n        // We found an index that we can use to lazily load ordered data\n        const orderByAlias =\n          orderByExpression.path.length > 1\n            ? String(orderByExpression.path[0])\n            : rawQuery.from.alias\n\n        orderByOptimizationInfo = {\n          alias: orderByAlias,\n          offset: offset ?? 0,\n          limit,\n          comparator,\n          valueExtractorForRawRow,\n          index,\n          orderBy: orderByClause,\n        }\n\n        optimizableOrderByCollections[followRefCollection.id] =\n          orderByOptimizationInfo\n\n        setSizeCallback = (getSize: () => number) => {\n          optimizableOrderByCollections[followRefCollection.id]![`dataNeeded`] =\n            () => {\n              const size = getSize()\n              return Math.max(0, orderByOptimizationInfo!.limit - size)\n            }\n        }\n      }\n    }\n  }\n\n  // Use fractional indexing and return the tuple [value, index]\n  return pipeline.pipe(\n    orderByWithFractionalIndex(valueExtractor, {\n      limit,\n      offset,\n      comparator: compare,\n      setSizeCallback,\n      setWindowFn: (\n        windowFn: (options: { offset?: number; limit?: number }) => void\n      ) => {\n        setWindowFn(\n          // We wrap the move function such that we update the orderByOptimizationInfo\n          // because that is used by the `dataNeeded` callback to determine if we need to load more data\n          (options) => {\n            windowFn(options)\n            if (orderByOptimizationInfo) {\n              orderByOptimizationInfo.offset =\n                options.offset ?? orderByOptimizationInfo.offset\n              orderByOptimizationInfo.limit =\n                options.limit ?? orderByOptimizationInfo.limit\n            }\n          }\n        )\n      },\n    })\n    // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format\n  )\n}\n\n/**\n * Builds a comparison configuration object that uses the values provided in the orderBy clause.\n * If no string sort configuration is provided it defaults to the collection's string sort configuration.\n */\nexport function buildCompareOptions(\n  clause: OrderByClause,\n  collection: CollectionLike<any, any>\n): CompareOptions {\n  if (clause.compareOptions.stringSort !== undefined) {\n    return clause.compareOptions\n  }\n\n  return {\n    ...collection.compareOptions,\n    direction: clause.compareOptions.direction,\n    nulls: clause.compareOptions.nulls,\n  }\n}\n"],"names":["replaceAggregatesByRefs","compileExpression","makeComparator","defaultComparator","followRef","ensureIndexForField","PropRef","findIndexForField","orderByWithFractionalIndex"],"mappings":"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"}

package/dist/cjs/query/compiler/order-by.d.cts

@@ -1,6 +1,7 @@
+import { CompareOptions } from '../builder/types.js';
 import { WindowOptions } from './types.js';
 import { OrderBy, OrderByClause, QueryIR, Select } from '../ir.js';
-import { NamespacedAndKeyedStream, NamespacedRow } from '../../types.js';
+import { CollectionLike, NamespacedAndKeyedStream, NamespacedRow } from '../../types.js';
 import { IStreamBuilder, KeyValue } from '@tanstack/db-ivm';
 import { IndexInterface } from '../../indexes/base-index.js';
 import { Collection } from '../../collection/index.js';
@@ -20,3 +21,8 @@ export type OrderByOptimizationInfo = {
  * Always uses fractional indexing and adds the index as __ordering_index to the result
  */
 export declare function processOrderBy(rawQuery: QueryIR, pipeline: NamespacedAndKeyedStream, orderByClause: Array<OrderByClause>, selectClause: Select, collection: Collection, optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>, setWindowFn: (windowFn: (options: WindowOptions) => void) => void, limit?: number, offset?: number): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>>;
+/**
+ * Builds a comparison configuration object that uses the values provided in the orderBy clause.
+ * If no string sort configuration is provided it defaults to the collection's string sort configuration.
+ */
+export declare function buildCompareOptions(clause: OrderByClause, collection: CollectionLike<any, any>): CompareOptions;

package/dist/cjs/query/expression-helpers.cjs

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function extractFieldPath(expr) {
+  if (expr.type === `ref`) {
+    return expr.path;
+  }
+  return null;
+}
+function extractValue(expr) {
+  if (expr.type === `val`) {
+    return expr.value;
+  }
+  return void 0;
+}
+function walkExpression(expr, visitor) {
+  if (!expr) return;
+  visitor(expr);
+  if (expr.type === `func`) {
+    expr.args.forEach((arg) => walkExpression(arg, visitor));
+  }
+}
+function parseWhereExpression(expr, options) {
+  if (!expr) return null;
+  const { handlers, onUnknownOperator } = options;
+  if (expr.type === `val`) {
+    return expr.value;
+  }
+  if (expr.type === `ref`) {
+    return expr.path;
+  }
+  const { name, args } = expr;
+  const handler = handlers[name];
+  if (!handler) {
+    if (onUnknownOperator) {
+      return onUnknownOperator(name, args);
+    }
+    throw new Error(
+      `No handler provided for operator: ${name}. Available handlers: ${Object.keys(handlers).join(`, `)}`
+    );
+  }
+  const parsedArgs = args.map((arg) => {
+    if (arg.type === `ref`) {
+      return arg.path;
+    }
+    if (arg.type === `val`) {
+      return arg.value;
+    }
+    return parseWhereExpression(arg, options);
+  });
+  return handler(...parsedArgs);
+}
+function parseOrderByExpression(orderBy) {
+  if (!orderBy || orderBy.length === 0) {
+    return [];
+  }
+  return orderBy.map((clause) => {
+    const field = extractFieldPath(clause.expression);
+    if (!field) {
+      throw new Error(
+        `ORDER BY expression must be a field reference, got: ${clause.expression.type}`
+      );
+    }
+    const { direction, nulls } = clause.compareOptions;
+    const result = {
+      field,
+      direction,
+      nulls
+    };
+    if (`stringSort` in clause.compareOptions) {
+      result.stringSort = clause.compareOptions.stringSort;
+    }
+    if (`locale` in clause.compareOptions) {
+      result.locale = clause.compareOptions.locale;
+    }
+    if (`localeOptions` in clause.compareOptions) {
+      result.localeOptions = clause.compareOptions.localeOptions;
+    }
+    return result;
+  });
+}
+function extractSimpleComparisons(expr) {
+  if (!expr) return [];
+  const comparisons = [];
+  function extract(e) {
+    if (e.type === `func`) {
+      if (e.name === `and`) {
+        e.args.forEach((arg) => extract(arg));
+        return;
+      }
+      if (e.name === `not`) {
+        const [arg] = e.args;
+        if (!arg || arg.type !== `func`) {
+          throw new Error(
+            `extractSimpleComparisons requires a comparison or null check inside 'not' operator.`
+          );
+        }
+        const nullCheckOps2 = [`isNull`, `isUndefined`];
+        if (nullCheckOps2.includes(arg.name)) {
+          const [fieldArg] = arg.args;
+          const field = fieldArg?.type === `ref` ? fieldArg.path : null;
+          if (field) {
+            comparisons.push({
+              field,
+              operator: `not_${arg.name}`
+              // No value for null/undefined checks
+            });
+          } else {
+            throw new Error(
+              `extractSimpleComparisons requires a field reference for '${arg.name}' operator.`
+            );
+          }
+          return;
+        }
+        const comparisonOps2 = [`eq`, `gt`, `gte`, `lt`, `lte`, `in`];
+        if (comparisonOps2.includes(arg.name)) {
+          const [leftArg, rightArg] = arg.args;
+          const field = leftArg?.type === `ref` ? leftArg.path : null;
+          const value = rightArg?.type === `val` ? rightArg.value : null;
+          if (field && value !== void 0) {
+            comparisons.push({
+              field,
+              operator: `not_${arg.name}`,
+              value
+            });
+          } else {
+            throw new Error(
+              `extractSimpleComparisons requires simple field-value comparisons. Found complex expression for 'not(${arg.name})' operator.`
+            );
+          }
+          return;
+        }
+        throw new Error(
+          `extractSimpleComparisons does not support 'not(${arg.name})'. NOT can only wrap comparison operators (eq, gt, gte, lt, lte, in) or null checks (isNull, isUndefined).`
+        );
+      }
+      const unsupportedOps = [
+        `or`,
+        `like`,
+        `ilike`,
+        `upper`,
+        `lower`,
+        `length`,
+        `concat`,
+        `add`,
+        `coalesce`,
+        `count`,
+        `avg`,
+        `sum`,
+        `min`,
+        `max`
+      ];
+      if (unsupportedOps.includes(e.name)) {
+        throw new Error(
+          `extractSimpleComparisons does not support '${e.name}' operator. Use parseWhereExpression with custom handlers for complex expressions.`
+        );
+      }
+      const nullCheckOps = [`isNull`, `isUndefined`];
+      if (nullCheckOps.includes(e.name)) {
+        const [fieldArg] = e.args;
+        const field = fieldArg?.type === `ref` ? fieldArg.path : null;
+        if (field) {
+          comparisons.push({
+            field,
+            operator: e.name
+            // No value for null/undefined checks
+          });
+        } else {
+          throw new Error(
+            `extractSimpleComparisons requires a field reference for '${e.name}' operator.`
+          );
+        }
+        return;
+      }
+      const comparisonOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `in`];
+      if (comparisonOps.includes(e.name)) {
+        const [leftArg, rightArg] = e.args;
+        const field = leftArg?.type === `ref` ? leftArg.path : null;
+        const value = rightArg?.type === `val` ? rightArg.value : null;
+        if (field && value !== void 0) {
+          comparisons.push({
+            field,
+            operator: e.name,
+            value
+          });
+        } else {
+          throw new Error(
+            `extractSimpleComparisons requires simple field-value comparisons. Found complex expression for '${e.name}' operator.`
+          );
+        }
+      } else {
+        throw new Error(
+          `extractSimpleComparisons encountered unknown operator: '${e.name}'`
+        );
+      }
+    }
+  }
+  extract(expr);
+  return comparisons;
+}
+function parseLoadSubsetOptions(options) {
+  if (!options) {
+    return { filters: [], sorts: [] };
+  }
+  return {
+    filters: extractSimpleComparisons(options.where),
+    sorts: parseOrderByExpression(options.orderBy),
+    limit: options.limit
+  };
+}
+exports.extractFieldPath = extractFieldPath;
+exports.extractSimpleComparisons = extractSimpleComparisons;
+exports.extractValue = extractValue;
+exports.parseLoadSubsetOptions = parseLoadSubsetOptions;
+exports.parseOrderByExpression = parseOrderByExpression;
+exports.parseWhereExpression = parseWhereExpression;
+exports.walkExpression = walkExpression;
+//# sourceMappingURL=expression-helpers.cjs.map

package/dist/cjs/query/expression-helpers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression-helpers.cjs","sources":["../../../src/query/expression-helpers.ts"],"sourcesContent":["/**\n * Expression Helpers for TanStack DB\n *\n * These utilities help parse LoadSubsetOptions (where, orderBy, limit) from TanStack DB\n * into formats suitable for your API backend. They provide a generic way to traverse\n * expression trees without having to implement your own parser.\n *\n * @example\n * ```typescript\n * import { parseWhereExpression, parseOrderByExpression } from '@tanstack/db'\n *\n * queryFn: async (ctx) => {\n *   const { limit, where, orderBy } = ctx.meta?.loadSubsetOptions ?? {}\n *\n *   // Convert expression tree to filters\n *   const filters = parseWhereExpression(where, {\n *     eq: (field, value) => ({ [field]: value }),\n *     lt: (field, value) => ({ [`${field}_lt`]: value }),\n *     and: (filters) => Object.assign({}, ...filters)\n *   })\n *\n *   // Extract sort information\n *   const sort = parseOrderByExpression(orderBy)\n *\n *   return api.getProducts({ ...filters, sort, limit })\n * }\n * ```\n */\n\nimport type { IR, OperatorName } from \"../index.js\"\n\ntype BasicExpression<T = any> = IR.BasicExpression<T>\ntype OrderBy = IR.OrderBy\n\n/**\n * Represents a simple field path extracted from an expression.\n * Can include string keys for object properties and numbers for array indices.\n */\nexport type FieldPath = Array<string | number>\n\n/**\n * Represents a simple comparison operation\n */\nexport interface SimpleComparison {\n  field: FieldPath\n  operator: string\n  value?: any // Optional for operators like isNull and isUndefined that don't have a value\n}\n\n/**\n * Options for customizing how WHERE expressions are parsed\n */\nexport interface ParseWhereOptions<T = any> {\n  /**\n   * Handler functions for different operators.\n   * Each handler receives the parsed field path(s) and value(s) and returns your custom format.\n   *\n   * Supported operators from TanStack DB:\n   * - Comparison: eq, gt, gte, lt, lte, in, like, ilike\n   * - Logical: and, or, not\n   * - Null checking: isNull, isUndefined\n   * - String functions: upper, lower, length, concat\n   * - Numeric: add\n   * - Utility: coalesce\n   * - Aggregates: count, avg, sum, min, max\n   */\n  handlers: {\n    [K in OperatorName]?: (...args: Array<any>) => T\n  } & {\n    [key: string]: (...args: Array<any>) => T\n  }\n  /**\n   * Optional handler for when an unknown operator is encountered.\n   * If not provided, unknown operators throw an error.\n   */\n  onUnknownOperator?: (operator: string, args: Array<any>) => T\n}\n\n/**\n * Result of parsing an ORDER BY expression\n */\nexport interface ParsedOrderBy {\n  field: FieldPath\n  direction: `asc` | `desc`\n  nulls: `first` | `last`\n  /** String sorting method: 'lexical' (default) or 'locale' (locale-aware) */\n  stringSort?: `lexical` | `locale`\n  /** Locale for locale-aware string sorting (e.g., 'en-US') */\n  locale?: string\n  /** Additional options for locale-aware sorting */\n  localeOptions?: object\n}\n\n/**\n * Extracts the field path from a PropRef expression.\n * Returns null for non-ref expressions.\n *\n * @param expr - The expression to extract from\n * @returns The field path array, or null\n *\n * @example\n * ```typescript\n * const field = extractFieldPath(someExpression)\n * // Returns: ['product', 'category']\n * ```\n */\nexport function extractFieldPath(expr: BasicExpression): FieldPath | null {\n  if (expr.type === `ref`) {\n    return expr.path\n  }\n  return null\n}\n\n/**\n * Extracts the value from a Value expression.\n * Returns undefined for non-value expressions.\n *\n * @param expr - The expression to extract from\n * @returns The extracted value\n *\n * @example\n * ```typescript\n * const val = extractValue(someExpression)\n * // Returns: 'electronics'\n * ```\n */\nexport function extractValue(expr: BasicExpression): any {\n  if (expr.type === `val`) {\n    return expr.value\n  }\n  return undefined\n}\n\n/**\n * Generic expression tree walker that visits each node in the expression.\n * Useful for implementing custom parsing logic.\n *\n * @param expr - The expression to walk\n * @param visitor - Visitor function called for each node\n *\n * @example\n * ```typescript\n * walkExpression(whereExpr, (node) => {\n *   if (node.type === 'func' && node.name === 'eq') {\n *     console.log('Found equality comparison')\n *   }\n * })\n * ```\n */\nexport function walkExpression(\n  expr: BasicExpression | undefined | null,\n  visitor: (node: BasicExpression) => void\n): void {\n  if (!expr) return\n\n  visitor(expr)\n\n  if (expr.type === `func`) {\n    expr.args.forEach((arg: BasicExpression) => walkExpression(arg, visitor))\n  }\n}\n\n/**\n * Parses a WHERE expression into a custom format using provided handlers.\n *\n * This is the main helper for converting TanStack DB where clauses into your API's filter format.\n * You provide handlers for each operator, and this function traverses the expression tree\n * and calls the appropriate handlers.\n *\n * @param expr - The WHERE expression to parse\n * @param options - Configuration with handler functions for each operator\n * @returns The parsed result in your custom format\n *\n * @example\n * ```typescript\n * // REST API with query parameters\n * const filters = parseWhereExpression(where, {\n *   handlers: {\n *     eq: (field, value) => ({ [field.join('.')]: value }),\n *     lt: (field, value) => ({ [`${field.join('.')}_lt`]: value }),\n *     gt: (field, value) => ({ [`${field.join('.')}_gt`]: value }),\n *     and: (...filters) => Object.assign({}, ...filters),\n *     or: (...filters) => ({ $or: filters })\n *   }\n * })\n * // Returns: { category: 'electronics', price_lt: 100 }\n * ```\n *\n * @example\n * ```typescript\n * // GraphQL where clause\n * const where = parseWhereExpression(whereExpr, {\n *   handlers: {\n *     eq: (field, value) => ({ [field.join('_')]: { _eq: value } }),\n *     lt: (field, value) => ({ [field.join('_')]: { _lt: value } }),\n *     and: (...filters) => ({ _and: filters })\n *   }\n * })\n * ```\n */\nexport function parseWhereExpression<T = any>(\n  expr: BasicExpression<boolean> | undefined | null,\n  options: ParseWhereOptions<T>\n): T | null {\n  if (!expr) return null\n\n  const { handlers, onUnknownOperator } = options\n\n  // Handle value expressions\n  if (expr.type === `val`) {\n    return expr.value as unknown as T\n  }\n\n  // Handle property references\n  if (expr.type === `ref`) {\n    return expr.path as unknown as T\n  }\n\n  // Handle function expressions\n  // After checking val and ref, expr must be func\n  const { name, args } = expr\n  const handler = handlers[name]\n\n  if (!handler) {\n    if (onUnknownOperator) {\n      return onUnknownOperator(name, args)\n    }\n    throw new Error(\n      `No handler provided for operator: ${name}. Available handlers: ${Object.keys(handlers).join(`, `)}`\n    )\n  }\n\n  // Parse arguments recursively\n  const parsedArgs = args.map((arg: BasicExpression) => {\n    // For refs, extract the field path\n    if (arg.type === `ref`) {\n      return arg.path\n    }\n    // For values, extract the value\n    if (arg.type === `val`) {\n      return arg.value\n    }\n    // For nested functions, recurse (after checking ref and val, must be func)\n    return parseWhereExpression(arg, options)\n  })\n\n  return handler(...parsedArgs)\n}\n\n/**\n * Parses an ORDER BY expression into a simple array of sort specifications.\n *\n * @param orderBy - The ORDER BY expression array\n * @returns Array of parsed order by specifications\n *\n * @example\n * ```typescript\n * const sorts = parseOrderByExpression(orderBy)\n * // Returns: [\n * //   { field: ['category'], direction: 'asc', nulls: 'last' },\n * //   { field: ['price'], direction: 'desc', nulls: 'last' }\n * // ]\n * ```\n */\nexport function parseOrderByExpression(\n  orderBy: OrderBy | undefined | null\n): Array<ParsedOrderBy> {\n  if (!orderBy || orderBy.length === 0) {\n    return []\n  }\n\n  return orderBy.map((clause: IR.OrderByClause) => {\n    const field = extractFieldPath(clause.expression)\n\n    if (!field) {\n      throw new Error(\n        `ORDER BY expression must be a field reference, got: ${clause.expression.type}`\n      )\n    }\n\n    const { direction, nulls } = clause.compareOptions\n    const result: ParsedOrderBy = {\n      field,\n      direction,\n      nulls,\n    }\n\n    // Add string collation options if present (discriminated union)\n    if (`stringSort` in clause.compareOptions) {\n      result.stringSort = clause.compareOptions.stringSort\n    }\n    if (`locale` in clause.compareOptions) {\n      result.locale = clause.compareOptions.locale\n    }\n    if (`localeOptions` in clause.compareOptions) {\n      result.localeOptions = clause.compareOptions.localeOptions\n    }\n\n    return result\n  })\n}\n\n/**\n * Extracts all simple comparisons from a WHERE expression.\n * This is useful for simple APIs that only support basic filters.\n *\n * Note: This only works for simple AND-ed conditions and NOT-wrapped comparisons.\n * Throws an error if it encounters unsupported operations like OR or complex nested expressions.\n *\n * NOT operators are flattened by prefixing the operator name (e.g., `not(eq(...))` becomes `not_eq`).\n *\n * @param expr - The WHERE expression to parse\n * @returns Array of simple comparisons\n * @throws Error if expression contains OR or other unsupported operations\n *\n * @example\n * ```typescript\n * const comparisons = extractSimpleComparisons(where)\n * // Returns: [\n * //   { field: ['category'], operator: 'eq', value: 'electronics' },\n * //   { field: ['price'], operator: 'lt', value: 100 },\n * //   { field: ['email'], operator: 'isNull' }, // No value for null checks\n * //   { field: ['status'], operator: 'not_eq', value: 'archived' }\n * // ]\n * ```\n */\nexport function extractSimpleComparisons(\n  expr: BasicExpression<boolean> | undefined | null\n): Array<SimpleComparison> {\n  if (!expr) return []\n\n  const comparisons: Array<SimpleComparison> = []\n\n  function extract(e: BasicExpression): void {\n    if (e.type === `func`) {\n      // Handle AND - recurse into both sides\n      if (e.name === `and`) {\n        e.args.forEach((arg: BasicExpression) => extract(arg))\n        return\n      }\n\n      // Handle NOT - recurse into argument and prefix operator with 'not_'\n      if (e.name === `not`) {\n        const [arg] = e.args\n        if (!arg || arg.type !== `func`) {\n          throw new Error(\n            `extractSimpleComparisons requires a comparison or null check inside 'not' operator.`\n          )\n        }\n\n        // Handle NOT with null/undefined checks\n        const nullCheckOps = [`isNull`, `isUndefined`]\n        if (nullCheckOps.includes(arg.name)) {\n          const [fieldArg] = arg.args\n          const field = fieldArg?.type === `ref` ? fieldArg.path : null\n\n          if (field) {\n            comparisons.push({\n              field,\n              operator: `not_${arg.name}`,\n              // No value for null/undefined checks\n            })\n          } else {\n            throw new Error(\n              `extractSimpleComparisons requires a field reference for '${arg.name}' operator.`\n            )\n          }\n          return\n        }\n\n        // Handle NOT with comparison operators\n        const comparisonOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `in`]\n        if (comparisonOps.includes(arg.name)) {\n          const [leftArg, rightArg] = arg.args\n          const field = leftArg?.type === `ref` ? leftArg.path : null\n          const value = rightArg?.type === `val` ? rightArg.value : null\n\n          if (field && value !== undefined) {\n            comparisons.push({\n              field,\n              operator: `not_${arg.name}`,\n              value,\n            })\n          } else {\n            throw new Error(\n              `extractSimpleComparisons requires simple field-value comparisons. Found complex expression for 'not(${arg.name})' operator.`\n            )\n          }\n          return\n        }\n\n        // NOT can only wrap simple comparisons or null checks\n        throw new Error(\n          `extractSimpleComparisons does not support 'not(${arg.name})'. NOT can only wrap comparison operators (eq, gt, gte, lt, lte, in) or null checks (isNull, isUndefined).`\n        )\n      }\n\n      // Throw on unsupported operations\n      const unsupportedOps = [\n        `or`,\n        `like`,\n        `ilike`,\n        `upper`,\n        `lower`,\n        `length`,\n        `concat`,\n        `add`,\n        `coalesce`,\n        `count`,\n        `avg`,\n        `sum`,\n        `min`,\n        `max`,\n      ]\n      if (unsupportedOps.includes(e.name)) {\n        throw new Error(\n          `extractSimpleComparisons does not support '${e.name}' operator. Use parseWhereExpression with custom handlers for complex expressions.`\n        )\n      }\n\n      // Handle null/undefined check operators (single argument, no value)\n      const nullCheckOps = [`isNull`, `isUndefined`]\n      if (nullCheckOps.includes(e.name)) {\n        const [fieldArg] = e.args\n\n        // Extract field (must be a ref)\n        const field = fieldArg?.type === `ref` ? fieldArg.path : null\n\n        if (field) {\n          comparisons.push({\n            field,\n            operator: e.name,\n            // No value for null/undefined checks\n          })\n        } else {\n          throw new Error(\n            `extractSimpleComparisons requires a field reference for '${e.name}' operator.`\n          )\n        }\n        return\n      }\n\n      // Handle comparison operators\n      const comparisonOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `in`]\n      if (comparisonOps.includes(e.name)) {\n        const [leftArg, rightArg] = e.args\n\n        // Extract field and value\n        const field = leftArg?.type === `ref` ? leftArg.path : null\n        const value = rightArg?.type === `val` ? rightArg.value : null\n\n        if (field && value !== undefined) {\n          comparisons.push({\n            field,\n            operator: e.name,\n            value,\n          })\n        } else {\n          throw new Error(\n            `extractSimpleComparisons requires simple field-value comparisons. Found complex expression for '${e.name}' operator.`\n          )\n        }\n      } else {\n        // Unknown operator\n        throw new Error(\n          `extractSimpleComparisons encountered unknown operator: '${e.name}'`\n        )\n      }\n    }\n  }\n\n  extract(expr)\n  return comparisons\n}\n\n/**\n * Convenience function to get all LoadSubsetOptions in a pre-parsed format.\n * Good starting point for simple use cases.\n *\n * @param options - The LoadSubsetOptions from ctx.meta\n * @returns Pre-parsed filters, sorts, and limit\n *\n * @example\n * ```typescript\n * queryFn: async (ctx) => {\n *   const parsed = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)\n *\n *   // Convert to your API format\n *   return api.getProducts({\n *     ...Object.fromEntries(\n *       parsed.filters.map(f => [`${f.field.join('.')}_${f.operator}`, f.value])\n *     ),\n *     sort: parsed.sorts.map(s => `${s.field.join('.')}:${s.direction}`).join(','),\n *     limit: parsed.limit\n *   })\n * }\n * ```\n */\nexport function parseLoadSubsetOptions(\n  options:\n    | {\n        where?: BasicExpression<boolean>\n        orderBy?: OrderBy\n        limit?: number\n      }\n    | undefined\n    | null\n): {\n  filters: Array<SimpleComparison>\n  sorts: Array<ParsedOrderBy>\n  limit?: number\n} {\n  if (!options) {\n    return { filters: [], sorts: [] }\n  }\n\n  return {\n    filters: extractSimpleComparisons(options.where),\n    sorts: parseOrderByExpression(options.orderBy),\n    limit: options.limit,\n  }\n}\n"],"names":["nullCheckOps","comparisonOps"],"mappings":"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"}

package/dist/cjs/query/expression-helpers.d.cts

@@ -0,0 +1,216 @@
+import { IR, OperatorName } from '../index.js';
+type BasicExpression<T = any> = IR.BasicExpression<T>;
+type OrderBy = IR.OrderBy;
+/**
+ * Represents a simple field path extracted from an expression.
+ * Can include string keys for object properties and numbers for array indices.
+ */
+export type FieldPath = Array<string | number>;
+/**
+ * Represents a simple comparison operation
+ */
+export interface SimpleComparison {
+    field: FieldPath;
+    operator: string;
+    value?: any;
+}
+/**
+ * Options for customizing how WHERE expressions are parsed
+ */
+export interface ParseWhereOptions<T = any> {
+    /**
+     * Handler functions for different operators.
+     * Each handler receives the parsed field path(s) and value(s) and returns your custom format.
+     *
+     * Supported operators from TanStack DB:
+     * - Comparison: eq, gt, gte, lt, lte, in, like, ilike
+     * - Logical: and, or, not
+     * - Null checking: isNull, isUndefined
+     * - String functions: upper, lower, length, concat
+     * - Numeric: add
+     * - Utility: coalesce
+     * - Aggregates: count, avg, sum, min, max
+     */
+    handlers: {
+        [K in OperatorName]?: (...args: Array<any>) => T;
+    } & {
+        [key: string]: (...args: Array<any>) => T;
+    };
+    /**
+     * Optional handler for when an unknown operator is encountered.
+     * If not provided, unknown operators throw an error.
+     */
+    onUnknownOperator?: (operator: string, args: Array<any>) => T;
+}
+/**
+ * Result of parsing an ORDER BY expression
+ */
+export interface ParsedOrderBy {
+    field: FieldPath;
+    direction: `asc` | `desc`;
+    nulls: `first` | `last`;
+    /** String sorting method: 'lexical' (default) or 'locale' (locale-aware) */
+    stringSort?: `lexical` | `locale`;
+    /** Locale for locale-aware string sorting (e.g., 'en-US') */
+    locale?: string;
+    /** Additional options for locale-aware sorting */
+    localeOptions?: object;
+}
+/**
+ * Extracts the field path from a PropRef expression.
+ * Returns null for non-ref expressions.
+ *
+ * @param expr - The expression to extract from
+ * @returns The field path array, or null
+ *
+ * @example
+ * ```typescript
+ * const field = extractFieldPath(someExpression)
+ * // Returns: ['product', 'category']
+ * ```
+ */
+export declare function extractFieldPath(expr: BasicExpression): FieldPath | null;
+/**
+ * Extracts the value from a Value expression.
+ * Returns undefined for non-value expressions.
+ *
+ * @param expr - The expression to extract from
+ * @returns The extracted value
+ *
+ * @example
+ * ```typescript
+ * const val = extractValue(someExpression)
+ * // Returns: 'electronics'
+ * ```
+ */
+export declare function extractValue(expr: BasicExpression): any;
+/**
+ * Generic expression tree walker that visits each node in the expression.
+ * Useful for implementing custom parsing logic.
+ *
+ * @param expr - The expression to walk
+ * @param visitor - Visitor function called for each node
+ *
+ * @example
+ * ```typescript
+ * walkExpression(whereExpr, (node) => {
+ *   if (node.type === 'func' && node.name === 'eq') {
+ *     console.log('Found equality comparison')
+ *   }
+ * })
+ * ```
+ */
+export declare function walkExpression(expr: BasicExpression | undefined | null, visitor: (node: BasicExpression) => void): void;
+/**
+ * Parses a WHERE expression into a custom format using provided handlers.
+ *
+ * This is the main helper for converting TanStack DB where clauses into your API's filter format.
+ * You provide handlers for each operator, and this function traverses the expression tree
+ * and calls the appropriate handlers.
+ *
+ * @param expr - The WHERE expression to parse
+ * @param options - Configuration with handler functions for each operator
+ * @returns The parsed result in your custom format
+ *
+ * @example
+ * ```typescript
+ * // REST API with query parameters
+ * const filters = parseWhereExpression(where, {
+ *   handlers: {
+ *     eq: (field, value) => ({ [field.join('.')]: value }),
+ *     lt: (field, value) => ({ [`${field.join('.')}_lt`]: value }),
+ *     gt: (field, value) => ({ [`${field.join('.')}_gt`]: value }),
+ *     and: (...filters) => Object.assign({}, ...filters),
+ *     or: (...filters) => ({ $or: filters })
+ *   }
+ * })
+ * // Returns: { category: 'electronics', price_lt: 100 }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // GraphQL where clause
+ * const where = parseWhereExpression(whereExpr, {
+ *   handlers: {
+ *     eq: (field, value) => ({ [field.join('_')]: { _eq: value } }),
+ *     lt: (field, value) => ({ [field.join('_')]: { _lt: value } }),
+ *     and: (...filters) => ({ _and: filters })
+ *   }
+ * })
+ * ```
+ */
+export declare function parseWhereExpression<T = any>(expr: BasicExpression<boolean> | undefined | null, options: ParseWhereOptions<T>): T | null;
+/**
+ * Parses an ORDER BY expression into a simple array of sort specifications.
+ *
+ * @param orderBy - The ORDER BY expression array
+ * @returns Array of parsed order by specifications
+ *
+ * @example
+ * ```typescript
+ * const sorts = parseOrderByExpression(orderBy)
+ * // Returns: [
+ * //   { field: ['category'], direction: 'asc', nulls: 'last' },
+ * //   { field: ['price'], direction: 'desc', nulls: 'last' }
+ * // ]
+ * ```
+ */
+export declare function parseOrderByExpression(orderBy: OrderBy | undefined | null): Array<ParsedOrderBy>;
+/**
+ * Extracts all simple comparisons from a WHERE expression.
+ * This is useful for simple APIs that only support basic filters.
+ *
+ * Note: This only works for simple AND-ed conditions and NOT-wrapped comparisons.
+ * Throws an error if it encounters unsupported operations like OR or complex nested expressions.
+ *
+ * NOT operators are flattened by prefixing the operator name (e.g., `not(eq(...))` becomes `not_eq`).
+ *
+ * @param expr - The WHERE expression to parse
+ * @returns Array of simple comparisons
+ * @throws Error if expression contains OR or other unsupported operations
+ *
+ * @example
+ * ```typescript
+ * const comparisons = extractSimpleComparisons(where)
+ * // Returns: [
+ * //   { field: ['category'], operator: 'eq', value: 'electronics' },
+ * //   { field: ['price'], operator: 'lt', value: 100 },
+ * //   { field: ['email'], operator: 'isNull' }, // No value for null checks
+ * //   { field: ['status'], operator: 'not_eq', value: 'archived' }
+ * // ]
+ * ```
+ */
+export declare function extractSimpleComparisons(expr: BasicExpression<boolean> | undefined | null): Array<SimpleComparison>;
+/**
+ * Convenience function to get all LoadSubsetOptions in a pre-parsed format.
+ * Good starting point for simple use cases.
+ *
+ * @param options - The LoadSubsetOptions from ctx.meta
+ * @returns Pre-parsed filters, sorts, and limit
+ *
+ * @example
+ * ```typescript
+ * queryFn: async (ctx) => {
+ *   const parsed = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)
+ *
+ *   // Convert to your API format
+ *   return api.getProducts({
+ *     ...Object.fromEntries(
+ *       parsed.filters.map(f => [`${f.field.join('.')}_${f.operator}`, f.value])
+ *     ),
+ *     sort: parsed.sorts.map(s => `${s.field.join('.')}:${s.direction}`).join(','),
+ *     limit: parsed.limit
+ *   })
+ * }
+ * ```
+ */
+export declare function parseLoadSubsetOptions(options: {
+    where?: BasicExpression<boolean>;
+    orderBy?: OrderBy;
+    limit?: number;
+} | undefined | null): {
+    filters: Array<SimpleComparison>;
+    sorts: Array<ParsedOrderBy>;
+    limit?: number;
+};
+export {};

package/dist/cjs/query/index.d.cts

@@ -5,3 +5,5 @@ export { compileQuery } from './compiler/index.js';
 export { createLiveQueryCollection, liveQueryCollectionOptions, } from './live-query-collection.js';
 export { type LiveQueryCollectionConfig } from './live/types.js';
 export { type LiveQueryCollectionUtils } from './live/collection-config-builder.js';
+export { isWhereSubset, unionWherePredicates, minusWherePredicates, isOrderBySubset, isLimitSubset, isPredicateSubset, } from './predicate-utils.js';
+export { DeduplicatedLoadSubset } from './subset-dedupe.js';

package/dist/cjs/query/live/collection-config-builder.cjs

@@ -41,6 +41,7 @@ class CollectionConfigBuilder {
     if (this.query.orderBy && this.query.orderBy.length > 0) {
       this.compare = createOrderByComparator(this.orderByIndices);
     }
+    this.compareOptions = this.config.defaultStringCollation ?? extractCollectionFromSource(this.query).compareOptions;
     this.compileBasePipeline();
   }
   /**
@@ -63,6 +64,7 @@ class CollectionConfigBuilder {
       getKey: this.config.getKey || ((item) => this.resultKeys.get(item)),
       sync: this.getSyncConfig(),
       compare: this.compare,
+      defaultStringCollation: this.compareOptions,
       gcTime: this.config.gcTime || 5e3,
       // 5 seconds by default for live queries
       schema: this.config.schema,
@@ -577,6 +579,17 @@ function extractCollectionsFromQuery(query) {
   extractFromQuery(query);
   return collections;
 }
+function extractCollectionFromSource(query) {
+  const from = query.from;
+  if (from.type === `collectionRef`) {
+    return from.collection;
+  } else if (from.type === `queryRef`) {
+    return extractCollectionFromSource(from.query);
+  }
+  throw new Error(
+    `Failed to extract collection. Invalid FROM clause: ${JSON.stringify(query)}`
+  );
+}
 function extractCollectionAliases(query) {
   const aliasesById = /* @__PURE__ */ new Map();
   function recordAlias(source) {