@warlock.js/cascade 4.4.0 → 4.6.0

package/esm/expressions/aggregate-expressions.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"aggregate-expressions.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/expressions/aggregate-expressions.ts"],"sourcesContent":["/**\n * Database-agnostic aggregation expressions.\n *\n * `count` / `sum` / `avg` / `min` / `max` are **cross-driver** — the same\n * call compiles to the native shape on every supported database (MongoDB\n * `{ $sum: \"$field\" }`, SQL `SUM(field)`, ...).\n *\n * `distinct` / `floor` / `first` / `last` are **MongoDB-only**. They have no\n * single-scalar `GROUP BY` equivalent in SQL, so on Postgres they throw a\n * fail-fast error at the `.groupBy()` call (naming the `selectRaw` /\n * `havingRaw` escape hatch) rather than emit a silently-different query.\n *\n * @example\n * ```typescript\n * import { $agg } from '@warlock.js/cascade';\n *\n * // Works for both MongoDB and SQL\n * Lesson.query()\n *   .groupBy(\"type\", {\n *     count: $agg.count(),\n *     total: $agg.sum(\"duration\"),\n *     avg: $agg.avg(\"rating\")\n *   })\n *   .get();\n * ```\n */\n\n/**\n * Abstract aggregate expression format.\n *\n * This format is database-agnostic and will be translated by each driver\n * to their native syntax.\n */\nexport type AggregateExpression = {\n  /** The aggregate function type */\n  __agg: AggregateFunction;\n  /** The field to aggregate (null for count) */\n  __field: string | null;\n};\n\n/**\n * Supported aggregate functions.\n */\nexport type AggregateFunction =\n  | \"count\"\n  | \"sum\"\n  | \"avg\"\n  | \"min\"\n  | \"max\"\n  | \"first\"\n  | \"last\"\n  | \"distinct\"\n  | \"floor\";\n\n/**\n * Checks if a value is an abstract aggregate expression.\n */\nexport function isAggregateExpression(value: unknown): value is AggregateExpression {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"__field\" in value &&\n    typeof (value as AggregateExpression).__agg === \"string\"\n  );\n}\n\n/**\n * Database-agnostic aggregation expression helpers.\n *\n * These helpers create abstract expressions that each driver translates\n * to their native format.\n */\nexport const $agg = {\n  /**\n   * Count documents in each group.\n   *\n   * @returns Abstract count expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   count: $agg.count()\n   * });\n   * ```\n   *\n   * Translates to:\n   * - MongoDB: `{ $sum: 1 }`\n   * - SQL: `COUNT(*)`\n   */\n  count(): AggregateExpression {\n    return { __agg: \"count\", __field: null };\n  },\n\n  /**\n   * Sum a numeric field across documents in each group.\n   *\n   * @param field - The field name to sum\n   * @returns Abstract sum expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   totalDuration: $agg.sum(\"duration\")\n   * });\n   * ```\n   *\n   * Translates to:\n   * - MongoDB: `{ $sum: \"$duration\" }`\n   * - SQL: `SUM(duration)`\n   */\n  sum(field: string): AggregateExpression {\n    return { __agg: \"sum\", __field: field };\n  },\n\n  /**\n   * Calculate the average value of a field across documents in each group.\n   *\n   * @param field - The field name to average\n   * @returns Abstract average expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   avgRating: $agg.avg(\"rating\")\n   * });\n   * ```\n   *\n   * Translates to:\n   * - MongoDB: `{ $avg: \"$rating\" }`\n   * - SQL: `AVG(rating)`\n   */\n  avg(field: string): AggregateExpression {\n    return { __agg: \"avg\", __field: field };\n  },\n\n  /**\n   * Get the minimum value of a field across documents in each group.\n   *\n   * @param field - The field name\n   * @returns Abstract min expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   minPrice: $agg.min(\"price\")\n   * });\n   * ```\n   *\n   * Translates to:\n   * - MongoDB: `{ $min: \"$price\" }`\n   * - SQL: `MIN(price)`\n   */\n  min(field: string): AggregateExpression {\n    return { __agg: \"min\", __field: field };\n  },\n\n  /**\n   * Get the maximum value of a field across documents in each group.\n   *\n   * @param field - The field name\n   * @returns Abstract max expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   maxPrice: $agg.max(\"price\")\n   * });\n   * ```\n   *\n   * Translates to:\n   * - MongoDB: `{ $max: \"$price\" }`\n   * - SQL: `MAX(price)`\n   */\n  max(field: string): AggregateExpression {\n    return { __agg: \"max\", __field: field };\n  },\n\n  /**\n   * Get the distinct values of a field across documents in each group.\n   *\n   * @param field - The field name\n   * @returns Abstract distinct expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   distinctColors: $agg.distinct(\"color\")\n   * });\n   * ```\n   *\n   * **MongoDB-only.** MongoDB: `{ $distinct: \"$color\" }` (returns the array\n   * of distinct values). On Postgres this throws — SQL `DISTINCT` is a set\n   * quantifier, not a scalar aggregate, so there is no equivalent single\n   * value to put in a `GROUP BY` projection. Use `selectRaw` if you need a\n   * Postgres-specific shape (e.g. `array_agg(DISTINCT color)`).\n   */\n  distinct(field: string): AggregateExpression {\n    return { __agg: \"distinct\", __field: field };\n  },\n\n  /**\n   * Get the floor value of a field across documents in each group.\n   *\n   * @param field - The field name\n   * @returns Abstract floor expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   floorPrice: $agg.floor(\"price\")\n   * });\n   * ```\n   *\n   * **MongoDB-only.** MongoDB: `{ $floor: \"$price\" }`. On Postgres this\n   * throws — `FLOOR` is a scalar function, not an aggregate, so it is\n   * meaningless inside a bare `$group` / `GROUP BY`. Use `selectRaw` with\n   * `FLOOR(...)` over the aggregated value if you need it on Postgres.\n   */\n  floor(field: string): AggregateExpression {\n    return { __agg: \"floor\", __field: field };\n  },\n\n  /**\n   * Get the first value of a field in each group (order-dependent).\n   *\n   * @param field - The field name\n   * @returns Abstract first expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   firstName: $agg.first(\"name\")\n   * });\n   * ```\n   *\n   * **MongoDB-only.** MongoDB: `{ $first: \"$name\" }` (group-order\n   * dependent). On Postgres this throws — the SQL equivalent is\n   * `FIRST_VALUE(name) OVER (ORDER BY ...)`, a window function needing an\n   * ordering context the `$agg` API doesn't carry. Use `selectRaw` with an\n   * explicit window function if you need it on Postgres.\n   */\n  first(field: string): AggregateExpression {\n    return { __agg: \"first\", __field: field };\n  },\n\n  /**\n   * Get the last value of a field in each group (order-dependent).\n   *\n   * @param field - The field name\n   * @returns Abstract last expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   lastName: $agg.last(\"name\")\n   * });\n   * ```\n   *\n   * **MongoDB-only.** MongoDB: `{ $last: \"$name\" }` (group-order\n   * dependent). On Postgres this throws — the SQL equivalent is\n   * `LAST_VALUE(name) OVER (ORDER BY ...)`, a window function needing an\n   * ordering context the `$agg` API doesn't carry. Use `selectRaw` with an\n   * explicit window function if you need it on Postgres.\n   */\n  last(field: string): AggregateExpression {\n    return { __agg: \"last\", __field: field };\n  },\n};\n"],"mappings":";;;;AAyDA,SAAgB,sBAAsB,OAA8C;CAClF,OACE,OAAO,UAAU,YACjB,UAAU,QACV,aAAa,SACb,OAAQ,MAA8B,UAAU;AAEpD;;;;;;;AAQA,MAAa,OAAO;;;;;;;;;;;;;;;;;CAiBlB,QAA6B;EAC3B,OAAO;GAAE,OAAO;GAAS,SAAS;EAAK;CACzC;;;;;;;;;;;;;;;;;;CAmBA,IAAI,OAAoC;EACtC,OAAO;GAAE,OAAO;GAAO,SAAS;EAAM;CACxC;;;;;;;;;;;;;;;;;;CAmBA,IAAI,OAAoC;EACtC,OAAO;GAAE,OAAO;GAAO,SAAS;EAAM;CACxC;;;;;;;;;;;;;;;;;;CAmBA,IAAI,OAAoC;EACtC,OAAO;GAAE,OAAO;GAAO,SAAS;EAAM;CACxC;;;;;;;;;;;;;;;;;;CAmBA,IAAI,OAAoC;EACtC,OAAO;GAAE,OAAO;GAAO,SAAS;EAAM;CACxC;;;;;;;;;;;;;;;;;;;;CAqBA,SAAS,OAAoC;EAC3C,OAAO;GAAE,OAAO;GAAY,SAAS;EAAM;CAC7C;;;;;;;;;;;;;;;;;;;CAoBA,MAAM,OAAoC;EACxC,OAAO;GAAE,OAAO;GAAS,SAAS;EAAM;CAC1C;;;;;;;;;;;;;;;;;;;;CAqBA,MAAM,OAAoC;EACxC,OAAO;GAAE,OAAO;GAAS,SAAS;EAAM;CAC1C;;;;;;;;;;;;;;;;;;;;CAqBA,KAAK,OAAoC;EACvC,OAAO;GAAE,OAAO;GAAQ,SAAS;EAAM;CACzC;AACF"}
+{"version":3,"file":"aggregate-expressions.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/expressions/aggregate-expressions.ts"],"sourcesContent":["/**\n * Database-agnostic aggregation expressions.\n *\n * `count` / `countDistinct` / `sum` / `avg` / `min` / `max` are **cross-driver**\n * — the same call compiles to the native shape on every supported database\n * (MongoDB `{ $sum: \"$field\" }`, SQL `SUM(field)`, ...). `countDistinct` uses\n * MongoDB's `$addToSet` + `$size` per-group pattern and SQL `COUNT(DISTINCT …)`.\n *\n * `distinct` / `floor` / `first` / `last` are **MongoDB-only**. They have no\n * single-scalar `GROUP BY` equivalent in SQL, so on Postgres they throw a\n * fail-fast error at the `.groupBy()` call (naming the `selectRaw` /\n * `havingRaw` escape hatch) rather than emit a silently-different query.\n *\n * @example\n * ```typescript\n * import { $agg } from '@warlock.js/cascade';\n *\n * // Works for both MongoDB and SQL\n * Lesson.query()\n *   .groupBy(\"type\", {\n *     count: $agg.count(),\n *     total: $agg.sum(\"duration\"),\n *     avg: $agg.avg(\"rating\")\n *   })\n *   .get();\n * ```\n */\n\nimport type { ColumnExpression, ColumnExpressionInput } from \"./column-expressions\";\n\n/**\n * Abstract aggregate expression format.\n *\n * This format is database-agnostic and will be translated by each driver\n * to their native syntax.\n */\nexport type AggregateExpression = {\n  /** The aggregate function type */\n  __agg: AggregateFunction;\n  /** The field to aggregate (null for count, or when `__expr` carries a composed expression) */\n  __field: string | null;\n  /**\n   * A typed column expression to aggregate over, when the aggregate operates\n   * on more than a bare column (e.g. `price * quantity`). When present, drivers\n   * compile this instead of `__field`. Absent for the simple bare-column form\n   * so existing `$agg.sum(\"col\")` payloads stay byte-for-byte identical.\n   */\n  __expr?: ColumnExpression;\n};\n\n/**\n * Supported aggregate functions.\n */\nexport type AggregateFunction =\n  | \"count\"\n  | \"countDistinct\"\n  | \"sum\"\n  | \"avg\"\n  | \"min\"\n  | \"max\"\n  | \"first\"\n  | \"last\"\n  | \"distinct\"\n  | \"floor\";\n\n/**\n * Checks if a value is an abstract aggregate expression.\n */\nexport function isAggregateExpression(value: unknown): value is AggregateExpression {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"__field\" in value &&\n    typeof (value as AggregateExpression).__agg === \"string\"\n  );\n}\n\n/**\n * Database-agnostic aggregation expression helpers.\n *\n * These helpers create abstract expressions that each driver translates\n * to their native format.\n */\nexport const $agg = {\n  /**\n   * Count documents in each group.\n   *\n   * @returns Abstract count expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   count: $agg.count()\n   * });\n   * ```\n   *\n   * Translates to:\n   * - MongoDB: `{ $sum: 1 }`\n   * - SQL: `COUNT(*)`\n   */\n  count(): AggregateExpression {\n    return { __agg: \"count\", __field: null };\n  },\n\n  /**\n   * Count the number of distinct values of a field in each group.\n   *\n   * @param field - The field name to count distinct values of\n   * @returns Abstract count-distinct expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"country\", {\n   *   uniqueCities: $agg.countDistinct(\"city\")\n   * });\n   * ```\n   *\n   * **Cross-driver.** Translates to:\n   * - SQL: `COUNT(DISTINCT city)`\n   * - MongoDB: `{ $addToSet: \"$city\" }` in the `$group` stage, finalized with\n   *   `{ $size: \"$uniqueCities\" }` in the renaming `$project` (the standard\n   *   distinct-count-per-group pattern, since `$size` is not a `$group`\n   *   accumulator).\n   */\n  countDistinct(field: string): AggregateExpression {\n    return { __agg: \"countDistinct\", __field: field };\n  },\n\n  /**\n   * Sum a numeric field — or a composed arithmetic expression — across\n   * documents in each group.\n   *\n   * Pass a bare column name to sum a single field (unchanged from v1), or a\n   * typed `$expr` node (`$expr.mul` / `$expr.add` / `$expr.sub` / `$expr.div` /\n   * `$expr.col` / `$expr.lit`) to sum a computed value such as `price * quantity`.\n   *\n   * @param input - A field name or a typed `ColumnExpression`\n   * @returns Abstract sum expression\n   *\n   * @example\n   * ```typescript\n   * import { $agg, $expr } from \"@warlock.js/cascade\";\n   *\n   * // Bare column\n   * query.groupBy(\"type\", { totalDuration: $agg.sum(\"duration\") });\n   *\n   * // Composed expression: SUM(price * quantity)\n   * query.groupBy(\"type\", { revenue: $agg.sum($expr.mul(\"price\", \"quantity\")) });\n   * ```\n   *\n   * Translates to:\n   * - SQL: `SUM(\"duration\")` / `SUM((\"price\" * \"quantity\"))`\n   * - MongoDB: `{ $sum: \"$duration\" }` / `{ $sum: { $multiply: [\"$price\", \"$quantity\"] } }`\n   */\n  sum(input: ColumnExpressionInput): AggregateExpression {\n    if (typeof input === \"string\") {\n      return { __agg: \"sum\", __field: input };\n    }\n\n    return { __agg: \"sum\", __field: null, __expr: input };\n  },\n\n  /**\n   * Sum a raw, driver-native expression escape hatch.\n   *\n   * Equivalent to `$agg.sum($expr.raw(expression))`. The raw string is emitted\n   * verbatim into the generated query — never build it from untrusted input.\n   * Reach for the typed {@link sum} form first; this exists only for fragments\n   * the typed combinators can't express.\n   *\n   * @param expression - A raw expression fragment (e.g. `\"price * quantity\"`)\n   * @returns Abstract sum expression wrapping the raw fragment\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   net: $agg.sumRaw(\"price * quantity * (1 - discount)\"),\n   * });\n   * ```\n   *\n   * Translates to:\n   * - SQL: `SUM(price * quantity * (1 - discount))`\n   * - MongoDB: throws — raw SQL fragments are not portable to a pipeline; use\n   *   the typed {@link sum} form (or `groupByRaw`) on MongoDB instead.\n   */\n  sumRaw(expression: string): AggregateExpression {\n    return {\n      __agg: \"sum\",\n      __field: null,\n      __expr: { __expr: \"raw\", expression },\n    };\n  },\n\n  /**\n   * Calculate the average value of a field across documents in each group.\n   *\n   * @param field - The field name to average\n   * @returns Abstract average expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   avgRating: $agg.avg(\"rating\")\n   * });\n   * ```\n   *\n   * Translates to:\n   * - MongoDB: `{ $avg: \"$rating\" }`\n   * - SQL: `AVG(rating)`\n   */\n  avg(field: string): AggregateExpression {\n    return { __agg: \"avg\", __field: field };\n  },\n\n  /**\n   * Get the minimum value of a field across documents in each group.\n   *\n   * @param field - The field name\n   * @returns Abstract min expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   minPrice: $agg.min(\"price\")\n   * });\n   * ```\n   *\n   * Translates to:\n   * - MongoDB: `{ $min: \"$price\" }`\n   * - SQL: `MIN(price)`\n   */\n  min(field: string): AggregateExpression {\n    return { __agg: \"min\", __field: field };\n  },\n\n  /**\n   * Get the maximum value of a field across documents in each group.\n   *\n   * @param field - The field name\n   * @returns Abstract max expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   maxPrice: $agg.max(\"price\")\n   * });\n   * ```\n   *\n   * Translates to:\n   * - MongoDB: `{ $max: \"$price\" }`\n   * - SQL: `MAX(price)`\n   */\n  max(field: string): AggregateExpression {\n    return { __agg: \"max\", __field: field };\n  },\n\n  /**\n   * Get the distinct values of a field across documents in each group.\n   *\n   * @param field - The field name\n   * @returns Abstract distinct expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   distinctColors: $agg.distinct(\"color\")\n   * });\n   * ```\n   *\n   * **MongoDB-only.** MongoDB: `{ $distinct: \"$color\" }` (returns the array\n   * of distinct values). On Postgres this throws — SQL `DISTINCT` is a set\n   * quantifier, not a scalar aggregate, so there is no equivalent single\n   * value to put in a `GROUP BY` projection. Use `selectRaw` if you need a\n   * Postgres-specific shape (e.g. `array_agg(DISTINCT color)`).\n   */\n  distinct(field: string): AggregateExpression {\n    return { __agg: \"distinct\", __field: field };\n  },\n\n  /**\n   * Get the floor value of a field across documents in each group.\n   *\n   * @param field - The field name\n   * @returns Abstract floor expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   floorPrice: $agg.floor(\"price\")\n   * });\n   * ```\n   *\n   * **MongoDB-only.** MongoDB: `{ $floor: \"$price\" }`. On Postgres this\n   * throws — `FLOOR` is a scalar function, not an aggregate, so it is\n   * meaningless inside a bare `$group` / `GROUP BY`. Use `selectRaw` with\n   * `FLOOR(...)` over the aggregated value if you need it on Postgres.\n   */\n  floor(field: string): AggregateExpression {\n    return { __agg: \"floor\", __field: field };\n  },\n\n  /**\n   * Get the first value of a field in each group (order-dependent).\n   *\n   * @param field - The field name\n   * @returns Abstract first expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   firstName: $agg.first(\"name\")\n   * });\n   * ```\n   *\n   * **MongoDB-only.** MongoDB: `{ $first: \"$name\" }` (group-order\n   * dependent). On Postgres this throws — the SQL equivalent is\n   * `FIRST_VALUE(name) OVER (ORDER BY ...)`, a window function needing an\n   * ordering context the `$agg` API doesn't carry. Use `selectRaw` with an\n   * explicit window function if you need it on Postgres.\n   */\n  first(field: string): AggregateExpression {\n    return { __agg: \"first\", __field: field };\n  },\n\n  /**\n   * Get the last value of a field in each group (order-dependent).\n   *\n   * @param field - The field name\n   * @returns Abstract last expression\n   *\n   * @example\n   * ```typescript\n   * query.groupBy(\"type\", {\n   *   lastName: $agg.last(\"name\")\n   * });\n   * ```\n   *\n   * **MongoDB-only.** MongoDB: `{ $last: \"$name\" }` (group-order\n   * dependent). On Postgres this throws — the SQL equivalent is\n   * `LAST_VALUE(name) OVER (ORDER BY ...)`, a window function needing an\n   * ordering context the `$agg` API doesn't carry. Use `selectRaw` with an\n   * explicit window function if you need it on Postgres.\n   */\n  last(field: string): AggregateExpression {\n    return { __agg: \"last\", __field: field };\n  },\n};\n"],"mappings":";;;;AAoEA,SAAgB,sBAAsB,OAA8C;CAClF,OACE,OAAO,UAAU,YACjB,UAAU,QACV,aAAa,SACb,OAAQ,MAA8B,UAAU;AAEpD;;;;;;;AAQA,MAAa,OAAO;;;;;;;;;;;;;;;;;CAiBlB,QAA6B;EAC3B,OAAO;GAAE,OAAO;GAAS,SAAS;EAAK;CACzC;;;;;;;;;;;;;;;;;;;;;CAsBA,cAAc,OAAoC;EAChD,OAAO;GAAE,OAAO;GAAiB,SAAS;EAAM;CAClD;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BA,IAAI,OAAmD;EACrD,IAAI,OAAO,UAAU,UACnB,OAAO;GAAE,OAAO;GAAO,SAAS;EAAM;EAGxC,OAAO;GAAE,OAAO;GAAO,SAAS;GAAM,QAAQ;EAAM;CACtD;;;;;;;;;;;;;;;;;;;;;;;;CAyBA,OAAO,YAAyC;EAC9C,OAAO;GACL,OAAO;GACP,SAAS;GACT,QAAQ;IAAE,QAAQ;IAAO;GAAW;EACtC;CACF;;;;;;;;;;;;;;;;;;CAmBA,IAAI,OAAoC;EACtC,OAAO;GAAE,OAAO;GAAO,SAAS;EAAM;CACxC;;;;;;;;;;;;;;;;;;CAmBA,IAAI,OAAoC;EACtC,OAAO;GAAE,OAAO;GAAO,SAAS;EAAM;CACxC;;;;;;;;;;;;;;;;;;CAmBA,IAAI,OAAoC;EACtC,OAAO;GAAE,OAAO;GAAO,SAAS;EAAM;CACxC;;;;;;;;;;;;;;;;;;;;CAqBA,SAAS,OAAoC;EAC3C,OAAO;GAAE,OAAO;GAAY,SAAS;EAAM;CAC7C;;;;;;;;;;;;;;;;;;;CAoBA,MAAM,OAAoC;EACxC,OAAO;GAAE,OAAO;GAAS,SAAS;EAAM;CAC1C;;;;;;;;;;;;;;;;;;;;CAqBA,MAAM,OAAoC;EACxC,OAAO;GAAE,OAAO;GAAS,SAAS;EAAM;CAC1C;;;;;;;;;;;;;;;;;;;;CAqBA,KAAK,OAAoC;EACvC,OAAO;GAAE,OAAO;GAAQ,SAAS;EAAM;CACzC;AACF"}

package/esm/expressions/column-expressions.d.mts

@@ -0,0 +1,193 @@
+//#region ../@warlock.js/cascade/src/expressions/column-expressions.d.ts
+/**
+ * Database-agnostic, **typed** column expressions for aggregate inputs.
+ *
+ * These let `$agg.sum(...)` (and any future expression-accepting aggregate)
+ * operate on a composed arithmetic expression — e.g. `price * quantity` — not
+ * just a bare column, while staying portable across drivers.
+ *
+ * The builders are grouped under a single `$expr` object (mirroring `$agg`),
+ * so the package root exposes exactly two expression namespaces — `$agg` for
+ * aggregates and `$expr` for the scalar arithmetic that feeds them — rather
+ * than a handful of collision-prone bare verbs (`mul`, `add`, `col`, …).
+ *
+ * The expression tree is a small, closed union of safe nodes:
+ *
+ * - `$expr.col("price")` — a column reference (driver quotes/escapes it)
+ * - `$expr.lit(2)` — a numeric/boolean literal
+ * - `$expr.mul(a, b, …)` / `$expr.add(…)` / `$expr.sub(a, b)` / `$expr.div(a, b)` — arithmetic
+ * - `$expr.raw("price * 1.2")` — an explicit escape hatch for a raw SQL fragment
+ *
+ * Only `$expr.raw` ever embeds an uninterpreted string, and it is opt-in by
+ * name. Everything else is composed from typed nodes, so user-supplied column
+ * names flow through the driver's identifier-quoting path rather than being
+ * string-interpolated into SQL. This is the boundary the S2 task calls out: a
+ * tiny typed DSL for the common safe ops, plus a clearly-named raw escape
+ * hatch for everything beyond it.
+ *
+ * Bare strings are still accepted everywhere a `ColumnExpression` is — a plain
+ * string is treated as a column reference (`"price"` === `$expr.col("price")`),
+ * so the existing `$agg.sum("amount")` call site keeps working unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { $agg, $expr } from "@warlock.js/cascade";
+ *
+ * query.groupByDate("created_at", "month", {
+ *   revenue: $agg.sum($expr.mul("price", "quantity")),
+ * });
+ * ```
+ */
+/** Discriminator tag identifying a node in the column-expression tree. */
+type ColumnExpressionType = "column" | "literal" | "add" | "subtract" | "multiply" | "divide" | "raw";
+/**
+ * A reference to a column/field. The driver is responsible for quoting the
+ * name (SQL) or prefixing it with `$` (Mongo) — it is never interpolated raw.
+ */
+type ColumnRefExpression = {
+  readonly __expr: "column";
+  readonly column: string;
+};
+/** A scalar literal value embedded directly in the expression. */
+type LiteralExpression = {
+  readonly __expr: "literal";
+  readonly value: number | boolean;
+};
+/**
+ * An arithmetic operation over one or more operands.
+ *
+ * `add` / `multiply` are variadic; `subtract` / `divide` take exactly two
+ * operands (left, right) since they are not associative.
+ */
+type ArithmeticExpression = {
+  readonly __expr: "add" | "subtract" | "multiply" | "divide";
+  readonly operands: ColumnExpression[];
+};
+/**
+ * A raw expression escape hatch. The string is emitted verbatim into the
+ * generated SQL — callers MUST NOT build it from untrusted input. This is the
+ * documented boundary for anything the typed nodes above don't cover.
+ */
+type RawColumnExpression = {
+  readonly __expr: "raw";
+  readonly expression: string;
+};
+/**
+ * Any node in the typed column-expression tree. A bare `string` is also a
+ * valid expression input wherever this type is accepted — it is interpreted as
+ * a column reference.
+ */
+type ColumnExpression = ColumnRefExpression | LiteralExpression | ArithmeticExpression | RawColumnExpression;
+/** Input accepted by expression-aware helpers: a typed node or a column-name string. */
+type ColumnExpressionInput = ColumnExpression | string;
+/**
+ * Type guard: is `value` one of the typed column-expression nodes?
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is a `ColumnExpression` node
+ */
+declare function isColumnExpression(value: unknown): value is ColumnExpression;
+/**
+ * Reference a column/field by name.
+ *
+ * @param column - The column/field name
+ * @returns A column-reference expression node
+ */
+declare function col(column: string): ColumnRefExpression;
+/**
+ * A scalar literal (number or boolean) operand.
+ *
+ * @param value - The literal value
+ * @returns A literal expression node
+ */
+declare function lit(value: number | boolean): LiteralExpression;
+/**
+ * Multiply two or more operands.
+ *
+ * @param operands - Column names, literals, or nested expression nodes
+ * @returns A multiply expression node
+ */
+declare function mul(...operands: ColumnExpressionInput[]): ArithmeticExpression;
+/**
+ * Add two or more operands.
+ *
+ * @param operands - Column names, literals, or nested expression nodes
+ * @returns An add expression node
+ */
+declare function add(...operands: ColumnExpressionInput[]): ArithmeticExpression;
+/**
+ * Subtract `right` from `left`.
+ *
+ * @param left - The minuend
+ * @param right - The subtrahend
+ * @returns A subtract expression node
+ */
+declare function sub(left: ColumnExpressionInput, right: ColumnExpressionInput): ArithmeticExpression;
+/**
+ * Divide `left` by `right`.
+ *
+ * @param left - The dividend
+ * @param right - The divisor
+ * @returns A divide expression node
+ */
+declare function div(left: ColumnExpressionInput, right: ColumnExpressionInput): ArithmeticExpression;
+/**
+ * Wrap a raw expression string as an escape hatch.
+ *
+ * The string is emitted verbatim — never build it from untrusted input. Use
+ * this only when the typed `$expr.mul` / `$expr.add` / `$expr.sub` /
+ * `$expr.div` / `$expr.col` / `$expr.lit` combinators can't express what you
+ * need.
+ *
+ * @param expression - A raw, driver-native expression fragment
+ * @returns A raw expression node
+ */
+declare function raw(expression: string): RawColumnExpression;
+/**
+ * Normalize an expression input to a `ColumnExpression` node. A bare string
+ * becomes a `$expr.col(...)` reference; an existing node passes through
+ * unchanged.
+ *
+ * @param input - A typed expression node or a bare column-name string
+ * @returns The corresponding `ColumnExpression` node
+ */
+declare function toColumnExpression(input: ColumnExpressionInput): ColumnExpression;
+/**
+ * Typed, database-agnostic column-expression builders.
+ *
+ * Grouped under one object (like `$agg`) so the scalar arithmetic that feeds
+ * an aggregate reads as a single, discoverable namespace: `$agg.sum($expr.mul(
+ * "price", "quantity"))`. Each builder returns a plain, closed `ColumnExpression`
+ * node — the driver translates it to native SQL / a Mongo pipeline.
+ *
+ * @example
+ * ```typescript
+ * import { $agg, $expr } from "@warlock.js/cascade";
+ *
+ * // SUM(price * quantity)
+ * query.groupBy("product_id", { revenue: $agg.sum($expr.mul("price", "quantity")) });
+ *
+ * // SUM((1 - discount) * price)
+ * query.groupBy("product_id", {
+ *   net: $agg.sum($expr.mul($expr.sub($expr.lit(1), "discount"), "price")),
+ * });
+ *
+ * // price * 1.2 (e.g. tax)
+ * $agg.sum($expr.mul("price", $expr.lit(1.2)));
+ *
+ * // escape hatch (Postgres-only, emitted verbatim — never from user input)
+ * $agg.sum($expr.raw("price * quantity * (1 - discount)"));
+ * ```
+ */
+declare const $expr: {
+  col: typeof col;
+  lit: typeof lit;
+  mul: typeof mul;
+  add: typeof add;
+  sub: typeof sub;
+  div: typeof div;
+  raw: typeof raw;
+};
+//#endregion
+export { $expr, ArithmeticExpression, ColumnExpression, ColumnExpressionInput, ColumnExpressionType, ColumnRefExpression, LiteralExpression, RawColumnExpression, isColumnExpression, toColumnExpression };
+//# sourceMappingURL=column-expressions.d.mts.map

package/esm/expressions/column-expressions.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-expressions.d.mts","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/expressions/column-expressions.ts"],"mappings":";;AAyCA;;;;AAAgC;AAahC;;;;AAEiB;AAIjB;;;;AAEgB;AAShB;;;;;;;;AAEqC;AAQrC;;;;AAEqB;AAQrB;;;;;;;;;;KAlDY,oBAAA;;;;AAsDW;KAzCX,mBAAA;EAAA,SACD,MAAA;EAAA,SACA,MAAM;AAAA;AA0CmC;AAAA,KAtCxC,iBAAA;EAAA,SACD,MAAA;EAAA,SACA,KAAK;AAAA;;;;;AA4C6D;AAM5E;KAzCW,oBAAA;EAAA,SACD,MAAA;EAAA,SACA,QAAA,EAAU,gBAAgB;AAAA;AA+CY;;;;AAUO;AAVP,KAvCrC,mBAAA;EAAA,SACD,MAAA;EAAA,SACA,UAAU;AAAA;;;;;AAyDmD;KAjD5D,gBAAA,GACR,mBAAA,GACA,iBAAA,GACA,oBAAA,GACA,mBAAA;;KAGQ,qBAAA,GAAwB,gBAAgB;;;;;;AAoDoB;iBA5CxD,kBAAA,CAAmB,KAAA,YAAiB,KAAA,IAAS,gBAAgB;;;;;;;iBAcpE,GAAA,CAAI,MAAA,WAAiB,mBAAmB;;;;;;;iBAUxC,GAAA,CAAI,KAAA,qBAA0B,iBAAiB;AAkCjC;;;;;;AAAA,iBAxBd,GAAA,IAAO,QAAA,EAAU,qBAAA,KAA0B,oBAAoB;;;;;;;iBAU/D,GAAA,IAAO,QAAA,EAAU,qBAAA,KAA0B,oBAAoB;AA+BjD;AAAA;;;;AAkB8B;AAYrD;AA9BuB,iBApBd,GAAA,CACP,IAAA,EAAM,qBAAA,EACN,KAAA,EAAO,qBAAA,GACN,oBAAA;;;;;;;AA+C+E;iBAjCzE,GAAA,CACP,IAAA,EAAM,qBAAA,EACN,KAAA,EAAO,qBAAA,GACN,oBAAA;;;;;;;;;;;;iBAkBM,GAAA,CAAI,UAAA,WAAqB,mBAAmB;;;;;;;;;iBAYrC,kBAAA,CAAmB,KAAA,EAAO,qBAAA,GAAwB,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BrE,KAAA"}

package/esm/expressions/column-expressions.mjs

@@ -0,0 +1,152 @@
+//#region ../@warlock.js/cascade/src/expressions/column-expressions.ts
+/**
+* Type guard: is `value` one of the typed column-expression nodes?
+*
+* @param value - The value to test
+* @returns `true` when `value` is a `ColumnExpression` node
+*/
+function isColumnExpression(value) {
+	return typeof value === "object" && value !== null && typeof value.__expr === "string";
+}
+/**
+* Reference a column/field by name.
+*
+* @param column - The column/field name
+* @returns A column-reference expression node
+*/
+function col(column) {
+	return {
+		__expr: "column",
+		column
+	};
+}
+/**
+* A scalar literal (number or boolean) operand.
+*
+* @param value - The literal value
+* @returns A literal expression node
+*/
+function lit(value) {
+	return {
+		__expr: "literal",
+		value
+	};
+}
+/**
+* Multiply two or more operands.
+*
+* @param operands - Column names, literals, or nested expression nodes
+* @returns A multiply expression node
+*/
+function mul(...operands) {
+	return {
+		__expr: "multiply",
+		operands: operands.map(toColumnExpression)
+	};
+}
+/**
+* Add two or more operands.
+*
+* @param operands - Column names, literals, or nested expression nodes
+* @returns An add expression node
+*/
+function add(...operands) {
+	return {
+		__expr: "add",
+		operands: operands.map(toColumnExpression)
+	};
+}
+/**
+* Subtract `right` from `left`.
+*
+* @param left - The minuend
+* @param right - The subtrahend
+* @returns A subtract expression node
+*/
+function sub(left, right) {
+	return {
+		__expr: "subtract",
+		operands: [toColumnExpression(left), toColumnExpression(right)]
+	};
+}
+/**
+* Divide `left` by `right`.
+*
+* @param left - The dividend
+* @param right - The divisor
+* @returns A divide expression node
+*/
+function div(left, right) {
+	return {
+		__expr: "divide",
+		operands: [toColumnExpression(left), toColumnExpression(right)]
+	};
+}
+/**
+* Wrap a raw expression string as an escape hatch.
+*
+* The string is emitted verbatim — never build it from untrusted input. Use
+* this only when the typed `$expr.mul` / `$expr.add` / `$expr.sub` /
+* `$expr.div` / `$expr.col` / `$expr.lit` combinators can't express what you
+* need.
+*
+* @param expression - A raw, driver-native expression fragment
+* @returns A raw expression node
+*/
+function raw(expression) {
+	return {
+		__expr: "raw",
+		expression
+	};
+}
+/**
+* Normalize an expression input to a `ColumnExpression` node. A bare string
+* becomes a `$expr.col(...)` reference; an existing node passes through
+* unchanged.
+*
+* @param input - A typed expression node or a bare column-name string
+* @returns The corresponding `ColumnExpression` node
+*/
+function toColumnExpression(input) {
+	return typeof input === "string" ? col(input) : input;
+}
+/**
+* Typed, database-agnostic column-expression builders.
+*
+* Grouped under one object (like `$agg`) so the scalar arithmetic that feeds
+* an aggregate reads as a single, discoverable namespace: `$agg.sum($expr.mul(
+* "price", "quantity"))`. Each builder returns a plain, closed `ColumnExpression`
+* node — the driver translates it to native SQL / a Mongo pipeline.
+*
+* @example
+* ```typescript
+* import { $agg, $expr } from "@warlock.js/cascade";
+*
+* // SUM(price * quantity)
+* query.groupBy("product_id", { revenue: $agg.sum($expr.mul("price", "quantity")) });
+*
+* // SUM((1 - discount) * price)
+* query.groupBy("product_id", {
+*   net: $agg.sum($expr.mul($expr.sub($expr.lit(1), "discount"), "price")),
+* });
+*
+* // price * 1.2 (e.g. tax)
+* $agg.sum($expr.mul("price", $expr.lit(1.2)));
+*
+* // escape hatch (Postgres-only, emitted verbatim — never from user input)
+* $agg.sum($expr.raw("price * quantity * (1 - discount)"));
+* ```
+*/
+const $expr = {
+	col,
+	lit,
+	mul,
+	add,
+	sub,
+	div,
+	raw
+};
+
+//#endregion
+export { $expr, isColumnExpression, toColumnExpression };
+//# sourceMappingURL=column-expressions.mjs.map

package/esm/expressions/column-expressions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-expressions.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/expressions/column-expressions.ts"],"sourcesContent":["/**\n * Database-agnostic, **typed** column expressions for aggregate inputs.\n *\n * These let `$agg.sum(...)` (and any future expression-accepting aggregate)\n * operate on a composed arithmetic expression — e.g. `price * quantity` — not\n * just a bare column, while staying portable across drivers.\n *\n * The builders are grouped under a single `$expr` object (mirroring `$agg`),\n * so the package root exposes exactly two expression namespaces — `$agg` for\n * aggregates and `$expr` for the scalar arithmetic that feeds them — rather\n * than a handful of collision-prone bare verbs (`mul`, `add`, `col`, …).\n *\n * The expression tree is a small, closed union of safe nodes:\n *\n * - `$expr.col(\"price\")` — a column reference (driver quotes/escapes it)\n * - `$expr.lit(2)` — a numeric/boolean literal\n * - `$expr.mul(a, b, …)` / `$expr.add(…)` / `$expr.sub(a, b)` / `$expr.div(a, b)` — arithmetic\n * - `$expr.raw(\"price * 1.2\")` — an explicit escape hatch for a raw SQL fragment\n *\n * Only `$expr.raw` ever embeds an uninterpreted string, and it is opt-in by\n * name. Everything else is composed from typed nodes, so user-supplied column\n * names flow through the driver's identifier-quoting path rather than being\n * string-interpolated into SQL. This is the boundary the S2 task calls out: a\n * tiny typed DSL for the common safe ops, plus a clearly-named raw escape\n * hatch for everything beyond it.\n *\n * Bare strings are still accepted everywhere a `ColumnExpression` is — a plain\n * string is treated as a column reference (`\"price\"` === `$expr.col(\"price\")`),\n * so the existing `$agg.sum(\"amount\")` call site keeps working unchanged.\n *\n * @example\n * ```typescript\n * import { $agg, $expr } from \"@warlock.js/cascade\";\n *\n * query.groupByDate(\"created_at\", \"month\", {\n *   revenue: $agg.sum($expr.mul(\"price\", \"quantity\")),\n * });\n * ```\n */\n\n/** Discriminator tag identifying a node in the column-expression tree. */\nexport type ColumnExpressionType =\n  | \"column\"\n  | \"literal\"\n  | \"add\"\n  | \"subtract\"\n  | \"multiply\"\n  | \"divide\"\n  | \"raw\";\n\n/**\n * A reference to a column/field. The driver is responsible for quoting the\n * name (SQL) or prefixing it with `$` (Mongo) — it is never interpolated raw.\n */\nexport type ColumnRefExpression = {\n  readonly __expr: \"column\";\n  readonly column: string;\n};\n\n/** A scalar literal value embedded directly in the expression. */\nexport type LiteralExpression = {\n  readonly __expr: \"literal\";\n  readonly value: number | boolean;\n};\n\n/**\n * An arithmetic operation over one or more operands.\n *\n * `add` / `multiply` are variadic; `subtract` / `divide` take exactly two\n * operands (left, right) since they are not associative.\n */\nexport type ArithmeticExpression = {\n  readonly __expr: \"add\" | \"subtract\" | \"multiply\" | \"divide\";\n  readonly operands: ColumnExpression[];\n};\n\n/**\n * A raw expression escape hatch. The string is emitted verbatim into the\n * generated SQL — callers MUST NOT build it from untrusted input. This is the\n * documented boundary for anything the typed nodes above don't cover.\n */\nexport type RawColumnExpression = {\n  readonly __expr: \"raw\";\n  readonly expression: string;\n};\n\n/**\n * Any node in the typed column-expression tree. A bare `string` is also a\n * valid expression input wherever this type is accepted — it is interpreted as\n * a column reference.\n */\nexport type ColumnExpression =\n  | ColumnRefExpression\n  | LiteralExpression\n  | ArithmeticExpression\n  | RawColumnExpression;\n\n/** Input accepted by expression-aware helpers: a typed node or a column-name string. */\nexport type ColumnExpressionInput = ColumnExpression | string;\n\n/**\n * Type guard: is `value` one of the typed column-expression nodes?\n *\n * @param value - The value to test\n * @returns `true` when `value` is a `ColumnExpression` node\n */\nexport function isColumnExpression(value: unknown): value is ColumnExpression {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as ColumnExpression).__expr === \"string\"\n  );\n}\n\n/**\n * Reference a column/field by name.\n *\n * @param column - The column/field name\n * @returns A column-reference expression node\n */\nfunction col(column: string): ColumnRefExpression {\n  return { __expr: \"column\", column };\n}\n\n/**\n * A scalar literal (number or boolean) operand.\n *\n * @param value - The literal value\n * @returns A literal expression node\n */\nfunction lit(value: number | boolean): LiteralExpression {\n  return { __expr: \"literal\", value };\n}\n\n/**\n * Multiply two or more operands.\n *\n * @param operands - Column names, literals, or nested expression nodes\n * @returns A multiply expression node\n */\nfunction mul(...operands: ColumnExpressionInput[]): ArithmeticExpression {\n  return { __expr: \"multiply\", operands: operands.map(toColumnExpression) };\n}\n\n/**\n * Add two or more operands.\n *\n * @param operands - Column names, literals, or nested expression nodes\n * @returns An add expression node\n */\nfunction add(...operands: ColumnExpressionInput[]): ArithmeticExpression {\n  return { __expr: \"add\", operands: operands.map(toColumnExpression) };\n}\n\n/**\n * Subtract `right` from `left`.\n *\n * @param left - The minuend\n * @param right - The subtrahend\n * @returns A subtract expression node\n */\nfunction sub(\n  left: ColumnExpressionInput,\n  right: ColumnExpressionInput,\n): ArithmeticExpression {\n  return {\n    __expr: \"subtract\",\n    operands: [toColumnExpression(left), toColumnExpression(right)],\n  };\n}\n\n/**\n * Divide `left` by `right`.\n *\n * @param left - The dividend\n * @param right - The divisor\n * @returns A divide expression node\n */\nfunction div(\n  left: ColumnExpressionInput,\n  right: ColumnExpressionInput,\n): ArithmeticExpression {\n  return {\n    __expr: \"divide\",\n    operands: [toColumnExpression(left), toColumnExpression(right)],\n  };\n}\n\n/**\n * Wrap a raw expression string as an escape hatch.\n *\n * The string is emitted verbatim — never build it from untrusted input. Use\n * this only when the typed `$expr.mul` / `$expr.add` / `$expr.sub` /\n * `$expr.div` / `$expr.col` / `$expr.lit` combinators can't express what you\n * need.\n *\n * @param expression - A raw, driver-native expression fragment\n * @returns A raw expression node\n */\nfunction raw(expression: string): RawColumnExpression {\n  return { __expr: \"raw\", expression };\n}\n\n/**\n * Normalize an expression input to a `ColumnExpression` node. A bare string\n * becomes a `$expr.col(...)` reference; an existing node passes through\n * unchanged.\n *\n * @param input - A typed expression node or a bare column-name string\n * @returns The corresponding `ColumnExpression` node\n */\nexport function toColumnExpression(input: ColumnExpressionInput): ColumnExpression {\n  return typeof input === \"string\" ? col(input) : input;\n}\n\n/**\n * Typed, database-agnostic column-expression builders.\n *\n * Grouped under one object (like `$agg`) so the scalar arithmetic that feeds\n * an aggregate reads as a single, discoverable namespace: `$agg.sum($expr.mul(\n * \"price\", \"quantity\"))`. Each builder returns a plain, closed `ColumnExpression`\n * node — the driver translates it to native SQL / a Mongo pipeline.\n *\n * @example\n * ```typescript\n * import { $agg, $expr } from \"@warlock.js/cascade\";\n *\n * // SUM(price * quantity)\n * query.groupBy(\"product_id\", { revenue: $agg.sum($expr.mul(\"price\", \"quantity\")) });\n *\n * // SUM((1 - discount) * price)\n * query.groupBy(\"product_id\", {\n *   net: $agg.sum($expr.mul($expr.sub($expr.lit(1), \"discount\"), \"price\")),\n * });\n *\n * // price * 1.2 (e.g. tax)\n * $agg.sum($expr.mul(\"price\", $expr.lit(1.2)));\n *\n * // escape hatch (Postgres-only, emitted verbatim — never from user input)\n * $agg.sum($expr.raw(\"price * quantity * (1 - discount)\"));\n * ```\n */\nexport const $expr = {\n  col,\n  lit,\n  mul,\n  add,\n  sub,\n  div,\n  raw,\n};\n"],"mappings":";;;;;;;AA0GA,SAAgB,mBAAmB,OAA2C;CAC5E,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAA2B,WAAW;AAElD;;;;;;;AAQA,SAAS,IAAI,QAAqC;CAChD,OAAO;EAAE,QAAQ;EAAU;CAAO;AACpC;;;;;;;AAQA,SAAS,IAAI,OAA4C;CACvD,OAAO;EAAE,QAAQ;EAAW;CAAM;AACpC;;;;;;;AAQA,SAAS,IAAI,GAAG,UAAyD;CACvE,OAAO;EAAE,QAAQ;EAAY,UAAU,SAAS,IAAI,kBAAkB;CAAE;AAC1E;;;;;;;AAQA,SAAS,IAAI,GAAG,UAAyD;CACvE,OAAO;EAAE,QAAQ;EAAO,UAAU,SAAS,IAAI,kBAAkB;CAAE;AACrE;;;;;;;;AASA,SAAS,IACP,MACA,OACsB;CACtB,OAAO;EACL,QAAQ;EACR,UAAU,CAAC,mBAAmB,IAAI,GAAG,mBAAmB,KAAK,CAAC;CAChE;AACF;;;;;;;;AASA,SAAS,IACP,MACA,OACsB;CACtB,OAAO;EACL,QAAQ;EACR,UAAU,CAAC,mBAAmB,IAAI,GAAG,mBAAmB,KAAK,CAAC;CAChE;AACF;;;;;;;;;;;;AAaA,SAAS,IAAI,YAAyC;CACpD,OAAO;EAAE,QAAQ;EAAO;CAAW;AACrC;;;;;;;;;AAUA,SAAgB,mBAAmB,OAAgD;CACjF,OAAO,OAAO,UAAU,WAAW,IAAI,KAAK,IAAI;AAClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,QAAQ;CACnB;CACA;CACA;CACA;CACA;CACA;CACA;AACF"}

package/esm/index.d.mts

@@ -16,7 +16,7 @@ import { ForeignKeyBuilder } from "./migration/foreign-key-builder.mjs";
 import { AlterSchema, ColumnMap, IndexEntry, Migration, MigrationAlterOptions, MigrationConstructor, MigrationContract, MigrationCreateOptions, OperationType, PendingOperation, UniqueEntry, migrate } from "./migration/migration.mjs";
 import { ChunkCallback, CursorPaginationOptions, CursorPaginationResult, DriverQuery, GroupByInput, HavingInput, JoinOptions, OrderDirection, PaginationOptions, PaginationResult, QueryBuilderContract, RawExpression, WhereCallback, WhereObject, WhereOperator } from "./contracts/query-builder.contract.mjs";
 import { SyncAdapterContract } from "./contracts/sync-adapter.contract.mjs";
-import { CreateDatabaseOptions, DriverContract, DriverEvent, DriverEventListener, DriverTransactionContract, DropDatabaseOptions, InsertResult, TransactionContext, UpdateOperations, UpdateResult } from "./contracts/database-driver.contract.mjs";
+import { CreateDatabaseOptions, DriverContract, DriverEvent, DriverEventListener, DriverTransactionContract, DropDatabaseOptions, InsertResult, RawQueryResult, TransactionContext, UpdateOperations, UpdateResult } from "./contracts/database-driver.contract.mjs";
 import { GenerateIdOptions, IdGeneratorContract } from "./contracts/database-id-generator.contract.mjs";
 import { RemoverContract, RemoverOptions, RemoverResult } from "./contracts/database-remover.contract.mjs";
 import { RestorerContract, RestorerOptions, RestorerResult } from "./contracts/database-restorer.contract.mjs";
@@ -35,6 +35,7 @@ import { DatabaseWriterValidationError } from "./validation/database-writer-vali
 import { BaseQueryRuleOptions, BaseUniqueRuleOptions, ExistsRuleOptions, UniqueRuleOptions } from "./validation/types.mjs";
 import { DatabaseWriter } from "./writer/database-writer.mjs";
 import { RelationLoader } from "./relations/relation-loader.mjs";
+import { $expr, ArithmeticExpression, ColumnExpression, ColumnExpressionInput, ColumnExpressionType, ColumnRefExpression, LiteralExpression, RawColumnExpression, isColumnExpression, toColumnExpression } from "./expressions/column-expressions.mjs";
 import { $agg, AggregateExpression, AggregateFunction, isAggregateExpression } from "./expressions/aggregate-expressions.mjs";
 import { MongoDriverOptions, Operation, PipelineStage } from "./drivers/mongodb/types.mjs";
 import { MongoDbDriver, isMongoDBDriverLoaded } from "./drivers/mongodb/mongodb-driver.mjs";
@@ -64,6 +65,6 @@ import { PostgresQueryBuilder } from "./drivers/postgres/postgres-query-builder.
 import { PostgresOperationType, PostgresParserOperation, PostgresParserOptions, PostgresQueryParser } from "./drivers/postgres/postgres-query-parser.mjs";
 import { PostgresSyncAdapter } from "./drivers/postgres/postgres-sync-adapter.mjs";
 import { MongoClientOptions, TransactionOptions } from "mongodb";
-export { $agg, AggregateExpression, AggregateFunction, AlterSchema, type BaseQueryRuleOptions, type BaseUniqueRuleOptions, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToOptions, BuildUpdateOperationsResult, type ChildModel, ChunkCallback, ColumnBuilder, ColumnDefinition, ColumnMap, ColumnType, ConnectionOptions, CreateDatabaseOptions, CreateDatabaseResult, CursorPaginationOptions, CursorPaginationResult, DEFAULT_MAX_SYNC_DEPTH, DataSource, DataSourceOptions, DataSourceRegistryEvent, DataSourceRegistryListener, DatabaseDirtyTracker, DatabaseDriver, DatabaseRemover, DatabaseRestorer, DatabaseWriter, DatabaseWriterValidationError, DefineModelOptions, DeleteStrategy, DetachedColumnBuilder, DriverContract, DriverEvent, DriverEventListener, DriverQuery, DriverTransactionContract, DropAllTablesResult, DropDatabaseOptions, type EmbedKey, type ExistsRuleOptions, ExportMigrationsSQLOptions, ForeignKeyBuilder, ForeignKeyDefinition, FullTextIndexOptions, GenerateIdOptions, GeoIndexOptions, type GlobalScopeDefinition, type GlobalScopeOptions, GroupByInput, HasMany, type HasManyOptions, HasOne, type HasOneOptions, HavingInput, IdGeneratorContract, IndexDefinition, IndexEntry, InsertResult, JoinOptions, type LoadedRelationResult, type LoadedRelationsMap, type LocalScopeCallback, Migration, MigrationAlterOptions, MigrationConstructor, MigrationContract, MigrationCreateOptions, MigrationDefaults, MigrationDriverContract, MigrationDriverFactory, type MigrationRecord, type MigrationResult, MigrationRunner, type MigrationRunnerOptions, type MigrationStatus, MissingDataSourceError, Model, ModelDefaultConfig, ModelDefaults, ModelEventListener, ModelEventName, ModelEvents, ModelRef, type ModelSchema, type ModelSnapshot, type ModelSyncConfig, type ModelSyncContract, ModelSyncOperation, type ModelSyncOperationContract, ModelTransformCallback, ModelType, type MongoClientOptions, MongoDbDriver, MongoDriverOptions, MongoIdGenerator, MongoMigrationDriver, MongoQueryBuilder, MongoSyncAdapter, NamingConvention, OnDeletedEventContext, Operation, OperationType, OrderDirection, PaginationOptions, PaginationResult, type PendingMigration, PendingOperation, PipelineStage, type PivotData, type PivotIds, PivotOperations, PostgresBlueprint, PostgresConnectionConfig, PostgresCopyOptions, PostgresDialect, PostgresDriver, PostgresIsolationLevel, PostgresMigrationDriver, PostgresNotification, PostgresOperation, PostgresOperationType, PostgresParserOperation, PostgresParserOptions, PostgresPoolConfig, PostgresQueryBuilder, PostgresQueryParser, PostgresQueryResult, PostgresSyncAdapter, PostgresTransactionOptions, PostgresWhereClause, QueryBuilderContract, RELATION_METADATA_KEY, RawExpression, RegisterModel, RegisterModelOptions, type RelationConstraintCallback, type RelationConstraints, RelationDefaults, type RelationDefinition, type RelationDefinitions, RelationHydrator, RelationLoader, type RelationType, RemoverContract, RemoverOptions, RemoverResult, RestorerContract, RestorerOptions, RestorerResult, RollbackMigrationsOptions, type RollbackOptions, type RunMigrationsOptions, type ScopeTiming, type SerializedRelation, SqlAggregateFunction, SqlDeleteOperation, SqlDialectContract, SqlGroupClause, SqlHavingClause, SqlInsertOperation, SqlJoinClause, SqlJoinType, SqlOrderClause, SqlQueryConfig, SqlQueryResult, SqlSelectClause, SqlUpdateOperation, SqlWhereOperation, SqlWhereType, StrictMode, SyncAdapterContract, type SyncConfig, type SyncContext, SyncContextManager, type SyncEventPayload, SyncInstruction, type SyncInstructionOptions, SyncManager, type SyncResult, type TableIndexInformation, TransactionContext, type TransactionOptions, TransactionRollbackError, UniqueEntry, type UniqueRuleOptions, UpdateOperations, UpdateResult, UuidStrategy, VectorIndexOptions, WhereCallback, WhereObject, WhereOperator, WriterContract, WriterOptions, WriterResult, arrayBigInt, arrayBoolean, arrayDate, arrayDecimal, arrayFloat, arrayInt, arrayJson, arrayText, arrayTimestamp, arrayUuid, bigInt, bigInteger, binary, blobCol, boolCol as bool, boolCol, char, cleanupModelsRegistery, connectToDatabase, createDatabase, createPivotOperations, dataSourceRegistry, databaseDataSourceContext, databaseTransactionContext, date, dateTime, decimal, defineModel, double, dropAllTables, enumCol, exportMigrationsSQL, float, freshMigrate, geometry, getAllModelsFromRegistry, getDatabaseDriver, getModelFromRegistry, globalModelEvents, int, integer, ipAddress, isAggregateExpression, isMongoDBDriverLoaded, json, lineString, listExecutedMigrations, longText, macAddress, mediumText, migrate, migrationRunner, modelSync, objectCol, onceConnected, onceDisconnected, point, polygon, registerModelInRegistry, removeModelFromRegistery, resolveModelClass, resolveModelName, rollbackMigrations, runMigrations, setCol, smallInt, smallInteger, string, text, time, timestamp, tinyInt, tinyInteger, transaction, tryResolveModelClass, ulid, useModelTransformer, uuid, vector, verifyRegisteredRelations, year };
+export { $agg, $expr, AggregateExpression, AggregateFunction, AlterSchema, ArithmeticExpression, type BaseQueryRuleOptions, type BaseUniqueRuleOptions, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToOptions, BuildUpdateOperationsResult, type ChildModel, ChunkCallback, ColumnBuilder, ColumnDefinition, ColumnExpression, ColumnExpressionInput, ColumnExpressionType, ColumnMap, ColumnRefExpression, ColumnType, ConnectionOptions, CreateDatabaseOptions, CreateDatabaseResult, CursorPaginationOptions, CursorPaginationResult, DEFAULT_MAX_SYNC_DEPTH, DataSource, DataSourceOptions, DataSourceRegistryEvent, DataSourceRegistryListener, DatabaseDirtyTracker, DatabaseDriver, DatabaseRemover, DatabaseRestorer, DatabaseWriter, DatabaseWriterValidationError, DefineModelOptions, DeleteStrategy, DetachedColumnBuilder, DriverContract, DriverEvent, DriverEventListener, DriverQuery, DriverTransactionContract, DropAllTablesResult, DropDatabaseOptions, type EmbedKey, type ExistsRuleOptions, ExportMigrationsSQLOptions, ForeignKeyBuilder, ForeignKeyDefinition, FullTextIndexOptions, GenerateIdOptions, GeoIndexOptions, type GlobalScopeDefinition, type GlobalScopeOptions, GroupByInput, HasMany, type HasManyOptions, HasOne, type HasOneOptions, HavingInput, IdGeneratorContract, IndexDefinition, IndexEntry, InsertResult, JoinOptions, LiteralExpression, type LoadedRelationResult, type LoadedRelationsMap, type LocalScopeCallback, Migration, MigrationAlterOptions, MigrationConstructor, MigrationContract, MigrationCreateOptions, MigrationDefaults, MigrationDriverContract, MigrationDriverFactory, type MigrationRecord, type MigrationResult, MigrationRunner, type MigrationRunnerOptions, type MigrationStatus, MissingDataSourceError, Model, ModelDefaultConfig, ModelDefaults, ModelEventListener, ModelEventName, ModelEvents, ModelRef, type ModelSchema, type ModelSnapshot, type ModelSyncConfig, type ModelSyncContract, ModelSyncOperation, type ModelSyncOperationContract, ModelTransformCallback, ModelType, type MongoClientOptions, MongoDbDriver, MongoDriverOptions, MongoIdGenerator, MongoMigrationDriver, MongoQueryBuilder, MongoSyncAdapter, NamingConvention, OnDeletedEventContext, Operation, OperationType, OrderDirection, PaginationOptions, PaginationResult, type PendingMigration, PendingOperation, PipelineStage, type PivotData, type PivotIds, PivotOperations, PostgresBlueprint, PostgresConnectionConfig, PostgresCopyOptions, PostgresDialect, PostgresDriver, PostgresIsolationLevel, PostgresMigrationDriver, PostgresNotification, PostgresOperation, PostgresOperationType, PostgresParserOperation, PostgresParserOptions, PostgresPoolConfig, PostgresQueryBuilder, PostgresQueryParser, PostgresQueryResult, PostgresSyncAdapter, PostgresTransactionOptions, PostgresWhereClause, QueryBuilderContract, RELATION_METADATA_KEY, RawColumnExpression, RawExpression, RawQueryResult, RegisterModel, RegisterModelOptions, type RelationConstraintCallback, type RelationConstraints, RelationDefaults, type RelationDefinition, type RelationDefinitions, RelationHydrator, RelationLoader, type RelationType, RemoverContract, RemoverOptions, RemoverResult, RestorerContract, RestorerOptions, RestorerResult, RollbackMigrationsOptions, type RollbackOptions, type RunMigrationsOptions, type ScopeTiming, type SerializedRelation, SqlAggregateFunction, SqlDeleteOperation, SqlDialectContract, SqlGroupClause, SqlHavingClause, SqlInsertOperation, SqlJoinClause, SqlJoinType, SqlOrderClause, SqlQueryConfig, SqlQueryResult, SqlSelectClause, SqlUpdateOperation, SqlWhereOperation, SqlWhereType, StrictMode, SyncAdapterContract, type SyncConfig, type SyncContext, SyncContextManager, type SyncEventPayload, SyncInstruction, type SyncInstructionOptions, SyncManager, type SyncResult, type TableIndexInformation, TransactionContext, type TransactionOptions, TransactionRollbackError, UniqueEntry, type UniqueRuleOptions, UpdateOperations, UpdateResult, UuidStrategy, VectorIndexOptions, WhereCallback, WhereObject, WhereOperator, WriterContract, WriterOptions, WriterResult, arrayBigInt, arrayBoolean, arrayDate, arrayDecimal, arrayFloat, arrayInt, arrayJson, arrayText, arrayTimestamp, arrayUuid, bigInt, bigInteger, binary, blobCol, boolCol as bool, boolCol, char, cleanupModelsRegistery, connectToDatabase, createDatabase, createPivotOperations, dataSourceRegistry, databaseDataSourceContext, databaseTransactionContext, date, dateTime, decimal, defineModel, double, dropAllTables, enumCol, exportMigrationsSQL, float, freshMigrate, geometry, getAllModelsFromRegistry, getDatabaseDriver, getModelFromRegistry, globalModelEvents, int, integer, ipAddress, isAggregateExpression, isColumnExpression, isMongoDBDriverLoaded, json, lineString, listExecutedMigrations, longText, macAddress, mediumText, migrate, migrationRunner, modelSync, objectCol, onceConnected, onceDisconnected, point, polygon, registerModelInRegistry, removeModelFromRegistery, resolveModelClass, resolveModelName, rollbackMigrations, runMigrations, setCol, smallInt, smallInteger, string, text, time, timestamp, tinyInt, tinyInteger, toColumnExpression, transaction, tryResolveModelClass, ulid, useModelTransformer, uuid, vector, verifyRegisteredRelations, year };
 import "./validation/plugins/database-rules-plugin.mjs";
 import "./validation/plugins/embed-validator-plugin.mjs";

package/esm/index.mjs

@@ -23,6 +23,7 @@ import { DatabaseRestorer } from "./restorer/database-restorer.mjs";
 import { Model } from "./model/model.mjs";
 import "./relations/index.mjs";
 import { $agg, isAggregateExpression } from "./expressions/aggregate-expressions.mjs";
+import { $expr, isColumnExpression, toColumnExpression } from "./expressions/column-expressions.mjs";
 import { MongoIdGenerator } from "./drivers/mongodb/mongodb-id-generator.mjs";
 import { MongoMigrationDriver } from "./drivers/mongodb/mongodb-migration-driver.mjs";
 import { MongoQueryBuilder } from "./drivers/mongodb/mongodb-query-builder.mjs";
@@ -50,4 +51,4 @@ import { createDatabase, dropAllTables } from "./operations/database.mjs";
 import { exportMigrationsSQL, freshMigrate, listExecutedMigrations, rollbackMigrations, runMigrations } from "./operations/migrations.mjs";
 import "./operations/index.mjs";
 
-export { $agg, BelongsTo, BelongsToMany, ColumnBuilder, DEFAULT_MAX_SYNC_DEPTH, DataSource, DatabaseDirtyTracker, DatabaseRemover, DatabaseRestorer, DatabaseWriter, DatabaseWriterValidationError, DetachedColumnBuilder, ForeignKeyBuilder, HasMany, HasOne, Migration, MigrationRunner, MissingDataSourceError, Model, ModelEvents, ModelSyncOperation, MongoDbDriver, MongoIdGenerator, MongoMigrationDriver, MongoQueryBuilder, MongoSyncAdapter, PivotOperations, PostgresBlueprint, PostgresDialect, PostgresDriver, PostgresMigrationDriver, PostgresQueryBuilder, PostgresQueryParser, PostgresSyncAdapter, RELATION_METADATA_KEY, RegisterModel, RelationHydrator, RelationLoader, SyncContextManager, SyncManager, TransactionRollbackError, arrayBigInt, arrayBoolean, arrayDate, arrayDecimal, arrayFloat, arrayInt, arrayJson, arrayText, arrayTimestamp, arrayUuid, bigInt, bigInteger, binary, blobCol, boolCol as bool, boolCol, char, cleanupModelsRegistery, connectToDatabase, createDatabase, createPivotOperations, dataSourceRegistry, databaseDataSourceContext, databaseTransactionContext, date, dateTime, decimal, defineModel, double, dropAllTables, enumCol, exportMigrationsSQL, float, freshMigrate, geometry, getAllModelsFromRegistry, getDatabaseDriver, getModelFromRegistry, globalModelEvents, int, integer, ipAddress, isAggregateExpression, isMongoDBDriverLoaded, json, lineString, listExecutedMigrations, longText, macAddress, mediumText, migrate, migrationRunner, modelSync, objectCol, onceConnected, onceDisconnected, point, polygon, registerModelInRegistry, removeModelFromRegistery, resolveModelClass, resolveModelName, rollbackMigrations, runMigrations, setCol, smallInt, smallInteger, string, text, time, timestamp, tinyInt, tinyInteger, transaction, tryResolveModelClass, ulid, useModelTransformer, uuid, vector, verifyRegisteredRelations, year };
+export { $agg, $expr, BelongsTo, BelongsToMany, ColumnBuilder, DEFAULT_MAX_SYNC_DEPTH, DataSource, DatabaseDirtyTracker, DatabaseRemover, DatabaseRestorer, DatabaseWriter, DatabaseWriterValidationError, DetachedColumnBuilder, ForeignKeyBuilder, HasMany, HasOne, Migration, MigrationRunner, MissingDataSourceError, Model, ModelEvents, ModelSyncOperation, MongoDbDriver, MongoIdGenerator, MongoMigrationDriver, MongoQueryBuilder, MongoSyncAdapter, PivotOperations, PostgresBlueprint, PostgresDialect, PostgresDriver, PostgresMigrationDriver, PostgresQueryBuilder, PostgresQueryParser, PostgresSyncAdapter, RELATION_METADATA_KEY, RegisterModel, RelationHydrator, RelationLoader, SyncContextManager, SyncManager, TransactionRollbackError, arrayBigInt, arrayBoolean, arrayDate, arrayDecimal, arrayFloat, arrayInt, arrayJson, arrayText, arrayTimestamp, arrayUuid, bigInt, bigInteger, binary, blobCol, boolCol as bool, boolCol, char, cleanupModelsRegistery, connectToDatabase, createDatabase, createPivotOperations, dataSourceRegistry, databaseDataSourceContext, databaseTransactionContext, date, dateTime, decimal, defineModel, double, dropAllTables, enumCol, exportMigrationsSQL, float, freshMigrate, geometry, getAllModelsFromRegistry, getDatabaseDriver, getModelFromRegistry, globalModelEvents, int, integer, ipAddress, isAggregateExpression, isColumnExpression, isMongoDBDriverLoaded, json, lineString, listExecutedMigrations, longText, macAddress, mediumText, migrate, migrationRunner, modelSync, objectCol, onceConnected, onceDisconnected, point, polygon, registerModelInRegistry, removeModelFromRegistery, resolveModelClass, resolveModelName, rollbackMigrations, runMigrations, setCol, smallInt, smallInteger, string, text, time, timestamp, tinyInt, tinyInteger, toColumnExpression, transaction, tryResolveModelClass, ulid, useModelTransformer, uuid, vector, verifyRegisteredRelations, year };

package/esm/model/methods/write-methods.d.mts

@@ -0,0 +1,29 @@
+//#region ../@warlock.js/cascade/src/model/methods/write-methods.d.ts
+/**
+ * Options for {@link createManyRecords} (and `Model.createMany`).
+ */
+type CreateManyOptions = {
+  /**
+   * Number of rows processed per chunk.
+   *
+   * @default 500 ({@link DEFAULT_CREATE_MANY_BATCH_SIZE})
+   */
+  batchSize?: number;
+  /**
+   * Route each chunk through the driver's native multi-row insert
+   * (`insertMany`) instead of per-row `save()`.
+   *
+   * **Tradeoff:** the bulk path is 10–100× faster for large arrays but
+   * SKIPS the per-row lifecycle: `saving` / `creating` / `created` / `saved`
+   * events, instance hooks, and sync operations are NOT emitted. Casts,
+   * timestamps, defaults and id-generation that the writer normally applies
+   * ARE still applied (the rows are prepped through the same writer pipeline),
+   * so persisted columns match the default path.
+   *
+   * @default false
+   */
+  bulk?: boolean;
+};
+//#endregion
+export { CreateManyOptions };
+//# sourceMappingURL=write-methods.d.mts.map

package/esm/model/methods/write-methods.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-methods.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/cascade/src/model/methods/write-methods.ts"],"mappings":";;;;KAmBY,iBAAA;;;;;;EAMV,SAAA;;;;;;;;;;;;;;EAeA,IAAI;AAAA"}