@tanstack/db 0.0.1

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

@@ -0,0 +1,229 @@
+import { orderByWithIndex, map, topKWithIndex, orderByWithFractionalIndex, topKWithFractionalIndex, orderBy, topK } from "@electric-sql/d2ts";
+import { evaluateOperandOnNestedRow } from "./extractors.js";
+import { isOrderIndexFunctionCall } from "./utils.js";
+function processOrderBy(resultPipeline, query, mainTableAlias) {
+  let hasOrderIndexColumn = false;
+  let orderIndexType = `numeric`;
+  let orderIndexAlias = ``;
+  for (const item of query.select) {
+    if (typeof item === `object`) {
+      for (const [alias, expr] of Object.entries(item)) {
+        if (typeof expr === `object` && isOrderIndexFunctionCall(expr)) {
+          hasOrderIndexColumn = true;
+          orderIndexAlias = alias;
+          orderIndexType = getOrderIndexType(expr);
+          break;
+        }
+      }
+    }
+    if (hasOrderIndexColumn) break;
+  }
+  const orderByItems = [];
+  if (typeof query.orderBy === `string`) {
+    orderByItems.push({
+      operand: query.orderBy,
+      direction: `asc`
+    });
+  } else if (Array.isArray(query.orderBy)) {
+    for (const item of query.orderBy) {
+      if (typeof item === `string`) {
+        orderByItems.push({
+          operand: item,
+          direction: `asc`
+        });
+      } else if (typeof item === `object`) {
+        for (const [column, direction] of Object.entries(item)) {
+          orderByItems.push({
+            operand: column,
+            direction
+          });
+        }
+      }
+    }
+  } else if (typeof query.orderBy === `object`) {
+    for (const [column, direction] of Object.entries(query.orderBy)) {
+      orderByItems.push({
+        operand: column,
+        direction
+      });
+    }
+  }
+  const valueExtractor = (value) => {
+    const row = value;
+    const nestedRow = { [mainTableAlias]: row };
+    if (orderByItems.length > 1) {
+      return orderByItems.map((item) => {
+        const val = evaluateOperandOnNestedRow(
+          nestedRow,
+          item.operand,
+          mainTableAlias
+        );
+        return item.direction === `desc` && typeof val === `number` ? -val : item.direction === `desc` && typeof val === `string` ? String.fromCharCode(
+          ...[...val].map((c) => 65535 - c.charCodeAt(0))
+        ) : val;
+      });
+    } else if (orderByItems.length === 1) {
+      const item = orderByItems[0];
+      const val = evaluateOperandOnNestedRow(
+        nestedRow,
+        item.operand,
+        mainTableAlias
+      );
+      return item.direction === `desc` && typeof val === `number` ? -val : item.direction === `desc` && typeof val === `string` ? String.fromCharCode(
+        ...[...val].map((c) => 65535 - c.charCodeAt(0))
+      ) : val;
+    }
+    return null;
+  };
+  const comparator = (a, b) => {
+    if (typeof a === `number` && typeof b === `number`) {
+      return a - b;
+    }
+    if (typeof a === `string` && typeof b === `string`) {
+      return a.localeCompare(b);
+    }
+    if (typeof a === `boolean` && typeof b === `boolean`) {
+      return a === b ? 0 : a ? 1 : -1;
+    }
+    if (a instanceof Date && b instanceof Date) {
+      return a.getTime() - b.getTime();
+    }
+    if (a === null || b === null) {
+      return 0;
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+      for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        const aVal = a[i];
+        const bVal = b[i];
+        let result;
+        if (typeof aVal === `boolean` && typeof bVal === `boolean`) {
+          result = aVal === bVal ? 0 : aVal ? 1 : -1;
+        } else if (typeof aVal === `number` && typeof bVal === `number`) {
+          result = aVal - bVal;
+        } else if (typeof aVal === `string` && typeof bVal === `string`) {
+          result = aVal.localeCompare(bVal);
+        } else {
+          result = comparator(aVal, bVal);
+        }
+        if (result !== 0) {
+          return result;
+        }
+      }
+      return a.length - b.length;
+    }
+    if (a == null && b == null) {
+      return 0;
+    }
+    return a.toString().localeCompare(b.toString());
+  };
+  let topKComparator;
+  if (!query.keyBy) {
+    topKComparator = (a, b) => {
+      const aValue = valueExtractor(a);
+      const bValue = valueExtractor(b);
+      return comparator(aValue, bValue);
+    };
+  }
+  if (hasOrderIndexColumn) {
+    if (orderIndexType === `numeric`) {
+      if (query.keyBy) {
+        resultPipeline = resultPipeline.pipe(
+          orderByWithIndex(valueExtractor, {
+            limit: query.limit,
+            offset: query.offset,
+            comparator
+          }),
+          map(([key, [value, index]]) => {
+            const result = {
+              ...value,
+              [orderIndexAlias]: index
+            };
+            return [key, result];
+          })
+        );
+      } else {
+        resultPipeline = resultPipeline.pipe(
+          map((value) => [null, value]),
+          topKWithIndex(topKComparator, {
+            limit: query.limit,
+            offset: query.offset
+          }),
+          map(([_, [value, index]]) => {
+            return {
+              ...value,
+              [orderIndexAlias]: index
+            };
+          })
+        );
+      }
+    } else {
+      if (query.keyBy) {
+        resultPipeline = resultPipeline.pipe(
+          orderByWithFractionalIndex(valueExtractor, {
+            limit: query.limit,
+            offset: query.offset,
+            comparator
+          }),
+          map(([key, [value, index]]) => {
+            const result = {
+              ...value,
+              [orderIndexAlias]: index
+            };
+            return [key, result];
+          })
+        );
+      } else {
+        resultPipeline = resultPipeline.pipe(
+          map((value) => [null, value]),
+          topKWithFractionalIndex(topKComparator, {
+            limit: query.limit,
+            offset: query.offset
+          }),
+          map(([_, [value, index]]) => {
+            return {
+              ...value,
+              [orderIndexAlias]: index
+            };
+          })
+        );
+      }
+    }
+  } else {
+    if (query.keyBy) {
+      resultPipeline = resultPipeline.pipe(
+        orderBy(valueExtractor, {
+          limit: query.limit,
+          offset: query.offset,
+          comparator
+        })
+      );
+    } else {
+      resultPipeline = resultPipeline.pipe(
+        map((value) => [null, value]),
+        topK(topKComparator, {
+          limit: query.limit,
+          offset: query.offset
+        }),
+        map(([_, value]) => value)
+      );
+    }
+  }
+  return resultPipeline;
+}
+function getOrderIndexType(obj) {
+  if (!isOrderIndexFunctionCall(obj)) {
+    throw new Error(`Not an ORDER_INDEX function call`);
+  }
+  const arg = obj[`ORDER_INDEX`];
+  if (arg === `numeric` || arg === true || arg === `default`) {
+    return `numeric`;
+  } else if (arg === `fractional`) {
+    return `fractional`;
+  } else {
+    throw new Error(`Invalid ORDER_INDEX type: ` + arg);
+  }
+}
+export {
+  processOrderBy
+};
+//# sourceMappingURL=order-by.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"order-by.js","sources":["../../../src/query/order-by.ts"],"sourcesContent":["import {\n  map,\n  orderBy,\n  orderByWithFractionalIndex,\n  orderByWithIndex,\n  topK,\n  topKWithFractionalIndex,\n  topKWithIndex,\n} from \"@electric-sql/d2ts\"\nimport { evaluateOperandOnNestedRow } from \"./extractors\"\nimport { isOrderIndexFunctionCall } from \"./utils\"\nimport type { ConditionOperand, Query } from \"./schema\"\nimport type { IStreamBuilder } from \"@electric-sql/d2ts\"\n\nexport function processOrderBy(\n  resultPipeline: IStreamBuilder<\n    Record<string, unknown> | [string | number, Record<string, unknown>]\n  >,\n  query: Query,\n  mainTableAlias: string\n) {\n  // Check if any column in the SELECT clause is an ORDER_INDEX function call\n  let hasOrderIndexColumn = false\n  let orderIndexType: `numeric` | `fractional` = `numeric`\n  let orderIndexAlias = ``\n\n  // Scan the SELECT clause for ORDER_INDEX 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` && isOrderIndexFunctionCall(expr)) {\n          hasOrderIndexColumn = true\n          orderIndexAlias = alias\n          orderIndexType = getOrderIndexType(expr)\n          break\n        }\n      }\n    }\n    if (hasOrderIndexColumn) break\n  }\n\n  // Normalize orderBy to an array of objects\n  const orderByItems: Array<{\n    operand: ConditionOperand\n    direction: `asc` | `desc`\n  }> = []\n\n  if (typeof query.orderBy === `string`) {\n    // Handle string format: '@column'\n    orderByItems.push({\n      operand: query.orderBy,\n      direction: `asc`,\n    })\n  } else if (Array.isArray(query.orderBy)) {\n    // Handle array format: ['@column1', { '@column2': 'desc' }]\n    for (const item of query.orderBy) {\n      if (typeof item === `string`) {\n        orderByItems.push({\n          operand: item,\n          direction: `asc`,\n        })\n      } else if (typeof item === `object`) {\n        for (const [column, direction] of Object.entries(item)) {\n          orderByItems.push({\n            operand: column,\n            direction: direction as `asc` | `desc`,\n          })\n        }\n      }\n    }\n  } else if (typeof query.orderBy === `object`) {\n    // Handle object format: { '@column': 'desc' }\n    for (const [column, direction] of Object.entries(query.orderBy)) {\n      orderByItems.push({\n        operand: column,\n        direction: direction as `asc` | `desc`,\n      })\n    }\n  }\n\n  // Create a value extractor function for the orderBy operator\n  const valueExtractor = (value: unknown) => {\n    const row = value as Record<string, unknown>\n\n    // Create a nested row structure for evaluateOperandOnNestedRow\n    const nestedRow: Record<string, unknown> = { [mainTableAlias]: row }\n\n    // For multiple orderBy columns, create a composite key\n    if (orderByItems.length > 1) {\n      return orderByItems.map((item) => {\n        const val = evaluateOperandOnNestedRow(\n          nestedRow,\n          item.operand,\n          mainTableAlias\n        )\n\n        // Reverse the value for 'desc' ordering\n        return item.direction === `desc` && typeof val === `number`\n          ? -val\n          : item.direction === `desc` && typeof val === `string`\n            ? String.fromCharCode(\n                ...[...val].map((c) => 0xffff - c.charCodeAt(0))\n              )\n            : val\n      })\n    } else if (orderByItems.length === 1) {\n      // For a single orderBy column, use the value directly\n      const item = orderByItems[0]\n      const val = evaluateOperandOnNestedRow(\n        nestedRow,\n        item!.operand,\n        mainTableAlias\n      )\n\n      // Reverse the value for 'desc' ordering\n      return item!.direction === `desc` && typeof val === `number`\n        ? -val\n        : item!.direction === `desc` && typeof val === `string`\n          ? String.fromCharCode(\n              ...[...val].map((c) => 0xffff - c.charCodeAt(0))\n            )\n          : val\n    }\n\n    // Default case - no ordering\n    return null\n  }\n\n  const comparator = (a: unknown, b: unknown): number => {\n    // if a and b are both numbers compare them directly\n    if (typeof a === `number` && typeof b === `number`) {\n      return a - b\n    }\n    // if a and b are both strings, compare them lexicographically\n    if (typeof a === `string` && typeof b === `string`) {\n      return a.localeCompare(b)\n    }\n    // if a and b are both booleans, compare them\n    if (typeof a === `boolean` && typeof b === `boolean`) {\n      return a === b ? 0 : a ? 1 : -1\n    }\n    // if a and b are both dates, compare them\n    if (a instanceof Date && b instanceof Date) {\n      return a.getTime() - b.getTime()\n    }\n    // if a and b are both null, return 0\n    if (a === null || b === null) {\n      return 0\n    }\n\n    // if a and b are both arrays, compare them element by element\n    if (Array.isArray(a) && Array.isArray(b)) {\n      for (let i = 0; i < Math.min(a.length, b.length); i++) {\n        // Get the values from the array\n        const aVal = a[i]\n        const bVal = b[i]\n\n        // Compare the values\n        let result: number\n\n        if (typeof aVal === `boolean` && typeof bVal === `boolean`) {\n          // Special handling for booleans - false comes before true\n          result = aVal === bVal ? 0 : aVal ? 1 : -1\n        } else if (typeof aVal === `number` && typeof bVal === `number`) {\n          // Numeric comparison\n          result = aVal - bVal\n        } else if (typeof aVal === `string` && typeof bVal === `string`) {\n          // String comparison\n          result = aVal.localeCompare(bVal)\n        } else {\n          // Default comparison using the general comparator\n          result = comparator(aVal, bVal)\n        }\n\n        if (result !== 0) {\n          return result\n        }\n      }\n      // All elements are equal up to the minimum length\n      return a.length - b.length\n    }\n    // if a and b are both null/undefined, return 0\n    if (a == null && b == null) {\n      return 0\n    }\n    // Fallback to string comparison for all other cases\n    return (a as any).toString().localeCompare((b as any).toString())\n  }\n\n  let topKComparator: (a: unknown, b: unknown) => number\n  if (!query.keyBy) {\n    topKComparator = (a, b) => {\n      const aValue = valueExtractor(a)\n      const bValue = valueExtractor(b)\n      return comparator(aValue, bValue)\n    }\n  }\n\n  // Apply the appropriate orderBy operator based on whether an ORDER_INDEX column is requested\n  if (hasOrderIndexColumn) {\n    if (orderIndexType === `numeric`) {\n      if (query.keyBy) {\n        // Use orderByWithIndex for numeric indices\n        resultPipeline = resultPipeline.pipe(\n          orderByWithIndex(valueExtractor, {\n            limit: query.limit,\n            offset: query.offset,\n            comparator,\n          }),\n          map(([key, [value, index]]) => {\n            // Add the index to the result\n            const result = {\n              ...(value as Record<string, unknown>),\n              [orderIndexAlias]: index,\n            }\n            return [key, result]\n          })\n        )\n      } else {\n        // Use topKWithIndex for numeric indices\n        resultPipeline = resultPipeline.pipe(\n          map((value) => [null, value]),\n          topKWithIndex(topKComparator!, {\n            limit: query.limit,\n            offset: query.offset,\n          }),\n          map(([_, [value, index]]) => {\n            // Add the index to the result\n            return {\n              ...(value as Record<string, unknown>),\n              [orderIndexAlias]: index,\n            }\n          })\n        )\n      }\n    } else {\n      if (query.keyBy) {\n        // Use orderByWithFractionalIndex for fractional indices\n        resultPipeline = resultPipeline.pipe(\n          orderByWithFractionalIndex(valueExtractor, {\n            limit: query.limit,\n            offset: query.offset,\n            comparator,\n          }),\n          map(([key, [value, index]]) => {\n            // Add the index to the result\n            const result = {\n              ...(value as Record<string, unknown>),\n              [orderIndexAlias]: index,\n            }\n            return [key, result]\n          })\n        )\n      } else {\n        // Use topKWithFractionalIndex for fractional indices\n        resultPipeline = resultPipeline.pipe(\n          map((value) => [null, value]),\n          topKWithFractionalIndex(topKComparator!, {\n            limit: query.limit,\n            offset: query.offset,\n          }),\n          map(([_, [value, index]]) => {\n            // Add the index to the result\n            return {\n              ...(value as Record<string, unknown>),\n              [orderIndexAlias]: index,\n            }\n          })\n        )\n      }\n    }\n  } else {\n    if (query.keyBy) {\n      // Use regular orderBy if no index column is requested and but a keyBy is requested\n      resultPipeline = resultPipeline.pipe(\n        orderBy(valueExtractor, {\n          limit: query.limit,\n          offset: query.offset,\n          comparator,\n        })\n      )\n    } else {\n      // Use topK if no index column is requested and no keyBy is requested\n      resultPipeline = resultPipeline.pipe(\n        map((value) => [null, value]),\n        topK(topKComparator!, {\n          limit: query.limit,\n          offset: query.offset,\n        }),\n        map(([_, value]) => value as Record<string, unknown>)\n      )\n    }\n  }\n\n  return resultPipeline\n}\n\n// Helper function to extract the ORDER_INDEX type from a function call\nfunction getOrderIndexType(obj: any): `numeric` | `fractional` {\n  if (!isOrderIndexFunctionCall(obj)) {\n    throw new Error(`Not an ORDER_INDEX function call`)\n  }\n\n  const arg = obj[`ORDER_INDEX`]\n  if (arg === `numeric` || arg === true || arg === `default`) {\n    return `numeric`\n  } else if (arg === `fractional`) {\n    return `fractional`\n  } else {\n    throw new Error(`Invalid ORDER_INDEX type: ` + arg)\n  }\n}\n"],"names":[],"mappings":";;;AAcgB,SAAA,eACd,gBAGA,OACA,gBACA;AAEA,MAAI,sBAAsB;AAC1B,MAAI,iBAA2C;AAC/C,MAAI,kBAAkB;AAGX,aAAA,QAAQ,MAAM,QAAQ;AAC3B,QAAA,OAAO,SAAS,UAAU;AAC5B,iBAAW,CAAC,OAAO,IAAI,KAAK,OAAO,QAAQ,IAAI,GAAG;AAChD,YAAI,OAAO,SAAS,YAAY,yBAAyB,IAAI,GAAG;AACxC,gCAAA;AACJ,4BAAA;AAClB,2BAAiB,kBAAkB,IAAI;AACvC;AAAA,QAAA;AAAA,MACF;AAAA,IACF;AAEF,QAAI,oBAAqB;AAAA,EAAA;AAI3B,QAAM,eAGD,CAAC;AAEF,MAAA,OAAO,MAAM,YAAY,UAAU;AAErC,iBAAa,KAAK;AAAA,MAChB,SAAS,MAAM;AAAA,MACf,WAAW;AAAA,IAAA,CACZ;AAAA,EACQ,WAAA,MAAM,QAAQ,MAAM,OAAO,GAAG;AAE5B,eAAA,QAAQ,MAAM,SAAS;AAC5B,UAAA,OAAO,SAAS,UAAU;AAC5B,qBAAa,KAAK;AAAA,UAChB,SAAS;AAAA,UACT,WAAW;AAAA,QAAA,CACZ;AAAA,MACH,WAAW,OAAO,SAAS,UAAU;AACnC,mBAAW,CAAC,QAAQ,SAAS,KAAK,OAAO,QAAQ,IAAI,GAAG;AACtD,uBAAa,KAAK;AAAA,YAChB,SAAS;AAAA,YACT;AAAA,UAAA,CACD;AAAA,QAAA;AAAA,MACH;AAAA,IACF;AAAA,EAEO,WAAA,OAAO,MAAM,YAAY,UAAU;AAEjC,eAAA,CAAC,QAAQ,SAAS,KAAK,OAAO,QAAQ,MAAM,OAAO,GAAG;AAC/D,mBAAa,KAAK;AAAA,QAChB,SAAS;AAAA,QACT;AAAA,MAAA,CACD;AAAA,IAAA;AAAA,EACH;AAII,QAAA,iBAAiB,CAAC,UAAmB;AACzC,UAAM,MAAM;AAGZ,UAAM,YAAqC,EAAE,CAAC,cAAc,GAAG,IAAI;AAG/D,QAAA,aAAa,SAAS,GAAG;AACpB,aAAA,aAAa,IAAI,CAAC,SAAS;AAChC,cAAM,MAAM;AAAA,UACV;AAAA,UACA,KAAK;AAAA,UACL;AAAA,QACF;AAGA,eAAO,KAAK,cAAc,UAAU,OAAO,QAAQ,WAC/C,CAAC,MACD,KAAK,cAAc,UAAU,OAAO,QAAQ,WAC1C,OAAO;AAAA,UACL,GAAG,CAAC,GAAG,GAAG,EAAE,IAAI,CAAC,MAAM,QAAS,EAAE,WAAW,CAAC,CAAC;AAAA,QAAA,IAEjD;AAAA,MAAA,CACP;AAAA,IAAA,WACQ,aAAa,WAAW,GAAG;AAE9B,YAAA,OAAO,aAAa,CAAC;AAC3B,YAAM,MAAM;AAAA,QACV;AAAA,QACA,KAAM;AAAA,QACN;AAAA,MACF;AAGA,aAAO,KAAM,cAAc,UAAU,OAAO,QAAQ,WAChD,CAAC,MACD,KAAM,cAAc,UAAU,OAAO,QAAQ,WAC3C,OAAO;AAAA,QACL,GAAG,CAAC,GAAG,GAAG,EAAE,IAAI,CAAC,MAAM,QAAS,EAAE,WAAW,CAAC,CAAC;AAAA,MAAA,IAEjD;AAAA,IAAA;AAID,WAAA;AAAA,EACT;AAEM,QAAA,aAAa,CAAC,GAAY,MAAuB;AAErD,QAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAClD,aAAO,IAAI;AAAA,IAAA;AAGb,QAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAC3C,aAAA,EAAE,cAAc,CAAC;AAAA,IAAA;AAG1B,QAAI,OAAO,MAAM,aAAa,OAAO,MAAM,WAAW;AACpD,aAAO,MAAM,IAAI,IAAI,IAAI,IAAI;AAAA,IAAA;AAG3B,QAAA,aAAa,QAAQ,aAAa,MAAM;AAC1C,aAAO,EAAE,YAAY,EAAE,QAAQ;AAAA,IAAA;AAG7B,QAAA,MAAM,QAAQ,MAAM,MAAM;AACrB,aAAA;AAAA,IAAA;AAIT,QAAI,MAAM,QAAQ,CAAC,KAAK,MAAM,QAAQ,CAAC,GAAG;AAC/B,eAAA,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK;AAE/C,cAAA,OAAO,EAAE,CAAC;AACV,cAAA,OAAO,EAAE,CAAC;AAGZ,YAAA;AAEJ,YAAI,OAAO,SAAS,aAAa,OAAO,SAAS,WAAW;AAE1D,mBAAS,SAAS,OAAO,IAAI,OAAO,IAAI;AAAA,QAAA,WAC/B,OAAO,SAAS,YAAY,OAAO,SAAS,UAAU;AAE/D,mBAAS,OAAO;AAAA,QAAA,WACP,OAAO,SAAS,YAAY,OAAO,SAAS,UAAU;AAEtD,mBAAA,KAAK,cAAc,IAAI;AAAA,QAAA,OAC3B;AAEI,mBAAA,WAAW,MAAM,IAAI;AAAA,QAAA;AAGhC,YAAI,WAAW,GAAG;AACT,iBAAA;AAAA,QAAA;AAAA,MACT;AAGK,aAAA,EAAE,SAAS,EAAE;AAAA,IAAA;AAGlB,QAAA,KAAK,QAAQ,KAAK,MAAM;AACnB,aAAA;AAAA,IAAA;AAGT,WAAQ,EAAU,SAAS,EAAE,cAAe,EAAU,UAAU;AAAA,EAClE;AAEI,MAAA;AACA,MAAA,CAAC,MAAM,OAAO;AACC,qBAAA,CAAC,GAAG,MAAM;AACnB,YAAA,SAAS,eAAe,CAAC;AACzB,YAAA,SAAS,eAAe,CAAC;AACxB,aAAA,WAAW,QAAQ,MAAM;AAAA,IAClC;AAAA,EAAA;AAIF,MAAI,qBAAqB;AACvB,QAAI,mBAAmB,WAAW;AAChC,UAAI,MAAM,OAAO;AAEf,yBAAiB,eAAe;AAAA,UAC9B,iBAAiB,gBAAgB;AAAA,YAC/B,OAAO,MAAM;AAAA,YACb,QAAQ,MAAM;AAAA,YACd;AAAA,UAAA,CACD;AAAA,UACD,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,MAAM;AAE7B,kBAAM,SAAS;AAAA,cACb,GAAI;AAAA,cACJ,CAAC,eAAe,GAAG;AAAA,YACrB;AACO,mBAAA,CAAC,KAAK,MAAM;AAAA,UACpB,CAAA;AAAA,QACH;AAAA,MAAA,OACK;AAEL,yBAAiB,eAAe;AAAA,UAC9B,IAAI,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;AAAA,UAC5B,cAAc,gBAAiB;AAAA,YAC7B,OAAO,MAAM;AAAA,YACb,QAAQ,MAAM;AAAA,UAAA,CACf;AAAA,UACD,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,KAAK,CAAC,MAAM;AAEpB,mBAAA;AAAA,cACL,GAAI;AAAA,cACJ,CAAC,eAAe,GAAG;AAAA,YACrB;AAAA,UACD,CAAA;AAAA,QACH;AAAA,MAAA;AAAA,IACF,OACK;AACL,UAAI,MAAM,OAAO;AAEf,yBAAiB,eAAe;AAAA,UAC9B,2BAA2B,gBAAgB;AAAA,YACzC,OAAO,MAAM;AAAA,YACb,QAAQ,MAAM;AAAA,YACd;AAAA,UAAA,CACD;AAAA,UACD,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,MAAM;AAE7B,kBAAM,SAAS;AAAA,cACb,GAAI;AAAA,cACJ,CAAC,eAAe,GAAG;AAAA,YACrB;AACO,mBAAA,CAAC,KAAK,MAAM;AAAA,UACpB,CAAA;AAAA,QACH;AAAA,MAAA,OACK;AAEL,yBAAiB,eAAe;AAAA,UAC9B,IAAI,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;AAAA,UAC5B,wBAAwB,gBAAiB;AAAA,YACvC,OAAO,MAAM;AAAA,YACb,QAAQ,MAAM;AAAA,UAAA,CACf;AAAA,UACD,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,KAAK,CAAC,MAAM;AAEpB,mBAAA;AAAA,cACL,GAAI;AAAA,cACJ,CAAC,eAAe,GAAG;AAAA,YACrB;AAAA,UACD,CAAA;AAAA,QACH;AAAA,MAAA;AAAA,IACF;AAAA,EACF,OACK;AACL,QAAI,MAAM,OAAO;AAEf,uBAAiB,eAAe;AAAA,QAC9B,QAAQ,gBAAgB;AAAA,UACtB,OAAO,MAAM;AAAA,UACb,QAAQ,MAAM;AAAA,UACd;AAAA,QACD,CAAA;AAAA,MACH;AAAA,IAAA,OACK;AAEL,uBAAiB,eAAe;AAAA,QAC9B,IAAI,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;AAAA,QAC5B,KAAK,gBAAiB;AAAA,UACpB,OAAO,MAAM;AAAA,UACb,QAAQ,MAAM;AAAA,QAAA,CACf;AAAA,QACD,IAAI,CAAC,CAAC,GAAG,KAAK,MAAM,KAAgC;AAAA,MACtD;AAAA,IAAA;AAAA,EACF;AAGK,SAAA;AACT;AAGA,SAAS,kBAAkB,KAAoC;AACzD,MAAA,CAAC,yBAAyB,GAAG,GAAG;AAC5B,UAAA,IAAI,MAAM,kCAAkC;AAAA,EAAA;AAG9C,QAAA,MAAM,IAAI,aAAa;AAC7B,MAAI,QAAQ,aAAa,QAAQ,QAAQ,QAAQ,WAAW;AACnD,WAAA;AAAA,EAAA,WACE,QAAQ,cAAc;AACxB,WAAA;AAAA,EAAA,OACF;AACC,UAAA,IAAI,MAAM,+BAA+B,GAAG;AAAA,EAAA;AAEtD;"}

package/dist/esm/query/pipeline-compiler.d.ts

@@ -0,0 +1,9 @@
+import { Query } from './schema.js';
+import { IStreamBuilder } from '@electric-sql/d2ts';
+/**
+ * Compiles a query into a D2 pipeline
+ * @param query The query to compile
+ * @param inputs Mapping of table names to input streams
+ * @returns A stream builder representing the compiled query
+ */
+export declare function compileQueryPipeline<T extends IStreamBuilder<unknown>>(query: Query, inputs: Record<string, IStreamBuilder<Record<string, unknown>>>): T;

package/dist/esm/query/pipeline-compiler.js

@@ -0,0 +1,94 @@
+import { map, filter } from "@electric-sql/d2ts";
+import { evaluateConditionOnNestedRow } from "./evaluators.js";
+import { processJoinClause } from "./joins.js";
+import { processGroupBy } from "./group-by.js";
+import { processOrderBy } from "./order-by.js";
+import { processKeyBy } from "./key-by.js";
+import { processSelect } from "./select.js";
+function compileQueryPipeline(query, inputs) {
+  const allInputs = { ...inputs };
+  if (query.with && query.with.length > 0) {
+    for (const withQuery of query.with) {
+      if (!withQuery.as) {
+        throw new Error(`WITH query must have an "as" property`);
+      }
+      if (withQuery.keyBy !== void 0) {
+        throw new Error(`WITH query cannot have a "keyBy" property`);
+      }
+      if (allInputs[withQuery.as]) {
+        throw new Error(`CTE with name "${withQuery.as}" already exists`);
+      }
+      const withQueryWithoutWith = { ...withQuery, with: void 0 };
+      const compiledWithQuery = compileQueryPipeline(
+        withQueryWithoutWith,
+        allInputs
+      );
+      allInputs[withQuery.as] = compiledWithQuery;
+    }
+  }
+  const tables = {};
+  const mainTableAlias = query.as || query.from;
+  const input = allInputs[query.from];
+  if (!input) {
+    throw new Error(`Input for table "${query.from}" not found in inputs map`);
+  }
+  tables[mainTableAlias] = input;
+  let pipeline = input.pipe(
+    map((row) => {
+      return { [mainTableAlias]: row };
+    })
+  );
+  if (query.join) {
+    pipeline = processJoinClause(
+      pipeline,
+      query,
+      tables,
+      mainTableAlias,
+      allInputs
+    );
+  }
+  if (query.where) {
+    pipeline = pipeline.pipe(
+      filter((nestedRow) => {
+        const result = evaluateConditionOnNestedRow(
+          nestedRow,
+          query.where,
+          mainTableAlias
+        );
+        return result;
+      })
+    );
+  }
+  if (query.groupBy) {
+    pipeline = processGroupBy(pipeline, query, mainTableAlias);
+  }
+  if (query.having) {
+    pipeline = pipeline.pipe(
+      filter((row) => {
+        const result = evaluateConditionOnNestedRow(
+          { [mainTableAlias]: row, ...row },
+          query.having,
+          mainTableAlias
+        );
+        return result;
+      })
+    );
+  }
+  pipeline = processSelect(pipeline, query, mainTableAlias, allInputs);
+  let resultPipeline = pipeline;
+  if (query.keyBy) {
+    resultPipeline = processKeyBy(resultPipeline, query);
+  }
+  if (query.orderBy) {
+    resultPipeline = processOrderBy(resultPipeline, query, mainTableAlias);
+  } else if (query.limit !== void 0 || query.offset !== void 0) {
+    throw new Error(
+      `LIMIT and OFFSET require an ORDER BY clause to ensure deterministic results`
+    );
+  }
+  return resultPipeline;
+}
+export {
+  compileQueryPipeline
+};
+//# sourceMappingURL=pipeline-compiler.js.map

package/dist/esm/query/pipeline-compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-compiler.js","sources":["../../../src/query/pipeline-compiler.ts"],"sourcesContent":["import { filter, map } from \"@electric-sql/d2ts\"\nimport { evaluateConditionOnNestedRow } from \"./evaluators.js\"\nimport { processJoinClause } from \"./joins.js\"\nimport { processGroupBy } from \"./group-by.js\"\nimport { processOrderBy } from \"./order-by.js\"\nimport { processKeyBy } from \"./key-by.js\"\nimport { processSelect } from \"./select.js\"\nimport type { Condition, Query } from \"./schema.js\"\nimport type { IStreamBuilder } from \"@electric-sql/d2ts\"\n\n/**\n * Compiles a query into a D2 pipeline\n * @param query The query to compile\n * @param inputs Mapping of table names to input streams\n * @returns A stream builder representing the compiled query\n */\nexport function compileQueryPipeline<T extends IStreamBuilder<unknown>>(\n  query: Query,\n  inputs: Record<string, IStreamBuilder<Record<string, unknown>>>\n): T {\n  // Create a copy of the inputs map to avoid modifying the original\n  const allInputs = { ...inputs }\n\n  // Process WITH queries if they exist\n  if (query.with && query.with.length > 0) {\n    // Process each WITH query in order\n    for (const withQuery of query.with) {\n      // Ensure the WITH query has an alias\n      if (!withQuery.as) {\n        throw new Error(`WITH query must have an \"as\" property`)\n      }\n\n      // Ensure the WITH query is not keyed\n      if ((withQuery as Query).keyBy !== undefined) {\n        throw new Error(`WITH query cannot have a \"keyBy\" property`)\n      }\n\n      // Check if this CTE name already exists in the inputs\n      if (allInputs[withQuery.as]) {\n        throw new Error(`CTE with name \"${withQuery.as}\" already exists`)\n      }\n\n      // Create a new query without the 'with' property to avoid circular references\n      const withQueryWithoutWith = { ...withQuery, with: undefined }\n\n      // Compile the WITH query using the current set of inputs\n      // (which includes previously compiled WITH queries)\n      const compiledWithQuery = compileQueryPipeline(\n        withQueryWithoutWith,\n        allInputs\n      )\n\n      // Add the compiled query to the inputs map using its alias\n      allInputs[withQuery.as] = compiledWithQuery as IStreamBuilder<\n        Record<string, unknown>\n      >\n    }\n  }\n\n  // Create a map of table aliases to inputs\n  const tables: Record<string, IStreamBuilder<Record<string, unknown>>> = {}\n\n  // The main table is the one in the FROM clause\n  const mainTableAlias = query.as || query.from\n\n  // Get the main input from the inputs map (now including CTEs)\n  const input = allInputs[query.from]\n  if (!input) {\n    throw new Error(`Input for table \"${query.from}\" not found in inputs map`)\n  }\n\n  tables[mainTableAlias] = input\n\n  // Prepare the initial pipeline with the main table wrapped in its alias\n  let pipeline = input.pipe(\n    map((row: unknown) => {\n      // Initialize the record with a nested structure\n      return { [mainTableAlias]: row } as Record<string, unknown>\n    })\n  )\n\n  // Process JOIN clauses if they exist\n  if (query.join) {\n    pipeline = processJoinClause(\n      pipeline,\n      query,\n      tables,\n      mainTableAlias,\n      allInputs\n    )\n  }\n\n  // Process the WHERE clause if it exists\n  if (query.where) {\n    pipeline = pipeline.pipe(\n      filter((nestedRow) => {\n        const result = evaluateConditionOnNestedRow(\n          nestedRow,\n          query.where as Condition,\n          mainTableAlias\n        )\n        return result\n      })\n    )\n  }\n\n  // Process the GROUP BY clause if it exists\n  if (query.groupBy) {\n    pipeline = processGroupBy(pipeline, query, mainTableAlias)\n  }\n\n  // Process the HAVING clause if it exists\n  // This works similarly to WHERE but is applied after any aggregations\n  if (query.having) {\n    pipeline = pipeline.pipe(\n      filter((row) => {\n        // For HAVING, we're working with the flattened row that contains both\n        // the group by keys and the aggregate results directly\n        const result = evaluateConditionOnNestedRow(\n          { [mainTableAlias]: row, ...row } as Record<string, unknown>,\n          query.having as Condition,\n          mainTableAlias\n        )\n        return result\n      })\n    )\n  }\n\n  // Process the SELECT clause - this is where we flatten the structure\n  pipeline = processSelect(pipeline, query, mainTableAlias, allInputs)\n\n  let resultPipeline: IStreamBuilder<\n    Record<string, unknown> | [string | number, Record<string, unknown>]\n  > = pipeline\n\n  // Process keyBy parameter if it exists\n  if (query.keyBy) {\n    resultPipeline = processKeyBy(resultPipeline, query)\n  }\n\n  // Process orderBy parameter if it exists\n  if (query.orderBy) {\n    resultPipeline = processOrderBy(resultPipeline, query, mainTableAlias)\n  } else if (query.limit !== undefined || query.offset !== undefined) {\n    // If there's a limit or offset without orderBy, throw an error\n    throw new Error(\n      `LIMIT and OFFSET require an ORDER BY clause to ensure deterministic results`\n    )\n  }\n\n  return resultPipeline as T\n}\n"],"names":[],"mappings":";;;;;;;AAgBgB,SAAA,qBACd,OACA,QACG;AAEG,QAAA,YAAY,EAAE,GAAG,OAAO;AAG9B,MAAI,MAAM,QAAQ,MAAM,KAAK,SAAS,GAAG;AAE5B,eAAA,aAAa,MAAM,MAAM;AAE9B,UAAA,CAAC,UAAU,IAAI;AACX,cAAA,IAAI,MAAM,uCAAuC;AAAA,MAAA;AAIpD,UAAA,UAAoB,UAAU,QAAW;AACtC,cAAA,IAAI,MAAM,2CAA2C;AAAA,MAAA;AAIzD,UAAA,UAAU,UAAU,EAAE,GAAG;AAC3B,cAAM,IAAI,MAAM,kBAAkB,UAAU,EAAE,kBAAkB;AAAA,MAAA;AAIlE,YAAM,uBAAuB,EAAE,GAAG,WAAW,MAAM,OAAU;AAI7D,YAAM,oBAAoB;AAAA,QACxB;AAAA,QACA;AAAA,MACF;AAGU,gBAAA,UAAU,EAAE,IAAI;AAAA,IAAA;AAAA,EAG5B;AAIF,QAAM,SAAkE,CAAC;AAGnE,QAAA,iBAAiB,MAAM,MAAM,MAAM;AAGnC,QAAA,QAAQ,UAAU,MAAM,IAAI;AAClC,MAAI,CAAC,OAAO;AACV,UAAM,IAAI,MAAM,oBAAoB,MAAM,IAAI,2BAA2B;AAAA,EAAA;AAG3E,SAAO,cAAc,IAAI;AAGzB,MAAI,WAAW,MAAM;AAAA,IACnB,IAAI,CAAC,QAAiB;AAEpB,aAAO,EAAE,CAAC,cAAc,GAAG,IAAI;AAAA,IAChC,CAAA;AAAA,EACH;AAGA,MAAI,MAAM,MAAM;AACH,eAAA;AAAA,MACT;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EAAA;AAIF,MAAI,MAAM,OAAO;AACf,eAAW,SAAS;AAAA,MAClB,OAAO,CAAC,cAAc;AACpB,cAAM,SAAS;AAAA,UACb;AAAA,UACA,MAAM;AAAA,UACN;AAAA,QACF;AACO,eAAA;AAAA,MACR,CAAA;AAAA,IACH;AAAA,EAAA;AAIF,MAAI,MAAM,SAAS;AACN,eAAA,eAAe,UAAU,OAAO,cAAc;AAAA,EAAA;AAK3D,MAAI,MAAM,QAAQ;AAChB,eAAW,SAAS;AAAA,MAClB,OAAO,CAAC,QAAQ;AAGd,cAAM,SAAS;AAAA,UACb,EAAE,CAAC,cAAc,GAAG,KAAK,GAAG,IAAI;AAAA,UAChC,MAAM;AAAA,UACN;AAAA,QACF;AACO,eAAA;AAAA,MACR,CAAA;AAAA,IACH;AAAA,EAAA;AAIF,aAAW,cAAc,UAAU,OAAO,gBAAgB,SAAS;AAEnE,MAAI,iBAEA;AAGJ,MAAI,MAAM,OAAO;AACE,qBAAA,aAAa,gBAAgB,KAAK;AAAA,EAAA;AAIrD,MAAI,MAAM,SAAS;AACA,qBAAA,eAAe,gBAAgB,OAAO,cAAc;AAAA,EAAA,WAC5D,MAAM,UAAU,UAAa,MAAM,WAAW,QAAW;AAElE,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EAAA;AAGK,SAAA;AACT;"}

package/dist/esm/query/query-builder.d.ts

@@ -0,0 +1,219 @@
+import { Collection } from '../collection.js';
+import { Comparator, Condition, Limit, LiteralValue, Offset, OrderBy, Query, Select } from './schema.js';
+import { Context, Flatten, InferResultTypeFromSelectTuple, Input, InputReference, PropertyReference, PropertyReferenceString, RemoveIndexSignature, Schema } from './types.js';
+type CollectionRef = {
+    [K: string]: Collection<any>;
+};
+export declare class BaseQueryBuilder<TContext extends Context<Schema>> {
+    private readonly query;
+    /**
+     * Create a new QueryBuilder instance.
+     */
+    constructor(query?: Partial<Query<TContext>>);
+    from<TCollectionRef extends CollectionRef>(collectionRef: TCollectionRef): QueryBuilder<{
+        baseSchema: Flatten<TContext[`baseSchema`] & {
+            [K in keyof TCollectionRef & string]: RemoveIndexSignature<(TCollectionRef[keyof TCollectionRef] extends Collection<infer T> ? T : never) & Input>;
+        }>;
+        schema: Flatten<{
+            [K in keyof TCollectionRef & string]: RemoveIndexSignature<(TCollectionRef[keyof TCollectionRef] extends Collection<infer T> ? T : never) & Input>;
+        }>;
+        default: keyof TCollectionRef & string;
+    }>;
+    from<T extends InputReference<{
+        baseSchema: TContext[`baseSchema`];
+        schema: TContext[`baseSchema`];
+    }>>(collection: T): QueryBuilder<{
+        baseSchema: TContext[`baseSchema`];
+        schema: {
+            [K in T]: RemoveIndexSignature<TContext[`baseSchema`][T]>;
+        };
+        default: T;
+    }>;
+    from<T extends InputReference<{
+        baseSchema: TContext[`baseSchema`];
+        schema: TContext[`baseSchema`];
+    }>, TAs extends string>(collection: T, as: TAs): QueryBuilder<{
+        baseSchema: TContext[`baseSchema`];
+        schema: {
+            [K in TAs]: RemoveIndexSignature<TContext[`baseSchema`][T]>;
+        };
+        default: TAs;
+    }>;
+    private fromCollectionRef;
+    private fromInputReference;
+    /**
+     * Specify what columns to select.
+     * Overwrites any previous select clause.
+     *
+     * @param selects The columns to select
+     * @returns A new QueryBuilder with the select clause set
+     */
+    select<TSelects extends Array<Select<TContext>>>(this: QueryBuilder<TContext>, ...selects: TSelects): QueryBuilder<Flatten<Omit<TContext, `result`> & {
+        result: InferResultTypeFromSelectTuple<TContext, TSelects>;
+    }>>;
+    /**
+     * Add a where clause comparing two values.
+     */
+    where(left: PropertyReferenceString<TContext> | LiteralValue, operator: Comparator, right: PropertyReferenceString<TContext> | LiteralValue): QueryBuilder<TContext>;
+    /**
+     * Add a where clause with a complete condition object.
+     */
+    where(condition: Condition<TContext>): QueryBuilder<TContext>;
+    /**
+     * Add a having clause comparing two values.
+     * For filtering results after they have been grouped.
+     */
+    having(left: PropertyReferenceString<TContext> | LiteralValue, operator: Comparator, right: PropertyReferenceString<TContext> | LiteralValue): QueryBuilder<TContext>;
+    /**
+     * Add a having clause with a complete condition object.
+     * For filtering results after they have been grouped.
+     */
+    having(condition: Condition<TContext>): QueryBuilder<TContext>;
+    /**
+     * Add a join clause to the query using a CollectionRef.
+     */
+    join<TCollectionRef extends CollectionRef>(joinClause: {
+        type: `inner` | `left` | `right` | `full` | `cross`;
+        from: TCollectionRef;
+        on: Condition<Flatten<{
+            baseSchema: TContext[`baseSchema`];
+            schema: TContext[`schema`] & {
+                [K in keyof TCollectionRef & string]: RemoveIndexSignature<(TCollectionRef[keyof TCollectionRef] extends Collection<infer T> ? T : never) & Input>;
+            };
+        }>>;
+        where?: Condition<Flatten<{
+            baseSchema: TContext[`baseSchema`];
+            schema: {
+                [K in keyof TCollectionRef & string]: RemoveIndexSignature<(TCollectionRef[keyof TCollectionRef] extends Collection<infer T> ? T : never) & Input>;
+            };
+        }>>;
+    }): QueryBuilder<Flatten<Omit<TContext, `schema`> & {
+        schema: TContext[`schema`] & {
+            [K in keyof TCollectionRef & string]: RemoveIndexSignature<(TCollectionRef[keyof TCollectionRef] extends Collection<infer T> ? T : never) & Input>;
+        };
+    }>>;
+    /**
+     * Add a join clause to the query without specifying an alias.
+     * The collection name will be used as the default alias.
+     */
+    join<T extends InputReference<{
+        baseSchema: TContext[`baseSchema`];
+        schema: TContext[`baseSchema`];
+    }>>(joinClause: {
+        type: `inner` | `left` | `right` | `full` | `cross`;
+        from: T;
+        on: Condition<Flatten<{
+            baseSchema: TContext[`baseSchema`];
+            schema: TContext[`schema`] & {
+                [K in T]: RemoveIndexSignature<TContext[`baseSchema`][T]>;
+            };
+        }>>;
+        where?: Condition<Flatten<{
+            baseSchema: TContext[`baseSchema`];
+            schema: {
+                [K in T]: RemoveIndexSignature<TContext[`baseSchema`][T]>;
+            };
+        }>>;
+    }): QueryBuilder<Flatten<Omit<TContext, `schema`> & {
+        schema: TContext[`schema`] & {
+            [K in T]: RemoveIndexSignature<TContext[`baseSchema`][T]>;
+        };
+    }>>;
+    /**
+     * Add a join clause to the query with a specified alias.
+     */
+    join<TFrom extends InputReference<{
+        baseSchema: TContext[`baseSchema`];
+        schema: TContext[`baseSchema`];
+    }>, TAs extends string>(joinClause: {
+        type: `inner` | `left` | `right` | `full` | `cross`;
+        from: TFrom;
+        as: TAs;
+        on: Condition<Flatten<{
+            baseSchema: TContext[`baseSchema`];
+            schema: TContext[`schema`] & {
+                [K in TAs]: RemoveIndexSignature<TContext[`baseSchema`][TFrom]>;
+            };
+        }>>;
+        where?: Condition<Flatten<{
+            baseSchema: TContext[`baseSchema`];
+            schema: {
+                [K in TAs]: RemoveIndexSignature<TContext[`baseSchema`][TFrom]>;
+            };
+        }>>;
+    }): QueryBuilder<Flatten<Omit<TContext, `schema`> & {
+        schema: TContext[`schema`] & {
+            [K in TAs]: RemoveIndexSignature<TContext[`baseSchema`][TFrom]>;
+        };
+    }>>;
+    private joinCollectionRef;
+    private joinInputReference;
+    /**
+     * Add an orderBy clause to sort the results.
+     * Overwrites any previous orderBy clause.
+     *
+     * @param orderBy The order specification
+     * @returns A new QueryBuilder with the orderBy clause set
+     */
+    orderBy(orderBy: OrderBy<TContext>): QueryBuilder<TContext>;
+    /**
+     * Set a limit on the number of results returned.
+     *
+     * @param limit Maximum number of results to return
+     * @returns A new QueryBuilder with the limit set
+     */
+    limit(limit: Limit<TContext>): QueryBuilder<TContext>;
+    /**
+     * Set an offset to skip a number of results.
+     *
+     * @param offset Number of results to skip
+     * @returns A new QueryBuilder with the offset set
+     */
+    offset(offset: Offset<TContext>): QueryBuilder<TContext>;
+    /**
+     * Specify which column(s) to use as keys in the output keyed stream.
+     *
+     * @param keyBy The column(s) to use as keys
+     * @returns A new QueryBuilder with the keyBy clause set
+     */
+    keyBy(keyBy: PropertyReference<TContext> | Array<PropertyReference<TContext>>): QueryBuilder<TContext>;
+    /**
+     * Add a groupBy clause to group the results by one or more columns.
+     *
+     * @param groupBy The column(s) to group by
+     * @returns A new QueryBuilder with the groupBy clause set
+     */
+    groupBy(groupBy: PropertyReference<TContext> | Array<PropertyReference<TContext>>): QueryBuilder<TContext>;
+    /**
+     * Define a Common Table Expression (CTE) that can be referenced in the main query.
+     * This allows referencing the CTE by name in subsequent from/join clauses.
+     *
+     * @param name The name of the CTE
+     * @param queryBuilderCallback A function that builds the CTE query
+     * @returns A new QueryBuilder with the CTE added
+     */
+    with<TName extends string, TResult = Record<string, unknown>>(name: TName, queryBuilderCallback: (builder: InitialQueryBuilder<{
+        baseSchema: TContext[`baseSchema`];
+        schema: {};
+    }>) => QueryBuilder<any>): InitialQueryBuilder<{
+        baseSchema: TContext[`baseSchema`] & {
+            [K in TName]: TResult;
+        };
+        schema: TContext[`schema`];
+    }>;
+    get _query(): Query<TContext>;
+}
+export type InitialQueryBuilder<TContext extends Context<Schema>> = Pick<BaseQueryBuilder<TContext>, `from` | `with`>;
+export type QueryBuilder<TContext extends Context<Schema>> = Omit<BaseQueryBuilder<TContext>, `from`>;
+/**
+ * Create a new query builder with the given schema
+ */
+export declare function queryBuilder<TBaseSchema extends Schema = {}>(): InitialQueryBuilder<{
+    baseSchema: TBaseSchema;
+    schema: {};
+}>;
+export type ResultsFromContext<TContext extends Context<Schema>> = Flatten<TContext[`result`] extends object ? TContext[`result`] : TContext[`result`] extends undefined ? TContext[`schema`] : object>;
+export type ResultFromQueryBuilder<TQueryBuilder> = Flatten<TQueryBuilder extends QueryBuilder<infer C> ? C extends {
+    result: infer R;
+} ? R : never : never>;
+export {};