@protobase/server 0.22.6 → 0.22.8

package/dist/aggregate-groups.js

@@ -2,6 +2,7 @@ import { badRequest } from "./problem.js";
 import { readTransaction } from "./transactions.js";
 import { parseParams } from "./params.js";
 import { labelRequests, relatedLabels } from "./related-labels.js";
+import { splitGroups } from "./aggregate-splits.js";
 import { scoped, seriesRange } from "./aggregate-service.js";
 import { z } from "zod";
 import { groupTotals, series } from "@protobase/query";
@@ -30,7 +31,10 @@ const aggregateParams = z.object({
 		"month",
 		"year"
 	]).optional(),
-	time_zone: z.string().optional()
+	time_zone: z.string().optional(),
+	split_by: name.optional(),
+	split_limit: z.coerce.number().int().optional(),
+	split_label: name.optional()
 });
 const invalid = (parameter, message) => badRequest("invalid-parameter", `Invalid parameter ${parameter}: ${message}`, { errors: [{
 	parameter,
@@ -49,13 +53,20 @@ const measureOf = (params) => {
 };
 const optionErrors = (params, dated) => {
 	const given = (names) => names.filter((option) => params[option] !== void 0);
-	if (dated) return given(["limit", "label"]).map((option) => invalid(option, `Not for a date or timestamp group_by`));
+	if (dated) {
+		const errors = given(["limit", "label"]).map((option) => invalid(option, `Not for a date or timestamp group_by`));
+		if (params.split_by === void 0 && given(["split_limit", "split_label"]).length > 0) errors.push(invalid("split_by", "split_limit and split_label need split_by"));
+		return errors;
+	}
 	return given([
 		"range",
 		"from",
 		"to",
 		"granularity",
-		"time_zone"
+		"time_zone",
+		"split_by",
+		"split_limit",
+		"split_label"
 	]).map((option) => invalid(option, "Only for a date or timestamp group_by"));
 };
 const isDated = (model, field) => {
@@ -75,6 +86,7 @@ const aggregate = async (deps, entry, session, input) => {
 	const dated = isDated(model, params.group_by);
 	const [problem] = optionErrors(params, dated);
 	if (problem) throw problem;
+	if (params.split_by !== void 0 && !Object.hasOwn(model.fields, params.split_by)) throw invalid("split_by", `Unknown field "${params.split_by}"`);
 	const warning = await deps.guard(entry, {
 		...filter && { filter },
 		groupBy: params.group_by
@@ -82,10 +94,45 @@ const aggregate = async (deps, entry, session, input) => {
 		model,
 		scope
 	});
+	const splitWarning = params.split_by === void 0 ? void 0 : await deps.guard(entry, {
+		...filter && { filter },
+		groupBy: params.split_by
+	}, {
+		model,
+		scope
+	});
 	if (dated) {
 		const granularity = params.granularity ?? "day";
 		const timeZone = params.time_zone ?? "UTC";
 		const range = await seriesRange(deps, access, params.group_by, params, scope);
+		if (params.split_by !== void 0) {
+			const split = {
+				by: params.split_by,
+				...params.split_limit !== void 0 && { limit: params.split_limit },
+				...params.split_label !== void 0 && { label: params.split_label }
+			};
+			const parts = range ? await splitGroups(deps, session, model, params.group_by, split, {
+				range,
+				granularity,
+				timeZone,
+				...filter && { filter },
+				...measure && { measure },
+				scope
+			}) : {
+				splits: [],
+				groups: []
+			};
+			return {
+				body: {
+					group_by: params.group_by,
+					split_by: params.split_by,
+					granularity,
+					time_zone: timeZone,
+					...parts
+				},
+				warning: warning ?? splitWarning
+			};
+		}
 		const groups = (range ? await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => series(trx, model, params.group_by, {
 			range,
 			granularity,

package/dist/aggregate-splits.js

@@ -0,0 +1,41 @@
+import { readTransaction } from "./transactions.js";
+import { labelRequests, relatedLabels } from "./related-labels.js";
+import { series, splitSeries } from "@protobase/query";
+//#region src/aggregate-splits.ts
+/**
+* The buckets of a date field with each split into its parts: per bucket the shown values that have rows in it, in
+* rank order. The bucket's own totals stay what `series` finds, so what the other values add up to is total minus parts.
+* With `label`, a relation's values carry the `label` field of the record each points at.
+*/
+const splitGroups = async (deps, session, model, field, split, options) => {
+	const labels = split.label === void 0 ? [] : await labelRequests(deps, session, model, [split.by], `${split.by}.${split.label}`);
+	return readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+		const buckets = await series(trx, model, field, options);
+		const { splits, points } = await splitSeries(trx, model, field, split.by, {
+			...options,
+			...split.limit !== void 0 && { limit: split.limit }
+		});
+		const names = (await relatedLabels(trx, labels, splits.map((value) => ({ [split.by]: value }))))[split.by] ?? {};
+		const partsOf = /* @__PURE__ */ new Map();
+		for (const { bucket, split: value, ...totals } of points) partsOf.set(bucket, [...partsOf.get(bucket) ?? [], {
+			value,
+			...totals
+		}]);
+		return {
+			splits: splits.map((value) => {
+				const label = value === null ? void 0 : names[String(value)];
+				return label === void 0 ? { value } : {
+					value,
+					label
+				};
+			}),
+			groups: buckets.map(({ bucket, ...totals }) => ({
+				value: bucket,
+				...totals,
+				splits: partsOf.get(bucket) ?? []
+			}))
+		};
+	});
+};
+//#endregion
+export { splitGroups };

package/dist/openapi/resource-paths.js

@@ -590,7 +590,7 @@ const resourcePaths = (access) => {
 			operationId: `aggregate_${entry.name}`,
 			tags: tag,
 			summary: `Totals per group of ${entry.name} records`,
-			description: "Groups the records the filter finds, its own terms on `group_by` included, by the value of a field, or by the hour, day, week, month or year of a date or timestamp field with the empty ones included. Each group has its count and, with `sum` or `average`, that of a numeric field, `null` when no record of the group has a value. Value groups come largest first. An index must serve the grouped field.",
+			description: "Groups the records the filter finds, its own terms on `group_by` included, by the value of a field, or by the hour, day, week, month or year of a date or timestamp field with the empty ones included. Each group has its count and, with `sum` or `average`, that of a numeric field, `null` when no record of the group has a value. Value groups come largest first. An index must serve the grouped field. A date group can be split: see `split_by`.",
 			parameters: [
 				query("group_by", "A filterable field", { type: "string" }, true),
 				param("filter"),
@@ -620,7 +620,10 @@ const resourcePaths = (access) => {
 				}),
 				query("from", "For a date group_by: the explicit start (ISO 8601); with `to`, replaces range"),
 				query("to", "For a date group_by: the exclusive end (ISO 8601), default now"),
-				query("time_zone", "For a date group_by: the IANA time zone of the buckets, default UTC")
+				query("time_zone", "For a date group_by: the IANA time zone of the buckets, default UTC"),
+				query("split_by", "For a date group_by: a filterable field of values that splits each bucket into parts; an index must serve it"),
+				query("split_limit", "For a date group_by: how many values of `split_by` to keep, the largest over the range (by the sum, else by count), default 8, at most 100", { type: "integer" }),
+				query("split_label", "For a date group_by with a relation `split_by`: the field of the related resource whose value each split carries as `label`")
 			],
 			responses: {
 				200: {
@@ -631,6 +634,21 @@ const resourcePaths = (access) => {
 							group_by: { type: "string" },
 							granularity: { type: "string" },
 							time_zone: { type: "string" },
+							split_by: {
+								type: "string",
+								description: "Only with `split_by`"
+							},
+							splits: {
+								type: "array",
+								description: "Only with `split_by`: the kept values, largest first",
+								items: {
+									type: "object",
+									properties: {
+										value: {},
+										label: { type: "string" }
+									}
+								}
+							},
 							groups: {
 								type: "array",
 								items: {
@@ -640,7 +658,20 @@ const resourcePaths = (access) => {
 										label: { type: "string" },
 										count: { type: "integer" },
 										sum: { type: ["number", "null"] },
-										average: { type: ["number", "null"] }
+										average: { type: ["number", "null"] },
+										splits: {
+											type: "array",
+											description: "Only with `split_by`: the kept values that have rows in the group, in rank order",
+											items: {
+												type: "object",
+												properties: {
+													value: {},
+													count: { type: "integer" },
+													sum: { type: ["number", "null"] },
+													average: { type: ["number", "null"] }
+												}
+											}
+										}
 									}
 								}
 							}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.22.6",
+  "version": "0.22.8",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,9 +31,9 @@
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
     "@better-auth/sso": "^1.7.7",
-    "@protobase/layout": "0.22.6",
-    "@protobase/query": "0.22.6",
-    "@protobase/schema": "0.22.6",
+    "@protobase/layout": "0.22.8",
+    "@protobase/query": "0.22.8",
+    "@protobase/schema": "0.22.8",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",