@adrdp/pg-rest 0.1.3 → 0.2.0

package/dist/schema-BhF_TQdX.js

@@ -0,0 +1,669 @@
+//#region src/errors.ts
+/**
+* Thrown by the pure parts of the library (parsers, SQL builders). It is
+* converted into an {@link ApiError} at the request boundary.
+*/
+var PgRestError = class extends Error {
+	constructor(status, code, message, details = null, hint = null, headers = {}) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.details = details;
+		this.hint = hint;
+		this.headers = headers;
+		this.name = "PgRestError";
+	}
+	get body() {
+		return {
+			code: this.code,
+			message: this.message,
+			details: this.details,
+			hint: this.hint
+		};
+	}
+};
+/**
+* A one-line summary for stack traces and logs. The wire format is `body`, which this never
+* touches: PostgREST clients read `message` from the JSON, while a program that catches the
+* error reads it from `Error.message` and wants the code and hint with it.
+*/
+const describe$1 = (b) => [
+	`${b.code}:`,
+	b.message,
+	b.details ? `(${b.details})` : "",
+	b.hint ? `hint: ${b.hint}` : ""
+].filter(Boolean).join(" ");
+/** An error that has already been mapped to an HTTP response. */
+var ApiError = class extends Error {
+	_tag = "ApiError";
+	status;
+	body;
+	headers;
+	constructor(fields) {
+		super(describe$1(fields.body));
+		this.name = "ApiError";
+		this.status = fields.status;
+		this.body = fields.body;
+		this.headers = fields.headers;
+	}
+};
+/** Normalized error thrown by a {@link DbAdapter}. */
+var DbQueryError = class extends Error {
+	constructor(sqlState, message, detail, hint) {
+		super(message);
+		this.sqlState = sqlState;
+		this.detail = detail;
+		this.hint = hint;
+		this.name = "DbQueryError";
+	}
+};
+const SQLSTATE = /^[0-9A-Z]{5}$/;
+/**
+* Recognise a database error thrown by any driver and turn it into a {@link DbQueryError}.
+* Drivers put the SQLSTATE in different places: `code` (node-postgres, postgres.js, PGlite),
+* `errno` (Bun.sql) or `sqlState`. Anything else (connection errors, bugs) is returned unchanged.
+*/
+const normalizeDbError = (e) => {
+	if (e instanceof DbQueryError || !e || typeof e !== "object") return e;
+	const x = e;
+	for (const key of [
+		"sqlState",
+		"code",
+		"errno"
+	]) {
+		const v = x[key];
+		if (typeof v === "string" && SQLSTATE.test(v)) return new DbQueryError(v, String(x["message"] ?? ""), typeof x["detail"] === "string" ? x["detail"] : void 0, typeof x["hint"] === "string" ? x["hint"] : void 0);
+	}
+	return e;
+};
+/**
+* SQLSTATE → HTTP status, following the PostgREST 16 table
+* (https://docs.postgrest.org/en/v16/references/errors.html).
+*/
+const statusFromSqlState = (state, role, anon) => {
+	if (/^PT\d{3}$/.test(state)) return Number(state.slice(2));
+	switch (state) {
+		case "23503":
+		case "23505": return 409;
+		case "25006": return 405;
+		case "42883":
+		case "42P01": return 404;
+		case "42P17": return 500;
+		case "42501": return role === anon ? 401 : 403;
+		case "P0001": return 400;
+		case "53400": return 500;
+	}
+	switch (state.slice(0, 2)) {
+		case "08":
+		case "53": return 503;
+		case "0L":
+		case "0P":
+		case "28": return 403;
+		case "09":
+		case "25":
+		case "2D":
+		case "38":
+		case "39":
+		case "3B":
+		case "40":
+		case "54":
+		case "55":
+		case "57":
+		case "58":
+		case "F0":
+		case "HV":
+		case "P0":
+		case "XX": return 500;
+		default: return 400;
+	}
+};
+/**
+* Map a Postgres error to a PostgREST-style API error.
+*
+* Supports PostgREST's custom error conventions:
+* - `RAISE ... USING ERRCODE = 'PTxyz'` → HTTP status xyz
+* - `RAISE SQLSTATE 'PGRST'` with a JSON message/detail
+*/
+const dbErrorToApiError = (err, role, anonymousRole) => {
+	if (err.sqlState === "PGRST") try {
+		const msg = JSON.parse(err.message);
+		const det = err.detail ? JSON.parse(err.detail) : {};
+		return new ApiError({
+			status: det.status ?? 500,
+			headers: det.headers ?? {},
+			body: {
+				code: msg.code ?? "PGRST",
+				message: msg.message ?? "",
+				details: msg.details ?? null,
+				hint: msg.hint ?? null
+			}
+		});
+	} catch {
+		return new ApiError({
+			status: 500,
+			headers: {},
+			body: {
+				code: "PGRST121",
+				message: "Could not parse JSON in the RAISE error",
+				details: err.message,
+				hint: null
+			}
+		});
+	}
+	return new ApiError({
+		status: statusFromSqlState(err.sqlState, role, anonymousRole),
+		headers: {},
+		body: {
+			code: err.sqlState,
+			message: err.message,
+			details: err.detail ?? null,
+			hint: err.hint ?? null
+		}
+	});
+};
+
+//#endregion
+//#region src/quote.ts
+/** Quote an SQL identifier: `a"b` → `"a""b"`. */
+const quoteIdent = (name) => {
+	if (name.includes("\0")) throw new PgRestError(400, "PGRST100", "Invalid identifier", "contains a NUL byte");
+	return `"${name.replace(/"/g, "\"\"")}"`;
+};
+const quoteQualified = (schema, name) => `${quoteIdent(schema)}.${quoteIdent(name)}`;
+/**
+* Escape a string as an SQL literal of *unknown* type, so Postgres infers the
+* type from context (`int_col = '5'` works). Mirrors `pg.escapeLiteral`.
+*
+* We inline literals (like PostgREST does) instead of binding parameters
+* because some drivers (Bun.sql) re-encode string parameters as JSON when the
+* inferred type is json/jsonb.
+*/
+const literal = (value) => {
+	if (value.includes("\0")) throw new PgRestError(400, "PGRST100", "Invalid value", "contains a NUL byte");
+	let out = `'${value.replace(/'/g, "''")}'`;
+	if (out.includes("\\")) out = `E${out.replace(/\\/g, "\\\\")}`;
+	return out;
+};
+const ID = "[A-Za-z_][A-Za-z0-9_]*";
+const TYPE_RE = new RegExp(`^(?:(?:double precision|character varying|national character varying|national character|bit varying|timestamp(?:\\(\\d+\\))? with(?:out)? time zone|time(?:\\(\\d+\\))? with(?:out)? time zone)|${ID}(?:\\.${ID})?)(?:\\(\\s*\\d+(?:\\s*,\\s*\\d+)?\\s*\\))?(?:\\[\\])*$`, "i");
+/** Validate a user-supplied cast target (`::type`) and return it verbatim. */
+const safeType = (type) => {
+	const t = type.trim();
+	if (t.length > 100 || !TYPE_RE.test(t)) throw new PgRestError(400, "PGRST100", "Invalid type in cast", `"${type}" is not an allowed cast target`);
+	return t;
+};
+
+//#endregion
+//#region src/schema.ts
+const relKey = (schema, name) => `${schema}.${name}`;
+const kindOf = (k) => k === "v" ? "view" : k === "m" ? "matview" : k === "f" ? "foreign" : k === "p" ? "partitioned" : "table";
+const schemaList = (schemas) => `ARRAY[${schemas.map(literal).join(",")}]::text[]`;
+const asJson = (inner) => `SELECT coalesce(json_agg(r), '[]'::json)::text AS j FROM (${inner}) r`;
+const run = async (db, sql) => {
+	const j = (await db.query(asJson(sql)))[0]?.["j"];
+	return JSON.parse(typeof j === "string" ? j : "[]");
+};
+/**
+* Foreign keys seen through views: a view that exposes the columns of a foreign key (directly, or
+* through other views) gets the same relationships as the table, towards tables and views alike.
+*/
+const viewForeignKeys = (fks, rows) => {
+	const viewCols = /* @__PURE__ */ new Map();
+	for (const r of rows) {
+		const key = relKey(r.vschema, r.vname);
+		const m = viewCols.get(key) ?? /* @__PURE__ */ new Map();
+		m.set(r.vcol, {
+			key: relKey(r.tschema, r.tname),
+			col: r.tcol
+		});
+		viewCols.set(key, m);
+	}
+	const base = (key, col, depth = 0) => {
+		const next = viewCols.get(key)?.get(col);
+		return next && depth < 16 ? base(next.key, next.col, depth + 1) : {
+			key,
+			col
+		};
+	};
+	/** Every view that exposes all of `cols` of table `tableKey`, with the view-side column names. */
+	const exposing = (tableKey, cols) => {
+		const out$1 = [];
+		for (const [vkey, m] of viewCols) {
+			const names = [];
+			for (const c of cols) {
+				let found;
+				for (const [vcol] of m) {
+					const b = base(vkey, vcol);
+					if (b.key === tableKey && b.col === c) {
+						found = vcol;
+						break;
+					}
+				}
+				if (found === void 0) break;
+				names.push(found);
+			}
+			if (names.length === cols.length) {
+				const [schema, ...rest] = vkey.split(".");
+				out$1.push({
+					schema,
+					name: rest.join("."),
+					cols: names
+				});
+			}
+		}
+		return out$1;
+	};
+	const out = [];
+	for (const fk of fks) {
+		const sources = [{
+			schema: fk.schema,
+			name: fk.table,
+			cols: [...fk.cols]
+		}, ...exposing(relKey(fk.schema, fk.table), fk.cols)];
+		const targets = [{
+			schema: fk.fschema,
+			name: fk.ftable,
+			cols: [...fk.fcols]
+		}, ...exposing(relKey(fk.fschema, fk.ftable), fk.fcols)];
+		for (const [i, s] of sources.entries()) for (const [j, t] of targets.entries()) {
+			if (i === 0 && j === 0) continue;
+			out.push({
+				name: fk.name,
+				schema: s.schema,
+				table: s.name,
+				cols: s.cols,
+				fschema: t.schema,
+				ftable: t.name,
+				fcols: t.cols
+			});
+		}
+	}
+	return out;
+};
+/** Read the catalog and build a fresh {@link SchemaCache}. */
+const introspect = async (db, schemas) => {
+	const S = schemaList(schemas);
+	const relRows = await run(db, `SELECT n.nspname AS schema, c.relname AS name, c.relkind::text AS kind,
+            obj_description(c.oid, 'pg_class') AS comment,
+            pg_relation_is_updatable(c.oid, true) AS bits
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = ANY(${S})
+        AND c.relkind IN ('r','v','m','f','p')
+        AND NOT c.relispartition
+      ORDER BY 1, 2`);
+	const colRows = await run(db, `SELECT n.nspname AS schema, c.relname AS "table", a.attname AS name,
+            format_type(a.atttypid, a.atttypmod) AS type,
+            (SELECT json_agg(e.enumlabel ORDER BY e.enumsortorder) FROM pg_enum e
+              WHERE e.enumtypid = CASE WHEN bt.typtype = 'e' THEN bt.oid
+                                       WHEN et.typtype = 'e' THEN et.oid END) AS enum_labels,
+            NOT a.attnotnull AS nullable,
+            (a.atthasdef OR a.attidentity <> '') AS has_default,
+            pg_get_expr(d.adbin, d.adrelid) AS default_expr,
+            (a.attgenerated <> '') AS generated,
+            a.attidentity::text AS identity,
+            col_description(c.oid, a.attnum) AS comment,
+            a.attnum AS pos
+       FROM pg_attribute a
+       JOIN pg_class c ON c.oid = a.attrelid
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+       LEFT JOIN pg_type bt ON bt.oid = a.atttypid
+       LEFT JOIN pg_type et ON et.oid = bt.typelem
+      WHERE n.nspname = ANY(${S})
+        AND c.relkind IN ('r','v','m','f','p')
+        AND NOT c.relispartition
+        AND a.attnum > 0 AND NOT a.attisdropped
+      ORDER BY 1, 2, a.attnum`);
+	const conRows = await run(db, `SELECT con.conname AS name, con.contype::text AS type,
+            ns.nspname AS schema, rel.relname AS "table",
+            (SELECT json_agg(a.attname ORDER BY k.ord)
+               FROM unnest(con.conkey) WITH ORDINALITY k(attnum, ord)
+               JOIN pg_attribute a ON a.attrelid = con.conrelid AND a.attnum = k.attnum) AS cols,
+            fns.nspname AS fschema, frel.relname AS ftable,
+            (SELECT json_agg(a.attname ORDER BY k.ord)
+               FROM unnest(con.confkey) WITH ORDINALITY k(attnum, ord)
+               JOIN pg_attribute a ON a.attrelid = con.confrelid AND a.attnum = k.attnum) AS fcols
+       FROM pg_constraint con
+       JOIN pg_class rel ON rel.oid = con.conrelid
+       JOIN pg_namespace ns ON ns.oid = rel.relnamespace
+       LEFT JOIN pg_class frel ON frel.oid = con.confrelid
+       LEFT JOIN pg_namespace fns ON fns.oid = frel.relnamespace
+      WHERE con.contype IN ('p','u','f')
+        AND con.conparentid = 0
+        AND (ns.nspname = ANY(${S}) OR fns.nspname = ANY(${S}))`);
+	const viewRows = await run(db, `SELECT DISTINCT ON (vc.oid, m.x[1]::int)
+            vn.nspname AS vschema, vc.relname AS vname, va.attname AS vcol,
+            tn.nspname AS tschema, tc.relname AS tname, ta.attname AS tcol
+       FROM pg_rewrite rw
+       JOIN pg_class vc ON vc.oid = rw.ev_class AND vc.relkind IN ('v','m')
+       JOIN pg_namespace vn ON vn.oid = vc.relnamespace
+       CROSS JOIN LATERAL regexp_matches(rw.ev_action::text,
+            ':resno (\\d+) :resname [^:]* :ressortgroupref \\d+ :resorigtbl (\\d+) :resorigcol (\\d+) :resjunk false', 'g')
+            WITH ORDINALITY AS m(x, ord)
+       JOIN pg_attribute va ON va.attrelid = vc.oid AND va.attnum = m.x[1]::int AND NOT va.attisdropped
+       JOIN pg_class tc ON tc.oid = m.x[2]::oid
+       JOIN pg_namespace tn ON tn.oid = tc.relnamespace
+       JOIN pg_attribute ta ON ta.attrelid = tc.oid AND ta.attnum = m.x[3]::int
+      WHERE vn.nspname = ANY(${S}) AND rw.rulename = '_RETURN' AND m.x[2]::oid <> 0
+      ORDER BY vc.oid, m.x[1]::int, m.ord DESC`);
+	const fnRows = await run(db, `SELECT n.nspname AS schema, p.proname AS name,
+            p.proretset AS returns_set, p.provolatile::text AS volatility,
+            format_type(p.prorettype, NULL) AS return_type,
+            (SELECT json_agg(e.enumlabel ORDER BY e.enumsortorder) FROM pg_enum e
+               WHERE e.enumtypid = CASE WHEN rt.typtype = 'e' THEN rt.oid
+                                        WHEN ret_el.typtype = 'e' THEN ret_el.oid END) AS return_enum,
+            rt.typtype::text AS return_typtype,
+            coalesce(p.proargmodes && ARRAY['o','b','t']::"char"[], false) AS has_out,
+            p.pronargdefaults AS n_defaults,
+            obj_description(p.oid, 'pg_proc') AS comment,
+            p.prorows::float8 AS rows,
+            CASE WHEN rt.typtype = 'd' AND rt.typname LIKE '%/%'
+                 THEN json_build_object('name', rt.typname, 'bytea', rt.typbasetype = 'bytea'::regtype) END AS ret_media,
+            (SELECT json_build_object('schema', n2.nspname, 'name', c2.relname)
+               FROM pg_type t2 JOIN pg_class c2 ON c2.oid = t2.typrelid JOIN pg_namespace n2 ON n2.oid = c2.relnamespace
+              WHERE p.pronargs = 1 AND t2.oid = p.proargtypes[0] AND c2.relkind IN ('r','v','m','f','p')) AS arg_rel,
+            (SELECT json_build_object('schema', n2.nspname, 'name', c2.relname)
+               FROM pg_type t2 JOIN pg_class c2 ON c2.oid = t2.typrelid JOIN pg_namespace n2 ON n2.oid = c2.relnamespace
+              WHERE t2.oid = p.prorettype AND c2.relkind IN ('r','v','m','f','p')) AS ret_rel,
+            (SELECT coalesce(json_agg(json_build_object(
+                       'name', coalesce(p.proargnames[t.i], ''),
+                       'type', format_type(t.typ, NULL),
+                       'enum', (SELECT json_agg(e.enumlabel ORDER BY e.enumsortorder) FROM pg_enum e
+                                 WHERE e.enumtypid = (SELECT CASE WHEN at.typtype = 'e' THEN at.oid
+                                                                  WHEN ael.typtype = 'e' THEN ael.oid END
+                                                        FROM pg_type at
+                                                        LEFT JOIN pg_type ael ON ael.oid = at.typelem
+                                                       WHERE at.oid = t.typ)),
+                       'mode', coalesce(p.proargmodes[t.i]::text, 'i')) ORDER BY t.i), '[]'::json)
+               FROM unnest(coalesce(p.proallargtypes, string_to_array(p.proargtypes::text, ' ')::oid[]))
+                    WITH ORDINALITY AS t(typ, i)
+              WHERE coalesce(p.proargmodes[t.i]::text, 'i') IN ('i','b','v')) AS args
+       FROM pg_proc p
+       JOIN pg_namespace n ON n.oid = p.pronamespace
+       JOIN pg_type rt ON rt.oid = p.prorettype
+       LEFT JOIN pg_type ret_el ON ret_el.oid = rt.typelem
+      WHERE n.nspname = ANY(${S})
+        AND p.prokind = 'f'
+        AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = p.oid AND d.deptype = 'e')
+      -- overloads share a name, so the signature breaks the tie: without it the order is whatever
+      -- the catalog scan returns, which differs between a database and a copy of it, and the
+      -- generated types churn
+      ORDER BY 1, 2, pg_get_function_identity_arguments(p.oid)`);
+	const mediaHandlers = (await run(db, `SELECT n.nspname AS schema, p.proname AS name,
+            (SELECT json_build_object('schema', n2.nspname, 'name', c2.relname)
+               FROM pg_type t2 JOIN pg_class c2 ON c2.oid = t2.typrelid JOIN pg_namespace n2 ON n2.oid = c2.relnamespace
+              WHERE t2.oid = p.proargtypes[0] AND c2.relkind IN ('r','v','m','f','p')) AS arg_rel,
+            rt.typbasetype = 'bytea'::regtype AS bytea
+       FROM pg_proc p
+       JOIN pg_namespace n ON n.oid = p.pronamespace
+       JOIN pg_type rt ON rt.oid = p.prorettype AND rt.typtype = 'd'
+      WHERE n.nspname = ANY(${S})
+        AND p.prokind = 'a' AND p.pronargs = 1 AND p.proname LIKE '%/%'
+        AND (p.proargtypes[0] = 'anyelement'::regtype
+             OR EXISTS (SELECT 1 FROM pg_type t3 JOIN pg_class c3 ON c3.oid = t3.typrelid WHERE t3.oid = p.proargtypes[0]))
+      ORDER BY 1, 2`)).map((h) => ({
+		schema: h.schema,
+		mediaType: h.name.toLowerCase(),
+		...h.arg_rel ? { argRelation: h.arg_rel } : {},
+		bytea: h.bytea
+	}));
+	const pk = /* @__PURE__ */ new Map();
+	const uniques = /* @__PURE__ */ new Map();
+	const foreignKeys = [];
+	for (const c of conRows) {
+		const key = relKey(c.schema, c.table);
+		if (c.type === "p") pk.set(key, c.cols);
+		else if (c.type === "u") uniques.set(key, [...uniques.get(key) ?? [], c.cols]);
+		else if (c.type === "f" && c.fschema && c.ftable && c.fcols) foreignKeys.push({
+			name: c.name,
+			schema: c.schema,
+			table: c.table,
+			cols: c.cols,
+			fschema: c.fschema,
+			ftable: c.ftable,
+			fcols: c.fcols
+		});
+	}
+	foreignKeys.push(...viewForeignKeys(foreignKeys, viewRows));
+	const viewSource = /* @__PURE__ */ new Map();
+	{
+		const direct = /* @__PURE__ */ new Map();
+		for (const r of viewRows) direct.set(`${relKey(r.vschema, r.vname)}.${r.vcol}`, {
+			key: relKey(r.tschema, r.tname),
+			col: r.tcol
+		});
+		for (const [from, first] of direct) {
+			let at = first;
+			for (let depth = 0; depth < 16; depth++) {
+				const next = direct.get(`${at.key}.${at.col}`);
+				if (!next) break;
+				at = next;
+			}
+			const [schema, ...rest] = at.key.split(".");
+			viewSource.set(from, {
+				schema,
+				table: rest.join("."),
+				column: at.col
+			});
+		}
+	}
+	const colsByRel = /* @__PURE__ */ new Map();
+	for (const c of colRows) {
+		const key = relKey(c.schema, c.table);
+		const list = colsByRel.get(key) ?? [];
+		const source = viewSource.get(`${key}.${c.name}`);
+		list.push({
+			name: c.name,
+			type: c.type,
+			...c.enum_labels ? { enumLabels: c.enum_labels } : {},
+			...source ? { source } : {},
+			nullable: c.nullable,
+			hasDefault: c.has_default,
+			defaultExpr: c.default_expr,
+			generated: c.generated,
+			...c.identity === "a" ? { identity: "always" } : c.identity === "d" ? { identity: "by-default" } : {},
+			comment: c.comment,
+			position: c.pos
+		});
+		colsByRel.set(key, list);
+	}
+	const relations = /* @__PURE__ */ new Map();
+	for (const r of relRows) {
+		const key = relKey(r.schema, r.name);
+		relations.set(key, {
+			schema: r.schema,
+			name: r.name,
+			kind: kindOf(r.kind),
+			columns: colsByRel.get(key) ?? [],
+			pk: pk.get(key) ?? [],
+			uniques: uniques.get(key) ?? [],
+			insertable: (r.bits & 8) === 8,
+			updatable: (r.bits & 4) === 4,
+			deletable: (r.bits & 16) === 16,
+			comment: r.comment
+		});
+	}
+	const functions = /* @__PURE__ */ new Map();
+	for (const f of fnRows) {
+		const nDefaults = f.n_defaults;
+		const args = f.args.map((a, i) => ({
+			name: a.name,
+			type: a.type,
+			hasDefault: i >= f.args.length - nDefaults,
+			variadic: a.mode === "v",
+			...a.enum ? { enumLabels: a.enum } : {}
+		}));
+		const def = {
+			schema: f.schema,
+			name: f.name,
+			args,
+			returnType: f.return_type,
+			...f.return_enum ? { returnEnumLabels: f.return_enum } : {},
+			returnsSet: f.returns_set,
+			returnsComposite: f.has_out || f.return_typtype === "c" || f.return_type === "record",
+			returnsVoid: f.return_type === "void",
+			volatility: f.volatility === "i" ? "immutable" : f.volatility === "s" ? "stable" : "volatile",
+			comment: f.comment,
+			rows: f.rows,
+			...f.arg_rel ? { argRelation: f.arg_rel } : {},
+			...f.ret_rel ? { returnRelation: f.ret_rel } : {},
+			...f.ret_media && !f.returns_set ? { returnMediaType: f.ret_media } : {}
+		};
+		const key = relKey(f.schema, f.name);
+		functions.set(key, [...functions.get(key) ?? [], def]);
+	}
+	return {
+		schemas,
+		relations,
+		foreignKeys,
+		functions,
+		mediaHandlers
+	};
+};
+const sameCols = (a, b) => a.length === b.length && a.every((c) => b.includes(c));
+const isUnique = (rel, cols) => rel.pk.length > 0 && sameCols(rel.pk, cols) || rel.uniques.some((u) => sameCols(u, cols));
+const describe = (r) => {
+	const j = r.junction;
+	if (j) return `'${j.relation.name}' using '${j.fkFrom.name}' and '${j.fkTo.name}' (many-to-many)`;
+	if (r.computed) return `'${r.computed.name}' (computed, ${r.kind === "m2o" ? "many-to-one" : "one-to-many"})`;
+	return `'${r.fk.name}' (${r.kind === "m2o" ? "many-to-one" : r.kind === "o2o" ? "one-to-one" : "one-to-many"}) on ${r.fk.table}(${r.fk.cols.join(",")})`;
+};
+/** Find the relationships between `from` and the table/view named `target`. */
+const findRelationships = (cache, from, target, hint) => {
+	const out = [];
+	const rel = (schema, name) => cache.relations.get(relKey(schema, name));
+	for (const fk of cache.foreignKeys) {
+		const selfReference = fk.schema === fk.fschema && fk.table === fk.ftable;
+		if (fk.schema === from.schema && fk.table === from.name && fk.ftable === target && !selfReference) {
+			const to = rel(fk.fschema, fk.ftable);
+			if (to) out.push({
+				kind: "m2o",
+				from,
+				to,
+				fromCols: fk.cols,
+				toCols: fk.fcols,
+				fk
+			});
+		}
+		if (fk.schema === from.schema && fk.table === from.name && fk.cols.length === 1 && fk.cols[0] === target) {
+			const to = rel(fk.fschema, fk.ftable);
+			if (to) out.push({
+				kind: "m2o",
+				from,
+				to,
+				fromCols: fk.cols,
+				toCols: fk.fcols,
+				fk
+			});
+		}
+		if (fk.fschema === from.schema && fk.ftable === from.name && fk.table === target) {
+			const to = rel(fk.schema, fk.table);
+			if (to) out.push({
+				kind: isUnique(to, fk.cols) ? "o2o" : "o2m",
+				from,
+				to,
+				fromCols: fk.fcols,
+				toCols: fk.cols,
+				fk
+			});
+		}
+	}
+	for (const f of cache.functions.get(relKey(from.schema, target)) ?? []) {
+		if (f.argRelation?.schema !== from.schema || f.argRelation.name !== from.name || !f.returnRelation) continue;
+		const to = rel(f.returnRelation.schema, f.returnRelation.name);
+		if (!to) continue;
+		const fk = {
+			name: f.name,
+			schema: from.schema,
+			table: from.name,
+			cols: [],
+			fschema: to.schema,
+			ftable: to.name,
+			fcols: []
+		};
+		out.push({
+			kind: !f.returnsSet || f.rows === 1 ? "m2o" : "o2m",
+			from,
+			to,
+			fromCols: [],
+			toCols: [],
+			fk,
+			computed: f
+		});
+	}
+	for (const fk1 of cache.foreignKeys) {
+		if (fk1.fschema !== from.schema || fk1.ftable !== from.name) continue;
+		const junction = rel(fk1.schema, fk1.table);
+		if (!junction) continue;
+		for (const fk2 of cache.foreignKeys) {
+			if (fk2 === fk1) continue;
+			if (fk2.schema !== fk1.schema || fk2.table !== fk1.table) continue;
+			if (fk2.ftable !== target) continue;
+			const to = rel(fk2.fschema, fk2.ftable);
+			if (!to) continue;
+			out.push({
+				kind: "m2m",
+				from,
+				to,
+				fromCols: fk1.fcols,
+				toCols: fk2.fcols,
+				fk: fk1,
+				junction: {
+					relation: junction,
+					fkFrom: fk1,
+					fkTo: fk2
+				}
+			});
+		}
+	}
+	if (!hint) return out;
+	return out.filter((r) => {
+		if (r.junction) return r.junction.relation.name === hint || r.junction.fkFrom.name === hint || r.junction.fkTo.name === hint;
+		return r.fk.name === hint || r.fk.cols.includes(hint) || r.fk.fcols.includes(hint);
+	});
+};
+/**
+* Resolve exactly one relationship or throw PostgREST-style PGRST200/PGRST201.
+* `target` may also be a table that is not related at all (→ PGRST200).
+*/
+const resolveRelationship = (cache, from, target, hint) => {
+	const found = findRelationships(cache, from, target, hint);
+	if (found.length === 1) return found[0];
+	if (found.length === 0) throw new PgRestError(400, "PGRST200", `Could not find a relationship between '${from.name}' and '${target}' in the schema cache`, hint ? `Searched for a foreign key relationship between '${from.name}' and '${target}' using the hint '${hint}' in the schema '${from.schema}', but no matches were found.` : `Searched for a foreign key relationship between '${from.name}' and '${target}' in the schema '${from.schema}', but no matches were found.`, null);
+	throw new PgRestError(300, "PGRST201", `Could not embed because more than one relationship was found for '${from.name}' and '${target}'`, JSON.stringify(found.map((r) => describe(r))), `Try changing '${target}' to one of the following: ${found.map((r) => `'${target}!${r.junction ? r.junction.relation.name : r.fk.name}'`).join(", ")}. Find the desired relationship in the 'details' key.`);
+};
+/** Look up a relation by (optional) schema and name, or throw PGRST205. */
+const getRelation = (cache, schema, name) => {
+	const rel = cache.relations.get(relKey(schema, name));
+	if (!rel) throw new PgRestError(404, "PGRST205", `Could not find the table '${schema}.${name}' in the schema cache`, null, suggest(cache, schema, name));
+	return rel;
+};
+const suggest = (cache, schema, name) => {
+	let best;
+	for (const r of cache.relations.values()) {
+		if (r.schema !== schema) continue;
+		const d = levenshtein(name.toLowerCase(), r.name.toLowerCase());
+		if (d <= Math.max(1, Math.floor(name.length / 4)) && (!best || d < best.d)) best = {
+			name: r.name,
+			d
+		};
+	}
+	return best ? `Perhaps you meant the table '${schema}.${best.name}'` : null;
+};
+const levenshtein = (a, b) => {
+	const dp = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i++) {
+		let prev = dp[0];
+		dp[0] = i;
+		for (let j = 1; j <= b.length; j++) {
+			const tmp = dp[j];
+			dp[j] = Math.min(dp[j] + 1, dp[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+			prev = tmp;
+		}
+	}
+	return dp[b.length];
+};
+
+//#endregion
+export { relKey as a, quoteIdent as c, ApiError as d, DbQueryError as f, normalizeDbError as h, levenshtein as i, quoteQualified as l, dbErrorToApiError as m, getRelation as n, resolveRelationship as o, PgRestError as p, introspect as r, literal as s, findRelationships as t, safeType as u };