@supabase/postgrest-typegen 0.0.1

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./types.ts";
+export * from "./sort.ts";
+export * from "./introspection/index.ts";
+export * from "./generation/index.ts";

package/src/introspection/index.ts

@@ -0,0 +1,124 @@
+import {
+  GENERATOR_METADATA_VERSION,
+  type GeneratorMetadata,
+} from "../types.ts";
+import { normalizeRows } from "./normalize.ts";
+import { listRelationships } from "./relationships.ts";
+import { COLUMNS_SQL } from "./sql/columns.sql.ts";
+import { FOREIGN_TABLES_SQL } from "./sql/foreign_tables.sql.ts";
+import { FUNCTIONS_SQL } from "./sql/functions.sql.ts";
+import { DEFAULT_SYSTEM_SCHEMAS, filterByList } from "./sql/helpers.ts";
+import { MATERIALIZED_VIEWS_SQL } from "./sql/materialized_views.sql.ts";
+import { PRIMARY_KEYS_SQL } from "./sql/primary_keys.sql.ts";
+import { SCHEMAS_SQL } from "./sql/schemas.sql.ts";
+import { TABLES_SQL } from "./sql/table.sql.ts";
+import { TYPES_SQL } from "./sql/types.sql.ts";
+import { VIEWS_SQL } from "./sql/views.sql.ts";
+
+/**
+ * Minimal structural database interface. `pg.Pool` / `pg.Client` satisfy it,
+ * as do Bun and other drivers. postgres-meta injects its forked-pg pool here,
+ * keeping its own error handling on its side of the boundary. Errors throw;
+ * callers adapt.
+ */
+export interface Queryable {
+  query(sql: string): Promise<{ rows: any[] }>;
+}
+
+export interface IntrospectOptions {
+  includedSchemas?: string[];
+  excludedSchemas?: string[];
+}
+
+/**
+ * Introspect a database into the `GeneratorMetadata` contract.
+ *
+ * Port of `getGeneratorMetadata` from `postgres-meta/src/lib/generators.ts`.
+ * Instead of going through the `PostgresMeta*` manager classes, it calls the
+ * ported SQL builders directly with the single option combination the
+ * generator path uses, then applies the int8 `normalize` coercion so output is
+ * identical regardless of driver. Connection lifecycle is the caller's
+ * responsibility — unlike `getGeneratorMetadata`, this does not end the pool.
+ */
+export async function introspect(
+  db: Queryable,
+  opts: IntrospectOptions = {},
+): Promise<GeneratorMetadata> {
+  const includedSchemas = opts.includedSchemas ?? [];
+  const excludedSchemas = opts.excludedSchemas ?? [];
+  // Managers receive `undefined` (not an empty array) when no filter is set.
+  const included = includedSchemas.length > 0 ? includedSchemas : undefined;
+  const excluded = excludedSchemas.length > 0 ? excludedSchemas : undefined;
+
+  // Most queries exclude the system schemas by default; foreign tables and
+  // materialized views do not (matching the respective manager `list()` calls).
+  const systemExcludingFilter = filterByList(
+    included,
+    excluded,
+    DEFAULT_SYSTEM_SCHEMAS,
+  );
+  const plainFilter = filterByList(included, excluded);
+
+  const queryRows = async (sql: string) =>
+    normalizeRows((await db.query(sql)).rows);
+
+  const schemas = await queryRows(
+    SCHEMAS_SQL({
+      includeSystemSchemas: false,
+      nameFilter: systemExcludingFilter,
+    }),
+  );
+  const tables = await queryRows(
+    TABLES_SQL({ schemaFilter: systemExcludingFilter }),
+  );
+  const foreignTables = await queryRows(
+    FOREIGN_TABLES_SQL({ schemaFilter: plainFilter }),
+  );
+  const views = await queryRows(
+    VIEWS_SQL({ schemaFilter: systemExcludingFilter }),
+  );
+  const materializedViews = await queryRows(
+    MATERIALIZED_VIEWS_SQL({ schemaFilter: plainFilter }),
+  );
+  const columns = await queryRows(
+    COLUMNS_SQL({ schemaFilter: systemExcludingFilter }),
+  );
+  const primaryKeys = await queryRows(
+    PRIMARY_KEYS_SQL({ schemaFilter: systemExcludingFilter }),
+  );
+  const relationships = await listRelationships(db, {
+    includedSchemas: included,
+    excludedSchemas: excluded,
+  });
+  const functions = await queryRows(
+    FUNCTIONS_SQL({ schemaFilter: systemExcludingFilter }),
+  );
+  // types: includeSystemSchemas true (no schema filter), table + array types included.
+  const types = await queryRows(
+    TYPES_SQL({
+      schemaFilter: "",
+      includeTableTypes: true,
+      includeArrayTypes: true,
+    }),
+  );
+
+  return {
+    version: GENERATOR_METADATA_VERSION,
+    schemas: schemas.filter(
+      ({ name }) =>
+        !excludedSchemas.includes(name) &&
+        (includedSchemas.length === 0 || includedSchemas.includes(name)),
+    ),
+    tables,
+    foreignTables,
+    views,
+    materializedViews,
+    columns,
+    primaryKeys,
+    relationships,
+    functions: functions.filter(
+      ({ return_type }) => !["trigger", "event_trigger"].includes(return_type),
+    ),
+    types,
+  } as GeneratorMetadata;
+}

package/src/introspection/normalize.ts

@@ -0,0 +1,71 @@
+/**
+ * int8 → number coercion replicating postgres-meta's global int8 type parser.
+ *
+ * postgres-meta installs `pg.types.setTypeParser(INT8, ...)` in
+ * `src/lib/db.ts`, so every `bigint`/`int8` column comes back as a JS number
+ * when it fits in a safe integer, and as the raw string otherwise. Stock `pg`
+ * (and other drivers) instead return int8 as a string. To keep
+ * `GeneratorMetadata` byte-identical regardless of driver, we re-apply that
+ * exact coercion to the known int8 top-level fields after each query.
+ *
+ * Only top-level int8 columns need this: int8 values embedded inside `jsonb`
+ * columns (e.g. `args[].type_id`, composite type attributes)
+ * are decoded by the JSON parser as numbers in every driver, matching
+ * postgres-meta. Composite text ids like a column's `"<oid>.<attnum>"` are not
+ * safe integers, so the `Number.isSafeInteger` guard leaves them untouched —
+ * exactly as postgres-meta's parser does, since that column is `text`, not
+ * int8.
+ */
+
+/**
+ * Top-level result columns that are `int8` across the typegen introspection
+ * queries (schemas/tables/foreign-tables/views/materialized-views/columns/
+ * functions/types). Field names are unique enough across these queries that a
+ * name-based set faithfully reproduces the OID-based global parser.
+ */
+const INT8_FIELDS = [
+  "id",
+  "table_id",
+  "type_relation_id",
+  "return_type_id",
+  "return_type_relation_id",
+  "bytes",
+  "live_rows_estimate",
+  "dead_rows_estimate",
+] as const;
+
+/**
+ * Coerce a single value the way postgres-meta's `setTypeParser(INT8, ...)`
+ * does: parse to a number when it is a safe integer, otherwise keep the raw
+ * string. Non-string values (already-numbers, `null`) pass through unchanged.
+ */
+export function coerceInt8Value(value: unknown): unknown {
+  if (typeof value !== "string") {
+    return value;
+  }
+  const asNumber = Number(value);
+  if (Number.isSafeInteger(asNumber)) {
+    return asNumber;
+  }
+  return value;
+}
+
+/**
+ * Apply {@link coerceInt8Value} to the known int8 fields of a single row,
+ * mutating and returning it.
+ */
+export function normalizeRow<T extends Record<string, unknown>>(row: T): T {
+  for (const field of INT8_FIELDS) {
+    if (field in row) {
+      (row as Record<string, unknown>)[field] = coerceInt8Value(row[field]);
+    }
+  }
+  return row;
+}
+
+/** Apply {@link normalizeRow} to every row of a query result. */
+export function normalizeRows<T extends Record<string, unknown>>(
+  rows: T[],
+): T[] {
+  return rows.map(normalizeRow);
+}

package/src/introspection/relationships.ts

@@ -0,0 +1,173 @@
+import type { PostgresRelationship } from "../types.ts";
+import type { IntrospectOptions, Queryable } from "./index.ts";
+import { DEFAULT_SYSTEM_SCHEMAS, filterByList } from "./sql/helpers.ts";
+import { TABLE_RELATIONSHIPS_SQL } from "./sql/table_relationships.sql.ts";
+import { VIEWS_KEY_DEPENDENCIES_SQL } from "./sql/views_key_dependencies.sql.ts";
+
+/**
+ * Port of `postgres-meta/src/lib/PostgresMetaRelationships.ts`.
+ *
+ * The relationships used for type generation come in two parts:
+ *  1. table↔table m2o/o2o relationships, read directly from `pg_constraint`
+ *     (`TABLE_RELATIONSHIPS_SQL`); and
+ *  2. relationships that involve a view on either side, which PostgREST derives
+ *     by mapping a base table's foreign key columns onto the view columns that
+ *     select them (`VIEWS_KEY_DEPENDENCIES_SQL` + the cartesian-product
+ *     expansion below). This second part is pure TypeScript, not SQL — ported
+ *     verbatim from upstream.
+ *
+ * Adapted from:
+ * https://github.com/PostgREST/postgrest/blob/f9f0f79fa914ac00c11fbf7f4c558e14821e67e2/src/PostgREST/SchemaCache.hs#L392
+ */
+
+type ColDep = {
+  table_column: string;
+  view_columns: string[];
+};
+
+export type ViewKeyDependency = {
+  table_schema: string;
+  table_name: string;
+  view_schema: string;
+  view_name: string;
+  constraint_name: string;
+  constraint_type: "f" | "f_ref" | "p" | "p_ref";
+  column_dependencies: ColDep[];
+};
+
+/**
+ * Expand the table↔table relationships into the view↔table / table↔view /
+ * view↔view relationships implied by the view key dependencies. Pure function
+ * (no database) so the cartesian-product expansion can be unit-tested directly.
+ *
+ * Ported verbatim from `PostgresMetaRelationships.list()` (the body of the
+ * `allViewM2oAndO2oRelationships` block).
+ */
+export function expandViewRelationships(
+  allTableM2oAndO2oRelationships: PostgresRelationship[],
+  viewsKeyDependencies: ViewKeyDependency[],
+): PostgresRelationship[] {
+  return allTableM2oAndO2oRelationships.flatMap((r) => {
+    const expandKeyDepCols = (
+      colDeps: ColDep[],
+    ): { tableColumns: string[]; viewColumns: string[] }[] => {
+      const tableColumns = colDeps.map(({ table_column }) => table_column);
+      // https://gist.github.com/ssippe/1f92625532eef28be6974f898efb23ef?permalink_comment_id=3474581#gistcomment-3474581
+      const cartesianProduct = <T>(allEntries: T[][]): T[][] => {
+        return allEntries.reduce<T[][]>(
+          (results, entries) =>
+            results
+              .map((result) => entries.map((entry) => result.concat(entry)))
+              .reduce((subResults, result) => subResults.concat(result), []),
+          [[]],
+        );
+      };
+      const viewColumnsPermutations = cartesianProduct(
+        colDeps.map((cd) => cd.view_columns),
+      );
+      return viewColumnsPermutations.map((viewColumns) => ({
+        tableColumns,
+        viewColumns,
+      }));
+    };
+
+    const viewToTableKeyDeps = viewsKeyDependencies.filter(
+      (vkd) =>
+        vkd.table_schema === r.schema &&
+        vkd.table_name === r.relation &&
+        vkd.constraint_name === r.foreign_key_name &&
+        vkd.constraint_type === "f",
+    );
+    const tableToViewKeyDeps = viewsKeyDependencies.filter(
+      (vkd) =>
+        vkd.table_schema === r.referenced_schema &&
+        vkd.table_name === r.referenced_relation &&
+        vkd.constraint_name === r.foreign_key_name &&
+        vkd.constraint_type === "f_ref",
+    );
+
+    const viewToTableRelationships = viewToTableKeyDeps.flatMap((vtkd) =>
+      expandKeyDepCols(vtkd.column_dependencies).map(({ viewColumns }) => ({
+        foreign_key_name: r.foreign_key_name,
+        schema: vtkd.view_schema,
+        relation: vtkd.view_name,
+        columns: viewColumns,
+        is_one_to_one: r.is_one_to_one,
+        referenced_schema: r.referenced_schema,
+        referenced_relation: r.referenced_relation,
+        referenced_columns: r.referenced_columns,
+      })),
+    );
+
+    const tableToViewRelationships = tableToViewKeyDeps.flatMap((tvkd) =>
+      expandKeyDepCols(tvkd.column_dependencies).map(({ viewColumns }) => ({
+        foreign_key_name: r.foreign_key_name,
+        schema: r.schema,
+        relation: r.relation,
+        columns: r.columns,
+        is_one_to_one: r.is_one_to_one,
+        referenced_schema: tvkd.view_schema,
+        referenced_relation: tvkd.view_name,
+        referenced_columns: viewColumns,
+      })),
+    );
+
+    const viewToViewRelationships = viewToTableKeyDeps.flatMap((vtkd) =>
+      expandKeyDepCols(vtkd.column_dependencies).flatMap(({ viewColumns }) =>
+        tableToViewKeyDeps.flatMap((tvkd) =>
+          expandKeyDepCols(tvkd.column_dependencies).map(
+            ({ viewColumns: referencedViewColumns }) => ({
+              foreign_key_name: r.foreign_key_name,
+              schema: vtkd.view_schema,
+              relation: vtkd.view_name,
+              columns: viewColumns,
+              is_one_to_one: r.is_one_to_one,
+              referenced_schema: tvkd.view_schema,
+              referenced_relation: tvkd.view_name,
+              referenced_columns: referencedViewColumns,
+            }),
+          ),
+        ),
+      ),
+    );
+
+    return [
+      ...viewToTableRelationships,
+      ...tableToViewRelationships,
+      ...viewToViewRelationships,
+    ];
+  });
+}
+
+/**
+ * List all relationships (table↔table plus the view-derived ones) for the
+ * given schema filter. Mirrors `PostgresMetaRelationships.list()` with the
+ * generator path's defaults (`includeSystemSchemas: false`). Errors from the
+ * injected `Queryable` propagate by throwing — callers adapt.
+ */
+export async function listRelationships(
+  db: Queryable,
+  { includedSchemas, excludedSchemas }: IntrospectOptions = {},
+): Promise<PostgresRelationship[]> {
+  const schemaFilter = filterByList(
+    includedSchemas,
+    excludedSchemas,
+    DEFAULT_SYSTEM_SCHEMAS,
+  );
+
+  const { rows: allTableM2oAndO2oRelationships } = await db.query(
+    TABLE_RELATIONSHIPS_SQL({ schemaFilter }),
+  );
+  const { rows: viewsKeyDependencies } = await db.query(
+    VIEWS_KEY_DEPENDENCIES_SQL({ schemaFilter }),
+  );
+
+  const allViewM2oAndO2oRelationships = expandViewRelationships(
+    allTableM2oAndO2oRelationships as PostgresRelationship[],
+    viewsKeyDependencies as ViewKeyDependency[],
+  );
+
+  return (allTableM2oAndO2oRelationships as PostgresRelationship[]).concat(
+    allViewM2oAndO2oRelationships,
+  );
+}

package/src/introspection/sql/columns.sql.ts

@@ -0,0 +1,131 @@
+import { literal } from "pg-format";
+import type { SQLQueryPropsWithSchemaFilter } from "./common.ts";
+
+export const COLUMNS_SQL = (
+  props: SQLQueryPropsWithSchemaFilter & {
+    tableIdFilter?: string;
+    tableIdentifierFilter?: string;
+    columnNameFilter?: string;
+    idsFilter?: string;
+  },
+) => /* SQL */ `
+-- Adapted from information_schema.columns
+
+SELECT
+  c.oid :: int8 AS table_id,
+  nc.nspname AS schema,
+  c.relname AS table,
+  (c.oid || '.' || a.attnum) AS id,
+  a.attnum AS ordinal_position,
+  a.attname AS name,
+  CASE
+    WHEN a.atthasdef THEN pg_get_expr(ad.adbin, ad.adrelid)
+    ELSE NULL
+  END AS default_value,
+  CASE
+    WHEN t.typtype = 'd' THEN CASE
+      WHEN bt.typelem <> 0 :: oid
+      AND bt.typlen = -1 THEN 'ARRAY'
+      WHEN nbt.nspname = 'pg_catalog' THEN format_type(t.typbasetype, NULL)
+      ELSE 'USER-DEFINED'
+    END
+    ELSE CASE
+      WHEN t.typelem <> 0 :: oid
+      AND t.typlen = -1 THEN 'ARRAY'
+      WHEN nt.nspname = 'pg_catalog' THEN format_type(a.atttypid, NULL)
+      ELSE 'USER-DEFINED'
+    END
+  END AS data_type,
+  COALESCE(bt.typname, t.typname) AS format,
+  COALESCE(nbt.nspname, nt.nspname) AS type_schema,
+  a.attidentity IN ('a', 'd') AS is_identity,
+  CASE
+    a.attidentity
+    WHEN 'a' THEN 'ALWAYS'
+    WHEN 'd' THEN 'BY DEFAULT'
+    ELSE NULL
+  END AS identity_generation,
+  a.attgenerated IN ('s') AS is_generated,
+  NOT (
+    a.attnotnull
+    OR t.typtype = 'd' AND t.typnotnull
+  ) AS is_nullable,
+  (
+    c.relkind IN ('r', 'p')
+    OR c.relkind IN ('v', 'f') AND pg_column_is_updatable(c.oid, a.attnum, FALSE)
+  ) AS is_updatable,
+  uniques.table_id IS NOT NULL AS is_unique,
+  check_constraints.definition AS "check",
+  array_to_json(
+    array(
+      SELECT
+        enumlabel
+      FROM
+        pg_catalog.pg_enum enums
+      WHERE
+        enums.enumtypid = coalesce(bt.oid, t.oid)
+        OR enums.enumtypid = coalesce(bt.typelem, t.typelem)
+      ORDER BY
+        enums.enumsortorder
+    )
+  ) AS enums,
+  col_description(c.oid, a.attnum) AS comment
+FROM
+  pg_attribute a
+  LEFT JOIN pg_attrdef ad ON a.attrelid = ad.adrelid
+  AND a.attnum = ad.adnum
+  JOIN (
+    pg_class c
+    JOIN pg_namespace nc ON c.relnamespace = nc.oid
+  ) ON a.attrelid = c.oid
+  JOIN (
+    pg_type t
+    JOIN pg_namespace nt ON t.typnamespace = nt.oid
+  ) ON a.atttypid = t.oid
+  LEFT JOIN (
+    pg_type bt
+    JOIN pg_namespace nbt ON bt.typnamespace = nbt.oid
+  ) ON t.typtype = 'd'
+  AND t.typbasetype = bt.oid
+  LEFT JOIN (
+    SELECT DISTINCT ON (table_id, ordinal_position)
+      conrelid AS table_id,
+      conkey[1] AS ordinal_position
+    FROM pg_catalog.pg_constraint
+    WHERE contype = 'u' AND cardinality(conkey) = 1
+  ) AS uniques ON uniques.table_id = c.oid AND uniques.ordinal_position = a.attnum
+  LEFT JOIN (
+    -- We only select the first column check
+    SELECT DISTINCT ON (table_id, ordinal_position)
+      conrelid AS table_id,
+      conkey[1] AS ordinal_position,
+      substring(
+        pg_get_constraintdef(pg_constraint.oid, true),
+        8,
+        length(pg_get_constraintdef(pg_constraint.oid, true)) - 8
+      ) AS "definition"
+    FROM pg_constraint
+    WHERE contype = 'c' AND cardinality(conkey) = 1
+    ORDER BY table_id, ordinal_position, oid asc
+  ) AS check_constraints ON check_constraints.table_id = c.oid AND check_constraints.ordinal_position = a.attnum
+WHERE
+  ${props.schemaFilter ? `nc.nspname ${props.schemaFilter} AND` : ""}
+  ${props.idsFilter ? `(c.oid || '.' || a.attnum) ${props.idsFilter} AND` : ""}
+  ${props.columnNameFilter ? `(c.relname || '.' || a.attname) ${props.columnNameFilter} AND` : ""}
+  ${props.tableIdFilter ? `c.oid ${props.tableIdFilter} AND` : ""}
+  ${props.tableIdentifierFilter ? `nc.nspname || '.' || c.relname ${props.tableIdentifierFilter} AND` : ""}
+  NOT pg_is_other_temp_schema(nc.oid)
+  AND a.attnum > 0
+  AND NOT a.attisdropped
+  AND (c.relkind IN ('r', 'v', 'm', 'f', 'p'))
+  AND (
+    pg_has_role(c.relowner, 'USAGE')
+    OR has_column_privilege(
+      c.oid,
+      a.attnum,
+      'SELECT, INSERT, UPDATE, REFERENCES'
+    )
+  )
+${props.limit ? `limit ${literal(props.limit)}` : ""}
+${props.offset ? `offset ${literal(props.offset)}` : ""}
+`;

package/src/introspection/sql/common.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared prop shapes for the SQL builders, ported from
+ * `postgres-meta/src/lib/sql/common.ts`. Only the variants used by the
+ * typegen introspection path are kept.
+ */
+export type SQLQueryProps = {
+  limit?: number;
+  offset?: number;
+};
+
+export type SQLQueryPropsWithSchemaFilter = SQLQueryProps & {
+  schemaFilter?: string;
+};
+
+export type SQLQueryPropsWithSchemaFilterAndIdsFilter = SQLQueryProps & {
+  schemaFilter?: string;
+  idsFilter?: string;
+};

package/src/introspection/sql/foreign_tables.sql.ts

@@ -0,0 +1,26 @@
+import { literal } from "pg-format";
+import type { SQLQueryProps } from "./common.ts";
+
+export const FOREIGN_TABLES_SQL = (
+  props: SQLQueryProps & {
+    schemaFilter?: string;
+    idsFilter?: string;
+    tableIdentifierFilter?: string;
+  },
+) => /* SQL */ `
+SELECT
+  c.oid :: int8 AS id,
+  n.nspname AS schema,
+  c.relname AS name,
+  obj_description(c.oid) AS comment
+FROM
+  pg_class c
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE
+  ${props.schemaFilter ? `n.nspname ${props.schemaFilter} AND` : ""}
+  ${props.idsFilter ? `c.oid ${props.idsFilter} AND` : ""}
+  ${props.tableIdentifierFilter ? `(n.nspname || '.' || c.relname) ${props.tableIdentifierFilter} AND` : ""}
+  c.relkind = 'f'
+${props.limit ? `limit ${literal(props.limit)}` : ""}
+${props.offset ? `offset ${literal(props.offset)}` : ""}
+`;