@protobase/server 0.19.16 → 0.21.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/changes/actor.js

@@ -1,7 +1,7 @@
 import { runningJobs } from "../jobs/current.js";
 import { dispatchJobName } from "./capture-sql.js";
 //#region src/changes/actor.ts
-/** The setting a write transaction sets so the change capture records who wrote, when a resource has events. */
+/** The setting a write transaction sets so the change capture records who wrote, when a resource has events or history. */
 const actorSettings = (deps, session) => {
 	if (!deps.actorSetting) return {};
 	const actor = {

package/dist/changes/capture-plan.js

@@ -1,4 +1,5 @@
-import { captureBody, captureFunctionSql, createTriggerSql, dropTriggerSql, outboxSql, quoteIdent, resourceTriggers, tableSql } from "./capture-sql.js";
+import { captureBody, captureFunctionSql, createTriggerSql, dropTriggerSql, isCaptured, outboxSql, quoteIdent, resourceTriggers, tableSql } from "./capture-sql.js";
+import { historyTableSql } from "../history/history-sql.js";
 //#region src/changes/capture-plan.ts
 const sameTrigger = (found, wanted) => found.type === wanted.type && found.args.length === wanted.args.length && found.args.every((arg, index) => arg === wanted.args[index]);
 const tableOf = (state, model) => {
@@ -7,14 +8,14 @@ const tableOf = (state, model) => {
 	return table;
 };
 /**
-* Compares the database with the resources that declare events. Fails on what it cannot change safely: a missing
-* table, two resources with events on one table, or a trigger of the same name that calls another function.
+* Compares the database with the resources that declare events or history. Fails on what it cannot change safely: a
+* missing table, two captured resources on one table, or a trigger of the same name that calls another function.
 */
 const capturePlan = (schema, models, state) => {
-	const withEvents = models.filter((model) => (model.events ?? []).length > 0);
+	const captured = models.filter(isCaptured);
 	const capture = state.capture;
 	const current = capture !== void 0 && capture.definer && capture.source === captureBody(schema);
-	const wanted = withEvents.flatMap((model) => resourceTriggers(model).map((trigger) => ({
+	const wanted = captured.flatMap((model) => resourceTriggers(model).map((trigger) => ({
 		model,
 		trigger,
 		table: tableOf(state, model)
@@ -22,17 +23,18 @@ const capturePlan = (schema, models, state) => {
 	const tables = /* @__PURE__ */ new Map();
 	for (const { model, table } of wanted) {
 		const other = tables.get(table);
-		if (other && other !== model.name) throw new Error(`Not implemented: resources "${other}" and "${model.name}" both have events on table ${tableSql(model)}; declare them on one`);
+		if (other && other !== model.name) throw new Error(`Not implemented: resources "${other}" and "${model.name}" both have events or history on table ${tableSql(model)}; declare them on one`);
 		tables.set(table, model.name);
 	}
 	const create = wanted.filter(({ model, trigger, table }) => {
 		const found = state.triggers.find((candidate) => candidate.table === table && candidate.name === trigger.name);
-		if (found && found.function !== capture?.oid) throw new Error(`Table ${tableSql(model)} has a trigger "${trigger.name}" of its own; rename it, since events need that name`);
+		if (found && found.function !== capture?.oid) throw new Error(`Table ${tableSql(model)} has a trigger "${trigger.name}" of its own; rename it, since events and history need that name`);
 		return !found || !sameTrigger(found, trigger);
 	});
 	const drop = state.triggers.filter((found) => found.function === capture?.oid).filter((found) => !wanted.some(({ trigger, table }) => table === found.table && trigger.name === found.name));
 	return {
-		setup: withEvents.length > 0 && (!state.outbox || !current),
+		setup: captured.length > 0 && (!state.outbox || !current),
+		history: models.some((model) => model.history) && !state.history,
 		create: create.map(({ model, trigger }) => ({
 			model,
 			trigger
@@ -51,12 +53,13 @@ const planSql = (schema, plan) => {
 			outboxSql(schema),
 			captureFunctionSql(schema)
 		] : [],
+		...plan.history ? [`create schema if not exists ${quoteIdent(schema)}`, historyTableSql(schema)] : [],
 		...plan.drop.map(({ name, tableSql }) => dropTriggerSql(name, tableSql)),
 		...plan.create.flatMap(({ model, trigger }) => [dropTriggerSql(trigger.name, tableSql(model)), createTriggerSql(schema, trigger, tableSql(model))])
 	];
 	return statements.length === 0 ? void 0 : `${statements.join(";\n\n")};`;
 };
-/** The resources whose changes would not be captured as the config declares: what a server refuses to start with. */
-const uncaptured = (plan, models) => plan.setup ? models.filter((model) => (model.events ?? []).length > 0).map((model) => model.name) : [...new Set(plan.create.map(({ model }) => model.name))];
+/** The resources whose changes would not be captured or kept as the config declares: what a server refuses to start with. */
+const uncaptured = (plan, models) => [...new Set([...plan.setup ? models.filter(isCaptured) : plan.create.map(({ model }) => model), ...plan.history ? models.filter((model) => model.history) : []].map((model) => model.name))];
 //#endregion
 export { capturePlan, planSql, uncaptured };

package/dist/changes/capture-schema.d.ts

@@ -5,14 +5,16 @@ import { Db } from "@protobase/query";
 /** The command that writes what the config needs as a migration file of the project. */
 export declare const migrationCommand = "protobase migration";
 /**
- * The SQL that brings the database to the capture the resources' events need: the schema with the outbox and
- * `capture()`, and a trigger pair per resource with events, recreated when its fields changed; triggers of resources
- * without events any more are dropped. `undefined` when the database is current. Tables are never dropped.
+ * The SQL that brings the database to the capture the resources' events and history need: the schema with the outbox
+ * and `capture()`, the history table, and a trigger pair per resource with either, recreated when its fields changed;
+ * triggers of resources without either any more are dropped. `undefined` when the database is current. Tables are
+ * never dropped.
  */
 export declare const changesMigration: (db: Db, models: readonly ResourceModel[], options?: EventsOptions) => Promise<string | undefined>;
 /**
- * Refuses to go on while a resource's events would not be captured as declared: a missing or out-of-date schema, or
- * trigger. The server never changes the schema itself: the project's migrations do, before the new version serves.
+ * Refuses to go on while a resource's events or history would not be captured as declared: a missing or out-of-date
+ * schema, history table or trigger. The server never changes the schema itself: the project's migrations do, before the
+ * new version serves.
  */
 export declare const checkChanges: (db: Db, models: readonly ResourceModel[], options?: EventsOptions) => Promise<void>;
 //#endregion

package/dist/changes/capture-schema.js

@@ -1,4 +1,4 @@
-import { quoteIdent, tableSql } from "./capture-sql.js";
+import { isCaptured, quoteIdent, tableSql } from "./capture-sql.js";
 import { changesSchema } from "./events-options.js";
 import { capturePlan, planSql, uncaptured } from "./capture-plan.js";
 import { sql } from "kysely";
@@ -11,7 +11,7 @@ const triggerArgs = (hex) => {
 };
 const rowsOf = async (db, query) => (await query.execute(db)).rows;
 const readCaptureState = async (db, schema, models) => {
-	const [outbox] = await rowsOf(db, sql`select to_regclass(${`${quoteIdent(schema)}."outbox"`}) is not null as found`);
+	const exists = async (table) => (await rowsOf(db, sql`select to_regclass(${`${quoteIdent(schema)}.${quoteIdent(table)}`}) is not null as found`))[0]?.found ?? false;
 	const [capture] = await rowsOf(db, sql`select p.oid::text as oid, p.prosrc as source, p.prosecdef as definer from pg_proc p join pg_namespace n on n.oid = p.pronamespace where n.nspname = ${schema} and p.proname = 'capture' and p.pronargs = 0`);
 	const tables = {};
 	for (const model of models) {
@@ -24,7 +24,8 @@ const readCaptureState = async (db, schema, models) => {
       from pg_trigger t join pg_class c on c.oid = t.tgrelid join pg_namespace ns on ns.oid = c.relnamespace
       where not t.tgisinternal and (t.tgfoid::text = ${capture?.oid ?? ""} or t.tgrelid::text = any(${oids}::text[]))`);
 	return {
-		outbox: outbox?.found ?? false,
+		outbox: await exists("outbox"),
+		history: await exists("history"),
 		...capture && { capture },
 		triggers: triggers.map((trigger) => ({
 			...trigger,
@@ -35,31 +36,32 @@ const readCaptureState = async (db, schema, models) => {
 };
 const plan = async (db, models, options) => {
 	const schema = changesSchema(options);
-	const withEvents = models.filter((model) => (model.events ?? []).length > 0);
 	return {
 		schema,
-		plan: capturePlan(schema, models, await readCaptureState(db, schema, withEvents))
+		plan: capturePlan(schema, models, await readCaptureState(db, schema, models.filter(isCaptured)))
 	};
 };
 /**
-* The SQL that brings the database to the capture the resources' events need: the schema with the outbox and
-* `capture()`, and a trigger pair per resource with events, recreated when its fields changed; triggers of resources
-* without events any more are dropped. `undefined` when the database is current. Tables are never dropped.
+* The SQL that brings the database to the capture the resources' events and history need: the schema with the outbox
+* and `capture()`, the history table, and a trigger pair per resource with either, recreated when its fields changed;
+* triggers of resources without either any more are dropped. `undefined` when the database is current. Tables are
+* never dropped.
 */
 const changesMigration = async (db, models, options) => {
 	const { schema, plan: found } = await plan(db, models, options);
 	return planSql(schema, found);
 };
 /**
-* Refuses to go on while a resource's events would not be captured as declared: a missing or out-of-date schema, or
-* trigger. The server never changes the schema itself: the project's migrations do, before the new version serves.
+* Refuses to go on while a resource's events or history would not be captured as declared: a missing or out-of-date
+* schema, history table or trigger. The server never changes the schema itself: the project's migrations do, before the
+* new version serves.
 */
 const checkChanges = async (db, models, options) => {
-	if (!models.some((model) => model.events)) return;
+	if (!models.some(isCaptured)) return;
 	const { plan: found } = await plan(db, models, options);
 	const missing = uncaptured(found, models);
 	if (missing.length === 0) return;
-	throw new Error(`The changes of ${missing.join(", ")} are not captured as their events need: their triggers or the changes schema are missing or out of date. Write the change as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
+	throw new Error(`The changes of ${missing.join(", ")} are not captured as their events or history need: their triggers, the history table or the changes schema are missing or out of date. Write the change as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
 };
 //#endregion
 export { changesMigration, checkChanges, migrationCommand };

package/dist/changes/capture-sql.d.ts

@@ -0,0 +1,5 @@
+import { ResourceModel } from "@protobase/schema";
+//#region src/changes/capture-sql.d.ts
+/** Whether the triggers capture a resource's changes: for its events, its history, or both. */
+export declare const isCaptured: (model: ResourceModel) => boolean;
+//#endregion

package/dist/changes/capture-sql.js

@@ -16,9 +16,12 @@ const identifier = (name) => {
 };
 /** The table as SQL names it, qualified when the resource names a schema. */
 const tableSql = (model) => qualified(model.table);
+/** Whether the triggers capture a resource's changes: for its events, its history, or both. */
+const isCaptured = (model) => (model.events ?? []).length > 0 || model.history === true;
 /**
 * The outbox: one row per changed row, written in the writer's transaction. `transaction` is the writer's transaction
-* id; `dispatch_after` holds back a change that the process which wrote it is delivering itself.
+* id; `database_role` the role that wrote; `dispatch_after` holds back a change that the process which wrote it is
+* delivering itself. The `alter` adds the role to an outbox of an earlier version.
 */
 const outboxSql = (schema) => `create table if not exists ${quoteIdent(schema)}."outbox" (
   "id" bigint generated always as identity primary key,
@@ -29,16 +32,19 @@ const outboxSql = (schema) => `create table if not exists ${quoteIdent(schema)}.
   "new" jsonb,
   "changed" text[],
   "actor" jsonb,
+  "database_role" text,
   "dispatch_after" timestamptz not null default now(),
   "created_at" timestamptz not null default now()
-)`;
+);
+alter table ${quoteIdent(schema)}."outbox" add column if not exists "database_role" text`;
 /** The job that turns captured changes into events and deliveries: one per writing transaction, run one at a time. */
 const dispatchJobName = "changes.dispatch";
 /** Every dispatch job's group in its ordered queue, so only one runs at a time, across processes too. */
 const dispatchGroup = "changes";
 /**
 * The body of `capture()`: its arguments are the resource, the columns to keep and the sensitive columns, whose names
-* it lists when they change but whose values it never keeps. It skips a transaction that set `<schema>.capture` to
+* it lists when they change but whose values it never keeps. It keeps the writing role: the one `set role` chose, else
+* the session's, since the function itself runs as its owner. It skips a transaction that set `<schema>.capture` to
 * `off`, and an update that changed none of those columns. The first row a transaction captures enqueues a dispatch
 * job in the same transaction; `<schema>.dispatch` remembers that for the rest of it, and a rolled-back savepoint
 * forgets it with the job.
@@ -68,7 +74,7 @@ begin
       return null;
     end if;
   end if;
-  insert into ${quoteIdent(schema)}."outbox" ("transaction", "resource", "op", "old", "new", "changed", "actor")
+  insert into ${quoteIdent(schema)}."outbox" ("transaction", "resource", "op", "old", "new", "changed", "actor", "database_role")
   values (
     pg_current_xact_id()::text::bigint,
     TG_ARGV[0],
@@ -76,7 +82,8 @@ begin
     (select jsonb_object_agg(o.key, o.value) from jsonb_each(old_row) as o where o.key = any(kept)),
     (select jsonb_object_agg(n.key, n.value) from jsonb_each(new_row) as n where n.key = any(kept)),
     changed,
-    nullif(current_setting('${schema}.actor', true), '')::jsonb
+    nullif(current_setting('${schema}.actor', true), '')::jsonb,
+    coalesce(nullif(current_setting('role'), 'none'), session_user)
   );
   if current_setting('${schema}.dispatch', true) is distinct from 'queued' then
     perform ${jobsSchema}.enqueue('${dispatchJobName}', null, null, null, '${dispatchGroup}');
@@ -90,7 +97,7 @@ end
 * service writing as its own role keeps working once a resource has events.
 */
 const captureFunctionSql = (schema) => `create or replace function ${quoteIdent(schema)}."capture"() returns trigger language plpgsql security definer set search_path = pg_catalog, pg_temp as $capture$${captureBody(schema)}$capture$`;
-/** The two triggers of a resource with events: inserts and deletes, and updates that change the row. */
+/** The two triggers of a resource whose changes are captured: inserts and deletes, and updates that change the row. */
 const resourceTriggers = (model) => {
 	const fields = Object.values(model.fields);
 	const args = [
@@ -116,4 +123,4 @@ const createTriggerSql = (schema, trigger, table) => {
 	return `create trigger ${quoteIdent(trigger.name)} ${timing} on ${table} for each row${when} execute function ${quoteIdent(schema)}."capture"(${args})`;
 };
 //#endregion
-export { captureBody, captureFunctionSql, createTriggerSql, dispatchGroup, dispatchJobName, dropTriggerSql, outboxSql, quoteIdent, resourceTriggers, tableSql };
+export { captureBody, captureFunctionSql, createTriggerSql, dispatchGroup, dispatchJobName, dropTriggerSql, isCaptured, outboxSql, quoteIdent, resourceTriggers, tableSql };

package/dist/changes/coalesce.d.ts

@@ -14,6 +14,8 @@ export type CapturedRow = {
   /** The columns an update changed, sensitive ones included; `null` for inserts and deletes. */
   changed: string[] | null;
   actor: EventActor | null;
+  /** The database role that wrote; `null` for a row captured before Protobase kept it. */
+  databaseRole: string | null;
   /** When the writing transaction started, ISO 8601. */
   at: string;
 };
@@ -28,6 +30,8 @@ export type CoalescedChange = {
   after: Row | null;
   changed: string[];
   actor: EventActor | null;
+  /** The database role of its last change. */
+  databaseRole: string | null;
   /** The id of its last outbox row. */
   sequence: string;
   /** When its last change's transaction started. */

package/dist/changes/coalesce.js

@@ -17,6 +17,7 @@ const merged = ({ first, last, actor, listed }) => {
 		transaction: first.transaction,
 		resource: first.resource,
 		actor,
+		databaseRole: last.databaseRole,
 		sequence: last.id,
 		at: last.at
 	};

package/dist/changes/outbox.js

@@ -30,7 +30,7 @@ const parseColumns = (text, model) => {
 const readOutbox = async (db, schema, models, limit) => {
 	const byName = new Map(models.map((model) => [model.name, model]));
 	const { rows } = await sql`select "id"::text as id, "transaction"::text as transaction, "resource", "op", "old"::text as old, "new"::text as new, "changed",
-      "actor"::text as actor, to_char("created_at" at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') as at
+      "actor"::text as actor, "database_role" as "databaseRole", to_char("created_at" at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') as at
     from ${sql.raw(`${quoteIdent(schema)}."outbox"`)} where "dispatch_after" <= now() order by "id" limit ${limit}`.execute(db);
 	return rows.map((row) => {
 		const model = byName.get(row.resource);

package/dist/changes/resource-change.d.ts

@@ -15,6 +15,8 @@ export type ResourceChange = {
   changed: string[];
   actor: EventActor | null;
   source: 'api' | 'database';
+  /** The database role that wrote; `null` when unknown. */
+  databaseRole: string | null;
   tenant?: TenantValue;
   transaction: string;
   /** Grows with every change of a record, so receivers can drop stale events. */

package/dist/changes/resource-change.js

@@ -34,6 +34,7 @@ const resourceChange = (model, change) => {
 		changed: fieldsOf(model, change.changed),
 		actor: change.actor,
 		source: change.actor ? "api" : "database",
+		databaseRole: change.databaseRole,
 		...tenant != null && { tenant },
 		transaction: change.transaction,
 		sequence: change.sequence,

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,8 @@ 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}`) : [];
+		const history = model.history ? [] : view.layout.flatMap((item) => item.kind === "history" ? [`history "${item.title}" needs .history() on resource "${view.resource}"`] : []);
 		return [
 			...sensitiveErrors(view, model),
 			...unknownFieldErrors(view, model),
@@ -145,7 +148,9 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 			...listOf,
 			...searches,
 			...maps,
+			...history,
 			...boards,
+			...chart,
 			...linkErrors(view, model, models, pageNames),
 			...inputErrors(view, models),
 			...createErrors(view, pageNames)

package/dist/create-admin.d.ts

@@ -1,5 +1,6 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
 import { EventsOptions } from "./changes/events-options.js";
+import { HistoryOptions } from "./history/options.js";
 import { JobDefinition } from "./jobs/job-types.js";
 import { Admin, Authenticator, PageSource, ViewSource } from "./types.js";
 import { WebhooksOptions } from "./webhooks/table/options.js";
@@ -30,7 +31,9 @@ export type CreateAdminInput = {
   files?: FilesOptions;
   /** Where the changes that resources' events are raised from are captured (see `EventsOptions`). */
   events?: EventsOptions;
-  /** The app's jobs (see `defineJob`): with any, or a resource with events, admins get the failed jobs page (`failed_jobs`). */
+  /** How long the history of resources with `.history()` is kept (see `HistoryOptions`). */
+  history?: HistoryOptions;
+  /** The app's jobs (see `defineJob`): with any, or a resource with events or history, admins get the failed jobs page (`failed_jobs`). */
   jobs?: JobDefinition[];
   /** Where the resources' events are delivered (`subscription(...)` exports of the config module). */
   subscriptions?: SubscriptionDefinition[];
@@ -51,5 +54,5 @@ export type CreateAdminInput = {
   options?: AdminOptions;
 };
 /** The admin REST API as a Hono app. It uses only Web APIs, so it runs on Node, Workers and anywhere else Hono does. */
-export declare const createAdmin: ({ resources: appResources, views: appViews, pages, userMenu, bottomBars, db, authenticate, auth, functions, files: filesOptions, events, jobs, subscriptions, webhooks: webhooksOptions, bundlePlugins, fieldTypes, options }: CreateAdminInput) => Admin;
+export declare const createAdmin: ({ resources: appResources, views: appViews, pages, userMenu, bottomBars, db, authenticate, auth, functions, files: filesOptions, events, history: historyOptions, jobs, subscriptions, webhooks: webhooksOptions, bundlePlugins, fieldTypes, options }: CreateAdminInput) => Admin;
 //#endregion