@supabase/postgrest-typegen 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Supabase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @supabase/postgrest-typegen
+
+Type generation for [PostgREST](https://postgrest.org) from a PostgreSQL
+schema. This is the type-generation engine behind `supabase gen types`,
+extracted from [postgres-meta](https://github.com/supabase/postgres-meta) into a
+small, driver-agnostic library.
+
+> **Status:** alpha. The public API is settling as generators and introspection
+> are ported.
+
+## Scope: introspection is permanent, four generators are transitional
+
+This package's permanent job is introspection and the `GeneratorMetadata`
+contract (see "Out-of-process generators" below): any *new* language's
+generator lives in that language's own SDK repo, consuming this package's
+JSON output, not inside `postgrest-typegen`.
+
+The TypeScript, Go, Python, and Swift generators bundled here are a
+**deliberate transition**, not the target architecture for new languages.
+They were ported byte-parity from postgres-meta's own templates so
+`supabase gen types` keeps working unchanged while postgres-meta's copies get
+deprecated in favor of this package. It's decided that all four eventually
+move out to their own SDK repos too (tracked in SDK-1641), not yet scheduled
+— sequenced after postgres-meta's cutover to this package settles.
+
+## Design
+
+There is a hard split between **introspection** (database → metadata) and
+**generation** (metadata → string):
+
+```ts
+import { introspect } from "@supabase/postgrest-typegen/introspection";
+import {
+  generateTypescript,
+  sortGeneratorMetadata,
+} from "@supabase/postgrest-typegen/generation";
+
+// Any `pg.Pool` / `pg.Client` (or compatible driver) works here.
+const metadata = await introspect(pool, { includedSchemas: ["public"] });
+// Canonically sort before generating (see "Stable ordering" below).
+const types = await generateTypescript(sortGeneratorMetadata(metadata), {
+  postgrestVersion: "12",
+});
+```
+
+`GeneratorMetadata` is the pluggable contract: the SQL introspector is the
+default producer, but any source that can produce that shape can feed the
+generators.
+
+### Stable ordering (`sortGeneratorMetadata`)
+
+The Go/Python/Swift generators emit tables, views, and materialized views in
+`GeneratorMetadata` order, so their output depends on how the producer ordered
+its collections (a SQL introspector returns rows in environment-dependent heap
+order). `sortGeneratorMetadata` is a pure pass that canonically sorts every
+collection; **apply it after introspection and before any `generate*` call** so
+output is deterministic regardless of the producer. Generators expect
+pre-sorted input and do not re-sort it themselves.
+
+### Runtime validation (opt-in)
+
+`GeneratorMetadata` is backed by an [ArkType](https://arktype.io) schema, so a
+result coming from a custom/injected producer can be validated at runtime
+rather than blindly cast. `introspect()` does **not** validate — wrap its
+result yourself when you want the guarantee:
+
+```ts
+import { parseGeneratorMetadata, generatorMetadataSchema } from "@supabase/postgrest-typegen";
+
+// Throws a TypeError with a readable summary if the shape is wrong.
+const metadata = parseGeneratorMetadata(await someCustomIntrospector(db));
+
+// Or use the raw schema directly for custom flows.
+const out = generatorMetadataSchema(unknownInput);
+```
+
+### Out-of-process generators (JSON Schema + serialization)
+
+Generators that live outside this package's process, in another language's
+own SDK repo, receive `GeneratorMetadata` as JSON rather than a live object.
+This package owns that boundary, so no consumer serializes the contract a
+different way:
+
+```ts
+import {
+  serializeGeneratorMetadata,
+  generatorMetadataJsonSchema,
+} from "@supabase/postgrest-typegen";
+
+// The exact JSON document an out-of-process generator (e.g. `dart run
+// supabase_typegen`) receives over stdin/stdout.
+const json = serializeGeneratorMetadata(sortGeneratorMetadata(metadata));
+
+// The JSON Schema for that document, for consumers that want to validate or
+// codegen against the contract without depending on ArkType or TypeScript.
+generatorMetadataJsonSchema;
+```
+
+`GeneratorMetadata.version` is bumped whenever the shape changes in a way a
+consumer should branch on, since an out-of-process consumer only sees the
+serialized document and can't otherwise detect a shape change until something
+breaks at read time.
+
+### Generators
+
+```ts
+import {
+  generateTypescript, // async (uses prettier)
+  generateGo,
+  generatePython,
+  generateSwift,
+} from "@supabase/postgrest-typegen/generation";
+```
+
+| Function             | Options                                                                 |
+| -------------------- | ----------------------------------------------------------------------- |
+| `generateTypescript` | `{ detectOneToOneRelationships?, postgrestVersion?, defaultSchema? }`    |
+| `generateGo`         | —                                                                       |
+| `generatePython`     | —                                                                       |
+| `generateSwift`      | `{ accessControl?: 'internal' \| 'public' \| 'private' \| 'package' }`   |
+
+## Installation
+
+Not yet published; consumed in-repo for now (`packages/postgrest-typegen`).
+
+```bash
+# pg is a peer of your application, not bundled here
+npm install pg
+```
+
+## License
+
+MIT

package/dist/generation/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,10 @@
+/**
+ * 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/go.d.ts

@@ -0,0 +1,6 @@
+import type { GeneratorMetadata } from "../types.ts";
+/**
+ * Emits tables/views/materialized views in `GeneratorMetadata` order. Pass
+ * input pre-sorted with `sortGeneratorMetadata` for deterministic output.
+ */
+export declare const generateGo: ({ schemas, tables, views, materializedViews, columns, types, }: GeneratorMetadata) => string;

package/dist/generation/go.js

@@ -0,0 +1,233 @@
+/**
+ * Emits tables/views/materialized views in `GeneratorMetadata` order. Pass
+ * input pre-sorted with `sortGeneratorMetadata` for deterministic output.
+ */
+export const generateGo = ({ schemas, tables, views, materializedViews, columns, types, }) => {
+    const columnsByTableId = columns.reduce((acc, curr) => {
+        acc[curr.table_id] ??= [];
+        acc[curr.table_id].push(curr);
+        return acc;
+    }, {});
+    const compositeTypes = types.filter((type) => type.attributes.length > 0);
+    let output = `
+package database
+
+${tables
+        .filter((table) => schemas.some((schema) => schema.name === table.schema))
+        .flatMap((table) => generateTableStructsForOperations(schemas.find((schema) => schema.name === table.schema), table, columnsByTableId[table.id], types, ["Select", "Insert", "Update"]))
+        .join("\n\n")}
+
+${views
+        .filter((view) => schemas.some((schema) => schema.name === view.schema))
+        .flatMap((view) => generateTableStructsForOperations(schemas.find((schema) => schema.name === view.schema), view, columnsByTableId[view.id], types, ["Select"]))
+        .join("\n\n")}
+
+${materializedViews
+        .filter((materializedView) => schemas.some((schema) => schema.name === materializedView.schema))
+        .flatMap((materializedView) => generateTableStructsForOperations(schemas.find((schema) => schema.name === materializedView.schema), materializedView, columnsByTableId[materializedView.id], types, ["Select"]))
+        .join("\n\n")}
+
+${compositeTypes
+        .filter((compositeType) => schemas.some((schema) => schema.name === compositeType.schema))
+        .map((compositeType) => generateCompositeTypeStruct(schemas.find((schema) => schema.name === compositeType.schema), compositeType, types))
+        .join("\n\n")}
+`.trim();
+    return output;
+};
+/**
+ * Converts a Postgres name to PascalCase.
+ *
+ * @example
+ * ```ts
+ * formatForGoTypeName('pokedex') // Pokedex
+ * formatForGoTypeName('pokemon_center') // PokemonCenter
+ * formatForGoTypeName('victory-road') // VictoryRoad
+ * formatForGoTypeName('pokemon league') // PokemonLeague
+ * ```
+ */
+function formatForGoTypeName(name) {
+    return name
+        .split(/[^a-zA-Z0-9]/)
+        .map((word) => {
+        if (word) {
+            return `${word[0].toUpperCase()}${word.slice(1)}`;
+        }
+        else {
+            return "";
+        }
+    })
+        .join("");
+}
+function generateTableStruct(schema, table, columns, types, operation) {
+    // Storing columns as a tuple of [formattedName, type, name] rather than creating the string
+    // representation of the line allows us to pre-format the entries. Go formats
+    // struct fields to be aligned, e.g.:
+    // ```go
+    // type Pokemon struct {
+    //   id   int    `json:"id"`
+    //   name string `json:"name"`
+    // }
+    const columnEntries = columns?.map((column) => {
+        let nullable;
+        if (operation === "Insert") {
+            nullable =
+                column.is_nullable ||
+                    column.is_identity ||
+                    column.is_generated ||
+                    !!column.default_value;
+        }
+        else if (operation === "Update") {
+            nullable = true;
+        }
+        else {
+            nullable = column.is_nullable;
+        }
+        return [
+            formatForGoTypeName(column.name),
+            pgTypeToGoType(column.format, nullable, types),
+            column.name,
+        ];
+    }) ?? [];
+    const [maxFormattedNameLength, maxTypeLength] = columnEntries.reduce(([maxFormattedName, maxType], [formattedName, type]) => {
+        return [
+            Math.max(maxFormattedName, formattedName.length),
+            Math.max(maxType, type.length),
+        ];
+    }, [0, 0]);
+    // Pad the formatted name and type to align the struct fields, then join
+    // create the final string representation of the struct fields.
+    const formattedColumnEntries = columnEntries.map(([formattedName, type, name]) => {
+        return `  ${formattedName.padEnd(maxFormattedNameLength)} ${type.padEnd(maxTypeLength)} \`json:"${name}"\``;
+    });
+    return `
+type ${formatForGoTypeName(schema.name)}${formatForGoTypeName(table.name)}${operation} struct {
+${formattedColumnEntries.join("\n")}
+}
+`.trim();
+}
+function generateTableStructsForOperations(schema, table, columns, types, operations) {
+    return operations.map((operation) => generateTableStruct(schema, table, columns, types, operation));
+}
+function generateCompositeTypeStruct(schema, type, types) {
+    // Use the type_id of the attributes to find the types of the attributes
+    const typeWithRetrievedAttributes = {
+        ...type,
+        attributes: type.attributes.map((attribute) => {
+            const type = types.find((type) => type.id === attribute.type_id);
+            return {
+                ...attribute,
+                type,
+            };
+        }),
+    };
+    const attributeEntries = typeWithRetrievedAttributes.attributes.map((attribute) => [
+        formatForGoTypeName(attribute.name),
+        pgTypeToGoType(attribute.type.format, false),
+        attribute.name,
+    ]);
+    const [maxFormattedNameLength, maxTypeLength] = attributeEntries.reduce(([maxFormattedName, maxType], [formattedName, type]) => {
+        return [
+            Math.max(maxFormattedName, formattedName.length),
+            Math.max(maxType, type.length),
+        ];
+    }, [0, 0]);
+    // Pad the formatted name and type to align the struct fields, then join
+    // create the final string representation of the struct fields.
+    const formattedAttributeEntries = attributeEntries.map(([formattedName, type, name]) => {
+        return `  ${formattedName.padEnd(maxFormattedNameLength)} ${type.padEnd(maxTypeLength)} \`json:"${name}"\``;
+    });
+    return `
+type ${formatForGoTypeName(schema.name)}${formatForGoTypeName(type.name)} struct {
+${formattedAttributeEntries.join("\n")}
+}
+`.trim();
+}
+// Note: the type map uses `interface{ } `, not `any`, to remain compatible with
+// older versions of Go.
+const GO_TYPE_MAP = {
+    // Bool
+    bool: "bool",
+    // Numbers
+    int2: "int16",
+    int4: "int32",
+    int8: "int64",
+    float4: "float32",
+    float8: "float64",
+    numeric: "float64",
+    // Strings
+    bytea: "[]byte",
+    bpchar: "string",
+    varchar: "string",
+    date: "string",
+    text: "string",
+    citext: "string",
+    time: "string",
+    timetz: "string",
+    timestamp: "string",
+    timestamptz: "string",
+    interval: "string",
+    uuid: "string",
+    vector: "string",
+    // JSON
+    json: "interface{}",
+    jsonb: "interface{}",
+    // Range
+    int4range: "string",
+    int4multirange: "string",
+    int8range: "string",
+    int8multirange: "string",
+    numrange: "string",
+    nummultirange: "string",
+    tsrange: "string",
+    tsmultirange: "string",
+    tstzrange: "string",
+    tstzmultirange: "string",
+    daterange: "string",
+    datemultirange: "string",
+    // Misc
+    void: "interface{}",
+    record: "map[string]interface{}",
+};
+const GO_NULLABLE_TYPE_MAP = {
+    string: "*string",
+    bool: "*bool",
+    int16: "*int16",
+    int32: "*int32",
+    int64: "*int64",
+    float32: "*float32",
+    float64: "*float64",
+    "[]byte": "[]byte",
+    "interface{}": "interface{}",
+    "map[string]interface{}": "map[string]interface{}",
+};
+function pgTypeToGoType(pgType, nullable, types = []) {
+    let goType = undefined;
+    if (pgType in GO_TYPE_MAP) {
+        goType = GO_TYPE_MAP[pgType];
+    }
+    // Enums
+    const enumType = types.find((type) => type.name === pgType && type.enums.length > 0);
+    if (enumType) {
+        goType = "string";
+    }
+    if (goType) {
+        if (nullable) {
+            return GO_NULLABLE_TYPE_MAP[goType];
+        }
+        return goType;
+    }
+    // Composite types
+    const compositeType = types.find((type) => type.name === pgType && type.attributes.length > 0);
+    if (compositeType) {
+        // TODO: generate composite types
+        // return formatForGoTypeName(pgType)
+        return "map[string]interface{}";
+    }
+    // Arrays
+    if (pgType.startsWith("_")) {
+        const innerType = pgTypeToGoType(pgType.slice(1), nullable, types);
+        return `[]${innerType} `;
+    }
+    // Fallback
+    return "interface{}";
+}

package/dist/generation/index.d.ts

@@ -0,0 +1,5 @@
+export { sortGeneratorMetadata } from "../sort.ts";
+export { generateGo } from "./go.ts";
+export { generatePython } from "./python.ts";
+export { generateTypescript, type GenerateTypescriptOptions, pgTypeToTsType, } from "./typescript.ts";
+export { type AccessControl, generateSwift, type GenerateSwiftOptions, } from "./swift.ts";

package/dist/generation/index.js

@@ -0,0 +1,5 @@
+export { sortGeneratorMetadata } from "../sort.js";
+export { generateGo } from "./go.js";
+export { generatePython } from "./python.js";
+export { generateTypescript, pgTypeToTsType, } from "./typescript.js";
+export { generateSwift, } from "./swift.js";

package/dist/generation/python.d.ts

@@ -0,0 +1,6 @@
+import type { GeneratorMetadata } from "../types.ts";
+/**
+ * Emits tables/views/materialized views in `GeneratorMetadata` order. Pass
+ * input pre-sorted with `sortGeneratorMetadata` for deterministic output.
+ */
+export declare const generatePython: ({ schemas, tables, views, materializedViews, columns, types, }: GeneratorMetadata) => string;