@bezoar/kit 0.0.1 → 0.0.3

package/.dist/_chunks/build.mjs

@@ -5,6 +5,7 @@ import { createServer } from "node:net";
 import { PGLiteSocketServer } from "@electric-sql/pglite-socket";
 import { createGenerator } from "@ts-safeql/generate";
 import postgres from "postgres";
+import { parse } from "libpg-query";
 import { record, within } from "objectively";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
@@ -74,6 +75,36 @@ const apply = async (executor, sources) => {
 		throw new InvalidSourceError(file.path, `failed: ${reason(cause)}`, { cause });
 	}
 };
+const COLUMNS = `
+  SELECT n.nspname AS schema, c.relname AS table,
+         pg_catalog.pg_table_is_visible(c.oid) AS visible,
+         a.attname AS name, NOT (a.attnotnull OR t.typnotnull) AS nullable
+  FROM pg_attribute a
+  JOIN pg_class c ON c.oid = a.attrelid
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+  JOIN pg_type t ON t.oid = a.atttypid
+  WHERE c.relkind IN ('r', 'p')
+    AND a.attnum > 0
+    AND NOT a.attisdropped
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  ORDER BY n.nspname, c.relname, a.attnum`;
+const readColumns = async (executor) => {
+	const columns = /* @__PURE__ */ new Map();
+	for (const row of (await executor.query(COLUMNS, [])).rows) {
+		const column = {
+			name: String(row.name),
+			nullable: row.nullable === true
+		};
+		const keys = [`${String(row.schema)}.${String(row.table)}`];
+		if (row.visible === true) keys.push(String(row.table));
+		for (const key of keys) {
+			const list = columns.get(key);
+			if (list === void 0) columns.set(key, [column]);
+			else list.push(column);
+		}
+	}
+	return columns;
+};
 const ENUMS = `
   SELECT t.typname AS name,
          array_agg(e.enumlabel::text ORDER BY e.enumsortorder) AS labels
@@ -88,6 +119,66 @@ const readEnums = async (executor) => {
 	for (const row of (await executor.query(ENUMS, [SCHEMA])).rows) enums[String(row.name)] = Array.isArray(row.labels) ? row.labels.map(String) : [];
 	return enums;
 };
+const is = (value, key) => key in value;
+const paramOf = (node) => {
+	if (node === void 0) return;
+	if ("TypeCast" in node) return paramOf(node.TypeCast.arg);
+	if ("ParamRef" in node) return node.ParamRef.number;
+};
+const tableOf = (columns, relation) => {
+	if (relation?.relname === void 0) return;
+	const { schemaname, relname } = relation;
+	return columns.get(schemaname === void 0 ? relname : `${schemaname}.${relname}`);
+};
+const nameOf$1 = (node) => node !== void 0 && "ResTarget" in node && node.ResTarget.indirection === void 0 ? node.ResTarget.name : void 0;
+const valueOf = (node) => "ResTarget" in node ? node.ResTarget.val : void 0;
+const rowsOf = (node) => {
+	if (node === void 0 || !("SelectStmt" in node)) return [];
+	const { valuesLists, targetList } = node.SelectStmt;
+	if (valuesLists !== void 0) return valuesLists.map((row) => "List" in row ? row.List.items ?? [] : []);
+	if (targetList !== void 0) return [targetList.map(valueOf)];
+	return [];
+};
+const collect = (tree, columns) => {
+	const found = /* @__PURE__ */ new Set();
+	const mark = (node) => {
+		const number = paramOf(node);
+		if (number !== void 0) found.add(number);
+	};
+	const written = (table, name, value) => {
+		if (table?.find((column) => column.name === name)?.nullable) mark(value);
+	};
+	const walk = (value) => {
+		if (Array.isArray(value)) {
+			for (const item of value) walk(item);
+			return;
+		}
+		if (!record(value)) return;
+		if (is(value, "NullTest")) mark(value.NullTest.arg);
+		else if (is(value, "CoalesceExpr")) for (const arg of value.CoalesceExpr.args ?? []) mark(arg);
+		else if (is(value, "A_Expr")) {
+			const { kind, lexpr, rexpr } = value.A_Expr;
+			if (kind === "AEXPR_DISTINCT" || kind === "AEXPR_NOT_DISTINCT") {
+				mark(lexpr);
+				mark(rexpr);
+			}
+		} else if (is(value, "InsertStmt")) {
+			const { relation, cols, selectStmt, onConflictClause } = value.InsertStmt;
+			const table = tableOf(columns, relation);
+			const names = cols === void 0 ? (table ?? []).map((column) => column.name) : cols.map(nameOf$1);
+			for (const row of rowsOf(selectStmt)) for (const [index, item] of row.entries()) written(table, names[index], item);
+			for (const target of onConflictClause?.targetList ?? []) written(table, nameOf$1(target), valueOf(target));
+		} else if (is(value, "UpdateStmt")) {
+			const { relation, targetList } = value.UpdateStmt;
+			const table = tableOf(columns, relation);
+			for (const target of targetList ?? []) written(table, nameOf$1(target), valueOf(target));
+		}
+		for (const member of Object.values(value)) walk(member);
+	};
+	walk(tree);
+	return found;
+};
+const nullableParams = async (sql, columns) => collect(await parse(sql), columns);
 const free = () => new Promise((resolve, reject) => {
 	const server = createServer();
 	server.listen(0, HOST, () => {
@@ -104,7 +195,7 @@ const admitsNull = (target) => {
 	if (target.kind === "union") return target.value.some(admitsNull);
 	return false;
 };
-const describeQueries = async (client, queries) => {
+const describeQueries = async (client, queries, columns) => {
 	const described = /* @__PURE__ */ new Map();
 	if (queries.length === 0) return described;
 	const port = await free();
@@ -137,8 +228,12 @@ const describeQueries = async (client, queries) => {
 			if (result._tag === "Left") throw new InvalidQueryError(query.path, `failed: ${result.left.message}`, { cause: result.left });
 			const { stmt, output } = result.right;
 			const targets = new Map(output?.value ?? []);
+			const nullable = await nullableParams(query.sql, columns);
 			described.set(query.name, {
-				params: stmt.types,
+				params: stmt.types.map((type, index) => ({
+					type,
+					nullable: nullable.has(index + 1)
+				})),
 				columns: stmt.columns.map((column) => {
 					const target = targets.get(column.name);
 					return {
@@ -417,7 +512,7 @@ const TYPES = `
 const readTypes = async (executor, described) => {
 	const oids = /* @__PURE__ */ new Set();
 	for (const { params, columns } of described.values()) {
-		for (const oid of params) oids.add(oid);
+		for (const param of params) oids.add(param.type);
 		for (const column of columns) oids.add(column.type);
 	}
 	const names = /* @__PURE__ */ new Map();
@@ -441,11 +536,14 @@ const define = (queries, described, types, enums) => {
 			return name;
 		};
 		statements[query.name] = {
-			slots: query.slots.map((name, index) => ({
-				name,
-				type: typeOf(`the slot :${name}`, description.params[index] ?? 0),
-				nullable: false
-			})),
+			slots: query.slots.map((name, index) => {
+				const param = description.params[index];
+				return {
+					name,
+					type: typeOf(`the slot :${name}`, param?.type ?? 0),
+					nullable: param?.nullable ?? false
+				};
+			}),
 			columns: description.columns.map((column) => ({
 				name: column.name,
 				type: typeOf(`the column ${column.name}`, column.type),
@@ -490,7 +588,8 @@ const generate = async (config, root) => {
 	try {
 		await apply(executor, sources);
 		const enums = await readEnums(executor);
-		const described = await describeQueries(client, sources.queries);
+		const columns = await readColumns(executor);
+		const described = await describeQueries(client, sources.queries, columns);
 		const types = await readTypes(executor, described);
 		const contract = define(sources.queries, described, types, enums);
 		return {

package/.dist/index.d.mts

@@ -74,11 +74,15 @@ export interface Sources {
   queries: Query[];
 }
 /**
- * What Postgres and SafeQL say about one query: the type OID of each slot,
- * and the name, type OID, and nullability of each column.
+ * What Postgres, SafeQL, and the parse tree say about one query: the type
+ * OID and nullability of each slot, and the name, type OID, and nullability
+ * of each column.
  */
 export interface Described {
-  readonly params: readonly number[];
+  readonly params: readonly {
+    readonly type: number;
+    readonly nullable: boolean;
+  }[];
   readonly columns: readonly {
     readonly name: string;
     readonly type: number;
@@ -90,6 +94,16 @@ export interface Described {
  * its labels, in declaration order. What the contract carries as `enums`.
  */
 export type Enums = Readonly<Record<string, readonly string[]>>;
+/**
+ * The columns of each table of the database after the migrations ran, in
+ * declaration order, with whether each takes null. A table is keyed by
+ * `schema.name`, and by its bare name when the search path finds it. What
+ * decides the nullability of a slot a query writes into a column.
+ */
+export type Columns = ReadonlyMap<string, readonly {
+  readonly name: string;
+  readonly nullable: boolean;
+}[]>;
 /**
  * One file of the output.
  */
@@ -246,8 +260,8 @@ export declare class InvalidQueryError extends Error {
 /**
  * Generates the output of a project without writing it. The function
  * validates the config, reads the SQL, applies the migrations and the seeds
- * to a database in memory, reads the enums, describes each query, builds
- * the contract, and emits the files.
+ * to a database in memory, reads the enums and the columns, describes each
+ * query, builds the contract, and emits the files.
  *
  * @param config - The authored config.
  * @param root - The project root.

package/README.md

@@ -89,6 +89,31 @@ is an error: a query names its slots.
 Every lever of a query is a SQL lever. A cast sets the type of a slot. An
 alias names a column. Two columns with one name fail the build.
 
+A slot is required unless its null has a meaning. The SQL gives it one when
+the slot is the operand of `IS NULL` or `IS NOT NULL`, an argument of
+`COALESCE`, or a side of `IS DISTINCT FROM` or `IS NOT DISTINCT FROM`,
+through any cast. The schema gives it one when an `INSERT`, an `UPDATE`, or
+an `ON CONFLICT DO UPDATE` writes the slot into a column without `NOT NULL`.
+Such a slot is an optional argument that also takes `null`, and an absent
+argument binds null. Any other slot is required: a null there matches
+nothing.
+
+```sql
+-- src/queries/events/search.sql
+SELECT id, slug, title
+FROM events
+WHERE (day = :day OR :day IS NULL)
+  AND slug = COALESCE(:slug, slug)
+ORDER BY id;
+```
+
+```sql
+-- src/queries/events/insert.sql: day has no NOT NULL, so :day takes null.
+INSERT INTO events (slug, title, day)
+VALUES (:slug, :title, :day)
+RETURNING id;
+```
+
 ## Build
 
 ```sh
@@ -100,7 +125,9 @@ migrations and the seeds in order. It reads the enums. Then it serves the
 database on a local port and describes each query through
 [SafeQL](https://safeql.dev): Postgres reports the type of each slot and
 each column, and SafeQL reports whether each column can be null, through
-outer joins, `COALESCE`, aggregates, CTEs, and views.
+outer joins, `COALESCE`, aggregates, CTEs, and views. The kit parses each
+query with [libpg-query](https://github.com/pganalyze/libpg-query-node) and
+reads the columns of the catalog to decide whether each slot can be null.
 
 A file that Postgres rejects fails the build with the file and the error of
 Postgres:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bezoar/kit",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Build kit: SQL in a hermetic Postgres to a typed contract",
   "license": "MIT",
   "repository": {
@@ -32,9 +32,9 @@
     "libpg-query": "18.1.5",
     "objectively": "^0.3.0",
     "postgres": "^3.4.9",
-    "@bezoar/pglite": "0.0.1",
-    "@bezoar/core": "0.0.1",
-    "@bezoar/schema": "0.0.1"
+    "@bezoar/core": "0.0.3",
+    "@bezoar/pglite": "0.0.3",
+    "@bezoar/schema": "0.0.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.9"