@protobase/server 0.22.5 → 0.22.7

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/check-view-queries.js

@@ -1,4 +1,4 @@
-import { isGroupChart } from "@protobase/schema/internal";
+import { isGroupChart, viewOfList } from "@protobase/schema/internal";
 import { checkFilter, parseFilter } from "@protobase/schema";
 //#region src/check-view-queries.ts
 const widgetName = {
@@ -45,7 +45,8 @@ const checkViewQueries = (models, views) => {
 	const byName = new Map(models.map((model) => [model.name, model]));
 	const problems = views.flatMap((view) => {
 		const model = byName.get(view.resource);
-		return model ? viewQueryErrors(view, model).map((problem) => `View "${view.resource}": ${problem}`) : [];
+		if (!model) return [];
+		return [...viewQueryErrors(view, model).map((problem) => `View "${view.resource}": ${problem}`), ...(view.lists ?? []).flatMap((named) => viewQueryErrors(viewOfList(view, named.name), model).map((problem) => `View "${view.resource}" list "${named.name}": ${problem}`))];
 	});
 	if (problems.length > 0) throw new Error(`The views ask for what their resources do not allow:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
 };

package/dist/check-views.js

@@ -7,7 +7,7 @@ import { mapDisplayErrors, mapErrors } from "./view-map.js";
 import { relatedColumnErrors } from "./view-related-column.js";
 import { editableErrors } from "./view-editable.js";
 import { conditionProblems } from "@protobase/layout";
-import { actionInputErrors, addressErrors, addressPlaceholders, boardErrors, calendarErrors, chartFields, displayFields, fieldRefsIn, hrefField, hrefPlaceholders, layoutItems, linkActionError, promptError, promptFields, updateSetErrors } from "@protobase/schema/internal";
+import { actionInputErrors, addressErrors, addressPlaceholders, boardErrors, calendarErrors, chartFields, displayFields, fieldRefsIn, hrefField, hrefPlaceholders, layoutItems, linkActionError, promptError, promptFields, updateSetErrors, viewOfList } from "@protobase/schema/internal";
 import { isRecordCondition } from "@protobase/schema";
 //#region src/check-views.ts
 const linkFields = (run) => run?.kind !== "link" ? [] : "to" in run ? addressPlaceholders(run.to) : hrefPlaceholders(run.href);
@@ -151,9 +151,7 @@ const listOfErrors = (model, name, models) => {
 const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 	const models = Object.fromEntries(registry.entries.map((entry) => [entry.name, entry.model]));
 	const pageNames = new Set(pages);
-	const problems = views.flatMap((view) => {
-		const model = models[view.resource];
-		if (!model) return [];
+	const viewProblems = (view, model) => {
 		const related = [...layoutItems(view.layout).flatMap((item) => item.kind === "related" ? relatedErrors(item, view.resource, models).map((error) => `related "${item.title}": ${error}`) : []), ...relatedColumnsErrors(view, model, models)];
 		const photos = [
 			...(view.list?.displays ?? []).flatMap((display) => display.kind === "cards" && display.photos ? cardPhotosErrors(display.photos, view.resource, models).map((error) => `display "${display.name}" photos: ${error}`) : []),
@@ -193,7 +191,16 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 			...aiActionErrors(view, model),
 			...inputErrors(view, models),
 			...createErrors(view, pageNames)
-		].map((problem) => `View "${view.resource}": ${problem}`);
+		];
+	};
+	const problems = views.flatMap((view) => {
+		const model = models[view.resource];
+		if (!model) return [];
+		return [...viewProblems(view, model).map((problem) => `View "${view.resource}": ${problem}`), ...(view.lists ?? []).flatMap((named) => viewProblems({
+			...viewOfList(view, named.name),
+			layout: [],
+			actions: []
+		}, model).map((problem) => `View "${view.resource}" list "${named.name}": ${problem}`))];
 	});
 	if (problems.length > 0) throw new Error(`The views do not match the resources:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
 };

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/dist/view-access.js

@@ -255,41 +255,54 @@ const actionShape = (model, models) => shapes.object({
 	}),
 	inputs: inputsShape(models)
 }, { requires: ["run", "inputs"] });
-const viewShape = (resource, model, models, prompted) => shapes.object({
-	resource: shapes.data,
-	roles: shapes.data,
-	title: shapes.field,
-	searchResult: shapes.object({
-		title: shapes.list(shapes.field, { nonEmpty: true }),
-		subtitle: shapes.field
-	}),
-	nav: shapes.object({
+const viewShape = (resource, model, models, prompted) => {
+	const nav = shapes.object({
 		hidden: shapes.data,
 		group: shapes.data,
 		order: shapes.data,
 		recent: shapes.map((recent) => navRecentErrors(recent, model).length === 0 ? recent : void 0)
-	}),
-	names: shapes.data,
-	icon: shapes.data,
-	help: shapes.data,
-	fields: shapes.keys(),
-	list: listShape(resource, model, models, prompted),
-	filters: shapes.list(widgetShape),
-	layout: shapes.list(layoutShape(resource, model, models)),
-	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,
-	actions: shapes.list(actionShape(model, models)),
-	listOf: shapes.field,
-	signIn: shapes.data,
-	saveSearch: shapes.map((search) => prompted.has(search.resource) || models[search.resource] ? search : void 0),
-	searchesOf: shapes.map((searches) => searchesOfFor(searches, resource, models)),
-	import: shapes.data,
-	export: shapes.data,
-	create: shapes.data,
-	forms: shapes.map(() => void 0)
-});
+	});
+	const chart = shapes.map((chart) => chartFields(chart).every((name) => Object.hasOwn(model.fields, name)) ? chart : void 0);
+	return shapes.object({
+		resource: shapes.data,
+		roles: shapes.data,
+		title: shapes.field,
+		searchResult: shapes.object({
+			title: shapes.list(shapes.field, { nonEmpty: true }),
+			subtitle: shapes.field
+		}),
+		nav,
+		names: shapes.data,
+		icon: shapes.data,
+		help: shapes.data,
+		fields: shapes.keys(),
+		list: listShape(resource, model, models, prompted),
+		filters: shapes.list(widgetShape),
+		layout: shapes.list(layoutShape(resource, model, models)),
+		chart,
+		recordMode: shapes.data,
+		helpWhen: shapes.data,
+		saveFeedback: shapes.data,
+		actions: shapes.list(actionShape(model, models)),
+		listOf: shapes.field,
+		signIn: shapes.data,
+		saveSearch: shapes.map((search) => prompted.has(search.resource) || models[search.resource] ? search : void 0),
+		searchesOf: shapes.map((searches) => searchesOfFor(searches, resource, models)),
+		import: shapes.data,
+		export: shapes.data,
+		create: shapes.data,
+		forms: shapes.map(() => void 0),
+		lists: shapes.list(shapes.object({
+			name: shapes.data,
+			names: shapes.data,
+			nav,
+			help: shapes.data,
+			list: listShape(resource, model, models, prompted),
+			filters: shapes.list(widgetShape),
+			chart
+		}))
+	});
+};
 /**
 * The view with every reference to a field the caller cannot read removed: list columns, sort, search and displays,
 * field hints, filter widgets, record sections, maps, galleries and custom components' props, the chart, title and search result, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.22.5",
+  "version": "0.22.7",
   "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.5",
-    "@protobase/query": "0.22.5",
-    "@protobase/schema": "0.22.5",
+    "@protobase/layout": "0.22.7",
+    "@protobase/query": "0.22.7",
+    "@protobase/schema": "0.22.7",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",