@protobase/server 0.19.16 → 0.20.0

package/dist/aggregate-groups.js

@@ -0,0 +1,137 @@
+import { badRequest } from "./problem.js";
+import { readTransaction } from "./transactions.js";
+import { parseParams } from "./params.js";
+import { labelRequests, relatedLabels } from "./related-labels.js";
+import { scoped, seriesRange } from "./aggregate-service.js";
+import { groupTotals, series } from "@protobase/query";
+import { z } from "zod";
+//#region src/aggregate-groups.ts
+const name = z.string().min(1);
+const aggregateParams = z.object({
+	group_by: name,
+	filter: z.string().optional(),
+	sum: name.optional(),
+	average: name.optional(),
+	limit: z.coerce.number().int().optional(),
+	label: name.optional(),
+	range: z.enum([
+		"7d",
+		"30d",
+		"90d",
+		"1y",
+		"all"
+	]).optional(),
+	from: z.string().optional(),
+	to: z.string().optional(),
+	granularity: z.enum([
+		"hour",
+		"day",
+		"week",
+		"month",
+		"year"
+	]).optional(),
+	time_zone: z.string().optional()
+});
+const invalid = (parameter, message) => badRequest("invalid-parameter", `Invalid parameter ${parameter}: ${message}`, { errors: [{
+	parameter,
+	message
+}] });
+const measureOf = (params) => {
+	if (params.sum !== void 0 && params.average !== void 0) throw invalid("average", "Give sum or average, not both");
+	if (params.sum !== void 0) return {
+		kind: "sum",
+		field: params.sum
+	};
+	if (params.average !== void 0) return {
+		kind: "average",
+		field: params.average
+	};
+};
+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`));
+	return given([
+		"range",
+		"from",
+		"to",
+		"granularity",
+		"time_zone"
+	]).map((option) => invalid(option, "Only for a date or timestamp group_by"));
+};
+const isDated = (model, field) => {
+	const type = model.fields[field]?.type;
+	return type === "date" || type === "timestamp";
+};
+/**
+* Records per value of a field, or per hour, day, week, month or year of a date field with the empty ones included,
+* each with how many there are and, with `sum` or `average`, that of a numeric field. Read as a list is: the caller's
+* filter on the model as they see it, inside their tenant and row filter; the scan guard judges the grouped field.
+*/
+const aggregate = async (deps, entry, session, input) => {
+	const params = parseParams(aggregateParams, input);
+	const { access, model, filter, scope } = await scoped(deps, entry, session, params.filter);
+	if (!Object.hasOwn(model.fields, params.group_by)) throw invalid("group_by", `Unknown field "${params.group_by}"`);
+	const measure = measureOf(params);
+	const dated = isDated(model, params.group_by);
+	const [problem] = optionErrors(params, dated);
+	if (problem) throw problem;
+	const warning = await deps.guard(entry, {
+		...filter && { filter },
+		groupBy: params.group_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);
+		const groups = (range ? await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => series(trx, model, params.group_by, {
+			range,
+			granularity,
+			timeZone,
+			...filter && { filter },
+			...measure && { measure },
+			scope
+		})) : []).map(({ bucket, ...totals }) => ({
+			value: bucket,
+			...totals
+		}));
+		return {
+			body: {
+				group_by: params.group_by,
+				granularity,
+				time_zone: timeZone,
+				groups
+			},
+			warning
+		};
+	}
+	const labels = params.label === void 0 ? [] : await labelRequests(deps, session, model, [params.group_by], `${params.group_by}.${params.label}`);
+	return {
+		body: await readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+			const totals = await groupTotals(trx, model, params.group_by, {
+				statementTimeoutMs: deps.statementTimeoutMs,
+				...filter && { filter },
+				...measure && { measure },
+				...params.limit !== void 0 && { limit: params.limit },
+				scope
+			});
+			const names = (await relatedLabels(trx, labels, totals.map((group) => ({ [params.group_by]: group.value }))))[params.group_by] ?? {};
+			const groups = totals.map((group) => {
+				const label = group.value === null ? void 0 : names[String(group.value)];
+				return label === void 0 ? group : {
+					...group,
+					label
+				};
+			});
+			return {
+				group_by: params.group_by,
+				groups
+			};
+		}),
+		warning
+	};
+};
+//#endregion
+export { aggregate };

package/dist/aggregate-service.js

@@ -103,25 +103,26 @@ const earliest = async (deps, access, fieldName, scope) => {
 	return (await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => sql`select min(${columnId(target)})::text as lowest from ${tableId(access.full)} as t${whereClause(conditions)}`.execute(trx))).rows[0]?.lowest ?? void 0;
 };
 const bound = (model, fieldName, value) => model.fields[fieldName]?.type === "date" ? value.slice(0, 10) : value;
-const seriesRange = async (deps, access, params, scope) => {
+/** The span a series of `field` covers: `from` and `to`, else the `range` up to now, `all` from the earliest row. */
+const seriesRange = async (deps, access, field, params, scope) => {
 	const to = params.to ?? (/* @__PURE__ */ new Date()).toISOString();
 	const { model } = access;
 	if (params.from) return {
-		from: bound(model, params.field, params.from),
-		to: bound(model, params.field, to)
+		from: bound(model, field, params.from),
+		to: bound(model, field, to)
 	};
 	const range = params.range ?? "30d";
 	if (range !== "all") {
 		const from = (/* @__PURE__ */ new Date(Date.now() - rangeDays[range] * 864e5)).toISOString();
 		return {
-			from: bound(model, params.field, from),
-			to: bound(model, params.field, to)
+			from: bound(model, field, from),
+			to: bound(model, field, to)
 		};
 	}
-	const lowest = await earliest(deps, access, params.field, scope);
+	const lowest = await earliest(deps, access, field, scope);
 	return lowest ? {
-		from: bound(model, params.field, lowest),
-		to: bound(model, params.field, to)
+		from: bound(model, field, lowest),
+		to: bound(model, field, to)
 	} : void 0;
 };
 /** Row counts per calendar bucket of a date or timestamp field, empty buckets included. */
@@ -132,7 +133,7 @@ const timeSeries = async (deps, entry, session, input) => {
 		parameter: "field",
 		message: "Unknown field"
 	}] });
-	const range = await seriesRange(deps, access, params, scope);
+	const range = await seriesRange(deps, access, params.field, params, scope);
 	const timeZone = params.time_zone ?? "UTC";
 	const points = range ? await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => series(trx, model, params.field, {
 		range,
@@ -159,4 +160,4 @@ const numericHistogram = async (deps, entry, session, input) => {
 	};
 };
 //#endregion
-export { facets, numericHistogram, timeSeries };
+export { facets, numericHistogram, scoped, seriesRange, timeSeries };

package/dist/check-view-queries.js

@@ -1,3 +1,4 @@
+import { isGroupChart } from "@protobase/schema/internal";
 //#region src/check-view-queries.ts
 const widgetName = {
 	facets: "facets filter",
@@ -24,7 +25,7 @@ const searchErrors = (model, view) => (view.list?.search ?? []).filter((name) =>
 */
 const viewQueryErrors = (view, model) => [
 	...view.filters.flatMap((widget) => filterableErrors(model, widget.kind === "flags" ? widget.fields : [widget.field], `the ${widgetName[widget.kind]}`)),
-	...view.chart ? filterableErrors(model, [view.chart.field], "the chart") : [],
+	...view.chart ? filterableErrors(model, [isGroupChart(view.chart) ? view.chart.groupBy : view.chart.field], "the chart") : [],
 	...listSortErrors(model, view),
 	...searchErrors(model, view)
 ];

package/dist/check-views.js

@@ -2,10 +2,11 @@ import { relatedErrors } from "./view-related.js";
 import { cardPhotosErrors } from "./view-card-photos.js";
 import { cardFavoriteErrors, favoriteOwnerErrors } from "./view-card-favorite.js";
 import { saveSearchErrors, searchesOfErrors } from "./view-saved-search.js";
+import { chartErrors } from "./view-chart.js";
 import { mapDisplayErrors, mapErrors } from "./view-map.js";
 import { relatedColumnErrors } from "./view-related-column.js";
 import { editableErrors } from "./view-editable.js";
-import { actionInputErrors, addressErrors, addressPlaceholders, boardErrors, displayFields, fieldRefsIn, hrefField, hrefPlaceholders, linkActionError } from "@protobase/schema/internal";
+import { actionInputErrors, addressErrors, addressPlaceholders, boardErrors, chartFields, displayFields, fieldRefsIn, hrefField, hrefPlaceholders, linkActionError } from "@protobase/schema/internal";
 //#region src/check-views.ts
 const linkFields = (run) => run?.kind !== "link" ? [] : "to" in run ? addressPlaceholders(run.to) : hrefPlaceholders(run.href);
 const sensitiveErrors = (view, model) => {
@@ -20,7 +21,7 @@ const sensitiveErrors = (view, model) => {
 		]],
 		["a list display", (view.list?.displays ?? []).flatMap(displayFields)],
 		["a filter", view.filters.flatMap((widget) => widget.kind === "flags" ? widget.fields : [widget.field])],
-		["the chart", view.chart ? [view.chart.field] : []],
+		["the chart", view.chart ? chartFields(view.chart) : []],
 		["the sidebar", view.layout.flatMap((item) => item.kind === "sidebar" ? item.fields : [])],
 		["a map", view.layout.flatMap((item) => item.kind === "map" ? [item.latitude, item.longitude] : [])],
 		["a gallery", view.layout.flatMap((item) => item.kind === "gallery" && item.image !== void 0 ? [item.image] : [])],
@@ -111,7 +112,7 @@ const listOfErrors = (model, name, models) => {
 * edits a list column in its cell that is not a field with an editor of one line the API may write,
 * has a related section or related list column, a cards display's or gallery's photos or a cards display's favorite button, a `listOf`, a "Save search" button or a
 * `searchesOf` that do not fit the resources, cards
-* displays of one list that name different photos, a map that cannot show the
+* displays of one list that name different photos, a chart per value that cannot group or add up its fields, a map that cannot show the
 * record's position or a map display that cannot find the records in its view, a board whose columns are no filterable enum, a link to an address the app does not have, action inputs that do not fit, or a create page that is not one of `pages`.
 */
 const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
@@ -131,6 +132,7 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 		const searches = [...view.saveSearch ? saveSearchErrors(view.saveSearch, view.resource, models, views).map((error) => `saveSearch: ${error}`) : [], ...view.searchesOf ? searchesOfErrors(view.searchesOf, view.resource, models).map((error) => `searchesOf: ${error}`) : []];
 		const maps = [...view.layout.flatMap((item) => item.kind === "map" ? mapErrors(item, model).map((error) => `map "${item.title}": ${error}`) : []), ...(view.list?.displays ?? []).flatMap((display) => display.kind === "map" ? mapDisplayErrors(display, model).map((error) => `display "${display.name}": ${error}`) : [])];
 		const boards = (view.list?.displays ?? []).flatMap((display) => display.kind === "board" ? boardErrors(display, model).map((error) => `display "${display.name}": ${error}`) : []);
+		const chart = view.chart ? chartErrors(view.chart, model).map((error) => `chart: ${error}`) : [];
 		return [
 			...sensitiveErrors(view, model),
 			...unknownFieldErrors(view, model),
@@ -146,6 +148,7 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 			...searches,
 			...maps,
 			...boards,
+			...chart,
 			...linkErrors(view, model, models, pageNames),
 			...inputErrors(view, models),
 			...createErrors(view, pageNames)

package/dist/openapi/resource-paths.js

@@ -130,6 +130,7 @@ const needs = {
 	list: "list",
 	search: "list",
 	facets: "list",
+	aggregate: "list",
 	series: "list",
 	histogram: "list",
 	map: "list",
@@ -363,6 +364,71 @@ const resourcePaths = (access) => {
 				...auth
 			}
 		} },
+		[`/${entry.name}:aggregate`]: { get: {
+			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.",
+			parameters: [
+				query("group_by", "A filterable field", { type: "string" }, true),
+				param("filter"),
+				query("sum", "A numeric field to add up per group"),
+				query("average", "A numeric field to average per group, instead of `sum`"),
+				query("limit", "Most value groups to return, default 100, at most 1000", { type: "integer" }),
+				query("label", "For a relation to a single-key resource: the field of that resource whose value each group carries as `label`"),
+				query("granularity", "For a date group_by: the bucket, default day", {
+					type: "string",
+					enum: [
+						"hour",
+						"day",
+						"week",
+						"month",
+						"year"
+					]
+				}),
+				query("range", "For a date group_by: the relative range ending now (default 30d); `all` starts at the earliest row", {
+					type: "string",
+					enum: [
+						"7d",
+						"30d",
+						"90d",
+						"1y",
+						"all"
+					]
+				}),
+				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")
+			],
+			responses: {
+				200: {
+					description: "The groups; a date group's `value` is its bucket in local ISO time",
+					content: json({
+						type: "object",
+						properties: {
+							group_by: { type: "string" },
+							granularity: { type: "string" },
+							time_zone: { type: "string" },
+							groups: {
+								type: "array",
+								items: {
+									type: "object",
+									properties: {
+										value: {},
+										label: { type: "string" },
+										count: { type: "integer" },
+										sum: { type: ["number", "null"] },
+										average: { type: ["number", "null"] }
+									}
+								}
+							}
+						}
+					})
+				},
+				400: error("BadRequest"),
+				...auth
+			}
+		} },
 		[`/${entry.name}:series`]: { get: {
 			operationId: `series_${entry.name}`,
 			tags: tag,

package/dist/routes/collection.js

@@ -1,6 +1,7 @@
 import { runWrite } from "../write-pipeline.js";
 import { listRecords } from "../list-service.js";
 import { facets, numericHistogram, timeSeries } from "../aggregate-service.js";
+import { aggregate } from "../aggregate-groups.js";
 import { mapRecords } from "../map-service.js";
 import { uploadFile } from "../files/upload.js";
 import { returnPreference } from "./preferences.js";
@@ -25,6 +26,10 @@ const collectionRoutes = (deps) => {
 			const { body, warning } = await facets(deps, entry, session, query);
 			return c.json(body, 200, warningHeader(warning));
 		}
+		if (action === "aggregate") {
+			const { body, warning } = await aggregate(deps, entry, session, query);
+			return c.json(body, 200, warningHeader(warning));
+		}
 		if (action === "series") return c.json(await timeSeries(deps, entry, session, query));
 		if (action === "histogram") return c.json(await numericHistogram(deps, entry, session, query));
 		if (action === "map") {

package/dist/view-access.js

@@ -4,7 +4,7 @@ import { cardFavoriteErrors } from "./view-card-favorite.js";
 import { searchesOfFor } from "./view-saved-search.js";
 import { relatedColumnErrors } from "./view-related-column.js";
 import { resolveFieldPath } from "@protobase/layout";
-import { addressErrors, hrefPlaceholders, navRecentErrors, pruneByShape, shapes, tableDisplay } from "@protobase/schema/internal";
+import { addressErrors, chartFields, hrefPlaceholders, navRecentErrors, pruneByShape, shapes, tableDisplay } from "@protobase/schema/internal";
 //#region src/view-access.ts
 const pruneRelated = (item, resource, models) => {
 	const { columns, ...rest } = item;
@@ -218,11 +218,7 @@ const viewShape = (resource, model, models, prompted) => shapes.object({
 	list: listShape(resource, model, models, prompted),
 	filters: shapes.list(widgetShape),
 	layout: shapes.list(layoutShape(resource, model, models)),
-	chart: shapes.object({
-		field: shapes.field,
-		range: shapes.data,
-		granularity: shapes.data
-	}, { requires: ["field"] }),
+	chart: shapes.map((chart) => chartFields(chart).every((name) => Object.hasOwn(model.fields, name)) ? chart : void 0),
 	recordMode: shapes.data,
 	helpWhen: shapes.data,
 	saveFeedback: shapes.data,

package/dist/view-chart.js

@@ -0,0 +1,33 @@
+import { isGroupChart } from "@protobase/schema/internal";
+//#region src/view-chart.ts
+const numericTypes = [
+	"integer",
+	"bigint",
+	"decimal"
+];
+const ungroupable = [
+	"date",
+	"timestamp",
+	"json",
+	"file"
+];
+/**
+* What is wrong with a list's chart per value of a field: a field to group by that has no values to share out, or one
+* to add up that is no number. The filterable and sensitive checks of every chart are with the other fields'.
+*/
+const chartErrors = (chart, model) => {
+	if (!isGroupChart(chart)) return [];
+	const fieldOf = (name) => Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
+	const group = fieldOf(chart.groupBy);
+	const measured = chart.sum ?? chart.average;
+	const measure = measured === void 0 ? void 0 : fieldOf(measured);
+	return [
+		...!group ? [`groupBy: unknown field "${chart.groupBy}" on ${model.name}`] : [],
+		...group && ungroupable.includes(group.type) ? [`groupBy: "${chart.groupBy}" is a ${group.type} field; chart a date with { field, range, granularity }, and group by a field of values`] : [],
+		...measured !== void 0 && !measure ? [`unknown field "${measured}" on ${model.name} to add up`] : [],
+		...measure && !numericTypes.includes(measure.type) ? [`"${measured}" is ${measure.type}, and only a number can be added up`] : [],
+		...chart.type === "donut" && chart.average !== void 0 ? ["a donut shares out a total, and averages add up to none: count or sum instead"] : []
+	];
+};
+//#endregion
+export { chartErrors };

package/package.json

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