@supabase/postgrest-typegen 0.4.0 → 0.6.0

package/src/introspection/index.ts

@@ -2,6 +2,7 @@ import {
   GENERATOR_METADATA_VERSION,
   type GeneratorMetadata,
 } from "../types.ts";
+import { resolveRpcFunctions } from "../rpc.ts";
 import { normalizeRows } from "./normalize.ts";
 import { listRelationships } from "./relationships.ts";
 import { COLUMNS_SQL } from "./sql/columns.sql.ts";
@@ -13,7 +14,9 @@ import { PRIMARY_KEYS_SQL } from "./sql/primary_keys.sql.ts";
 import { SCHEMAS_SQL } from "./sql/schemas.sql.ts";
 import { TABLES_SQL } from "./sql/table.sql.ts";
 import { TYPES_SQL } from "./sql/types.sql.ts";
+import { VIEW_DEFINITIONS_SQL } from "./sql/view_definitions.sql.ts";
 import { VIEWS_SQL } from "./sql/views.sql.ts";
+import { applyViewColumnNullability } from "./view-nullability.ts";
 
 /**
  * Minimal structural database interface. `pg.Pool` / `pg.Client` satisfy it,
@@ -71,6 +74,7 @@ export async function introspect(
     relationships,
     functions,
     types,
+    viewDefinitions,
   ] = await Promise.all([
     queryRows(SCHEMAS_SQL({ schemaFilter: systemExcludingFilter })),
     queryRows(TABLES_SQL({ schemaFilter: systemExcludingFilter })),
@@ -82,16 +86,17 @@ export async function introspect(
     listRelationships(db, systemExcludingFilter),
     queryRows(FUNCTIONS_SQL({ schemaFilter: systemExcludingFilter })),
     queryRows(TYPES_SQL),
+    queryRows(VIEW_DEFINITIONS_SQL({ schemaFilter: systemExcludingFilter })),
   ]);
 
-  return {
+  const metadata = {
     version: GENERATOR_METADATA_VERSION,
     schemas,
     tables,
     foreignTables,
     views,
     materializedViews,
-    columns,
+    columns: applyViewColumnNullability(columns, viewDefinitions),
     primaryKeys,
     relationships,
     functions: functions.filter(
@@ -99,4 +104,5 @@ export async function introspect(
     ),
     types,
   } as GeneratorMetadata;
+  return { ...metadata, rpcFunctions: resolveRpcFunctions(metadata) };
 }

package/src/introspection/node-tree.ts

@@ -0,0 +1,129 @@
+/**
+ * A value in the text form of a `pg_node_tree`: a scalar token, `null` for
+ * `<>`, a list, or a node. Integer, OID and bitmapset lists (`(i 1 2)`,
+ * `(o 23)`, `(b 3)`) lose their marker and become lists of scalar tokens.
+ */
+export type NodeTreeValue = string | null | NodeTreeValue[] | NodeTreeNode;
+
+export interface NodeTreeNode {
+  type: string;
+  fields: Record<string, NodeTreeValue>;
+}
+
+interface Token {
+  raw: string;
+  text: string;
+}
+
+const LIST_MARKERS = new Set(["i", "o", "b", "x"]);
+const WHITESPACE = " \t\n";
+const PUNCTUATION = "(){}";
+
+/**
+ * Parse the text form of a `pg_node_tree` (for example
+ * `pg_rewrite.ev_action::text`), following the tokenizer of PostgreSQL's
+ * `read.c`: tokens are separated by whitespace, `(`, `)`, `{` and `}` are
+ * tokens of their own, and a backslash escapes the next character.
+ */
+export function parseNodeTree(text: string): NodeTreeValue {
+  const tokens = tokenize(text);
+  let position = 0;
+
+  const peek = (): Token | undefined => tokens[position];
+  const next = (): Token => {
+    const token = tokens[position++];
+    if (token === undefined) {
+      throw new Error("Unexpected end of pg_node_tree");
+    }
+    return token;
+  };
+  const isFieldEnd = (token: Token | undefined) =>
+    token === undefined || token.raw === "}" || token.raw.startsWith(":");
+
+  const parseValue = (): NodeTreeValue => {
+    const token = next();
+    if (token.raw === "{") {
+      const type = next().text;
+      const fields: Record<string, NodeTreeValue> = {};
+      while (peek()?.raw !== "}") {
+        const name = next().raw.slice(1);
+        fields[name] = isFieldEnd(peek()) ? null : parseValue();
+        // Some fields span several tokens, such as a constant's
+        // `:constvalue 4 [ 1 0 0 0 ]`; only the first one is kept.
+        while (!isFieldEnd(peek())) {
+          parseValue();
+        }
+      }
+      next();
+      return { type, fields };
+    }
+    if (token.raw === "(") {
+      const items: NodeTreeValue[] = [];
+      const first = peek();
+      if (first !== undefined && LIST_MARKERS.has(first.raw)) {
+        next();
+      }
+      while (peek()?.raw !== ")") {
+        items.push(parseValue());
+      }
+      next();
+      return items;
+    }
+    if (token.raw === "<>") {
+      return null;
+    }
+    return token.text;
+  };
+
+  const value = parseValue();
+  if (position !== tokens.length) {
+    throw new Error("Trailing tokens after pg_node_tree");
+  }
+  return value;
+}
+
+function tokenize(text: string): Token[] {
+  const tokens: Token[] = [];
+  let index = 0;
+  while (index < text.length) {
+    const character = text.charAt(index);
+    if (WHITESPACE.includes(character)) {
+      index++;
+      continue;
+    }
+    if (PUNCTUATION.includes(character)) {
+      tokens.push({ raw: character, text: character });
+      index++;
+      continue;
+    }
+    const start = index;
+    let unescaped = "";
+    while (index < text.length) {
+      const current = text.charAt(index);
+      if (current === "\\" && index + 1 < text.length) {
+        unescaped += text.charAt(index + 1);
+        index += 2;
+        continue;
+      }
+      if (WHITESPACE.includes(current) || PUNCTUATION.includes(current)) {
+        break;
+      }
+      unescaped += current;
+      index++;
+    }
+    tokens.push({ raw: text.slice(start, index), text: unescaped });
+  }
+  return tokens;
+}
+
+export function isNode(
+  value: NodeTreeValue | undefined,
+  type?: string,
+): value is NodeTreeNode {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    (type === undefined || value.type === type)
+  );
+}

package/src/introspection/sql/view_definitions.sql.ts

@@ -0,0 +1,45 @@
+import type { SchemaFilterProps } from "./common.ts";
+
+/**
+ * The query tree of every view and materialized view in the filtered schemas,
+ * plus every view they read from in any schema, with the `NOT NULL` columns
+ * each one references. `inferNonNullViewColumns` resolves view column
+ * nullability from it.
+ */
+export const VIEW_DEFINITIONS_SQL = (props: SchemaFilterProps) => /* SQL */ `
+WITH RECURSIVE view_closure(oid) AS (
+  SELECT c.oid
+  FROM pg_class c
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE
+    ${props.schemaFilter ? `n.nspname ${props.schemaFilter} AND` : ""}
+    c.relkind IN ('v', 'm')
+  UNION
+  SELECT dep.refobjid
+  FROM view_closure vc
+  JOIN pg_rewrite r ON r.ev_class = vc.oid AND r.rulename = '_RETURN'
+  JOIN pg_depend dep ON dep.classid = 'pg_rewrite' :: regclass
+    AND dep.objid = r.oid
+    AND dep.refclassid = 'pg_class' :: regclass
+  JOIN pg_class rc ON rc.oid = dep.refobjid AND rc.relkind IN ('v', 'm')
+)
+SELECT
+  r.ev_class :: int8 AS view_id,
+  r.ev_action :: text AS definition,
+  COALESCE(
+    (
+      SELECT json_agg(json_build_array(dep.refobjid :: int8, dep.refobjsubid))
+      FROM pg_depend dep
+      JOIN pg_attribute a ON a.attrelid = dep.refobjid AND a.attnum = dep.refobjsubid
+      JOIN pg_type t ON t.oid = a.atttypid
+      WHERE dep.classid = 'pg_rewrite' :: regclass
+        AND dep.objid = r.oid
+        AND dep.refclassid = 'pg_class' :: regclass
+        AND dep.refobjsubid > 0
+        AND (a.attnotnull OR t.typtype = 'd' AND t.typnotnull)
+    ),
+    '[]'
+  ) AS non_null_columns
+FROM view_closure vc
+JOIN pg_rewrite r ON r.ev_class = vc.oid AND r.rulename = '_RETURN'
+`;

package/src/introspection/view-nullability.ts

@@ -0,0 +1,243 @@
+import type { PostgresColumn } from "../types.ts";
+import {
+  isNode,
+  type NodeTreeNode,
+  type NodeTreeValue,
+  parseNodeTree,
+} from "./node-tree.ts";
+
+/** A row of `VIEW_DEFINITIONS_SQL`. */
+export interface ViewDefinitionRow {
+  view_id: number | string;
+  definition: string;
+  non_null_columns: [number | string, number | string][];
+}
+
+const RTE_RELATION = "0";
+const RTE_SUBQUERY = "1";
+const RTE_JOIN = "2";
+const RTE_CTE = "6";
+const RTE_GROUP = "9";
+
+const JOIN_INNER = "0";
+const JOIN_LEFT = "1";
+const JOIN_RIGHT = "3";
+
+const NOT_NULL_DIRECTIVE = /^\s*@notNull\s*$/m;
+
+/**
+ * Mark view and materialized view columns as not nullable when PostgreSQL can
+ * prove it from the view's query tree (see {@link inferNonNullViewColumns}) or
+ * when the column comment has an `@notNull` line. PostgreSQL never sets
+ * `attnotnull` on view columns, so without this every one of them is nullable.
+ */
+export function applyViewColumnNullability<T extends PostgresColumn>(
+  columns: T[],
+  rows: ViewDefinitionRow[],
+): T[] {
+  const viewIds = new Set(rows.map((row) => String(row.view_id)));
+  const nonNull = inferNonNullViewColumns(rows);
+  return columns.map((column) =>
+    column.is_nullable &&
+    viewIds.has(String(column.table_id)) &&
+    (nonNull.has(column.id) || NOT_NULL_DIRECTIVE.test(column.comment ?? ""))
+      ? { ...column, is_nullable: false }
+      : column,
+  );
+}
+
+/**
+ * The ids (`<view oid>.<attnum>`) of the view columns that can never be null.
+ * A column qualifies when it is a plain reference to a `NOT NULL` column, or
+ * to a view column that qualifies, followed through joins, subqueries,
+ * non-recursive CTEs and `GROUP BY`, and nothing on the way puts it on the
+ * nullable side of an outer join, in a set operation or under grouping sets.
+ * The outer-join check walks the join tree instead of reading
+ * `varnullingrels`, which PostgreSQL 15 does not have.
+ */
+function inferNonNullViewColumns(rows: ViewDefinitionRow[]): Set<string> {
+  const definitions = new Map(
+    rows.map((row) => [String(row.view_id), row.definition]),
+  );
+  const nonNullBaseColumns = new Set(
+    rows.flatMap((row) =>
+      row.non_null_columns.map(([relation, attnum]) => `${relation}.${attnum}`),
+    ),
+  );
+  const resolved = new Map<string, Set<number>>();
+  const nullableIndexesByQuery = new Map<NodeTreeNode, Set<number>>();
+  const nullableIndexesOf = (query: NodeTreeNode): Set<number> => {
+    let indexes = nullableIndexesByQuery.get(query);
+    if (indexes === undefined) {
+      indexes = nullableRangeTableIndexes(query);
+      nullableIndexesByQuery.set(query, indexes);
+    }
+    return indexes;
+  };
+
+  const nonNullColumnsOfView = (viewId: string): Set<number> => {
+    const cached = resolved.get(viewId);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const columns = new Set<number>();
+    resolved.set(viewId, columns);
+    try {
+      const tree = parseNodeTree(definitions.get(viewId) ?? "");
+      const query = Array.isArray(tree) ? tree[0] : tree;
+      if (isNode(query, "QUERY") && allowsNonNull(query)) {
+        for (const entry of list(query.fields.targetList)) {
+          if (
+            isNode(entry, "TARGETENTRY") &&
+            entry.fields.resjunk !== "true" &&
+            isNonNullExpression(entry.fields.expr, [query])
+          ) {
+            columns.add(Number(entry.fields.resno));
+          }
+        }
+      }
+    } catch {
+      columns.clear();
+    }
+    return columns;
+  };
+
+  const isNonNullColumn = (relation: string, attnum: number): boolean =>
+    definitions.has(relation)
+      ? nonNullColumnsOfView(relation).has(attnum)
+      : nonNullBaseColumns.has(`${relation}.${attnum}`);
+
+  const isNonNullExpression = (
+    expression: NodeTreeValue | undefined,
+    queries: NodeTreeNode[],
+  ): boolean => {
+    const query = queries.at(-1);
+    if (
+      query === undefined ||
+      !isNode(expression, "VAR") ||
+      expression.fields.varlevelsup !== "0"
+    ) {
+      return false;
+    }
+    const varno = Number(expression.fields.varno);
+    const attnum = Number(expression.fields.varattno);
+    if (attnum <= 0 || nullableIndexesOf(query).has(varno)) {
+      return false;
+    }
+    const entry = list(query.fields.rtable)[varno - 1];
+    if (!isNode(entry, "RANGETBLENTRY")) {
+      return false;
+    }
+    switch (entry.fields.rtekind) {
+      case RTE_RELATION:
+        return (
+          typeof entry.fields.relid === "string" &&
+          isNonNullColumn(entry.fields.relid, attnum)
+        );
+      case RTE_SUBQUERY:
+        return isNonNullOutput(entry.fields.subquery, attnum, queries);
+      case RTE_JOIN:
+        return isNonNullExpression(
+          list(entry.fields.joinaliasvars)[attnum - 1],
+          queries,
+        );
+      case RTE_GROUP:
+        return isNonNullExpression(
+          list(entry.fields.groupexprs)[attnum - 1],
+          queries,
+        );
+      case RTE_CTE: {
+        const levelsUp = Number(entry.fields.ctelevelsup);
+        const owner = queries.at(-1 - levelsUp);
+        const cte = list(owner?.fields.cteList).find(
+          (candidate) =>
+            isNode(candidate, "COMMONTABLEEXPR") &&
+            candidate.fields.ctename === entry.fields.ctename,
+        );
+        return (
+          isNode(cte) &&
+          cte.fields.cterecursive !== "true" &&
+          isNonNullOutput(
+            cte.fields.ctequery,
+            attnum,
+            queries.slice(0, queries.length - levelsUp),
+          )
+        );
+      }
+      default:
+        return false;
+    }
+  };
+
+  const isNonNullOutput = (
+    subquery: NodeTreeValue | undefined,
+    resno: number,
+    queries: NodeTreeNode[],
+  ): boolean => {
+    if (!isNode(subquery, "QUERY") || !allowsNonNull(subquery)) {
+      return false;
+    }
+    const entry = list(subquery.fields.targetList).find(
+      (candidate) =>
+        isNode(candidate, "TARGETENTRY") &&
+        Number(candidate.fields.resno) === resno,
+    );
+    return (
+      isNode(entry) &&
+      isNonNullExpression(entry.fields.expr, [...queries, subquery])
+    );
+  };
+
+  const result = new Set<string>();
+  for (const viewId of definitions.keys()) {
+    for (const attnum of nonNullColumnsOfView(viewId)) {
+      result.add(`${viewId}.${attnum}`);
+    }
+  }
+  return result;
+}
+
+function allowsNonNull(query: NodeTreeNode): boolean {
+  return (
+    query.fields.setOperations === null &&
+    list(query.fields.groupingSets).length === 0
+  );
+}
+
+/**
+ * The range table indexes that sit on the nullable side of an outer join in
+ * the query's join tree, including the indexes of nested joins themselves.
+ */
+function nullableRangeTableIndexes(query: NodeTreeNode): Set<number> {
+  const nullable = new Set<number>();
+  const visit = (node: NodeTreeValue | undefined, isNullable: boolean) => {
+    if (isNode(node, "RANGETBLREF")) {
+      if (isNullable) {
+        nullable.add(Number(node.fields.rtindex));
+      }
+    } else if (isNode(node, "FROMEXPR")) {
+      for (const item of list(node.fields.fromlist)) {
+        visit(item, isNullable);
+      }
+    } else if (isNode(node, "JOINEXPR")) {
+      const joinType = node.fields.jointype;
+      if (isNullable) {
+        nullable.add(Number(node.fields.rtindex));
+      }
+      visit(
+        node.fields.larg,
+        isNullable || (joinType !== JOIN_INNER && joinType !== JOIN_LEFT),
+      );
+      visit(
+        node.fields.rarg,
+        isNullable || (joinType !== JOIN_INNER && joinType !== JOIN_RIGHT),
+      );
+    }
+  };
+  visit(query.fields.jointree, false);
+  return nullable;
+}
+
+function list(value: NodeTreeValue | undefined): NodeTreeValue[] {
+  return Array.isArray(value) ? value : [];
+}