@adrdp/pg-rest 0.1.3 → 0.2.0

package/dist/types-DaNxiC7H.d.ts

@@ -0,0 +1,146 @@
+//#region src/schema.d.ts
+interface Column {
+  readonly name: string;
+  /** Result of `format_type`, e.g. `integer`, `character varying(10)`, `text[]`. */
+  readonly type: string;
+  /**
+   * Labels of the enum type, in declaration order, when the column is an enum or an array of one.
+   * Domains over an enum are not unwrapped.
+   */
+  readonly enumLabels?: ReadonlyArray<string> | undefined;
+  /**
+   * For a view column read straight from a table column, that column -- followed through
+   * view-over-view chains. `nullable` still reports what the catalog says of the *view*, which is
+   * always true: a `NOT NULL` source says nothing about a `LEFT JOIN` in the view's own query.
+   */
+  readonly source?: {
+    readonly schema: string;
+    readonly table: string;
+    readonly column: string;
+  } | undefined;
+  readonly nullable: boolean;
+  readonly hasDefault: boolean;
+  /** SQL text of the default expression, when there is one. */
+  readonly defaultExpr: string | null;
+  readonly generated: boolean;
+  /**
+   * `GENERATED ALWAYS AS IDENTITY` or `GENERATED BY DEFAULT AS IDENTITY`. An `always` column refuses
+   * a value outright (`428C9`), unlike a column that merely has a default.
+   */
+  readonly identity?: "always" | "by-default" | undefined;
+  readonly comment: string | null;
+  readonly position: number;
+}
+type RelationKind = "table" | "view" | "matview" | "foreign" | "partitioned";
+interface Relation {
+  readonly schema: string;
+  readonly name: string;
+  readonly kind: RelationKind;
+  readonly columns: ReadonlyArray<Column>;
+  readonly pk: ReadonlyArray<string>;
+  readonly uniques: ReadonlyArray<ReadonlyArray<string>>;
+  readonly insertable: boolean;
+  readonly updatable: boolean;
+  readonly deletable: boolean;
+  readonly comment: string | null;
+}
+interface ForeignKey {
+  readonly name: string;
+  readonly schema: string;
+  readonly table: string;
+  readonly cols: ReadonlyArray<string>;
+  readonly fschema: string;
+  readonly ftable: string;
+  readonly fcols: ReadonlyArray<string>;
+}
+interface FunctionArg {
+  readonly name: string;
+  readonly type: string;
+  readonly hasDefault: boolean;
+  readonly variadic: boolean;
+  /** Labels of the enum type, when the argument is an enum or an array of one. */
+  readonly enumLabels?: ReadonlyArray<string> | undefined;
+}
+interface FunctionDef {
+  readonly schema: string;
+  readonly name: string;
+  readonly args: ReadonlyArray<FunctionArg>;
+  readonly returnType: string;
+  /** Labels of the enum type, when the function returns an enum or an array of one. */
+  readonly returnEnumLabels?: ReadonlyArray<string> | undefined;
+  readonly returnsSet: boolean;
+  /** True if the function returns a composite / record / TABLE(...) row type. */
+  readonly returnsComposite: boolean;
+  readonly returnsVoid: boolean;
+  readonly volatility: "immutable" | "stable" | "volatile";
+  readonly comment: string | null;
+  /** The table when the function's only parameter is a table row (computed relationships). */
+  readonly argRelation?: {
+    readonly schema: string;
+    readonly name: string;
+  };
+  /** The table whose rows the function returns. */
+  readonly returnRelation?: {
+    readonly schema: string;
+    readonly name: string;
+  };
+  /** Planner row estimate; 1 on a set-returning function makes a computed relationship to-one. */
+  readonly rows: number;
+  /** Scalar functions returning a domain named like a media type (`"text/plain"`, …): the raw value is the body. */
+  readonly returnMediaType?: {
+    readonly name: string;
+    readonly bytea: boolean;
+  };
+}
+/** A custom media type handler: an aggregate named after the media type that returns a domain (see PostgREST's "custom media types"). */
+interface MediaHandler {
+  readonly schema: string;
+  /** The aggregate's name, i.e. the media type (for example `text/plain`, or the catch-all). */
+  readonly mediaType: string;
+  /** The table whose rows it aggregates, or `undefined` for `anyelement`. */
+  readonly argRelation?: {
+    readonly schema: string;
+    readonly name: string;
+  };
+  /** True when the domain wraps `bytea` (the body is binary). */
+  readonly bytea: boolean;
+}
+interface SchemaCache {
+  readonly mediaHandlers: ReadonlyArray<MediaHandler>;
+  readonly schemas: ReadonlyArray<string>;
+  readonly relations: ReadonlyMap<string, Relation>;
+  readonly foreignKeys: ReadonlyArray<ForeignKey>;
+  readonly functions: ReadonlyMap<string, ReadonlyArray<FunctionDef>>;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Generate TypeScript types from an introspected schema, as the text of a module.
+ *
+ * The catalog is the only source: this is the same {@link SchemaCache} the request path reads, so
+ * what the types allow is what the library accepts. Write the result next to your code and keep it
+ * in version control:
+ *
+ * ```ts
+ * writeFileSync("src/db.types.ts", generateTypes(await pgRest.schemaCache()));
+ * ```
+ */
+interface GenerateTypesOptions {
+  /** Name of the exported type. Default `"Database"`. */
+  readonly name?: string;
+  /**
+   * Nullability of view columns. The catalog reports every one of them as nullable, which is the
+   * truth as far as it knows: a `NOT NULL` source column says nothing about a `LEFT JOIN` in the
+   * view's own query. `"like-source"` follows `Column.source` instead -- shorter types, at the risk
+   * of claiming non-null where an outer join can produce one.
+   */
+  readonly views?: "nullable" | "like-source";
+  /** Banner comment. `false` leaves it out. */
+  readonly header?: string | false;
+}
+/** The type of one column's value, enum labels and array dimensions included. */
+declare const columnType: (col: Pick<Column, "type" | "enumLabels">) => string;
+/** Generate the module text. Deterministic: same catalog, same bytes. */
+declare const generateTypes: (cache: SchemaCache, options?: GenerateTypesOptions) => string;
+//#endregion
+export { ForeignKey as a, SchemaCache as c, Column as i, columnType as n, FunctionDef as o, generateTypes as r, Relation as s, GenerateTypesOptions as t };

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+import { n as columnType, r as generateTypes, t as GenerateTypesOptions } from "./types-DaNxiC7H.js";
+export { GenerateTypesOptions, columnType, generateTypes };

package/dist/types.js

@@ -0,0 +1,202 @@
+import { a as relKey, t as findRelationships } from "./schema-BhF_TQdX.js";
+
+//#region src/types.ts
+const RESERVED_KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** An object key: bare when it is a plain identifier, quoted otherwise. */
+const key = (name) => RESERVED_KEY.test(name) ? name : JSON.stringify(name);
+const pascal = (s) => s.replace(/(^|[^A-Za-z0-9])([A-Za-z0-9])/g, (_, __, c) => c.toUpperCase());
+/**
+* Map a `format_type` string to a TypeScript type. Anything not recognised becomes `unknown`
+* rather than `string`: a type that is merely plausible is worse than one that forces a check.
+*/
+const scalar = (pgType) => {
+	const base = pgType.trim().replace(/\(.*\)$/, "");
+	switch (base.includes(".") ? base.slice(base.lastIndexOf(".") + 1) : base) {
+		case "smallint":
+		case "integer":
+		case "bigint":
+		case "numeric":
+		case "decimal":
+		case "real":
+		case "double precision":
+		case "smallserial":
+		case "serial":
+		case "bigserial": return "number";
+		case "boolean": return "boolean";
+		case "text":
+		case "character varying":
+		case "character":
+		case "bpchar":
+		case "varchar":
+		case "char":
+		case "name":
+		case "citext":
+		case "uuid":
+		case "date":
+		case "timestamp with time zone":
+		case "timestamp without time zone":
+		case "time with time zone":
+		case "time without time zone":
+		case "interval":
+		case "bytea":
+		case "money":
+		case "xml":
+		case "inet":
+		case "cidr":
+		case "macaddr":
+		case "macaddr8":
+		case "tsvector": return "string";
+		default: return "unknown";
+	}
+};
+/** The type of one column's value, enum labels and array dimensions included. */
+const columnType = (col) => {
+	let t = col.type.trim();
+	let dims = 0;
+	while (t.endsWith("[]")) {
+		t = t.slice(0, -2).trim();
+		dims++;
+	}
+	const labels = col.enumLabels;
+	const inner = labels?.length ? labels.map((l) => JSON.stringify(l)).join(" | ") : scalar(t);
+	return (dims > 0 && inner.includes(" | ") ? `(${inner})` : inner) + "[]".repeat(dims);
+};
+const nullableFor = (cache, col, views) => {
+	if (!col.nullable) return false;
+	if (views === "nullable" || !col.source) return true;
+	const base = cache.relations.get(relKey(col.source.schema, col.source.table))?.columns.find((c) => c.name === col.source.column);
+	return base ? base.nullable : true;
+};
+const writer = () => {
+	const lines = [];
+	return {
+		lines,
+		push: (depth, text) => lines.push(`${"  ".repeat(depth)}${text}`)
+	};
+};
+/** `row`, `insert` and `update` of one relation. */
+const shapes = (rel, sourceNullable, push, depth) => {
+	const cols = [...rel.columns].sort((a, b) => a.position - b.position);
+	const value = (c) => {
+		const t = columnType(c);
+		return t === "unknown" || !sourceNullable(c) ? t : `${t} | null`;
+	};
+	push(depth, "row: {");
+	for (const c of cols) push(depth + 1, `${key(c.name)}: ${value(c)};`);
+	push(depth, "};");
+	const writable = cols.filter((c) => !c.generated && c.identity !== "always");
+	push(depth, rel.insertable ? "insert: {" : "insert: never;");
+	if (rel.insertable) {
+		for (const c of writable) {
+			const optional = c.hasDefault || sourceNullable(c) ? "?" : "";
+			push(depth + 1, `${key(c.name)}${optional}: ${value(c)};`);
+		}
+		push(depth, "};");
+	}
+	push(depth, rel.updatable ? "update: {" : "update: never;");
+	if (rel.updatable) {
+		for (const c of writable) push(depth + 1, `${key(c.name)}?: ${value(c)};`);
+		push(depth, "};");
+	}
+};
+/**
+* Every name that can be embedded from `rel`, resolved by the same {@link findRelationships} the
+* request path uses -- so a `select` the types accept is one the library can resolve.
+*/
+const embeds = (cache, rel) => {
+	const candidates = /* @__PURE__ */ new Set();
+	for (const r of cache.relations.values()) if (r.schema === rel.schema && r.name !== rel.name) candidates.add(r.name);
+	for (const fk of cache.foreignKeys) if (fk.schema === rel.schema && fk.table === rel.name && fk.cols.length === 1) candidates.add(fk.cols[0]);
+	for (const [k, defs] of cache.functions) {
+		const [schema, ...rest] = k.split(".");
+		if (schema !== rel.schema) continue;
+		if (defs.some((d) => d.argRelation?.schema === rel.schema && d.argRelation.name === rel.name && d.returnRelation)) candidates.add(rest.join("."));
+	}
+	const out = [];
+	for (const target of [...candidates].sort()) {
+		const usable = findRelationships(cache, rel, target).filter((r) => r.to.schema === rel.schema);
+		if (usable.length === 0) continue;
+		const first = usable[0];
+		const to = first.kind === "o2m" || first.kind === "m2m" ? "many" : "one";
+		const hints = usable.map((r) => JSON.stringify(r.fk.name)).join(", ");
+		const ambiguous = usable.length > 1 ? `; ambiguous: true; hints: [${hints}]` : "";
+		out.push([target, `{ rel: ${JSON.stringify(first.to.name)}; to: ${JSON.stringify(to)}${ambiguous} }`]);
+	}
+	return out;
+};
+/** The arguments and result of one overload. */
+const signature = (fn, relationsType, cache) => {
+	const raw = fn.args.length === 1 && fn.args[0].name === "";
+	const args = raw ? columnType({
+		type: fn.args[0].type,
+		enumLabels: fn.args[0].enumLabels
+	}) : fn.args.length === 0 ? "{}" : `{ ${fn.args.map((a) => {
+		const t = columnType({
+			type: a.type,
+			enumLabels: a.enumLabels
+		});
+		return `${key(a.name)}${a.hasDefault ? "?" : ""}: ${t}`;
+	}).join("; ")} }`;
+	const target = fn.returnRelation ? cache.relations.get(relKey(fn.returnRelation.schema, fn.returnRelation.name)) : void 0;
+	return `{ args: ${args}; returns: ${fn.returnsVoid ? "null" : target ? `${relationsType}[${JSON.stringify(target.name)}]["row"]` : fn.returnsComposite ? "Record<string, unknown>" : columnType({
+		type: fn.returnType,
+		enumLabels: fn.returnEnumLabels
+	})}; set: ${fn.returnsSet}${raw ? "; raw: true" : ""} }`;
+};
+/** Generate the module text. Deterministic: same catalog, same bytes. */
+const generateTypes = (cache, options = {}) => {
+	const name = options.name ?? "Database";
+	const views = options.views ?? "nullable";
+	const { lines, push } = writer();
+	if (options.header !== false) {
+		push(0, `// ${options.header ?? `Generated from the database catalog by @adrdp/pg-rest. Do not edit.`}`);
+		push(0, "");
+	}
+	const schemas = [...cache.schemas];
+	for (const schema of schemas) {
+		const relationsType = `${name}${pascal(schema)}Relations`;
+		const relations = [...cache.relations.values()].filter((r) => r.schema === schema).sort((a, b) => a.name.localeCompare(b.name));
+		push(0, `type ${relationsType} = {`);
+		for (const rel of relations) {
+			const sourceNullable = (c) => nullableFor(cache, c, views);
+			push(1, `${key(rel.name)}: {`);
+			shapes(rel, sourceNullable, push, 2);
+			push(2, `pk: [${rel.pk.map((c) => JSON.stringify(c)).join(", ")}];`);
+			push(2, `insertable: ${rel.insertable};`);
+			push(2, `updatable: ${rel.updatable};`);
+			push(2, `deletable: ${rel.deletable};`);
+			const rels = embeds(cache, rel);
+			if (rels.length === 0) push(2, "rel: {};");
+			else {
+				push(2, "rel: {");
+				for (const [target, entry] of rels) push(3, `${key(target)}: ${entry};`);
+				push(2, "};");
+			}
+			push(1, "};");
+		}
+		push(0, "};");
+		push(0, "");
+		const functionsType = `${name}${pascal(schema)}Functions`;
+		const fns = [...cache.functions.entries()].filter(([k]) => k.startsWith(`${schema}.`)).map(([k, defs]) => [k.slice(schema.length + 1), defs.filter((d) => !(d.argRelation && d.returnRelation))]).filter(([, defs]) => defs.length > 0).sort(([a], [b]) => a.localeCompare(b));
+		if (fns.length === 0) push(0, `type ${functionsType} = {};`);
+		else {
+			push(0, `type ${functionsType} = {`);
+			for (const [fnName, defs] of fns) {
+				const overloads = defs.map((d) => signature(d, relationsType, cache)).join(", ");
+				push(1, `${key(fnName)}: [${overloads}];`);
+			}
+			push(0, "};");
+		}
+		push(0, "");
+	}
+	push(0, `export type ${name} = {`);
+	push(1, `default: ${JSON.stringify(schemas[0] ?? "public")};`);
+	push(1, "schemas: {");
+	for (const schema of schemas) push(2, `${key(schema)}: { relations: ${name}${pascal(schema)}Relations; functions: ${name}${pascal(schema)}Functions };`);
+	push(1, "};");
+	push(0, "};");
+	return `${lines.join("\n")}\n`;
+};
+
+//#endregion
+export { columnType, generateTypes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrdp/pg-rest",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "A PostgREST-compatible REST layer for PostgreSQL, consumed as a library (Bun, Node.js and other runtimes with web-standard Request/Response). You decide who the user is (RLS) — no JWT required.",
   "license": "MIT",
   "author": "Alexandre Dos Reis",
@@ -20,6 +20,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
     "./adapters/bun": {
       "types": "./dist/adapters/bun.d.ts",
       "default": "./dist/adapters/bun.js"
@@ -60,6 +64,8 @@
     "@changesets/cli": "^3.0.3",
     "@electric-sql/pglite": "^0.5.15",
     "@hono/node-server": "^2.1.6",
+    "@neondatabase/postgrest-js": "^0.2.0-beta",
+    "@supabase/postgrest-js": "^2.119.0",
     "@types/bun": "latest",
     "@types/pg": "^8.23.1",
     "autocannon": "^8.0.0",