@supabase/postgrest-typegen 0.5.0 → 0.7.0

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 : [];
+}

package/src/rpc.ts

@@ -35,6 +35,9 @@ type InputArg = PostgresFunction["args"][number] & {
 
 type Candidate = { fn: PostgresFunction; inArgs: InputArg[] };
 
+/** A NUL separator cannot occur in an identifier, so names with dots never collide. */
+const qualifiedKey = (schema: string, name: string) => `${schema}\0${name}`;
+
 export function resolveRpcFunctions(
   metadata: GeneratorMetadata,
 ): RpcFunction[] {
@@ -48,13 +51,20 @@ export function resolveRpcFunctions(
       )
       .map((type) => [type.id, type]),
   );
+  const relations = [
+    ...metadata.tables,
+    ...metadata.foreignTables,
+    ...metadata.views,
+    ...metadata.materializedViews,
+  ];
   const relationsById = new Map(
-    [
-      ...metadata.tables,
-      ...metadata.foreignTables,
-      ...metadata.views,
-      ...metadata.materializedViews,
-    ].map((relation) => [relation.id, relation]),
+    relations.map((relation) => [relation.id, relation]),
+  );
+  const relationsBySchemaName = new Map(
+    relations.map((relation) => [
+      qualifiedKey(relation.schema, relation.name),
+      relation,
+    ]),
   );
   const columnNamesByRelationId = new Map<number, Set<string>>();
   for (const column of metadata.columns) {
@@ -96,14 +106,13 @@ export function resolveRpcFunctions(
   // the rendered argument list may still name the relation.
   const computedFieldOf = ({ fn, inArgs }: Candidate): number | null => {
     const soleInArg = inArgs.length === 1 ? inArgs[0] : undefined;
-    const argType = soleInArg && relationTypesById.get(soleInArg.type_id);
+    if (!soleInArg) return null;
+    const argType = relationTypesById.get(soleInArg.type_id);
     const relation = argType
       ? relationsById.get(argType.type_relation_id)
-      : [...relationsById.values()].find(
-          (relation) =>
-            relation.schema === fn.schema &&
-            relation.name === fn.argument_types,
-        );
+      : typesById.has(soleInArg.type_id)
+        ? undefined
+        : relationsBySchemaName.get(qualifiedKey(fn.schema, fn.argument_types));
     if (!relation || relation.schema !== fn.schema) return null;
     if (columnNamesByRelationId.get(relation.id)?.has(fn.name)) return null;
     return relation.id;
@@ -178,13 +187,14 @@ export function resolveRpcFunctions(
         }
       }
     }
-    // A sole unnamed row parameter makes the function a computed field, which
-    // PostgREST only exposes under `/rpc` when it also returns rows.
+    // PostgREST passes a sole unnamed parameter only when it is json, jsonb or
+    // text, so a function taking a row this way is a computed field or a
+    // computed relationship, reachable by embedding it from its relation and
+    // never through `/rpc`, whatever it returns.
     if (
       soleInArg &&
       soleInArg.name === "" &&
-      relationTypesById.has(soleInArg.type_id) &&
-      returnRelationName(fn) === null
+      relationTypesById.has(soleInArg.type_id)
     ) {
       return `the function ${fn.schema}.${fn.name} with parameter or with a single unnamed json/jsonb parameter, but no matches were found in the schema cache`;
     }
@@ -205,9 +215,7 @@ export function resolveRpcFunctions(
           ...typeReference(arg.type_id),
           has_default: arg.has_default === true,
           relation_id:
-            relationId !== undefined &&
-            relationId !== null &&
-            relationsById.has(relationId)
+            relationId !== undefined && relationsById.has(relationId)
               ? relationId
               : null,
         };
@@ -266,7 +274,7 @@ export function resolveRpcFunctions(
     );
     const candidate = { fn, inArgs };
     if (!isCallable(candidate)) continue;
-    const key = `${fn.schema}.${fn.name}`;
+    const key = qualifiedKey(fn.schema, fn.name);
     let group = groups.get(key);
     if (!group) {
       group = [];

package/src/types.ts

@@ -205,8 +205,8 @@ const rpcFunctionReturnsSchema = rpcTypeReferenceSchema.merge({
    */
   relation_id: "number | null",
   /**
-   * The columns of a `RETURNS TABLE (…)` or `OUT` parameter result, in name
-   * order; `null` for every other return type.
+   * The columns of a `RETURNS TABLE (…)` result, in name order; `null` for
+   * every other return type, including a record built from `OUT` parameters.
    */
   columns: rpcTypeReferenceSchema.merge({ name: "string" }).array().or("null"),
 });
@@ -245,9 +245,10 @@ const rpcFunctionOverloadSchema = type({
   computed_field_of: "number | null",
   /**
    * Why PostgREST cannot resolve a call to this overload, when it cannot: the
-   * function conflicts with another overload, or it is a computed field that
-   * returns no rows. Generators surface the message instead of a callable
-   * signature.
+   * function conflicts with another overload, or its sole parameter is an
+   * unnamed row, which PostgREST never matches under `/rpc` (the function is
+   * a computed field or computed relationship, reached by embedding).
+   * Generators surface the message instead of a callable signature.
    */
   error: "string | null",
 });