@uniqu/url 0.0.3 → 0.0.5

package/README.md

@@ -151,7 +151,7 @@ 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' }] }` |
+| `$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.
@@ -179,13 +179,12 @@ controls.$with = [
   {
     name: 'posts',
     filter: { status: 'published' },
-    $sort: { createdAt: -1 },
-    $limit: 5,
+    controls: { $sort: { createdAt: -1 }, $limit: 5 },
   },
 ]
 ```
 
-All controls are supported inside parens: `$sort`, `$limit`, `$skip`, `$select`, and nested `$with`.
+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
 
@@ -201,12 +200,22 @@ This produces a tree:
 controls.$with = [
   {
     name: 'posts',
-    $sort: { createdAt: -1 },
-    $limit: 5,
-    $with: [
-      { name: 'comments', $limit: 10, $with: [{ name: 'author' }] },
-      { name: 'tags' },
-    ],
+    filter: {},
+    controls: {
+      $sort: { createdAt: -1 },
+      $limit: 5,
+      $with: [
+        {
+          name: 'comments',
+          filter: {},
+          controls: {
+            $limit: 10,
+            $with: [{ name: 'author', filter: {}, controls: {} }],
+          },
+        },
+        { name: 'tags', filter: {}, controls: {} },
+      ],
+    },
   },
 ]
 ```
@@ -229,21 +238,27 @@ Produces:
       {
         name: 'posts',
         filter: { status: 'published' },
-        $sort: { createdAt: -1 },
-        $limit: 5,
-        $select: ['title', 'body'],
+        controls: {
+          $sort: { createdAt: -1 },
+          $limit: 5,
+          $select: ['title', 'body'],
+        },
+        insights: Map { 'status' => Set { '$eq' }, ... },
       },
-      { name: 'author' },
+      { 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 |
@@ -314,8 +329,12 @@ Produces:
     $skip: 10,
     $count: true,
     $with: [
-      { name: 'posts', filter: { status: 'published' }, $sort: { date: -1 }, $limit: 5 },
-      { name: 'profile' },
+      {
+        name: 'posts',
+        filter: { status: 'published' },
+        controls: { $sort: { date: -1 }, $limit: 5 },
+      },
+      { name: 'profile', filter: {}, controls: {} },
     ],
   },
 }

package/dist/index.cjs

@@ -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, withInsights } = handleControls(controlParts);
+	const { controls, controlInsights } = handleControls(controlParts);
 	let filter = {};
 	let parser;
 	if (exprParts.length) {
@@ -354,9 +354,7 @@ 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 f of withInsights) parser.captureInsight(f, "$with");
+	for (const [field, op] of controlInsights) parser.captureInsight(field, op);
 	return {
 		filter,
 		controls,
@@ -379,26 +377,31 @@ function buildExists(fields, positive) {
 /** 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 };
+	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 };
+	if (!inner) return {
+		name,
+		filter: {},
+		controls: {}
+	};
 	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;
+	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 withInsights = /* @__PURE__ */ new Set();
+	const controlInsights = [];
 	for (const raw of parts) {
 		const [key, ...rest] = raw.split("=");
 		const value = rest.join("=");
@@ -413,7 +416,11 @@ function handleControls(parts) {
 					if (!rel || seen.has(rel.name)) continue;
 					seen.add(rel.name);
 					controls.$with.push(rel);
-					withInsights.add(rel.name);
+					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;
 			}
@@ -437,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;
 				}
@@ -456,7 +463,7 @@ function handleControls(parts) {
 				(_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;
 				});
@@ -476,9 +483,7 @@ function handleControls(parts) {
 	}
 	return {
 		controls,
-		selectInsights,
-		orderInsights,
-		withInsights
+		controlInsights
 	};
 }
 

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { Uniquery, UniqueryInsights } from '@uniqu/core';
+import { Uniquery, FilterExpr, UniqueryControls, UniqueryInsights } from '@uniqu/core';
 
-/** Result of parsing a URL query string. Narrows `Uniquery.insights` from optional to required (eagerly computed during parsing). */
+/** Result of parsing a URL query string. Narrows optional fields to required (always produced by the parser). */
 interface UrlQuery extends Uniquery {
+    filter: FilterExpr;
+    controls: UniqueryControls;
     insights: UniqueryInsights;
 }
 /**

package/dist/index.mjs

@@ -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, withInsights } = handleControls(controlParts);
+	const { controls, controlInsights } = handleControls(controlParts);
 	let filter = {};
 	let parser;
 	if (exprParts.length) {
@@ -353,9 +353,7 @@ 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 f of withInsights) parser.captureInsight(f, "$with");
+	for (const [field, op] of controlInsights) parser.captureInsight(field, op);
 	return {
 		filter,
 		controls,
@@ -378,26 +376,31 @@ function buildExists(fields, positive) {
 /** 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 };
+	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 };
+	if (!inner) return {
+		name,
+		filter: {},
+		controls: {}
+	};
 	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;
+	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 withInsights = /* @__PURE__ */ new Set();
+	const controlInsights = [];
 	for (const raw of parts) {
 		const [key, ...rest] = raw.split("=");
 		const value = rest.join("=");
@@ -412,7 +415,11 @@ function handleControls(parts) {
 					if (!rel || seen.has(rel.name)) continue;
 					seen.add(rel.name);
 					controls.$with.push(rel);
-					withInsights.add(rel.name);
+					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;
 			}
@@ -436,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;
 				}
@@ -455,7 +462,7 @@ function handleControls(parts) {
 				(_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;
 				});
@@ -475,9 +482,7 @@ function handleControls(parts) {
 	}
 	return {
 		controls,
-		selectInsights,
-		orderInsights,
-		withInsights
+		controlInsights
 	};
 }
 

package/package.json

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