@uniqu/core 0.0.1 → 0.0.3

package/README.md

@@ -82,8 +82,50 @@ 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 `WithRelation` is a self-contained sub-query with its own filter, sort, pagination, projection, and nested `$with`:
+
+```ts
+import type { Uniquery, WithRelation } from '@uniqu/core'
+
+const query: Uniquery = {
+  filter: { status: 'active' },
+  controls: {
+    $with: [
+      {
+        name: 'posts',
+        filter: { status: 'published' },
+        $sort: { createdAt: -1 },
+        $limit: 5,
+        $select: ['title', 'body'],
+        $with: [
+          { name: 'comments', $limit: 10 },
+          { name: 'author' },
+        ],
+      },
+      { name: 'profile' },
+    ],
+  },
+}
+```
+
+`WithRelation` extends `UniqueryControls` (minus `$count`) and adds `name` and `filter`:
+
+```ts
+interface WithRelation extends Omit<UniqueryControls, '$count'> {
+  name: string
+  filter?: FilterExpr
+}
+```
+
+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.
+
+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 +232,13 @@ const insights = computeInsights(query.filter, query.controls)
 //   'createdAt' => Set { '$order' },
 //   'name'      => Set { '$select' },
 //   'email'     => Set { '$select' },
+//   'posts'     => Set { '$with' },
 // }
 ```
 
-Use cases: field whitelisting, operator auditing, index planning.
+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.
+
+Use cases: field whitelisting, operator auditing, index planning, relation validation.
 
 ### `getInsights`
 
@@ -222,7 +267,8 @@ const insights = getInsights(query)
 | `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'` |
+| `WithRelation` | Relation sub-query — extends `UniqueryControls` (minus `$count`) with `name` and `filter` |
+| `InsightOp` | `ComparisonOp \| '$select' \| '$order' \| '$with'` |
 | `UniqueryInsights` | `Map<string, Set<InsightOp>>` |
 
 ### Functions

package/dist/index.cjs

@@ -32,7 +32,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 	return results.length === 1 ? results[0] : visitor.and(results);
 }
 function isPrimitive(x) {
-	return x === null || typeof x === "string" || typeof x === "number" || typeof x === "boolean" || x instanceof RegExp || x instanceof Date;
+	if (x === null || typeof x !== "object") return true;
+	if (x instanceof RegExp || x instanceof Date) return true;
+	if (!Array.isArray(x) && x.constructor !== void 0 && x.constructor !== Object) return true;
+	return false;
 }
 
 //#endregion
@@ -62,6 +65,7 @@ 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");
 	return insights;
 }
 /**

package/dist/index.d.ts

@@ -65,6 +65,13 @@ 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>> {
     $sort?: Partial<Record<keyof T & string, 1 | -1>>;
@@ -72,6 +79,8 @@ 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 primary query. */
+    $with?: WithRelation[];
     /** Pass-through for unknown $-prefixed keywords. */
     [key: `$${string}`]: unknown;
 }
@@ -83,7 +92,7 @@ interface Uniquery<T = Record<string, unknown>> {
     insights?: UniqueryInsights;
 }
 /** 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 +135,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

@@ -30,7 +30,10 @@
 	return results.length === 1 ? results[0] : visitor.and(results);
 }
 function isPrimitive(x) {
-	return x === null || typeof x === "string" || typeof x === "number" || typeof x === "boolean" || x instanceof RegExp || x instanceof Date;
+	if (x === null || typeof x !== "object") return true;
+	if (x instanceof RegExp || x instanceof Date) return true;
+	if (!Array.isArray(x) && x.constructor !== void 0 && x.constructor !== Object) return true;
+	return false;
 }
 
 //#endregion
@@ -60,6 +63,7 @@ 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");
 	return insights;
 }
 /**

package/package.json

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