@uniqu/url 0.0.1 → 0.0.3

package/README.md

@@ -151,10 +151,117 @@ 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' }, { name: 'author' }] }` |
 | `$<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' },
+    $sort: { createdAt: -1 },
+    $limit: 5,
+  },
+]
+```
+
+All controls are supported inside parens: `$sort`, `$limit`, `$skip`, `$select`, 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',
+    $sort: { createdAt: -1 },
+    $limit: 5,
+    $with: [
+      { name: 'comments', $limit: 10, $with: [{ name: 'author' }] },
+      { name: 'tags' },
+    ],
+  },
+]
+```
+
+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' },
+        $sort: { createdAt: -1 },
+        $limit: 5,
+        $select: ['title', 'body'],
+      },
+      { name: 'author' },
+    ],
+  },
+  insights: Map {
+    'status' => Set { '$eq' },
+    'posts'  => Set { '$with' },
+    'author' => Set { '$with' },
+  },
+}
+```
+
+#### 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 +275,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 +313,10 @@ Produces:
     $limit: 50,
     $skip: 10,
     $count: true,
+    $with: [
+      { name: 'posts', filter: { status: 'published' }, $sort: { date: -1 }, $limit: 5 },
+      { name: 'profile' },
+    ],
   },
 }
 ```

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, selectInsights, orderInsights, withInsights } = handleControls(controlParts);
 	let filter = {};
 	let parser;
 	if (exprParts.length) {
@@ -356,20 +356,67 @@ function buildExists(fields, positive) {
 	} else parser = new Parser([]);
 	for (const f of selectInsights) parser.captureInsight(f, "$select");
 	for (const f of orderInsights) parser.captureInsight(f, "$order");
+	for (const f of withInsights) parser.captureInsight(f, "$with");
 	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 };
+	const name = seg.slice(0, parenIdx);
+	if (!name) return null;
+	const inner = seg.slice(parenIdx + 1, -1);
+	if (!inner) return { name };
+	const sub = parseUrl(inner);
+	const rel = { name };
+	if (Object.keys(sub.filter).length) rel.filter = sub.filter;
+	if (sub.controls.$sort) rel.$sort = sub.controls.$sort;
+	if (sub.controls.$skip != null) rel.$skip = sub.controls.$skip;
+	if (sub.controls.$limit != null) rel.$limit = sub.controls.$limit;
+	if (sub.controls.$select) rel.$select = sub.controls.$select;
+	if (sub.controls.$with?.length) rel.$with = sub.controls.$with;
+	return rel;
+}
 function handleControls(parts) {
 	const controls = {};
 	const selectInsights = /* @__PURE__ */ new Set();
 	const orderInsights = /* @__PURE__ */ new Set();
+	const withInsights = /* @__PURE__ */ new Set();
 	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);
+					withInsights.add(rel.name);
+				}
+				break;
+			}
 			case "$select": {
 				let hasExclusion = false;
 				const fields = [];
@@ -405,8 +452,8 @@ 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(/^-/, ""));
@@ -430,7 +477,8 @@ function handleControls(parts) {
 	return {
 		controls,
 		selectInsights,
-		orderInsights
+		orderInsights,
+		withInsights
 	};
 }
 

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, selectInsights, orderInsights, withInsights } = handleControls(controlParts);
 	let filter = {};
 	let parser;
 	if (exprParts.length) {
@@ -355,20 +355,67 @@ function buildExists(fields, positive) {
 	} else parser = new Parser([]);
 	for (const f of selectInsights) parser.captureInsight(f, "$select");
 	for (const f of orderInsights) parser.captureInsight(f, "$order");
+	for (const f of withInsights) parser.captureInsight(f, "$with");
 	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 };
+	const name = seg.slice(0, parenIdx);
+	if (!name) return null;
+	const inner = seg.slice(parenIdx + 1, -1);
+	if (!inner) return { name };
+	const sub = parseUrl(inner);
+	const rel = { name };
+	if (Object.keys(sub.filter).length) rel.filter = sub.filter;
+	if (sub.controls.$sort) rel.$sort = sub.controls.$sort;
+	if (sub.controls.$skip != null) rel.$skip = sub.controls.$skip;
+	if (sub.controls.$limit != null) rel.$limit = sub.controls.$limit;
+	if (sub.controls.$select) rel.$select = sub.controls.$select;
+	if (sub.controls.$with?.length) rel.$with = sub.controls.$with;
+	return rel;
+}
 function handleControls(parts) {
 	const controls = {};
 	const selectInsights = /* @__PURE__ */ new Set();
 	const orderInsights = /* @__PURE__ */ new Set();
+	const withInsights = /* @__PURE__ */ new Set();
 	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);
+					withInsights.add(rel.name);
+				}
+				break;
+			}
 			case "$select": {
 				let hasExclusion = false;
 				const fields = [];
@@ -404,8 +451,8 @@ 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(/^-/, ""));
@@ -429,7 +476,8 @@ function handleControls(parts) {
 	return {
 		controls,
 		selectInsights,
-		orderInsights
+		orderInsights,
+		withInsights
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqu/url",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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.1"
+    "@uniqu/core": "^0.0.3"
   },
   "scripts": {
     "pub": "pnpm publish --access public",