@supabase/postgrest-typegen 0.4.0 → 0.5.0

package/dist/rpc.js

@@ -0,0 +1,223 @@
+/**
+ * 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.js";
+/** 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"]);
+export function resolveRpcFunctions(metadata) {
+    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.type_relation_id !== null)
+        .map((type) => [type.id, type]));
+    const relationsById = new Map([
+        ...metadata.tables,
+        ...metadata.foreignTables,
+        ...metadata.views,
+        ...metadata.materializedViews,
+    ].map((relation) => [relation.id, relation]));
+    const columnNamesByRelationId = new Map();
+    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) => {
+        const type = typesById.get(typeId);
+        return {
+            type_id: typeId,
+            format: type?.name ?? null,
+            type_schema: type?.schema ?? null,
+        };
+    };
+    const typeName = (typeId) => 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) => {
+        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 }) => {
+        const soleInArg = inArgs.length === 1 ? inArgs[0] : undefined;
+        const argType = soleInArg && 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);
+        if (!relation || relation.schema !== fn.schema)
+            return null;
+        if (columnNamesByRelationId.get(relation.id)?.has(fn.name))
+            return null;
+        return relation.id;
+    };
+    const isCallable = ({ inArgs }) => {
+        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, group) => {
+        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`;
+                }
+            }
+        }
+        // A sole unnamed row parameter makes the function a computed field, which
+        // PostgREST only exposes under `/rpc` when it also returns rows.
+        if (soleInArg &&
+            soleInArg.name === "" &&
+            relationTypesById.has(soleInArg.type_id) &&
+            returnRelationName(fn) === null) {
+            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, group) => {
+        const { fn, inArgs } = candidate;
+        const args = 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 &&
+                    relationId !== null &&
+                    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();
+    for (const fn of metadata.functions) {
+        if (!schemaNames.has(fn.schema))
+            continue;
+        const inArgs = fn.args.filter((arg) => INPUT_ARG_MODES.has(arg.mode));
+        const candidate = { fn, inArgs };
+        if (!isCallable(candidate))
+            continue;
+        const key = `${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;
+        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/dist/sort.js

@@ -60,5 +60,28 @@ export function sortGeneratorMetadata(metadata) {
             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/dist/types.d.ts

@@ -208,6 +208,119 @@ declare const postgresViewSchema: import("arktype/internal/variants/object.ts").
     }[] | undefined;
 }, {}>;
 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()`.
+ */
+declare const rpcTypeReferenceSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    type_id: number;
+    format: string | null;
+    type_schema: string | null;
+}, {}>;
+export type RpcTypeReference = typeof rpcTypeReferenceSchema.infer;
+declare const rpcFunctionArgSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    type_id: number;
+    format: string | null;
+    type_schema: string | null;
+    name: string;
+    mode: "in" | "inout" | "variadic";
+    has_default: boolean;
+    relation_id: number | null;
+}, {}>;
+export type RpcFunctionArg = typeof rpcFunctionArgSchema.infer;
+declare const rpcFunctionReturnsSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    type_id: number;
+    format: string | null;
+    type_schema: string | null;
+    relation_id: number | null;
+    columns: {
+        type_id: number;
+        format: string | null;
+        type_schema: string | null;
+        name: string;
+    }[] | null;
+}, {}>;
+export type RpcFunctionReturns = typeof rpcFunctionReturnsSchema.infer;
+declare const rpcFunctionOverloadSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    function_id: number;
+    args: {
+        type_id: number;
+        format: string | null;
+        type_schema: string | null;
+        name: string;
+        mode: "in" | "inout" | "variadic";
+        has_default: boolean;
+        relation_id: number | null;
+    }[];
+    returns: {
+        type_id: number;
+        format: string | null;
+        type_schema: string | null;
+        relation_id: number | null;
+        columns: {
+            type_id: number;
+            format: string | null;
+            type_schema: string | null;
+            name: string;
+        }[] | null;
+    };
+    is_set_returning: boolean;
+    rows_estimate: number | null;
+    setof_options: {
+        from: string;
+        to: string;
+        is_one_to_one: boolean;
+        is_setof_return: boolean;
+    } | null;
+    computed_field_of: number | null;
+    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.
+ */
+declare const rpcFunctionSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    schema: string;
+    name: string;
+    overloads: {
+        function_id: number;
+        args: {
+            type_id: number;
+            format: string | null;
+            type_schema: string | null;
+            name: string;
+            mode: "in" | "inout" | "variadic";
+            has_default: boolean;
+            relation_id: number | null;
+        }[];
+        returns: {
+            type_id: number;
+            format: string | null;
+            type_schema: string | null;
+            relation_id: number | null;
+            columns: {
+                type_id: number;
+                format: string | null;
+                type_schema: string | null;
+                name: string;
+            }[] | null;
+        };
+        is_set_returning: boolean;
+        rows_estimate: number | null;
+        setof_options: {
+            from: string;
+            to: string;
+            is_one_to_one: boolean;
+            is_setof_return: boolean;
+        } | null;
+        computed_field_of: number | null;
+        error: string | null;
+    }[];
+}, {}>;
+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
@@ -341,6 +454,44 @@ export declare const generatorMetadataSchema: import("arktype/internal/variants/
         comment: string | null;
         type_relation_id: number | null;
     }[];
+    rpcFunctions?: {
+        schema: string;
+        name: string;
+        overloads: {
+            function_id: number;
+            args: {
+                type_id: number;
+                format: string | null;
+                type_schema: string | null;
+                name: string;
+                mode: "in" | "inout" | "variadic";
+                has_default: boolean;
+                relation_id: number | null;
+            }[];
+            returns: {
+                type_id: number;
+                format: string | null;
+                type_schema: string | null;
+                relation_id: number | null;
+                columns: {
+                    type_id: number;
+                    format: string | null;
+                    type_schema: string | null;
+                    name: string;
+                }[] | null;
+            };
+            is_set_returning: boolean;
+            rows_estimate: number | null;
+            setof_options: {
+                from: string;
+                to: string;
+                is_one_to_one: boolean;
+                is_setof_return: boolean;
+            } | null;
+            computed_field_of: number | null;
+            error: string | null;
+        }[];
+    }[] | undefined;
 }, {}>;
 export type GeneratorMetadata = typeof generatorMetadataSchema.infer;
 /**

package/dist/types.js

@@ -150,6 +150,89 @@ const postgresViewSchema = type({
     comment: "string | null",
     "columns?": postgresColumnSchema.array(),
 });
+/**
+ * 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",
+});
+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",
+});
+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 (…)` or `OUT` parameter result, in name
+     * order; `null` for every other return type.
+     */
+    columns: rpcTypeReferenceSchema.merge({ name: "string" }).array().or("null"),
+});
+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 it is a computed field that
+     * returns no rows. Generators surface the message instead of a callable
+     * signature.
+     */
+    error: "string | null",
+});
+/**
+ * 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(),
+});
 /**
  * Bumped whenever `GeneratorMetadata`'s shape changes in a way a consumer
  * should branch on. Out-of-process consumers (a generator in another
@@ -177,6 +260,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(),
 });
 /**
  * JSON Schema for {@link generatorMetadataSchema}, published so out-of-process

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/postgrest-typegen",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Type generation for PostgREST from PostgreSQL schemas",
   "keywords": [
     "codegen",
@@ -58,11 +58,12 @@
     "check-types:consumer": "tsc --project tsconfig.consumer.json",
     "format-and-lint": "oxfmt --check . && oxlint --deny-warnings src test scripts",
     "format-and-lint:fix": "oxfmt . && oxlint --fix src test scripts",
+    "generate:postgrest-js-types": "bun scripts/generate-postgrest-js-types.ts",
     "knip": "knip",
     "test": "bun scripts/run-tests.ts test/"
   },
   "dependencies": {
-    "arktype": "2.2.5"
+    "arktype": "2.2.8"
   },
   "devDependencies": {
     "@testcontainers/postgresql": "^12.1.0",
@@ -74,8 +75,8 @@
     "@types/pg": "^8.23.1",
     "knip": "^6.32.3",
     "oxfmt": "0.66.0",
-    "oxlint": "1.85.0",
-    "oxlint-tsgolint": "7.0.2003",
+    "oxlint": "1.87.0",
+    "oxlint-tsgolint": "7.0.2004",
     "pg": "^8.23.0",
     "testcontainers": "^12.1.0",
     "typescript": "7.0.2"

package/src/generation/index.ts

@@ -7,8 +7,3 @@ export {
   pgTypeToTsType,
   type TypeResolutionContext,
 } from "./typescript.ts";
-export {
-  type AccessControl,
-  generateSwift,
-  type GenerateSwiftOptions,
-} from "./swift.ts";