@supabase/postgrest-typegen 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,372 @@
+declare const postgresColumnSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    table_id: number;
+    schema: string;
+    table: string;
+    id: string;
+    ordinal_position: number;
+    name: string;
+    default_value: unknown;
+    data_type: string;
+    format: string;
+    type_schema: string;
+    is_identity: boolean;
+    identity_generation: "ALWAYS" | "BY DEFAULT" | null;
+    is_generated: boolean;
+    is_nullable: boolean;
+    is_updatable: boolean;
+    is_unique: boolean;
+    enums: string[];
+    check: string | null;
+    comment: string | null;
+}, {}>;
+export type PostgresColumn = typeof postgresColumnSchema.infer;
+declare const postgresForeignTableSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: number;
+    schema: string;
+    name: string;
+    comment: string | null;
+    columns?: {
+        table_id: number;
+        schema: string;
+        table: string;
+        id: string;
+        ordinal_position: number;
+        name: string;
+        default_value: unknown;
+        data_type: string;
+        format: string;
+        type_schema: string;
+        is_identity: boolean;
+        identity_generation: "ALWAYS" | "BY DEFAULT" | null;
+        is_generated: boolean;
+        is_nullable: boolean;
+        is_updatable: boolean;
+        is_unique: boolean;
+        enums: string[];
+        check: string | null;
+        comment: string | null;
+    }[] | undefined;
+}, {}>;
+export type PostgresForeignTable = typeof postgresForeignTableSchema.infer;
+declare const postgresFunctionSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: number;
+    schema: string;
+    name: string;
+    language: string;
+    definition: string;
+    complete_statement: string;
+    args: {
+        mode: "in" | "inout" | "out" | "table" | "variadic";
+        name: string;
+        type_id: number;
+        has_default: boolean | null;
+    }[];
+    argument_types: string;
+    identity_argument_types: string;
+    return_type_id: number;
+    return_type: string;
+    return_type_relation_id: number | null;
+    is_set_returning_function: boolean;
+    prorows: number | null;
+    behavior: "IMMUTABLE" | "STABLE" | "VOLATILE";
+    security_definer: boolean;
+    config_params: {
+        [x: string]: string;
+    } | null;
+}, {}>;
+export type PostgresFunction = typeof postgresFunctionSchema.infer;
+declare const postgresMaterializedViewSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: number;
+    schema: string;
+    name: string;
+    is_populated: boolean;
+    comment: string | null;
+    columns?: {
+        table_id: number;
+        schema: string;
+        table: string;
+        id: string;
+        ordinal_position: number;
+        name: string;
+        default_value: unknown;
+        data_type: string;
+        format: string;
+        type_schema: string;
+        is_identity: boolean;
+        identity_generation: "ALWAYS" | "BY DEFAULT" | null;
+        is_generated: boolean;
+        is_nullable: boolean;
+        is_updatable: boolean;
+        is_unique: boolean;
+        enums: string[];
+        check: string | null;
+        comment: string | null;
+    }[] | undefined;
+}, {}>;
+export type PostgresMaterializedView = typeof postgresMaterializedViewSchema.infer;
+declare const postgresPrimaryKeySchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    schema: string;
+    table_name: string;
+    name: string;
+    table_id: number;
+}, {}>;
+export type PostgresPrimaryKey = typeof postgresPrimaryKeySchema.infer;
+declare const postgresRelationshipSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    foreign_key_name: string;
+    schema: string;
+    relation: string;
+    columns: string[];
+    is_one_to_one: boolean;
+    referenced_schema: string;
+    referenced_relation: string;
+    referenced_columns: string[];
+}, {}>;
+export type PostgresRelationship = typeof postgresRelationshipSchema.infer;
+declare const postgresSchemaSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: number;
+    name: string;
+    owner: string;
+}, {}>;
+export type PostgresSchema = typeof postgresSchemaSchema.infer;
+declare const postgresTableSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: number;
+    schema: string;
+    name: string;
+    rls_enabled: boolean;
+    rls_forced: boolean;
+    replica_identity: "DEFAULT" | "FULL" | "INDEX" | "NOTHING";
+    bytes: number;
+    size: string;
+    live_rows_estimate: number;
+    dead_rows_estimate: number;
+    comment: string | null;
+    columns?: {
+        table_id: number;
+        schema: string;
+        table: string;
+        id: string;
+        ordinal_position: number;
+        name: string;
+        default_value: unknown;
+        data_type: string;
+        format: string;
+        type_schema: string;
+        is_identity: boolean;
+        identity_generation: "ALWAYS" | "BY DEFAULT" | null;
+        is_generated: boolean;
+        is_nullable: boolean;
+        is_updatable: boolean;
+        is_unique: boolean;
+        enums: string[];
+        check: string | null;
+        comment: string | null;
+    }[] | undefined;
+}, {}>;
+export type PostgresTable = typeof postgresTableSchema.infer;
+declare const postgresTypeSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: number;
+    name: string;
+    schema: string;
+    format: string;
+    enums: string[];
+    attributes: {
+        name: string;
+        type_id: number;
+    }[];
+    comment: string | null;
+    type_relation_id: number | null;
+}, {}>;
+export type PostgresType = typeof postgresTypeSchema.infer;
+declare const postgresViewSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: number;
+    schema: string;
+    name: string;
+    is_updatable: boolean;
+    comment: string | null;
+    columns?: {
+        table_id: number;
+        schema: string;
+        table: string;
+        id: string;
+        ordinal_position: number;
+        name: string;
+        default_value: unknown;
+        data_type: string;
+        format: string;
+        type_schema: string;
+        is_identity: boolean;
+        identity_generation: "ALWAYS" | "BY DEFAULT" | null;
+        is_generated: boolean;
+        is_nullable: boolean;
+        is_updatable: boolean;
+        is_unique: boolean;
+        enums: string[];
+        check: string | null;
+        comment: string | null;
+    }[] | undefined;
+}, {}>;
+export type PostgresView = typeof postgresViewSchema.infer;
+/**
+ * Bumped whenever `GeneratorMetadata`'s shape changes in a way a consumer
+ * should branch on. Out-of-process consumers (a generator in another
+ * language's SDK repo, fed JSON over a process boundary) only see the
+ * serialized document, so a shape change is otherwise undetectable until
+ * something breaks at read time.
+ */
+export declare const GENERATOR_METADATA_VERSION = 1;
+/**
+ * The complete set of introspected metadata required to generate types.
+ * Produced by `introspect()` (the default SQL-based producer) or any other
+ * source able to satisfy this shape. The table-like collections drop the
+ * optional `columns` field (mirroring `Omit<…, "columns">`); columns are
+ * carried separately on `columns`.
+ */
+export declare const generatorMetadataSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    schemas: {
+        id: number;
+        name: string;
+        owner: string;
+    }[];
+    tables: {
+        bytes: number;
+        comment: string | null;
+        dead_rows_estimate: number;
+        id: number;
+        live_rows_estimate: number;
+        name: string;
+        replica_identity: "DEFAULT" | "FULL" | "INDEX" | "NOTHING";
+        rls_enabled: boolean;
+        rls_forced: boolean;
+        schema: string;
+        size: string;
+    }[];
+    foreignTables: {
+        comment: string | null;
+        id: number;
+        name: string;
+        schema: string;
+    }[];
+    views: {
+        comment: string | null;
+        id: number;
+        is_updatable: boolean;
+        name: string;
+        schema: string;
+    }[];
+    materializedViews: {
+        comment: string | null;
+        id: number;
+        is_populated: boolean;
+        name: string;
+        schema: string;
+    }[];
+    columns: {
+        table_id: number;
+        schema: string;
+        table: string;
+        id: string;
+        ordinal_position: number;
+        name: string;
+        default_value: unknown;
+        data_type: string;
+        format: string;
+        type_schema: string;
+        is_identity: boolean;
+        identity_generation: "ALWAYS" | "BY DEFAULT" | null;
+        is_generated: boolean;
+        is_nullable: boolean;
+        is_updatable: boolean;
+        is_unique: boolean;
+        enums: string[];
+        check: string | null;
+        comment: string | null;
+    }[];
+    primaryKeys: {
+        schema: string;
+        table_name: string;
+        name: string;
+        table_id: number;
+    }[];
+    relationships: {
+        foreign_key_name: string;
+        schema: string;
+        relation: string;
+        columns: string[];
+        is_one_to_one: boolean;
+        referenced_schema: string;
+        referenced_relation: string;
+        referenced_columns: string[];
+    }[];
+    functions: {
+        id: number;
+        schema: string;
+        name: string;
+        language: string;
+        definition: string;
+        complete_statement: string;
+        args: {
+            mode: "in" | "inout" | "out" | "table" | "variadic";
+            name: string;
+            type_id: number;
+            has_default: boolean | null;
+        }[];
+        argument_types: string;
+        identity_argument_types: string;
+        return_type_id: number;
+        return_type: string;
+        return_type_relation_id: number | null;
+        is_set_returning_function: boolean;
+        prorows: number | null;
+        behavior: "IMMUTABLE" | "STABLE" | "VOLATILE";
+        security_definer: boolean;
+        config_params: {
+            [x: string]: string;
+        } | null;
+    }[];
+    types: {
+        id: number;
+        name: string;
+        schema: string;
+        format: string;
+        enums: string[];
+        attributes: {
+            name: string;
+            type_id: number;
+        }[];
+        comment: string | null;
+        type_relation_id: number | null;
+    }[];
+}, {}>;
+export type GeneratorMetadata = typeof generatorMetadataSchema.infer;
+/**
+ * JSON Schema for {@link generatorMetadataSchema}, published so out-of-process
+ * consumers (a generator living in its own SDK repo, not this package) can
+ * validate or generate types against the contract without depending on
+ * ArkType or this package's TypeScript types.
+ */
+export declare const generatorMetadataJsonSchema: import("arktype").JsonSchema.NonBooleanBranch;
+/**
+ * Serialize a {@link GeneratorMetadata} value to the JSON document that
+ * crosses the process boundary to an out-of-process generator (e.g. `dart
+ * run supabase_typegen`). `GeneratorMetadata` is plain, JSON-safe data, so
+ * this is a thin, explicit boundary rather than a transform, kept as a named
+ * export so every caller serializes the contract the same way.
+ */
+export declare function serializeGeneratorMetadata(metadata: GeneratorMetadata): string;
+/**
+ * Validate an unknown value against the {@link generatorMetadataSchema} and
+ * return it typed as {@link GeneratorMetadata}. Throws a `TypeError` with
+ * ArkType's human-readable summary if validation fails.
+ *
+ * Offered as an opt-in helper so any integrator producing `GeneratorMetadata`
+ * through an injected adapter can verify the result at runtime instead of
+ * casting. `introspect()` does not call this — wrap its result yourself when
+ * you want the guarantee:
+ *
+ * ```ts
+ * const metadata = parseGeneratorMetadata(await introspect(db));
+ * ```
+ */
+export declare function parseGeneratorMetadata(data: unknown): GeneratorMetadata;
+export {};

package/dist/types.js

@@ -0,0 +1,207 @@
+/**
+ * Public metadata contract for type generation.
+ *
+ * ArkType is the single source of truth: each `Postgres*` schema below is a
+ * runtime validator, and the corresponding exported type is derived from it via
+ * `.infer`. The shapes are kept identical to postgres-meta's `src/lib/types.ts`
+ * so that postgres-meta can consume this package as a drop-in replacement for
+ * its embedded templates (a compile-time equivalence test pins this).
+ *
+ * `GeneratorMetadata` is the pluggable contract: the SQL introspector is the
+ * default producer, but any source able to produce this shape can feed the
+ * language generators. Because the producer may be an injected adapter,
+ * `parseGeneratorMetadata` is offered so integrators can validate a result at
+ * runtime instead of blindly casting it. Validation is deliberately *not* baked
+ * into `introspect()` — it is an opt-in helper.
+ */
+import { type } from "arktype";
+const postgresColumnSchema = type({
+    table_id: "number",
+    schema: "string",
+    table: "string",
+    /** `<table_id>.<ordinal_position>` */
+    id: "string",
+    ordinal_position: "number",
+    name: "string",
+    default_value: "unknown",
+    data_type: "string",
+    format: "string",
+    /**
+     * Schema owning `format`'s type. Bare enum/composite/domain names are
+     * ambiguous across schemas (two schemas can each define an enum named
+     * `mood`); this disambiguates without changing `format` itself.
+     */
+    type_schema: "string",
+    is_identity: "boolean",
+    identity_generation: "'ALWAYS' | 'BY DEFAULT' | null",
+    is_generated: "boolean",
+    is_nullable: "boolean",
+    is_updatable: "boolean",
+    is_unique: "boolean",
+    enums: "string[]",
+    check: "string | null",
+    comment: "string | null",
+});
+const postgresForeignTableSchema = type({
+    id: "number",
+    schema: "string",
+    name: "string",
+    comment: "string | null",
+    "columns?": postgresColumnSchema.array(),
+});
+const postgresFunctionSchema = type({
+    id: "number",
+    schema: "string",
+    name: "string",
+    language: "string",
+    definition: "string",
+    complete_statement: "string",
+    args: type({
+        mode: "'in' | 'out' | 'inout' | 'variadic' | 'table'",
+        name: "string",
+        type_id: "number",
+        // `introspect()` emits `null` for the OUT columns of RETURNS TABLE /
+        // OUT-arg functions: the introspection SQL sizes `arg_has_defaults` from
+        // the input-arg count while `arg_modes`/`arg_types` include output args,
+        // so the trailing rows are padded with NULL. postgres-meta types this as a
+        // plain boolean, but the opt-in validator must accept the real output.
+        has_default: "boolean | null",
+    }).array(),
+    argument_types: "string",
+    identity_argument_types: "string",
+    return_type_id: "number",
+    return_type: "string",
+    return_type_relation_id: "number | null",
+    is_set_returning_function: "boolean",
+    prorows: "number | null",
+    behavior: "'IMMUTABLE' | 'STABLE' | 'VOLATILE'",
+    security_definer: "boolean",
+    config_params: type({ "[string]": "string" }).or("null"),
+});
+const postgresMaterializedViewSchema = type({
+    id: "number",
+    schema: "string",
+    name: "string",
+    is_populated: "boolean",
+    comment: "string | null",
+    "columns?": postgresColumnSchema.array(),
+});
+const postgresPrimaryKeySchema = type({
+    schema: "string",
+    table_name: "string",
+    name: "string",
+    table_id: "number",
+});
+const postgresRelationshipSchema = type({
+    foreign_key_name: "string",
+    schema: "string",
+    relation: "string",
+    columns: "string[]",
+    is_one_to_one: "boolean",
+    referenced_schema: "string",
+    referenced_relation: "string",
+    referenced_columns: "string[]",
+});
+const postgresSchemaSchema = type({
+    id: "number",
+    name: "string",
+    owner: "string",
+});
+const postgresTableSchema = type({
+    id: "number",
+    schema: "string",
+    name: "string",
+    rls_enabled: "boolean",
+    rls_forced: "boolean",
+    replica_identity: "'DEFAULT' | 'INDEX' | 'FULL' | 'NOTHING'",
+    bytes: "number",
+    size: "string",
+    live_rows_estimate: "number",
+    dead_rows_estimate: "number",
+    comment: "string | null",
+    "columns?": postgresColumnSchema.array(),
+});
+const postgresTypeSchema = type({
+    id: "number",
+    name: "string",
+    schema: "string",
+    format: "string",
+    enums: "string[]",
+    attributes: type({ name: "string", type_id: "number" }).array(),
+    comment: "string | null",
+    type_relation_id: "number | null",
+});
+const postgresViewSchema = type({
+    id: "number",
+    schema: "string",
+    name: "string",
+    is_updatable: "boolean",
+    comment: "string | null",
+    "columns?": postgresColumnSchema.array(),
+});
+/**
+ * Bumped whenever `GeneratorMetadata`'s shape changes in a way a consumer
+ * should branch on. Out-of-process consumers (a generator in another
+ * language's SDK repo, fed JSON over a process boundary) only see the
+ * serialized document, so a shape change is otherwise undetectable until
+ * something breaks at read time.
+ */
+export const GENERATOR_METADATA_VERSION = 1;
+/**
+ * The complete set of introspected metadata required to generate types.
+ * Produced by `introspect()` (the default SQL-based producer) or any other
+ * source able to satisfy this shape. The table-like collections drop the
+ * optional `columns` field (mirroring `Omit<…, "columns">`); columns are
+ * carried separately on `columns`.
+ */
+export const generatorMetadataSchema = type({
+    version: `${GENERATOR_METADATA_VERSION}`,
+    schemas: postgresSchemaSchema.array(),
+    tables: postgresTableSchema.omit("columns").array(),
+    foreignTables: postgresForeignTableSchema.omit("columns").array(),
+    views: postgresViewSchema.omit("columns").array(),
+    materializedViews: postgresMaterializedViewSchema.omit("columns").array(),
+    columns: postgresColumnSchema.array(),
+    primaryKeys: postgresPrimaryKeySchema.array(),
+    relationships: postgresRelationshipSchema.array(),
+    functions: postgresFunctionSchema.array(),
+    types: postgresTypeSchema.array(),
+});
+/**
+ * JSON Schema for {@link generatorMetadataSchema}, published so out-of-process
+ * consumers (a generator living in its own SDK repo, not this package) can
+ * validate or generate types against the contract without depending on
+ * ArkType or this package's TypeScript types.
+ */
+export const generatorMetadataJsonSchema = generatorMetadataSchema.toJsonSchema();
+/**
+ * Serialize a {@link GeneratorMetadata} value to the JSON document that
+ * crosses the process boundary to an out-of-process generator (e.g. `dart
+ * run supabase_typegen`). `GeneratorMetadata` is plain, JSON-safe data, so
+ * this is a thin, explicit boundary rather than a transform, kept as a named
+ * export so every caller serializes the contract the same way.
+ */
+export function serializeGeneratorMetadata(metadata) {
+    return JSON.stringify(metadata);
+}
+/**
+ * Validate an unknown value against the {@link generatorMetadataSchema} and
+ * return it typed as {@link GeneratorMetadata}. Throws a `TypeError` with
+ * ArkType's human-readable summary if validation fails.
+ *
+ * Offered as an opt-in helper so any integrator producing `GeneratorMetadata`
+ * through an injected adapter can verify the result at runtime instead of
+ * casting. `introspect()` does not call this — wrap its result yourself when
+ * you want the guarantee:
+ *
+ * ```ts
+ * const metadata = parseGeneratorMetadata(await introspect(db));
+ * ```
+ */
+export function parseGeneratorMetadata(data) {
+    const out = generatorMetadataSchema(data);
+    if (out instanceof type.errors) {
+        throw new TypeError(`Invalid GeneratorMetadata: ${out.summary}`);
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@supabase/postgrest-typegen",
+  "version": "0.0.1",
+  "description": "Type generation for PostgREST from PostgreSQL schemas",
+  "keywords": [
+    "codegen",
+    "pg",
+    "postgres",
+    "postgrest",
+    "typegen",
+    "types"
+  ],
+  "homepage": "https://github.com/supabase/sdk",
+  "bugs": "https://github.com/supabase/sdk/issues",
+  "license": "MIT",
+  "author": "Supabase",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/supabase/sdk.git",
+    "directory": "packages/postgrest-typegen"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./introspection": {
+      "bun": "./src/introspection/index.ts",
+      "types": "./dist/introspection/index.d.ts",
+      "import": "./dist/introspection/index.js",
+      "require": "./dist/introspection/index.js",
+      "default": "./dist/introspection/index.js"
+    },
+    "./generation": {
+      "bun": "./src/generation/index.ts",
+      "types": "./dist/generation/index.d.ts",
+      "import": "./dist/generation/index.js",
+      "require": "./dist/generation/index.js",
+      "default": "./dist/generation/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "format-and-lint": "oxfmt --check . && oxlint --deny-warnings src test scripts",
+    "format-and-lint:fix": "oxfmt . && oxlint --fix src test scripts",
+    "knip": "knip",
+    "test": "bun scripts/run-tests.ts test/"
+  },
+  "dependencies": {
+    "arktype": "2.2.3",
+    "pg-format": "1.0.4",
+    "prettier": "3.5.3"
+  },
+  "devDependencies": {
+    "@testcontainers/postgresql": "^12.1.0",
+    "@tsconfig/node-ts": "^23.6.4",
+    "@tsconfig/node24": "^24.0.5",
+    "@types/bun": "^1.4.0",
+    "@types/node": "^26.3.0",
+    "@types/pg": "^8.23.1",
+    "@types/pg-format": "^1.0.5",
+    "knip": "^6.32.3",
+    "oxfmt": "0.65.0",
+    "oxlint": "1.80.0",
+    "oxlint-tsgolint": "7.0.2001",
+    "pg": "^8.23.0",
+    "testcontainers": "^12.1.0",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/generation/constants.ts

@@ -0,0 +1,11 @@
+/**
+ * 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"]);