better-supabase 0.7.0 → 0.8.0

package/dist/overlay/index.js

@@ -0,0 +1,554 @@
+import { n as memoized, t as importOptionalPeer } from "../optional-peer-D1pi-skw.js";
+//#region src/overlay/path.ts
+const ESCAPES = {
+	b: "\b",
+	f: "\f",
+	n: "\n",
+	r: "\r",
+	t: "	",
+	"'": "'",
+	"\\": "\\",
+	"/": "/"
+};
+/**
+* Parses an RFC 9535 normalized path (§ 2.7), such as `$['paths'][0]`, into
+* its segments. Throws for anything else, because the engine promised one.
+*/
+function parseNormalizedPath(path) {
+	if (!path.startsWith("$")) throw new TypeError(`Not a normalized path: ${path}`);
+	const segments = [];
+	let i = 1;
+	while (i < path.length) {
+		if (path[i] !== "[") throw new TypeError(`Not a normalized path: ${path}`);
+		i++;
+		if (path[i] === "'") {
+			i++;
+			let name = "";
+			while (i < path.length && path[i] !== "'") {
+				const char = path[i] ?? "";
+				if (char !== "\\") {
+					name += char;
+					i++;
+					continue;
+				}
+				const next = path[i + 1] ?? "";
+				if (next === "u") {
+					name += String.fromCodePoint(Number.parseInt(path.slice(i + 2, i + 6), 16));
+					i += 6;
+					continue;
+				}
+				const escaped = ESCAPES[next];
+				if (escaped === void 0) throw new TypeError(`Not a normalized path: ${path}`);
+				name += escaped;
+				i += 2;
+			}
+			if (path[i] !== "'" || path[i + 1] !== "]") throw new TypeError(`Not a normalized path: ${path}`);
+			segments.push(name);
+			i += 2;
+			continue;
+		}
+		const end = path.indexOf("]", i);
+		const digits = end === -1 ? "" : path.slice(i, end);
+		if (!/^(?:0|[1-9]\d*)$/.test(digits)) throw new TypeError(`Not a normalized path: ${path}`);
+		segments.push(Number(digits));
+		i = end + 1;
+	}
+	return segments;
+}
+const SHORTHAND = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function quote(name) {
+	let out = "";
+	for (const char of name) {
+		const code = char.codePointAt(0) ?? 0;
+		if (char === "\\") out += "\\\\";
+		else if (char === "'") out += "\\'";
+		else if (char === "\b") out += "\\b";
+		else if (char === "\f") out += "\\f";
+		else if (char === "\n") out += "\\n";
+		else if (char === "\r") out += "\\r";
+		else if (char === "	") out += "\\t";
+		else if (code < 32) out += `\\u${code.toString(16).padStart(4, "0")}`;
+		else out += char;
+	}
+	return `['${out}']`;
+}
+/**
+* Formats segments as a readable RFC 9535 query: member-name shorthand for
+* plain names, bracket notation otherwise (`$.paths['/customers'].get`).
+*/
+function formatPath(segments) {
+	let out = "$";
+	for (const segment of segments) if (typeof segment === "number") out += `[${segment}]`;
+	else if (SHORTHAND.test(segment)) out += `.${segment}`;
+	else out += quote(segment);
+	return out;
+}
+/** Decodes one RFC 6901 reference token. */
+function decodePointerToken(token) {
+	return token.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+//#endregion
+//#region src/overlay/apply.ts
+const ALLOW_EMPTY = "x-better-supabase-allow-empty";
+const REF_PREFIX = "#/components/actions/";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isArray = (value) => Array.isArray(value);
+const kindOf$1 = (value) => Array.isArray(value) ? "array" : isObject(value) ? "object" : "primitive";
+function readMinor(version) {
+	if (typeof version !== "string") return void 0;
+	const match = /^1\.([012])\.\d+$/.exec(version);
+	if (!match) return void 0;
+	const minor = Number(match[1]);
+	return minor === 0 || minor === 1 || minor === 2 ? minor : void 0;
+}
+/** An Action Object needs a string target; the other fields are read defensively. */
+const isAction = (entry) => typeof entry["target"] === "string";
+function report(reporter, severity, code, message, pointer) {
+	reporter.diagnostics.push({
+		code,
+		severity,
+		message,
+		pointer: `${reporter.prefix}${pointer}`
+	});
+}
+/**
+* Expands a Reusable Action Reference (Overlay 1.2 § 4.5.6) into a plain
+* action: the referenced `fields`, then the reference's own fields on top.
+*/
+function resolveReference(overlay, entry, pointer, reporter) {
+	const { $ref: ref, ...own } = entry;
+	if (typeof ref !== "string" || !ref.startsWith(REF_PREFIX)) {
+		report(reporter, "error", "overlay-ref-unresolved", `The reusable action reference ${String(ref)} does not point under ${REF_PREFIX}`, pointer);
+		return;
+	}
+	const name = decodePointerToken(ref.slice(21));
+	const components = "components" in overlay ? overlay.components : void 0;
+	const reusables = isObject(components) ? components["actions"] : void 0;
+	const reusable = isObject(reusables) && Object.hasOwn(reusables, name) ? reusables[name] : void 0;
+	if (!isObject(reusable)) {
+		report(reporter, "error", "overlay-ref-unresolved", `The reusable action ${ref} does not exist in components.actions`, pointer);
+		return;
+	}
+	const fields = isObject(reusable["fields"]) ? { ...reusable["fields"] } : {};
+	if ("target" in fields) {
+		report(reporter, "warning", "overlay-invalid-action", `The reusable action ${ref} sets target, which only the reference may set; it is ignored`, pointer);
+		delete fields["target"];
+	}
+	return {
+		...fields,
+		...own
+	};
+}
+function resolve(document, segments) {
+	let parent = void 0;
+	let key = void 0;
+	let value = document;
+	for (const segment of segments) {
+		parent = value;
+		key = segment;
+		value = typeof segment === "number" ? Array.isArray(value) ? value[segment] : void 0 : isObject(value) ? value[segment] : void 0;
+	}
+	return {
+		parent,
+		key,
+		value
+	};
+}
+const escapeToken = (segment) => `/${String(segment).replaceAll("~", "~0").replaceAll("/", "~1")}`;
+const toPointer = (segments) => segments.map(escapeToken).join("");
+/** Merges `source` into `target` recursively (§ 4.5.4.1) and collects the conflicting pointers. */
+function mergeInto(target, source, at, conflicts) {
+	for (const [key, value] of Object.entries(source)) {
+		if (!Object.hasOwn(target, key)) {
+			target[key] = value;
+			continue;
+		}
+		const current = target[key];
+		if (kindOf$1(current) !== kindOf$1(value)) {
+			conflicts.push(`${at}${escapeToken(key)}`);
+			continue;
+		}
+		if (isObject(current) && isObject(value)) mergeInto(current, value, `${at}${escapeToken(key)}`, conflicts);
+		else if (isArray(current) && isArray(value)) current.push(...value);
+		else target[key] = value;
+	}
+}
+function select(state, expression, options, reporter, pointer, field) {
+	try {
+		return options.jsonpath.paths(state.document, expression).map(parseNormalizedPath);
+	} catch (error) {
+		report(reporter, "error", "overlay-invalid-target", `The ${field} ${JSON.stringify(expression)} is not a valid RFC 9535 query: ${error instanceof Error ? error.message : String(error)}`, pointer);
+		return;
+	}
+}
+function removeNodes(state, targets, reporter, pointer) {
+	const fromArrays = /* @__PURE__ */ new Map();
+	for (const segments of targets) {
+		const { parent, key } = resolve(state.document, segments);
+		if (key === void 0) {
+			report(reporter, "error", "overlay-invalid-action", "The action removes the document root, which is not allowed", pointer);
+			continue;
+		}
+		if (Array.isArray(parent) && typeof key === "number") {
+			const indexes = fromArrays.get(parent) ?? [];
+			indexes.push(key);
+			fromArrays.set(parent, indexes);
+		} else if (isObject(parent) && typeof key === "string") delete parent[key];
+	}
+	for (const [array, indexes] of fromArrays) for (const index of [...new Set(indexes)].toSorted((a, b) => b - a)) array.splice(index, 1);
+}
+function updateNodes(state, targets, value, reporter, pointer) {
+	const nodes = targets.map((segments) => ({
+		segments,
+		...resolve(state.document, segments)
+	}));
+	const kinds = new Set(nodes.map((node) => kindOf$1(node.value)));
+	if (kinds.size > 1) {
+		report(reporter, "error", "overlay-mixed-targets", `The target selects ${[...kinds].join(" and ")} nodes; an update needs nodes of one kind`, pointer);
+		return;
+	}
+	const valueKind = kindOf$1(value);
+	for (const node of nodes) {
+		const copy = structuredClone(value);
+		const at = toPointer(node.segments) || "the root";
+		if (isArray(node.value)) {
+			if (isArray(copy)) node.value.push(...copy);
+			else node.value.push(copy);
+			continue;
+		}
+		if (isObject(node.value)) {
+			if (!isObject(copy)) {
+				report(reporter, "error", "overlay-merge-conflict", `Cannot merge a${valueKind === "array" ? "n array" : " primitive"} into the object at ${at}`, pointer);
+				continue;
+			}
+			const conflicts = [];
+			mergeInto(node.value, copy, toPointer(node.segments), conflicts);
+			for (const conflict of conflicts) report(reporter, "error", "overlay-merge-conflict", `Cannot merge values of different kinds at ${conflict}`, pointer);
+			continue;
+		}
+		if (valueKind !== "primitive") {
+			report(reporter, "error", "overlay-merge-conflict", `Cannot replace the primitive at ${at} with a${valueKind === "array" ? "n array" : "n object"}`, pointer);
+			continue;
+		}
+		if (node.key === void 0) state.document = copy;
+		else if (Array.isArray(node.parent) && typeof node.key === "number") node.parent[node.key] = copy;
+		else if (isObject(node.parent) && typeof node.key === "string") node.parent[node.key] = copy;
+	}
+}
+function runAction(state, action, minor, options, reporter, pointer) {
+	if (action.remove !== true && action.update === void 0 && action.copy !== void 0 && minor === 0) {
+		report(reporter, "error", "overlay-version-feature", "copy needs Overlay 1.1 or later; the action is skipped", pointer);
+		return;
+	}
+	const targets = select(state, action.target, options, reporter, pointer, "target");
+	if (!targets) return;
+	if (targets.length === 0) {
+		if (action[ALLOW_EMPTY] !== true && options.allowEmpty !== true) report(reporter, "error", "overlay-no-match", `The target ${action.target} selects no nodes; set ${ALLOW_EMPTY}: true on the action if that is expected`, pointer);
+		return;
+	}
+	if (action.remove === true) {
+		removeNodes(state, targets, reporter, pointer);
+		return;
+	}
+	if (action.update !== void 0) {
+		updateNodes(state, targets, action.update, reporter, pointer);
+		return;
+	}
+	if (typeof action.copy === "string") {
+		const sources = select(state, action.copy, options, reporter, pointer, "copy source");
+		if (!sources) return;
+		const [source] = sources;
+		if (sources.length !== 1 || !source) {
+			report(reporter, "error", "overlay-copy-source", `The copy source ${action.copy} selects ${sources.length} nodes; it must select exactly one`, pointer);
+			return;
+		}
+		updateNodes(state, targets, resolve(state.document, source).value, reporter, pointer);
+		return;
+	}
+	report(reporter, "warning", "overlay-empty-action", "The action has no update, copy or remove, so it changes nothing", pointer);
+}
+/** Applies one overlay to `state.document` in place. */
+function applyInPlace(state, overlay, options, reporter) {
+	const minor = readMinor(overlay.overlay);
+	if (minor === void 0) {
+		report(reporter, "error", "overlay-version-unsupported", `Overlay version ${overlay.overlay} is not supported; use 1.0.x, 1.1.x or 1.2.x`, "/overlay");
+		return;
+	}
+	if (!Array.isArray(overlay.actions)) {
+		report(reporter, "error", "overlay-invalid-action", "The overlay has no actions array", "/actions");
+		return;
+	}
+	const actions = overlay.actions;
+	for (const [index, entry] of actions.entries()) {
+		const pointer = `/actions/${index}`;
+		if (!isObject(entry)) {
+			report(reporter, "error", "overlay-invalid-action", "The action is not an object", pointer);
+			continue;
+		}
+		if ("$ref" in entry && minor < 2) report(reporter, "warning", "overlay-version-feature", `Reusable actions need Overlay 1.2; the reference is expanded for this ${overlay.overlay} overlay`, pointer);
+		const action = "$ref" in entry ? resolveReference(overlay, entry, pointer, reporter) : entry;
+		if (!action) continue;
+		if (!isAction(action)) {
+			report(reporter, "error", "overlay-invalid-action", "The action has no target", pointer);
+			continue;
+		}
+		runAction(state, action, minor, options, reporter, pointer);
+	}
+}
+/**
+* Applies an Overlay 1.0, 1.1 or 1.2 document to `document` and returns a
+* new document. The input is cloned once with `structuredClone` and never
+* changed; each target runs once through `options.jsonpath`.
+*
+* Actions run in order, each on the result of the previous one (Overlay
+* § 4.5.1.1). `update` merges objects, concatenates or appends to arrays and
+* replaces primitives; `remove` deletes the selected nodes; `copy` (1.1 and
+* later) uses the value of the single node its query selects. Reusable action
+* references (1.2) are expanded, with a warning when the overlay declares
+* 1.0 or 1.1.
+*
+* Problems never throw: they are diagnostics, and the failing action is
+* skipped. A target that selects nothing reports `overlay-no-match` as an
+* error unless the action sets `x-better-supabase-allow-empty: true` or the
+* options set `allowEmpty`. The other codes are `overlay-invalid-target`,
+* `overlay-invalid-action`, `overlay-mixed-targets`,
+* `overlay-merge-conflict`, `overlay-copy-source`, `overlay-ref-unresolved`,
+* `overlay-version-feature`, `overlay-version-unsupported` and
+* `overlay-empty-action`.
+*
+* The result keeps the input's type; an overlay that changes the shape
+* needs the caller to narrow it.
+*
+* @example
+* const jsonpath = await loadJsonPath();
+* const { document, diagnostics } = applyOverlay(openapi, overlay, { jsonpath });
+*/
+function applyOverlay(document, overlay, options) {
+	return run(document, [overlay], options, () => "");
+}
+/**
+* Applies overlays in order, each to the result of the previous one, with a
+* single clone of the input. Diagnostic pointers start with the overlay's
+* index (`/1/actions/0`).
+*/
+function applyOverlays(document, overlays, options) {
+	return run(document, overlays, options, (index) => `/${index}`);
+}
+function run(document, overlays, options, prefix) {
+	const state = { document: structuredClone(document) };
+	const diagnostics = [];
+	for (const [index, overlay] of overlays.entries()) applyInPlace(state, overlay, options, {
+		prefix: prefix(index),
+		diagnostics
+	});
+	return {
+		document: state.document,
+		diagnostics
+	};
+}
+//#endregion
+//#region src/overlay/define.ts
+const isReference = (action) => "$ref" in action;
+const isPlain = (action) => !("$ref" in action);
+function defineOverlay(input) {
+	const { overlay: declared, ...rest } = input;
+	if (input.actions.length === 0) throw new TypeError("defineOverlay: an overlay needs at least one action");
+	const references = input.actions.filter(isReference);
+	const uses12 = input.components !== void 0 || input.$self !== void 0 || references.length > 0;
+	const version = declared ?? (uses12 ? "1.2.0" : "1.1.0");
+	if (version !== "1.2.0" && uses12) throw new TypeError(`defineOverlay: reusable actions, components and $self need overlay 1.2.0, not ${version}`);
+	if (version === "1.0.0" && input.actions.some((action) => !isReference(action) && action.copy !== void 0)) throw new TypeError("defineOverlay: copy needs overlay 1.1.0 or later");
+	for (const field of ["extends", "$self"]) if (input[field]?.includes("#")) throw new TypeError(`defineOverlay: ${field} must not contain a fragment`);
+	const reusables = input.components?.actions ?? {};
+	for (const reference of references) {
+		const name = decodePointerToken(reference.$ref.slice(21));
+		if (!Object.hasOwn(reusables, name)) throw new TypeError(`defineOverlay: ${reference.$ref} does not exist in components.actions`);
+	}
+	switch (version) {
+		case "1.2.0": return {
+			overlay: version,
+			...rest
+		};
+		case "1.1.0":
+		case "1.0.0": return {
+			overlay: version,
+			...rest,
+			actions: input.actions.filter(isPlain)
+		};
+		default: throw new TypeError(`defineOverlay: unsupported overlay ${String(version)}`);
+	}
+}
+/**
+* Turns an overlay into an equivalent Overlay 1.1 document for tools that do
+* not read 1.2: every reusable action reference becomes a plain action, and
+* `$self` and `components` are dropped. A reference that does not resolve is
+* left out and reported as `overlay-ref-unresolved`.
+*/
+function expandReusableActions(overlay) {
+	const reporter = {
+		prefix: "",
+		diagnostics: []
+	};
+	const actions = [];
+	const entries = overlay.actions;
+	for (const [index, entry] of entries.entries()) {
+		if (!isObject(entry)) continue;
+		const action = "$ref" in entry ? resolveReference(overlay, entry, `/actions/${index}`, reporter) : entry;
+		if (action && isAction(action)) actions.push(action);
+	}
+	const extensions = Object.fromEntries(Object.entries(overlay).filter(([key]) => key.startsWith("x-")));
+	return {
+		overlay: {
+			overlay: "1.1.0",
+			info: overlay.info,
+			...overlay.extends === void 0 ? {} : { extends: overlay.extends },
+			actions,
+			...extensions
+		},
+		diagnostics: reporter.diagnostics
+	};
+}
+//#endregion
+//#region src/overlay/diff.ts
+const kindOf = (value) => Array.isArray(value) ? "array" : isObject(value) ? "object" : "primitive";
+function equal(a, b) {
+	if (a === b) return true;
+	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, i) => equal(item, b[i]));
+	if (isObject(a) && isObject(b)) {
+		const keys = Object.keys(a);
+		return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && equal(a[key], b[key]));
+	}
+	return false;
+}
+/**
+* Appends the actions that turn the array `a` into `b`, or returns `false`
+* when the change needs the array replaced as a whole.
+*/
+function diffArray(path, a, b, ctx) {
+	if (b.length >= a.length && a.every((item, i) => equal(item, b[i]))) {
+		if (b.length > a.length) ctx.actions.push({
+			target: formatPath(path),
+			update: b.slice(a.length)
+		});
+		return true;
+	}
+	if (a.length !== b.length) return false;
+	const pending = [];
+	for (const [i, item] of a.entries()) {
+		const next = b[i];
+		if (equal(item, next)) continue;
+		if (!isObject(item) || !isObject(next)) return false;
+		diffObject([...path, i], item, next, {
+			...ctx,
+			actions: pending
+		});
+	}
+	ctx.actions.push(...pending);
+	return true;
+}
+function diffObject(path, a, b, ctx) {
+	const removals = [];
+	const added = {};
+	const nested = [];
+	const replace = (key, value) => {
+		removals.push({
+			target: formatPath([...path, key]),
+			remove: true
+		});
+		added[key] = value;
+	};
+	for (const key of Object.keys(a)) if (!Object.hasOwn(b, key)) removals.push({
+		target: formatPath([...path, key]),
+		remove: true
+	});
+	for (const [key, next] of Object.entries(b)) {
+		if (!Object.hasOwn(a, key)) {
+			added[key] = next;
+			continue;
+		}
+		const current = a[key];
+		if (equal(current, next)) continue;
+		if (kindOf(current) !== kindOf(next)) replace(key, next);
+		else if (isObject(current) && isObject(next)) diffObject([...path, key], current, next, {
+			...ctx,
+			actions: nested
+		});
+		else if (Array.isArray(current) && Array.isArray(next)) {
+			if (!diffArray([...path, key], current, next, {
+				...ctx,
+				actions: nested
+			})) replace(key, next);
+		} else if (ctx.replacePrimitives) nested.push({
+			target: formatPath([...path, key]),
+			update: next
+		});
+		else replace(key, next);
+	}
+	ctx.actions.push(...removals);
+	if (Object.keys(added).length > 0) ctx.actions.push({
+		target: formatPath(path),
+		update: added
+	});
+	ctx.actions.push(...nested);
+}
+/**
+* Writes the Overlay that turns `base` into `enriched`, so other tools can
+* reproduce what hooks and transforms changed. Targets use stable keys
+* (`$.paths['/customers'].get`); array indexes appear only inside arrays of
+* the same length.
+*
+* A deleted key becomes a `remove` action; added keys become one `update` on
+* their parent; a changed primitive becomes an `update` on it (1.1 and
+* later) or a `remove` and re-add (1.0). An array that only grew gets its new
+* items appended; any other array change replaces the array. Applying the
+* result to `base` gives a document equal to `enriched`, though replaced
+* keys move to the end of their object.
+*
+* Throws a `TypeError` when the roots are not both objects, or when the two
+* documents are equal (an overlay needs at least one action).
+*/
+function overlayFromDiff(base, enriched, options = {}) {
+	if (!isObject(base) || !isObject(enriched)) throw new TypeError("overlayFromDiff: both documents must be objects");
+	const version = options.version ?? "1.1.0";
+	const actions = [];
+	diffObject([], base, enriched, {
+		replacePrimitives: version !== "1.0.0",
+		actions
+	});
+	if (actions.length === 0) throw new TypeError("overlayFromDiff: the documents are equal, so there is nothing to write");
+	return {
+		overlay: version,
+		info: options.info ?? {
+			title: "better-supabase changes",
+			version: "1.0.0"
+		},
+		...options.extends === void 0 ? {} : { extends: options.extends },
+		actions
+	};
+}
+//#endregion
+//#region src/overlay/load.ts
+const isEngine = (value) => typeof value === "object" && value !== null && "paths" in value && typeof value.paths === "function";
+/**
+* Imports `jsonpath-rfc9535` on first use. The specifier is a variable so
+* bundlers leave the optional peer out of apps that pass their own engine.
+*/
+const importEngine = () => importOptionalPeer("jsonpath-rfc9535");
+async function load(importer) {
+	const module = await importer();
+	if (!isEngine(module)) throw new TypeError("better-supabase/overlay needs an RFC 9535 JSONPath engine: pnpm add jsonpath-rfc9535, or pass your own { paths(document, expression) }");
+	return module;
+}
+const cachedEngine = memoized(() => load(importEngine));
+/**
+* Loads the optional `jsonpath-rfc9535` peer, an RFC 9535 implementation
+* that passes the JSONPath Compliance Test Suite, for `applyOverlay`.
+* Rejects with an install message when the package is missing. The engine
+* is loaded once per module; `importer` replaces the import in tests.
+*/
+function loadJsonPath(importer) {
+	if (importer) return load(importer);
+	return cachedEngine();
+}
+//#endregion
+export { applyOverlay, applyOverlays, defineOverlay, expandReusableActions, loadJsonPath, overlayFromDiff };

package/dist/{plugin-FGY8UhYm.d.ts → plugin-CPK2HsbY.d.ts}

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
-import { w as ErrorMapper } from "./result-D7y2fT87.js";
-import { I as TableFlags, P as SchemaMeta, R as TableMeta, a as AnyModels } from "./types-6BdhkmZe.js";
-import { _ as MutationOp, g as MutationKind, h as MutationIntent, r as Executor, v as Operation } from "./executor-DvsBbNBS.js";
+import { w as ErrorMapper } from "./result-BchM1XZn.js";
+import { I as TableFlags, P as SchemaMeta, R as TableMeta, a as AnyModels } from "./types-CoE5Zwy4.js";
+import { _ as MutationOp, g as MutationKind, h as MutationIntent, r as Executor, v as Operation } from "./executor-Drzu3dBK.js";
 //#region src/core/plugin.d.ts
 /** Who is making the request. */
 interface Actor {
@@ -91,6 +91,39 @@ type ApplyOne<E, M extends AnyModels, T extends keyof M, K extends "methods" | "
 })[K] : unknown;
 /** True when table `T` has the flag set by codegen. */
 type HasFlag<M, T, F extends string> = M extends AnyModels ? T extends keyof M ? M[T]["Flags"] extends { readonly [K in F]: unknown; } ? true : false : false : false;
+/** A parameter a plugin adds to the operations of a table in the API spec. */
+interface DescribeParameter {
+  readonly name: string;
+  readonly in: "query" | "header" | "cookie";
+  readonly required?: boolean;
+  readonly description?: string;
+  /** JSON Schema 2020-12. */
+  readonly schema: Readonly<Record<string, unknown>>;
+}
+/**
+ * What `Plugin.describe` can change in the API model `defineApi` builds.
+ * Every method ignores tables and columns the API does not serve.
+ */
+interface PluginDescribeApi {
+  readonly schema: SchemaMeta;
+  /** Prefix of generated `x-` fields, e.g. `x-better-supabase-`. */
+  readonly extensionPrefix: string;
+  /** The served tables, with the names of their operations and actions. */
+  readonly resources: readonly {
+    readonly table: TableMeta;
+    readonly operations: readonly string[];
+  }[];
+  /** Adds a parameter to the table's operations, or to the named ones. */
+  addParameter(table: string, parameter: DescribeParameter, operations?: readonly string[]): void;
+  /**
+   * Marks a column `readOnly` in the table's schemas and drops it from the
+   * required fields of request bodies. `description` is used when the
+   * column has none.
+   */
+  markReadOnly(table: string, column: string, description?: string): void;
+  /** Deep-merges JSON Schema fields into the column's schemas. */
+  describeColumn(table: string, column: string, patch: Readonly<Record<string, unknown>>): void;
+}
 declare const PLUGIN_API_VERSION = 1;
 /**
  * Plugin API v1. Every hook is optional. Hooks run in `use()` order.
@@ -135,6 +168,12 @@ interface Plugin<Name extends string = string, Ext extends RepositoryExtension =
   readonly mapError?: ErrorMapper;
   /** `repository`: add methods to the repositories of matching tables. */
   readonly repository?: (api: RepositoryApi) => Readonly<Record<string, (...args: never[]) => unknown>> | undefined;
+  /**
+   * `spec`: describe what the plugin does to the served tables in the API
+   * model (`defineApi`, `createOpenApi`): parameters it reads, columns it
+   * manages. A throw is reported as `plugin-describe-failed`.
+   */
+  readonly describe?: (api: PluginDescribeApi) => void;
   /** Phantom carrying the repository extension type. */
   readonly "~ext"?: Ext;
 }

package/dist/plugins/actor/index.d.ts

@@ -1,4 +1,4 @@
-import { d as Plugin, m as RequestContext } from "../../plugin-FGY8UhYm.js";
+import { d as Plugin, m as RequestContext } from "../../plugin-CPK2HsbY.js";
 //#region src/plugins/actor/index.d.ts
 export interface ActorOptions {
   /** Custom actor id resolution. Defaults to `context.actor.id` for users and services. */

package/dist/plugins/actor/index.js

@@ -1,5 +1,5 @@
 import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
-import { a as insertsOnly, i as guardManaged, t as dbName, u as withDefault } from "../../shared-CxWmcyqB.js";
+import { a as insertsOnly, c as withDefault, i as guardManaged, t as dbName } from "../../shared-DHjhfRdV.js";
 //#region src/plugins/actor/index.ts
 function defaultActor(context) {
 	const actor = context.actor;

package/dist/plugins/rules/index.d.ts

@@ -1,5 +1,5 @@
-import { v as Operation } from "../../executor-DvsBbNBS.js";
-import { d as Plugin, p as RepositoryExtension } from "../../plugin-FGY8UhYm.js";
+import { v as Operation } from "../../executor-Drzu3dBK.js";
+import { d as Plugin, p as RepositoryExtension } from "../../plugin-CPK2HsbY.js";
 //#region src/plugins/rules/index.d.ts
 export type RuleLevel = "off" | "warn" | "error";
 /** A level, or a level with the rule's option: `['error', 500]`. */

package/dist/plugins/rules/index.js

@@ -1,5 +1,5 @@
 import { t as DbException } from "../../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../../errors-B11Duf73.js";
+import { n as dbError } from "../../errors-2M6CKMP4.js";
 import { t as lookupOf } from "../../lookup-BaP5bI27.js";
 import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
 import { t as simplify } from "../../simplify-DDO0j0LI.js";

package/dist/plugins/soft-delete/index.d.ts

@@ -1,6 +1,6 @@
-import { t as AsyncResult } from "../../result-D7y2fT87.js";
-import { E as PrimaryKeyValue } from "../../types-6BdhkmZe.js";
-import { d as Plugin, o as HasFlag, p as RepositoryExtension } from "../../plugin-FGY8UhYm.js";
+import { t as AsyncResult } from "../../result-BchM1XZn.js";
+import { E as PrimaryKeyValue } from "../../types-CoE5Zwy4.js";
+import { d as Plugin, o as HasFlag, p as RepositoryExtension } from "../../plugin-CPK2HsbY.js";
 //#region src/plugins/soft-delete/index.d.ts
 export interface SoftDeleteFindArgs {
   /** Include soft-deleted rows of the queried table. */