@uniqu/core 0.1.0 → 0.1.2

package/README.md

@@ -83,6 +83,7 @@ A `FilterExpr` is either a **comparison node** (leaf) or a **logical node** (bra
 | `$count` | `boolean` | Request total count |
 | `$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 |
+| `$having` | `FilterExpr` | Post-aggregation filter on aliases and dimension fields |
 | `$with` | `(WithRelation \| string)[]` | Relations to populate alongside the primary query |
 | `$<custom>` | `unknown` | Arbitrary pass-through keywords |
 
@@ -164,6 +165,36 @@ interface AggregateExpr {
 
 Known functions are `sum`, `count`, `avg`, `min`, `max` (`AggregateFn`), but `$fn` accepts any string for extensibility — consumers validate and execute supported functions.
 
+#### Post-Aggregation Filter (`$having`)
+
+`$having` filters groups after aggregation — the equivalent of SQL `HAVING`. It operates on aggregate result aliases and dimension fields:
+
+```ts
+const query: Uniquery = {
+  filter: { status: 'active' },
+  controls: {
+    $select: [
+      'currency',
+      { $fn: 'sum', $field: 'amount', $as: 'total' },
+    ],
+    $groupBy: ['currency'],
+    $having: { total: { $gt: 1000 } },
+    $sort: { total: -1 },
+  },
+}
+```
+
+`$having` accepts a full `FilterExpr` — logical operators (`$and`, `$or`, `$not`) and all comparison operators are supported. It is untyped (`FilterExpr` without a generic) because its fields are aggregate aliases that don't exist on the entity type `T`.
+
+Insights track `$having` fields with the `'$having'` op:
+
+```ts
+// insights for the query above:
+// 'total'    => Set { '$having', '$order' }
+// 'currency' => Set { '$select', '$groupBy' }
+// 'amount'   => Set { 'sum' }
+```
+
 Insights track aggregate usage with bare function names (not `$`-prefixed), making it easy to distinguish controls from aggregates:
 
 ```ts
@@ -341,13 +372,17 @@ const insights = getInsights(query)
 | `ComparisonNode<T>` | Leaf node — keys constrained to `keyof T` when typed |
 | `LogicalNode<T>` | `{ $and: ... } \| { $or: ... } \| { $not: ... }` — variants are mutually exclusive via `never` |
 | `AggregateFn` | `'sum' \| 'count' \| 'avg' \| 'min' \| 'max'` |
-| `AggregateExpr` | `{ $fn, $field, $as? }` — aggregate function call in `$select` |
+| `AggregateExpr<Fn, Field, Alias>` | `{ $fn, $field, $as? }` — aggregate function call in `$select`. Generic params preserve literal types for result inference |
 | `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 |
+| `UniqueryControls<T>` | Pagination, sorting, projection, grouping, `$having` — `$select`/`$sort`/`$groupBy` constrained to `keyof T` when typed |
 | `Uniquery<T>` | `{ name?, filter, controls, insights? }` — root query (no name) or nested relation (with name) |
 | `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` |
+| `AggregateControls<T, D, M>` | Typed aggregate controls — `$groupBy` required, `$with` forbidden, `$select` constrained to dimensions + aggregates |
+| `AggregateQuery<T, D, M>` | Typed aggregate query — `{ filter?, controls, insights? }` with dimension/measure constraints |
+| `AggregateResult<T, Select>` | Infer result row type from `$select` — dimensions preserve original types, aggregates → `number` (min/max preserve field type) |
+| `ResolveAlias<A>` | Resolve the output alias of an `AggregateExpr` — uses `$as` if provided, otherwise `{fn}_{field}` |
+| `InsightOp` | `ComparisonOp \| '$select' \| '$order' \| '$with' \| '$groupBy' \| '$having' \| AggregateFn \| string` |
 | `UniqueryInsights` | `Map<string, Set<InsightOp>>` |
 
 ### Functions

package/dist/index.cjs

@@ -72,7 +72,21 @@ function isPrimitive(x) {
 	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?.$having) walkFilter(controls.$having, {
+		comparison(field) {
+			capture(field, "$having");
+		},
+		and() {},
+		or() {},
+		not() {}
+	});
+	if (controls?.$sort) {
+		let aliasToField;
+		if (Array.isArray(controls.$select)) {
+			for (const entry of controls.$select) if (typeof entry !== "string" && entry.$as) (aliasToField ?? (aliasToField = /* @__PURE__ */ new Map())).set(entry.$as, entry.$field);
+		}
+		for (const field of Object.keys(controls.$sort)) capture(aliasToField?.get(field) ?? field, "$order");
+	}
 	if (controls?.$with) for (const entry of controls.$with) {
 		if (typeof entry === "string") {
 			capture(entry, "$with");

package/dist/index.d.ts

@@ -67,14 +67,14 @@ type LogicalNode<T = Record<string, unknown>> = {
 };
 /** 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 {
+/** A single aggregate function call within $select. Generic params preserve literal types for result inference. */
+interface AggregateExpr<Fn extends string = AggregateFn | (string & {}), Field extends string = string, Alias extends string = string> {
     /** Function name (sum, count, avg, min, max, or custom). */
-    $fn: AggregateFn | (string & {});
+    $fn: Fn;
     /** Field to aggregate. '*' for count(*). */
-    $field: string;
+    $field: Field;
     /** Alias for the result. Auto-generated by URL parser if omitted. */
-    $as?: string;
+    $as?: Alias;
 }
 /**
  * Projection definition.
@@ -92,6 +92,8 @@ interface UniqueryControls<T = Record<string, unknown>, Nav extends Record<strin
     $select?: SelectExpr<T>;
     /** Fields to group by for aggregate queries. */
     $groupBy?: (keyof T & string)[];
+    /** Post-aggregation filter. Operates on aggregate aliases and dimension fields. */
+    $having?: FilterExpr;
     /** Relations to populate alongside the query. */
     $with?: TypedWithRelation<Nav>[];
     /** Pass-through for unknown $-prefixed keywords. */
@@ -145,9 +147,46 @@ type WithRelation = {
  * 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 & {});
+type InsightOp = ComparisonOp | '$select' | '$order' | '$with' | '$groupBy' | '$having' | AggregateFn | (string & {});
 /** Map of field names to the set of operators used on that field. */
 type UniqueryInsights = Map<string, Set<InsightOp>>;
+/** Aggregate query controls. Separate from UniqueryControls: $groupBy is required, $with is forbidden. */
+interface AggregateControls<T = Record<string, unknown>, D extends keyof T & string = keyof T & string, M extends keyof T & string = keyof T & string> {
+    $groupBy: D[];
+    $select?: (D | AggregateExpr<AggregateFn, M | '*'>)[];
+    $having?: FilterExpr;
+    $sort?: Record<string, 1 | -1>;
+    $skip?: number;
+    $limit?: number;
+    $count?: boolean;
+    [key: `$${string}`]: unknown;
+}
+/** Aggregate query — no name (can't nest), no Nav (no $with). */
+interface AggregateQuery<T = Record<string, unknown>, D extends keyof T & string = keyof T & string, M extends keyof T & string = keyof T & string> {
+    filter?: FilterExpr<T>;
+    controls: AggregateControls<T, D, M>;
+    insights?: UniqueryInsights;
+}
+/** Resolve the output alias of an AggregateExpr. Uses $as if provided, otherwise generates {fn}_{field}. */
+type ResolveAlias<A extends AggregateExpr> = A extends {
+    $as: infer Alias extends string;
+} ? Alias : A extends {
+    $fn: infer Fn extends string;
+    $field: infer F extends string;
+} ? `${Fn}_${F}` : string;
+/**
+ * Infer the result row type from an aggregate query's $select.
+ * Dimension fields preserve their original type from T.
+ * Aggregate expressions: min/max preserve original type, others → number.
+ */
+type AggregateResult<T, Select extends readonly (string | AggregateExpr)[]> = {
+    [K in Extract<Select[number], string> & keyof T]: T[K];
+} & {
+    [A in Extract<Select[number], AggregateExpr> as ResolveAlias<A>]: A extends {
+        $fn: 'min' | 'max';
+        $field: infer F extends keyof T & string;
+    } ? T[F] : number;
+};
 
 /**
  * Visitor callbacks for controlling how filter nodes are processed.
@@ -188,4 +227,4 @@ declare function computeInsights(filter?: FilterExpr, controls?: UniqueryControl
 declare function getInsights(query: Uniquery): UniqueryInsights;
 
 export { computeInsights, getInsights, isPrimitive, walkFilter };
-export type { AggregateExpr, AggregateFn, ComparisonNode, ComparisonOp, FieldOps, FieldOpsFor, FieldValue, FilterExpr, FilterVisitor, InsightOp, LogicalNode, NavTarget, Primitive, SelectExpr, TypedWithRelation, Uniquery, UniqueryControls, UniqueryInsights, WithRelation };
+export type { AggregateControls, AggregateExpr, AggregateFn, AggregateQuery, AggregateResult, ComparisonNode, ComparisonOp, FieldOps, FieldOpsFor, FieldValue, FilterExpr, FilterVisitor, InsightOp, LogicalNode, NavTarget, Primitive, ResolveAlias, SelectExpr, TypedWithRelation, Uniquery, UniqueryControls, UniqueryInsights, WithRelation };

package/dist/index.mjs

@@ -70,7 +70,21 @@ function isPrimitive(x) {
 	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?.$having) walkFilter(controls.$having, {
+		comparison(field) {
+			capture(field, "$having");
+		},
+		and() {},
+		or() {},
+		not() {}
+	});
+	if (controls?.$sort) {
+		let aliasToField;
+		if (Array.isArray(controls.$select)) {
+			for (const entry of controls.$select) if (typeof entry !== "string" && entry.$as) (aliasToField ?? (aliasToField = /* @__PURE__ */ new Map())).set(entry.$as, entry.$field);
+		}
+		for (const field of Object.keys(controls.$sort)) capture(aliasToField?.get(field) ?? field, "$order");
+	}
 	if (controls?.$with) for (const entry of controls.$with) {
 		if (typeof entry === "string") {
 			capture(entry, "$with");

package/package.json

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