@tanstack/db 0.0.1

package/dist/esm/query/extractors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractors.js","sources":["../../../src/query/extractors.ts"],"sourcesContent":["import { evaluateFunction, isFunctionCall } from \"./functions.js\"\nimport type { AllowedFunctionName, ConditionOperand } from \"./schema.js\"\n\n/**\n * Extracts a value from a nested row structure\n * @param nestedRow The nested row structure\n * @param columnRef The column reference (may include table.column format)\n * @param mainTableAlias The main table alias to check first for columns without table reference\n * @param joinedTableAlias The joined table alias to check second for columns without table reference\n * @returns The extracted value or undefined if not found\n */\nexport function extractValueFromNestedRow(\n  nestedRow: Record<string, unknown>,\n  columnRef: string,\n  mainTableAlias?: string,\n  joinedTableAlias?: string\n): unknown {\n  // Check if it's a table.column reference\n  if (columnRef.includes(`.`)) {\n    const [tableAlias, colName] = columnRef.split(`.`) as [string, string]\n\n    // Get the table data\n    const tableData = nestedRow[tableAlias] as\n      | Record<string, unknown>\n      | null\n      | undefined\n\n    if (!tableData) {\n      return null\n    }\n\n    // Return the column value from that table\n    const value = tableData[colName]\n    return value\n  } else {\n    // If no table is specified, first try to find in the main table if provided\n    if (mainTableAlias && nestedRow[mainTableAlias]) {\n      const mainTableData = nestedRow[mainTableAlias] as Record<string, unknown>\n      if (typeof mainTableData === `object` && columnRef in mainTableData) {\n        return mainTableData[columnRef]\n      }\n    }\n\n    // Then try the joined table if provided\n    if (joinedTableAlias && nestedRow[joinedTableAlias]) {\n      const joinedTableData = nestedRow[joinedTableAlias] as Record<\n        string,\n        unknown\n      >\n      if (typeof joinedTableData === `object` && columnRef in joinedTableData) {\n        return joinedTableData[columnRef]\n      }\n    }\n\n    // If not found in main or joined table, try to find the column in any table\n    for (const [_tableAlias, tableData] of Object.entries(nestedRow)) {\n      if (\n        tableData &&\n        typeof tableData === `object` &&\n        columnRef in (tableData as Record<string, unknown>)\n      ) {\n        return (tableData as Record<string, unknown>)[columnRef]\n      }\n    }\n    return undefined\n  }\n}\n\n/**\n * Evaluates an operand against a nested row structure\n */\nexport function evaluateOperandOnNestedRow(\n  nestedRow: Record<string, unknown>,\n  operand: ConditionOperand,\n  mainTableAlias?: string,\n  joinedTableAlias?: string\n): unknown {\n  // Handle column references\n  if (typeof operand === `string` && operand.startsWith(`@`)) {\n    const columnRef = operand.substring(1)\n    return extractValueFromNestedRow(\n      nestedRow,\n      columnRef,\n      mainTableAlias,\n      joinedTableAlias\n    )\n  }\n\n  // Handle explicit column references\n  if (operand && typeof operand === `object` && `col` in operand) {\n    const colRef = (operand as { col: unknown }).col\n\n    if (typeof colRef === `string`) {\n      // First try to extract from nested row structure\n      const nestedValue = extractValueFromNestedRow(\n        nestedRow,\n        colRef,\n        mainTableAlias,\n        joinedTableAlias\n      )\n\n      // If not found in nested structure, check if it's a direct property of the row\n      // This is important for HAVING clauses that reference aggregated values\n      if (nestedValue === undefined && colRef in nestedRow) {\n        return nestedRow[colRef]\n      }\n\n      return nestedValue\n    }\n\n    return undefined\n  }\n\n  // Handle function calls\n  if (operand && typeof operand === `object` && isFunctionCall(operand)) {\n    // Get the function name (the only key in the object)\n    const functionName = Object.keys(operand)[0] as AllowedFunctionName\n    // Get the arguments using type assertion with specific function name\n    const args = (operand as any)[functionName]\n\n    // If the arguments are a reference or another expression, evaluate them first\n    const evaluatedArgs = Array.isArray(args)\n      ? args.map((arg) =>\n          evaluateOperandOnNestedRow(\n            nestedRow,\n            arg as ConditionOperand,\n            mainTableAlias,\n            joinedTableAlias\n          )\n        )\n      : evaluateOperandOnNestedRow(\n          nestedRow,\n          args as ConditionOperand,\n          mainTableAlias,\n          joinedTableAlias\n        )\n\n    // Call the function with the evaluated arguments\n    return evaluateFunction(\n      functionName,\n      evaluatedArgs as ConditionOperand | Array<ConditionOperand>\n    )\n  }\n\n  // Handle explicit literals\n  if (operand && typeof operand === `object` && `value` in operand) {\n    return (operand as { value: unknown }).value\n  }\n\n  // Handle literal values\n  return operand\n}\n\n/**\n * Extracts a join key value from a row based on the operand\n * @param row The data row (not nested)\n * @param operand The operand to extract the key from\n * @param defaultTableAlias The default table alias\n * @returns The extracted key value\n */\nexport function extractJoinKey<T extends Record<string, unknown>>(\n  row: T,\n  operand: ConditionOperand,\n  defaultTableAlias?: string\n): unknown {\n  let keyValue: unknown\n\n  // Handle column references (e.g., \"@orders.id\" or \"@id\")\n  if (typeof operand === `string` && operand.startsWith(`@`)) {\n    const columnRef = operand.substring(1)\n\n    // If it contains a dot, extract the table and column\n    if (columnRef.includes(`.`)) {\n      const [tableAlias, colName] = columnRef.split(`.`) as [string, string]\n      // If this is referencing the current table, extract from row directly\n      if (tableAlias === defaultTableAlias) {\n        keyValue = row[colName]\n      } else {\n        // This might be a column from another table, return undefined\n        keyValue = undefined\n      }\n    } else {\n      // No table specified, look directly in the row\n      keyValue = row[columnRef]\n    }\n  } else if (operand && typeof operand === `object` && `col` in operand) {\n    // Handle explicit column references like { col: \"orders.id\" } or { col: \"id\" }\n    const colRef = (operand as { col: unknown }).col\n\n    if (typeof colRef === `string`) {\n      if (colRef.includes(`.`)) {\n        const [tableAlias, colName] = colRef.split(`.`) as [string, string]\n        // If this is referencing the current table, extract from row directly\n        if (tableAlias === defaultTableAlias) {\n          keyValue = row[colName]\n        } else {\n          // This might be a column from another table, return undefined\n          keyValue = undefined\n        }\n      } else {\n        // No table specified, look directly in the row\n        keyValue = row[colRef]\n      }\n    }\n  } else {\n    // Handle literals or other types\n    keyValue = operand\n  }\n\n  return keyValue\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/query/functions.d.ts

@@ -0,0 +1,21 @@
+import { AllowedFunctionName } from './schema.js';
+/**
+ * Evaluates a function call with the given name and arguments
+ * @param functionName The name of the function to evaluate
+ * @param arg The arguments to pass to the function
+ * @returns The result of the function call
+ */
+export declare function evaluateFunction(functionName: AllowedFunctionName, arg: unknown): unknown;
+/**
+ * Determines if an object is a function call
+ * @param obj The object to check
+ * @returns True if the object is a function call, false otherwise
+ */
+export declare function isFunctionCall(obj: unknown): boolean;
+/**
+ * Extracts the function name and argument from a function call object.
+ */
+export declare function extractFunctionCall(obj: Record<string, unknown>): {
+    functionName: AllowedFunctionName;
+    argument: unknown;
+};

package/dist/esm/query/functions.js

@@ -0,0 +1,152 @@
+function upperFunction(arg) {
+  if (typeof arg !== `string`) {
+    throw new Error(`UPPER function expects a string argument`);
+  }
+  return arg.toUpperCase();
+}
+function lowerFunction(arg) {
+  if (typeof arg !== `string`) {
+    throw new Error(`LOWER function expects a string argument`);
+  }
+  return arg.toLowerCase();
+}
+function lengthFunction(arg) {
+  if (typeof arg === `string` || Array.isArray(arg)) {
+    return arg.length;
+  }
+  throw new Error(`LENGTH function expects a string or array argument`);
+}
+function concatFunction(arg) {
+  if (!Array.isArray(arg)) {
+    throw new Error(`CONCAT function expects an array of string arguments`);
+  }
+  if (arg.length === 0) {
+    return ``;
+  }
+  for (let i = 0; i < arg.length; i++) {
+    if (arg[i] !== null && arg[i] !== void 0 && typeof arg[i] !== `string`) {
+      throw new Error(
+        `CONCAT function expects all arguments to be strings, but argument at position ${i} is ${typeof arg[i]}`
+      );
+    }
+  }
+  return arg.map((str) => str === null || str === void 0 ? `` : str).join(``);
+}
+function coalesceFunction(arg) {
+  if (!Array.isArray(arg)) {
+    throw new Error(`COALESCE function expects an array of arguments`);
+  }
+  if (arg.length === 0) {
+    return null;
+  }
+  for (const value of arg) {
+    if (value !== null && value !== void 0) {
+      return value;
+    }
+  }
+  return null;
+}
+function dateFunction(arg) {
+  if (arg instanceof Date) {
+    return arg;
+  }
+  if (arg === null || arg === void 0) {
+    return null;
+  }
+  if (typeof arg === `string` || typeof arg === `number`) {
+    const date = new Date(arg);
+    if (isNaN(date.getTime())) {
+      throw new Error(`DATE function could not parse "${arg}" as a valid date`);
+    }
+    return date;
+  }
+  throw new Error(`DATE function expects a string, number, or Date argument`);
+}
+function jsonExtractFunction(arg) {
+  if (!Array.isArray(arg) || arg.length < 1) {
+    throw new Error(
+      `JSON_EXTRACT function expects an array with at least one element [jsonInput, ...pathElements]`
+    );
+  }
+  const [jsonInput, ...pathElements] = arg;
+  if (jsonInput === null || jsonInput === void 0) {
+    return null;
+  }
+  let jsonData;
+  if (typeof jsonInput === `string`) {
+    try {
+      jsonData = JSON.parse(jsonInput);
+    } catch (error) {
+      throw new Error(
+        `JSON_EXTRACT function could not parse JSON string: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  } else if (typeof jsonInput === `object`) {
+    jsonData = jsonInput;
+  } else {
+    throw new Error(
+      `JSON_EXTRACT function expects a JSON string or object as the first argument`
+    );
+  }
+  if (pathElements.length === 0) {
+    return jsonData;
+  }
+  let current = jsonData;
+  for (let i = 0; i < pathElements.length; i++) {
+    const pathElement = pathElements[i];
+    if (typeof pathElement !== `string`) {
+      throw new Error(
+        `JSON_EXTRACT function expects path elements to be strings, but element at position ${i + 1} is ${typeof pathElement}`
+      );
+    }
+    if (current === null || current === void 0 || typeof current !== `object`) {
+      return null;
+    }
+    current = current[pathElement];
+  }
+  return current === void 0 ? null : current;
+}
+function orderIndexFunction(arg) {
+  if (arg !== `numeric` && arg !== `fractional` && arg !== true && arg !== `default`) {
+    throw new Error(
+      `ORDER_INDEX function expects "numeric", "fractional", "default", or true as argument`
+    );
+  }
+  return null;
+}
+const functionImplementations = {
+  // Map function names to their implementation functions
+  DATE: dateFunction,
+  JSON_EXTRACT: jsonExtractFunction,
+  JSON_EXTRACT_PATH: jsonExtractFunction,
+  // Alias for JSON_EXTRACT
+  UPPER: upperFunction,
+  LOWER: lowerFunction,
+  COALESCE: coalesceFunction,
+  CONCAT: concatFunction,
+  LENGTH: lengthFunction,
+  ORDER_INDEX: orderIndexFunction
+};
+function evaluateFunction(functionName, arg) {
+  const implementation = functionImplementations[functionName];
+  if (!implementation) {
+    throw new Error(`Unknown function: ${functionName}`);
+  }
+  return implementation(arg);
+}
+function isFunctionCall(obj) {
+  if (!obj || typeof obj !== `object`) {
+    return false;
+  }
+  const keys = Object.keys(obj);
+  if (keys.length !== 1) {
+    return false;
+  }
+  const functionName = keys[0];
+  return Object.keys(functionImplementations).includes(functionName);
+}
+export {
+  evaluateFunction,
+  isFunctionCall
+};
+//# sourceMappingURL=functions.js.map

package/dist/esm/query/functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.js","sources":["../../../src/query/functions.ts"],"sourcesContent":["import type { AllowedFunctionName } from \"./schema.js\"\n\n/**\n * Type for function implementations\n */\ntype FunctionImplementation = (arg: unknown) => unknown\n\n/**\n * Converts a string to uppercase\n */\nfunction upperFunction(arg: unknown): string {\n  if (typeof arg !== `string`) {\n    throw new Error(`UPPER function expects a string argument`)\n  }\n  return arg.toUpperCase()\n}\n\n/**\n * Converts a string to lowercase\n */\nfunction lowerFunction(arg: unknown): string {\n  if (typeof arg !== `string`) {\n    throw new Error(`LOWER function expects a string argument`)\n  }\n  return arg.toLowerCase()\n}\n\n/**\n * Returns the length of a string or array\n */\nfunction lengthFunction(arg: unknown): number {\n  if (typeof arg === `string` || Array.isArray(arg)) {\n    return arg.length\n  }\n\n  throw new Error(`LENGTH function expects a string or array argument`)\n}\n\n/**\n * Concatenates multiple strings\n */\nfunction concatFunction(arg: unknown): string {\n  if (!Array.isArray(arg)) {\n    throw new Error(`CONCAT function expects an array of string arguments`)\n  }\n\n  if (arg.length === 0) {\n    return ``\n  }\n\n  // Check that all arguments are strings\n  for (let i = 0; i < arg.length; i++) {\n    if (arg[i] !== null && arg[i] !== undefined && typeof arg[i] !== `string`) {\n      throw new Error(\n        `CONCAT function expects all arguments to be strings, but argument at position ${i} is ${typeof arg[i]}`\n      )\n    }\n  }\n\n  // Concatenate strings, treating null and undefined as empty strings\n  return arg\n    .map((str) => (str === null || str === undefined ? `` : str))\n    .join(``)\n}\n\n/**\n * Returns the first non-null, non-undefined value from an array\n */\nfunction coalesceFunction(arg: unknown): unknown {\n  if (!Array.isArray(arg)) {\n    throw new Error(`COALESCE function expects an array of arguments`)\n  }\n\n  if (arg.length === 0) {\n    return null\n  }\n\n  // Return the first non-null, non-undefined value\n  for (const value of arg) {\n    if (value !== null && value !== undefined) {\n      return value\n    }\n  }\n\n  // If all values were null or undefined, return null\n  return null\n}\n\n/**\n * Creates or converts a value to a Date object\n */\nfunction dateFunction(arg: unknown): Date | null {\n  // If the argument is already a Date, return it\n  if (arg instanceof Date) {\n    return arg\n  }\n\n  // If the argument is null or undefined, return null\n  if (arg === null || arg === undefined) {\n    return null\n  }\n\n  // Handle string and number conversions\n  if (typeof arg === `string` || typeof arg === `number`) {\n    const date = new Date(arg)\n\n    // Check if the date is valid\n    if (isNaN(date.getTime())) {\n      throw new Error(`DATE function could not parse \"${arg}\" as a valid date`)\n    }\n\n    return date\n  }\n\n  throw new Error(`DATE function expects a string, number, or Date argument`)\n}\n\n/**\n * Extracts a value from a JSON string or object using a path.\n * Similar to PostgreSQL's json_extract_path function.\n *\n * Usage: JSON_EXTRACT([jsonInput, 'path', 'to', 'property'])\n * Example: JSON_EXTRACT(['{\"user\": {\"name\": \"John\"}}', 'user', 'name']) returns \"John\"\n */\nfunction jsonExtractFunction(arg: unknown): unknown {\n  if (!Array.isArray(arg) || arg.length < 1) {\n    throw new Error(\n      `JSON_EXTRACT function expects an array with at least one element [jsonInput, ...pathElements]`\n    )\n  }\n\n  const [jsonInput, ...pathElements] = arg\n\n  // Handle null or undefined input\n  if (jsonInput === null || jsonInput === undefined) {\n    return null\n  }\n\n  // Parse JSON if it's a string\n  let jsonData: any\n\n  if (typeof jsonInput === `string`) {\n    try {\n      jsonData = JSON.parse(jsonInput)\n    } catch (error) {\n      throw new Error(\n        `JSON_EXTRACT function could not parse JSON string: ${error instanceof Error ? error.message : String(error)}`\n      )\n    }\n  } else if (typeof jsonInput === `object`) {\n    // If already an object, use it directly\n    jsonData = jsonInput\n  } else {\n    throw new Error(\n      `JSON_EXTRACT function expects a JSON string or object as the first argument`\n    )\n  }\n\n  // If no path elements, return the parsed JSON\n  if (pathElements.length === 0) {\n    return jsonData\n  }\n\n  // Navigate through the path elements\n  let current = jsonData\n\n  for (let i = 0; i < pathElements.length; i++) {\n    const pathElement = pathElements[i]\n\n    // Path elements should be strings\n    if (typeof pathElement !== `string`) {\n      throw new Error(\n        `JSON_EXTRACT function expects path elements to be strings, but element at position ${i + 1} is ${typeof pathElement}`\n      )\n    }\n\n    // If current node is null or undefined, or not an object, we can't navigate further\n    if (\n      current === null ||\n      current === undefined ||\n      typeof current !== `object`\n    ) {\n      return null\n    }\n\n    // Access property\n    current = current[pathElement]\n  }\n\n  // Return null instead of undefined for consistency\n  return current === undefined ? null : current\n}\n\n/**\n * Placeholder function for ORDER_INDEX\n * This function doesn't do anything when called directly, as the actual index\n * is provided by the orderBy operator during query execution.\n * The argument can be 'numeric', 'fractional', or any truthy value (defaults to 'numeric')\n */\nfunction orderIndexFunction(arg: unknown): null {\n  // This is just a placeholder - the actual index is provided by the orderBy operator\n  // The function validates that the argument is one of the expected values\n  if (\n    arg !== `numeric` &&\n    arg !== `fractional` &&\n    arg !== true &&\n    arg !== `default`\n  ) {\n    throw new Error(\n      `ORDER_INDEX function expects \"numeric\", \"fractional\", \"default\", or true as argument`\n    )\n  }\n  return null\n}\n\n/**\n * Map of function names to their implementations\n */\nconst functionImplementations: Record<\n  AllowedFunctionName,\n  FunctionImplementation\n> = {\n  // Map function names to their implementation functions\n  DATE: dateFunction,\n  JSON_EXTRACT: jsonExtractFunction,\n  JSON_EXTRACT_PATH: jsonExtractFunction, // Alias for JSON_EXTRACT\n  UPPER: upperFunction,\n  LOWER: lowerFunction,\n  COALESCE: coalesceFunction,\n  CONCAT: concatFunction,\n  LENGTH: lengthFunction,\n  ORDER_INDEX: orderIndexFunction,\n}\n\n/**\n * Evaluates a function call with the given name and arguments\n * @param functionName The name of the function to evaluate\n * @param arg The arguments to pass to the function\n * @returns The result of the function call\n */\nexport function evaluateFunction(\n  functionName: AllowedFunctionName,\n  arg: unknown\n): unknown {\n  const implementation = functionImplementations[functionName] as\n    | FunctionImplementation\n    | undefined // Double check that the implementation is defined\n\n  if (!implementation) {\n    throw new Error(`Unknown function: ${functionName}`)\n  }\n  return implementation(arg)\n}\n\n/**\n * Determines if an object is a function call\n * @param obj The object to check\n * @returns True if the object is a function call, false otherwise\n */\nexport function isFunctionCall(obj: unknown): boolean {\n  if (!obj || typeof obj !== `object`) {\n    return false\n  }\n\n  const keys = Object.keys(obj)\n  if (keys.length !== 1) {\n    return false\n  }\n\n  const functionName = keys[0] as string\n\n  // Check if the key is one of the allowed function names\n  return Object.keys(functionImplementations).includes(functionName)\n}\n\n/**\n * Extracts the function name and argument from a function call object.\n */\nexport function extractFunctionCall(obj: Record<string, unknown>): {\n  functionName: AllowedFunctionName\n  argument: unknown\n} {\n  const keys = Object.keys(obj)\n  if (keys.length !== 1) {\n    throw new Error(`Invalid function call: object must have exactly one key`)\n  }\n\n  const functionName = keys[0] as AllowedFunctionName\n  if (!Object.keys(functionImplementations).includes(functionName)) {\n    throw new Error(`Invalid function name: ${functionName}`)\n  }\n\n  return {\n    functionName,\n    argument: obj[functionName],\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/query/group-by.d.ts

@@ -0,0 +1,40 @@
+import { ConditionOperand, Query } from './schema.js';
+import { IStreamBuilder } from '@electric-sql/d2ts';
+/**
+ * Process the groupBy clause in a D2QL query
+ */
+export declare function processGroupBy(pipeline: IStreamBuilder<Record<string, unknown>>, query: Query, mainTableAlias: string): IStreamBuilder<Record<string, unknown>>;
+/**
+ * Helper function to get an aggregate function based on the function name
+ */
+export declare function getAggregateFunction(functionName: string, columnRef: string | ConditionOperand, mainTableAlias: string): {
+    preMap: (data: Record<string, unknown>) => number;
+    reduce: (values: [number, number][]) => number;
+    postMap?: ((result: number) => number) | undefined;
+} | {
+    pipe: (stream: IStreamBuilder<Record<string, unknown>>) => IStreamBuilder<import('@electric-sql/d2ts').KeyValue<string, number>>;
+} | {
+    preMap: (data: Record<string, unknown>) => {
+        sum: number;
+        count: number;
+    };
+    reduce: (values: [{
+        sum: number;
+        count: number;
+    }, number][]) => {
+        sum: number;
+        count: number;
+    };
+    postMap?: ((result: {
+        sum: number;
+        count: number;
+    }) => number) | undefined;
+} | {
+    preMap: (data: Record<string, unknown>) => number[];
+    reduce: (values: [number[], number][]) => number[];
+    postMap?: ((result: number[]) => number) | undefined;
+} | {
+    preMap: (data: Record<string, unknown>) => Map<number, number>;
+    reduce: (values: [Map<number, number>, number][]) => Map<number, number>;
+    postMap?: ((result: Map<number, number>) => number) | undefined;
+};

package/dist/esm/query/group-by.js

@@ -0,0 +1,91 @@
+import { groupBy, map, groupByOperators } from "@electric-sql/d2ts";
+import { extractValueFromNestedRow, evaluateOperandOnNestedRow } from "./extractors.js";
+import { isAggregateFunctionCall } from "./utils.js";
+const { sum, count, avg, min, max, median, mode } = groupByOperators;
+function processGroupBy(pipeline, query, mainTableAlias) {
+  const groupByColumns = Array.isArray(query.groupBy) ? query.groupBy : [query.groupBy];
+  const keyExtractor = (nestedRow) => {
+    const key = {};
+    for (const column of groupByColumns) {
+      if (typeof column === `string` && column.startsWith(`@`)) {
+        const columnRef = column.substring(1);
+        const columnName = columnRef.includes(`.`) ? columnRef.split(`.`)[1] : columnRef;
+        key[columnName] = extractValueFromNestedRow(
+          nestedRow,
+          columnRef,
+          mainTableAlias
+        );
+      }
+    }
+    return key;
+  };
+  const aggregates = {};
+  for (const item of query.select) {
+    if (typeof item === `object`) {
+      for (const [alias, expr] of Object.entries(item)) {
+        if (typeof expr === `object` && isAggregateFunctionCall(expr)) {
+          const functionName = Object.keys(expr)[0];
+          const columnRef = expr[functionName];
+          aggregates[alias] = getAggregateFunction(
+            functionName,
+            columnRef,
+            mainTableAlias
+          );
+        }
+      }
+    }
+  }
+  if (Object.keys(aggregates).length > 0) {
+    pipeline = pipeline.pipe(
+      groupBy(keyExtractor, aggregates),
+      // Convert KeyValue<string, ResultType> to Record<string, unknown>
+      map(([_key, value]) => {
+        return value;
+      })
+    );
+  }
+  return pipeline;
+}
+function getAggregateFunction(functionName, columnRef, mainTableAlias) {
+  const valueExtractor = (nestedRow) => {
+    let value;
+    if (typeof columnRef === `string` && columnRef.startsWith(`@`)) {
+      value = extractValueFromNestedRow(
+        nestedRow,
+        columnRef.substring(1),
+        mainTableAlias
+      );
+    } else {
+      value = evaluateOperandOnNestedRow(
+        nestedRow,
+        columnRef,
+        mainTableAlias
+      );
+    }
+    return typeof value === `number` ? value : 0;
+  };
+  switch (functionName.toUpperCase()) {
+    case `SUM`:
+      return sum(valueExtractor);
+    case `COUNT`:
+      return count();
+    // count() doesn't need a value extractor
+    case `AVG`:
+      return avg(valueExtractor);
+    case `MIN`:
+      return min(valueExtractor);
+    case `MAX`:
+      return max(valueExtractor);
+    case `MEDIAN`:
+      return median(valueExtractor);
+    case `MODE`:
+      return mode(valueExtractor);
+    default:
+      throw new Error(`Unsupported aggregate function: ${functionName}`);
+  }
+}
+export {
+  getAggregateFunction,
+  processGroupBy
+};
+//# sourceMappingURL=group-by.js.map

package/dist/esm/query/group-by.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-by.js","sources":["../../../src/query/group-by.ts"],"sourcesContent":["import { groupBy, groupByOperators, map } from \"@electric-sql/d2ts\"\nimport {\n  evaluateOperandOnNestedRow,\n  extractValueFromNestedRow,\n} from \"./extractors\"\nimport { isAggregateFunctionCall } from \"./utils\"\nimport type { ConditionOperand, FunctionCall, Query } from \"./schema\"\nimport type { IStreamBuilder } from \"@electric-sql/d2ts\"\n\nconst { sum, count, avg, min, max, median, mode } = groupByOperators\n\n/**\n * Process the groupBy clause in a D2QL query\n */\nexport function processGroupBy(\n  pipeline: IStreamBuilder<Record<string, unknown>>,\n  query: Query,\n  mainTableAlias: string\n) {\n  // Normalize groupBy to an array of column references\n  const groupByColumns = Array.isArray(query.groupBy)\n    ? query.groupBy\n    : [query.groupBy]\n\n  // Create a key extractor function for the groupBy operator\n  const keyExtractor = (nestedRow: Record<string, unknown>) => {\n    const key: Record<string, unknown> = {}\n\n    // Extract each groupBy column value\n    for (const column of groupByColumns) {\n      if (typeof column === `string` && (column as string).startsWith(`@`)) {\n        const columnRef = (column as string).substring(1)\n        const columnName = columnRef.includes(`.`)\n          ? columnRef.split(`.`)[1]\n          : columnRef\n\n        key[columnName!] = extractValueFromNestedRow(\n          nestedRow,\n          columnRef,\n          mainTableAlias\n        )\n      }\n    }\n\n    return key\n  }\n\n  // Create aggregate functions for any aggregated columns in the SELECT clause\n  const aggregates: Record<string, any> = {}\n\n  // Scan the SELECT clause for aggregate functions\n  for (const item of query.select) {\n    if (typeof item === `object`) {\n      for (const [alias, expr] of Object.entries(item)) {\n        if (typeof expr === `object` && isAggregateFunctionCall(expr)) {\n          // Get the function name (the only key in the object)\n          const functionName = Object.keys(expr)[0]\n          // Get the column reference or expression to aggregate\n          const columnRef = (expr as FunctionCall)[\n            functionName as keyof FunctionCall\n          ]\n\n          // Add the aggregate function to our aggregates object\n          aggregates[alias] = getAggregateFunction(\n            functionName!,\n            columnRef,\n            mainTableAlias\n          )\n        }\n      }\n    }\n  }\n\n  // Apply the groupBy operator if we have any aggregates\n  if (Object.keys(aggregates).length > 0) {\n    pipeline = pipeline.pipe(\n      groupBy(keyExtractor, aggregates),\n      // Convert KeyValue<string, ResultType> to Record<string, unknown>\n      map(([_key, value]) => {\n        // After groupBy, the value already contains both the key fields and aggregate results\n        // We need to return it as is, not wrapped in a nested structure\n        return value as Record<string, unknown>\n      })\n    )\n  }\n\n  return pipeline\n}\n\n/**\n * Helper function to get an aggregate function based on the function name\n */\nexport function getAggregateFunction(\n  functionName: string,\n  columnRef: string | ConditionOperand,\n  mainTableAlias: string\n) {\n  // Create a value extractor function for the column to aggregate\n  const valueExtractor = (nestedRow: Record<string, unknown>) => {\n    let value: unknown\n    if (typeof columnRef === `string` && columnRef.startsWith(`@`)) {\n      value = extractValueFromNestedRow(\n        nestedRow,\n        columnRef.substring(1),\n        mainTableAlias\n      )\n    } else {\n      value = evaluateOperandOnNestedRow(\n        nestedRow,\n        columnRef as ConditionOperand,\n        mainTableAlias\n      )\n    }\n    // Ensure we return a number for aggregate functions\n    return typeof value === `number` ? value : 0\n  }\n\n  // Return the appropriate aggregate function\n  switch (functionName.toUpperCase()) {\n    case `SUM`:\n      return sum(valueExtractor)\n    case `COUNT`:\n      return count() // count() doesn't need a value extractor\n    case `AVG`:\n      return avg(valueExtractor)\n    case `MIN`:\n      return min(valueExtractor)\n    case `MAX`:\n      return max(valueExtractor)\n    case `MEDIAN`:\n      return median(valueExtractor)\n    case `MODE`:\n      return mode(valueExtractor)\n    default:\n      throw new Error(`Unsupported aggregate function: ${functionName}`)\n  }\n}\n"],"names":[],"mappings":";;;AASA,MAAM,EAAE,KAAK,OAAO,KAAK,KAAK,KAAK,QAAQ,SAAS;AAKpC,SAAA,eACd,UACA,OACA,gBACA;AAEM,QAAA,iBAAiB,MAAM,QAAQ,MAAM,OAAO,IAC9C,MAAM,UACN,CAAC,MAAM,OAAO;AAGZ,QAAA,eAAe,CAAC,cAAuC;AAC3D,UAAM,MAA+B,CAAC;AAGtC,eAAW,UAAU,gBAAgB;AACnC,UAAI,OAAO,WAAW,YAAa,OAAkB,WAAW,GAAG,GAAG;AAC9D,cAAA,YAAa,OAAkB,UAAU,CAAC;AAC1C,cAAA,aAAa,UAAU,SAAS,GAAG,IACrC,UAAU,MAAM,GAAG,EAAE,CAAC,IACtB;AAEJ,YAAI,UAAW,IAAI;AAAA,UACjB;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,MAAA;AAAA,IACF;AAGK,WAAA;AAAA,EACT;AAGA,QAAM,aAAkC,CAAC;AAG9B,aAAA,QAAQ,MAAM,QAAQ;AAC3B,QAAA,OAAO,SAAS,UAAU;AAC5B,iBAAW,CAAC,OAAO,IAAI,KAAK,OAAO,QAAQ,IAAI,GAAG;AAChD,YAAI,OAAO,SAAS,YAAY,wBAAwB,IAAI,GAAG;AAE7D,gBAAM,eAAe,OAAO,KAAK,IAAI,EAAE,CAAC;AAElC,gBAAA,YAAa,KACjB,YACF;AAGA,qBAAW,KAAK,IAAI;AAAA,YAClB;AAAA,YACA;AAAA,YACA;AAAA,UACF;AAAA,QAAA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAIF,MAAI,OAAO,KAAK,UAAU,EAAE,SAAS,GAAG;AACtC,eAAW,SAAS;AAAA,MAClB,QAAQ,cAAc,UAAU;AAAA;AAAA,MAEhC,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM;AAGd,eAAA;AAAA,MACR,CAAA;AAAA,IACH;AAAA,EAAA;AAGK,SAAA;AACT;AAKgB,SAAA,qBACd,cACA,WACA,gBACA;AAEM,QAAA,iBAAiB,CAAC,cAAuC;AACzD,QAAA;AACJ,QAAI,OAAO,cAAc,YAAY,UAAU,WAAW,GAAG,GAAG;AACtD,cAAA;AAAA,QACN;AAAA,QACA,UAAU,UAAU,CAAC;AAAA,QACrB;AAAA,MACF;AAAA,IAAA,OACK;AACG,cAAA;AAAA,QACN;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IAAA;AAGK,WAAA,OAAO,UAAU,WAAW,QAAQ;AAAA,EAC7C;AAGQ,UAAA,aAAa,YAAe,GAAA;AAAA,IAClC,KAAK;AACH,aAAO,IAAI,cAAc;AAAA,IAC3B,KAAK;AACH,aAAO,MAAM;AAAA;AAAA,IACf,KAAK;AACH,aAAO,IAAI,cAAc;AAAA,IAC3B,KAAK;AACH,aAAO,IAAI,cAAc;AAAA,IAC3B,KAAK;AACH,aAAO,IAAI,cAAc;AAAA,IAC3B,KAAK;AACH,aAAO,OAAO,cAAc;AAAA,IAC9B,KAAK;AACH,aAAO,KAAK,cAAc;AAAA,IAC5B;AACE,YAAM,IAAI,MAAM,mCAAmC,YAAY,EAAE;AAAA,EAAA;AAEvE;"}

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

@@ -0,0 +1,5 @@
+export * from './query-builder.js';
+export * from './compiled-query.js';
+export * from './pipeline-compiler.js';
+export * from './schema.js';
+export * from './types.js';

package/dist/esm/query/joins.d.ts

@@ -0,0 +1,14 @@
+import { Query } from './index.js';
+import { IStreamBuilder } from '@electric-sql/d2ts';
+/**
+ * Creates a processing pipeline for join clauses
+ */
+export declare function processJoinClause(pipeline: IStreamBuilder<Record<string, unknown>>, query: Query, tables: Record<string, IStreamBuilder<Record<string, unknown>>>, mainTableAlias: string, allInputs: Record<string, IStreamBuilder<Record<string, unknown>>>): IStreamBuilder<Record<string, unknown>>;
+/**
+ * Creates a processing pipeline for join results
+ */
+export declare function processJoinResults(mainTableAlias: string, joinedTableAlias: string, joinClause: {
+    on: any;
+    where?: any;
+    type: string;
+}): (pipeline: IStreamBuilder<unknown>) => IStreamBuilder<Record<string, unknown>>;

package/dist/esm/query/joins.js

@@ -0,0 +1,155 @@
+import { map, join, consolidate, filter } from "@electric-sql/d2ts";
+import { evaluateConditionOnNestedRow } from "./evaluators.js";
+import { extractJoinKey } from "./extractors.js";
+function processJoinClause(pipeline, query, tables, mainTableAlias, allInputs) {
+  if (!query.join) return pipeline;
+  const input = allInputs[query.from];
+  for (const joinClause of query.join) {
+    const joinedTableAlias = joinClause.as || joinClause.from;
+    const joinType = joinClause.type === `cross` ? `inner` : joinClause.type;
+    const mainPipeline = pipeline.pipe(
+      map((nestedRow) => {
+        const mainRow = nestedRow[mainTableAlias];
+        const keyValue = extractJoinKey(
+          mainRow,
+          joinClause.on[0],
+          mainTableAlias
+        );
+        return [keyValue, nestedRow];
+      })
+    );
+    let joinedTableInput;
+    if (allInputs[joinClause.from]) {
+      joinedTableInput = allInputs[joinClause.from];
+    } else {
+      joinedTableInput = input.graph.newInput();
+    }
+    tables[joinedTableAlias] = joinedTableInput;
+    const joinedPipeline = joinedTableInput.pipe(
+      map((row) => {
+        const nestedRow = { [joinedTableAlias]: row };
+        const keyValue = extractJoinKey(row, joinClause.on[2], joinedTableAlias);
+        return [keyValue, nestedRow];
+      })
+    );
+    switch (joinType) {
+      case `inner`:
+        pipeline = mainPipeline.pipe(
+          join(joinedPipeline, `inner`),
+          consolidate(),
+          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)
+        );
+        break;
+      case `left`:
+        pipeline = mainPipeline.pipe(
+          join(joinedPipeline, `left`),
+          consolidate(),
+          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)
+        );
+        break;
+      case `right`:
+        pipeline = mainPipeline.pipe(
+          join(joinedPipeline, `right`),
+          consolidate(),
+          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)
+        );
+        break;
+      case `full`:
+        pipeline = mainPipeline.pipe(
+          join(joinedPipeline, `full`),
+          consolidate(),
+          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)
+        );
+        break;
+      default:
+        pipeline = mainPipeline.pipe(
+          join(joinedPipeline, `inner`),
+          consolidate(),
+          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)
+        );
+    }
+  }
+  return pipeline;
+}
+function processJoinResults(mainTableAlias, joinedTableAlias, joinClause) {
+  return function(pipeline) {
+    return pipeline.pipe(
+      // Process the join result and handle nulls in the same step
+      map((result) => {
+        const [_key, [mainNestedRow, joinedNestedRow]] = result;
+        if (joinClause.type === `inner` || joinClause.type === `cross`) {
+          if (!mainNestedRow || !joinedNestedRow) {
+            return void 0;
+          }
+        }
+        if (joinClause.type === `left` && !mainNestedRow) {
+          return void 0;
+        }
+        if (joinClause.type === `right` && !joinedNestedRow) {
+          return void 0;
+        }
+        const mergedNestedRow = {};
+        if (mainNestedRow) {
+          Object.entries(mainNestedRow).forEach(([tableAlias, tableData]) => {
+            mergedNestedRow[tableAlias] = tableData;
+          });
+        }
+        if (joinedNestedRow) {
+          Object.entries(joinedNestedRow).forEach(([tableAlias, tableData]) => {
+            mergedNestedRow[tableAlias] = tableData;
+          });
+        } else if (joinClause.type === `left` || joinClause.type === `full`) {
+          mergedNestedRow[joinedTableAlias] = null;
+        }
+        if (!mainNestedRow && (joinClause.type === `right` || joinClause.type === `full`)) {
+          mergedNestedRow[mainTableAlias] = null;
+        }
+        return mergedNestedRow;
+      }),
+      // Filter out undefined results
+      filter(
+        (value) => value !== void 0
+      ),
+      // Process the ON condition
+      filter((nestedRow) => {
+        if (!joinClause.on || joinClause.type === `cross`) {
+          return true;
+        }
+        if (joinClause.type === `left` && nestedRow[joinedTableAlias] === null) {
+          return true;
+        }
+        if (joinClause.type === `right` && nestedRow[mainTableAlias] === null) {
+          return true;
+        }
+        if (joinClause.type === `full` && (nestedRow[mainTableAlias] === null || nestedRow[joinedTableAlias] === null)) {
+          return true;
+        }
+        const result = evaluateConditionOnNestedRow(
+          nestedRow,
+          joinClause.on,
+          mainTableAlias,
+          joinedTableAlias
+        );
+        return result;
+      }),
+      // Process the WHERE clause for the join if it exists
+      filter((nestedRow) => {
+        if (!joinClause.where) {
+          return true;
+        }
+        const result = evaluateConditionOnNestedRow(
+          nestedRow,
+          joinClause.where,
+          mainTableAlias,
+          joinedTableAlias
+        );
+        return result;
+      })
+    );
+  };
+}
+export {
+  processJoinClause,
+  processJoinResults
+};
+//# sourceMappingURL=joins.js.map

package/dist/esm/query/joins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"joins.js","sources":["../../../src/query/joins.ts"],"sourcesContent":["import {\n  consolidate,\n  filter,\n  join as joinOperator,\n  map,\n} from \"@electric-sql/d2ts\"\nimport { evaluateConditionOnNestedRow } from \"./evaluators.js\"\nimport { extractJoinKey } from \"./extractors.js\"\nimport type { Query } from \"./index.js\"\nimport type { IStreamBuilder, JoinType } from \"@electric-sql/d2ts\"\n\n/**\n * Creates a processing pipeline for join clauses\n */\nexport function processJoinClause(\n  pipeline: IStreamBuilder<Record<string, unknown>>,\n  query: Query,\n  tables: Record<string, IStreamBuilder<Record<string, unknown>>>,\n  mainTableAlias: string,\n  allInputs: Record<string, IStreamBuilder<Record<string, unknown>>>\n) {\n  if (!query.join) return pipeline\n  const input = allInputs[query.from]\n\n  for (const joinClause of query.join) {\n    // Create a stream for the joined table\n    const joinedTableAlias = joinClause.as || joinClause.from\n\n    // Get the right join type for the operator\n    const joinType: JoinType =\n      joinClause.type === `cross` ? `inner` : joinClause.type\n\n    // We need to prepare the main pipeline and the joined pipeline\n    // to have the correct key format for joining\n    const mainPipeline = pipeline.pipe(\n      map((nestedRow: Record<string, unknown>) => {\n        // Extract the key from the ON condition left side for the main table\n        const mainRow = nestedRow[mainTableAlias] as Record<string, unknown>\n\n        // Extract the join key from the main row\n        const keyValue = extractJoinKey(\n          mainRow,\n          joinClause.on[0],\n          mainTableAlias\n        )\n\n        // Return [key, nestedRow] as a KeyValue type\n        return [keyValue, nestedRow] as [unknown, Record<string, unknown>]\n      })\n    )\n\n    // Get the joined table input from the inputs map\n    let joinedTableInput: IStreamBuilder<Record<string, unknown>>\n\n    if (allInputs[joinClause.from]) {\n      // Use the provided input if available\n      joinedTableInput = allInputs[joinClause.from]!\n    } else {\n      // Create a new input if not provided\n      joinedTableInput = input!.graph.newInput<Record<string, unknown>>()\n    }\n\n    tables[joinedTableAlias] = joinedTableInput\n\n    // Create a pipeline for the joined table\n    const joinedPipeline = joinedTableInput.pipe(\n      map((row: Record<string, unknown>) => {\n        // Wrap the row in an object with the table alias as the key\n        const nestedRow = { [joinedTableAlias]: row }\n\n        // Extract the key from the ON condition right side for the joined table\n        const keyValue = extractJoinKey(row, joinClause.on[2], joinedTableAlias)\n\n        // Return [key, nestedRow] as a KeyValue type\n        return [keyValue, nestedRow] as [unknown, Record<string, unknown>]\n      })\n    )\n\n    // Apply join with appropriate typings based on join type\n    switch (joinType) {\n      case `inner`:\n        pipeline = mainPipeline.pipe(\n          joinOperator(joinedPipeline, `inner`),\n          consolidate(),\n          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)\n        )\n        break\n      case `left`:\n        pipeline = mainPipeline.pipe(\n          joinOperator(joinedPipeline, `left`),\n          consolidate(),\n          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)\n        )\n        break\n      case `right`:\n        pipeline = mainPipeline.pipe(\n          joinOperator(joinedPipeline, `right`),\n          consolidate(),\n          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)\n        )\n        break\n      case `full`:\n        pipeline = mainPipeline.pipe(\n          joinOperator(joinedPipeline, `full`),\n          consolidate(),\n          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)\n        )\n        break\n      default:\n        pipeline = mainPipeline.pipe(\n          joinOperator(joinedPipeline, `inner`),\n          consolidate(),\n          processJoinResults(mainTableAlias, joinedTableAlias, joinClause)\n        )\n    }\n  }\n  return pipeline\n}\n\n/**\n * Creates a processing pipeline for join results\n */\nexport function processJoinResults(\n  mainTableAlias: string,\n  joinedTableAlias: string,\n  joinClause: { on: any; where?: any; type: string }\n) {\n  return function (\n    pipeline: IStreamBuilder<unknown>\n  ): IStreamBuilder<Record<string, unknown>> {\n    return pipeline.pipe(\n      // Process the join result and handle nulls in the same step\n      map((result: unknown) => {\n        const [_key, [mainNestedRow, joinedNestedRow]] = result as [\n          unknown,\n          [\n            Record<string, unknown> | undefined,\n            Record<string, unknown> | undefined,\n          ],\n        ]\n\n        // For inner joins, both sides should be non-null\n        if (joinClause.type === `inner` || joinClause.type === `cross`) {\n          if (!mainNestedRow || !joinedNestedRow) {\n            return undefined // Will be filtered out\n          }\n        }\n\n        // For left joins, the main row must be non-null\n        if (joinClause.type === `left` && !mainNestedRow) {\n          return undefined // Will be filtered out\n        }\n\n        // For right joins, the joined row must be non-null\n        if (joinClause.type === `right` && !joinedNestedRow) {\n          return undefined // Will be filtered out\n        }\n\n        // Merge the nested rows\n        const mergedNestedRow: Record<string, unknown> = {}\n\n        // Add main row data if it exists\n        if (mainNestedRow) {\n          Object.entries(mainNestedRow).forEach(([tableAlias, tableData]) => {\n            mergedNestedRow[tableAlias] = tableData\n          })\n        }\n\n        // If we have a joined row, add it to the merged result\n        if (joinedNestedRow) {\n          Object.entries(joinedNestedRow).forEach(([tableAlias, tableData]) => {\n            mergedNestedRow[tableAlias] = tableData\n          })\n        } else if (joinClause.type === `left` || joinClause.type === `full`) {\n          // For left or full joins, add the joined table with null data if missing\n          mergedNestedRow[joinedTableAlias] = null\n        }\n\n        // For right or full joins, add the main table with null data if missing\n        if (\n          !mainNestedRow &&\n          (joinClause.type === `right` || joinClause.type === `full`)\n        ) {\n          mergedNestedRow[mainTableAlias] = null\n        }\n\n        return mergedNestedRow\n      }),\n      // Filter out undefined results\n      filter(\n        (value: unknown): value is Record<string, unknown> =>\n          value !== undefined\n      ),\n      // Process the ON condition\n      filter((nestedRow: Record<string, unknown>) => {\n        // If there's no ON condition, or it's a cross join, always return true\n        if (!joinClause.on || joinClause.type === `cross`) {\n          return true\n        }\n\n        // For LEFT JOIN, if the right side is null, we should include the row\n        if (\n          joinClause.type === `left` &&\n          nestedRow[joinedTableAlias] === null\n        ) {\n          return true\n        }\n\n        // For RIGHT JOIN, if the left side is null, we should include the row\n        if (joinClause.type === `right` && nestedRow[mainTableAlias] === null) {\n          return true\n        }\n\n        // For FULL JOIN, if either side is null, we should include the row\n        if (\n          joinClause.type === `full` &&\n          (nestedRow[mainTableAlias] === null ||\n            nestedRow[joinedTableAlias] === null)\n        ) {\n          return true\n        }\n\n        const result = evaluateConditionOnNestedRow(\n          nestedRow,\n          joinClause.on,\n          mainTableAlias,\n          joinedTableAlias\n        )\n        return result\n      }),\n      // Process the WHERE clause for the join if it exists\n      filter((nestedRow: Record<string, unknown>) => {\n        if (!joinClause.where) {\n          return true\n        }\n\n        const result = evaluateConditionOnNestedRow(\n          nestedRow,\n          joinClause.where,\n          mainTableAlias,\n          joinedTableAlias\n        )\n        return result\n      })\n    )\n  }\n}\n"],"names":["joinOperator"],"mappings":"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"}

package/dist/esm/query/key-by.d.ts

@@ -0,0 +1,3 @@
+import { IStreamBuilder } from '@electric-sql/d2ts';
+import { Query } from './schema.js';
+export declare function processKeyBy(resultPipeline: IStreamBuilder<Record<string, unknown> | [string | number, Record<string, unknown>]>, query: Query): IStreamBuilder<Record<string, unknown> | [string | number, Record<string, unknown>]>;

package/dist/esm/query/key-by.js

@@ -0,0 +1,43 @@
+import { keyBy } from "@electric-sql/d2ts";
+function processKeyBy(resultPipeline, query) {
+  if (!query.keyBy) {
+    return resultPipeline;
+  }
+  const keyByParam = query.keyBy;
+  resultPipeline = resultPipeline.pipe(
+    keyBy((row) => {
+      if (Array.isArray(keyByParam)) {
+        const keyValues = {};
+        for (const keyColumn of keyByParam) {
+          const columnName = keyColumn.startsWith(`@`) ? keyColumn.substring(1) : keyColumn;
+          if (columnName in row) {
+            keyValues[columnName] = row[columnName];
+          } else {
+            throw new Error(
+              `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
+            );
+          }
+        }
+        return JSON.stringify(keyValues);
+      } else {
+        const columnName = keyByParam.startsWith(`@`) ? keyByParam.substring(1) : keyByParam;
+        if (!(columnName in row)) {
+          throw new Error(
+            `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
+          );
+        }
+        const keyValue = row[columnName];
+        if (typeof keyValue === `string` || typeof keyValue === `number`) {
+          return keyValue;
+        } else {
+          return JSON.stringify(keyValue);
+        }
+      }
+    })
+  );
+  return resultPipeline;
+}
+export {
+  processKeyBy
+};
+//# sourceMappingURL=key-by.js.map

package/dist/esm/query/key-by.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-by.js","sources":["../../../src/query/key-by.ts"],"sourcesContent":["import { keyBy } from \"@electric-sql/d2ts\"\nimport type { IStreamBuilder } from \"@electric-sql/d2ts\"\nimport type { Query } from \"./schema\"\n\nexport function processKeyBy(\n  resultPipeline: IStreamBuilder<\n    Record<string, unknown> | [string | number, Record<string, unknown>]\n  >,\n  query: Query\n) {\n  if (!query.keyBy) {\n    return resultPipeline\n  }\n  const keyByParam = query.keyBy\n\n  resultPipeline = resultPipeline.pipe(\n    keyBy((row: Record<string, unknown>) => {\n      if (Array.isArray(keyByParam)) {\n        // Multiple columns - extract values and JSON stringify\n        const keyValues: Record<string, unknown> = {}\n        for (const keyColumn of keyByParam) {\n          // Remove @ prefix if present\n          const columnName = (keyColumn as string).startsWith(`@`)\n            ? (keyColumn as string).substring(1)\n            : (keyColumn as string)\n\n          if (columnName in row) {\n            keyValues[columnName] = row[columnName]\n          } else {\n            throw new Error(\n              `Key column \"${columnName}\" not found in result set. Make sure it's included in the select clause.`\n            )\n          }\n        }\n        return JSON.stringify(keyValues)\n      } else {\n        // Single column\n        // Remove @ prefix if present\n        const columnName = (keyByParam as string).startsWith(`@`)\n          ? (keyByParam as string).substring(1)\n          : (keyByParam as string)\n\n        if (!(columnName in row)) {\n          throw new Error(\n            `Key column \"${columnName}\" not found in result set. Make sure it's included in the select clause.`\n          )\n        }\n\n        const keyValue = row[columnName]\n        // Use the value directly if it's a string or number, otherwise JSON stringify\n        if (typeof keyValue === `string` || typeof keyValue === `number`) {\n          return keyValue\n        } else {\n          return JSON.stringify(keyValue)\n        }\n      }\n    })\n  )\n\n  return resultPipeline\n}\n"],"names":[],"mappings":";AAIgB,SAAA,aACd,gBAGA,OACA;AACI,MAAA,CAAC,MAAM,OAAO;AACT,WAAA;AAAA,EAAA;AAET,QAAM,aAAa,MAAM;AAEzB,mBAAiB,eAAe;AAAA,IAC9B,MAAM,CAAC,QAAiC;AAClC,UAAA,MAAM,QAAQ,UAAU,GAAG;AAE7B,cAAM,YAAqC,CAAC;AAC5C,mBAAW,aAAa,YAAY;AAE5B,gBAAA,aAAc,UAAqB,WAAW,GAAG,IAClD,UAAqB,UAAU,CAAC,IAChC;AAEL,cAAI,cAAc,KAAK;AACX,sBAAA,UAAU,IAAI,IAAI,UAAU;AAAA,UAAA,OACjC;AACL,kBAAM,IAAI;AAAA,cACR,eAAe,UAAU;AAAA,YAC3B;AAAA,UAAA;AAAA,QACF;AAEK,eAAA,KAAK,UAAU,SAAS;AAAA,MAAA,OAC1B;AAGC,cAAA,aAAc,WAAsB,WAAW,GAAG,IACnD,WAAsB,UAAU,CAAC,IACjC;AAED,YAAA,EAAE,cAAc,MAAM;AACxB,gBAAM,IAAI;AAAA,YACR,eAAe,UAAU;AAAA,UAC3B;AAAA,QAAA;AAGI,cAAA,WAAW,IAAI,UAAU;AAE/B,YAAI,OAAO,aAAa,YAAY,OAAO,aAAa,UAAU;AACzD,iBAAA;AAAA,QAAA,OACF;AACE,iBAAA,KAAK,UAAU,QAAQ;AAAA,QAAA;AAAA,MAChC;AAAA,IAEH,CAAA;AAAA,EACH;AAEO,SAAA;AACT;"}

package/dist/esm/query/order-by.d.ts

@@ -0,0 +1,3 @@
+import { Query } from './schema.js';
+import { IStreamBuilder } from '@electric-sql/d2ts';
+export declare function processOrderBy(resultPipeline: IStreamBuilder<Record<string, unknown> | [string | number, Record<string, unknown>]>, query: Query, mainTableAlias: string): IStreamBuilder<Record<string, unknown> | [string | number, Record<string, unknown>]>;