@protobase/server 0.8.0 → 0.8.1

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,4 +1,5 @@
 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";
@@ -23,8 +24,10 @@ 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;
   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, views, pages, userMenu, db, authenticate, auth, functions, files: filesOptions, events, 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";
@@ -26,7 +27,7 @@ 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, views = [], pages = [], userMenu, db, authenticate, auth, functions = {}, files: filesOptions, events, options = {} }) => {
 	const basePath = options.basePath ?? "/api/v1";
 	const registry = buildRegistry(resources);
 	const apiFunctions = Object.fromEntries(Object.entries(functions).map(([name, source]) => [name, toApiFunction(name, source)]));
@@ -67,7 +68,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/index.d.ts

@@ -6,6 +6,7 @@ import { OrganizationRole, StoredMember, StoredOrganization } from "./better-aut
 import { OrganizationsOptions } from "./better-auth/organizations/options.js";
 import { PlatformSignIn, readPlatformSignIn } from "./better-auth/platform-sign-in.js";
 import { AdminAuth, CreateAuthOptions, UserCreatedHook, createAuth, normalizeRoles } from "./better-auth/create-auth.js";
+import { EventsOptions } from "./changes/events-options.js";
 import { FileProvider, FileStore, StoredObject } from "./files/store.js";
 import { FilesOptions } from "./files/options.js";
 import { Admin, AuditEvent, AuditQueue, Authenticator, PipelineHook, ScanGuardMode, Session, SessionOrganization, TenantValue, User, ViewSource, WriteEvent, WriteOperation } from "./types.js";
@@ -33,6 +34,10 @@ import { parseRoles } from "./better-auth/parse-roles.js";
 import { LinkedAccount, NewUser, StoredUser, createUser, deleteUser, hasUsers, listUsers, roleChoices, setUserBanned, setUserRole } from "./better-auth/users.js";
 import { IssueTokenOptions, issueToken, maxTokenTtlSeconds } from "./better-auth/tokens.js";
 import { authSchemaMigration, checkAuthSchema } from "./better-auth/auth-schema.js";
+import { changesMigration, checkChanges, migrationCommand } from "./changes/capture-schema.js";
+import { CapturedRow, CoalescedChange, coalesce } from "./changes/coalesce.js";
+import { ResourceChange, recordOf, resourceChange } from "./changes/resource-change.js";
+import { eventMatcher } from "./changes/match-events.js";
 import { MemberInput, NewOrganization, addAppRoleToOwners, addMember, createOrganization, listOrganizations, removeMember, setMemberRoles } from "./better-auth/organizations/host.js";
 import { AssistantBackend, assistantProtocolRoutes } from "./assistant/protocol-routes.js";
 import { fileConversationStore } from "./assistant/file-conversation-store.js";
@@ -49,4 +54,4 @@ import { LocalFilesOptions, localFileStore, localFiles } from "./files/local-fil
 import { FileCleanupInput, createFileCleanup } from "./files/file-cleanup.js";
 import { FileObject } from "./files/present.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.js";
-export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CreateAdminInput, type CreateAuthOptions, type FileCleanupInput, type FileObject, type FileProvider, type FileStore, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, HttpProblem, type IssueTokenOptions, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MemberInput, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type ResourceSource, type RoleDefinition, type RolesInput, type RuntimeOptions, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type SignInPolicy, type SignInRule, type SignatureOptions, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, checkAuthSchema, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineTool, deleteUser, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, issueToken, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, normalizeRoles, notFound, parseRoles, processor, readJson, readOnlyQueryTool, readOperatorSettings, readPlatformSignIn, readWriteQueryTool, removeMember, requestApproval, requireEnv, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, storageCleanupSchedule, streamChatCompletion, unauthorized, verifySignature, verifyStandardWebhook, widget, withCacheBreakpoints };
+export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CapturedRow, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CreateAdminInput, type CreateAuthOptions, type EventsOptions, type FileCleanupInput, type FileObject, type FileProvider, type FileStore, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, HttpProblem, type IssueTokenOptions, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MemberInput, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RuntimeOptions, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type SignInPolicy, type SignInRule, type SignatureOptions, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineTool, deleteUser, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, issueToken, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, normalizeRoles, notFound, parseRoles, processor, readJson, readOnlyQueryTool, readOperatorSettings, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, storageCleanupSchedule, streamChatCompletion, unauthorized, verifySignature, verifyStandardWebhook, widget, withCacheBreakpoints };

package/dist/index.js

@@ -29,6 +29,10 @@ import { jwtAuthenticator } from "./auth/jwt.js";
 import { betterAuthAuthenticator } from "./better-auth/authenticator.js";
 import { issueToken, maxTokenTtlSeconds } from "./better-auth/tokens.js";
 import { authSchemaMigration, checkAuthSchema } from "./better-auth/auth-schema.js";
+import { changesMigration, checkChanges, migrationCommand } from "./changes/capture-schema.js";
+import { coalesce } from "./changes/coalesce.js";
+import { recordOf, resourceChange } from "./changes/resource-change.js";
+import { eventMatcher } from "./changes/match-events.js";
 import { maxWidgetPropsBytes, widget } from "./assistant/widget.js";
 import { functionApp } from "./functions/function-app.js";
 import { readJson } from "./functions/read-json.js";
@@ -36,4 +40,4 @@ import { verifySignature, verifyStandardWebhook } from "./functions/verify-signa
 import { requireEnv } from "./functions/require-env.js";
 import { createFileCleanup } from "./files/file-cleanup.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.js";
-export { HttpProblem, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, checkAuthSchema, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineTool, deleteUser, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, issueToken, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, normalizeRoles, notFound, parseRoles, processor, readJson, readOnlyQueryTool, readOperatorSettings, readPlatformSignIn, readWriteQueryTool, removeMember, requestApproval, requireEnv, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, storageCleanupSchedule, streamChatCompletion, unauthorized, verifySignature, verifyStandardWebhook, widget, withCacheBreakpoints };
+export { HttpProblem, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineTool, deleteUser, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, issueToken, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, normalizeRoles, notFound, parseRoles, processor, readJson, readOnlyQueryTool, readOperatorSettings, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, storageCleanupSchedule, streamChatCompletion, unauthorized, verifySignature, verifyStandardWebhook, widget, withCacheBreakpoints };

package/dist/project-config.d.ts

@@ -1,4 +1,5 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
+import { EventsOptions } from "./changes/events-options.js";
 import { FilesOptions } from "./files/options.js";
 import { Authenticator } from "./types.js";
 import { FunctionSource } from "./functions/define-function.js";
@@ -21,6 +22,8 @@ export type ProjectConfig = {
   functions?: Record<string, FunctionSource>;
   /** Where file fields keep their bytes: providers by name, retention and the signing secret (see `FilesOptions`). */
   files?: FilesOptions;
+  /** Where the changes that resources' events are raised from are captured (see `EventsOptions`). */
+  events?: EventsOptions;
   options?: AdminOptions;
 };
 /** Typed identity, for `export default defineConfig({ extends: [...], config, auth, ... })` in `protobase.config.ts`. */

package/dist/project-config.js

@@ -122,10 +122,11 @@ const mergedOptions = (named) => {
 */
 const mergeConfig = (...configs) => {
 	const named = configs.flatMap((config, index) => flatten(config, config.name ?? `config ${index + 1}`));
-	const { db, authenticate, auth } = lastSet(named.map(({ config }) => ({
+	const { db, authenticate, auth, events } = lastSet(named.map(({ config }) => ({
 		db: config.db,
 		authenticate: config.authenticate,
-		auth: config.auth
+		auth: config.auth,
+		events: config.events
 	})));
 	const module = mergedModule(named);
 	const functions = mergedFunctions(named);
@@ -140,6 +141,7 @@ const mergeConfig = (...configs) => {
 		...auth && { auth },
 		...functions && { functions },
 		...files && { files },
+		...events && { events },
 		...options && { options }
 	};
 };

package/dist/transactions.js

@@ -1,8 +1,15 @@
 import { sql } from "kysely";
 //#region src/transactions.ts
-/** One transaction whose statements Postgres cancels after `timeoutMs` (SET LOCAL statement_timeout). */
-const writeTransaction = (db, timeoutMs, run) => db.transaction().execute(async (trx) => {
-	await sql`select set_config('statement_timeout', ${String(timeoutMs)}, true)`.execute(trx);
+/**
+* One transaction whose statements Postgres cancels after `timeoutMs` (SET LOCAL statement_timeout), with `settings`
+* set for it as well, all in one statement.
+*/
+const writeTransaction = (db, timeoutMs, run, settings = {}) => db.transaction().execute(async (trx) => {
+	const all = Object.entries({
+		statement_timeout: String(timeoutMs),
+		...settings
+	});
+	await sql`select ${sql.join(all.map(([name, value]) => sql`set_config(${name}, ${value}, true)`))}`.execute(trx);
 	return run(trx);
 });
 /** Same, and Postgres refuses any write inside it. */

package/dist/write-pipeline.js

@@ -4,6 +4,7 @@ import { tenantScope } from "./tenant.js";
 import { requestAccess, requireOperation, targetFilter, writableFields } from "./request-access.js";
 import { writeTransaction } from "./transactions.js";
 import { attachFiles } from "./files/attach.js";
+import { actorSettings } from "./changes/actor.js";
 import { validateBody } from "./validate-body.js";
 import { assertWritten, checkPrecondition, decide, denied, firstKeyField, missing, notifier, shown } from "./write-shared.js";
 import { applyUpdate, planUpdate } from "./write-update.js";
@@ -89,7 +90,7 @@ const writeIn = async (trx, deps, access, request) => {
 const runWrite = async (deps, entry, session, request) => {
 	const access = await requestAccess(deps, entry, session);
 	requireOperation(access, request.operation === "undelete" ? "update" : request.operation);
-	return writeTransaction(deps.db, deps.statementTimeoutMs, (trx) => writeIn(trx, deps, access, request));
+	return writeTransaction(deps.db, deps.statementTimeoutMs, (trx) => writeIn(trx, deps, access, request), actorSettings(deps, session));
 };
 //#endregion
 export { runWrite, writeIn };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "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.8.0",
-    "@protobase/query": "0.8.0",
-    "@protobase/schema": "0.8.0",
+    "@protobase/layout": "0.8.1",
+    "@protobase/query": "0.8.1",
+    "@protobase/schema": "0.8.1",
     "@scalar/hono-api-reference": "^0.12.10",
     "@simplewebauthn/server": "^13.3.1",
     "better-auth": "^1.7.7",