kern-orm 0.15.0 → 0.16.0

package/dist/testing.d.mts

@@ -1 +1,17 @@
-export * from "kern-db/testing";
+import { vt as AnyDb } from "./index-DD_wYhRD.mjs";
+export * from "kern-db/testing";
+/** Mismatch of a table of a `Db` and the database. */
+interface TableMismatch {
+  /** Key of the table in the schema of the `Db`. */
+  readonly table: string;
+  /** What does not match, such as a missing column. */
+  readonly message: string;
+}
+/**
+ * Finds the mismatches of the tables of `db` and its PostgreSQL schema, such as a missing column or a key without a unique index, resolving to an empty array when they match.
+ *
+ * It reads the catalog in the ambient transaction, such as a test transaction in which migrations have created the tables, and requires PostgreSQL 17 or newer.
+ * It checks that each table or view exists with the columns of the table under their physical names and of their types; for a table, also the nullability of each column, a default of each column marked with `hasDefault()`, no other column that every insert must give, a unique index of each key, a unique index of `(true)` of a singleton table, and a foreign key of each required relation `one` to a table.
+ */
+export declare function findTableMismatches(db: AnyDb): Promise<TableMismatch[]>;
+export type { TableMismatch };

package/dist/testing.mjs

@@ -1,2 +1,333 @@
+import { C as formatRelationName, S as collectDefinitions, r as schemaRelations } from "./schema-lVpsWpEF.mjs";
+import * as t from "kern-db/types";
+import { param } from "kern-db";
 export * from "kern-db/testing";
-export {};
+// src/inspection/tables.ts
+const minimumServerVersion = 17e4;
+/**
+* Finds the mismatches of the tables of `db` and its PostgreSQL schema, such as a missing column or a key without a unique index, resolving to an empty array when they match.
+*
+* It reads the catalog in the ambient transaction, such as a test transaction in which migrations have created the tables, and requires PostgreSQL 17 or newer.
+* It checks that each table or view exists with the columns of the table under their physical names and of their types; for a table, also the nullability of each column, a default of each column marked with `hasDefault()`, no other column that every insert must give, a unique index of each key, a unique index of `(true)` of a singleton table, and a foreign key of each required relation `one` to a table.
+*/
+async function findTableMismatches(db) {
+	const database = db.$database;
+	const tables = db.$schema.$tables;
+	const catalog = await readCatalog(database, db.$schemaName, Object.values(tables));
+	const mismatches = [];
+	for (const key of Object.keys(tables)) for (const message of findTableProblems(tables[key], catalog)) mismatches.push({
+		table: key,
+		message
+	});
+	for (const definition of collectDefinitions(db.$schema[schemaRelations])) {
+		const message = findRelationProblem(definition, catalog);
+		if (message !== void 0) mismatches.push({
+			table: definition.key,
+			message
+		});
+	}
+	return mismatches;
+}
+/** Reads the catalog of `tables` in PostgreSQL schema `schemaName`, or in `current_schema()` when it is `undefined`. */
+async function readCatalog(database, schemaName, tables) {
+	const server = await database.query`
+    SELECT current_setting('server_version_num')::integer AS version, current_schema() AS schema
+  `.select({
+		version: t.integer,
+		schema: t.text.nullable()
+	}).take();
+	if (server.version < minimumServerVersion) throw new Error(`findTableMismatches requires PostgreSQL 17 or newer, but the server is ${server.version}`);
+	const resolvedSchema = schemaName ?? server.schema;
+	if (resolvedSchema === null) throw new Error("Cannot resolve the PostgreSQL schema: current_schema() is NULL, since no schema of the search path exists");
+	const names = [...new Set(tables.map((table) => table.name))];
+	const sqlTypes = /* @__PURE__ */ new Set();
+	for (const table of tables) for (const column of Object.values(table.columns)) sqlTypes.add(column.type.sqlType);
+	return {
+		schemaName: resolvedSchema,
+		relations: await readRelations(database, resolvedSchema, names),
+		indexes: await readIndexes(database, resolvedSchema, names),
+		foreignKeys: await readForeignKeys(database, resolvedSchema, names),
+		types: await resolveTypes(database, [...sqlTypes])
+	};
+}
+/** Reads the tables and views of `names` in `schemaName` with their columns. */
+async function readRelations(database, schemaName, names) {
+	const rows = await database.query`
+    SELECT relation.relname::text AS name, relation.relkind::text AS kind,
+      attribute.attname::text AS column_name,
+      pg_catalog.format_type(attribute.atttypid, attribute.atttypmod) AS type,
+      attribute.attnotnull AS rejects_null,
+      attribute.attnotnull AND NOT EXISTS (
+        SELECT FROM pg_catalog.pg_constraint
+        WHERE conrelid = relation.oid AND contype = 'n' AND conkey = ARRAY[attribute.attnum] AND NOT convalidated
+      ) AS not_null_validated,
+      attribute.atthasdef OR attribute.attidentity <> '' OR attribute.attgenerated <> '' AS has_default
+    FROM pg_catalog.pg_class AS relation
+    JOIN pg_catalog.pg_namespace AS namespace ON namespace.oid = relation.relnamespace
+    LEFT JOIN pg_catalog.pg_attribute AS attribute
+      ON attribute.attrelid = relation.oid AND attribute.attnum > 0 AND NOT attribute.attisdropped
+    WHERE namespace.nspname = ${schemaName} AND relation.relname = ANY(${param(t.array(t.text), names)})
+  `.select({
+		name: t.text,
+		kind: t.text,
+		column_name: t.text.nullable(),
+		type: t.text.nullable(),
+		rejects_null: t.boolean.nullable(),
+		not_null_validated: t.boolean.nullable(),
+		has_default: t.boolean.nullable()
+	});
+	const relations = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		let relation = relations.get(row.name);
+		if (relation === void 0) {
+			relation = {
+				kind: row.kind,
+				columns: /* @__PURE__ */ new Map()
+			};
+			relations.set(row.name, relation);
+		}
+		if (row.column_name !== null) relation.columns.set(row.column_name, {
+			type: row.type,
+			rejectsNull: row.rejects_null,
+			notNullValidated: row.not_null_validated,
+			hasDefault: row.has_default
+		});
+	}
+	return relations;
+}
+/** Reads the unique indexes of the tables of `names` in `schemaName` by the names of their tables. */
+async function readIndexes(database, schemaName, names) {
+	const rows = await database.query`
+    SELECT relation.relname::text AS table_name, index_relation.relname::text AS name,
+      ARRAY(
+        SELECT attribute.attname::text
+        FROM generate_series(0, index.indnkeyatts - 1) AS ordinal
+        JOIN pg_catalog.pg_attribute AS attribute
+          ON attribute.attrelid = index.indrelid AND attribute.attnum = index.indkey[ordinal]
+        ORDER BY ordinal
+      ) AS columns,
+      index.indexprs IS NOT NULL AS has_expressions,
+      CASE WHEN index.indnkeyatts = 1 AND index.indkey[0] = 0
+        THEN pg_catalog.pg_get_indexdef(index.indexrelid, 1, true)
+      END AS expression,
+      index.indpred IS NOT NULL AS is_partial,
+      index.indimmediate AS is_immediate,
+      index.indisvalid AND index.indisready AND index.indislive AS is_valid
+    FROM pg_catalog.pg_index AS index
+    JOIN pg_catalog.pg_class AS relation ON relation.oid = index.indrelid
+    JOIN pg_catalog.pg_class AS index_relation ON index_relation.oid = index.indexrelid
+    JOIN pg_catalog.pg_namespace AS namespace ON namespace.oid = relation.relnamespace
+    WHERE index.indisunique AND namespace.nspname = ${schemaName} AND relation.relname = ANY(${param(t.array(t.text), names)})
+    ORDER BY index_relation.relname
+  `.select({
+		table_name: t.text,
+		name: t.text,
+		columns: t.array(t.text),
+		has_expressions: t.boolean,
+		expression: t.text.nullable(),
+		is_partial: t.boolean,
+		is_immediate: t.boolean,
+		is_valid: t.boolean
+	});
+	const indexes = /* @__PURE__ */ new Map();
+	for (const row of rows) addToGroup(indexes, row.table_name, {
+		name: row.name,
+		columns: row.columns,
+		hasExpressions: row.has_expressions,
+		expression: row.expression,
+		partial: row.is_partial,
+		immediate: row.is_immediate,
+		valid: row.is_valid
+	});
+	return indexes;
+}
+/** Reads the foreign keys of the tables of `names` in `schemaName` by the names of their tables. */
+async function readForeignKeys(database, schemaName, names) {
+	const rows = await database.query`
+    SELECT relation.relname::text AS table_name, constraint_.conname::text AS name,
+      target.relname::text AS target_name, target_namespace.nspname::text AS target_schema,
+      ARRAY(
+        SELECT attribute.attname::text
+        FROM unnest(constraint_.conkey) WITH ORDINALITY AS key_column(number, ordinal)
+        JOIN pg_catalog.pg_attribute AS attribute
+          ON attribute.attrelid = constraint_.conrelid AND attribute.attnum = key_column.number
+        ORDER BY key_column.ordinal
+      ) AS from_columns,
+      ARRAY(
+        SELECT attribute.attname::text
+        FROM unnest(constraint_.confkey) WITH ORDINALITY AS key_column(number, ordinal)
+        JOIN pg_catalog.pg_attribute AS attribute
+          ON attribute.attrelid = constraint_.confrelid AND attribute.attnum = key_column.number
+        ORDER BY key_column.ordinal
+      ) AS to_columns,
+      constraint_.condeferrable AS is_deferrable,
+      constraint_.convalidated AS is_validated,
+      coalesce((to_jsonb(constraint_) ->> 'conenforced')::boolean, true) AS is_enforced,
+      coalesce((to_jsonb(constraint_) ->> 'conperiod')::boolean, false) AS is_period
+    FROM pg_catalog.pg_constraint AS constraint_
+    JOIN pg_catalog.pg_class AS relation ON relation.oid = constraint_.conrelid
+    JOIN pg_catalog.pg_namespace AS namespace ON namespace.oid = relation.relnamespace
+    JOIN pg_catalog.pg_class AS target ON target.oid = constraint_.confrelid
+    JOIN pg_catalog.pg_namespace AS target_namespace ON target_namespace.oid = target.relnamespace
+    WHERE constraint_.contype = 'f' AND namespace.nspname = ${schemaName} AND relation.relname = ANY(${param(t.array(t.text), names)})
+    ORDER BY constraint_.conname
+  `.select({
+		table_name: t.text,
+		name: t.text,
+		target_name: t.text,
+		target_schema: t.text,
+		from_columns: t.array(t.text),
+		to_columns: t.array(t.text),
+		is_deferrable: t.boolean,
+		is_validated: t.boolean,
+		is_enforced: t.boolean,
+		is_period: t.boolean
+	});
+	const foreignKeys = /* @__PURE__ */ new Map();
+	for (const row of rows) addToGroup(foreignKeys, row.table_name, {
+		name: row.name,
+		target: row.target_name,
+		targetSchema: row.target_schema,
+		from: row.from_columns,
+		to: row.to_columns,
+		deferrable: row.is_deferrable,
+		validated: row.is_validated,
+		enforced: row.is_enforced,
+		period: row.is_period
+	});
+	return foreignKeys;
+}
+/**
+* Resolves `sqlTypes` in the search path of the connection, as the casts of queries do, to `format_type` of their types and type modifiers, or to `null` for a type that does not exist.
+*
+* `format_type` gives one text of each type and modifier, qualified when the search path does not find the type, so that aliases, such as `int4` and `integer`, give the same text.
+*/
+async function resolveTypes(database, sqlTypes) {
+	const rows = await database.query`
+    SELECT sql_type, pg_catalog.format_type(to_regtype(sql_type), to_regtypemod(sql_type)) AS type
+    FROM unnest(${param(t.array(t.text), sqlTypes)}) AS sql_type
+  `.select({
+		sql_type: t.text,
+		type: t.text.nullable()
+	});
+	const types = /* @__PURE__ */ new Map();
+	for (const row of rows) types.set(row.sql_type, row.type);
+	return types;
+}
+/** Returns the problems of `table` in `catalog`, such as a missing column. */
+function findTableProblems(table, catalog) {
+	const relation = catalog.relations.get(table.name);
+	if (relation === void 0) return [`Table "${table.name}" does not exist in schema "${catalog.schemaName}"`];
+	const isView = isViewKind(relation.kind);
+	if (!isView && !isTableKind(relation.kind)) return [`"${table.name}" in schema "${catalog.schemaName}" is not a table or a view`];
+	const problems = [];
+	const definedNames = /* @__PURE__ */ new Set();
+	for (const key of Object.keys(table.columns)) {
+		const column = table.columns[key];
+		const name = getColumnName(column, key);
+		definedNames.add(name);
+		const subject = formatColumn(key, name);
+		const actual = relation.columns.get(name);
+		if (actual === void 0) {
+			problems.push(`${subject} does not exist`);
+			continue;
+		}
+		const expectedType = catalog.types.get(column.type.sqlType);
+		if (expectedType === null) problems.push(`${subject} is of type "${column.type.sqlType}", which does not exist`);
+		else if (expectedType !== actual.type) problems.push(`${subject} is of type ${actual.type} rather than ${expectedType}`);
+		if (isView) continue;
+		if (column.type.isNullable && actual.rejectsNull) problems.push(`${subject} is NOT NULL, but the table defines it as nullable`);
+		else if (!column.type.isNullable && !actual.notNullValidated) problems.push(actual.rejectsNull ? `${subject} has a NOT VALID not-null constraint, so existing rows may hold NULL, but the table defines it as not nullable` : `${subject} is nullable, but the table defines it as not nullable`);
+		if (column.attributes.hasDefault && !actual.hasDefault) problems.push(`${subject} has no default, but the table marks it with hasDefault()`);
+	}
+	if (isView) return problems;
+	for (const [name, actual] of relation.columns) if (!definedNames.has(name) && actual.rejectsNull && !actual.hasDefault) problems.push(`Column "${name}" is NOT NULL without a default, so every insert of the table, which does not define it, fails`);
+	const indexes = catalog.indexes.get(table.name) ?? [];
+	const { primaryKey, unique } = table.keys;
+	if (primaryKey !== void 0) pushDefined(problems, findKeyProblem(table, "Primary key", primaryKey, indexes));
+	for (const key of unique) pushDefined(problems, findKeyProblem(table, "Unique key", key, indexes));
+	if (table.singleton) pushDefined(problems, findArbiterProblem("Singleton table", "unique index of (true)", indexes.filter((index) => index.expression === "(true)")));
+	return problems;
+}
+/**
+* Returns the problem of key `columns` of `table`, or `undefined` when a unique index backs it.
+*
+* The indexes are those that PostgreSQL infers as the arbiters of `ON CONFLICT` of the columns of the key, which `onConflict` and `upsert` build: of the same set of columns, in any order, without expressions or a predicate, and valid.
+* One of them must exist, and none may be deferrable, since PostgreSQL rejects the insert of a deferrable arbiter.
+*/
+function findKeyProblem(table, kind, columns, indexes) {
+	const names = new Set(columns.map((key) => getColumnName(table.columns[key], key)));
+	const matching = indexes.filter((index) => {
+		const indexColumns = new Set(index.columns);
+		return !index.hasExpressions && indexColumns.size === names.size && index.columns.every((name) => names.has(name));
+	});
+	return findArbiterProblem(`${kind} (${columns.join(", ")})`, "unique index", matching);
+}
+/** Returns the problem of `subject` when the indexes of `matching` cannot serve as its arbiters of `ON CONFLICT`, or `undefined` when they can. */
+function findArbiterProblem(subject, description, matching) {
+	const arbiters = matching.filter((index) => index.valid && !index.partial);
+	const deferrable = arbiters.find((index) => !index.immediate);
+	if (deferrable !== void 0) return `${subject} has deferrable ${description} "${deferrable.name}", which ON CONFLICT rejects as an arbiter`;
+	if (arbiters.length > 0) return;
+	if (matching.length === 0) return `${subject} has no ${description}`;
+	const index = matching[0];
+	const flaws = [];
+	if (index.partial) flaws.push("partial");
+	if (!index.valid) flaws.push("not valid");
+	return `${subject} has no usable ${description}: "${index.name}" is ${flaws.join(" and ")}`;
+}
+/** Returns the problem of a required relation `one` of `definition` to a table, or `undefined` when a foreign key backs it or the relation is not checked. */
+function findRelationProblem(definition, catalog) {
+	if (definition.kind !== "one" || !definition.required) return;
+	const { source, target } = definition;
+	for (const table of [source, target]) {
+		const relation = catalog.relations.get(table.name);
+		if (relation === void 0 || !isTableKind(relation.kind)) return;
+	}
+	const pairs = /* @__PURE__ */ new Set();
+	for (let index = 0; index < definition.from.length; index++) {
+		const fromKey = definition.from[index];
+		const toKey = definition.to[index];
+		pairs.add(formatPair(getColumnName(source.columns[fromKey], fromKey), getColumnName(target.columns[toKey], toKey)));
+	}
+	const matching = (catalog.foreignKeys.get(source.name) ?? []).filter((foreignKey) => foreignKey.target === target.name && foreignKey.targetSchema === catalog.schemaName && foreignKey.from.length === pairs.size && foreignKey.from.every((name, index) => pairs.has(formatPair(name, foreignKey.to[index]))));
+	const subject = `Required relation ${formatRelationName(definition.key, definition.name)}`;
+	if (matching.some((foreignKey) => !foreignKey.deferrable && foreignKey.validated && foreignKey.enforced && !foreignKey.period)) return;
+	if (matching.length === 0) return `${subject} has no foreign key of its columns`;
+	const foreignKey = matching[0];
+	const flaws = [];
+	if (foreignKey.deferrable) flaws.push("deferrable");
+	if (!foreignKey.validated) flaws.push("not valid");
+	if (!foreignKey.enforced) flaws.push("not enforced");
+	if (foreignKey.period) flaws.push("of a period");
+	return `${subject} has no usable foreign key of its columns: "${foreignKey.name}" is ${flaws.join(" and ")}`;
+}
+/** Returns the physical name of `column` under `key`. */
+function getColumnName(column, key) {
+	return column.attributes.name ?? key;
+}
+/** Returns the subject of a message of the column of `key`, with its physical name when it differs. */
+function formatColumn(key, name) {
+	return key === name ? `Column "${key}"` : `Column "${key}" (${name})`;
+}
+/** Returns a key of a pair of the names of a source column and a target column; a name cannot contain a NUL character. */
+function formatPair(from, to) {
+	return `${from}\0${to}`;
+}
+/** Whether `relkind` is of a table: ordinary, partitioned, or foreign. */
+function isTableKind(kind) {
+	return kind === "r" || kind === "p" || kind === "f";
+}
+/** Whether `relkind` is of a view or a materialized view. */
+function isViewKind(kind) {
+	return kind === "v" || kind === "m";
+}
+function addToGroup(groups, key, item) {
+	const group = groups.get(key);
+	if (group === void 0) groups.set(key, [item]);
+	else group.push(item);
+}
+function pushDefined(problems, problem) {
+	if (problem !== void 0) problems.push(problem);
+}
+export { findTableMismatches };

package/dist/types.d.mts

@@ -1,4 +1,4 @@
-import { $i as BaseType, ct as TextTypeOperators, da as MergeOperators, ea as Type, fa as NoOperators, fi as EqualityOperator, ft as AnyExpression, hi as InSignature, ma as GenericOperator, mi as HasEquality, oa as Column, pa as OperatorDefinitions, pi as EqualityOperators, st as TextOperators, ut as NumberTypeOperators, vi as ComparisonSignature } from "./index-DFcelQx0.mjs";
+import { $i as BaseType, ct as TextTypeOperators, da as MergeOperators, ea as Type, fa as NoOperators, fi as EqualityOperator, ft as AnyExpression, hi as InSignature, ma as GenericOperator, mi as HasEquality, oa as Column, pa as OperatorDefinitions, pi as EqualityOperators, st as TextOperators, ut as NumberTypeOperators, vi as ComparisonSignature } from "./index-DD_wYhRD.mjs";
 /**
  * Creates a one-dimensional array type of `element` values.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-orm",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Fully typed relational query builder for PostgreSQL with ambient transactions and single-query relation loading",
   "keywords": [
     "orm",
@@ -45,7 +45,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "kern-db": "^0.6.0"
+    "kern-db": "^0.6.1"
   },
   "devDependencies": {
     "@kern-orm/test-harness": "workspace:*",