@uniqu/core 0.0.3 → 0.0.5

package/README.md

@@ -87,7 +87,7 @@ A `FilterExpr` is either a **comparison node** (leaf) or a **logical node** (bra
 
 ### Relation Loading (`$with`)
 
-`$with` declares which relations to populate alongside the primary query. Each `WithRelation` is a self-contained sub-query with its own filter, sort, pagination, projection, and nested `$with`:
+`$with` declares which relations to populate alongside the primary query. Each relation is a full `Uniquery` sub-query (a `WithRelation`) with its own `name`, `filter`, `controls`, and `insights`:
 
 ```ts
 import type { Uniquery, WithRelation } from '@uniqu/core'
@@ -99,30 +99,29 @@ const query: Uniquery = {
       {
         name: 'posts',
         filter: { status: 'published' },
-        $sort: { createdAt: -1 },
-        $limit: 5,
-        $select: ['title', 'body'],
-        $with: [
-          { name: 'comments', $limit: 10 },
-          { name: 'author' },
-        ],
+        controls: {
+          $sort: { createdAt: -1 },
+          $limit: 5,
+          $select: ['title', 'body'],
+          $with: [
+            { name: 'comments', filter: {}, controls: { $limit: 10 } },
+            { name: 'author', filter: {}, controls: {} },
+          ],
+        },
       },
-      { name: 'profile' },
+      { name: 'profile', filter: {}, controls: {} },
     ],
   },
 }
 ```
 
-`WithRelation` extends `UniqueryControls` (minus `$count`) and adds `name` and `filter`:
+`WithRelation` is a `Uniquery` with a required `name`:
 
 ```ts
-interface WithRelation extends Omit<UniqueryControls, '$count'> {
-  name: string
-  filter?: FilterExpr
-}
+type WithRelation = Uniquery & { name: string }
 ```
 
-This means each relation entry supports the full set of controls — `$sort`, `$skip`, `$limit`, `$select`, nested `$with`, and pass-through `$`-prefixed keys — plus an optional scoped filter. The structure is recursive: a `WithRelation` can contain `$with` entries that themselves contain `$with` entries, to any depth.
+The `Uniquery` type itself has an optional `name` — when present it is a nested relation, when absent it is the root query. This means every `$with` entry is a self-contained query with its own `filter`, `controls` (including `$sort`, `$skip`, `$limit`, `$select`, nested `$with`, and pass-through keywords), and optional `insights`. The structure is recursive to any depth.
 
 Uniqu is a query parser, not an ORM. It records what was requested — the consumer (e.g. a database adapter) decides how to execute it (JOINs, subqueries, separate queries), validates relation names against its schema, and enforces depth/security limits.
 
@@ -236,7 +235,34 @@ const insights = computeInsights(query.filter, query.controls)
 // }
 ```
 
-Relation names from `$with` are captured with the `$with` insight operator, letting consumers validate that requested relations exist on the entity type. Only immediate (top-level) `$with` entries are captured — nested relation insights belong to their parent relation's scope.
+Relation names from `$with` are captured with the `$with` insight operator. Nested `$with` insights bubble up to the parent with dot-notation prefixed field names, and each relation also carries its own scoped `insights`:
+
+```ts
+const controls: UniqueryControls = {
+  $with: [
+    {
+      name: 'tasks',
+      filter: {},
+      controls: {
+        $with: [
+          { name: 'comments', filter: { body: { $regex: 'Great' } }, controls: {} },
+        ],
+      },
+    },
+  ],
+}
+
+const insights = computeInsights({}, controls)
+// Map {
+//   'tasks'               => Set { '$with' },
+//   'tasks.comments'      => Set { '$with' },
+//   'tasks.comments.body' => Set { '$regex' },
+// }
+
+// Each relation also has its own scoped insights:
+// tasks.insights        => Map { 'comments' => Set { '$with' }, 'comments.body' => Set { '$regex' } }
+// comments.insights     => Map { 'body' => Set { '$regex' } }
+```
 
 Use cases: field whitelisting, operator auditing, index planning, relation validation.
 
@@ -266,8 +292,8 @@ const insights = getInsights(query)
 | `ComparisonNode<T>` | Leaf node with typed field comparisons |
 | `LogicalNode<T>` | `{ $and: ... } \| { $or: ... } \| { $not: ... }` — variants are mutually exclusive via `never` |
 | `UniqueryControls<T>` | Pagination, sorting, projection — `$select`/`$sort` constrained to `keyof T` when typed |
-| `Uniquery<T>` | `{ filter: FilterExpr<T>, controls: UniqueryControls<T>, insights?: UniqueryInsights }` |
-| `WithRelation` | Relation sub-query — extends `UniqueryControls` (minus `$count`) with `name` and `filter` |
+| `Uniquery<T>` | `{ name?, filter, controls, insights? }` — root query (no name) or nested relation (with name) |
+| `WithRelation` | `Uniquery & { name: string }` — a `$with` relation with a required name |
 | `InsightOp` | `ComparisonOp \| '$select' \| '$order' \| '$with'` |
 | `UniqueryInsights` | `Map<string, Set<InsightOp>>` |
 

package/dist/index.cjs

@@ -8,6 +8,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 * - Bare primitive values are normalized to `comparison(field, '$eq', value)`.
 * - Multi-field ComparisonNodes are combined via `visitor.and(...)`.
 */ function walkFilter(expr, visitor) {
+	if (!expr) return void 0;
 	if ("$and" in expr && expr.$and !== void 0) {
 		const children = expr.$and.map((child) => walkFilter(child, visitor));
 		return visitor.and(children);
@@ -54,25 +55,34 @@ function isPrimitive(x) {
 		}
 		set.add(op);
 	}
-	walkFilter(filter, {
+	const visitor = {
 		comparison(field, op) {
 			capture(field, op);
 		},
 		and() {},
 		or() {},
 		not() {}
-	});
+	};
+	if (filter) walkFilter(filter, visitor);
 	if (controls?.$select) if (Array.isArray(controls.$select)) for (const field of controls.$select) capture(field, "$select");
 	else for (const field of Object.keys(controls.$select)) capture(field, "$select");
 	if (controls?.$sort) for (const field of Object.keys(controls.$sort)) capture(field, "$order");
-	if (controls?.$with) for (const rel of controls.$with) capture(rel.name, "$with");
+	if (controls?.$with) for (const rel of controls.$with) {
+		capture(rel.name, "$with");
+		const nested = rel.insights ?? computeInsights(rel.filter, rel.controls);
+		if (nested.size) rel.insights = nested;
+		for (const [field, ops] of nested) {
+			const prefixed = `${rel.name}.${field}`;
+			for (const op of ops) capture(prefixed, op);
+		}
+	}
 	return insights;
 }
 /**
 * Return insights for a query — uses pre-computed insights when present,
 * computes lazily otherwise.
 */ function getInsights(query) {
-	return query.insights ?? computeInsights(query.filter, query.controls);
+	return query.insights ?? computeInsights(query.filter ?? {}, query.controls);
 }
 
 //#endregion

package/dist/index.d.ts

@@ -65,32 +65,62 @@ type LogicalNode<T = Record<string, unknown>> = {
     $and?: never;
     $or?: never;
 };
-/** A relation to populate alongside the primary query. */
-interface WithRelation extends Omit<UniqueryControls, '$count'> {
-    /** Relation name (e.g. "posts", "posts.author"). */
-    name: string;
-    /** Filter scoped to this relation. */
-    filter?: FilterExpr;
-}
 /** Query controls (pagination, projection, sorting). Generic `T` constrains field names in `$select` and `$sort`. */
-interface UniqueryControls<T = Record<string, unknown>> {
+interface UniqueryControls<T = Record<string, unknown>, Nav extends Record<string, unknown> = Record<string, unknown>> {
     $sort?: Partial<Record<keyof T & string, 1 | -1>>;
     $skip?: number;
     $limit?: number;
     $count?: boolean;
     $select?: (keyof T & string)[] | Partial<Record<keyof T & string, 0 | 1>>;
-    /** Relations to populate alongside the primary query. */
-    $with?: WithRelation[];
+    /** Relations to populate alongside the query. */
+    $with?: TypedWithRelation<Nav>[];
     /** Pass-through for unknown $-prefixed keywords. */
     [key: `$${string}`]: unknown;
 }
-/** Top-level query: filter tree + controls. */
-interface Uniquery<T = Record<string, unknown>> {
-    filter: FilterExpr<T>;
-    controls: UniqueryControls<T>;
-    /** Pre-computed insights. When present, consumers should use `getInsights()` which trusts these instead of recomputing. */
+/**
+ * Canonical query representation.
+ * When `name` is present this is a nested relation (sub-query inside `$with`).
+ * When absent it is the root query.
+ */
+interface Uniquery<T = Record<string, unknown>, Nav extends Record<string, unknown> = Record<string, unknown>> {
+    /** Relation name. Present only for nested `$with` sub-queries. */
+    name?: string;
+    filter?: FilterExpr<T>;
+    controls?: UniqueryControls<T, Nav>;
+    /** Pre-computed insights. */
     insights?: UniqueryInsights;
 }
+/** Unwrap array types to get the element type for nav props. */
+type NavTarget<T> = T extends Array<infer U> ? U : T;
+/**
+ * A typed $with relation entry.
+ * When Nav is typed (from __navProps), name is constrained to known nav prop keys.
+ * Each entry gets its own filter/controls typed to the target entity.
+ * Falls back to untyped WithRelation when Nav has no known keys.
+ */
+type TypedWithRelation<Nav extends Record<string, unknown>> = [
+    keyof Nav & string
+] extends [never] ? WithRelation : {
+    [K in keyof Nav & string]: {
+        name: K;
+        filter?: FilterExpr<NavTarget<Nav[K]> extends {
+            __ownProps: infer F;
+        } ? F : Record<string, unknown>>;
+        controls?: UniqueryControls<NavTarget<Nav[K]> extends {
+            __ownProps: infer F;
+        } ? F : Record<string, unknown>, NavTarget<Nav[K]> extends {
+            __navProps: infer N extends Record<string, unknown>;
+        } ? N : Record<string, unknown>>;
+        insights?: UniqueryInsights;
+    };
+}[keyof Nav & string];
+/** Untyped $with relation — used when Nav generic is not provided. */
+type WithRelation = {
+    name: string;
+    filter?: FilterExpr;
+    controls?: UniqueryControls;
+    insights?: UniqueryInsights;
+};
 /** Insight operator includes comparison ops plus control-derived ops. */
 type InsightOp = ComparisonOp | '$select' | '$order' | '$with';
 /** Map of field names to the set of operators used on that field. */
@@ -119,7 +149,7 @@ interface FilterVisitor<R> {
  * - Bare primitive values are normalized to `comparison(field, '$eq', value)`.
  * - Multi-field ComparisonNodes are combined via `visitor.and(...)`.
  */
-declare function walkFilter<R>(expr: FilterExpr, visitor: FilterVisitor<R>): R;
+declare function walkFilter<R>(expr: FilterExpr | undefined, visitor: FilterVisitor<R>): R | undefined;
 declare function isPrimitive(x: unknown): x is Primitive;
 
 /**
@@ -127,7 +157,7 @@ declare function isPrimitive(x: unknown): x is Primitive;
  * This is the lazy counterpart to the eager insight capture done during
  * URL parsing.
  */
-declare function computeInsights(filter: FilterExpr, controls?: UniqueryControls): UniqueryInsights;
+declare function computeInsights(filter?: FilterExpr, controls?: UniqueryControls): UniqueryInsights;
 /**
  * Return insights for a query — uses pre-computed insights when present,
  * computes lazily otherwise.
@@ -135,4 +165,4 @@ declare function computeInsights(filter: FilterExpr, controls?: UniqueryControls
 declare function getInsights(query: Uniquery): UniqueryInsights;
 
 export { computeInsights, getInsights, isPrimitive, walkFilter };
-export type { ComparisonNode, ComparisonOp, FieldOps, FieldOpsFor, FieldValue, FilterExpr, FilterVisitor, InsightOp, LogicalNode, Primitive, Uniquery, UniqueryControls, UniqueryInsights, WithRelation };
+export type { ComparisonNode, ComparisonOp, FieldOps, FieldOpsFor, FieldValue, FilterExpr, FilterVisitor, InsightOp, LogicalNode, NavTarget, Primitive, TypedWithRelation, Uniquery, UniqueryControls, UniqueryInsights, WithRelation };

package/dist/index.mjs

@@ -6,6 +6,7 @@
 * - Bare primitive values are normalized to `comparison(field, '$eq', value)`.
 * - Multi-field ComparisonNodes are combined via `visitor.and(...)`.
 */ function walkFilter(expr, visitor) {
+	if (!expr) return void 0;
 	if ("$and" in expr && expr.$and !== void 0) {
 		const children = expr.$and.map((child) => walkFilter(child, visitor));
 		return visitor.and(children);
@@ -52,25 +53,34 @@ function isPrimitive(x) {
 		}
 		set.add(op);
 	}
-	walkFilter(filter, {
+	const visitor = {
 		comparison(field, op) {
 			capture(field, op);
 		},
 		and() {},
 		or() {},
 		not() {}
-	});
+	};
+	if (filter) walkFilter(filter, visitor);
 	if (controls?.$select) if (Array.isArray(controls.$select)) for (const field of controls.$select) capture(field, "$select");
 	else for (const field of Object.keys(controls.$select)) capture(field, "$select");
 	if (controls?.$sort) for (const field of Object.keys(controls.$sort)) capture(field, "$order");
-	if (controls?.$with) for (const rel of controls.$with) capture(rel.name, "$with");
+	if (controls?.$with) for (const rel of controls.$with) {
+		capture(rel.name, "$with");
+		const nested = rel.insights ?? computeInsights(rel.filter, rel.controls);
+		if (nested.size) rel.insights = nested;
+		for (const [field, ops] of nested) {
+			const prefixed = `${rel.name}.${field}`;
+			for (const op of ops) capture(prefixed, op);
+		}
+	}
 	return insights;
 }
 /**
 * Return insights for a query — uses pre-computed insights when present,
 * computes lazily otherwise.
 */ function getInsights(query) {
-	return query.insights ?? computeInsights(query.filter, query.controls);
+	return query.insights ?? computeInsights(query.filter ?? {}, query.controls);
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqu/core",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Canonical query format types, tree walker, and utilities for Uniqu",
   "license": "MIT",
   "author": "Artem Maltsev",