@protobase/server 0.0.0-stage → 0.1.0

package/dist/routes/target.js

@@ -0,0 +1,18 @@
+import { notFound } from "../problem.js";
+//#region src/routes/target.ts
+/** `orders` is the collection; `orders:facets` is a custom method (AIP-136). Resource names never contain a colon. */
+const resolveTarget = (deps, target) => {
+	const colon = target.indexOf(":");
+	const name = colon < 0 ? target : target.slice(0, colon);
+	const entry = deps.registry.find(name);
+	if (!entry) throw notFound(`There is no resource "${name}"`);
+	return {
+		entry,
+		action: colon < 0 ? "" : target.slice(colon + 1)
+	};
+};
+const unknownAction = (action) => {
+	throw notFound(`There is no method ":${action}"`);
+};
+//#endregion
+export { resolveTarget, unknownAction };

package/dist/row-permissions.js

@@ -0,0 +1,69 @@
+import { tenantScope } from "./tenant.js";
+import { recordDecision } from "./request-access.js";
+import { aliasedColumn, columnId, scopeConditions, tableId, whereClause } from "./sql-parts.js";
+import { fetchRecord } from "./records.js";
+import { compileFilter } from "@protobase/query";
+import { sql } from "kysely";
+//#region src/row-permissions.ts
+const keyOf = (access, row) => JSON.stringify(access.full.primaryKey.map((name) => String(row[name])));
+const matching = async (trx, access, rows, filter) => {
+	const { full } = access;
+	const keyFields = full.primaryKey.map((name) => full.fields[name]);
+	const tuples = rows.map((row) => sql`(${sql.join(keyFields.map((field) => row[field.name]))})`);
+	const tenant = tenantScope(access.entry, access.session)?.tenantValue;
+	const conditions = [
+		...scopeConditions(full, tenant),
+		compileFilter(full, filter),
+		sql`(${sql.join(keyFields.map(columnId))}) in (${sql.join(tuples)})`
+	];
+	const found = await sql`select ${sql.join(keyFields.map(aliasedColumn))} from ${tableId(full)} as t${whereClause(conditions)}`.execute(trx);
+	return new Set(found.rows.map((row) => keyOf(access, row)));
+};
+/**
+* What the caller may do with each of these (exposed) rows: the operation must be allowed, the row must match the
+* operation's row filter (checked in the database), and a record-level rule must pass for the stored record. This only
+* informs the UI; every write is checked again by the write pipeline.
+*/
+const rowPermissions = async (trx, access, rows) => {
+	const { resolved, entry, session } = access;
+	const result = rows.map(() => ({
+		update: true,
+		delete: true
+	}));
+	if (rows.length === 0) return result;
+	for (const operation of ["update", "delete"]) {
+		if (!resolved.operations[operation]) {
+			result.forEach((permissions) => {
+				permissions[operation] = false;
+			});
+			continue;
+		}
+		const filter = resolved.rowFilter[operation];
+		if (filter) {
+			const allowed = await matching(trx, access, rows, filter);
+			rows.forEach((row, i) => {
+				if (!allowed.has(keyOf(access, row))) result[i][operation] = false;
+			});
+		}
+		if (!resolved.recordChecks.includes(operation)) continue;
+		const tenant = tenantScope(entry, session)?.tenantValue;
+		for (const [i, row] of rows.entries()) {
+			if (!result[i][operation]) continue;
+			const key = access.full.primaryKey.map((name) => row[name]);
+			const stored = await fetchRecord(trx, entry, key, tenant);
+			if (!stored) {
+				result[i][operation] = false;
+				continue;
+			}
+			const decision = await recordDecision(access, operation, stored.record);
+			if (decision === false) {
+				result[i][operation] = false;
+				continue;
+			}
+			if (decision !== true) result[i][operation] = (await matching(trx, access, [row], decision)).size > 0;
+		}
+	}
+	return result;
+};
+//#endregion
+export { rowPermissions };

package/dist/rows.js

@@ -0,0 +1,12 @@
+//#region src/rows.ts
+const exposeValue = (type, value) => {
+	if (typeof value === "bigint") return value.toString();
+	if (!(value instanceof Date)) return value;
+	const iso = value.toISOString();
+	return type === "date" ? iso.slice(0, 10) : iso;
+};
+/** A row as the API shows it: dates as ISO text, 64-bit integers as strings. */
+const exposeRow = (model, row) => Object.fromEntries(Object.entries(row).filter(([name]) => Object.hasOwn(model.fields, name)).map(([name, value]) => [name, exposeValue(model.fields[name].type, value)]));
+const pickFields = (row, names) => names ? Object.fromEntries(names.map((name) => [name, row[name]])) : row;
+//#endregion
+export { exposeRow, pickFields };

package/dist/scan-guard.js

@@ -0,0 +1,72 @@
+import { HttpProblem } from "./problem.js";
+import { scopeConditions, tableId } from "./sql-parts.js";
+import { filterFields, filterShape } from "./filter-shape.js";
+import { buildListQuery, compileFilter, explainGuard } from "@protobase/query";
+import { sql } from "kysely";
+//#region src/scan-guard.ts
+const maxCached = 1e3;
+const filteredQuery = (db, entry, shape, { scope }) => {
+	const { model } = entry;
+	const conditions = [
+		...scopeConditions(scope.fullModel ?? model, scope.tenantValue),
+		...scope.rowFilter ? [compileFilter(model, scope.rowFilter)] : [],
+		...shape.filter ? [compileFilter(model, shape.filter)] : []
+	];
+	let query = db.selectFrom(sql`${tableId(model)}`.as("t")).select(sql.lit(1).as("one"));
+	for (const condition of conditions) query = query.where(condition);
+	return query;
+};
+const pagedQuery = async (db, shape, { model, scope }) => {
+	const { query } = await buildListQuery(db, model, shape, scope);
+	return query;
+};
+const indexStatement = (entry, fields) => {
+	const { schema, name } = entry.model.table;
+	const table = schema ? `"${schema}"."${name}"` : `"${name}"`;
+	const columns = [...new Set(fields.map((field) => field.column))];
+	if (columns.length === 0) return "an index that covers the filter your role is limited by";
+	return `create index on ${table} (${columns.map((column) => `"${column}"`).join(", ")})`;
+};
+/** Plans each list query shape once (EXPLAIN, never executed) and remembers the verdict. */
+const createScanGuard = (db, options = {}) => {
+	const { mode = "reject", seqScanRows } = options;
+	const verdicts = /* @__PURE__ */ new Map();
+	const thresholds = {
+		...seqScanRows && { seqScanRows },
+		sortRows: Number.MAX_SAFE_INTEGER
+	};
+	const judge = async (entry, shape, context) => {
+		const filtered = shape.filter ? await explainGuard(db, filteredQuery(db, entry, shape, context), thresholds) : void 0;
+		const paged = await explainGuard(db, await pagedQuery(db, shape, context), thresholds);
+		const sortField = shape.sort?.[0] && entry.model.fields[shape.sort[0][0]];
+		const suggestions = [...filtered && !filtered.ok ? [indexStatement(entry, filterFields(shape.filter))] : [], ...!paged.ok && sortField ? [indexStatement(entry, [sortField])] : []];
+		return {
+			findings: [...filtered?.findings ?? [], ...paged.findings],
+			suggestion: suggestions[0] ?? indexStatement(entry, filterFields(shape.filter))
+		};
+	};
+	const verdictFor = async (entry, shape, context) => {
+		const key = `${entry.name}|${filterShape(context.scope.rowFilter)}|${filterShape(shape.filter)}|${(shape.sort ?? []).map(([name, direction]) => `${name}:${direction}`).join(",")}`;
+		const known = verdicts.get(key);
+		if (known) return known;
+		const verdict = await judge(entry, shape, context);
+		if (verdicts.size >= maxCached) verdicts.delete(verdicts.keys().next().value);
+		verdicts.set(key, verdict);
+		return verdict;
+	};
+	/** Throws a 400 problem for an expensive shape in `reject` mode; in `warn` mode returns the warning text. */
+	return async (entry, shape, context) => {
+		if (mode === "off") return void 0;
+		const { findings, suggestion } = await verdictFor(entry, shape, context);
+		const finding = findings[0];
+		if (!finding) return void 0;
+		const detail = `This query would sequentially scan "${finding.relation}" (about ${finding.rows} rows). Add an index, for example: ${suggestion}`;
+		if (mode === "warn") return detail;
+		throw new HttpProblem(400, "expensive-query", "Bad Request", detail, {
+			findings,
+			suggestion
+		});
+	};
+};
+//#endregion
+export { createScanGuard };

package/dist/sql-parts.js

@@ -0,0 +1,32 @@
+import { compileFilter } from "@protobase/query";
+import { sql } from "kysely";
+//#region src/sql-parts.ts
+const etagAlias = "__pb_etag";
+const tableId = (model) => {
+	const { schema, name } = model.table;
+	return schema ? sql.id(schema, name) : sql.id(name);
+};
+const columnId = (field) => sql`${sql.id(field.column)}`;
+const aliasedColumn = (field) => sql`${columnId(field)} as ${sql.id(field.name)}`;
+/** `column as "field"` for the given fields (default: all), plus the ETag source column as exact text when the table has one. */
+const returningList = (entry, fields = Object.values(entry.model.fields)) => {
+	const columns = fields.map(aliasedColumn);
+	if (entry.etag) columns.push(sql`${columnId(entry.etag.field)}::text as ${sql.id(etagAlias)}`);
+	return sql.join(columns);
+};
+const columnNamed = (model, name) => {
+	const field = Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
+	return field ? columnId(field) : sql`${sql.id(name)}`;
+};
+/** Rows of the caller's tenant, live ones unless `deleted` says otherwise: the conditions every statement on a resource starts with. */
+const scopeConditions = (model, tenant, deleted = "hide") => {
+	const conditions = [];
+	if (model.softDelete && deleted !== "show") conditions.push(sql`${columnNamed(model, model.softDelete)} is ${sql.raw(deleted === "only" ? "not null" : "null")}`);
+	if (model.tenant && tenant !== void 0) conditions.push(sql`${columnNamed(model, model.tenant)} = ${tenant}`);
+	return conditions;
+};
+const keyConditions = (model, key) => model.primaryKey.map((name, i) => sql`${columnId(model.fields[name])} = ${key[i]}`);
+const filterCondition = (model, filter) => filter ? [compileFilter(model, filter)] : [];
+const whereClause = (conditions) => conditions.length === 0 ? sql`` : sql` where ${sql.join(conditions, sql` and `)}`;
+//#endregion
+export { aliasedColumn, columnId, etagAlias, filterCondition, keyConditions, returningList, scopeConditions, tableId, whereClause };

package/dist/tenant.js

@@ -0,0 +1,10 @@
+import { forbidden } from "./problem.js";
+//#region src/tenant.ts
+/** The query-layer scope for the caller; a tenant-scoped resource without a tenant is refused. */
+const tenantScope = (entry, session) => {
+	if (!entry.model.tenant) return void 0;
+	if (session.tenant === void 0) throw forbidden("tenant-required", `Resource "${entry.name}" is tenant-scoped and the caller has no tenant`);
+	return { tenantValue: session.tenant };
+};
+//#endregion
+export { tenantScope };

package/dist/transactions.js

@@ -0,0 +1,14 @@
+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);
+	return run(trx);
+});
+/** Same, and Postgres refuses any write inside it. */
+const readTransaction = (db, timeoutMs, run) => writeTransaction(db, timeoutMs, async (trx) => {
+	await sql`set transaction read only`.execute(trx);
+	return run(trx);
+});
+//#endregion
+export { readTransaction, writeTransaction };

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+import { Hono } from "hono";
+import { PageModel } from "@protobase/layout";
+import { ResolveOptions, ResourceModel, ViewModel } from "@protobase/schema";
+import { Db } from "@protobase/query";
+//#region src/types.d.ts
+export type TenantValue = string | number;
+export type User = {
+  id: string | number;
+  roles: string[];
+};
+export type Session = {
+  user: User;
+  tenant?: TenantValue;
+};
+/** Resolves the caller of a request, or throws a 401 problem (see `unauthorized`). */
+export type Authenticator = (request: Request) => Promise<Session> | Session;
+export type AdminEnv = {
+  Variables: {
+    session: Session;
+  };
+};
+export type Row = Record<string, unknown>;
+export type WriteOperation = 'create' | 'update' | 'delete' | 'undelete';
+/** Passed to every pipeline hook, inside the write transaction, after the row was written. */
+export type WriteEvent = {
+  operation: WriteOperation;
+  resource: ResourceModel;
+  user: User;
+  tenant?: TenantValue;
+  before?: Row;
+  after?: Row;
+};
+/** Extension point of the write pipeline: a hook that throws rolls the write back. */
+export type PipelineHook = (event: WriteEvent, trx: Db) => Promise<void>;
+/** What happened, by whom, to which value. It never carries the value itself. */
+export type AuditEvent = {
+  type: 'field.revealed';
+  /** ISO 8601, when the server answered. */
+  at: string;
+  actor: {
+    id: string | number;
+    roles: string[];
+  };
+  /** The caller's tenant (organization), when the resource has one. */
+  tenant?: TenantValue;
+  resource: string;
+  /** The record's key as its URL has it (composite keys joined with a comma). */
+  recordKey: string;
+  field: string;
+  /** Where the request came from, as its headers say; proxies set `forwardedFor`, so it is only as trustworthy as they are. */
+  origin: {
+    userAgent?: string;
+    forwardedFor?: string;
+  };
+};
+/**
+ * Where audit events go. `publish` resolves once the event is accepted; when it rejects, the request that caused the
+ * event fails, so nothing is revealed without its event. A real queue replaces the console one through
+ * `options.audit` in `protobase.config.ts`.
+ */
+export type AuditQueue = {
+  publish(event: AuditEvent): Promise<void>;
+};
+export type ScanGuardMode = 'reject' | 'warn' | 'off';
+export type AdminOptions = {
+  /** Default `/api/v1`. */
+  basePath?: string;
+  /** Applied to every request's transaction with SET LOCAL. Default 15000. */
+  statementTimeoutMs?: number;
+  /** List shapes that would sequentially scan a table of more than `seqScanRows` rows (default 10000). Default mode `reject`. */
+  scanGuard?: {
+    mode?: ScanGuardMode;
+    seqScanRows?: number;
+  };
+  /** Runs inside the write transaction after each create, update and delete. */
+  writeHooks?: PipelineHook[];
+  /** The project's roles (from `defineRoles`): an operation without an access rule needs the matching capability. */
+  roles?: ResolveOptions['roles'];
+  /** What an operation without a rule does; overrides the capability check. Without `roles` the default is allow. */
+  defaultAccess?: ResolveOptions['defaultAccess'];
+  /** Whether list items carry their `permissions` (update, delete): true by default, or `{ except: [...] }` for resources that opt out. */
+  rowPermissions?: boolean | {
+    except: string[];
+  };
+  /** Receives an event for every reveal of a sensitive field. Default: printed to the console, nothing kept. */
+  audit?: AuditQueue;
+  /** Called with every error the API turns into a 500, so the host can report it. */
+  onUnhandledError?: (error: unknown) => void;
+};
+export type ViewSource = {
+  toModel(): ViewModel;
+};
+export type PageSource = {
+  toModel(): PageModel;
+};
+export type Admin = Hono<AdminEnv>;
+//#endregion

package/dist/validate-body.js

@@ -0,0 +1,73 @@
+import { badRequest } from "./problem.js";
+import { writableFields } from "./request-access.js";
+//#region src/validate-body.ts
+const fail = (errors) => badRequest("invalid-record", `The request body is invalid: ${errors[0].field}: ${errors[0].message}`, { errors });
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const reserved = ["etag", "permissions"];
+/**
+* Checks a create or update body for this caller. A field the caller cannot read is an unknown field, one they can read
+* but not write is read-only (the tenant column and the API's own `etag` and `permissions` keys are always read-only);
+* every provided value goes through its field's zod schema, then `.validate()` rules run on the result.
+* Returns only the values to write: on create the defaults are filled in, on update only the provided fields.
+* `current` is the stored record an update merges into for `.validate()` rules.
+*/
+const validateBody = (access, mode, body, current = {}) => {
+	if (!isObject(body)) throw badRequest("invalid-record", "The request body must be a JSON object");
+	const { entry, readable: model, full } = access;
+	const writable = new Set(writableFields(access, mode));
+	const errors = [];
+	const values = {};
+	for (const name of Object.keys(body)) if (reserved.includes(name) && !Object.hasOwn(model.fields, name)) errors.push({
+		field: name,
+		code: "read-only",
+		message: name === "etag" ? "The version is not part of the body; send it in the If-Match header" : `"${name}" is read-only`
+	});
+	else if (!Object.hasOwn(model.fields, name)) errors.push({
+		field: name,
+		code: "unknown-field",
+		message: `Unknown field "${name}"`
+	});
+	else if (!writable.has(name) || name === full.tenant) errors.push({
+		field: name,
+		code: "read-only",
+		message: `"${name}" is read-only`
+	});
+	if (errors.length > 0) throw fail(errors);
+	for (const [name, source] of Object.entries(entry.source.state.fields ?? {})) {
+		const field = full.fields[name];
+		if (!source || !field || !writable.has(name) || name === full.tenant) continue;
+		const provided = Object.hasOwn(body, name);
+		if (!provided && mode === "update") continue;
+		if (!provided && field.default && "db" in field.default) continue;
+		const parsed = source.schema.safeParse(provided ? body[name] : void 0);
+		if (parsed.success) {
+			if (parsed.data !== void 0) values[name] = parsed.data;
+			continue;
+		}
+		if (!provided && field.nullable) continue;
+		if (!provided) errors.push({
+			field: name,
+			code: "required",
+			message: `"${name}" is required`
+		});
+		else errors.push(...parsed.error.issues.map((issue) => ({
+			field: name,
+			code: "invalid-value",
+			message: issue.message
+		})));
+	}
+	if (errors.length > 0) throw fail(errors);
+	const merged = {
+		...current,
+		...values
+	};
+	const issues = entry.source.validators.flatMap((validate) => validate(merged) ?? []);
+	if (issues.length > 0) throw fail(issues.map((issue) => ({
+		field: Object.hasOwn(model.fields, issue.field) ? issue.field : "_record",
+		code: "invalid-record",
+		message: issue.message
+	})));
+	return values;
+};
+//#endregion
+export { validateBody };

package/dist/view-access.js

@@ -0,0 +1,54 @@
+import { relatedErrors } from "./view-related.js";
+import { resolveFieldPath } from "@protobase/layout";
+import { navRecentErrors } from "@protobase/schema";
+//#region src/view-access.ts
+const pruneRelated = (item, resource, models) => {
+	const { columns, ...rest } = item;
+	const visible = models[item.resource] ? columns?.filter((column) => resolveFieldPath(models, item.resource, column).ok) : void 0;
+	const narrowed = visible && visible.length > 0 ? {
+		...rest,
+		columns: visible
+	} : rest;
+	return relatedErrors(narrowed, resource, models).length === 0 ? [narrowed] : [];
+};
+/**
+* The view with every reference to a field the caller cannot read removed: columns, sort, search, field labels,
+* filter widgets, layout, chart, title, search result, the update actions that set one, and the sidebar's `recent` group
+* when its status, filter or order uses a hidden field. Nothing in it may name a hidden field. Related sections are checked against
+* `models`, the caller's view of every resource.
+*/
+const pruneView = (view, model, models) => {
+	const visible = (name) => Object.hasOwn(model.fields, name);
+	const { title, chart, list, nav, searchResult, ...rest } = view;
+	const { recent, ...placement } = nav ?? {};
+	const resultTitle = searchResult?.title?.filter(visible);
+	const subtitle = searchResult?.subtitle;
+	return {
+		...rest,
+		...searchResult && { searchResult: {
+			...resultTitle?.length && { title: resultTitle },
+			...subtitle !== void 0 && visible(subtitle) && { subtitle }
+		} },
+		...nav && { nav: recent && navRecentErrors(recent, model).length === 0 ? nav : placement },
+		...title !== void 0 && visible(title) && { title },
+		...chart && visible(chart.field) && { chart },
+		...list && { list: {
+			columns: list.columns.filter(visible),
+			...list.sort && { sort: list.sort.filter(([name]) => visible(name)) },
+			...list.search && { search: list.search.filter(visible) }
+		} },
+		fields: Object.fromEntries(Object.entries(view.fields).filter(([name]) => visible(name))),
+		filters: view.filters.filter((widget) => visible(widget.field)),
+		actions: view.actions.filter((action) => action.run?.kind !== "update" || Object.keys(action.run.values).every(visible)),
+		layout: view.layout.flatMap((item) => {
+			if (item.kind === "related") return pruneRelated(item, view.resource, models);
+			const fields = item.fields.filter(visible);
+			return fields.length > 0 ? [{
+				...item,
+				fields
+			}] : [];
+		})
+	};
+};
+//#endregion
+export { pruneView };

package/dist/view-related.js

@@ -0,0 +1,59 @@
+import { resolveFieldPath } from "@protobase/layout";
+import { checkFilter, checkOrderBy, parseFilter, parseOrderBy } from "@protobase/schema";
+//#region src/view-related.ts
+const filterErrors = (model, source) => {
+	if (source === void 0) return [];
+	const parsed = parseFilter(source);
+	if (!parsed.ok) return parsed.errors.map((error) => error.message);
+	const checked = parsed.ast ? checkFilter(model, parsed.ast) : void 0;
+	return checked && !checked.ok ? checked.errors.map((error) => error.message) : [];
+};
+const sortErrors = (model, source) => {
+	if (source === void 0) return [];
+	const parsed = parseOrderBy(source);
+	if (!parsed.ok) return parsed.errors.map((error) => error.message);
+	const checked = checkOrderBy(model, parsed.items);
+	return checked.ok ? [] : checked.errors.map((error) => error.message);
+};
+const matchErrors = (model, name, to) => {
+	const field = Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
+	if (!field) return [`unknown field "${name}" on ${model.name}`];
+	if (!field.filterable) return [`"${name}" on ${model.name} is not filterable`];
+	if (to !== void 0 && field.relation?.resource !== to) return [`"${name}" on ${model.name} is not a relation to ${to}`];
+	return [];
+};
+/** The field whose values the `through` records hand on: `key`, else their single-column primary key. */
+const throughKey = (via, key) => key ?? (via.primaryKey.length === 1 ? via.primaryKey[0] : void 0);
+const throughErrors = (through, resource, models) => {
+	const via = models[through.resource];
+	if (!via) return [`unknown resource "${through.resource}"`];
+	const key = throughKey(via, through.key);
+	return [
+		...matchErrors(via, through.field, resource),
+		...key === void 0 ? [`${via.name} has a composite key, so name the field to collect with "key"`] : Object.hasOwn(via.fields, key) ? [] : [`unknown field "${key}" on ${via.name}`],
+		...filterErrors(via, through.filter).map((error) => `filter: ${error}`)
+	].map((error) => `through: ${error}`);
+};
+/**
+* What is wrong with a related section on the record page of `resource`, against these models; empty when it can be
+* shown. Against the full models it checks the config; against a caller's models, whether that caller can use it.
+*/
+const relatedErrors = (item, resource, models) => {
+	const owner = models[resource];
+	const target = models[item.resource];
+	if (!owner || !target) return [`unknown resource "${owner ? item.resource : resource}"`];
+	if (owner.primaryKey.length !== 1) return [`${resource} has a composite key, so a related section cannot match it`];
+	return [
+		...item.through ? [...throughErrors(item.through, resource, models), ...matchErrors(target, item.field)] : matchErrors(target, item.field, resource),
+		...filterErrors(target, item.filter).map((error) => `filter: ${error}`),
+		...sortErrors(target, item.sort).map((error) => `sort: ${error}`),
+		...(item.columns ?? []).flatMap((column) => {
+			const resolved = resolveFieldPath(models, target.name, column);
+			if (!resolved.ok) return [`column: ${resolved.message}`];
+			return resolved.steps.at(-1).field.sensitive ? [`column: "${column}" is sensitive, so it cannot be listed`] : [];
+		}),
+		...item.pageSize === void 0 || Number.isInteger(item.pageSize) && item.pageSize >= 1 && item.pageSize <= 100 ? [] : ["pageSize must be a whole number from 1 to 100"]
+	];
+};
+//#endregion
+export { relatedErrors, throughKey };

package/dist/write-pipeline.js

@@ -0,0 +1,94 @@
+import { HttpProblem, badRequest } from "./problem.js";
+import { tenantScope } from "./tenant.js";
+import { requestAccess, requireOperation, targetFilter, writableFields } from "./request-access.js";
+import { writeTransaction } from "./transactions.js";
+import { deleteRecord, fetchRecord, insertRecord, restoreRecord } from "./records.js";
+import { assertWritten, checkPrecondition, decide, denied, firstKeyField, missing, notifier, shown } from "./write-shared.js";
+import { validateBody } from "./validate-body.js";
+import { applyUpdate, planUpdate } from "./write-update.js";
+//#region src/write-pipeline.ts
+const withOwner = (access, values) => {
+	const { owner } = access.full;
+	const caller = access.session.user.id;
+	if (!owner || !access.resolved.rowFilter.create || values[owner] !== void 0 || caller === void 0) return values;
+	return {
+		...values,
+		[owner]: caller
+	};
+};
+const create = async (trx, deps, access, body) => {
+	const { entry, full } = access;
+	const scope = tenantScope(entry, access.session);
+	const tenantValues = full.tenant && scope ? { [full.tenant]: scope.tenantValue } : {};
+	const preset = typeof body === "object" && body !== null && !Array.isArray(body) && writableFields(access, "create").includes(full.owner ?? "") ? withOwner(access, body) : body;
+	const row = {
+		...withOwner(access, validateBody(access, "create", preset, tenantValues)),
+		...tenantValues
+	};
+	const filter = await decide(access, "create", void 0, row);
+	const created = await insertRecord(trx, entry, row, { etagFields: Object.keys(access.model.fields) });
+	await assertWritten(trx, access, created, "create", access.resolved.rowFilter.create, filter);
+	await notifier(deps, access)(trx, "create", void 0, created.record);
+	return shown(access, created);
+};
+const update = async (trx, deps, access, request) => {
+	const plan = await planUpdate(trx, access, request.key, request.body, request.ifMatch);
+	if (Object.keys(plan.values).length === 0) return shown(access, plan.current);
+	return shown(access, await applyUpdate(trx, deps, access, request.key, plan));
+};
+const removeOrRestore = async (trx, deps, access, request) => {
+	const { entry, full } = access;
+	const undelete = request.operation === "undelete";
+	if (undelete && !full.softDelete) throw badRequest("undelete-unsupported", `Resource "${entry.name}" does not soft delete, so there is nothing to undelete`);
+	const scope = tenantScope(entry, access.session);
+	const operation = undelete ? "update" : "delete";
+	const deleted = undelete ? "only" : "hide";
+	const target = targetFilter(access, operation);
+	const shape = { etagFields: Object.keys(access.model.fields) };
+	const current = await fetchRecord(trx, entry, request.key, scope?.tenantValue, {
+		deleted,
+		lock: true,
+		...target && { filter: target },
+		...shape
+	});
+	if (!current) throw undelete && await fetchRecord(trx, entry, request.key, scope?.tenantValue, {
+		filter: access.resolved.rowFilter.read,
+		fields: [firstKeyField(access)]
+	}) ? new HttpProblem(409, "not-deleted", "Conflict", `This ${entry.name} record is not deleted`) : missing(entry);
+	checkPrecondition(current, request.ifMatch, false);
+	const filter = await decide(access, operation, current.record);
+	if (filter && !await fetchRecord(trx, entry, request.key, scope?.tenantValue, {
+		deleted,
+		filter,
+		fields: [firstKeyField(access)]
+	})) throw denied(entry, operation);
+	const notify = notifier(deps, access);
+	if (undelete) {
+		const restored = await restoreRecord(trx, entry, request.key, scope?.tenantValue, shape);
+		await assertWritten(trx, access, restored, "undelete", access.resolved.rowFilter.update, filter);
+		await notify(trx, "undelete", current.record, restored.record);
+		return shown(access, restored);
+	}
+	const removed = await deleteRecord(trx, entry, request.key, scope?.tenantValue, shape);
+	await notify(trx, "delete", current.record, void 0);
+	return shown(access, removed);
+};
+/**
+* One write inside an open transaction, for a caller whose access is already resolved: operations and field access,
+* tenant scope, validation against the fields they may write, optimistic concurrency, row filters and record-level
+* rules checked in the database, then the hooks. Batches run many of these in one transaction.
+*/
+const writeIn = async (trx, deps, access, request) => {
+	requireOperation(access, request.operation === "undelete" ? "update" : request.operation);
+	if (request.operation === "create") return create(trx, deps, access, request.body);
+	if (request.operation === "update") return update(trx, deps, access, request);
+	return removeOrRestore(trx, deps, access, request);
+};
+/** The path every single write takes: resolve access once, then `writeIn` in its own transaction with a statement timeout. The caller has already authenticated `session`. */
+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));
+};
+//#endregion
+export { runWrite, writeIn };