@uniqu/url 0.0.2 → 0.0.4

package/README.md

@@ -151,10 +151,132 @@ 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 }` |
+| `$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.
 
+### Relation Loading (`$with`)
+
+`$with` declares which relations to populate alongside the primary query. Relations are comma-separated:
+
+```
+$with=posts,comments,author
+```
+
+#### Per-Relation Sub-Queries
+
+Each relation can include an inline sub-query in parentheses. Inside the parens, the full query syntax applies — filters, controls, and nested `$with`:
+
+```
+$with=posts($sort=-createdAt&$limit=5&status=published)
+```
+
+This parses to:
+
+```ts
+controls.$with = [
+  {
+    name: 'posts',
+    filter: { status: 'published' },
+    controls: { $sort: { createdAt: -1 }, $limit: 5 },
+  },
+]
+```
+
+Each relation is a full `Uniquery` sub-query with its own `filter`, `controls`, and `insights`. All controls are supported inside parens: `$sort`, `$limit`, `$skip`, `$select`, `$count`, and nested `$with`.
+
+#### Nested Relations
+
+`$with` is recursive — relations can load their own sub-relations to any depth:
+
+```
+$with=posts($sort=-createdAt&$limit=5&$with=comments($limit=10&$with=author),tags)
+```
+
+This produces a tree:
+
+```ts
+controls.$with = [
+  {
+    name: 'posts',
+    filter: {},
+    controls: {
+      $sort: { createdAt: -1 },
+      $limit: 5,
+      $with: [
+        {
+          name: 'comments',
+          filter: {},
+          controls: {
+            $limit: 10,
+            $with: [{ name: 'author', filter: {}, controls: {} }],
+          },
+        },
+        { name: 'tags', filter: {}, controls: {} },
+      ],
+    },
+  },
+]
+```
+
+Inside each level of parens, `&` separates parameters and `,` separates sibling relations within `$with=`. The parser handles balanced parentheses correctly across nesting levels.
+
+#### Combined Example
+
+```
+status=active&$with=posts($sort=-createdAt&$limit=5&$select=title,body&status=published),author
+```
+
+Produces:
+
+```ts
+{
+  filter: { status: 'active' },
+  controls: {
+    $with: [
+      {
+        name: 'posts',
+        filter: { status: 'published' },
+        controls: {
+          $sort: { createdAt: -1 },
+          $limit: 5,
+          $select: ['title', 'body'],
+        },
+        insights: Map { 'status' => Set { '$eq' }, ... },
+      },
+      { name: 'author', filter: {}, controls: {} },
+    ],
+  },
+  insights: Map {
+    'status' => Set { '$eq' },
+    'posts'  => Set { '$with' },
+    'posts.status' => Set { '$eq' },
+    'author' => Set { '$with' },
+  },
+}
+```
+
+Each `$with` relation carries its own scoped `insights`, and nested insights bubble up to the root with dot-notation prefixed field names.
+
+#### Edge Cases
+
+| Case | Behavior |
+|------|----------|
+| `$with=posts,posts` | Deduplicated — one entry |
+| `$with=` or `$with` | No relations (empty/omitted) |
+| `$with=posts()` | Empty parens — same as `$with=posts` |
+| Unknown relation names | Recorded as-is — consumer validates against its schema |
+
+#### Consumer Responsibility
+
+Uniqu parses and types the `$with` declaration. The consumer (e.g. a database adapter) is responsible for:
+
+- **Execution strategy** — JOINs, subqueries, or separate queries
+- **Relation validation** — checking that relation names exist on the entity
+- **Circular reference detection** — preventing infinite `$with` chains
+- **Depth limits** — restricting nesting depth for performance
+
 ## 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`).
@@ -168,6 +290,7 @@ $select=firstName,-client.ssn
 &$order=-createdAt,score
 &$limit=50&$skip=10
 &$count
+&$with=posts($sort=-date&$limit=5&status=published),profile
 &$exists=client.phone
 &$!exists=deletedAt
 &age>=18&age<=30
@@ -205,6 +328,14 @@ Produces:
     $limit: 50,
     $skip: 10,
     $count: true,
+    $with: [
+      {
+        name: 'posts',
+        filter: { status: 'published' },
+        controls: { $sort: { date: -1 }, $limit: 5 },
+      },
+      { name: 'profile', filter: {}, controls: {} },
+    ],
   },
 }
 ```

package/dist/index.cjs

@@ -338,7 +338,7 @@ function buildExists(fields, positive) {
 *
 * @param raw - Raw query string without the leading "?"
 */ function parseUrl(raw) {
-	const parts = raw.split("&");
+	const parts = splitTopLevel(raw, "&");
 	const controlParts = [];
 	const exprParts = [];
 	for (const _p of parts) {
@@ -346,7 +346,7 @@ function buildExists(fields, positive) {
 		if (/^\$[A-Za-z0-9_!]+/.test(p) && !p.startsWith("$exists=") && !p.startsWith("$!exists=")) controlParts.push(p);
 		else if (p.length) exprParts.push(p);
 	}
-	const { controls, selectInsights, orderInsights } = handleControls(controlParts);
+	const { controls, controlInsights } = handleControls(controlParts);
 	let filter = {};
 	let parser;
 	if (exprParts.length) {
@@ -354,22 +354,76 @@ function buildExists(fields, positive) {
 		filter = parser.parseExpression();
 		parser.expectEof();
 	} else parser = new Parser([]);
-	for (const f of selectInsights) parser.captureInsight(f, "$select");
-	for (const f of orderInsights) parser.captureInsight(f, "$order");
+	for (const [field, op] of controlInsights) parser.captureInsight(field, op);
 	return {
 		filter,
 		controls,
 		insights: parser.getInsights()
 	};
 }
+/** Split a string by `sep` at the top level (ignoring separators inside balanced parentheses). */ function splitTopLevel(str, sep) {
+	const parts = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < str.length; i++) if (str[i] === "(") depth++;
+	else if (str[i] === ")") depth--;
+	else if (str[i] === sep && depth === 0) {
+		parts.push(str.slice(start, i));
+		start = i + 1;
+	}
+	parts.push(str.slice(start));
+	return parts;
+}
+/** Parse a single `$with` segment like `posts` or `posts($sort=-createdAt&status=active)`. */ function parseWithSegment(seg) {
+	if (!seg) return null;
+	const parenIdx = seg.indexOf("(");
+	if (parenIdx === -1) return {
+		name: seg,
+		filter: {},
+		controls: {}
+	};
+	const name = seg.slice(0, parenIdx);
+	if (!name) return null;
+	const inner = seg.slice(parenIdx + 1, -1);
+	if (!inner) return {
+		name,
+		filter: {},
+		controls: {}
+	};
+	const sub = parseUrl(inner);
+	const rel = {
+		name,
+		filter: sub.filter,
+		controls: sub.controls
+	};
+	if (sub.insights.size) rel.insights = sub.insights;
+	return rel;
+}
 function handleControls(parts) {
 	const controls = {};
-	const selectInsights = /* @__PURE__ */ new Set();
-	const orderInsights = /* @__PURE__ */ new Set();
+	const controlInsights = [];
 	for (const raw of parts) {
 		const [key, ...rest] = raw.split("=");
-		const value = decodeURIComponent(rest.join("="));
+		const value = rest.join("=");
 		switch (key) {
+			case "$with": {
+				var _controls;
+				if (!value) break;
+				(_controls = controls).$with ?? (_controls.$with = []);
+				const seen = new Set(controls.$with.map((r) => r.name));
+				for (const seg of splitTopLevel(value, ",")) {
+					const rel = parseWithSegment(seg);
+					if (!rel || seen.has(rel.name)) continue;
+					seen.add(rel.name);
+					controls.$with.push(rel);
+					controlInsights.push([rel.name, "$with"]);
+					if (rel.insights) for (const [field, ops] of rel.insights) {
+						const prefixed = `${rel.name}.${field}`;
+						for (const op of ops) controlInsights.push([prefixed, op]);
+					}
+				}
+				break;
+			}
 			case "$select": {
 				let hasExclusion = false;
 				const fields = [];
@@ -390,14 +444,14 @@ function handleControls(parts) {
 					const obj = controls.$select ?? {};
 					for (const { name, include } of fields) {
 						obj[name] = include ? 1 : 0;
-						selectInsights.add(name);
+						controlInsights.push([name, "$select"]);
 					}
 					controls.$select = obj;
 				} else {
 					const arr = Array.isArray(controls.$select) ? controls.$select : [];
 					for (const { name } of fields) {
 						arr.push(name);
-						selectInsights.add(name);
+						controlInsights.push([name, "$select"]);
 					}
 					controls.$select = arr;
 				}
@@ -405,11 +459,11 @@ function handleControls(parts) {
 			}
 			case "$sort":
 			case "$order":
-				var _controls;
-				(_controls = controls).$sort ?? (_controls.$sort = {});
+				var _controls1;
+				(_controls1 = controls).$sort ?? (_controls1.$sort = {});
 				value.split(",").forEach((f) => {
 					if (!f) return;
-					orderInsights.add(f.replace(/^-/, ""));
+					controlInsights.push([f.replace(/^-/, ""), "$order"]);
 					if (f.startsWith("-")) controls.$sort[f.slice(1)] = -1;
 					else controls.$sort[f] = 1;
 				});
@@ -429,8 +483,7 @@ function handleControls(parts) {
 	}
 	return {
 		controls,
-		selectInsights,
-		orderInsights
+		controlInsights
 	};
 }
 

package/dist/index.mjs

@@ -337,7 +337,7 @@ function buildExists(fields, positive) {
 *
 * @param raw - Raw query string without the leading "?"
 */ function parseUrl(raw) {
-	const parts = raw.split("&");
+	const parts = splitTopLevel(raw, "&");
 	const controlParts = [];
 	const exprParts = [];
 	for (const _p of parts) {
@@ -345,7 +345,7 @@ function buildExists(fields, positive) {
 		if (/^\$[A-Za-z0-9_!]+/.test(p) && !p.startsWith("$exists=") && !p.startsWith("$!exists=")) controlParts.push(p);
 		else if (p.length) exprParts.push(p);
 	}
-	const { controls, selectInsights, orderInsights } = handleControls(controlParts);
+	const { controls, controlInsights } = handleControls(controlParts);
 	let filter = {};
 	let parser;
 	if (exprParts.length) {
@@ -353,22 +353,76 @@ function buildExists(fields, positive) {
 		filter = parser.parseExpression();
 		parser.expectEof();
 	} else parser = new Parser([]);
-	for (const f of selectInsights) parser.captureInsight(f, "$select");
-	for (const f of orderInsights) parser.captureInsight(f, "$order");
+	for (const [field, op] of controlInsights) parser.captureInsight(field, op);
 	return {
 		filter,
 		controls,
 		insights: parser.getInsights()
 	};
 }
+/** Split a string by `sep` at the top level (ignoring separators inside balanced parentheses). */ function splitTopLevel(str, sep) {
+	const parts = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < str.length; i++) if (str[i] === "(") depth++;
+	else if (str[i] === ")") depth--;
+	else if (str[i] === sep && depth === 0) {
+		parts.push(str.slice(start, i));
+		start = i + 1;
+	}
+	parts.push(str.slice(start));
+	return parts;
+}
+/** Parse a single `$with` segment like `posts` or `posts($sort=-createdAt&status=active)`. */ function parseWithSegment(seg) {
+	if (!seg) return null;
+	const parenIdx = seg.indexOf("(");
+	if (parenIdx === -1) return {
+		name: seg,
+		filter: {},
+		controls: {}
+	};
+	const name = seg.slice(0, parenIdx);
+	if (!name) return null;
+	const inner = seg.slice(parenIdx + 1, -1);
+	if (!inner) return {
+		name,
+		filter: {},
+		controls: {}
+	};
+	const sub = parseUrl(inner);
+	const rel = {
+		name,
+		filter: sub.filter,
+		controls: sub.controls
+	};
+	if (sub.insights.size) rel.insights = sub.insights;
+	return rel;
+}
 function handleControls(parts) {
 	const controls = {};
-	const selectInsights = /* @__PURE__ */ new Set();
-	const orderInsights = /* @__PURE__ */ new Set();
+	const controlInsights = [];
 	for (const raw of parts) {
 		const [key, ...rest] = raw.split("=");
-		const value = decodeURIComponent(rest.join("="));
+		const value = rest.join("=");
 		switch (key) {
+			case "$with": {
+				var _controls;
+				if (!value) break;
+				(_controls = controls).$with ?? (_controls.$with = []);
+				const seen = new Set(controls.$with.map((r) => r.name));
+				for (const seg of splitTopLevel(value, ",")) {
+					const rel = parseWithSegment(seg);
+					if (!rel || seen.has(rel.name)) continue;
+					seen.add(rel.name);
+					controls.$with.push(rel);
+					controlInsights.push([rel.name, "$with"]);
+					if (rel.insights) for (const [field, ops] of rel.insights) {
+						const prefixed = `${rel.name}.${field}`;
+						for (const op of ops) controlInsights.push([prefixed, op]);
+					}
+				}
+				break;
+			}
 			case "$select": {
 				let hasExclusion = false;
 				const fields = [];
@@ -389,14 +443,14 @@ function handleControls(parts) {
 					const obj = controls.$select ?? {};
 					for (const { name, include } of fields) {
 						obj[name] = include ? 1 : 0;
-						selectInsights.add(name);
+						controlInsights.push([name, "$select"]);
 					}
 					controls.$select = obj;
 				} else {
 					const arr = Array.isArray(controls.$select) ? controls.$select : [];
 					for (const { name } of fields) {
 						arr.push(name);
-						selectInsights.add(name);
+						controlInsights.push([name, "$select"]);
 					}
 					controls.$select = arr;
 				}
@@ -404,11 +458,11 @@ function handleControls(parts) {
 			}
 			case "$sort":
 			case "$order":
-				var _controls;
-				(_controls = controls).$sort ?? (_controls.$sort = {});
+				var _controls1;
+				(_controls1 = controls).$sort ?? (_controls1.$sort = {});
 				value.split(",").forEach((f) => {
 					if (!f) return;
-					orderInsights.add(f.replace(/^-/, ""));
+					controlInsights.push([f.replace(/^-/, ""), "$order"]);
 					if (f.startsWith("-")) controls.$sort[f.slice(1)] = -1;
 					else controls.$sort[f] = 1;
 				});
@@ -428,8 +482,7 @@ function handleControls(parts) {
 	}
 	return {
 		controls,
-		selectInsights,
-		orderInsights
+		controlInsights
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqu/url",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "URL query string parser producing the Uniqu canonical query format",
   "license": "MIT",
   "author": "Artem Maltsev",
@@ -28,7 +28,7 @@
     "dist"
   ],
   "dependencies": {
-    "@uniqu/core": "^0.0.2"
+    "@uniqu/core": "^0.0.4"
   },
   "scripts": {
     "pub": "pnpm publish --access public",