@supabase/postgrest-typegen 0.4.0 → 0.6.0

package/src/rpc.ts

@@ -0,0 +1,307 @@
+/**
+ * Resolves the PostgREST view of `GeneratorMetadata.functions`.
+ *
+ * The raw `functions` collection is `pg_proc` as introspected. Which of those
+ * functions PostgREST exposes under `/rpc`, how their overloads group, what a
+ * call returns and whether a function doubles as a computed field or an
+ * embeddable relation are PostgREST rules, not language rules. This pass
+ * applies them once so every generator, in this package or in another SDK
+ * repo reading the serialized document, emits the same RPC surface.
+ *
+ * Pure and deterministic: the output is canonically ordered regardless of the
+ * order of the input collections. `introspect()` attaches the result as
+ * `rpcFunctions`; generators that meet a document without it (produced by a
+ * version predating the collection, or by a custom producer) run this pass
+ * themselves.
+ */
+import { compareStrings } from "./collation.ts";
+import type {
+  GeneratorMetadata,
+  PostgresFunction,
+  PostgresType,
+  RpcFunction,
+  RpcFunctionArg,
+  RpcFunctionOverload,
+  RpcTypeReference,
+} from "./types.ts";
+
+/** json, jsonb and text: the types PostgREST accepts for a single unnamed parameter. */
+const UNNAMED_ARG_TYPE_IDS = new Set([114, 3802, 25]);
+const INPUT_ARG_MODES = new Set(["in", "inout", "variadic"]);
+
+type InputArg = PostgresFunction["args"][number] & {
+  mode: RpcFunctionArg["mode"];
+};
+
+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[] {
+  const schemaNames = new Set(metadata.schemas.map(({ name }) => name));
+  const typesById = new Map(metadata.types.map((type) => [type.id, type]));
+  const relationTypesById = new Map(
+    metadata.types
+      .filter(
+        (type): type is PostgresType & { type_relation_id: number } =>
+          type.type_relation_id !== null,
+      )
+      .map((type) => [type.id, type]),
+  );
+  const relations = [
+    ...metadata.tables,
+    ...metadata.foreignTables,
+    ...metadata.views,
+    ...metadata.materializedViews,
+  ];
+  const relationsById = new Map(
+    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) {
+    let names = columnNamesByRelationId.get(column.table_id);
+    if (!names) {
+      names = new Set();
+      columnNamesByRelationId.set(column.table_id, names);
+    }
+    names.add(column.name);
+  }
+
+  const typeReference = (typeId: number): RpcTypeReference => {
+    const type = typesById.get(typeId);
+    return {
+      type_id: typeId,
+      format: type?.name ?? null,
+      type_schema: type?.schema ?? null,
+    };
+  };
+  const typeName = (typeId: number) => typesById.get(typeId)?.name ?? "unknown";
+
+  // The relation a return type stands for, or a composite type's name when the
+  // return type is one, since both are relations in `pg_class`. Resolved
+  // against every schema: a function may return rows of another schema.
+  const returnRelationName = (fn: PostgresFunction): string | null => {
+    if (fn.return_type_relation_id === null) return null;
+    return (
+      relationsById.get(fn.return_type_relation_id)?.name ??
+      relationTypesById.get(fn.return_type_id)?.name ??
+      null
+    );
+  };
+
+  // The function is a computed field of the relation whose row type its sole
+  // input parameter has, provided the relation lives in the function's schema
+  // and has no column of the function's name: PostgREST resolves the name to
+  // the column, so such a function is neither selectable nor part of `Row`.
+  // When the parameter's type is not in `types` (a reduced custom document),
+  // the rendered argument list may still name the relation.
+  const computedFieldOf = ({ fn, inArgs }: Candidate): number | null => {
+    const soleInArg = inArgs.length === 1 ? inArgs[0] : undefined;
+    if (!soleInArg) return null;
+    const argType = relationTypesById.get(soleInArg.type_id);
+    const relation = argType
+      ? relationsById.get(argType.type_relation_id)
+      : 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;
+  };
+
+  const isCallable = ({ inArgs }: Candidate): boolean => {
+    if (inArgs.length === 0) return true;
+    if (!inArgs.some(({ name }) => name === "")) return true;
+    if (
+      inArgs.every(
+        (arg) =>
+          arg.name !== "" ||
+          (arg.has_default === true && UNNAMED_ARG_TYPE_IDS.has(arg.type_id)),
+      )
+    ) {
+      return true;
+    }
+    const soleInArg = inArgs.length === 1 ? inArgs[0] : undefined;
+    return (
+      soleInArg !== undefined &&
+      soleInArg.name === "" &&
+      (UNNAMED_ARG_TYPE_IDS.has(soleInArg.type_id) ||
+        relationTypesById.has(soleInArg.type_id))
+    );
+  };
+
+  const overloadError = (
+    candidate: Candidate,
+    group: Candidate[],
+  ): string | null => {
+    const { fn, inArgs } = candidate;
+    const soleInArg = inArgs.length === 1 ? inArgs[0] : undefined;
+    if (group.length > 1) {
+      // A no-argument overload next to one whose sole unnamed parameter has a
+      // default: PostgREST cannot pick one for an empty call.
+      if (inArgs.length === 0) {
+        const conflicting = group.find(
+          (other) =>
+            other !== candidate &&
+            other.inArgs.length === 1 &&
+            other.inArgs[0]?.name === "" &&
+            other.inArgs[0].has_default === true,
+        );
+        if (conflicting) {
+          return `Could not choose the best candidate function between: ${fn.schema}.${fn.name}(), ${fn.schema}.${fn.name}( => ${typeName(conflicting.fn.return_type_id)}). Try renaming the parameters or the function itself in the database so function overloading can be resolved`;
+        }
+      }
+      // Overloads whose sole parameter shares a name but not a type: a call
+      // carries no type information, so PostgREST cannot pick one.
+      if (soleInArg && soleInArg.name !== "") {
+        const conflicting = group.filter(
+          (other) =>
+            other !== candidate &&
+            other.inArgs.length === 1 &&
+            other.inArgs[0]?.name === soleInArg.name &&
+            other.inArgs[0].type_id !== soleInArg.type_id,
+        );
+        if (conflicting.length > 0) {
+          const conflictList = [candidate, ...conflicting]
+            .sort(
+              (a, b) =>
+                (a.inArgs[0]?.type_id || 0) - (b.inArgs[0]?.type_id || 0),
+            )
+            .map(
+              (other) =>
+                `${fn.schema}.${fn.name}(${other.inArgs
+                  .map((arg) => `${arg.name} => ${typeName(arg.type_id)}`)
+                  .join(", ")})`,
+            )
+            .join(", ");
+          return `Could not choose the best candidate function between: ${conflictList}. Try renaming the parameters or the function itself in the database so function overloading can be resolved`;
+        }
+      }
+    }
+    // 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)
+    ) {
+      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`;
+    }
+    return null;
+  };
+
+  const resolveOverload = (
+    candidate: Candidate,
+    group: Candidate[],
+  ): RpcFunctionOverload => {
+    const { fn, inArgs } = candidate;
+    const args: RpcFunctionArg[] = inArgs
+      .map((arg) => {
+        const relationId = relationTypesById.get(arg.type_id)?.type_relation_id;
+        return {
+          name: arg.name,
+          mode: arg.mode,
+          ...typeReference(arg.type_id),
+          has_default: arg.has_default === true,
+          relation_id:
+            relationId !== undefined && relationsById.has(relationId)
+              ? relationId
+              : null,
+        };
+      })
+      .sort((a, b) => compareStrings(a.name, b.name));
+
+    const tableColumns = fn.args
+      .filter(({ mode }) => mode === "table")
+      .map(({ name, type_id }) => ({ name, ...typeReference(type_id) }))
+      .sort((a, b) => compareStrings(a.name, b.name));
+
+    const relationName = returnRelationName(fn);
+    const returnsMultipleRows = fn.prorows !== null && fn.prorows > 1;
+    // A function whose sole parameter (of any mode) is a row type is embedded
+    // from that relation; any other row-returning function embeds from `*`.
+    const soleArg = fn.args.length === 1 ? fn.args[0] : undefined;
+    const sourceType = soleArg && relationTypesById.get(soleArg.type_id);
+    const setofOptions =
+      relationName === null
+        ? null
+        : {
+            from: sourceType ? sourceType.format : "*",
+            to: relationName,
+            is_one_to_one:
+              sourceType && !fn.is_set_returning_function
+                ? true
+                : !returnsMultipleRows,
+            is_setof_return: fn.is_set_returning_function,
+          };
+
+    return {
+      function_id: fn.id,
+      args,
+      returns: {
+        ...typeReference(fn.return_type_id),
+        relation_id:
+          fn.return_type_relation_id !== null &&
+          relationsById.has(fn.return_type_relation_id)
+            ? fn.return_type_relation_id
+            : null,
+        columns: tableColumns.length > 0 ? tableColumns : null,
+      },
+      is_set_returning: fn.is_set_returning_function,
+      rows_estimate: fn.prorows,
+      setof_options: setofOptions,
+      computed_field_of: computedFieldOf(candidate),
+      error: overloadError(candidate, group),
+    };
+  };
+
+  const groups = new Map<string, Candidate[]>();
+  for (const fn of metadata.functions) {
+    if (!schemaNames.has(fn.schema)) continue;
+    const inArgs = fn.args.filter((arg): arg is InputArg =>
+      INPUT_ARG_MODES.has(arg.mode),
+    );
+    const candidate = { fn, inArgs };
+    if (!isCallable(candidate)) continue;
+    const key = qualifiedKey(fn.schema, fn.name);
+    let group = groups.get(key);
+    if (!group) {
+      group = [];
+      groups.set(key, group);
+    }
+    group.push(candidate);
+  }
+
+  return [...groups.values()]
+    .map((group) => {
+      const sorted = [...group].sort(
+        (a, b) =>
+          compareStrings(a.fn.argument_types, b.fn.argument_types) ||
+          compareStrings(a.fn.return_type, b.fn.return_type) ||
+          a.fn.id - b.fn.id,
+      );
+      const [{ fn }] = sorted as [Candidate, ...Candidate[]];
+      return {
+        schema: fn.schema,
+        name: fn.name,
+        overloads: sorted.map((candidate) =>
+          resolveOverload(candidate, sorted),
+        ),
+      };
+    })
+    .sort(
+      (a, b) =>
+        compareStrings(a.schema, b.schema) || compareStrings(a.name, b.name),
+    );
+}

package/src/sort.ts

@@ -117,5 +117,36 @@ export function sortGeneratorMetadata(
         args: [...fn.args].sort((a, b) => compareStrings(a.name, b.name)),
       })),
     types: [...metadata.types].sort(bySchemaName),
+    // `resolveRpcFunctions` orders the overloads of a function by signature,
+    // and that order is kept here, like composite attributes; the entries,
+    // their args and their table columns are addressed by name.
+    ...(metadata.rpcFunctions === undefined
+      ? {}
+      : {
+          rpcFunctions: [...metadata.rpcFunctions]
+            .sort(
+              (a, b) =>
+                compareStrings(a.schema, b.schema) ||
+                compareStrings(a.name, b.name),
+            )
+            .map((fn) => ({
+              ...fn,
+              overloads: fn.overloads.map((overload) => ({
+                ...overload,
+                args: [...overload.args].sort((a, b) =>
+                  compareStrings(a.name, b.name),
+                ),
+                returns: {
+                  ...overload.returns,
+                  columns:
+                    overload.returns.columns === null
+                      ? null
+                      : [...overload.returns.columns].sort((a, b) =>
+                          compareStrings(a.name, b.name),
+                        ),
+                },
+              })),
+            })),
+        }),
   };
 }

package/src/types.ts

@@ -172,6 +172,100 @@ const postgresViewSchema = type({
 });
 export type PostgresView = typeof postgresViewSchema.infer;
 
+/**
+ * A reference to a `types` entry by oid. `format` is the type's `name` (the
+ * same spelling `PostgresColumn.format` uses, `_` prefixed for arrays) and
+ * `type_schema` its schema; both are `null` when the type is not in `types`,
+ * which never happens in a document produced by `introspect()`.
+ */
+const rpcTypeReferenceSchema = type({
+  type_id: "number",
+  format: "string | null",
+  type_schema: "string | null",
+});
+export type RpcTypeReference = typeof rpcTypeReferenceSchema.infer;
+
+const rpcFunctionArgSchema = rpcTypeReferenceSchema.merge({
+  /** Empty for an unnamed parameter. */
+  name: "string",
+  mode: "'in' | 'inout' | 'variadic'",
+  has_default: "boolean",
+  /**
+   * The relation whose row type this parameter has, when that relation is in
+   * the metadata. A caller passes such a parameter as a row object.
+   */
+  relation_id: "number | null",
+});
+export type RpcFunctionArg = typeof rpcFunctionArgSchema.infer;
+
+const rpcFunctionReturnsSchema = rpcTypeReferenceSchema.merge({
+  /**
+   * The relation whose rows the function returns, when that relation is in
+   * the metadata; the row shape is the relation's `columns`.
+   */
+  relation_id: "number | null",
+  /**
+   * 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"),
+});
+export type RpcFunctionReturns = typeof rpcFunctionReturnsSchema.infer;
+
+const rpcFunctionOverloadSchema = type({
+  /** The `functions` entry this overload was resolved from. */
+  function_id: "number",
+  /** The input parameters (`in`, `inout` and `variadic`), in name order. */
+  args: rpcFunctionArgSchema.array(),
+  returns: rpcFunctionReturnsSchema,
+  /** `true` when the response is an array of rows or values. */
+  is_set_returning: "boolean",
+  /** The planner's `ROWS` estimate of a set-returning function, else `null`. */
+  rows_estimate: "number | null",
+  /**
+   * Present when the result can be embedded and sub-selected like a relation.
+   * `to` names the relation (or composite type) whose rows come back, `from`
+   * the relation a sole row-typed parameter embeds from, or `*` when the
+   * function is called directly. `is_one_to_one` is `true` when at most one
+   * row comes back, so a client may unwrap the array. `is_setof_return`
+   * mirrors `is_set_returning`.
+   */
+  setof_options: type({
+    from: "string",
+    to: "string",
+    is_one_to_one: "boolean",
+    is_setof_return: "boolean",
+  }).or("null"),
+  /**
+   * The relation this function is a computed field of: its sole input
+   * parameter has that relation's row type, the relation is in the function's
+   * schema, and no column of the relation shares the function's name. Such a
+   * function is selectable as a nullable column of the relation.
+   */
+  computed_field_of: "number | null",
+  /**
+   * Why PostgREST cannot resolve a call to this overload, when it cannot: the
+   * 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",
+});
+export type RpcFunctionOverload = typeof rpcFunctionOverloadSchema.infer;
+
+/**
+ * A function PostgREST exposes under `/rpc`, with its overloads resolved.
+ * Produced by `resolveRpcFunctions` from the raw `functions` collection.
+ */
+const rpcFunctionSchema = type({
+  schema: "string",
+  name: "string",
+  /** Ordered by argument list, then by return type. Never empty. */
+  overloads: rpcFunctionOverloadSchema.array(),
+});
+export type RpcFunction = typeof rpcFunctionSchema.infer;
+
 /**
  * Bumped whenever `GeneratorMetadata`'s shape changes in a way a consumer
  * should branch on. Out-of-process consumers (a generator in another
@@ -200,6 +294,14 @@ export const generatorMetadataSchema = type({
   relationships: postgresRelationshipSchema.array(),
   functions: postgresFunctionSchema.array(),
   types: postgresTypeSchema.array(),
+  /**
+   * The PostgREST view of `functions`: which are callable through `/rpc`, how
+   * their overloads group and what a call returns. Derived from the other
+   * collections by `resolveRpcFunctions`, which `introspect()` runs. Optional
+   * because version 1 documents predating the collection are still valid;
+   * a generator falls back to running `resolveRpcFunctions` itself.
+   */
+  "rpcFunctions?": rpcFunctionSchema.array(),
 });
 export type GeneratorMetadata = typeof generatorMetadataSchema.infer;
 

package/dist/generation/constants.d.ts

@@ -1,9 +0,0 @@
-/**
- * Type-generation constants ported verbatim from
- * `postgres-meta/src/server/constants.ts`. Only the typegen-relevant values
- * live here; server/runtime constants stay in postgres-meta.
- *
- * Consumed by the TypeScript generator's function-argument handling.
- */
-export declare const VALID_UNNAMED_FUNCTION_ARG_TYPES: Set<number>;
-export declare const VALID_FUNCTION_ARGS_MODE: Set<string>;

package/dist/generation/constants.js

@@ -1,10 +0,0 @@
-/**
- * Type-generation constants ported verbatim from
- * `postgres-meta/src/server/constants.ts`. Only the typegen-relevant values
- * live here; server/runtime constants stay in postgres-meta.
- *
- * Consumed by the TypeScript generator's function-argument handling.
- */
-// json/jsonb/text types
-export const VALID_UNNAMED_FUNCTION_ARG_TYPES = new Set([114, 3802, 25]);
-export const VALID_FUNCTION_ARGS_MODE = new Set(["in", "inout", "variadic"]);

package/dist/generation/swift.d.ts

@@ -1,11 +0,0 @@
-import type { GeneratorMetadata } from "../types.ts";
-export type AccessControl = "internal" | "public" | "private" | "package";
-export interface GenerateSwiftOptions {
-    /** Swift access-control level applied to generated declarations. Default `'internal'`. */
-    accessControl?: AccessControl;
-}
-/**
- * Emits tables/views/materialized views in `GeneratorMetadata` order. Pass
- * input pre-sorted with `sortGeneratorMetadata` for deterministic output.
- */
-export declare const generateSwift: (metadata: GeneratorMetadata, opts?: GenerateSwiftOptions) => string;