@atscript/db-memory 0.1.131 → 0.1.133

package/README.md

@@ -96,7 +96,7 @@ Deliberate — matching a real engine here is hard or impossible and unnecessary
 - **No array-element matching** — the dot-path getter matches scalars and nested-object paths; Mongo-style implicit array-element / `$elemMatch` matching is not provided.
 - **Non-atomic stored batch writes** — `insertMany`/`updateMany`/`replaceMany`/`deleteMany` apply sequentially with no rollback; a mid-batch conflict leaves earlier items written. Single writes are safe. (Provider tables are read-only, so this never applies to the primary mode.)
 - **Provider tables are read-only, with no cross-request pagination stability** — page 1 and page 2 are separate requests over separate snapshots.
-- **No native aggregation** — `$groupBy` throws a typed `INVALID_QUERY` (clean 4xx, not 500).
+- **Aggregation is an in-process scan** — `$groupBy` / aggregates / calendar buckets / `$having` / `$count` run in JS over one snapshot with SQL semantics (null and missing group together; `sum`/`avg` over no value are `null`). Fine for the small sets this adapter targets; there is no index-backed grouping.
 - **Relations `$with`** — resolved by core's app-level batch loading, not natively.
 - **No FTS / vector / geo / `$search`** — unsupported.
 - **Not a production datastore** — nothing is persisted or shared across processes.

package/dist/index.cjs

@@ -1,5 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _atscript_db = require("@atscript/db");
+let _atscript_db_agg = require("@atscript/db/agg");
+let _uniqu_core = require("@uniqu/core");
 //#region src/lib/memory-filter.ts
 /**
 * Dot-path getter. Splits `path` on `.` and walks plain objects, returning the
@@ -22,22 +24,20 @@ function getPath(row, path) {
 	return current;
 }
 /**
-* Like {@link getPath}, but reports whether the FINAL key EXISTS rather than
-* its value. A key holding `null` counts as present. This is what lets
-* `$exists` distinguish a `null`-valued field (present) from an absent one —
-* a distinction {@link getPath} alone cannot make (both would read back as a
-* nullish value). Same array limitation as {@link getPath}.
+* {@link getPath} compiled for one path: split once, and a single segment is
+* a direct property read — for callers that read the same path off many rows.
 */
-function hasPath(row, path) {
+function pathReader(path) {
+	if (!path.includes(".")) return (row) => row[path];
 	const segments = path.split(".");
-	const last = segments.pop();
-	let current = row;
-	for (const seg of segments) {
-		if (current === null || typeof current !== "object" || Array.isArray(current)) return false;
-		current = current[seg];
-	}
-	if (current === null || typeof current !== "object" || Array.isArray(current)) return false;
-	return Object.prototype.hasOwnProperty.call(current, last);
+	return (row) => {
+		let current = row;
+		for (const seg of segments) {
+			if (current === null || typeof current !== "object" || Array.isArray(current)) return;
+			current = current[seg];
+		}
+		return current;
+	};
 }
 /**
 * Deep-equality for leaf values, used by `$eq`/`$ne`/`$in`/`$nin`.
@@ -170,7 +170,7 @@ const memoryVisitor = {
 					return fieldValue != null && regex.test(stringifyLeaf(fieldValue));
 				};
 			}
-			case "$exists": return (row) => value === hasPath(row, field);
+			case "$exists": return (row) => value === !evalEq(row, field, null);
 			default: throw new _atscript_db.DbError("INVALID_QUERY", [{
 				path: field,
 				message: `Unsupported filter operator: ${op}`
@@ -290,6 +290,18 @@ function sortRows(rows, $sort, tieBreak) {
 	}).map((decorated) => decorated.row);
 }
 /**
+* Applies `$skip` then `$limit` (both optional) via a single slice. No-op
+* pagination (the common unpaginated read) returns the input as-is: callers
+* pass a fresh, non-store-aliased array and copy what they return, so the
+* whole-array `.slice` copy that `slice(0, undefined)` would make is skipped.
+*/
+function paginate(rows, skip, limit) {
+	const start = skip ?? 0;
+	const end = limit === void 0 ? void 0 : start + limit;
+	if (start === 0 && end === void 0) return rows;
+	return rows.slice(start, end);
+}
+/**
 * Projects a plain row per a `{ path: 0 | 1 }` projection map. Decoupled from
 * `UniquSelect`: the caller passes the resolved projection map (e.g. from
 * `$select.asProjection`) so the engine has no query-layer dependency.
@@ -324,6 +336,195 @@ function projectRow(row, projection, opts) {
 	return out;
 }
 //#endregion
+//#region src/lib/memory-aggregate.ts
+/**
+* The in-memory grouping engine behind {@link MemoryAdapter.aggregate}: a pure
+* function over already-filtered rows (nested PHYSICAL documents), so stored
+* and provider (read-through) mode share it unchanged. Pipeline: group →
+* accumulate → `$having` → `$sort` → `$skip`/`$limit`, or → `$count` (the
+* groups that survive `$having`).
+*
+* Decisions (the SQL adapters' semantics):
+* - null and missing form ONE group; a calendar-bucket key is the
+*   `@uniqu/core` kernel label (the SQLite UDF runs the same kernel);
+* - `sum` / `avg` over no numeric value are `null`; `min` / `max` order with
+*   the `$sort` comparator; any other `$fn` is `INVALID_QUERY`;
+* - group identity is type-tagged: `1` and `"1"` never share a group (a
+*   number and a bigint of one value do), `Date`s group by instant, JSON
+*   values by a key-order-independent serialization;
+* - the returned rows carry exactly what `$select` asks for (every group key
+*   without one), nested like Mongo's `$project` yields them, with
+*   object-valued leaves copied so no store-owned value escapes.
+*/
+function aggregateRows(rows, controls) {
+	const $select = controls.$select;
+	const groupBy = controls.$groupBy ?? [];
+	const aggregates = $select?.aggregates ?? [];
+	const aliases = aggregates.map((expr) => (0, _atscript_db_agg.resolveAlias)(expr));
+	const keyReaders = groupBy.map((key) => groupKeyReader(key, controls));
+	const accumulators = aggregates.map(accumulatorFactory);
+	const newGroup = (values) => ({
+		values,
+		accs: accumulators.map((create) => create())
+	});
+	let groups;
+	if (keyReaders.length === 0) {
+		const group = newGroup([]);
+		for (const row of rows) for (const acc of group.accs) acc.add(row);
+		groups = [group];
+	} else {
+		const byIdentity = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			const values = keyReaders.map((read) => read(row));
+			const identity = groupIdentity(values);
+			let group = byIdentity.get(identity);
+			if (!group) {
+				group = newGroup(values);
+				byIdentity.set(identity, group);
+			}
+			for (const acc of group.accs) acc.add(row);
+		}
+		groups = byIdentity.values();
+	}
+	let out = [];
+	for (const { values, accs } of groups) {
+		const row = {};
+		for (let i = 0; i < groupBy.length; i++) setPath(row, groupBy[i], values[i]);
+		for (let i = 0; i < aliases.length; i++) row[aliases[i]] = accs[i].result();
+		out.push(row);
+	}
+	const having = controls.$having;
+	if (having) out = out.filter(buildMemoryPredicate(having));
+	if (controls.$count) return [{ count: out.length }];
+	const paged = paginate(sortRows(out, controls.$sort), controls.$skip, controls.$limit);
+	const fields = ($select === void 0 ? groupBy : $select.asArray ?? []).map((field) => [field, pathReader(field)]);
+	const outputAliases = $select === void 0 ? [] : [...($select.buckets ?? []).map((b) => b.alias), ...aliases];
+	return paged.map((row) => {
+		const picked = {};
+		for (const [field, read] of fields) setPath(picked, field, copyValue(read(row) ?? null));
+		for (const alias of outputAliases) picked[alias] = copyValue(row[alias]);
+		return picked;
+	});
+}
+/** Group values and min / max results may be store-owned objects (JSON values): hand back copies. */
+function copyValue(value) {
+	return value !== null && typeof value === "object" ? structuredClone(value) : value;
+}
+/** Reads one `$groupBy` key off a row: a bucket alias → its label, a path → its value. */
+function groupKeyReader(key, controls) {
+	const bucket = controls.$select?.bucketByAlias(key);
+	if (bucket) {
+		const label = (0, _uniqu_core.bucketer)(bucket.unit, bucket.tz, bucket.weekStart);
+		const read = pathReader(bucket.field);
+		return (row) => label(read(row));
+	}
+	const read = pathReader(key);
+	return (row) => read(row) ?? null;
+}
+/**
+* The identity of a group's key values: one {@link identityToken} per key,
+* length-prefixed when there are several, so no value can forge a separator.
+*/
+function groupIdentity(values) {
+	if (values.length === 1) return identityToken(values[0]);
+	let identity = "";
+	for (const value of values) {
+		const token = identityToken(value);
+		identity += `${token.length}:${token}`;
+	}
+	return identity;
+}
+/** A type-tagged identity token for one key value (see {@link aggregateRows}). */
+function identityToken(value) {
+	if (value === null || value === void 0) return "z";
+	if (value instanceof Date) return `D${value.getTime()}`;
+	switch (typeof value) {
+		case "string": return `s${value}`;
+		case "number":
+		case "bigint": return `n${String(value)}`;
+		case "boolean": return value ? "b1" : "b0";
+		default: return `j${stableJson(value)}`;
+	}
+}
+/** `JSON.stringify` with object keys sorted at every level. */
+function stableJson(value) {
+	return JSON.stringify(value, (_key, v) => {
+		if (v === null || typeof v !== "object" || Array.isArray(v)) return v;
+		const sorted = {};
+		for (const k of Object.keys(v).toSorted()) sorted[k] = v[k];
+		return sorted;
+	});
+}
+/** Numeric value of a measure, or `undefined` for null / missing / non-numeric. */
+function numericValue(value) {
+	if (typeof value === "number") return Number.isNaN(value) ? void 0 : value;
+	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "string" && value.trim() !== "") {
+		const n = Number(value);
+		return Number.isNaN(n) ? void 0 : n;
+	}
+}
+/**
+* Resolves an aggregate expression to an accumulator factory (one accumulator
+* per group). Validated up front, so an unknown `$fn` is rejected even when
+* there are no rows.
+*/
+function accumulatorFactory(expr) {
+	const field = expr.$field;
+	const read = pathReader(field);
+	switch (expr.$fn) {
+		case "count": {
+			const all = field === "*";
+			return () => {
+				let n = 0;
+				return {
+					add: (row) => {
+						if (all || read(row) != null) n++;
+					},
+					result: () => n
+				};
+			};
+		}
+		case "sum":
+		case "avg": {
+			const avg = expr.$fn === "avg";
+			return () => {
+				let sum = 0;
+				let n = 0;
+				return {
+					add: (row) => {
+						const v = numericValue(read(row));
+						if (v !== void 0) {
+							sum += v;
+							n++;
+						}
+					},
+					result: () => n === 0 ? null : avg ? sum / n : sum
+				};
+			};
+		}
+		case "min":
+		case "max": {
+			const sign = expr.$fn === "min" ? -1 : 1;
+			return () => {
+				let best = null;
+				return {
+					add: (row) => {
+						const v = read(row);
+						if (v == null) return;
+						if (best === null || compareLeaves(v, best) * sign > 0) best = v;
+					},
+					result: () => best
+				};
+			};
+		}
+		default: throw new _atscript_db.DbError("INVALID_QUERY", [{
+			path: "$select",
+			message: `Unsupported aggregate function "${String(expr.$fn)}" — use count, sum, avg, min or max`
+		}]);
+	}
+}
+//#endregion
 //#region src/lib/memory-adapter.ts
 /**
 * In-memory {@link BaseDbAdapter} implementation.
@@ -561,8 +762,7 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	* Write guard for provider-backed (read-only) mode. Called first in every one
 	* of the 8 write methods so all mutation entry points reject identically. Uses
 	* `INVALID_QUERY` (moost-db's validation interceptor maps it to HTTP 400, NOT
-	* 500 — the same choice `aggregate()` makes) since there is no dedicated
-	* read-only error code.
+	* 500) since there is no dedicated read-only error code.
 	*/
 	_assertWritable() {
 		if (this._provider) throw new _atscript_db.DbError("INVALID_QUERY", [{
@@ -803,13 +1003,6 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	_sortRows(rows, $sort) {
 		return sortRows(rows, $sort, (r) => this.pkKey(r));
 	}
-	/** Applies `$skip` then `$limit` (both optional) via a single slice. */
-	_paginate(rows, skip, limit) {
-		const start = skip ?? 0;
-		const end = limit === void 0 ? void 0 : start + limit;
-		if (start === 0 && end === void 0) return rows;
-		return rows.slice(start, end);
-	}
 	/**
 	* Projects a stored row per `$select` and returns a fresh, deep-cloned object
 	* so the store can never be mutated through a returned value.
@@ -875,25 +1068,32 @@ var MemoryAdapter = class extends _atscript_db.BaseDbAdapter {
 	async findManyWithCount(query) {
 		const filtered = await this._filteredRows(query);
 		const { $sort, $skip, $limit, $select } = this._readControls(query.controls ?? {});
-		const sorted = this._sortRows(filtered, $sort);
 		return {
-			data: this._paginate(sorted, $skip, $limit).map((row) => this._projectAndClone(row, $select)),
+			data: paginate(this._sortRows(filtered, $sort), $skip, $limit).map((row) => this._projectAndClone(row, $select)),
 			count: filtered.length
 		};
 	}
 	/**
-	* Aggregation (`$groupBy`) is a documented v1 non-goal for the in-memory
-	* adapter. The inherited base default throws a PLAIN `Error`, which a readable
-	* REST controller would surface as an unhandled HTTP 500 when a `?$groupBy=`
-	* query routes here. Throwing a typed {@link DbError} with `INVALID_QUERY`
-	* instead converts that into a clean client error — moost-db's validation
-	* interceptor maps `INVALID_QUERY` → HTTP 400.
+	* Grouped query (`$groupBy` + aggregates, calendar buckets, `$having`,
+	* `$sort`, `$skip` / `$limit`, `$count`) over ONE filtered snapshot — the
+	* pure {@link aggregateRows} engine, so provider (read-through) mode works
+	* unchanged. SQL-adapter semantics: null and missing group together,
+	* `sum` / `avg` over no numeric value are `null`, `$count` counts the groups
+	* that survive `$having`.
+	*
+	* `$search` never reaches here: this adapter is not searchable, so the core
+	* rejects a grouped search before dispatch.
 	*/
-	async aggregate(_query) {
-		throw new _atscript_db.DbError("INVALID_QUERY", [{
-			path: "",
-			message: "Aggregation ($groupBy) is not supported by the in-memory adapter"
-		}]);
+	async aggregate(query) {
+		return aggregateRows(await this._filteredRows(query), query.controls ?? {});
+	}
+	/**
+	* Every calendar-bucket unit: labels come from the `@uniqu/core` kernel
+	* (Node's ICU zone data — the list the core validates zones against, so
+	* there is no zone this adapter cannot resolve).
+	*/
+	calendarBucketUnits() {
+		return _atscript_db.ALL_BUCKET_UNITS;
 	}
 	async updateMany(filter, data, ops) {
 		this._assertWritable();

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TFieldOps } from "@atscript/db";
+import { BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TFieldOps } from "@atscript/db";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/lib/memory-adapter.d.ts
@@ -192,8 +192,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * Write guard for provider-backed (read-only) mode. Called first in every one
    * of the 8 write methods so all mutation entry points reject identically. Uses
    * `INVALID_QUERY` (moost-db's validation interceptor maps it to HTTP 400, NOT
-   * 500 — the same choice `aggregate()` makes) since there is no dedicated
-   * read-only error code.
+   * 500) since there is no dedicated read-only error code.
    */
   private _assertWritable;
   /**
@@ -308,8 +307,6 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * {@link sortRows}, injecting {@link pkKey} as the total-order tie-break.
    */
   private _sortRows;
-  /** Applies `$skip` then `$limit` (both optional) via a single slice. */
-  private _paginate;
   /**
    * Projects a stored row per `$select` and returns a fresh, deep-cloned object
    * so the store can never be mutated through a returned value.
@@ -353,14 +350,23 @@ declare class MemoryAdapter extends BaseDbAdapter {
     count: number;
   }>;
   /**
-   * Aggregation (`$groupBy`) is a documented v1 non-goal for the in-memory
-   * adapter. The inherited base default throws a PLAIN `Error`, which a readable
-   * REST controller would surface as an unhandled HTTP 500 when a `?$groupBy=`
-   * query routes here. Throwing a typed {@link DbError} with `INVALID_QUERY`
-   * instead converts that into a clean client error — moost-db's validation
-   * interceptor maps `INVALID_QUERY` → HTTP 400.
+   * Grouped query (`$groupBy` + aggregates, calendar buckets, `$having`,
+   * `$sort`, `$skip` / `$limit`, `$count`) over ONE filtered snapshot — the
+   * pure {@link aggregateRows} engine, so provider (read-through) mode works
+   * unchanged. SQL-adapter semantics: null and missing group together,
+   * `sum` / `avg` over no numeric value are `null`, `$count` counts the groups
+   * that survive `$having`.
+   *
+   * `$search` never reaches here: this adapter is not searchable, so the core
+   * rejects a grouped search before dispatch.
+   */
+  aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  /**
+   * Every calendar-bucket unit: labels come from the `@uniqu/core` kernel
+   * (Node's ICU zone data — the list the core validates zones against, so
+   * there is no zone this adapter cannot resolve).
    */
-  aggregate(_query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  calendarBucketUnits(): ReadonlySet<BucketUnit>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TFieldOps } from "@atscript/db";
+import { BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TFieldOps } from "@atscript/db";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/lib/memory-adapter.d.ts
@@ -192,8 +192,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * Write guard for provider-backed (read-only) mode. Called first in every one
    * of the 8 write methods so all mutation entry points reject identically. Uses
    * `INVALID_QUERY` (moost-db's validation interceptor maps it to HTTP 400, NOT
-   * 500 — the same choice `aggregate()` makes) since there is no dedicated
-   * read-only error code.
+   * 500) since there is no dedicated read-only error code.
    */
   private _assertWritable;
   /**
@@ -308,8 +307,6 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * {@link sortRows}, injecting {@link pkKey} as the total-order tie-break.
    */
   private _sortRows;
-  /** Applies `$skip` then `$limit` (both optional) via a single slice. */
-  private _paginate;
   /**
    * Projects a stored row per `$select` and returns a fresh, deep-cloned object
    * so the store can never be mutated through a returned value.
@@ -353,14 +350,23 @@ declare class MemoryAdapter extends BaseDbAdapter {
     count: number;
   }>;
   /**
-   * Aggregation (`$groupBy`) is a documented v1 non-goal for the in-memory
-   * adapter. The inherited base default throws a PLAIN `Error`, which a readable
-   * REST controller would surface as an unhandled HTTP 500 when a `?$groupBy=`
-   * query routes here. Throwing a typed {@link DbError} with `INVALID_QUERY`
-   * instead converts that into a clean client error — moost-db's validation
-   * interceptor maps `INVALID_QUERY` → HTTP 400.
+   * Grouped query (`$groupBy` + aggregates, calendar buckets, `$having`,
+   * `$sort`, `$skip` / `$limit`, `$count`) over ONE filtered snapshot — the
+   * pure {@link aggregateRows} engine, so provider (read-through) mode works
+   * unchanged. SQL-adapter semantics: null and missing group together,
+   * `sum` / `avg` over no numeric value are `null`, `$count` counts the groups
+   * that survive `$having`.
+   *
+   * `$search` never reaches here: this adapter is not searchable, so the core
+   * rejects a grouped search before dispatch.
+   */
+  aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  /**
+   * Every calendar-bucket unit: labels come from the `@uniqu/core` kernel
+   * (Node's ICU zone data — the list the core validates zones against, so
+   * there is no zone this adapter cannot resolve).
    */
-  aggregate(_query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  calendarBucketUnits(): ReadonlySet<BucketUnit>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;

package/dist/index.mjs

@@ -1,4 +1,6 @@
-import { BaseDbAdapter, DbError, DbSpace, walkFilter } from "@atscript/db";
+import { ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace, walkFilter } from "@atscript/db";
+import { resolveAlias } from "@atscript/db/agg";
+import { bucketer } from "@uniqu/core";
 //#region src/lib/memory-filter.ts
 /**
 * Dot-path getter. Splits `path` on `.` and walks plain objects, returning the
@@ -21,22 +23,20 @@ function getPath(row, path) {
 	return current;
 }
 /**
-* Like {@link getPath}, but reports whether the FINAL key EXISTS rather than
-* its value. A key holding `null` counts as present. This is what lets
-* `$exists` distinguish a `null`-valued field (present) from an absent one —
-* a distinction {@link getPath} alone cannot make (both would read back as a
-* nullish value). Same array limitation as {@link getPath}.
+* {@link getPath} compiled for one path: split once, and a single segment is
+* a direct property read — for callers that read the same path off many rows.
 */
-function hasPath(row, path) {
+function pathReader(path) {
+	if (!path.includes(".")) return (row) => row[path];
 	const segments = path.split(".");
-	const last = segments.pop();
-	let current = row;
-	for (const seg of segments) {
-		if (current === null || typeof current !== "object" || Array.isArray(current)) return false;
-		current = current[seg];
-	}
-	if (current === null || typeof current !== "object" || Array.isArray(current)) return false;
-	return Object.prototype.hasOwnProperty.call(current, last);
+	return (row) => {
+		let current = row;
+		for (const seg of segments) {
+			if (current === null || typeof current !== "object" || Array.isArray(current)) return;
+			current = current[seg];
+		}
+		return current;
+	};
 }
 /**
 * Deep-equality for leaf values, used by `$eq`/`$ne`/`$in`/`$nin`.
@@ -169,7 +169,7 @@ const memoryVisitor = {
 					return fieldValue != null && regex.test(stringifyLeaf(fieldValue));
 				};
 			}
-			case "$exists": return (row) => value === hasPath(row, field);
+			case "$exists": return (row) => value === !evalEq(row, field, null);
 			default: throw new DbError("INVALID_QUERY", [{
 				path: field,
 				message: `Unsupported filter operator: ${op}`
@@ -289,6 +289,18 @@ function sortRows(rows, $sort, tieBreak) {
 	}).map((decorated) => decorated.row);
 }
 /**
+* Applies `$skip` then `$limit` (both optional) via a single slice. No-op
+* pagination (the common unpaginated read) returns the input as-is: callers
+* pass a fresh, non-store-aliased array and copy what they return, so the
+* whole-array `.slice` copy that `slice(0, undefined)` would make is skipped.
+*/
+function paginate(rows, skip, limit) {
+	const start = skip ?? 0;
+	const end = limit === void 0 ? void 0 : start + limit;
+	if (start === 0 && end === void 0) return rows;
+	return rows.slice(start, end);
+}
+/**
 * Projects a plain row per a `{ path: 0 | 1 }` projection map. Decoupled from
 * `UniquSelect`: the caller passes the resolved projection map (e.g. from
 * `$select.asProjection`) so the engine has no query-layer dependency.
@@ -323,6 +335,195 @@ function projectRow(row, projection, opts) {
 	return out;
 }
 //#endregion
+//#region src/lib/memory-aggregate.ts
+/**
+* The in-memory grouping engine behind {@link MemoryAdapter.aggregate}: a pure
+* function over already-filtered rows (nested PHYSICAL documents), so stored
+* and provider (read-through) mode share it unchanged. Pipeline: group →
+* accumulate → `$having` → `$sort` → `$skip`/`$limit`, or → `$count` (the
+* groups that survive `$having`).
+*
+* Decisions (the SQL adapters' semantics):
+* - null and missing form ONE group; a calendar-bucket key is the
+*   `@uniqu/core` kernel label (the SQLite UDF runs the same kernel);
+* - `sum` / `avg` over no numeric value are `null`; `min` / `max` order with
+*   the `$sort` comparator; any other `$fn` is `INVALID_QUERY`;
+* - group identity is type-tagged: `1` and `"1"` never share a group (a
+*   number and a bigint of one value do), `Date`s group by instant, JSON
+*   values by a key-order-independent serialization;
+* - the returned rows carry exactly what `$select` asks for (every group key
+*   without one), nested like Mongo's `$project` yields them, with
+*   object-valued leaves copied so no store-owned value escapes.
+*/
+function aggregateRows(rows, controls) {
+	const $select = controls.$select;
+	const groupBy = controls.$groupBy ?? [];
+	const aggregates = $select?.aggregates ?? [];
+	const aliases = aggregates.map((expr) => resolveAlias(expr));
+	const keyReaders = groupBy.map((key) => groupKeyReader(key, controls));
+	const accumulators = aggregates.map(accumulatorFactory);
+	const newGroup = (values) => ({
+		values,
+		accs: accumulators.map((create) => create())
+	});
+	let groups;
+	if (keyReaders.length === 0) {
+		const group = newGroup([]);
+		for (const row of rows) for (const acc of group.accs) acc.add(row);
+		groups = [group];
+	} else {
+		const byIdentity = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			const values = keyReaders.map((read) => read(row));
+			const identity = groupIdentity(values);
+			let group = byIdentity.get(identity);
+			if (!group) {
+				group = newGroup(values);
+				byIdentity.set(identity, group);
+			}
+			for (const acc of group.accs) acc.add(row);
+		}
+		groups = byIdentity.values();
+	}
+	let out = [];
+	for (const { values, accs } of groups) {
+		const row = {};
+		for (let i = 0; i < groupBy.length; i++) setPath(row, groupBy[i], values[i]);
+		for (let i = 0; i < aliases.length; i++) row[aliases[i]] = accs[i].result();
+		out.push(row);
+	}
+	const having = controls.$having;
+	if (having) out = out.filter(buildMemoryPredicate(having));
+	if (controls.$count) return [{ count: out.length }];
+	const paged = paginate(sortRows(out, controls.$sort), controls.$skip, controls.$limit);
+	const fields = ($select === void 0 ? groupBy : $select.asArray ?? []).map((field) => [field, pathReader(field)]);
+	const outputAliases = $select === void 0 ? [] : [...($select.buckets ?? []).map((b) => b.alias), ...aliases];
+	return paged.map((row) => {
+		const picked = {};
+		for (const [field, read] of fields) setPath(picked, field, copyValue(read(row) ?? null));
+		for (const alias of outputAliases) picked[alias] = copyValue(row[alias]);
+		return picked;
+	});
+}
+/** Group values and min / max results may be store-owned objects (JSON values): hand back copies. */
+function copyValue(value) {
+	return value !== null && typeof value === "object" ? structuredClone(value) : value;
+}
+/** Reads one `$groupBy` key off a row: a bucket alias → its label, a path → its value. */
+function groupKeyReader(key, controls) {
+	const bucket = controls.$select?.bucketByAlias(key);
+	if (bucket) {
+		const label = bucketer(bucket.unit, bucket.tz, bucket.weekStart);
+		const read = pathReader(bucket.field);
+		return (row) => label(read(row));
+	}
+	const read = pathReader(key);
+	return (row) => read(row) ?? null;
+}
+/**
+* The identity of a group's key values: one {@link identityToken} per key,
+* length-prefixed when there are several, so no value can forge a separator.
+*/
+function groupIdentity(values) {
+	if (values.length === 1) return identityToken(values[0]);
+	let identity = "";
+	for (const value of values) {
+		const token = identityToken(value);
+		identity += `${token.length}:${token}`;
+	}
+	return identity;
+}
+/** A type-tagged identity token for one key value (see {@link aggregateRows}). */
+function identityToken(value) {
+	if (value === null || value === void 0) return "z";
+	if (value instanceof Date) return `D${value.getTime()}`;
+	switch (typeof value) {
+		case "string": return `s${value}`;
+		case "number":
+		case "bigint": return `n${String(value)}`;
+		case "boolean": return value ? "b1" : "b0";
+		default: return `j${stableJson(value)}`;
+	}
+}
+/** `JSON.stringify` with object keys sorted at every level. */
+function stableJson(value) {
+	return JSON.stringify(value, (_key, v) => {
+		if (v === null || typeof v !== "object" || Array.isArray(v)) return v;
+		const sorted = {};
+		for (const k of Object.keys(v).toSorted()) sorted[k] = v[k];
+		return sorted;
+	});
+}
+/** Numeric value of a measure, or `undefined` for null / missing / non-numeric. */
+function numericValue(value) {
+	if (typeof value === "number") return Number.isNaN(value) ? void 0 : value;
+	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "string" && value.trim() !== "") {
+		const n = Number(value);
+		return Number.isNaN(n) ? void 0 : n;
+	}
+}
+/**
+* Resolves an aggregate expression to an accumulator factory (one accumulator
+* per group). Validated up front, so an unknown `$fn` is rejected even when
+* there are no rows.
+*/
+function accumulatorFactory(expr) {
+	const field = expr.$field;
+	const read = pathReader(field);
+	switch (expr.$fn) {
+		case "count": {
+			const all = field === "*";
+			return () => {
+				let n = 0;
+				return {
+					add: (row) => {
+						if (all || read(row) != null) n++;
+					},
+					result: () => n
+				};
+			};
+		}
+		case "sum":
+		case "avg": {
+			const avg = expr.$fn === "avg";
+			return () => {
+				let sum = 0;
+				let n = 0;
+				return {
+					add: (row) => {
+						const v = numericValue(read(row));
+						if (v !== void 0) {
+							sum += v;
+							n++;
+						}
+					},
+					result: () => n === 0 ? null : avg ? sum / n : sum
+				};
+			};
+		}
+		case "min":
+		case "max": {
+			const sign = expr.$fn === "min" ? -1 : 1;
+			return () => {
+				let best = null;
+				return {
+					add: (row) => {
+						const v = read(row);
+						if (v == null) return;
+						if (best === null || compareLeaves(v, best) * sign > 0) best = v;
+					},
+					result: () => best
+				};
+			};
+		}
+		default: throw new DbError("INVALID_QUERY", [{
+			path: "$select",
+			message: `Unsupported aggregate function "${String(expr.$fn)}" — use count, sum, avg, min or max`
+		}]);
+	}
+}
+//#endregion
 //#region src/lib/memory-adapter.ts
 /**
 * In-memory {@link BaseDbAdapter} implementation.
@@ -560,8 +761,7 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	* Write guard for provider-backed (read-only) mode. Called first in every one
 	* of the 8 write methods so all mutation entry points reject identically. Uses
 	* `INVALID_QUERY` (moost-db's validation interceptor maps it to HTTP 400, NOT
-	* 500 — the same choice `aggregate()` makes) since there is no dedicated
-	* read-only error code.
+	* 500) since there is no dedicated read-only error code.
 	*/
 	_assertWritable() {
 		if (this._provider) throw new DbError("INVALID_QUERY", [{
@@ -802,13 +1002,6 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	_sortRows(rows, $sort) {
 		return sortRows(rows, $sort, (r) => this.pkKey(r));
 	}
-	/** Applies `$skip` then `$limit` (both optional) via a single slice. */
-	_paginate(rows, skip, limit) {
-		const start = skip ?? 0;
-		const end = limit === void 0 ? void 0 : start + limit;
-		if (start === 0 && end === void 0) return rows;
-		return rows.slice(start, end);
-	}
 	/**
 	* Projects a stored row per `$select` and returns a fresh, deep-cloned object
 	* so the store can never be mutated through a returned value.
@@ -874,25 +1067,32 @@ var MemoryAdapter = class extends BaseDbAdapter {
 	async findManyWithCount(query) {
 		const filtered = await this._filteredRows(query);
 		const { $sort, $skip, $limit, $select } = this._readControls(query.controls ?? {});
-		const sorted = this._sortRows(filtered, $sort);
 		return {
-			data: this._paginate(sorted, $skip, $limit).map((row) => this._projectAndClone(row, $select)),
+			data: paginate(this._sortRows(filtered, $sort), $skip, $limit).map((row) => this._projectAndClone(row, $select)),
 			count: filtered.length
 		};
 	}
 	/**
-	* Aggregation (`$groupBy`) is a documented v1 non-goal for the in-memory
-	* adapter. The inherited base default throws a PLAIN `Error`, which a readable
-	* REST controller would surface as an unhandled HTTP 500 when a `?$groupBy=`
-	* query routes here. Throwing a typed {@link DbError} with `INVALID_QUERY`
-	* instead converts that into a clean client error — moost-db's validation
-	* interceptor maps `INVALID_QUERY` → HTTP 400.
+	* Grouped query (`$groupBy` + aggregates, calendar buckets, `$having`,
+	* `$sort`, `$skip` / `$limit`, `$count`) over ONE filtered snapshot — the
+	* pure {@link aggregateRows} engine, so provider (read-through) mode works
+	* unchanged. SQL-adapter semantics: null and missing group together,
+	* `sum` / `avg` over no numeric value are `null`, `$count` counts the groups
+	* that survive `$having`.
+	*
+	* `$search` never reaches here: this adapter is not searchable, so the core
+	* rejects a grouped search before dispatch.
 	*/
-	async aggregate(_query) {
-		throw new DbError("INVALID_QUERY", [{
-			path: "",
-			message: "Aggregation ($groupBy) is not supported by the in-memory adapter"
-		}]);
+	async aggregate(query) {
+		return aggregateRows(await this._filteredRows(query), query.controls ?? {});
+	}
+	/**
+	* Every calendar-bucket unit: labels come from the `@uniqu/core` kernel
+	* (Node's ICU zone data — the list the core validates zones against, so
+	* there is no zone this adapter cannot resolve).
+	*/
+	calendarBucketUnits() {
+		return ALL_BUCKET_UNITS;
 	}
 	async updateMany(filter, data, ops) {
 		this._assertWritable();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-memory",
-  "version": "0.1.131",
+  "version": "0.1.133",
   "description": "In-memory adapter for atscript-db.",
   "keywords": [
     "atscript",
@@ -38,12 +38,14 @@
   "devDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
+    "@uniqu/core": "^0.1.10",
     "unplugin-atscript": "^0.1.92"
   },
   "peerDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
-    "@atscript/db": "^0.1.131"
+    "@uniqu/core": "^0.1.10",
+    "@atscript/db": "^0.1.133"
   },
   "scripts": {
     "postinstall": "asc -f dts",