@atscript/db 0.1.135 → 0.1.137

package/dist/{agg-DKuf_v2L.d.cts → agg-CV7y8nC6.d.cts}

@@ -1,8 +1,18 @@
 import { AggregateControls, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateFn as AggregateFn$1, AggregateQuery as AggregateQuery$1, AggregateResult, BucketExpr, BucketUnit as BucketUnit$1, CalendarBucketLabel, ComputedExpr, ResolvedBucket as ResolvedBucket$1, WeekStart, isAggregateExpr, isBucketExpr, resolveAlias } from "@uniqu/core";
 
 //#region src/query/aggregate-fns.d.ts
-/** The aggregate functions atscript-db adapters implement — uniqu's set minus `countDistinct`. */
-type TDbAggregateFn = Exclude<AggregateFn, "countDistinct">;
+/**
+ * The aggregate functions atscript-db knows — uniqu's full `AggregateFn` set.
+ * Which of them an adapter renders is its `aggregateFns()` capability.
+ */
+type TDbAggregateFn = AggregateFn;
+/**
+ * Every aggregate function — what an adapter that renders them all returns
+ * from `aggregateFns()`.
+ *
+ * @since 0.1.136
+ */
+declare const ALL_AGGREGATE_FNS: ReadonlySet<TDbAggregateFn>;
 /**
  * Throws `DbError` `INVALID_QUERY` (uniqu's wording) unless `fn` is in
  * `SUPPORTED_AGGREGATE_FNS` — for adapters to re-assert before rendering.
@@ -40,4 +50,4 @@ declare function resolveAggregateSearch(controls: {
   [key: `$${string}`]: unknown;
 } | undefined): TAggregateSearch | undefined;
 //#endregion
-export { assertAggregateFn as _, AggregateResult as a, CalendarBucketLabel as c, WeekStart as d, isAggregateExpr as f, TDbAggregateFn as g, resolveAlias as h, AggregateQuery$1 as i, ComputedExpr as l, resolveAggregateSearch as m, AggregateExpr$1 as n, BucketExpr as o, isBucketExpr as p, AggregateFn$1 as r, BucketUnit$1 as s, AggregateControls as t, ResolvedBucket$1 as u };
+export { TDbAggregateFn as _, AggregateResult as a, CalendarBucketLabel as c, WeekStart as d, isAggregateExpr as f, ALL_AGGREGATE_FNS as g, resolveAlias as h, AggregateQuery$1 as i, ComputedExpr as l, resolveAggregateSearch as m, AggregateExpr$1 as n, BucketExpr as o, isBucketExpr as p, AggregateFn$1 as r, BucketUnit$1 as s, AggregateControls as t, ResolvedBucket$1 as u, assertAggregateFn as v };

package/dist/{agg-BtlGeRfj.d.mts → agg-D5DHsAby.d.mts}

@@ -1,8 +1,18 @@
 import { AggregateControls, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateFn as AggregateFn$1, AggregateQuery as AggregateQuery$1, AggregateResult, BucketExpr, BucketUnit as BucketUnit$1, CalendarBucketLabel, ComputedExpr, ResolvedBucket as ResolvedBucket$1, WeekStart, isAggregateExpr as isAggregateExpr$1, isBucketExpr as isBucketExpr$1, resolveAlias } from "@uniqu/core";
 
 //#region src/query/aggregate-fns.d.ts
-/** The aggregate functions atscript-db adapters implement — uniqu's set minus `countDistinct`. */
-type TDbAggregateFn = Exclude<AggregateFn, "countDistinct">;
+/**
+ * The aggregate functions atscript-db knows — uniqu's full `AggregateFn` set.
+ * Which of them an adapter renders is its `aggregateFns()` capability.
+ */
+type TDbAggregateFn = AggregateFn;
+/**
+ * Every aggregate function — what an adapter that renders them all returns
+ * from `aggregateFns()`.
+ *
+ * @since 0.1.136
+ */
+declare const ALL_AGGREGATE_FNS: ReadonlySet<TDbAggregateFn>;
 /**
  * Throws `DbError` `INVALID_QUERY` (uniqu's wording) unless `fn` is in
  * `SUPPORTED_AGGREGATE_FNS` — for adapters to re-assert before rendering.
@@ -40,4 +50,4 @@ declare function resolveAggregateSearch(controls: {
   [key: `$${string}`]: unknown;
 } | undefined): TAggregateSearch | undefined;
 //#endregion
-export { assertAggregateFn as _, AggregateResult as a, CalendarBucketLabel as c, WeekStart as d, isAggregateExpr$1 as f, TDbAggregateFn as g, resolveAlias as h, AggregateQuery$1 as i, ComputedExpr as l, resolveAggregateSearch as m, AggregateExpr$1 as n, BucketExpr as o, isBucketExpr$1 as p, AggregateFn$1 as r, BucketUnit$1 as s, AggregateControls as t, ResolvedBucket$1 as u };
+export { TDbAggregateFn as _, AggregateResult as a, CalendarBucketLabel as c, WeekStart as d, isAggregateExpr$1 as f, ALL_AGGREGATE_FNS as g, resolveAlias as h, AggregateQuery$1 as i, ComputedExpr as l, resolveAggregateSearch as m, AggregateExpr$1 as n, BucketExpr as o, isBucketExpr$1 as p, AggregateFn$1 as r, BucketUnit$1 as s, AggregateControls as t, ResolvedBucket$1 as u, assertAggregateFn as v };

package/dist/agg.cjs

@@ -1,7 +1,39 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_agg = require("./agg-EcIbAFnJ.cjs");
+const require_aggregate_fns = require("./aggregate-fns-CGBv3E8S.cjs");
 let _uniqu_core = require("@uniqu/core");
-exports.assertAggregateFn = require_agg.assertAggregateFn;
+//#region src/agg.ts
+/**
+* Reads the `$search` / `$index` controls of an aggregate query.
+*
+* Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+* shapes what is left. Every adapter must therefore apply the search predicate
+* BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+* describe rows that matched. An adapter that silently ignored the term would
+* report totals for rows the same search excludes from the leaf list.
+*
+* Two rules the leaf search path applies and the grouped path must NOT:
+* - **No implicit relevance ordering.** Relevance is a property of a row, not
+*   of a group; after `$group` there is no per-row score left to sort on.
+*   Grouped results order by `$sort` or not at all.
+* - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+*   rows; applying that before `$group` would silently truncate group counts.
+*
+* Returns `undefined` when there is nothing to search for, so callers fall
+* straight through to the plain grouped path.
+*/
+function resolveAggregateSearch(controls) {
+	const raw = controls?.$search;
+	if (typeof raw !== "string") return;
+	const text = raw.trim();
+	if (!text) return;
+	const index = controls?.$index;
+	return {
+		text,
+		indexName: typeof index === "string" && index ? index : void 0
+	};
+}
+//#endregion
+exports.assertAggregateFn = require_aggregate_fns.assertAggregateFn;
 Object.defineProperty(exports, "isAggregateExpr", {
 	enumerable: true,
 	get: function() {
@@ -14,7 +46,7 @@ Object.defineProperty(exports, "isBucketExpr", {
 		return _uniqu_core.isBucketExpr;
 	}
 });
-exports.resolveAggregateSearch = require_agg.resolveAggregateSearch;
+exports.resolveAggregateSearch = resolveAggregateSearch;
 Object.defineProperty(exports, "resolveAlias", {
 	enumerable: true,
 	get: function() {

package/dist/agg.d.cts

@@ -1,3 +1,3 @@
-import { n as TResolvedBucket } from "./buckets-D6PBXKRJ.cjs";
-import { _ as assertAggregateFn, a as AggregateResult, c as CalendarBucketLabel, d as WeekStart, f as isAggregateExpr, g as TDbAggregateFn, h as resolveAlias, i as AggregateQuery, l as ComputedExpr, m as resolveAggregateSearch, n as AggregateExpr, o as BucketExpr, p as isBucketExpr, r as AggregateFn, s as BucketUnit, t as AggregateControls, u as ResolvedBucket } from "./agg-DKuf_v2L.cjs";
+import { n as TResolvedBucket } from "./buckets-C-27xmtq.cjs";
+import { _ as TDbAggregateFn, a as AggregateResult, c as CalendarBucketLabel, d as WeekStart, f as isAggregateExpr, h as resolveAlias, i as AggregateQuery, l as ComputedExpr, m as resolveAggregateSearch, n as AggregateExpr, o as BucketExpr, p as isBucketExpr, r as AggregateFn, s as BucketUnit, t as AggregateControls, u as ResolvedBucket, v as assertAggregateFn } from "./agg-CV7y8nC6.cjs";
 export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, type BucketExpr, type BucketUnit, type CalendarBucketLabel, type ComputedExpr, type ResolvedBucket, type TDbAggregateFn, type TResolvedBucket, type WeekStart, assertAggregateFn, isAggregateExpr, isBucketExpr, resolveAggregateSearch, resolveAlias };

package/dist/agg.d.mts

@@ -1,3 +1,3 @@
-import { n as TResolvedBucket } from "./buckets-GruoVxH5.mjs";
-import { _ as assertAggregateFn, a as AggregateResult, c as CalendarBucketLabel, d as WeekStart, f as isAggregateExpr, g as TDbAggregateFn, h as resolveAlias, i as AggregateQuery, l as ComputedExpr, m as resolveAggregateSearch, n as AggregateExpr, o as BucketExpr, p as isBucketExpr, r as AggregateFn, s as BucketUnit, t as AggregateControls, u as ResolvedBucket } from "./agg-BtlGeRfj.mjs";
+import { n as TResolvedBucket } from "./buckets-BFG2RYRW.mjs";
+import { _ as TDbAggregateFn, a as AggregateResult, c as CalendarBucketLabel, d as WeekStart, f as isAggregateExpr, h as resolveAlias, i as AggregateQuery, l as ComputedExpr, m as resolveAggregateSearch, n as AggregateExpr, o as BucketExpr, p as isBucketExpr, r as AggregateFn, s as BucketUnit, t as AggregateControls, u as ResolvedBucket, v as assertAggregateFn } from "./agg-D5DHsAby.mjs";
 export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, type BucketExpr, type BucketUnit, type CalendarBucketLabel, type ComputedExpr, type ResolvedBucket, type TDbAggregateFn, type TResolvedBucket, type WeekStart, assertAggregateFn, isAggregateExpr, isBucketExpr, resolveAggregateSearch, resolveAlias };

package/dist/agg.mjs

@@ -1,2 +1,35 @@
-import { i as resolveAlias, n as isBucketExpr, o as assertAggregateFn, r as resolveAggregateSearch, t as isAggregateExpr } from "./agg-CvXDGnKi.mjs";
+import { a as assertAggregateFn } from "./aggregate-fns-CfsveE1w.mjs";
+import { isAggregateExpr, isBucketExpr, resolveAlias } from "@uniqu/core";
+//#region src/agg.ts
+/**
+* Reads the `$search` / `$index` controls of an aggregate query.
+*
+* Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+* shapes what is left. Every adapter must therefore apply the search predicate
+* BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+* describe rows that matched. An adapter that silently ignored the term would
+* report totals for rows the same search excludes from the leaf list.
+*
+* Two rules the leaf search path applies and the grouped path must NOT:
+* - **No implicit relevance ordering.** Relevance is a property of a row, not
+*   of a group; after `$group` there is no per-row score left to sort on.
+*   Grouped results order by `$sort` or not at all.
+* - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+*   rows; applying that before `$group` would silently truncate group counts.
+*
+* Returns `undefined` when there is nothing to search for, so callers fall
+* straight through to the plain grouped path.
+*/
+function resolveAggregateSearch(controls) {
+	const raw = controls?.$search;
+	if (typeof raw !== "string") return;
+	const text = raw.trim();
+	if (!text) return;
+	const index = controls?.$index;
+	return {
+		text,
+		indexName: typeof index === "string" && index ? index : void 0
+	};
+}
+//#endregion
 export { assertAggregateFn, isAggregateExpr, isBucketExpr, resolveAggregateSearch, resolveAlias };

package/dist/aggregate-fns-CGBv3E8S.cjs

@@ -0,0 +1,87 @@
+const require_db_error = require("./db-error-DTkkeu5b.cjs");
+//#region src/query/aggregate-fns.ts
+/**
+* The only `$fn` names a `$select` aggregate may use. Any other name is rejected with
+* `INVALID_QUERY` (HTTP 400 through moost-db) before a query reaches an
+* adapter, so no adapter ever renders an unchecked function name into SQL or
+* a pipeline. A known name missing from the adapter's `aggregateFns()` is
+* `AGG_FN_NOT_SUPPORTED`.
+*/
+const SUPPORTED_AGGREGATE_FNS = [
+	"sum",
+	"count",
+	"avg",
+	"min",
+	"max",
+	"countDistinct"
+];
+/**
+* The aggregates that are NULL over no (non-null) value — every function but
+* the counts, which are 0. So a view field reading a left-joined table must be
+* optional unless it counts, and a CONDITIONAL one must be optional when no
+* row may match — except `sum`, whose conditional form is rendered as
+* `COALESCE(…, 0)`.
+*/
+const NULL_WHEN_EMPTY_AGGREGATE_FNS = new Set([
+	"sum",
+	"avg",
+	"min",
+	"max"
+]);
+/** `BaseDbAdapter.aggregateFns()` by default: every function except `countDistinct`. */
+const BASE_AGGREGATE_FNS = new Set([
+	"sum",
+	"count",
+	"avg",
+	"min",
+	"max"
+]);
+/**
+* Every aggregate function — what an adapter that renders them all returns
+* from `aggregateFns()`.
+*
+* @since 0.1.136
+*/
+const ALL_AGGREGATE_FNS = new Set(SUPPORTED_AGGREGATE_FNS);
+const SUPPORTED_LIST = `${SUPPORTED_AGGREGATE_FNS.slice(0, -1).join(", ")} or ${SUPPORTED_AGGREGATE_FNS.at(-1)}`;
+/**
+* Throws `DbError` `INVALID_QUERY` (uniqu's wording) unless `fn` is in
+* `SUPPORTED_AGGREGATE_FNS` — for adapters to re-assert before rendering.
+*/
+function assertAggregateFn(fn, path = "$select") {
+	if (!SUPPORTED_AGGREGATE_FNS.includes(fn)) throw new require_db_error.DbError("INVALID_QUERY", [{
+		path,
+		message: `Unknown aggregate function "${String(fn)}" — use ${SUPPORTED_LIST}`
+	}]);
+}
+//#endregion
+Object.defineProperty(exports, "ALL_AGGREGATE_FNS", {
+	enumerable: true,
+	get: function() {
+		return ALL_AGGREGATE_FNS;
+	}
+});
+Object.defineProperty(exports, "BASE_AGGREGATE_FNS", {
+	enumerable: true,
+	get: function() {
+		return BASE_AGGREGATE_FNS;
+	}
+});
+Object.defineProperty(exports, "NULL_WHEN_EMPTY_AGGREGATE_FNS", {
+	enumerable: true,
+	get: function() {
+		return NULL_WHEN_EMPTY_AGGREGATE_FNS;
+	}
+});
+Object.defineProperty(exports, "SUPPORTED_AGGREGATE_FNS", {
+	enumerable: true,
+	get: function() {
+		return SUPPORTED_AGGREGATE_FNS;
+	}
+});
+Object.defineProperty(exports, "assertAggregateFn", {
+	enumerable: true,
+	get: function() {
+		return assertAggregateFn;
+	}
+});

package/dist/aggregate-fns-CfsveE1w.mjs

@@ -0,0 +1,58 @@
+import { r as DbError } from "./db-error-D5uilS_A.mjs";
+//#region src/query/aggregate-fns.ts
+/**
+* The only `$fn` names a `$select` aggregate may use. Any other name is rejected with
+* `INVALID_QUERY` (HTTP 400 through moost-db) before a query reaches an
+* adapter, so no adapter ever renders an unchecked function name into SQL or
+* a pipeline. A known name missing from the adapter's `aggregateFns()` is
+* `AGG_FN_NOT_SUPPORTED`.
+*/
+const SUPPORTED_AGGREGATE_FNS = [
+	"sum",
+	"count",
+	"avg",
+	"min",
+	"max",
+	"countDistinct"
+];
+/**
+* The aggregates that are NULL over no (non-null) value — every function but
+* the counts, which are 0. So a view field reading a left-joined table must be
+* optional unless it counts, and a CONDITIONAL one must be optional when no
+* row may match — except `sum`, whose conditional form is rendered as
+* `COALESCE(…, 0)`.
+*/
+const NULL_WHEN_EMPTY_AGGREGATE_FNS = new Set([
+	"sum",
+	"avg",
+	"min",
+	"max"
+]);
+/** `BaseDbAdapter.aggregateFns()` by default: every function except `countDistinct`. */
+const BASE_AGGREGATE_FNS = new Set([
+	"sum",
+	"count",
+	"avg",
+	"min",
+	"max"
+]);
+/**
+* Every aggregate function — what an adapter that renders them all returns
+* from `aggregateFns()`.
+*
+* @since 0.1.136
+*/
+const ALL_AGGREGATE_FNS = new Set(SUPPORTED_AGGREGATE_FNS);
+const SUPPORTED_LIST = `${SUPPORTED_AGGREGATE_FNS.slice(0, -1).join(", ")} or ${SUPPORTED_AGGREGATE_FNS.at(-1)}`;
+/**
+* Throws `DbError` `INVALID_QUERY` (uniqu's wording) unless `fn` is in
+* `SUPPORTED_AGGREGATE_FNS` — for adapters to re-assert before rendering.
+*/
+function assertAggregateFn(fn, path = "$select") {
+	if (!SUPPORTED_AGGREGATE_FNS.includes(fn)) throw new DbError("INVALID_QUERY", [{
+		path,
+		message: `Unknown aggregate function "${String(fn)}" — use ${SUPPORTED_LIST}`
+	}]);
+}
+//#endregion
+export { assertAggregateFn as a, SUPPORTED_AGGREGATE_FNS as i, BASE_AGGREGATE_FNS as n, NULL_WHEN_EMPTY_AGGREGATE_FNS as r, ALL_AGGREGATE_FNS as t };