@protobase/server 0.8.0 → 0.8.2

package/dist/batch/run-batch.js

@@ -2,6 +2,7 @@ import { HttpProblem, badRequest, notFound } from "../problem.js";
 import { problemOf } from "../error-handler.js";
 import { requestAccess } from "../request-access.js";
 import { writeTransaction } from "../transactions.js";
+import { actorSettings } from "../changes/actor.js";
 import { keyOf } from "../write-shared.js";
 import { writeIn } from "../write-pipeline.js";
 import { resolveData, resolveKey } from "./refs.js";
@@ -99,7 +100,7 @@ const runBatch = async (deps, session, operations) => {
 			throw atOperation(error, index, operation);
 		}
 		return results;
-	});
+	}, actorSettings(deps, session));
 };
 //#endregion
 export { runBatch };

package/dist/changes/actor.js

@@ -0,0 +1,12 @@
+//#region src/changes/actor.ts
+/** The setting a write transaction sets so the change capture records who wrote, when a resource has events. */
+const actorSettings = (deps, session) => {
+	if (!deps.actorSetting) return {};
+	const actor = {
+		id: session.user.id,
+		roles: session.user.roles
+	};
+	return { [deps.actorSetting]: JSON.stringify(actor) };
+};
+//#endregion
+export { actorSettings };

package/dist/changes/capture-plan.js

@@ -0,0 +1,62 @@
+import { captureBody, captureFunctionSql, createTriggerSql, dropTriggerSql, outboxSql, quoteIdent, resourceTriggers, tableSql } from "./capture-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) => {
+	const table = state.tables[model.name];
+	if (!table) throw new Error(`The table ${tableSql(model)} of resource "${model.name}" does not exist`);
+	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.
+*/
+const capturePlan = (schema, models, state) => {
+	const withEvents = models.filter((model) => (model.events ?? []).length > 0);
+	const capture = state.capture;
+	const current = capture !== void 0 && capture.definer && capture.source === captureBody(schema);
+	const wanted = withEvents.flatMap((model) => resourceTriggers(model).map((trigger) => ({
+		model,
+		trigger,
+		table: tableOf(state, model)
+	})));
+	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`);
+		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`);
+		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),
+		create: create.map(({ model, trigger }) => ({
+			model,
+			trigger
+		})),
+		drop: drop.map(({ name, tableSql }) => ({
+			name,
+			tableSql
+		}))
+	};
+};
+/** The plan as SQL statements, each made to apply over what exists already; `undefined` when there is nothing to do. */
+const planSql = (schema, plan) => {
+	const statements = [
+		...plan.setup ? [
+			`create schema if not exists ${quoteIdent(schema)}`,
+			outboxSql(schema),
+			captureFunctionSql(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))];
+//#endregion
+export { capturePlan, planSql, uncaptured };

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

@@ -0,0 +1,18 @@
+import { EventsOptions } from "./events-options.js";
+import { ResourceModel } from "@protobase/schema";
+import { Db } from "@protobase/query";
+//#region src/changes/capture-schema.d.ts
+/** 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.
+ */
+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.
+ */
+export declare const checkChanges: (db: Db, models: readonly ResourceModel[], options?: EventsOptions) => Promise<void>;
+//#endregion

package/dist/changes/capture-schema.js

@@ -0,0 +1,65 @@
+import { changesSchema } from "./events-options.js";
+import { quoteIdent, tableSql } from "./capture-sql.js";
+import { capturePlan, planSql, uncaptured } from "./capture-plan.js";
+import { sql } from "kysely";
+//#region src/changes/capture-schema.ts
+/** The command that writes what the config needs as a migration file of the project. */
+const migrationCommand = "protobase migration";
+const triggerArgs = (hex) => {
+	const bytes = new Uint8Array((hex.match(/../g) ?? []).map((pair) => parseInt(pair, 16)));
+	return new TextDecoder().decode(bytes).split("\0").slice(0, -1);
+};
+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 [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) {
+		const [found] = await rowsOf(db, sql`select to_regclass(${tableSql(model)})::oid::text as oid`);
+		tables[model.name] = found?.oid ?? null;
+	}
+	const oids = Object.values(tables).filter((oid) => oid !== null);
+	const triggers = await rowsOf(db, sql`select t.tgrelid::text as "table", format('%I.%I', ns.nspname, c.relname) as "tableSql", t.tgname as name,
+      t.tgfoid::text as "function", t.tgtype::int as type, encode(t.tgargs, 'hex') as args
+      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,
+		...capture && { capture },
+		triggers: triggers.map((trigger) => ({
+			...trigger,
+			args: triggerArgs(trigger.args)
+		})),
+		tables
+	};
+};
+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))
+	};
+};
+/**
+* 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.
+*/
+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.
+*/
+const checkChanges = async (db, models, options) => {
+	if (!models.some((model) => model.events)) 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.`);
+};
+//#endregion
+export { changesMigration, checkChanges, migrationCommand };

package/dist/changes/capture-sql.js

@@ -0,0 +1,108 @@
+//#region src/changes/capture-sql.ts
+const quoteIdent = (name) => `"${name.replaceAll("\"", "\"\"")}"`;
+const quoteLiteral = (text) => `'${text.replaceAll("'", "''")}'`;
+const qualified = ({ schema, name }) => schema ? `${quoteIdent(schema)}.${quoteIdent(name)}` : quoteIdent(name);
+/** A Postgres array literal of text, every element quoted, so the same columns always give the same text. */
+const textArray = (items) => `{${items.map((item) => `"${item.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`).join(",")}}`;
+const identifier = (name) => {
+	const encoder = new TextEncoder();
+	let kept = "";
+	for (const char of name) {
+		if (encoder.encode(kept + char).length > 63) break;
+		kept += char;
+	}
+	return kept;
+};
+/** The table as SQL names it, qualified when the resource names a schema. */
+const tableSql = (model) => qualified(model.table);
+/**
+* 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.
+*/
+const outboxSql = (schema) => `create table if not exists ${quoteIdent(schema)}."outbox" (
+  "id" bigint generated always as identity primary key,
+  "transaction" bigint not null,
+  "resource" text not null,
+  "op" text not null,
+  "old" jsonb,
+  "new" jsonb,
+  "changed" text[],
+  "actor" jsonb,
+  "dispatch_after" timestamptz not null default now(),
+  "created_at" timestamptz not null default now()
+)`;
+/**
+* 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
+* `off`, and an update that changed none of those columns.
+*/
+const captureBody = (schema) => `
+declare
+  kept text[] := TG_ARGV[1]::text[];
+  hidden text[] := TG_ARGV[2]::text[];
+  old_row jsonb;
+  new_row jsonb;
+  changed text[];
+begin
+  if current_setting('${schema}.capture', true) = 'off' then
+    return null;
+  end if;
+  if TG_OP <> 'INSERT' then
+    old_row := to_jsonb(OLD);
+  end if;
+  if TG_OP <> 'DELETE' then
+    new_row := to_jsonb(NEW);
+  end if;
+  if TG_OP = 'UPDATE' then
+    select array_agg(c.name order by c.position) into changed
+    from unnest(kept || hidden) with ordinality as c(name, position)
+    where old_row -> c.name is distinct from new_row -> c.name;
+    if changed is null then
+      return null;
+    end if;
+  end if;
+  insert into ${quoteIdent(schema)}."outbox" ("transaction", "resource", "op", "old", "new", "changed", "actor")
+  values (
+    pg_current_xact_id()::text::bigint,
+    TG_ARGV[0],
+    TG_OP,
+    (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
+  );
+  return null;
+end
+`;
+/**
+* `capture()` runs as its owner, with a fixed search path: a writer needs no rights on the schema, so another
+* 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. */
+const resourceTriggers = (model) => {
+	const fields = Object.values(model.fields);
+	const args = [
+		model.name,
+		textArray(fields.filter((field) => !field.sensitive).map((field) => field.column)),
+		textArray(fields.filter((field) => field.sensitive).map((field) => field.column))
+	];
+	return [{
+		name: identifier(`${model.table.name}_changes`),
+		type: 13,
+		args
+	}, {
+		name: identifier(`${model.table.name}_changes_update`),
+		type: 17,
+		args
+	}];
+};
+const dropTriggerSql = (name, table) => `drop trigger if exists ${quoteIdent(name)} on ${table}`;
+const createTriggerSql = (schema, trigger, table) => {
+	const timing = trigger.type & 16 ? "after update" : "after insert or delete";
+	const when = trigger.type & 16 ? " when (old.* is distinct from new.*)" : "";
+	const args = trigger.args.map(quoteLiteral).join(", ");
+	return `create trigger ${quoteIdent(trigger.name)} ${timing} on ${table} for each row${when} execute function ${quoteIdent(schema)}."capture"(${args})`;
+};
+//#endregion
+export { captureBody, captureFunctionSql, createTriggerSql, dropTriggerSql, outboxSql, quoteIdent, resourceTriggers, tableSql };

package/dist/changes/coalesce.d.ts

@@ -0,0 +1,38 @@
+import { Row } from "../types.js";
+import { EventActor } from "@protobase/schema";
+//#region src/changes/coalesce.d.ts
+/** A row of the outbox: one row's insert, update or delete, its columns as `changes.capture()` kept them. */
+export type CapturedRow = {
+  /** The outbox id: commit order for the changes of one record. */
+  id: string;
+  transaction: string;
+  /** The resource whose table changed, which its trigger names. */
+  resource: string;
+  op: 'INSERT' | 'UPDATE' | 'DELETE';
+  old: Row | null;
+  new: Row | null;
+  /** The columns an update changed, sensitive ones included; `null` for inserts and deletes. */
+  changed: string[] | null;
+  actor: EventActor | null;
+};
+/**
+ * One record's changes in one transaction, as one: its columns at the start (`before`, none when it was inserted) and
+ * at commit (`after`, none when it was deleted), and for an update the columns that differ, sensitive ones included.
+ */
+export type CoalescedChange = {
+  transaction: string;
+  resource: string;
+  before: Row | null;
+  after: Row | null;
+  changed: string[];
+  actor: EventActor | null;
+  /** The id of its last outbox row. */
+  sequence: string;
+};
+/**
+ * The outbox rows of one or more transactions, in id order, as one change per (transaction, record). An insert then a
+ * delete is nothing, and so is an update that ends where it started; a delete then an insert of the same key is an
+ * update. `keyColumns` names a resource's primary key columns, which identify its records.
+ */
+export declare const coalesce: (rows: readonly CapturedRow[], keyColumns: (resource: string) => readonly string[]) => CoalescedChange[];
+//#endregion

package/dist/changes/coalesce.js

@@ -0,0 +1,69 @@
+//#region src/changes/coalesce.ts
+const sameValue = (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b);
+const recordKey = (row, columns, keyColumns) => JSON.stringify([
+	row.transaction,
+	row.resource,
+	...keyColumns.map((column) => columns?.[column] ?? null)
+]);
+const changedColumns = (before, after, listed) => [.../* @__PURE__ */ new Set([
+	...listed,
+	...Object.keys(before),
+	...Object.keys(after)
+])].filter((column) => {
+	return !(column in before || column in after) || !sameValue(before[column], after[column]);
+});
+const merged = ({ first, last, actor, listed }) => {
+	const base = {
+		transaction: first.transaction,
+		resource: first.resource,
+		actor,
+		sequence: last.id
+	};
+	const before = first.op === "INSERT" ? null : first.old;
+	const after = last.op === "DELETE" ? null : last.new;
+	if (!before && !after) return [];
+	if (!before || !after) return [{
+		...base,
+		before,
+		after,
+		changed: []
+	}];
+	const changed = changedColumns(before, after, listed);
+	return changed.length > 0 ? [{
+		...base,
+		before,
+		after,
+		changed
+	}] : [];
+};
+/**
+* The outbox rows of one or more transactions, in id order, as one change per (transaction, record). An insert then a
+* delete is nothing, and so is an update that ends where it started; a delete then an insert of the same key is an
+* update. `keyColumns` names a resource's primary key columns, which identify its records.
+*/
+const coalesce = (rows, keyColumns) => {
+	const current = /* @__PURE__ */ new Map();
+	const groups = [];
+	for (const row of rows) {
+		const columns = keyColumns(row.resource);
+		const key = recordKey(row, row.op === "INSERT" ? row.new : row.old, columns);
+		let group = current.get(key);
+		if (!group) {
+			group = {
+				first: row,
+				last: row,
+				actor: row.actor,
+				listed: /* @__PURE__ */ new Set()
+			};
+			groups.push(group);
+		}
+		group.last = row;
+		group.actor = row.actor ?? group.actor;
+		for (const column of row.changed ?? []) group.listed.add(column);
+		current.delete(key);
+		current.set(row.op === "DELETE" ? key : recordKey(row, row.new, columns), group);
+	}
+	return groups.flatMap(merged);
+};
+//#endregion
+export { coalesce };

package/dist/changes/events-options.d.ts

@@ -0,0 +1,10 @@
+//#region src/changes/events-options.d.ts
+/** Where captured changes live in the app's database (`events` in `protobase.config.ts`). */
+export type EventsOptions = {
+  /**
+   * The schema holding the outbox and the capture function, and the prefix of their transaction settings
+   * (`changes.actor`, `changes.capture`); default `changes`. Rename it when the database already has a schema by that name.
+   */
+  schema?: string;
+};
+//#endregion

package/dist/changes/events-options.js

@@ -0,0 +1,10 @@
+//#region src/changes/events-options.ts
+const schemaPattern = /^[a-z_][a-z0-9_]*$/;
+/** The schema of the options, checked: it also prefixes setting names, which take plain lowercase names only. */
+const changesSchema = (options = {}) => {
+	const schema = options.schema ?? "changes";
+	if (!schemaPattern.test(schema)) throw new Error(`Invalid events schema "${schema}": use lowercase letters, digits and "_"`);
+	return schema;
+};
+//#endregion
+export { changesSchema };

package/dist/changes/match-events.d.ts

@@ -0,0 +1,9 @@
+import { ResourceChange } from "./resource-change.js";
+import { EventMatch, ResourceModel } from "@protobase/schema";
+//#region src/changes/match-events.d.ts
+/**
+ * The names of the resource's events a change raises, in declaration order. The filters are checked once, here; `matches`
+ * are the events' code predicates by event name (`eventMatches()` of the resource).
+ */
+export declare const eventMatcher: (model: ResourceModel, matches?: Record<string, EventMatch<any>>) => (change: ResourceChange) => string[];
+//#endregion

package/dist/changes/match-events.js

@@ -0,0 +1,55 @@
+import { checkEventFilter, evaluateFilter } from "@protobase/schema";
+//#region src/changes/match-events.ts
+const filterOf = (model, source) => {
+	const { filter, problem } = checkEventFilter(model, source);
+	if (!filter) throw new Error(`Resource "${model.name}": event filter "${source}" ${problem}`);
+	return filter;
+};
+const holds = (filter, record) => record !== void 0 && evaluateFilter(filter, record) === true;
+const contextOf = (change) => ({
+	operation: change.operation,
+	...change.before && { before: change.before },
+	...change.after && { after: change.after },
+	changed: change.changed,
+	actor: change.actor,
+	source: change.source,
+	...change.tenant !== void 0 && { tenant: change.tenant },
+	transaction: change.transaction
+});
+const eventTest = (model, event, match) => {
+	const tests = [(change) => event.operations.includes(change.operation)];
+	if (event.when !== void 0) {
+		const when = filterOf(model, event.when);
+		tests.push((change) => holds(when, change.after));
+	}
+	if (event.from !== void 0) {
+		const from = filterOf(model, event.from);
+		tests.push((change) => holds(from, change.before));
+	}
+	if (event.becomes !== void 0) {
+		const condition = filterOf(model, event.becomes);
+		tests.push((change) => holds(condition, change.after) && !holds(condition, change.before));
+	}
+	if (event.changed) {
+		const fields = event.changed;
+		tests.push((change) => change.changed.some((name) => fields.includes(name)));
+	}
+	if (event.match) {
+		if (!match) throw new Error(`Resource "${model.name}": event "${event.name}" has no match function`);
+		tests.push((change) => match(contextOf(change)));
+	}
+	return (change) => tests.every((test) => test(change));
+};
+/**
+* The names of the resource's events a change raises, in declaration order. The filters are checked once, here; `matches`
+* are the events' code predicates by event name (`eventMatches()` of the resource).
+*/
+const eventMatcher = (model, matches = {}) => {
+	const tests = (model.events ?? []).map((event) => ({
+		name: event.name,
+		test: eventTest(model, event, matches[event.name])
+	}));
+	return (change) => tests.filter(({ test }) => test(change)).map(({ name }) => name);
+};
+//#endregion
+export { eventMatcher };

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

@@ -0,0 +1,27 @@
+import { Row, TenantValue } from "../types.js";
+import { CoalescedChange } from "./coalesce.js";
+import { EventActor, EventOperation, ResourceModel } from "@protobase/schema";
+//#region src/changes/resource-change.d.ts
+/** One record's change in one transaction, by field name: what events are matched against and payloads are built from. */
+export type ResourceChange = {
+  resource: string;
+  /** The record's key as its URL has it. */
+  key: string;
+  operation: EventOperation;
+  /** The record before and after the change, without sensitive fields. */
+  before?: Row;
+  after?: Row;
+  /** The fields an update changed, sensitive ones included. */
+  changed: string[];
+  actor: EventActor | null;
+  source: 'api' | 'database';
+  tenant?: TenantValue;
+  transaction: string;
+  /** Grows with every change of a record, so receivers can drop stale events. */
+  sequence: string;
+};
+/** A captured row by field name, fields without a captured column left out. */
+export declare const recordOf: (model: ResourceModel, columns: Row) => Row;
+/** A coalesced change of the resource's table, by field name, with deletes and undeletes told apart from updates. */
+export declare const resourceChange: (model: ResourceModel, change: CoalescedChange) => ResourceChange;
+//#endregion

package/dist/changes/resource-change.js

@@ -0,0 +1,43 @@
+import { encodeKey } from "@protobase/schema";
+//#region src/changes/resource-change.ts
+const fieldValue = (type, value) => {
+	if (value === null || value === void 0) return value;
+	if (type === "bigint" || type === "decimal") return String(value);
+	if (type === "integer") return Number(value);
+	return value;
+};
+/** A captured row by field name, fields without a captured column left out. */
+const recordOf = (model, columns) => Object.fromEntries(Object.values(model.fields).filter((field) => Object.hasOwn(columns, field.column)).map((field) => [field.name, fieldValue(field.type, columns[field.column])]));
+const operationOf = (model, before, after) => {
+	if (!before) return "create";
+	if (!after) return "delete";
+	if (!model.softDelete) return "update";
+	const wasDeleted = before[model.softDelete] != null;
+	const isDeleted = after[model.softDelete] != null;
+	if (!wasDeleted && isDeleted) return "delete";
+	if (wasDeleted && !isDeleted) return "undelete";
+	return "update";
+};
+const fieldsOf = (model, columns) => Object.values(model.fields).filter((field) => columns.includes(field.column)).map((field) => field.name);
+/** A coalesced change of the resource's table, by field name, with deletes and undeletes told apart from updates. */
+const resourceChange = (model, change) => {
+	const before = change.before ? recordOf(model, change.before) : void 0;
+	const after = change.after ? recordOf(model, change.after) : void 0;
+	const record = after ?? before;
+	const tenant = model.tenant === void 0 ? void 0 : record[model.tenant];
+	return {
+		resource: model.name,
+		key: encodeKey(model.primaryKey.map((name) => record[name])),
+		operation: operationOf(model, before, after),
+		...before && { before },
+		...after && { after },
+		changed: fieldsOf(model, change.changed),
+		actor: change.actor,
+		source: change.actor ? "api" : "database",
+		...tenant != null && { tenant },
+		transaction: change.transaction,
+		sequence: change.sequence
+	};
+};
+//#endregion
+export { recordOf, resourceChange };

package/dist/create-admin.d.ts

@@ -1,9 +1,11 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
+import { EventsOptions } from "./changes/events-options.js";
 import { FilesOptions } from "./files/options.js";
 import { AdminEnv, Authenticator, PageSource, ViewSource } from "./types.js";
 import { ResourceSource } from "./resource-source.js";
 import { FunctionSource } from "./functions/define-function.js";
 import { AdminOptions } from "./admin-options.js";
+import { JobDefinition } from "./jobs/job-types.js";
 import { Hono } from "hono";
 import { UserMenuSource } from "@protobase/schema";
 import { Db } from "@protobase/query";
@@ -23,8 +25,12 @@ export type CreateAdminInput = {
   functions?: Record<string, FunctionSource>;
   /** Where file fields keep their bytes (see `FilesOptions`). */
   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, admins get the failed jobs page (`failedJobs`). */
+  jobs?: JobDefinition[];
   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, views, pages, userMenu, db, authenticate, auth, functions, files: filesOptions, options }: CreateAdminInput) => Hono<AdminEnv, import("hono/types").BlankSchema, "/">;
+export declare const createAdmin: ({ resources: appResources, views: appViews, pages, userMenu, db, authenticate, auth, functions, files: filesOptions, events, jobs, options }: CreateAdminInput) => Hono<AdminEnv, import("hono/types").BlankSchema, "/">;
 //#endregion

package/dist/create-admin.js

@@ -6,6 +6,7 @@ import { consoleAuditQueue } from "./audit/console-queue.js";
 import { authBasePath } from "./better-auth/create-auth.js";
 import { organizationRoutes } from "./better-auth/organizations/admin-routes.js";
 import { statusRoute } from "./better-auth/status-route.js";
+import { changesSchema } from "./changes/events-options.js";
 import { checkShell } from "./check-shell.js";
 import { checkViews } from "./check-views.js";
 import { createFilesRuntime } from "./files/runtime.js";
@@ -22,12 +23,15 @@ import { docsRoutes } from "./routes/docs.js";
 import { metaRoutes } from "./routes/meta.js";
 import { recordRoutes } from "./routes/record.js";
 import { createScanGuard } from "./scan-guard.js";
+import { failedJobs, failedJobsView } from "./jobs/failed-jobs.js";
 import { Hono } from "hono";
 import { checkPages } from "@protobase/layout";
 //#region src/create-admin.ts
 /** The admin REST API as a Hono app. It uses only Web APIs, so it runs on Node, Workers and anywhere else Hono does. */
-const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenticate, auth, functions = {}, files: filesOptions, options = {} }) => {
+const createAdmin = ({ resources: appResources, views: appViews = [], pages = [], userMenu, db, authenticate, auth, functions = {}, files: filesOptions, events, jobs = [], options = {} }) => {
 	const basePath = options.basePath ?? "/api/v1";
+	const resources = jobs.length > 0 ? [...appResources, failedJobs] : appResources;
+	const views = jobs.length > 0 ? [...appViews, failedJobsView] : appViews;
 	const registry = buildRegistry(resources);
 	const apiFunctions = Object.fromEntries(Object.entries(functions).map(([name, source]) => [name, toApiFunction(name, source)]));
 	const viewModels = views.map((view) => view.toModel());
@@ -67,7 +71,8 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 		rowPermissions: (resource) => typeof options.rowPermissions === "object" ? !options.rowPermissions.except.includes(resource) : options.rowPermissions !== false,
 		...assistant && { assistant: assistant.kind === "external" ? assistant.url : `${systemPath}/assistant` },
 		...runtime && { runtime },
-		...files && { files }
+		...files && { files },
+		...registry.entries.some((entry) => entry.model.events) && { actorSetting: `${changesSchema(events)}.actor` }
 	};
 	const meta = createMeta(deps);
 	const onError = createErrorHandler(options.onUnhandledError);

package/dist/functions/require-env.d.ts

@@ -3,5 +3,5 @@
  * An environment variable the function cannot work without, such as an API key: `protobase dev` reads it from `.env`,
  * `protobase serve` from its environment. A missing one is an error, so the call is a 500 the app reports.
  */
-export declare const requireEnv: (name: string) => any;
+export declare const requireEnv: (name: string) => string;
 //#endregion