@adrdp/pg-rest 0.1.3 → 0.2.0

package/dist/index.js

@@ -1,157 +1,5 @@
-//#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
-		};
-	}
-};
-/** An error that has already been mapped to an HTTP response. */
-var ApiError = class extends Error {
-	_tag = "ApiError";
-	status;
-	body;
-	headers;
-	constructor(fields) {
-		super(fields.body.message);
-		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
-		}
-	});
-};
+import { a as relKey, c as quoteIdent, d as ApiError, f as DbQueryError, h as normalizeDbError, i as levenshtein, l as quoteQualified, m as dbErrorToApiError, n as getRelation, o as resolveRelationship, p as PgRestError, r as introspect, s as literal, u as safeType } from "./schema-BhF_TQdX.js";
 
-//#endregion
 //#region src/parse/field.ts
 const parseError = (message, details) => new PgRestError(400, "PGRST100", message, details ?? null);
 /**
@@ -246,37 +94,6 @@ const parseField = (input) => {
 	};
 };
 
-//#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/parse/select.ts
 const AGGREGATES = new Set([
@@ -931,8 +748,8 @@ const parseList = (raw, where) => {
 */
 const parseOperatorExpr = (field$1, expr, unquoteValue = false) => {
 	if (!unquoteValue) {
-		const bad = checkFilter(expr);
-		if (bad) throw bad;
+		const bad$1 = checkFilter(expr);
+		if (bad$1) throw bad$1;
 	}
 	let rest = expr;
 	let negate = false;
@@ -1002,8 +819,8 @@ const parseLogic = (op, negate, value) => {
 	};
 };
 const parseOrder = (input) => {
-	const bad = checkOrder(input);
-	if (bad) throw bad;
+	const bad$1 = checkOrder(input);
+	if (bad$1) throw bad$1;
 	return parseOrderTerms(input);
 };
 const parseOrderTerms = (input) => splitTopLevel(input, ",").map((raw) => {
@@ -1388,431 +1205,6 @@ const parseCsv = (text) => {
 	return data.filter((r) => !(r.length === 1 && r[0] === "")).map((r) => Object.fromEntries(header.map((h, i) => [h, r[i] === "" || r[i] === void 0 ? null : r[i]])));
 };
 
-//#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,
-            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,
-            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
-      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,
-            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),
-                       '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
-      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')
-      ORDER BY 1, 2`);
-	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 colsByRel = /* @__PURE__ */ new Map();
-	for (const c of colRows) {
-		const key = relKey(c.schema, c.table);
-		const list = colsByRel.get(key) ?? [];
-		list.push({
-			name: c.name,
-			type: c.type,
-			nullable: c.nullable,
-			hasDefault: c.has_default,
-			defaultExpr: c.default_expr,
-			generated: c.generated,
-			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"
-		}));
-		const def = {
-			schema: f.schema,
-			name: f.name,
-			args,
-			returnType: f.return_type,
-			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
 //#region src/media.ts
 const choiceFor = (mediaType, bytea, extra) => ({
@@ -2753,6 +2145,12 @@ const buildDelete = (o) => {
 
 //#endregion
 //#region src/core.ts
+/** The bare keys of a query string: `?a&b=1` -> `{a}`. They are arguments, never filters. */
+const bareKeys = (search) => {
+	const out = /* @__PURE__ */ new Set();
+	for (const kv of search.slice(1).split("&")) if (kv !== "" && !kv.includes("=")) out.add(decodeURIComponent(kv));
+	return out;
+};
 /** Statement options that depend on the negotiated output format. */
 const formatOptions = (format) => ({
 	csv: format.kind === "csv",
@@ -2760,11 +2158,17 @@ const formatOptions = (format) => ({
 	handler: format.kind === "handler" ? format.choice : void 0
 });
 const JSON_CT = "application/json; charset=utf-8";
-const readSchema = (env, request, method) => {
-	const wanted = (method === "GET" || method === "HEAD" ? request.headers.get("accept-profile") : request.headers.get("content-profile"))?.trim();
-	if (!wanted) return env.config.schemas[0];
-	if (!env.config.schemas.includes(wanted)) throw new PgRestError(406, "PGRST106", `Invalid schema: ${wanted}`, null, `Only the following schemas are exposed: ${env.config.schemas.join(", ")}`);
-	return wanted;
+/** The schema a call runs against: the one it asks for, if exposed, else the default one. */
+const useSchema = (env, wanted) => {
+	const name = wanted?.trim();
+	if (!name) return env.config.schemas[0];
+	if (!env.config.schemas.includes(name)) throw new PgRestError(406, "PGRST106", `Invalid schema: ${name}`, null, `Only the following schemas are exposed: ${env.config.schemas.join(", ")}`);
+	return name;
+};
+const readSchema = (env, request, method) => useSchema(env, method === "GET" || method === "HEAD" ? request.headers.get("accept-profile") : request.headers.get("content-profile"));
+/** Refuse a call that has no role when anonymous access is disabled. */
+const assertRole = (env, ctx) => {
+	if (!ctx.role && env.config.anonymousRole === void 0) throw new PgRestError(401, "PGRST302", "Anonymous access is disabled", null, null);
 };
 const parseCookies = (header) => {
 	const out = {};
@@ -2783,14 +2187,14 @@ const parseCookies = (header) => {
 	}
 	return out;
 };
-const applyCtxSql = (env, ctx, role, claims, request, method, pathname, schema, prefer) => {
+const applyCtxSql = (env, ctx, role, claims, caller, method, schema, prefer) => {
 	const entries = [["role", role], ["request.jwt.claims", JSON.stringify(claims)]];
 	if (env.config.requestSettings) {
 		const headers = {};
-		request.headers.forEach((v, k) => {
+		caller.headers?.forEach((v, k) => {
 			headers[k] = v;
 		});
-		entries.push(["request.method", method], ["request.path", pathname], ["request.headers", JSON.stringify(headers)], ["request.cookies", JSON.stringify(parseCookies(request.headers.get("cookie")))]);
+		entries.push(["request.method", method], ["request.path", caller.path], ["request.headers", JSON.stringify(headers)], ["request.cookies", JSON.stringify(parseCookies(caller.headers?.get("cookie") ?? null))]);
 	}
 	const searchPath = [schema, ...env.config.extraSearchPath].map(quoteIdent).join(", ");
 	entries.push(["search_path", searchPath]);
@@ -2807,21 +2211,21 @@ const applyCtxSql = (env, ctx, role, claims, request, method, pathname, schema,
 /** Parsed `response.headers` GUC: `[{"X-A": "b"}, ...]`. */
 const parseResponseHeaders = (raw) => {
 	if (raw == null || raw === "") return {};
-	const bad = () => new PgRestError(500, "PGRST111", "response.headers guc must be a JSON array composed of objects with a single key and a string value");
+	const bad$1 = () => new PgRestError(500, "PGRST111", "response.headers guc must be a JSON array composed of objects with a single key and a string value");
 	let parsed;
 	try {
 		parsed = JSON.parse(String(raw));
 	} catch {
-		throw bad();
+		throw bad$1();
 	}
-	if (!Array.isArray(parsed)) throw bad();
+	if (!Array.isArray(parsed)) throw bad$1();
 	const out = {};
 	for (const h of parsed) {
-		if (!h || typeof h !== "object" || Array.isArray(h)) throw bad();
+		if (!h || typeof h !== "object" || Array.isArray(h)) throw bad$1();
 		const keys = Object.keys(h);
-		if (keys.length !== 1) throw bad();
+		if (keys.length !== 1) throw bad$1();
 		const v = h[keys[0]];
-		if (typeof v !== "string") throw bad();
+		if (typeof v !== "string") throw bad$1();
 		out[keys[0]] = v;
 	}
 	return out;
@@ -2870,7 +2274,7 @@ const effectivePaging = (env, query, range) => {
 	};
 };
 const handleRequest = async (env, request, ctx) => {
-	if (!ctx.role && env.config.anonymousRole === void 0) throw new PgRestError(401, "PGRST302", "Anonymous access is disabled", null, null);
+	assertRole(env, ctx);
 	if (!isSupportedMethod(request.method)) return new Response(null, {
 		status: 405,
 		headers: { "Content-Type": JSON_CT }
@@ -2921,14 +2325,22 @@ const handleRequest = async (env, request, ctx) => {
 	const wantsPlan = requested.kind === "plan" ? requested : void 0;
 	const range = parseRange(request.headers.get("range"), request.headers.get("range-unit"));
 	const body = await parseBody(request, method);
+	const qp = {
+		params: [...url.searchParams],
+		bare: bareKeys(url.search)
+	};
 	let plan;
-	if (target.type === "table") plan = planTable(env, method, schema, target.name, url, prefer, format, range, body);
-	else plan = planRpc(env, method, schema, target.name, url, prefer, format, range, body);
-	return execute(env, ctx, request, method, url.pathname, schema, prefer, format, plan, honoredTx, wantsPlan);
-};
-const planTable = (env, method, schema, name, url, prefer, format, range, body) => {
+	if (target.type === "table") plan = planTable(env, method, schema, target.name, qp, prefer, format, range, body);
+	else plan = planRpc(env, method, schema, target.name, qp, prefer, format, range, body);
+	return execute(env, ctx, {
+		path: url.pathname,
+		headers: request.headers,
+		request
+	}, method, schema, prefer, format, plan, honoredTx, wantsPlan);
+};
+const planTable = (env, method, schema, name, qp, prefer, format, range, body) => {
 	const rel = getRelation(env.cache, schema, name);
-	const query = parseQuery([...url.searchParams]);
+	const query = parseQuery(qp.params);
 	const strip = format.kind === "json" || format.kind === "object" ? format.stripNulls : false;
 	const singular = format.kind === "object";
 	if (method === "GET" || method === "HEAD") {
@@ -3137,7 +2549,7 @@ const planTable = (env, method, schema, name, url, prefer, format, range, body)
 };
 /** A query-string value in the filter syntax (`eq.5`, `not.in.(1,2)`, `like(any).{a*}`), not a plain argument. */
 const looksLikeFilter = (v) => /^(not\.)?(eq|neq|gt|gte|lt|lte|like|ilike|match|imatch|in|is|isdistinct|cs|cd|ov|sl|sr|nxl|nxr|adj|fts|plfts|phfts|wfts)(\([a-z]+\))?\./.test(v);
-const planRpc = (env, method, schema, name, url, prefer, format, range, body) => {
+const planRpc = (env, method, schema, name, qp, prefer, format, range, body) => {
 	if (method !== "GET" && method !== "HEAD" && method !== "POST") throw new PgRestError(405, "PGRST101", `Cannot use the ${method} method on RPC`);
 	const RESERVED = new Set([
 		"select",
@@ -3153,7 +2565,7 @@ const planRpc = (env, method, schema, name, url, prefer, format, range, body) =>
 	let nonObjectBody = false;
 	const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 	const getArgKeys = /* @__PURE__ */ new Set();
-	const bare = /* @__PURE__ */ new Set();
+	const bare = qp.bare;
 	if (method === "POST") {
 		if (body) {
 			const v = body.value;
@@ -3169,9 +2581,8 @@ const planRpc = (env, method, schema, name, url, prefer, format, range, body) =>
 			}
 		}
 	} else {
-		for (const kv of url.search.slice(1).split("&")) if (kv !== "" && !kv.includes("=")) bare.add(decodeURIComponent(kv));
 		const lists = /* @__PURE__ */ new Map();
-		for (const [k, v] of url.searchParams) {
+		for (const [k, v] of qp.params) {
 			if (RESERVED.has(k) || bare.has(k) || looksLikeFilter(v) || k.includes(".")) continue;
 			lists.set(k, [...lists.get(k) ?? [], v]);
 		}
@@ -3186,7 +2597,7 @@ const planRpc = (env, method, schema, name, url, prefer, format, range, body) =>
 	const rawBody = nonObjectBody && isSingleUnnamedParam(fn);
 	const call = buildRpc(env.cache, fn, provided, rawBody);
 	const fnArgNames = new Set(fn.args.map((a) => a.name));
-	const query = parseQuery([...url.searchParams].filter(([k, v]) => !(v === "" && bare.has(k))), { allowFilterKey: (k) => method === "POST" || !fnArgNames.has(k) });
+	const query = parseQuery(qp.params.filter(([k, v]) => !(v === "" && bare.has(k))), { allowFilterKey: (k) => method === "POST" || !fnArgNames.has(k) });
 	const argsJson = rawBody ? JSON.stringify(body.value) : JSON.stringify(argValues);
 	const params = call.usesBody ? [rawBody && body.kind === "json" && typeof body.value === "string" ? body.value : argsJson] : [];
 	const strip = format.kind === "json" || format.kind === "object" ? format.stripNulls : false;
@@ -3243,13 +2654,13 @@ const planRpc = (env, method, schema, name, url, prefer, format, range, body) =>
 		})
 	};
 };
-const execute = async (env, ctx, request, method, pathname, schema, prefer, format, plan, honoredTx, wantsPlan) => {
+const execute = async (env, ctx, caller, method, schema, prefer, format, plan, honoredTx, wantsPlan) => {
 	const role = ctx.role ?? env.config.anonymousRole;
 	const claims = {
 		role,
 		...ctx.claims ?? {}
 	};
-	const setup = applyCtxSql(env, ctx, role, claims, request, method, pathname, schema, prefer);
+	const setup = applyCtxSql(env, ctx, role, claims, caller, method, schema, prefer);
 	const strict = prefer.handling === "strict";
 	const rollback = honoredTx && prefer.tx === "rollback" || wantsPlan !== void 0;
 	const attempt = async () => {
@@ -3263,8 +2674,8 @@ const execute = async (env, ctx, request, method, pathname, schema, prefer, form
 					role,
 					claims,
 					method,
-					path: pathname,
-					request
+					path: caller.path,
+					request: caller.request
 				});
 				let planned;
 				if (plan.planned) {
@@ -3330,9 +2741,9 @@ const execute = async (env, ctx, request, method, pathname, schema, prefer, form
 			}
 		});
 	}
-	return buildResponse(env, request, method, prefer, format, plan, result, honoredTx);
+	return buildResponse(env, method, prefer, format, plan, result, honoredTx);
 };
-const buildResponse = (env, request, method, prefer, format, plan, r, honoredTx) => {
+const buildResponse = (env, method, prefer, format, plan, r, honoredTx) => {
 	const headers = { Vary: "Accept, Prefer, Range" };
 	const applied = appliedHeader(prefer, honoredTx);
 	if (applied) headers["Preference-Applied"] = applied;
@@ -3486,11 +2897,305 @@ const handleSafely = async (env, request, ctx) => {
 	}
 };
 
+//#endregion
+//#region src/query.ts
+/** A query that failed, with the PostgREST error body and the input that produced it. */
+var QueryError = class extends ApiError {
+	constructor(input, api, options) {
+		super({
+			status: api.status,
+			body: api.body,
+			headers: api.headers
+		});
+		this.input = input;
+		this.name = "QueryError";
+		if (options?.cause !== void 0) this.cause = options.cause;
+	}
+};
+const OPS = new Set([
+	"eq",
+	"neq",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"like",
+	"ilike",
+	"match",
+	"imatch",
+	"in",
+	"is",
+	"isdistinct",
+	"fts",
+	"plfts",
+	"phfts",
+	"wfts",
+	"cs",
+	"cd",
+	"ov",
+	"sl",
+	"sr",
+	"nxl",
+	"nxr",
+	"adj"
+]);
+/** Inside a list or a logic tree these read as something other than text, so such a string is quoted. */
+const KEYWORDS = new Set([
+	"null",
+	"true",
+	"false",
+	"unknown"
+]);
+const bad = (message, hint) => new PgRestError(400, "PGRST100", message, null, hint ?? null);
+/**
+* Render a value the way the query string carries it. A lone value is taken verbatim --
+* `name=eq.a,b` is the text `a,b` and `name=eq.null` is the text `null`, which is why
+* only a *delimited* context (a list or a logic tree, where `,` `)` and `.` separate)
+* needs quoting. `tests/compare` pins both against PostgREST.
+*/
+const lit = (v, delimited) => {
+	if (v === void 0 || v === null) return "null";
+	if (typeof v !== "string") return String(v);
+	if (!delimited) return v;
+	return v === "" || KEYWORDS.has(v.toLowerCase()) || /[,()[\]{}".\\]/.test(v) || /^\s|\s$/.test(v) ? `"${v.replace(/(["\\])/g, "\\$1")}"` : v;
+};
+/** Array values are a list for `in` and a PostgreSQL array literal for the containment operators. */
+const listOf = (op, values) => {
+	const items = values.map((v) => lit(v, true)).join(",");
+	return op === "in" ? `(${items})` : `{${items}}`;
+};
+const toSpec = (column, f) => {
+	if (f === null || typeof f !== "object") return {
+		op: "eq",
+		value: f
+	};
+	if (Array.isArray(f)) {
+		const [op, value] = f;
+		if (typeof op !== "string" || !OPS.has(op)) throw bad(`Unknown filter operator '${String(op)}' on '${column}'`, "A filter is a value, a [operator, value] tuple or { op, value }");
+		return {
+			op,
+			value
+		};
+	}
+	const spec = f;
+	if (!OPS.has(spec.op)) throw bad(`Unknown filter operator '${String(spec.op)}' on '${column}'`);
+	if (spec.quantifier && spec.config) throw bad(`'${column}' cannot have both a quantifier and a text-search configuration`);
+	return spec;
+};
+/** The right-hand side of a filter: `[not.]op[(modifier)].value`. */
+const renderFilter = (column, f, delimited) => {
+	const spec = toSpec(column, f);
+	if (spec.value === null && (spec.op === "eq" || spec.op === "neq")) return `${Boolean(spec.not) !== (spec.op === "neq") ? "not." : ""}is.null`;
+	const modifier = spec.quantifier ?? spec.config;
+	return `${`${spec.not ? "not." : ""}${spec.op}${modifier ? `(${modifier})` : ""}`}.${Array.isArray(spec.value) ? listOf(spec.op, spec.value) : lit(spec.value, delimited)}`;
+};
+const isGroupKey = (key) => key === "and" || key === "or";
+/** Every condition of a `Where`, rendered as a logic tree would carry them (`total.gte.100`). */
+const renderConditions = (w) => Object.entries(w).flatMap(([key, value]) => {
+	if (value === void 0) return [];
+	if (isGroupKey(key)) {
+		if (!Array.isArray(value)) throw bad(`'${key}' takes a list of groups`);
+		return [`${key}(${value.map(renderGroup).join(",")})`];
+	}
+	return [`${key}.${renderFilter(key, value, true)}`];
+});
+/** One member of an `and`/`or` list. Several conditions in the same object are ANDed. */
+const renderGroup = (w) => {
+	const parts = renderConditions(w);
+	if (parts.length === 0) throw bad("An and/or group cannot be empty");
+	return parts.length === 1 ? parts[0] : `and(${parts.join(",")})`;
+};
+const renderOrder = (o) => {
+	if (typeof o === "string") return o;
+	const nulls = o.nulls === "first" ? ".nullsfirst" : o.nulls === "last" ? ".nullslast" : "";
+	return `${o.column}${o.desc ? ".desc" : ".asc"}${nulls}`;
+};
+/** `where`, `order`, `limit` and `offset` of one node, prefixed with its dotted path. */
+const pushNode = (node, path, out) => {
+	const at$1 = path.length ? `${path.join(".")}.` : "";
+	for (const [key, value] of Object.entries(node.where ?? {})) {
+		if (value === void 0) continue;
+		if (isGroupKey(key)) {
+			if (!Array.isArray(value)) throw bad(`'${key}' takes a list of groups`);
+			out.push([`${at$1}${key}`, `(${value.map(renderGroup).join(",")})`]);
+		} else out.push([`${at$1}${key}`, renderFilter(key, value, false)]);
+	}
+	if (node.order?.length) out.push([`${at$1}order`, node.order.map(renderOrder).join(",")]);
+	if (node.limit !== void 0) out.push([`${at$1}limit`, String(node.limit)]);
+	if (node.offset !== void 0) out.push([`${at$1}offset`, String(node.offset)]);
+};
+const isEmbed = (v) => !Array.isArray(v);
+/** The `select` parameter. Embedded resources also push their own filters and paging into `out`. */
+const renderSelect = (items, path, out) => {
+	return items.map((item) => {
+		if (typeof item === "string") return item;
+		return Object.entries(item).map(([relation, spec]) => {
+			const embed = isEmbed(spec) ? spec : { select: spec };
+			const name = embed.as ?? relation;
+			const mods = `${embed.hint ? `!${embed.hint}` : ""}${embed.inner ? "!inner" : ""}`;
+			const head = `${embed.spread ? "..." : ""}${embed.as ? `${embed.as}:` : ""}${relation}${mods}`;
+			const inner = renderSelect(embed.select ?? ["*"], [...path, name], out);
+			pushNode(embed, [...path, name], out);
+			return `${head}(${inner})`;
+		}).join(",");
+	}).join(",");
+};
+/** Everything the query string would carry, built from the object instead of parsed from a URL. */
+const toParams = (input) => {
+	const out = [];
+	const embedded = [];
+	if (input.select) out.push(["select", renderSelect(input.select, [], embedded)]);
+	out.push(...embedded);
+	pushNode(input, [], out);
+	if ("action" in input && (input.action === "insert" || input.action === "upsert")) {
+		if (input.onConflict?.length) out.push(["on_conflict", input.onConflict.join(",")]);
+		if (input.columns?.length) out.push(["columns", input.columns.join(",")]);
+	}
+	return out;
+};
+const isRpc = (input) => "rpc" in input;
+const methodOf = (input) => {
+	if (isRpc(input)) return "POST";
+	switch (input.action ?? "select") {
+		case "select": return "GET";
+		case "insert":
+		case "upsert": return "POST";
+		case "update": return "PATCH";
+		case "delete": return "DELETE";
+	}
+};
+const bodyOf = (input) => {
+	if (isRpc(input)) return {
+		kind: "json",
+		value: input.args ?? {}
+	};
+	if (!("action" in input)) return void 0;
+	switch (input.action) {
+		case "insert":
+		case "upsert": return {
+			kind: "json",
+			value: input.rows
+		};
+		case "update": return {
+			kind: "json",
+			value: input.set
+		};
+		default: return;
+	}
+};
+const writes = (input) => {
+	return methodOf(input) !== "GET" && !isRpc(input);
+};
+/**
+* Unlike HTTP, a write defaults to returning its rows: a function that gives nothing back
+* is of little use in a program. `returning: "minimal"` is PostgREST's own default.
+*/
+const returningOf = (input) => {
+	if (!writes(input)) return void 0;
+	return input.returning ?? "representation";
+};
+const preferencesOf = (input) => ({
+	...returningOf(input) ? { return: returningOf(input) } : {},
+	...input.count ? { count: input.count } : {},
+	..."action" in input && input.action === "upsert" ? { resolution: "merge-duplicates" } : {},
+	..."action" in input && input.action === "insert" && input.missing ? { missing: input.missing } : {},
+	...input.maxAffected !== void 0 ? {
+		handling: "strict",
+		maxAffected: input.maxAffected
+	} : {},
+	...input.timezone ? { timezone: input.timezone } : {},
+	invalid: []
+});
+/** The total in a `Content-Range` (`0-9/42`), when one was computed. */
+const totalOf = (range) => {
+	const total = range?.split("/")[1];
+	return total === void 0 || total === "*" ? void 0 : Number(total);
+};
+const run = async (env, input, ctx) => {
+	assertRole(env, ctx);
+	if (isRpc(input) && "table" in input) throw bad("A query names either a table or an rpc, not both");
+	const schema = useSchema(env, input.schema);
+	const method = methodOf(input);
+	const prefer = preferencesOf(input);
+	const format = input.single ? {
+		kind: "object",
+		stripNulls: Boolean(input.stripNulls)
+	} : {
+		kind: "json",
+		stripNulls: Boolean(input.stripNulls)
+	};
+	const qp = {
+		params: toParams(input),
+		bare: /* @__PURE__ */ new Set()
+	};
+	const body = bodyOf(input);
+	const plan = isRpc(input) ? planRpc(env, method, schema, input.rpc, qp, prefer, format, void 0, body) : planTable(env, method, schema, input.table, qp, prefer, format, void 0, body);
+	const res = await execute(env, ctx, { path: isRpc(input) ? `/rpc/${input.rpc}` : `/${input.table}` }, method, schema, prefer, format, plan, false, void 0);
+	const text = await res.text();
+	return {
+		data: text === "" ? null : JSON.parse(text),
+		count: totalOf(res.headers.get("content-range")),
+		status: res.status
+	};
+};
+/**
+* Run a query described by an object, in-process. Same parser, same SQL and same errors as
+* {@link handleRequest}: only the HTTP envelope is gone. Throws a {@link QueryError}.
+*/
+const runQuery = async (env, input, ctx = {}) => {
+	try {
+		return await run(env, input, ctx);
+	} catch (e) {
+		const api = toApiError(e, ctx.role ?? env.config.anonymousRole, env.config.anonymousRole);
+		throw new QueryError(input, api, api.status >= 500 && !(e instanceof PgRestError) && !(e instanceof ApiError) ? { cause: e } : void 0);
+	}
+};
+/**
+* Turn anything at all into the failed half of a {@link QuerySafeResult}. `runQuery` already maps
+* what it can; whatever it could not is still reported, as the body PostgREST answers a 500 with
+* and the original error under `cause`. Nothing is logged and nothing is dropped: `error` is the
+* only channel, so the caller decides what to do with it.
+*/
+const toSafeFailure = (input, e) => {
+	const error = e instanceof QueryError ? e : new QueryError(input, new ApiError({
+		status: 500,
+		headers: {},
+		body: {
+			code: "PGRSTX00",
+			message: "Internal error",
+			details: null,
+			hint: null
+		}
+	}), { cause: e });
+	return {
+		data: null,
+		error,
+		status: error.status
+	};
+};
+/**
+* {@link runQuery} with the failure as a value: `{ data, error }`, where exactly one is set.
+* The error is the same {@link QueryError} the throwing form raises -- this only chooses how it
+* reaches you, which is a matter of taste and of how much of a result you handle in one place.
+*
+* **This never rejects.** Every failure, including one the library did not foresee, comes back as
+* `error`, so a caller that checks it needs no `try`/`catch` at all.
+*/
+const runQuerySafe = async (env, input, ctx = {}) => {
+	try {
+		return {
+			...await runQuery(env, input, ctx),
+			error: null
+		};
+	} catch (e) {
+		return toSafeFailure(input, e);
+	}
+};
+
 //#endregion
 //#region src/index.ts
 const UNEXPOSABLE = new Set(["pg_catalog", "information_schema"]);
-/** Create a PostgREST-compatible handler over a Postgres database. */
-const createPgRest = async (options) => {
+const create = async (options) => {
 	const schemas = options.schemas?.length ? [...options.schemas] : ["public"];
 	for (const s of schemas) if (UNEXPOSABLE.has(s)) throw new Error(`pg-rest: the schema "${s}" cannot be exposed`);
 	const user = options.db;
@@ -3537,13 +3242,40 @@ const createPgRest = async (options) => {
 			cache: store.current()
 		}, request, context ?? {});
 	};
+	const query = async (input, ctx) => await runQuery({
+		db: adapter,
+		config,
+		cache: store.current()
+	}, input, ctx ?? {});
+	const querySafe = async (input, ctx) => {
+		try {
+			return await runQuerySafe({
+				db: adapter,
+				config,
+				cache: store.current()
+			}, input, ctx ?? {});
+		} catch (e) {
+			return toSafeFailure(input, e);
+		}
+	};
 	return {
 		handle,
+		query,
+		querySafe,
+		generateTypes: async (forTypes) => (await import("./types.js")).generateTypes(store.current(), forTypes),
 		reloadSchema: async () => void await store.reload(),
 		schemaCache: async () => store.current(),
 		close: async () => {}
 	};
 };
+/**
+* Create a PostgREST-compatible handler over a Postgres database.
+*
+* `createPgRest<Db>(options)` returns the same instance with `query` and `querySafe` typed by a
+* generated database type; the cast is the whole of that difference, since types never reach
+* runtime and the two instances are one object.
+*/
+const createPgRest = create;
 
 //#endregion
-export { ApiError, DbQueryError, PgRestError, SchemaLoadError, createPgRest };
+export { ApiError, DbQueryError, PgRestError, QueryError, SchemaLoadError, createPgRest };