@uniqu/core 0.0.2 → 0.0.4

package/README.md

@@ -82,8 +82,49 @@ A `FilterExpr` is either a **comparison node** (leaf) or a **logical node** (bra
 | `$limit` | `number` | Limit to N results |
 | `$count` | `boolean` | Request total count |
 | `$select` | `string[] \| Record<string, 0 \| 1>` | Field projection — array for inclusion, object for exclusion/mixed |
+| `$with` | `WithRelation[]` | Relations to populate alongside the primary query |
 | `$<custom>` | `unknown` | Arbitrary pass-through keywords |
 
+### Relation Loading (`$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'
+
+const query: Uniquery = {
+  filter: { status: 'active' },
+  controls: {
+    $with: [
+      {
+        name: 'posts',
+        filter: { status: 'published' },
+        controls: {
+          $sort: { createdAt: -1 },
+          $limit: 5,
+          $select: ['title', 'body'],
+          $with: [
+            { name: 'comments', filter: {}, controls: { $limit: 10 } },
+            { name: 'author', filter: {}, controls: {} },
+          ],
+        },
+      },
+      { name: 'profile', filter: {}, controls: {} },
+    ],
+  },
+}
+```
+
+`WithRelation` is a `Uniquery` with a required `name`:
+
+```ts
+type WithRelation = Uniquery & { name: string }
+```
+
+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.
+
 ## Type-Safe Filters
 
 `FilterExpr<T>` accepts a generic entity type for compile-time field and value checking. Dot-notation paths are always allowed for nested access:
@@ -190,10 +231,40 @@ const insights = computeInsights(query.filter, query.controls)
 //   'createdAt' => Set { '$order' },
 //   'name'      => Set { '$select' },
 //   'email'     => Set { '$select' },
+//   'posts'     => Set { '$with' },
+// }
+```
+
+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.
+Use cases: field whitelisting, operator auditing, index planning, relation validation.
 
 ### `getInsights`
 
@@ -221,8 +292,9 @@ 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 }` |
-| `InsightOp` | `ComparisonOp \| '$select' \| '$order'` |
+| `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>>` |
 
 ### Functions

package/dist/index.cjs

@@ -65,6 +65,15 @@ function isPrimitive(x) {
 	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");
+		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;
 }
 /**

package/dist/index.d.ts

@@ -72,18 +72,30 @@ interface UniqueryControls<T = Record<string, unknown>> {
     $limit?: number;
     $count?: boolean;
     $select?: (keyof T & string)[] | Partial<Record<keyof T & string, 0 | 1>>;
+    /** Relations to populate alongside the query. */
+    $with?: WithRelation[];
     /** Pass-through for unknown $-prefixed keywords. */
     [key: `$${string}`]: unknown;
 }
-/** Top-level query: filter tree + controls. */
+/**
+ * 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>> {
+    /** Relation name. Present only for nested `$with` sub-queries. */
+    name?: string;
     filter: FilterExpr<T>;
     controls: UniqueryControls<T>;
-    /** Pre-computed insights. When present, consumers should use `getInsights()` which trusts these instead of recomputing. */
+    /** Pre-computed insights. */
     insights?: UniqueryInsights;
 }
+/** A `$with` relation — a `Uniquery` with a required `name`. */
+type WithRelation = Uniquery & {
+    name: string;
+};
 /** Insight operator includes comparison ops plus control-derived ops. */
-type InsightOp = ComparisonOp | '$select' | '$order';
+type InsightOp = ComparisonOp | '$select' | '$order' | '$with';
 /** Map of field names to the set of operators used on that field. */
 type UniqueryInsights = Map<string, Set<InsightOp>>;
 
@@ -126,4 +138,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 };
+export type { ComparisonNode, ComparisonOp, FieldOps, FieldOpsFor, FieldValue, FilterExpr, FilterVisitor, InsightOp, LogicalNode, Primitive, Uniquery, UniqueryControls, UniqueryInsights, WithRelation };

package/dist/index.mjs

@@ -63,6 +63,15 @@ function isPrimitive(x) {
 	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");
+		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;
 }
 /**

package/package.json

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