@uniqu/core 0.0.6 → 0.1.0

package/README.md

@@ -81,13 +81,14 @@ A `FilterExpr` is either a **comparison node** (leaf) or a **logical node** (bra
 | `$skip` | `number` | Skip N results |
 | `$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 |
+| `$select` | `SelectExpr<T>` | Field projection — array of strings/aggregates for inclusion, object for exclusion/mixed |
+| `$groupBy` | `(keyof T & string)[]` | Fields to group by for aggregate queries |
+| `$with` | `(WithRelation \| string)[]` | 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`:
+`$with` declares which relations to populate alongside the primary query. Each entry can be a **string** (relation name only) or a full **object** (a `WithRelation` sub-query with its own `filter`, `controls`, and `insights`):
 
 ```ts
 import type { Uniquery, WithRelation } from '@uniqu/core'
@@ -96,6 +97,9 @@ const query: Uniquery = {
   filter: { status: 'active' },
   controls: {
     $with: [
+      // String shorthand — just the relation name
+      'profile',
+      // Object form — full sub-query
       {
         name: 'posts',
         filter: { status: 'published' },
@@ -105,11 +109,10 @@ const query: Uniquery = {
           $select: ['title', 'body'],
           $with: [
             { name: 'comments', filter: {}, controls: { $limit: 10 } },
-            { name: 'author', filter: {}, controls: {} },
+            'author',
           ],
         },
       },
-      { name: 'profile', filter: {}, controls: {} },
     ],
   },
 }
@@ -121,13 +124,59 @@ const query: Uniquery = {
 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.
+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` object 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.
+
+When a `Nav` generic is provided, string entries and `name` fields are constrained to `keyof Nav & string`. Without a generic, any string is accepted.
 
 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.
 
+### Aggregation (`$groupBy` + `$select`)
+
+`$groupBy` declares grouping fields. Aggregate functions appear as `AggregateExpr` objects in the `$select` array alongside plain field names:
+
+```ts
+import type { Uniquery, AggregateExpr } from '@uniqu/core'
+
+const query: Uniquery = {
+  filter: { status: 'active' },
+  controls: {
+    $select: [
+      'currency',
+      { $fn: 'sum', $field: 'amount', $as: 'total' },
+      { $fn: 'count', $field: '*', $as: 'count' },
+    ],
+    $groupBy: ['currency'],
+    $sort: { total: -1 },
+    $limit: 10,
+  },
+}
+```
+
+`AggregateExpr` has three fields:
+
+```ts
+interface AggregateExpr {
+  $fn: AggregateFn | (string & {})  // 'sum' | 'count' | 'avg' | 'min' | 'max' | custom
+  $field: string                     // field name, or '*' for count(*)
+  $as?: string                       // optional alias for the result
+}
+```
+
+Known functions are `sum`, `count`, `avg`, `min`, `max` (`AggregateFn`), but `$fn` accepts any string for extensibility — consumers validate and execute supported functions.
+
+Insights track aggregate usage with bare function names (not `$`-prefixed), making it easy to distinguish controls from aggregates:
+
+```ts
+// insights for the query above:
+// 'currency' => Set { '$select', '$groupBy' }
+// 'amount'   => Set { 'sum' }
+// '*'        => Set { 'count' }
+// 'total'    => Set { '$order' }
+```
+
 ## 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:
+`FilterExpr<T>` accepts a generic entity type for compile-time field and value checking:
 
 ```ts
 interface User {
@@ -140,12 +189,12 @@ const filter: FilterExpr<User> = {
   name: 'John',              // string — ok
   age: { $gte: 18 },         // number — ok
   active: true,              // boolean — ok
-  'address.city': 'NYC',     // dot-notation — always allowed
   // age: { $gte: 'old' },   // type error: string not assignable to number
+  // foo: 'bar',             // type error: 'foo' is not a key of User
 }
 ```
 
-Without a generic argument, `FilterExpr` accepts any string keys with any values (untyped mode).
+When typed, only keys of `T` are allowed — no arbitrary string keys. Without a generic argument, `FilterExpr` accepts any string keys with any values (untyped mode).
 
 ### Type-Safe Controls
 
@@ -289,12 +338,16 @@ const insights = getInsights(query)
 | `FieldOps` | Untyped operator map (`FieldOpsFor<Primitive>`) |
 | `FieldValue` | `Primitive \| FieldOps` |
 | `FilterExpr<T>` | `ComparisonNode<T> \| LogicalNode<T>` |
-| `ComparisonNode<T>` | Leaf node with typed field comparisons |
+| `ComparisonNode<T>` | Leaf node — keys constrained to `keyof T` when typed |
 | `LogicalNode<T>` | `{ $and: ... } \| { $or: ... } \| { $not: ... }` — variants are mutually exclusive via `never` |
-| `UniqueryControls<T>` | Pagination, sorting, projection — `$select`/`$sort` constrained to `keyof T` when typed |
+| `AggregateFn` | `'sum' \| 'count' \| 'avg' \| 'min' \| 'max'` |
+| `AggregateExpr` | `{ $fn, $field, $as? }` — aggregate function call in `$select` |
+| `SelectExpr<T>` | `((keyof T & string) \| AggregateExpr)[] \| Record<keyof T & string, 0 \| 1>` |
+| `UniqueryControls<T>` | Pagination, sorting, projection, grouping — `$select`/`$sort`/`$groupBy` constrained to `keyof T` when typed |
 | `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'` |
+| `TypedWithRelation<Nav>` | Typed `$with` entry — `keyof Nav & string` or object with typed filter/controls |
+| `WithRelation` | Untyped `$with` relation with `{ name: string, filter?, controls?, insights? }` |
+| `InsightOp` | `ComparisonOp \| '$select' \| '$order' \| '$with' \| '$groupBy' \| AggregateFn \| string` |
 | `UniqueryInsights` | `Map<string, Set<InsightOp>>` |
 
 ### Functions

package/dist/index.cjs

@@ -10,11 +10,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 */ 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));
+		const andArr = expr.$and;
+		const children = [];
+		for (const child of andArr) children.push(walkFilter(child, visitor));
 		return visitor.and(children);
 	}
 	if ("$or" in expr && expr.$or !== void 0) {
-		const children = expr.$or.map((child) => walkFilter(child, visitor));
+		const orArr = expr.$or;
+		const children = [];
+		for (const child of orArr) children.push(walkFilter(child, visitor));
 		return visitor.or(children);
 	}
 	if ("$not" in expr && expr.$not !== void 0) {
@@ -64,15 +68,21 @@ function isPrimitive(x) {
 		not() {}
 	};
 	if (filter) walkFilter(filter, visitor);
-	if (controls?.$select) if (Array.isArray(controls.$select)) for (const field of controls.$select) capture(field, "$select");
+	if (controls?.$select) if (Array.isArray(controls.$select)) for (const entry of controls.$select) if (typeof entry === "string") capture(entry, "$select");
+	else capture(entry.$field, entry.$fn);
 	else for (const field of Object.keys(controls.$select)) capture(field, "$select");
+	if (controls?.$groupBy) for (const field of controls.$groupBy) capture(field, "$groupBy");
 	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;
+	if (controls?.$with) for (const entry of controls.$with) {
+		if (typeof entry === "string") {
+			capture(entry, "$with");
+			continue;
+		}
+		capture(entry.name, "$with");
+		const nested = entry.insights ?? computeInsights(entry.filter, entry.controls);
+		if (nested.size) entry.insights = nested;
 		for (const [field, ops] of nested) {
-			const prefixed = `${rel.name}.${field}`;
+			const prefixed = `${entry.name}.${field}`;
 			for (const op of ops) capture(prefixed, op);
 		}
 	}

package/dist/index.d.ts

@@ -41,12 +41,12 @@ type FieldValue = Primitive | FieldOps;
 type FilterExpr<T = Record<string, unknown>> = ComparisonNode<T> | LogicalNode<T>;
 /**
  * Leaf node: one or more field comparisons.
- * Known keys from `T` get typed values; arbitrary string keys
- * (e.g. dot-notation paths like `"client.age"`) are always allowed.
+ * When `T` is typed, only known keys are allowed.
+ * When untyped (default), any string key is accepted.
  */
 type ComparisonNode<T = Record<string, unknown>> = {
     [K in keyof T & string]?: T[K] | FieldOpsFor<T[K]>;
-} & Record<string, unknown>;
+};
 /**
  * Branch node: logical combination of child expressions.
  * Each variant forbids the other logical keys via `never` to prevent
@@ -65,13 +65,33 @@ type LogicalNode<T = Record<string, unknown>> = {
     $and?: never;
     $or?: never;
 };
-/** Query controls (pagination, projection, sorting). Generic `T` constrains field names in `$select` and `$sort`. */
+/** Known aggregate function names. Consumers may support additional functions via the (string & {}) escape hatch. */
+type AggregateFn = 'sum' | 'count' | 'avg' | 'min' | 'max';
+/** A single aggregate function call within $select. */
+interface AggregateExpr {
+    /** Function name (sum, count, avg, min, max, or custom). */
+    $fn: AggregateFn | (string & {});
+    /** Field to aggregate. '*' for count(*). */
+    $field: string;
+    /** Alias for the result. Auto-generated by URL parser if omitted. */
+    $as?: string;
+}
+/**
+ * Projection definition.
+ * - Array form: inclusion list with optional aggregates.
+ *   Plain strings select fields; AggregateExpr objects define computed columns.
+ * - Object form: inclusion/exclusion map (0 or 1 per field). No aggregates in this form.
+ */
+type SelectExpr<T = Record<string, unknown>> = ((keyof T & string) | AggregateExpr)[] | Partial<Record<keyof T & string, 0 | 1>>;
+/** Query controls (pagination, projection, sorting, grouping). Generic `T` constrains field names. */
 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>>;
+    $select?: SelectExpr<T>;
+    /** Fields to group by for aggregate queries. */
+    $groupBy?: (keyof T & string)[];
     /** Relations to populate alongside the query. */
     $with?: TypedWithRelation<Nav>[];
     /** Pass-through for unknown $-prefixed keywords. */
@@ -100,7 +120,7 @@ type NavTarget<T> = T extends Array<infer U> ? U : T;
  */
 type TypedWithRelation<Nav extends Record<string, unknown>> = [
     keyof Nav & string
-] extends [never] ? WithRelation : {
+] extends [never] ? WithRelation | string : {
     [K in keyof Nav & string]: {
         name: K;
         filter?: FilterExpr<NavTarget<Nav[K]> extends {
@@ -113,7 +133,7 @@ type TypedWithRelation<Nav extends Record<string, unknown>> = [
         } ? N : Record<string, unknown>>;
         insights?: UniqueryInsights;
     };
-}[keyof Nav & string];
+}[keyof Nav & string] | (keyof Nav & string);
 /** Untyped $with relation — used when Nav generic is not provided. */
 type WithRelation = {
     name: string;
@@ -121,8 +141,11 @@ type WithRelation = {
     controls?: UniqueryControls;
     insights?: UniqueryInsights;
 };
-/** Insight operator includes comparison ops plus control-derived ops. */
-type InsightOp = ComparisonOp | '$select' | '$order' | '$with';
+/**
+ * Insight operator includes comparison ops, control ops ($-prefixed),
+ * and aggregate function names (bare, e.g. 'sum', 'avg').
+ */
+type InsightOp = ComparisonOp | '$select' | '$order' | '$with' | '$groupBy' | AggregateFn | (string & {});
 /** Map of field names to the set of operators used on that field. */
 type UniqueryInsights = Map<string, Set<InsightOp>>;
 
@@ -165,4 +188,4 @@ declare function computeInsights(filter?: FilterExpr, controls?: UniqueryControl
 declare function getInsights(query: Uniquery): UniqueryInsights;
 
 export { computeInsights, getInsights, isPrimitive, walkFilter };
-export type { ComparisonNode, ComparisonOp, FieldOps, FieldOpsFor, FieldValue, FilterExpr, FilterVisitor, InsightOp, LogicalNode, NavTarget, Primitive, TypedWithRelation, Uniquery, UniqueryControls, UniqueryInsights, WithRelation };
+export type { AggregateExpr, AggregateFn, ComparisonNode, ComparisonOp, FieldOps, FieldOpsFor, FieldValue, FilterExpr, FilterVisitor, InsightOp, LogicalNode, NavTarget, Primitive, SelectExpr, TypedWithRelation, Uniquery, UniqueryControls, UniqueryInsights, WithRelation };

package/dist/index.mjs

@@ -8,11 +8,15 @@
 */ 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));
+		const andArr = expr.$and;
+		const children = [];
+		for (const child of andArr) children.push(walkFilter(child, visitor));
 		return visitor.and(children);
 	}
 	if ("$or" in expr && expr.$or !== void 0) {
-		const children = expr.$or.map((child) => walkFilter(child, visitor));
+		const orArr = expr.$or;
+		const children = [];
+		for (const child of orArr) children.push(walkFilter(child, visitor));
 		return visitor.or(children);
 	}
 	if ("$not" in expr && expr.$not !== void 0) {
@@ -62,15 +66,21 @@ function isPrimitive(x) {
 		not() {}
 	};
 	if (filter) walkFilter(filter, visitor);
-	if (controls?.$select) if (Array.isArray(controls.$select)) for (const field of controls.$select) capture(field, "$select");
+	if (controls?.$select) if (Array.isArray(controls.$select)) for (const entry of controls.$select) if (typeof entry === "string") capture(entry, "$select");
+	else capture(entry.$field, entry.$fn);
 	else for (const field of Object.keys(controls.$select)) capture(field, "$select");
+	if (controls?.$groupBy) for (const field of controls.$groupBy) capture(field, "$groupBy");
 	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;
+	if (controls?.$with) for (const entry of controls.$with) {
+		if (typeof entry === "string") {
+			capture(entry, "$with");
+			continue;
+		}
+		capture(entry.name, "$with");
+		const nested = entry.insights ?? computeInsights(entry.filter, entry.controls);
+		if (nested.size) entry.insights = nested;
 		for (const [field, ops] of nested) {
-			const prefixed = `${rel.name}.${field}`;
+			const prefixed = `${entry.name}.${field}`;
 			for (const op of ops) capture(prefixed, op);
 		}
 	}

package/package.json

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