@uniqu/url 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moostjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# @uniqu/url
+
+<p align="center">
+  <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.
+
+## Install
+
+```bash
+pnpm add @uniqu/url
+```
+
+## Usage
+
+```ts
+import { parseUrl } from '@uniqu/url'
+
+const { filter, controls, insights } = parseUrl(
+  'age>=18&status!=DELETED&name~=/^Jo/i&$select=name,email&$limit=20'
+)
+```
+
+**Result:**
+
+```ts
+filter = {
+  age: { $gte: 18 },
+  status: { $ne: 'DELETED' },
+  name: { $regex: '/^Jo/i' },
+}
+
+controls = {
+  $select: ['name', 'email'],
+  $limit: 20,
+}
+
+insights = Map {
+  'age'    => Set { '$gte' },
+  'status' => Set { '$ne' },
+  'name'   => Set { '$regex', '$select' },
+  'email'  => Set { '$select' },
+}
+```
+
+## Query Syntax
+
+### Comparison Operators
+
+| Syntax | Operator | Example | Result |
+|--------|----------|---------|--------|
+| `=` | `$eq` | `status=ACTIVE` | `{ status: 'ACTIVE' }` |
+| `!=` | `$ne` | `status!=DELETED` | `{ status: { $ne: 'DELETED' } }` |
+| `>` | `$gt` | `age>25` | `{ age: { $gt: 25 } }` |
+| `>=` | `$gte` | `age>=18` | `{ age: { $gte: 18 } }` |
+| `<` | `$lt` | `price<100` | `{ price: { $lt: 100 } }` |
+| `<=` | `$lte` | `price<=99.99` | `{ price: { $lte: 99.99 } }` |
+| `~=` | `$regex` | `name~=/^Jo/i` | `{ name: { $regex: '/^Jo/i' } }` |
+
+### Lists (IN / NOT IN)
+
+```
+role{Admin,Editor}        → { role: { $in: ['Admin', 'Editor'] } }
+status!{Draft,Deleted}    → { status: { $nin: ['Draft', 'Deleted'] } }
+```
+
+### Between
+
+```
+25<age<35     → { age: { $gt: 25, $lt: 35 } }
+25<=age<=35   → { age: { $gte: 25, $lte: 35 } }
+```
+
+### Exists
+
+```
+$exists=phone,email       → { phone: { $exists: true }, email: { $exists: true } }
+$!exists=deletedAt        → { deletedAt: { $exists: false } }
+```
+
+### Negation (NOT)
+
+`!(...)` negates a grouped expression:
+
+```
+!(status=DELETED)
+→ { $not: { status: 'DELETED' } }
+
+!(age>18&status=active)
+→ { $not: { age: { $gt: 18 }, status: 'active' } }
+
+!(status=DELETED^status=ARCHIVED)
+→ { $not: { $or: [{ status: 'DELETED' }, { status: 'ARCHIVED' }] } }
+```
+
+`$not` can be combined with other operators via `&` and `^`:
+
+```
+!(role{Guest,Anonymous})&age>=18
+→ { $and: [{ $not: { role: { $in: ['Guest', 'Anonymous'] } } }, { age: { $gte: 18 } }] }
+```
+
+### Logical Operators
+
+`&` is AND (higher precedence), `^` is OR (lower precedence). Parentheses override precedence:
+
+```
+age>25^score>550&status=VIP
+→ { $or: [{ age: { $gt: 25 } }, { score: { $gt: 550 }, status: 'VIP' }] }
+
+(age>25^score>550)&status=VIP
+→ { $and: [{ $or: [{ age: { $gt: 25 } }, { score: { $gt: 550 } }] }, { status: 'VIP' }] }
+```
+
+Adjacent AND conditions on the same field are merged when safe:
+
+```
+age>=18&age<=30  → { age: { $gte: 18, $lte: 30 } }
+```
+
+### Literal Types
+
+| Syntax | Type | Examples |
+|--------|------|---------|
+| Bare number | `number` | `42`, `-3.14`, `0` |
+| Leading zero | `string` | `007`, `00`, `01` |
+| `true` / `false` | `boolean` | `flag=true` |
+| `null` | `null` | `deleted=null` |
+| `'quoted'` | `string` | `name='John Doe'` |
+| Bare word | `string` | `status=ACTIVE` |
+| `/pattern/flags` | `string` | `name~=/^Jo/i` |
+
+### Percent Encoding
+
+All parts are decoded with `decodeURIComponent()` before parsing. Encode special characters in URLs:
+
+```
+name=%27John%20Doe%27  → name: 'John Doe'
+name~=%2F%5EJo%2Fi     → name: { $regex: '/^Jo/i' }
+```
+
+## Control Keywords
+
+Control keywords start with `$` and are separated from filter expressions:
+
+| Keyword | Aliases | Example | Result |
+|---------|---------|---------|--------|
+| `$select` | — | `$select=name,email` | `{ $select: ['name', 'email'] }` |
+| `$order` | `$sort` | `$order=-createdAt,score` | `{ $sort: { createdAt: -1, score: 1 } }` |
+| `$limit` | `$top` | `$limit=20` | `{ $limit: 20 }` |
+| `$skip` | — | `$skip=40` | `{ $skip: 40 }` |
+| `$count` | — | `$count` | `{ $count: true }` |
+| `$<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.
+
+## 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`).
+
+For queries constructed as JSON objects (not parsed from URL), use `computeInsights()` from `@uniqu/core` for **lazy** computation.
+
+## Full Example
+
+```
+$select=firstName,-client.ssn
+&$order=-createdAt,score
+&$limit=50&$skip=10
+&$count
+&$exists=client.phone
+&$!exists=deletedAt
+&age>=18&age<=30
+&status!=DELETED
+&name~=/^Jo/i
+&role{Admin,Editor}
+&25<height<35
+^score>550&price>50&price<100
+```
+
+Produces:
+
+```ts
+{
+  filter: {
+    $or: [
+      {
+        'client.phone': { $exists: true },
+        deletedAt: { $exists: false },
+        age: { $gte: 18, $lte: 30 },
+        status: { $ne: 'DELETED' },
+        name: { $regex: '/^Jo/i' },
+        role: { $in: ['Admin', 'Editor'] },
+        height: { $gt: 25, $lt: 35 },
+      },
+      {
+        score: { $gt: 550 },
+        price: { $gt: 50, $lt: 100 },
+      },
+    ],
+  },
+  controls: {
+    $select: { firstName: 1, 'client.ssn': 0 },
+    $sort: { createdAt: -1, score: 1 },
+    $limit: 50,
+    $skip: 10,
+    $count: true,
+  },
+}
+```
+
+## API Reference
+
+### `parseUrl(raw: string): UrlQuery`
+
+Parse a URL query string (without the leading `?`) into the uniqu format.
+
+### `UrlQuery`
+
+```ts
+interface UrlQuery extends Uniquery {
+  insights: UniqueryInsights
+}
+```
+
+Narrows the optional `insights` field from `Uniquery` to required — insights are eagerly computed during URL parsing. Use `getInsights()` from `@uniqu/core` to transparently handle both URL-parsed queries (pre-computed) and manually constructed queries (lazy).
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.cjs

@@ -0,0 +1,438 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _uniqu_core = require("@uniqu/core");
+
+//#region packages/url/src/tokens.ts
+/**
+* Order matters:
+*   - keywords before generic words
+*   - multi-char operators (>=, <=, !=, ~=) before single-char
+*   - literals before identifiers
+*/ const tokens = [
+	{
+		r: /^\/(?:\\.|[^\\/])*\/[imsux]*/u,
+		type: "regex"
+	},
+	{
+		r: /^'(?:\\.|[^'\\])*'/u,
+		type: "string"
+	},
+	{
+		r: /^-?(?:0(?!\d)|[1-9]\d*)(?:\.\d+)?(?!\d)/u,
+		type: "number"
+	},
+	{
+		r: /^(?:true|false)/u,
+		type: "boolean"
+	},
+	{
+		r: /^null/u,
+		type: "null"
+	},
+	{
+		r: /^!=/u,
+		type: "op-ne"
+	},
+	{
+		r: /^>=/u,
+		type: "op-gte"
+	},
+	{
+		r: /^<=/u,
+		type: "op-lte"
+	},
+	{
+		r: /^~=/u,
+		type: "op-regex"
+	},
+	{
+		r: /^=/u,
+		type: "op-eq"
+	},
+	{
+		r: /^>/u,
+		type: "op-gt"
+	},
+	{
+		r: /^</u,
+		type: "op-lt"
+	},
+	{
+		r: /^\^/u,
+		type: "or"
+	},
+	{
+		r: /^&/u,
+		type: "and"
+	},
+	{
+		r: /^\(/u,
+		type: "lparen"
+	},
+	{
+		r: /^\)/u,
+		type: "rparen"
+	},
+	{
+		r: /^\{/u,
+		type: "lbrace"
+	},
+	{
+		r: /^\}/u,
+		type: "rbrace"
+	},
+	{
+		r: /^,/u,
+		type: "comma"
+	},
+	{
+		r: /^!/u,
+		type: "bang"
+	},
+	{
+		r: /^\$!?[A-Za-z0-9_]+/u,
+		type: "keyword"
+	},
+	{
+		r: /^(?:[^&^)\s=><!]+(?:\s|\+)+[^&^)=><!]*)+/u,
+		type: "string"
+	},
+	{
+		r: /^[A-Za-z0-9_.]+/u,
+		type: "word"
+	},
+	{
+		r: /^[\s]+/u,
+		type: "ws"
+	}
+];
+const tokenMap = new Map(tokens.map((t) => [t.type, t.r]));
+function lex(input) {
+	const tokensOut = [];
+	let idx = 0;
+	while (idx < input.length) {
+		let matched = false;
+		for (const { r, type } of tokens) {
+			r.lastIndex = 0;
+			const slice = input.slice(idx);
+			const m = r.exec(slice);
+			if (m) {
+				matched = true;
+				if (type !== "ws") tokensOut.push({
+					type,
+					value: m[0],
+					pos: idx
+				});
+				idx += m[0].length;
+				break;
+			}
+		}
+		if (!matched) throw new SyntaxError(`Unexpected char '${input[idx]}' at ${idx} --- ${input}`);
+	}
+	return tokensOut;
+}
+
+//#endregion
+//#region packages/url/src/parser.ts
+function _define_property(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+	else obj[key] = value;
+	return obj;
+}
+const opMap = {
+	"op-eq": "$eq",
+	"op-ne": "$ne",
+	"op-gt": "$gt",
+	"op-gte": "$gte",
+	"op-lt": "$lt",
+	"op-lte": "$lte",
+	"op-regex": "$regex"
+};
+var Parser = class {
+	peek(offset = 0) {
+		return this.t[this.i + offset];
+	}
+	consume(type) {
+		const tok = this.t[this.i++];
+		if (type && tok.type !== type) throw new SyntaxError(`Expected ${type}, got "${tok.value}" at pos ${tok.pos}`);
+		return tok;
+	}
+	match(type) {
+		if (this.peek()?.type === type) {
+			this.consume();
+			return true;
+		}
+		return false;
+	}
+	expectEof() {
+		if (this.i !== this.t.length) throw new SyntaxError(`Unexpected token at pos ${this.t[this.i]?.pos}. End of input expected.`);
+	}
+	captureInsight(field, op) {
+		let set = this.insights.get(field);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.insights.set(field, set);
+		}
+		set.add(op);
+	}
+	getInsights() {
+		return this.insights;
+	}
+	/** expression := disjunction */ parseExpression() {
+		return this.parseDisjunction();
+	}
+	parseDisjunction() {
+		let node = this.parseConjunction();
+		const orNodes = [node];
+		while (this.match("or")) orNodes.push(this.parseConjunction());
+		return orNodes.length === 1 ? node : { $or: orNodes };
+	}
+	parseConjunction() {
+		const nodes = [this.parseTerm()];
+		while (this.match("and")) nodes.push(this.parseTerm());
+		if (nodes.length === 1) return nodes[0];
+		return mergeConjunction(nodes) ?? { $and: nodes };
+	}
+	parseTerm() {
+		if (this.peek()?.type === "bang" && this.peek(1)?.type === "lparen") {
+			this.consume("bang");
+			this.consume("lparen");
+			const inside = this.parseDisjunction();
+			this.consume("rparen");
+			return { $not: inside };
+		}
+		if (this.match("lparen")) {
+			const inside = this.parseDisjunction();
+			this.consume("rparen");
+			return inside;
+		}
+		if (this.peek().type === "number" || this.peek().type === "string") {
+			const lhsLit = this.parseLiteral();
+			const firstOp = this.consume().type;
+			if (firstOp !== "op-lt" && firstOp !== "op-lte") this.i -= 2;
+			else {
+				const field = this.consume("word").value;
+				const secondOpTok = this.consume();
+				if (secondOpTok.type !== "op-lt" && secondOpTok.type !== "op-lte") throw new SyntaxError(`Invalid between syntax at pos ${secondOpTok.pos}`);
+				const rhsLit = this.parseLiteral();
+				const out = {};
+				const op1 = firstOp === "op-lt" ? "$gt" : "$gte";
+				const op2 = secondOpTok.type === "op-lt" ? "$lt" : "$lte";
+				out[field] = {
+					[op1]: lhsLit,
+					[op2]: rhsLit
+				};
+				this.captureInsight(field, op1);
+				this.captureInsight(field, op2);
+				return out;
+			}
+		}
+		if (this.peek().type === "keyword") {
+			const kwTok = this.peek();
+			if (kwTok.value === "$exists" || kwTok.value === "$!exists") {
+				this.consume("keyword");
+				this.consume("op-eq");
+				const fields = [];
+				fields.push(this.consume("word").value);
+				while (this.match("comma")) fields.push(this.consume("word").value);
+				for (const field of fields) this.captureInsight(field, "$exists");
+				return buildExists(fields, kwTok.value === "$exists");
+			}
+		}
+		if (this.peek().type === "word" && this.peek(1)?.type === "lbrace" || this.peek(1)?.type === "bang" && this.peek(2)?.type === "lbrace") {
+			const field = this.consume("word").value;
+			let negate = false;
+			if (this.match("bang")) negate = true;
+			this.consume("lbrace");
+			const list = [];
+			list.push(this.parseLiteral());
+			while (this.match("comma")) list.push(this.parseLiteral());
+			this.consume("rbrace");
+			const out = {};
+			const op = negate ? "$nin" : "$in";
+			out[field] = { [op]: list };
+			this.captureInsight(field, op);
+			return out;
+		}
+		const fieldTok = this.consume("word");
+		const opTok = this.consume();
+		const lit = this.parseLiteral();
+		const op = opMap[opTok.type];
+		const field = fieldTok.value;
+		if (op === void 0) throw new SyntaxError(`Unsupported operator "${opTok.value}" at pos ${opTok.pos}`);
+		this.captureInsight(field, op);
+		return op === "$eq" ? { [field]: lit } : { [field]: { [op]: lit } };
+	}
+	parseLiteral() {
+		const tok = this.consume();
+		switch (tok.type) {
+			case "number": return Number(tok.value);
+			case "boolean": return tok.value === "true";
+			case "null": return null;
+			case "regex": return tok.value;
+			case "word": return tok.value;
+			case "string": return unescapeString(tok.value);
+			default: throw new SyntaxError(`Unexpected literal "${tok.value}" at pos ${tok.pos}`);
+		}
+	}
+	constructor(t) {
+		_define_property(this, "t", void 0);
+		_define_property(this, "i", void 0);
+		_define_property(this, "insights", void 0);
+		this.t = t;
+		this.i = 0;
+		this.insights = /* @__PURE__ */ new Map();
+	}
+};
+function unescapeString(str) {
+	return str.replace(/(^'|'$)/gu, "");
+}
+/**
+* Attempt to merge an array of simple nodes produced by `parseTerm`.
+* Returns a single flattened object if safe, or null on conflict.
+*/ function mergeConjunction(nodes) {
+	const merged = [];
+	let currentMerge = {};
+	for (const node of nodes) {
+		if ("$or" in node || "$and" in node || "$not" in node) {
+			merged.push(node);
+			continue;
+		}
+		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));
+			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];
+			}
+		} else currentMerge[key] = val;
+	}
+	if (Object.keys(currentMerge).length > 0) merged.push(currentMerge);
+	return merged.length > 1 ? { $and: merged } : merged[0] ?? null;
+}
+function buildExists(fields, positive) {
+	const out = {};
+	for (const f of fields) out[f] = { $exists: positive };
+	return out;
+}
+
+//#endregion
+//#region packages/url/src/parse-url.ts
+/**
+* Parse a URL query string into the uniqu canonical format.
+*
+* The string may contain:
+*   - logical connectors `&` (AND) and `^` (OR)
+*   - comparison operators (=, !=, >, >=, <, <=, ~=, in-list, nin-list, between)
+*   - grouping parentheses
+*   - control keywords that start with `$` (e.g. `$select`, `$limit`, `$order`)
+*
+* @param raw - Raw query string without the leading "?"
+*/ function parseUrl(raw) {
+	const parts = raw.split("&");
+	const controlParts = [];
+	const exprParts = [];
+	for (const _p of parts) {
+		const p = decodeURIComponent(_p);
+		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);
+	let filter = {};
+	let parser;
+	if (exprParts.length) {
+		parser = new Parser(lex(exprParts.join("&")));
+		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");
+	return {
+		filter,
+		controls,
+		insights: parser.getInsights()
+	};
+}
+function handleControls(parts) {
+	const controls = {};
+	const selectInsights = /* @__PURE__ */ new Set();
+	const orderInsights = /* @__PURE__ */ new Set();
+	for (const raw of parts) {
+		const [key, ...rest] = raw.split("=");
+		const value = decodeURIComponent(rest.join("="));
+		switch (key) {
+			case "$select": {
+				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
+						});
+					} else fields.push({
+						name: f,
+						include: true
+					});
+				});
+				if (hasExclusion) {
+					const obj = controls.$select ?? {};
+					for (const { name, include } of fields) {
+						obj[name] = include ? 1 : 0;
+						selectInsights.add(name);
+					}
+					controls.$select = obj;
+				} else {
+					const arr = Array.isArray(controls.$select) ? controls.$select : [];
+					for (const { name } of fields) {
+						arr.push(name);
+						selectInsights.add(name);
+					}
+					controls.$select = arr;
+				}
+				break;
+			}
+			case "$sort":
+			case "$order":
+				var _controls;
+				(_controls = controls).$sort ?? (_controls.$sort = {});
+				value.split(",").forEach((f) => {
+					if (!f) return;
+					orderInsights.add(f.replace(/^-/, ""));
+					if (f.startsWith("-")) controls.$sort[f.slice(1)] = -1;
+					else controls.$sort[f] = 1;
+				});
+				break;
+			case "$limit":
+			case "$top":
+				controls.$limit = Number(value);
+				break;
+			case "$skip":
+				controls.$skip = Number(value);
+				break;
+			case "$count":
+				controls.$count = true;
+				break;
+			default: controls[key] = value;
+		}
+	}
+	return {
+		controls,
+		selectInsights,
+		orderInsights
+	};
+}
+
+//#endregion
+exports.parseUrl = parseUrl;

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { Uniquery, UniqueryInsights } from '@uniqu/core';
+
+/** Result of parsing a URL query string. Narrows `Uniquery.insights` from optional to required (eagerly computed during parsing). */
+interface UrlQuery extends Uniquery {
+    insights: UniqueryInsights;
+}
+/**
+ * Parse a URL query string into the uniqu canonical format.
+ *
+ * The string may contain:
+ *   - logical connectors `&` (AND) and `^` (OR)
+ *   - comparison operators (=, !=, >, >=, <, <=, ~=, in-list, nin-list, between)
+ *   - grouping parentheses
+ *   - control keywords that start with `$` (e.g. `$select`, `$limit`, `$order`)
+ *
+ * @param raw - Raw query string without the leading "?"
+ */
+declare function parseUrl(raw: string): UrlQuery;
+
+export { parseUrl };
+export type { UrlQuery };

package/dist/index.mjs

@@ -0,0 +1,437 @@
+import { isPrimitive } from "@uniqu/core";
+
+//#region packages/url/src/tokens.ts
+/**
+* Order matters:
+*   - keywords before generic words
+*   - multi-char operators (>=, <=, !=, ~=) before single-char
+*   - literals before identifiers
+*/ const tokens = [
+	{
+		r: /^\/(?:\\.|[^\\/])*\/[imsux]*/u,
+		type: "regex"
+	},
+	{
+		r: /^'(?:\\.|[^'\\])*'/u,
+		type: "string"
+	},
+	{
+		r: /^-?(?:0(?!\d)|[1-9]\d*)(?:\.\d+)?(?!\d)/u,
+		type: "number"
+	},
+	{
+		r: /^(?:true|false)/u,
+		type: "boolean"
+	},
+	{
+		r: /^null/u,
+		type: "null"
+	},
+	{
+		r: /^!=/u,
+		type: "op-ne"
+	},
+	{
+		r: /^>=/u,
+		type: "op-gte"
+	},
+	{
+		r: /^<=/u,
+		type: "op-lte"
+	},
+	{
+		r: /^~=/u,
+		type: "op-regex"
+	},
+	{
+		r: /^=/u,
+		type: "op-eq"
+	},
+	{
+		r: /^>/u,
+		type: "op-gt"
+	},
+	{
+		r: /^</u,
+		type: "op-lt"
+	},
+	{
+		r: /^\^/u,
+		type: "or"
+	},
+	{
+		r: /^&/u,
+		type: "and"
+	},
+	{
+		r: /^\(/u,
+		type: "lparen"
+	},
+	{
+		r: /^\)/u,
+		type: "rparen"
+	},
+	{
+		r: /^\{/u,
+		type: "lbrace"
+	},
+	{
+		r: /^\}/u,
+		type: "rbrace"
+	},
+	{
+		r: /^,/u,
+		type: "comma"
+	},
+	{
+		r: /^!/u,
+		type: "bang"
+	},
+	{
+		r: /^\$!?[A-Za-z0-9_]+/u,
+		type: "keyword"
+	},
+	{
+		r: /^(?:[^&^)\s=><!]+(?:\s|\+)+[^&^)=><!]*)+/u,
+		type: "string"
+	},
+	{
+		r: /^[A-Za-z0-9_.]+/u,
+		type: "word"
+	},
+	{
+		r: /^[\s]+/u,
+		type: "ws"
+	}
+];
+const tokenMap = new Map(tokens.map((t) => [t.type, t.r]));
+function lex(input) {
+	const tokensOut = [];
+	let idx = 0;
+	while (idx < input.length) {
+		let matched = false;
+		for (const { r, type } of tokens) {
+			r.lastIndex = 0;
+			const slice = input.slice(idx);
+			const m = r.exec(slice);
+			if (m) {
+				matched = true;
+				if (type !== "ws") tokensOut.push({
+					type,
+					value: m[0],
+					pos: idx
+				});
+				idx += m[0].length;
+				break;
+			}
+		}
+		if (!matched) throw new SyntaxError(`Unexpected char '${input[idx]}' at ${idx} --- ${input}`);
+	}
+	return tokensOut;
+}
+
+//#endregion
+//#region packages/url/src/parser.ts
+function _define_property(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+	else obj[key] = value;
+	return obj;
+}
+const opMap = {
+	"op-eq": "$eq",
+	"op-ne": "$ne",
+	"op-gt": "$gt",
+	"op-gte": "$gte",
+	"op-lt": "$lt",
+	"op-lte": "$lte",
+	"op-regex": "$regex"
+};
+var Parser = class {
+	peek(offset = 0) {
+		return this.t[this.i + offset];
+	}
+	consume(type) {
+		const tok = this.t[this.i++];
+		if (type && tok.type !== type) throw new SyntaxError(`Expected ${type}, got "${tok.value}" at pos ${tok.pos}`);
+		return tok;
+	}
+	match(type) {
+		if (this.peek()?.type === type) {
+			this.consume();
+			return true;
+		}
+		return false;
+	}
+	expectEof() {
+		if (this.i !== this.t.length) throw new SyntaxError(`Unexpected token at pos ${this.t[this.i]?.pos}. End of input expected.`);
+	}
+	captureInsight(field, op) {
+		let set = this.insights.get(field);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.insights.set(field, set);
+		}
+		set.add(op);
+	}
+	getInsights() {
+		return this.insights;
+	}
+	/** expression := disjunction */ parseExpression() {
+		return this.parseDisjunction();
+	}
+	parseDisjunction() {
+		let node = this.parseConjunction();
+		const orNodes = [node];
+		while (this.match("or")) orNodes.push(this.parseConjunction());
+		return orNodes.length === 1 ? node : { $or: orNodes };
+	}
+	parseConjunction() {
+		const nodes = [this.parseTerm()];
+		while (this.match("and")) nodes.push(this.parseTerm());
+		if (nodes.length === 1) return nodes[0];
+		return mergeConjunction(nodes) ?? { $and: nodes };
+	}
+	parseTerm() {
+		if (this.peek()?.type === "bang" && this.peek(1)?.type === "lparen") {
+			this.consume("bang");
+			this.consume("lparen");
+			const inside = this.parseDisjunction();
+			this.consume("rparen");
+			return { $not: inside };
+		}
+		if (this.match("lparen")) {
+			const inside = this.parseDisjunction();
+			this.consume("rparen");
+			return inside;
+		}
+		if (this.peek().type === "number" || this.peek().type === "string") {
+			const lhsLit = this.parseLiteral();
+			const firstOp = this.consume().type;
+			if (firstOp !== "op-lt" && firstOp !== "op-lte") this.i -= 2;
+			else {
+				const field = this.consume("word").value;
+				const secondOpTok = this.consume();
+				if (secondOpTok.type !== "op-lt" && secondOpTok.type !== "op-lte") throw new SyntaxError(`Invalid between syntax at pos ${secondOpTok.pos}`);
+				const rhsLit = this.parseLiteral();
+				const out = {};
+				const op1 = firstOp === "op-lt" ? "$gt" : "$gte";
+				const op2 = secondOpTok.type === "op-lt" ? "$lt" : "$lte";
+				out[field] = {
+					[op1]: lhsLit,
+					[op2]: rhsLit
+				};
+				this.captureInsight(field, op1);
+				this.captureInsight(field, op2);
+				return out;
+			}
+		}
+		if (this.peek().type === "keyword") {
+			const kwTok = this.peek();
+			if (kwTok.value === "$exists" || kwTok.value === "$!exists") {
+				this.consume("keyword");
+				this.consume("op-eq");
+				const fields = [];
+				fields.push(this.consume("word").value);
+				while (this.match("comma")) fields.push(this.consume("word").value);
+				for (const field of fields) this.captureInsight(field, "$exists");
+				return buildExists(fields, kwTok.value === "$exists");
+			}
+		}
+		if (this.peek().type === "word" && this.peek(1)?.type === "lbrace" || this.peek(1)?.type === "bang" && this.peek(2)?.type === "lbrace") {
+			const field = this.consume("word").value;
+			let negate = false;
+			if (this.match("bang")) negate = true;
+			this.consume("lbrace");
+			const list = [];
+			list.push(this.parseLiteral());
+			while (this.match("comma")) list.push(this.parseLiteral());
+			this.consume("rbrace");
+			const out = {};
+			const op = negate ? "$nin" : "$in";
+			out[field] = { [op]: list };
+			this.captureInsight(field, op);
+			return out;
+		}
+		const fieldTok = this.consume("word");
+		const opTok = this.consume();
+		const lit = this.parseLiteral();
+		const op = opMap[opTok.type];
+		const field = fieldTok.value;
+		if (op === void 0) throw new SyntaxError(`Unsupported operator "${opTok.value}" at pos ${opTok.pos}`);
+		this.captureInsight(field, op);
+		return op === "$eq" ? { [field]: lit } : { [field]: { [op]: lit } };
+	}
+	parseLiteral() {
+		const tok = this.consume();
+		switch (tok.type) {
+			case "number": return Number(tok.value);
+			case "boolean": return tok.value === "true";
+			case "null": return null;
+			case "regex": return tok.value;
+			case "word": return tok.value;
+			case "string": return unescapeString(tok.value);
+			default: throw new SyntaxError(`Unexpected literal "${tok.value}" at pos ${tok.pos}`);
+		}
+	}
+	constructor(t) {
+		_define_property(this, "t", void 0);
+		_define_property(this, "i", void 0);
+		_define_property(this, "insights", void 0);
+		this.t = t;
+		this.i = 0;
+		this.insights = /* @__PURE__ */ new Map();
+	}
+};
+function unescapeString(str) {
+	return str.replace(/(^'|'$)/gu, "");
+}
+/**
+* Attempt to merge an array of simple nodes produced by `parseTerm`.
+* Returns a single flattened object if safe, or null on conflict.
+*/ function mergeConjunction(nodes) {
+	const merged = [];
+	let currentMerge = {};
+	for (const node of nodes) {
+		if ("$or" in node || "$and" in node || "$not" in node) {
+			merged.push(node);
+			continue;
+		}
+		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));
+			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];
+			}
+		} else currentMerge[key] = val;
+	}
+	if (Object.keys(currentMerge).length > 0) merged.push(currentMerge);
+	return merged.length > 1 ? { $and: merged } : merged[0] ?? null;
+}
+function buildExists(fields, positive) {
+	const out = {};
+	for (const f of fields) out[f] = { $exists: positive };
+	return out;
+}
+
+//#endregion
+//#region packages/url/src/parse-url.ts
+/**
+* Parse a URL query string into the uniqu canonical format.
+*
+* The string may contain:
+*   - logical connectors `&` (AND) and `^` (OR)
+*   - comparison operators (=, !=, >, >=, <, <=, ~=, in-list, nin-list, between)
+*   - grouping parentheses
+*   - control keywords that start with `$` (e.g. `$select`, `$limit`, `$order`)
+*
+* @param raw - Raw query string without the leading "?"
+*/ function parseUrl(raw) {
+	const parts = raw.split("&");
+	const controlParts = [];
+	const exprParts = [];
+	for (const _p of parts) {
+		const p = decodeURIComponent(_p);
+		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);
+	let filter = {};
+	let parser;
+	if (exprParts.length) {
+		parser = new Parser(lex(exprParts.join("&")));
+		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");
+	return {
+		filter,
+		controls,
+		insights: parser.getInsights()
+	};
+}
+function handleControls(parts) {
+	const controls = {};
+	const selectInsights = /* @__PURE__ */ new Set();
+	const orderInsights = /* @__PURE__ */ new Set();
+	for (const raw of parts) {
+		const [key, ...rest] = raw.split("=");
+		const value = decodeURIComponent(rest.join("="));
+		switch (key) {
+			case "$select": {
+				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
+						});
+					} else fields.push({
+						name: f,
+						include: true
+					});
+				});
+				if (hasExclusion) {
+					const obj = controls.$select ?? {};
+					for (const { name, include } of fields) {
+						obj[name] = include ? 1 : 0;
+						selectInsights.add(name);
+					}
+					controls.$select = obj;
+				} else {
+					const arr = Array.isArray(controls.$select) ? controls.$select : [];
+					for (const { name } of fields) {
+						arr.push(name);
+						selectInsights.add(name);
+					}
+					controls.$select = arr;
+				}
+				break;
+			}
+			case "$sort":
+			case "$order":
+				var _controls;
+				(_controls = controls).$sort ?? (_controls.$sort = {});
+				value.split(",").forEach((f) => {
+					if (!f) return;
+					orderInsights.add(f.replace(/^-/, ""));
+					if (f.startsWith("-")) controls.$sort[f.slice(1)] = -1;
+					else controls.$sort[f] = 1;
+				});
+				break;
+			case "$limit":
+			case "$top":
+				controls.$limit = Number(value);
+				break;
+			case "$skip":
+				controls.$skip = Number(value);
+				break;
+			case "$count":
+				controls.$count = true;
+				break;
+			default: controls[key] = value;
+		}
+	}
+	return {
+		controls,
+		selectInsights,
+		orderInsights
+	};
+}
+
+//#endregion
+export { parseUrl };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@uniqu/url",
+  "version": "0.0.1",
+  "description": "URL query string parser producing the Uniqu canonical query format",
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/uniqu.git",
+    "directory": "packages/url"
+  },
+  "bugs": {
+    "url": "https://github.com/moostjs/uniqu/issues"
+  },
+  "homepage": "https://github.com/moostjs/uniqu/tree/main/packages/url#readme",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@uniqu/core": "^0.0.1"
+  },
+  "scripts": {
+    "pub": "pnpm publish --access public",
+    "test": "vitest"
+  }
+}