@uniqu/url 0.0.6 → 0.1.1

package/README.md

@@ -4,7 +4,7 @@
   <img src="../../logo.svg" alt="uniqu" height="80">
 </p>
 
-URL query string parser that produces the [Uniqu](../../README.md) canonical query format. Human-readable URL syntax with full filter expressions, sorting, pagination, and projection.
+URL query string parser and builder for the [Uniqu](../../README.md) canonical query format. Human-readable URL syntax with full filter expressions, sorting, pagination, projection, and aggregation.
 
 ## Install
 
@@ -151,11 +151,75 @@ Control keywords start with `$` and are separated from filter expressions:
 | `$limit` | `$top` | `$limit=20` | `{ $limit: 20 }` |
 | `$skip` | — | `$skip=40` | `{ $skip: 40 }` |
 | `$count` | — | `$count` | `{ $count: true }` |
+| `$groupBy` | — | `$groupBy=currency,region` | `{ $groupBy: ['currency', 'region'] }` |
 | `$with` | — | `$with=posts,author` | `{ $with: [{ name: 'posts', filter: {}, controls: {} }, ...] }` |
 | `$<custom>` | — | `$search=term` | `{ $search: 'term' }` |
 
 Prefix a field with `-` in `$select` to exclude it. When any exclusion is present, `$select` produces an object (`{ name: 1, password: 0 }`); otherwise it produces an array (`['name', 'email']`). Prefix with `-` in `$order` for descending sort.
 
+### Aggregate Functions in `$select`
+
+`$select` supports aggregate function calls using `fn(field)` syntax. An optional alias can be specified with `:alias`:
+
+```
+$select=sum(amount)                → [{ $fn: 'sum', $field: 'amount', $as: 'sum_amount' }]
+$select=sum(amount):total          → [{ $fn: 'sum', $field: 'amount', $as: 'total' }]
+$select=count(*)                   → [{ $fn: 'count', $field: '*', $as: 'count_star' }]
+$select=sum(amount),currency       → [{ $fn: 'sum', $field: 'amount', $as: 'sum_amount' }, 'currency']
+```
+
+When no alias is given, one is auto-generated as `{fn}_{field}` (with `*` becoming `star`).
+
+Supported functions: `sum`, `count`, `avg`, `min`, `max`, plus any custom function name — consumers validate supported functions.
+
+When aggregates are present, `$select` always uses the array form (even if `-` prefixed fields are mixed in).
+
+### Grouping (`$groupBy`)
+
+`$groupBy` declares which fields to group by. Comma-separated:
+
+```
+$groupBy=currency           → ['currency']
+$groupBy=currency,region    → ['currency', 'region']
+```
+
+#### Aggregation Example
+
+```
+$select=sum(amount):total,count(*),currency&$groupBy=currency&$sort=-total&$limit=10
+```
+
+Produces:
+
+```ts
+{
+  controls: {
+    $select: [
+      'currency',
+      { $fn: 'sum', $field: 'amount', $as: 'total' },
+      { $fn: 'count', $field: '*', $as: 'count_star' },
+    ],
+    $groupBy: ['currency'],
+    $sort: { total: -1 },
+    $limit: 10,
+  },
+  insights: Map {
+    'amount'   => Set { 'sum' },
+    '*'        => Set { 'count' },
+    'currency' => Set { '$select', '$groupBy' },
+    'total'    => Set { '$order' },
+  },
+}
+```
+
+Insights track aggregate functions with bare names (`'sum'`, `'count'`), distinct from `$`-prefixed control ops (`'$select'`, `'$groupBy'`).
+
+Aggregates and `$groupBy` work inside `$with` sub-queries too:
+
+```
+$with=orders($select=sum(total):revenue&$groupBy=status)
+```
+
 ### Relation Loading (`$with`)
 
 `$with` declares which relations to populate alongside the primary query. Relations are comma-separated:
@@ -279,7 +343,7 @@ Uniqu parses and types the `$with` declaration. The consumer (e.g. a database ad
 
 ## Insights
 
-Insights are computed **eagerly** during URL parsing — a `Map<string, Set<InsightOp>>` recording which fields are used and with which operators. This includes both filter operators and control usage (`$select`, `$order`).
+Insights are computed **eagerly** during URL parsing — a `Map<string, Set<InsightOp>>` recording which fields are used and with which operators. This includes filter operators, control usage (`$select`, `$order`, `$groupBy`), and aggregate functions (`sum`, `avg`, etc. — bare names without `$` prefix).
 
 For queries constructed as JSON objects (not parsed from URL), use `computeInsights()` from `@uniqu/core` for **lazy** computation.
 
@@ -340,12 +404,76 @@ Produces:
 }
 ```
 
+## URL Builder
+
+Build URL query strings from `Uniquery` objects — the inverse of `parseUrl`. Available as a separate entry point for optimal bundle size:
+
+```ts
+import { buildUrl } from '@uniqu/url/builder'
+```
+
+### Usage
+
+```ts
+const url = buildUrl({
+  filter: { status: 'active', age: { $gte: 18 } },
+  controls: {
+    $select: ['name', 'email'],
+    $sort: { createdAt: -1 },
+    $limit: 20,
+  },
+})
+// → "status=active&age>=18&$select=name,email&$sort=-createdAt&$limit=20"
+```
+
+### `buildUrl(query: Uniquery): string`
+
+Accepts a `Uniquery` object and returns a URL query string (without leading `?`).
+
+All features are supported:
+- Filter expressions (comparisons, `$and`/`$or`/`$not`, `$in`/`$nin`, `$exists`, `$regex`)
+- Controls (`$select`, `$sort`, `$limit`, `$skip`, `$count`, `$groupBy`, `$with`)
+- Aggregates in `$select` (`sum(amount):total`)
+- Nested `$with` sub-queries
+- Pass-through custom `$`-prefixed controls
+
+### Value serialization
+
+- Strings that look like numbers, booleans, or `null` are automatically quoted (`'25'`, `'true'`, `'null'`)
+- Strings with special characters (`&`, `^`, `=`, spaces, quotes) are quoted and escaped
+- Leading-zero numbers (`007`) stay as bare strings
+- `Date` values are serialized as quoted ISO strings
+- `RegExp` values are serialized as `/pattern/flags`
+
+### Round-tripping
+
+`buildUrl` produces output compatible with `parseUrl`:
+
+```ts
+import { parseUrl } from '@uniqu/url'
+import { buildUrl } from '@uniqu/url/builder'
+
+const query = { filter: { age: { $gte: 18 } }, controls: { $limit: 10 } }
+const url = buildUrl(query)
+const parsed = parseUrl(url)
+// parsed.filter → { age: { $gte: 18 } }
+// parsed.controls.$limit → 10
+```
+
+### Bundle optimization
+
+The builder is a separate entry point (`@uniqu/url/builder`) so that apps using only `buildUrl` don't pull in the lexer and parser code, and vice versa.
+
 ## API Reference
 
 ### `parseUrl(raw: string): UrlQuery`
 
 Parse a URL query string (without the leading `?`) into the uniqu format.
 
+### `buildUrl(query: Uniquery): string`
+
+Build a URL query string from a `Uniquery` object. Imported from `@uniqu/url/builder`.
+
 ### `UrlQuery`
 
 ```ts

package/dist/builder.cjs

@@ -0,0 +1,181 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _uniqu_core = require("@uniqu/core");
+
+//#region packages/url/src/builder.ts
+/**
+* Build a URL query string from a Uniquery object.
+* Produces output compatible with `parseUrl` from `@uniqu/url`.
+*
+* @param query - The canonical query to serialize
+* @returns URL query string without leading "?"
+*/ function buildUrl(query) {
+	const filterStr = query.filter ? serializeFilter(query.filter) : "";
+	const controlStr = query.controls ? serializeControls(query.controls) : "";
+	if (filterStr && controlStr) return filterStr + "&" + controlStr;
+	return filterStr || controlStr;
+}
+function serializeFilter(expr) {
+	if ("$and" in expr && expr.$and !== void 0) {
+		let result = "";
+		for (const child of expr.$and) {
+			const s = serializeFilter(child);
+			if (s) result = result ? result + "&" + s : s;
+		}
+		return result;
+	}
+	if ("$or" in expr && expr.$or !== void 0) {
+		let result = "";
+		for (const child of expr.$or) {
+			const s = serializeFilter(child);
+			if (s) result = result ? result + "^" + s : s;
+		}
+		return result;
+	}
+	if ("$not" in expr && expr.$not !== void 0) {
+		const inner = serializeFilter(expr.$not);
+		return inner ? `!(${inner})` : "";
+	}
+	let result = "";
+	for (const [field, value] of Object.entries(expr)) if ((0, _uniqu_core.isPrimitive)(value)) {
+		const part = `${field}=${serializeValue(value)}`;
+		result = result ? result + "&" + part : part;
+	} else for (const [op, opValue] of Object.entries(value)) {
+		const part = serializeComparison(field, op, opValue);
+		result = result ? result + "&" + part : part;
+	}
+	return result;
+}
+function serializeComparison(field, op, value) {
+	switch (op) {
+		case "$eq": return `${field}=${serializeValue(value)}`;
+		case "$ne": return `${field}!=${serializeValue(value)}`;
+		case "$gt": return `${field}>${serializeValue(value)}`;
+		case "$gte": return `${field}>=${serializeValue(value)}`;
+		case "$lt": return `${field}<${serializeValue(value)}`;
+		case "$lte": return `${field}<=${serializeValue(value)}`;
+		case "$regex": return `${field}~=${serializeValue(value)}`;
+		case "$in": {
+			let list = "";
+			for (const item of value) {
+				const s = serializeValue(item);
+				list = list ? list + "," + s : s;
+			}
+			return `${field}{${list}}`;
+		}
+		case "$nin": {
+			let list = "";
+			for (const item of value) {
+				const s = serializeValue(item);
+				list = list ? list + "," + s : s;
+			}
+			return `${field}!{${list}}`;
+		}
+		case "$exists": return value ? `$exists=${field}` : `$!exists=${field}`;
+		default: return `${field}${op}${serializeValue(value)}`;
+	}
+}
+function serializeValue(value) {
+	if (value === null) return "null";
+	if (value === true) return "true";
+	if (value === false) return "false";
+	if (typeof value === "number") return String(value);
+	if (value instanceof RegExp) return value.toString();
+	if (value instanceof Date) return `'${value.toISOString()}'`;
+	const str = String(value);
+	if (str === "null" || str === "true" || str === "false") return `'${str}'`;
+	if (/^\d/.test(str) && !isNaN(Number(str)) && !str.startsWith("0")) return `'${str}'`;
+	if (str.startsWith("/") && /\/[gimsuy]*$/.test(str)) return str;
+	if (/[&^=!<>~(){},\s'\\]/.test(str)) return `'${str.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+	return str;
+}
+const KNOWN_CONTROL_KEYS = new Set([
+	"$select",
+	"$groupBy",
+	"$having",
+	"$sort",
+	"$limit",
+	"$skip",
+	"$count",
+	"$with"
+]);
+function serializeControls(controls) {
+	let result = "";
+	if (controls.$select) {
+		let seg = "";
+		if (Array.isArray(controls.$select)) for (const entry of controls.$select) {
+			let s;
+			if (typeof entry === "string") s = entry;
+			else {
+				const agg = entry;
+				s = agg.$as ? `${agg.$fn}(${agg.$field}):${agg.$as}` : `${agg.$fn}(${agg.$field})`;
+			}
+			seg = seg ? seg + "," + s : s;
+		}
+		else for (const [field, val] of Object.entries(controls.$select)) {
+			const s = val === 0 ? `-${field}` : field;
+			seg = seg ? seg + "," + s : s;
+		}
+		if (seg) result = `$select=${seg}`;
+	}
+	if (controls.$groupBy?.length) {
+		let seg = "";
+		for (const field of controls.$groupBy) seg = seg ? seg + "," + field : field;
+		const part = `$groupBy=${seg}`;
+		result = result ? result + "&" + part : part;
+	}
+	if (controls.$having) {
+		const havingStr = serializeFilter(controls.$having);
+		if (havingStr) {
+			const part = "$and" in controls.$having ? `$having=(${havingStr})` : `$having=${havingStr}`;
+			result = result ? result + "&" + part : part;
+		}
+	}
+	if (controls.$sort) {
+		let seg = "";
+		for (const [field, dir] of Object.entries(controls.$sort)) {
+			const s = dir === -1 ? `-${field}` : field;
+			seg = seg ? seg + "," + s : s;
+		}
+		if (seg) {
+			const part = `$sort=${seg}`;
+			result = result ? result + "&" + part : part;
+		}
+	}
+	if (controls.$limit !== void 0) {
+		const part = `$limit=${controls.$limit}`;
+		result = result ? result + "&" + part : part;
+	}
+	if (controls.$skip !== void 0) {
+		const part = `$skip=${controls.$skip}`;
+		result = result ? result + "&" + part : part;
+	}
+	if (controls.$count) result = result ? result + "&$count" : "$count";
+	if (controls.$with) {
+		let seg = "";
+		for (const entry of controls.$with) {
+			let s;
+			if (typeof entry === "string") s = entry;
+			else {
+				const rel = entry;
+				const inner = buildUrl({
+					filter: rel.filter,
+					controls: rel.controls
+				});
+				s = inner ? `${rel.name}(${inner})` : rel.name;
+			}
+			seg = seg ? seg + "," + s : s;
+		}
+		if (seg) {
+			const part = `$with=${seg}`;
+			result = result ? result + "&" + part : part;
+		}
+	}
+	for (const [key, value] of Object.entries(controls)) if (key.startsWith("$") && !KNOWN_CONTROL_KEYS.has(key)) {
+		const part = value !== void 0 && value !== "" ? `${key}=${value}` : key;
+		result = result ? result + "&" + part : part;
+	}
+	return result;
+}
+
+//#endregion
+exports.buildUrl = buildUrl;

package/dist/builder.d.ts

@@ -0,0 +1,12 @@
+import { Uniquery } from '@uniqu/core';
+
+/**
+ * Build a URL query string from a Uniquery object.
+ * Produces output compatible with `parseUrl` from `@uniqu/url`.
+ *
+ * @param query - The canonical query to serialize
+ * @returns URL query string without leading "?"
+ */
+declare function buildUrl(query: Uniquery): string;
+
+export { buildUrl };

package/dist/builder.mjs

@@ -0,0 +1,180 @@
+import { isPrimitive } from "@uniqu/core";
+
+//#region packages/url/src/builder.ts
+/**
+* Build a URL query string from a Uniquery object.
+* Produces output compatible with `parseUrl` from `@uniqu/url`.
+*
+* @param query - The canonical query to serialize
+* @returns URL query string without leading "?"
+*/ function buildUrl(query) {
+	const filterStr = query.filter ? serializeFilter(query.filter) : "";
+	const controlStr = query.controls ? serializeControls(query.controls) : "";
+	if (filterStr && controlStr) return filterStr + "&" + controlStr;
+	return filterStr || controlStr;
+}
+function serializeFilter(expr) {
+	if ("$and" in expr && expr.$and !== void 0) {
+		let result = "";
+		for (const child of expr.$and) {
+			const s = serializeFilter(child);
+			if (s) result = result ? result + "&" + s : s;
+		}
+		return result;
+	}
+	if ("$or" in expr && expr.$or !== void 0) {
+		let result = "";
+		for (const child of expr.$or) {
+			const s = serializeFilter(child);
+			if (s) result = result ? result + "^" + s : s;
+		}
+		return result;
+	}
+	if ("$not" in expr && expr.$not !== void 0) {
+		const inner = serializeFilter(expr.$not);
+		return inner ? `!(${inner})` : "";
+	}
+	let result = "";
+	for (const [field, value] of Object.entries(expr)) if (isPrimitive(value)) {
+		const part = `${field}=${serializeValue(value)}`;
+		result = result ? result + "&" + part : part;
+	} else for (const [op, opValue] of Object.entries(value)) {
+		const part = serializeComparison(field, op, opValue);
+		result = result ? result + "&" + part : part;
+	}
+	return result;
+}
+function serializeComparison(field, op, value) {
+	switch (op) {
+		case "$eq": return `${field}=${serializeValue(value)}`;
+		case "$ne": return `${field}!=${serializeValue(value)}`;
+		case "$gt": return `${field}>${serializeValue(value)}`;
+		case "$gte": return `${field}>=${serializeValue(value)}`;
+		case "$lt": return `${field}<${serializeValue(value)}`;
+		case "$lte": return `${field}<=${serializeValue(value)}`;
+		case "$regex": return `${field}~=${serializeValue(value)}`;
+		case "$in": {
+			let list = "";
+			for (const item of value) {
+				const s = serializeValue(item);
+				list = list ? list + "," + s : s;
+			}
+			return `${field}{${list}}`;
+		}
+		case "$nin": {
+			let list = "";
+			for (const item of value) {
+				const s = serializeValue(item);
+				list = list ? list + "," + s : s;
+			}
+			return `${field}!{${list}}`;
+		}
+		case "$exists": return value ? `$exists=${field}` : `$!exists=${field}`;
+		default: return `${field}${op}${serializeValue(value)}`;
+	}
+}
+function serializeValue(value) {
+	if (value === null) return "null";
+	if (value === true) return "true";
+	if (value === false) return "false";
+	if (typeof value === "number") return String(value);
+	if (value instanceof RegExp) return value.toString();
+	if (value instanceof Date) return `'${value.toISOString()}'`;
+	const str = String(value);
+	if (str === "null" || str === "true" || str === "false") return `'${str}'`;
+	if (/^\d/.test(str) && !isNaN(Number(str)) && !str.startsWith("0")) return `'${str}'`;
+	if (str.startsWith("/") && /\/[gimsuy]*$/.test(str)) return str;
+	if (/[&^=!<>~(){},\s'\\]/.test(str)) return `'${str.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+	return str;
+}
+const KNOWN_CONTROL_KEYS = new Set([
+	"$select",
+	"$groupBy",
+	"$having",
+	"$sort",
+	"$limit",
+	"$skip",
+	"$count",
+	"$with"
+]);
+function serializeControls(controls) {
+	let result = "";
+	if (controls.$select) {
+		let seg = "";
+		if (Array.isArray(controls.$select)) for (const entry of controls.$select) {
+			let s;
+			if (typeof entry === "string") s = entry;
+			else {
+				const agg = entry;
+				s = agg.$as ? `${agg.$fn}(${agg.$field}):${agg.$as}` : `${agg.$fn}(${agg.$field})`;
+			}
+			seg = seg ? seg + "," + s : s;
+		}
+		else for (const [field, val] of Object.entries(controls.$select)) {
+			const s = val === 0 ? `-${field}` : field;
+			seg = seg ? seg + "," + s : s;
+		}
+		if (seg) result = `$select=${seg}`;
+	}
+	if (controls.$groupBy?.length) {
+		let seg = "";
+		for (const field of controls.$groupBy) seg = seg ? seg + "," + field : field;
+		const part = `$groupBy=${seg}`;
+		result = result ? result + "&" + part : part;
+	}
+	if (controls.$having) {
+		const havingStr = serializeFilter(controls.$having);
+		if (havingStr) {
+			const part = "$and" in controls.$having ? `$having=(${havingStr})` : `$having=${havingStr}`;
+			result = result ? result + "&" + part : part;
+		}
+	}
+	if (controls.$sort) {
+		let seg = "";
+		for (const [field, dir] of Object.entries(controls.$sort)) {
+			const s = dir === -1 ? `-${field}` : field;
+			seg = seg ? seg + "," + s : s;
+		}
+		if (seg) {
+			const part = `$sort=${seg}`;
+			result = result ? result + "&" + part : part;
+		}
+	}
+	if (controls.$limit !== void 0) {
+		const part = `$limit=${controls.$limit}`;
+		result = result ? result + "&" + part : part;
+	}
+	if (controls.$skip !== void 0) {
+		const part = `$skip=${controls.$skip}`;
+		result = result ? result + "&" + part : part;
+	}
+	if (controls.$count) result = result ? result + "&$count" : "$count";
+	if (controls.$with) {
+		let seg = "";
+		for (const entry of controls.$with) {
+			let s;
+			if (typeof entry === "string") s = entry;
+			else {
+				const rel = entry;
+				const inner = buildUrl({
+					filter: rel.filter,
+					controls: rel.controls
+				});
+				s = inner ? `${rel.name}(${inner})` : rel.name;
+			}
+			seg = seg ? seg + "," + s : s;
+		}
+		if (seg) {
+			const part = `$with=${seg}`;
+			result = result ? result + "&" + part : part;
+		}
+	}
+	for (const [key, value] of Object.entries(controls)) if (key.startsWith("$") && !KNOWN_CONTROL_KEYS.has(key)) {
+		const part = value !== void 0 && value !== "" ? `${key}=${value}` : key;
+		result = result ? result + "&" + part : part;
+	}
+	return result;
+}
+
+//#endregion
+export { buildUrl };

package/dist/index.cjs

@@ -289,7 +289,7 @@ var Parser = class {
 	}
 };
 function unescapeString(str) {
-	return str.replace(/(^'|'$)/gu, "");
+	return str.replace(/(^'|'$)/gu, "").replace(/\\(.)/gu, "$1");
 }
 /**
 * Attempt to merge an array of simple nodes produced by `parseTerm`.
@@ -305,14 +305,15 @@ function unescapeString(str) {
 		for (const [key, val] of Object.entries(node)) if (key in currentMerge) {
 			const currentVal = currentMerge[key];
 			const currentOps = (0, _uniqu_core.isPrimitive)(currentVal) ? ["$eq"] : Object.keys(currentVal);
-			const otherOps = (0, _uniqu_core.isPrimitive)(val) ? /* @__PURE__ */ new Set("$eq") : new Set(Object.keys(val));
+			const otherOps = (0, _uniqu_core.isPrimitive)(val) ? new Set(["$eq"]) : new Set(Object.keys(val));
 			if (currentOps.some((op) => otherOps.has(op))) {
 				merged.push(currentMerge);
 				currentMerge = {};
 			} else {
-				currentMerge[key] = {};
-				for (const op of currentOps) currentMerge[key][op] = (0, _uniqu_core.isPrimitive)(currentVal) ? currentVal : currentVal[op];
-				for (const op of Array.from(otherOps)) currentMerge[key][op] = (0, _uniqu_core.isPrimitive)(val) ? val : val[op];
+				const m = {};
+				for (const op of currentOps) m[op] = (0, _uniqu_core.isPrimitive)(currentVal) ? currentVal : currentVal[op];
+				for (const op of otherOps) m[op] = (0, _uniqu_core.isPrimitive)(val) ? val : val[op];
+				currentMerge[key] = m;
 			}
 		} else currentMerge[key] = val;
 	}
@@ -350,9 +351,9 @@ function buildExists(fields, positive) {
 	let filter = {};
 	let parser;
 	if (exprParts.length) {
-		parser = new Parser(lex(exprParts.join("&")));
-		filter = parser.parseExpression();
-		parser.expectEof();
+		const parsed = parseFilterExpr(exprParts.join("&"));
+		parser = parsed.parser;
+		filter = parsed.expr;
 	} else parser = new Parser([]);
 	for (const [field, op] of controlInsights) parser.captureInsight(field, op);
 	return {
@@ -374,6 +375,15 @@ function buildExists(fields, positive) {
 	parts.push(str.slice(start));
 	return parts;
 }
+/** Lex + parse a raw filter expression string. */ function parseFilterExpr(raw) {
+	const parser = new Parser(lex(raw));
+	const expr = parser.parseExpression();
+	parser.expectEof();
+	return {
+		expr,
+		parser
+	};
+}
 /** Parse a single `$with` segment like `posts` or `posts($sort=-createdAt&status=active)`. */ function parseWithSegment(seg) {
 	if (!seg) return null;
 	const parenIdx = seg.indexOf("(");
@@ -403,14 +413,16 @@ function handleControls(parts) {
 	const controls = {};
 	const controlInsights = [];
 	for (const raw of parts) {
-		const [key, ...rest] = raw.split("=");
-		const value = rest.join("=");
+		const eqIdx = raw.indexOf("=");
+		const key = eqIdx === -1 ? raw : raw.slice(0, eqIdx);
+		const value = eqIdx === -1 ? "" : raw.slice(eqIdx + 1);
 		switch (key) {
 			case "$with": {
 				var _controls;
 				if (!value) break;
 				(_controls = controls).$with ?? (_controls.$with = []);
-				const seen = new Set(controls.$with.map((r) => r.name));
+				const seen = /* @__PURE__ */ new Set();
+				for (const r of controls.$with) seen.add(typeof r === "string" ? r : r.name);
 				for (const seg of splitTopLevel(value, ",")) {
 					const rel = parseWithSegment(seg);
 					if (!rel || seen.has(rel.name)) continue;
@@ -425,35 +437,50 @@ function handleControls(parts) {
 				break;
 			}
 			case "$select": {
+				const items = value.split(",");
 				let hasExclusion = false;
-				const fields = [];
-				value.split(",").forEach((f) => {
-					if (!f) return;
-					if (f.startsWith("-")) {
-						hasExclusion = true;
-						fields.push({
-							name: f.slice(1),
-							include: false
+				let hasAggregate = false;
+				for (const f of items) {
+					if (!f) continue;
+					if (f.startsWith("-")) hasExclusion = true;
+					else if (/^\w+\(/.test(f)) hasAggregate = true;
+				}
+				if (hasAggregate || !hasExclusion) {
+					const arr = Array.isArray(controls.$select) ? controls.$select : [];
+					for (const f of items) {
+						if (!f || /^\w+\(/.test(f)) continue;
+						arr.push(f);
+						controlInsights.push([f, "$select"]);
+					}
+					for (const f of items) {
+						if (!f) continue;
+						const aggMatch = /^(\w+)\((\*|[\w.]+)\)(?::([\w.]+))?$/.exec(f);
+						if (!aggMatch) continue;
+						const fn = aggMatch[1];
+						const field = aggMatch[2];
+						const alias = aggMatch[3] ?? (field === "*" ? `${fn}_star` : `${fn}_${field}`);
+						arr.push({
+							$fn: fn,
+							$field: field,
+							$as: alias
 						});
-					} else fields.push({
-						name: f,
-						include: true
-					});
-				});
-				if (hasExclusion) {
-					const obj = controls.$select ?? {};
-					for (const { name, include } of fields) {
-						obj[name] = include ? 1 : 0;
-						controlInsights.push([name, "$select"]);
+						controlInsights.push([field, fn]);
 					}
-					controls.$select = obj;
+					controls.$select = arr;
 				} else {
-					const arr = Array.isArray(controls.$select) ? controls.$select : [];
-					for (const { name } of fields) {
-						arr.push(name);
-						controlInsights.push([name, "$select"]);
+					const obj = controls.$select ?? {};
+					for (const f of items) {
+						if (!f) continue;
+						if (f.startsWith("-")) {
+							const name = f.slice(1);
+							obj[name] = 0;
+							controlInsights.push([name, "$select"]);
+						} else {
+							obj[f] = 1;
+							controlInsights.push([f, "$select"]);
+						}
 					}
-					controls.$select = arr;
+					controls.$select = obj;
 				}
 				break;
 			}
@@ -461,13 +488,36 @@ function handleControls(parts) {
 			case "$order":
 				var _controls1;
 				(_controls1 = controls).$sort ?? (_controls1.$sort = {});
-				value.split(",").forEach((f) => {
-					if (!f) return;
-					controlInsights.push([f.replace(/^-/, ""), "$order"]);
-					if (f.startsWith("-")) controls.$sort[f.slice(1)] = -1;
-					else controls.$sort[f] = 1;
-				});
+				for (const f of value.split(",")) {
+					if (!f) continue;
+					if (f.startsWith("-")) {
+						const name = f.slice(1);
+						controls.$sort[name] = -1;
+						controlInsights.push([name, "$order"]);
+					} else {
+						controls.$sort[f] = 1;
+						controlInsights.push([f, "$order"]);
+					}
+				}
 				break;
+			case "$groupBy":
+				var _controls2;
+				if (!value) break;
+				(_controls2 = controls).$groupBy ?? (_controls2.$groupBy = []);
+				for (const f of value.split(",")) {
+					if (!f) continue;
+					controls.$groupBy.push(f);
+					controlInsights.push([f, "$groupBy"]);
+				}
+				break;
+			case "$having": {
+				if (!value) break;
+				const { expr, parser: hp } = parseFilterExpr(value);
+				if (controls.$having) controls.$having = { $and: [controls.$having, expr] };
+				else controls.$having = expr;
+				for (const [field] of hp.getInsights()) controlInsights.push([field, "$having"]);
+				break;
+			}
 			case "$limit":
 			case "$top":
 				controls.$limit = Number(value);

package/dist/index.mjs

@@ -288,7 +288,7 @@ var Parser = class {
 	}
 };
 function unescapeString(str) {
-	return str.replace(/(^'|'$)/gu, "");
+	return str.replace(/(^'|'$)/gu, "").replace(/\\(.)/gu, "$1");
 }
 /**
 * Attempt to merge an array of simple nodes produced by `parseTerm`.
@@ -304,14 +304,15 @@ function unescapeString(str) {
 		for (const [key, val] of Object.entries(node)) if (key in currentMerge) {
 			const currentVal = currentMerge[key];
 			const currentOps = isPrimitive(currentVal) ? ["$eq"] : Object.keys(currentVal);
-			const otherOps = isPrimitive(val) ? /* @__PURE__ */ new Set("$eq") : new Set(Object.keys(val));
+			const otherOps = isPrimitive(val) ? new Set(["$eq"]) : new Set(Object.keys(val));
 			if (currentOps.some((op) => otherOps.has(op))) {
 				merged.push(currentMerge);
 				currentMerge = {};
 			} else {
-				currentMerge[key] = {};
-				for (const op of currentOps) currentMerge[key][op] = isPrimitive(currentVal) ? currentVal : currentVal[op];
-				for (const op of Array.from(otherOps)) currentMerge[key][op] = isPrimitive(val) ? val : val[op];
+				const m = {};
+				for (const op of currentOps) m[op] = isPrimitive(currentVal) ? currentVal : currentVal[op];
+				for (const op of otherOps) m[op] = isPrimitive(val) ? val : val[op];
+				currentMerge[key] = m;
 			}
 		} else currentMerge[key] = val;
 	}
@@ -349,9 +350,9 @@ function buildExists(fields, positive) {
 	let filter = {};
 	let parser;
 	if (exprParts.length) {
-		parser = new Parser(lex(exprParts.join("&")));
-		filter = parser.parseExpression();
-		parser.expectEof();
+		const parsed = parseFilterExpr(exprParts.join("&"));
+		parser = parsed.parser;
+		filter = parsed.expr;
 	} else parser = new Parser([]);
 	for (const [field, op] of controlInsights) parser.captureInsight(field, op);
 	return {
@@ -373,6 +374,15 @@ function buildExists(fields, positive) {
 	parts.push(str.slice(start));
 	return parts;
 }
+/** Lex + parse a raw filter expression string. */ function parseFilterExpr(raw) {
+	const parser = new Parser(lex(raw));
+	const expr = parser.parseExpression();
+	parser.expectEof();
+	return {
+		expr,
+		parser
+	};
+}
 /** Parse a single `$with` segment like `posts` or `posts($sort=-createdAt&status=active)`. */ function parseWithSegment(seg) {
 	if (!seg) return null;
 	const parenIdx = seg.indexOf("(");
@@ -402,14 +412,16 @@ function handleControls(parts) {
 	const controls = {};
 	const controlInsights = [];
 	for (const raw of parts) {
-		const [key, ...rest] = raw.split("=");
-		const value = rest.join("=");
+		const eqIdx = raw.indexOf("=");
+		const key = eqIdx === -1 ? raw : raw.slice(0, eqIdx);
+		const value = eqIdx === -1 ? "" : raw.slice(eqIdx + 1);
 		switch (key) {
 			case "$with": {
 				var _controls;
 				if (!value) break;
 				(_controls = controls).$with ?? (_controls.$with = []);
-				const seen = new Set(controls.$with.map((r) => r.name));
+				const seen = /* @__PURE__ */ new Set();
+				for (const r of controls.$with) seen.add(typeof r === "string" ? r : r.name);
 				for (const seg of splitTopLevel(value, ",")) {
 					const rel = parseWithSegment(seg);
 					if (!rel || seen.has(rel.name)) continue;
@@ -424,35 +436,50 @@ function handleControls(parts) {
 				break;
 			}
 			case "$select": {
+				const items = value.split(",");
 				let hasExclusion = false;
-				const fields = [];
-				value.split(",").forEach((f) => {
-					if (!f) return;
-					if (f.startsWith("-")) {
-						hasExclusion = true;
-						fields.push({
-							name: f.slice(1),
-							include: false
+				let hasAggregate = false;
+				for (const f of items) {
+					if (!f) continue;
+					if (f.startsWith("-")) hasExclusion = true;
+					else if (/^\w+\(/.test(f)) hasAggregate = true;
+				}
+				if (hasAggregate || !hasExclusion) {
+					const arr = Array.isArray(controls.$select) ? controls.$select : [];
+					for (const f of items) {
+						if (!f || /^\w+\(/.test(f)) continue;
+						arr.push(f);
+						controlInsights.push([f, "$select"]);
+					}
+					for (const f of items) {
+						if (!f) continue;
+						const aggMatch = /^(\w+)\((\*|[\w.]+)\)(?::([\w.]+))?$/.exec(f);
+						if (!aggMatch) continue;
+						const fn = aggMatch[1];
+						const field = aggMatch[2];
+						const alias = aggMatch[3] ?? (field === "*" ? `${fn}_star` : `${fn}_${field}`);
+						arr.push({
+							$fn: fn,
+							$field: field,
+							$as: alias
 						});
-					} else fields.push({
-						name: f,
-						include: true
-					});
-				});
-				if (hasExclusion) {
-					const obj = controls.$select ?? {};
-					for (const { name, include } of fields) {
-						obj[name] = include ? 1 : 0;
-						controlInsights.push([name, "$select"]);
+						controlInsights.push([field, fn]);
 					}
-					controls.$select = obj;
+					controls.$select = arr;
 				} else {
-					const arr = Array.isArray(controls.$select) ? controls.$select : [];
-					for (const { name } of fields) {
-						arr.push(name);
-						controlInsights.push([name, "$select"]);
+					const obj = controls.$select ?? {};
+					for (const f of items) {
+						if (!f) continue;
+						if (f.startsWith("-")) {
+							const name = f.slice(1);
+							obj[name] = 0;
+							controlInsights.push([name, "$select"]);
+						} else {
+							obj[f] = 1;
+							controlInsights.push([f, "$select"]);
+						}
 					}
-					controls.$select = arr;
+					controls.$select = obj;
 				}
 				break;
 			}
@@ -460,13 +487,36 @@ function handleControls(parts) {
 			case "$order":
 				var _controls1;
 				(_controls1 = controls).$sort ?? (_controls1.$sort = {});
-				value.split(",").forEach((f) => {
-					if (!f) return;
-					controlInsights.push([f.replace(/^-/, ""), "$order"]);
-					if (f.startsWith("-")) controls.$sort[f.slice(1)] = -1;
-					else controls.$sort[f] = 1;
-				});
+				for (const f of value.split(",")) {
+					if (!f) continue;
+					if (f.startsWith("-")) {
+						const name = f.slice(1);
+						controls.$sort[name] = -1;
+						controlInsights.push([name, "$order"]);
+					} else {
+						controls.$sort[f] = 1;
+						controlInsights.push([f, "$order"]);
+					}
+				}
 				break;
+			case "$groupBy":
+				var _controls2;
+				if (!value) break;
+				(_controls2 = controls).$groupBy ?? (_controls2.$groupBy = []);
+				for (const f of value.split(",")) {
+					if (!f) continue;
+					controls.$groupBy.push(f);
+					controlInsights.push([f, "$groupBy"]);
+				}
+				break;
+			case "$having": {
+				if (!value) break;
+				const { expr, parser: hp } = parseFilterExpr(value);
+				if (controls.$having) controls.$having = { $and: [controls.$having, expr] };
+				else controls.$having = expr;
+				for (const [field] of hp.getInsights()) controlInsights.push([field, "$having"]);
+				break;
+			}
 			case "$limit":
 			case "$top":
 				controls.$limit = Number(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqu/url",
-  "version": "0.0.6",
+  "version": "0.1.1",
   "description": "URL query string parser producing the Uniqu canonical query format",
   "license": "MIT",
   "author": "Artem Maltsev",
@@ -22,13 +22,30 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
+    "./builder": {
+      "types": "./dist/builder.d.ts",
+      "import": "./dist/builder.mjs",
+      "require": "./dist/builder.cjs"
+    },
     "./package.json": "./package.json"
   },
+  "build": [
+    {
+      "entries": [
+        "src/index.ts"
+      ]
+    },
+    {
+      "entries": [
+        "src/builder.ts"
+      ]
+    }
+  ],
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@uniqu/core": "^0.0.6"
+    "@uniqu/core": "^0.1.1"
   },
   "scripts": {
     "pub": "pnpm publish --access public",