@supabase/postgrest-typegen 0.0.1

package/dist/introspection/sql/helpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Schemas that postgres-meta excludes by default when `includeSystemSchemas`
+ * is false. Ported from `postgres-meta/src/lib/constants.ts`.
+ */
+export declare const DEFAULT_SYSTEM_SCHEMAS: string[];
+/**
+ * Build a SQL `IN (...)` / `NOT IN (...)` fragment for an include/exclude list,
+ * ported verbatim from `postgres-meta/src/lib/helpers.ts`. Values are escaped
+ * with pg-format's `literal`. Returns an empty string when there is nothing to
+ * filter, so callers interpolate it conditionally.
+ */
+export declare const filterByList: (include?: (string | number)[], exclude?: (string | number)[], defaultExclude?: (string | number)[]) => string;

package/dist/introspection/sql/helpers.js

@@ -0,0 +1,28 @@
+import { literal } from "pg-format";
+/**
+ * Schemas that postgres-meta excludes by default when `includeSystemSchemas`
+ * is false. Ported from `postgres-meta/src/lib/constants.ts`.
+ */
+export const DEFAULT_SYSTEM_SCHEMAS = [
+    "information_schema",
+    "pg_catalog",
+    "pg_toast",
+];
+/**
+ * Build a SQL `IN (...)` / `NOT IN (...)` fragment for an include/exclude list,
+ * ported verbatim from `postgres-meta/src/lib/helpers.ts`. Values are escaped
+ * with pg-format's `literal`. Returns an empty string when there is nothing to
+ * filter, so callers interpolate it conditionally.
+ */
+export const filterByList = (include, exclude, defaultExclude) => {
+    if (defaultExclude) {
+        exclude = defaultExclude.concat(exclude ?? []);
+    }
+    if (include?.length) {
+        return `IN (${include.map(literal).join(",")})`;
+    }
+    else if (exclude?.length) {
+        return `NOT IN (${exclude.map(literal).join(",")})`;
+    }
+    return "";
+};

package/dist/introspection/sql/materialized_views.sql.d.ts

@@ -0,0 +1,4 @@
+import type { SQLQueryPropsWithSchemaFilterAndIdsFilter } from "./common.ts";
+export declare const MATERIALIZED_VIEWS_SQL: (props: SQLQueryPropsWithSchemaFilterAndIdsFilter & {
+    materializedViewIdentifierFilter?: string;
+}) => string;

package/dist/introspection/sql/materialized_views.sql.js

@@ -0,0 +1,19 @@
+import { literal } from "pg-format";
+export const MATERIALIZED_VIEWS_SQL = (props) => /* SQL */ `
+select
+  c.oid::int8 as id,
+  n.nspname as schema,
+  c.relname as name,
+  c.relispopulated as is_populated,
+  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.materializedViewIdentifierFilter ? `(n.nspname || '.' || c.relname) ${props.materializedViewIdentifierFilter} AND` : ""}
+  c.relkind = 'm'
+${props.limit ? `limit ${literal(props.limit)}` : ""}
+${props.offset ? `offset ${literal(props.offset)}` : ""}
+`;

package/dist/introspection/sql/primary_keys.sql.d.ts

@@ -0,0 +1,4 @@
+import type { SQLQueryPropsWithSchemaFilter } from "./common.ts";
+export declare const PRIMARY_KEYS_SQL: (props: SQLQueryPropsWithSchemaFilter & {
+    tableIdentifierFilter?: string;
+}) => string;

package/dist/introspection/sql/primary_keys.sql.js

@@ -0,0 +1,32 @@
+import { literal } from "pg-format";
+export const PRIMARY_KEYS_SQL = (props) => /* SQL */ `
+SELECT
+  c.oid :: int8 AS table_id,
+  n.nspname AS schema,
+  c.relname AS table_name,
+  a.attname AS name
+FROM
+  pg_index i
+  JOIN pg_class c ON i.indrelid = c.oid
+  JOIN pg_namespace n ON c.relnamespace = n.oid
+  JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(i.indkey)
+WHERE
+  ${props.schemaFilter ? `n.nspname ${props.schemaFilter} AND` : ""}
+  ${props.tableIdentifierFilter ? `n.nspname || '.' || c.relname ${props.tableIdentifierFilter} AND` : ""}
+  i.indisprimary
+  AND c.relkind IN ('r', 'p')
+  AND NOT pg_is_other_temp_schema(n.oid)
+  AND (
+    pg_has_role(c.relowner, 'USAGE')
+    OR has_table_privilege(
+      c.oid,
+      'SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER'
+    )
+    OR has_any_column_privilege(c.oid, 'SELECT, INSERT, UPDATE, REFERENCES')
+  )
+ORDER BY
+  c.oid,
+  array_position(i.indkey, a.attnum)
+${props.limit ? `limit ${literal(props.limit)}` : ""}
+${props.offset ? `offset ${literal(props.offset)}` : ""}
+`;

package/dist/introspection/sql/schemas.sql.d.ts

@@ -0,0 +1,6 @@
+import type { SQLQueryProps } from "./common.ts";
+export declare const SCHEMAS_SQL: (props: SQLQueryProps & {
+    nameFilter?: string;
+    idsFilter?: string;
+    includeSystemSchemas?: boolean;
+}) => string;

package/dist/introspection/sql/schemas.sql.js

@@ -0,0 +1,24 @@
+import { literal } from "pg-format";
+export const SCHEMAS_SQL = (props) => /* SQL */ `
+-- Adapted from information_schema.schemata
+select
+  n.oid::int8 as id,
+  n.nspname as name,
+  u.rolname as owner
+from
+  pg_namespace n,
+  pg_roles u
+where
+  n.nspowner = u.oid
+  ${props.idsFilter ? `and n.oid ${props.idsFilter}` : ""}
+  ${props.nameFilter ? `and n.nspname ${props.nameFilter}` : ""}
+  ${!props.includeSystemSchemas ? `and not pg_catalog.starts_with(n.nspname, 'pg_')` : ""}
+  and (
+    pg_has_role(n.nspowner, 'USAGE')
+    or has_schema_privilege(n.oid, 'CREATE, USAGE')
+  )
+  and not pg_catalog.starts_with(n.nspname, 'pg_temp_')
+  and not pg_catalog.starts_with(n.nspname, 'pg_toast_temp_')
+${props.limit ? `limit ${literal(props.limit)}` : ""}
+${props.offset ? `offset ${literal(props.offset)}` : ""}
+`;

package/dist/introspection/sql/table.sql.d.ts

@@ -0,0 +1,4 @@
+import type { SQLQueryPropsWithSchemaFilterAndIdsFilter } from "./common.ts";
+export declare const TABLES_SQL: (props: SQLQueryPropsWithSchemaFilterAndIdsFilter & {
+    tableIdentifierFilter?: string;
+}) => string;

package/dist/introspection/sql/table.sql.js

@@ -0,0 +1,41 @@
+import { literal } from "pg-format";
+export const TABLES_SQL = (props) => /* SQL */ `
+SELECT
+  c.oid :: int8 AS id,
+  nc.nspname AS schema,
+  c.relname AS name,
+  c.relrowsecurity AS rls_enabled,
+  c.relforcerowsecurity AS rls_forced,
+  CASE
+    WHEN c.relreplident = 'd' THEN 'DEFAULT'
+    WHEN c.relreplident = 'i' THEN 'INDEX'
+    WHEN c.relreplident = 'f' THEN 'FULL'
+    ELSE 'NOTHING'
+  END AS replica_identity,
+  pg_total_relation_size(format('%I.%I', nc.nspname, c.relname)) :: int8 AS bytes,
+  pg_size_pretty(
+    pg_total_relation_size(format('%I.%I', nc.nspname, c.relname))
+  ) AS size,
+  pg_stat_get_live_tuples(c.oid) AS live_rows_estimate,
+  pg_stat_get_dead_tuples(c.oid) AS dead_rows_estimate,
+  obj_description(c.oid) AS comment
+FROM
+  pg_namespace nc
+  JOIN pg_class c ON nc.oid = c.relnamespace
+WHERE
+  ${props.schemaFilter ? `nc.nspname ${props.schemaFilter} AND` : ""}
+  ${props.idsFilter ? `c.oid ${props.idsFilter} AND` : ""}
+  ${props.tableIdentifierFilter ? `nc.nspname || '.' || c.relname ${props.tableIdentifierFilter} AND` : ""}
+  c.relkind IN ('r', 'p')
+  AND NOT pg_is_other_temp_schema(nc.oid)
+  AND (
+    pg_has_role(c.relowner, 'USAGE')
+    OR has_table_privilege(
+      c.oid,
+      'SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER'
+    )
+    OR has_any_column_privilege(c.oid, 'SELECT, INSERT, UPDATE, REFERENCES')
+  )
+${props.limit ? `limit ${literal(props.limit)}` : ""}
+${props.offset ? `offset ${literal(props.offset)}` : ""}
+`;

package/dist/introspection/sql/table_relationships.sql.d.ts

@@ -0,0 +1,2 @@
+import type { SQLQueryPropsWithSchemaFilter } from "./common.ts";
+export declare const TABLE_RELATIONSHIPS_SQL: (props: SQLQueryPropsWithSchemaFilter) => string;

package/dist/introspection/sql/table_relationships.sql.js

@@ -0,0 +1,49 @@
+export const TABLE_RELATIONSHIPS_SQL = (props) => /* SQL */ `
+-- Adapted from
+-- https://github.com/PostgREST/postgrest/blob/f9f0f79fa914ac00c11fbf7f4c558e14821e67e2/src/PostgREST/SchemaCache.hs#L722
+WITH
+pks_uniques_cols AS (
+  SELECT
+    connamespace,
+    conrelid,
+    jsonb_agg(column_info.cols) as cols
+  FROM pg_constraint
+  JOIN lateral (
+    SELECT array_agg(cols.attname order by cols.attnum) as cols
+    FROM ( select unnest(conkey) as col) _
+    JOIN pg_attribute cols on cols.attrelid = conrelid and cols.attnum = col
+  ) column_info ON TRUE
+  WHERE
+    contype IN ('p', 'u') and
+    connamespace::regnamespace::text <> 'pg_catalog'
+    ${props.schemaFilter ? `and connamespace::regnamespace::text ${props.schemaFilter}` : ""}
+  GROUP BY connamespace, conrelid
+)
+SELECT
+  traint.conname AS foreign_key_name,
+  ns1.nspname AS schema,
+  tab.relname AS relation,
+  column_info.cols AS columns,
+  ns2.nspname AS referenced_schema,
+  other.relname AS referenced_relation,
+  column_info.refs AS referenced_columns,
+  (column_info.cols IN (SELECT * FROM jsonb_array_elements(pks_uqs.cols))) AS is_one_to_one
+FROM pg_constraint traint
+JOIN LATERAL (
+  SELECT
+    jsonb_agg(cols.attname order by ord) AS cols,
+    jsonb_agg(refs.attname order by ord) AS refs
+  FROM unnest(traint.conkey, traint.confkey) WITH ORDINALITY AS _(col, ref, ord)
+  JOIN pg_attribute cols ON cols.attrelid = traint.conrelid AND cols.attnum = col
+  JOIN pg_attribute refs ON refs.attrelid = traint.confrelid AND refs.attnum = ref
+  WHERE ${props.schemaFilter ? `traint.connamespace::regnamespace::text ${props.schemaFilter}` : "true"}
+) AS column_info ON TRUE
+JOIN pg_namespace ns1 ON ns1.oid = traint.connamespace
+JOIN pg_class tab ON tab.oid = traint.conrelid
+JOIN pg_class other ON other.oid = traint.confrelid
+JOIN pg_namespace ns2 ON ns2.oid = other.relnamespace
+LEFT JOIN pks_uniques_cols pks_uqs ON pks_uqs.connamespace = traint.connamespace AND pks_uqs.conrelid = traint.conrelid
+WHERE traint.contype = 'f'
+AND traint.conparentid = 0
+${props.schemaFilter ? `and ns1.nspname ${props.schemaFilter}` : ""}
+`;

package/dist/introspection/sql/types.sql.d.ts

@@ -0,0 +1,5 @@
+import type { SQLQueryPropsWithSchemaFilterAndIdsFilter } from "./common.ts";
+export declare const TYPES_SQL: (props: SQLQueryPropsWithSchemaFilterAndIdsFilter & {
+    includeTableTypes?: boolean;
+    includeArrayTypes?: boolean;
+}) => string;

package/dist/introspection/sql/types.sql.js

@@ -0,0 +1,65 @@
+import { literal } from "pg-format";
+export const TYPES_SQL = (props) => /* SQL */ `
+select
+  t.oid::int8 as id,
+  t.typname as name,
+  n.nspname as schema,
+  format_type (t.oid, null) as format,
+  coalesce(t_enums.enums, '[]') as enums,
+  coalesce(t_attributes.attributes, '[]') as attributes,
+  obj_description (t.oid, 'pg_type') as comment,
+  nullif(t.typrelid::int8, 0) as type_relation_id
+from
+  pg_type t
+  left join pg_namespace n on n.oid = t.typnamespace
+  left join (
+    select
+      enumtypid,
+      jsonb_agg(enumlabel order by enumsortorder) as enums
+    from
+      pg_enum
+    group by
+      enumtypid
+  ) as t_enums on t_enums.enumtypid = t.oid
+  left join (
+    select
+      oid,
+      jsonb_agg(
+        jsonb_build_object('name', a.attname, 'type_id', a.atttypid::int8)
+        order by a.attnum asc
+      ) as attributes
+    from
+      pg_class c
+      join pg_attribute a on a.attrelid = c.oid
+    where
+      c.relkind = 'c' and not a.attisdropped
+    group by
+      c.oid
+  ) as t_attributes on t_attributes.oid = t.typrelid
+  where
+      (
+        t.typrelid = 0
+        or (
+          select
+            c.relkind ${props.includeTableTypes ? `in ('c', 'r', 'v', 'm', 'p')` : `= 'c'`}
+          from
+            pg_class c
+          where
+            c.oid = t.typrelid
+        )
+      )
+      ${!props.includeArrayTypes
+    ? `and not exists (
+                 select
+                 from
+                   pg_type el
+                 where
+                   el.oid = t.typelem
+                   and el.typarray = t.oid
+               )`
+    : ""}
+      ${props.schemaFilter ? `and n.nspname ${props.schemaFilter}` : ""}
+      ${props.idsFilter ? `and t.oid ${props.idsFilter}` : ""}
+${props.limit ? `limit ${literal(props.limit)}` : ""}
+${props.offset ? `offset ${literal(props.offset)}` : ""}
+`;

package/dist/introspection/sql/views.sql.d.ts

@@ -0,0 +1,4 @@
+import type { SQLQueryPropsWithSchemaFilterAndIdsFilter } from "./common.ts";
+export declare const VIEWS_SQL: (props: SQLQueryPropsWithSchemaFilterAndIdsFilter & {
+    viewIdentifierFilter?: string;
+}) => string;

package/dist/introspection/sql/views.sql.js

@@ -0,0 +1,20 @@
+import { literal } from "pg-format";
+export const VIEWS_SQL = (props) => /* SQL */ `
+SELECT
+  c.oid :: int8 AS id,
+  n.nspname AS schema,
+  c.relname AS name,
+  -- See definition of information_schema.views
+  (pg_relation_is_updatable(c.oid, false) & 20) = 20 AS is_updatable,
+  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.viewIdentifierFilter ? `(n.nspname || '.' || c.relname) ${props.viewIdentifierFilter} AND` : ""}
+  c.relkind = 'v'
+${props.limit ? `limit ${literal(props.limit)}` : ""}
+${props.offset ? `offset ${literal(props.offset)}` : ""}
+`;

package/dist/introspection/sql/views_key_dependencies.sql.d.ts

@@ -0,0 +1,2 @@
+import type { SQLQueryPropsWithSchemaFilter } from "./common.ts";
+export declare const VIEWS_KEY_DEPENDENCIES_SQL: (props: SQLQueryPropsWithSchemaFilter) => string;

package/dist/introspection/sql/views_key_dependencies.sql.js

@@ -0,0 +1,195 @@
+export const VIEWS_KEY_DEPENDENCIES_SQL = (props) => /* SQL */ `
+-- Adapted from
+-- https://github.com/PostgREST/postgrest/blob/f9f0f79fa914ac00c11fbf7f4c558e14821e67e2/src/PostgREST/SchemaCache.hs#L820
+with recursive
+pks_fks as (
+  -- pk + fk referencing col
+  select
+    contype::text as contype,
+    conname,
+    array_length(conkey, 1) as ncol,
+    conrelid as resorigtbl,
+    col as resorigcol,
+    ord
+  from pg_constraint
+  left join lateral unnest(conkey) with ordinality as _(col, ord) on true
+  where contype IN ('p', 'f')
+  union
+  -- fk referenced col
+  select
+    concat(contype, '_ref') as contype,
+    conname,
+    array_length(confkey, 1) as ncol,
+    confrelid,
+    col,
+    ord
+  from pg_constraint
+  left join lateral unnest(confkey) with ordinality as _(col, ord) on true
+  where contype='f'
+  ${props.schemaFilter ? `and connamespace::regnamespace::text ${props.schemaFilter}` : ""}
+),
+views as (
+  select
+    c.oid       as view_id,
+    n.nspname   as view_schema,
+    c.relname   as view_name,
+    r.ev_action as view_definition
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace
+  join pg_rewrite r on r.ev_class = c.oid
+  where c.relkind in ('v', 'm') 
+    ${props.schemaFilter ? `and n.nspname ${props.schemaFilter}` : ""}
+),
+transform_json as (
+  select
+    view_id, view_schema, view_name,
+    -- the following formatting is without indentation on purpose
+    -- to allow simple diffs, with less whitespace noise
+    replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      regexp_replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      replace(
+      replace(
+        view_definition::text,
+      -- This conversion to json is heavily optimized for performance.
+      -- The general idea is to use as few regexp_replace() calls as possible.
+      -- Simple replace() is a lot faster, so we jump through some hoops
+      -- to be able to use regexp_replace() only once.
+      -- This has been tested against a huge schema with 250+ different views.
+      -- The unit tests do NOT reflect all possible inputs. Be careful when changing this!
+      -- -----------------------------------------------
+      -- pattern           | replacement         | flags
+      -- -----------------------------------------------
+      -- <> in pg_node_tree is the same as null in JSON, but due to very poor performance of json_typeof
+      -- we need to make this an empty array here to prevent json_array_elements from throwing an error
+      -- when the targetList is null.
+      -- We'll need to put it first, to make the node protection below work for node lists that start with
+      -- null: (<> ..., too. This is the case for coldefexprs, when the first column does not have a default value.
+         '<>'              , '()'
+      -- , is not part of the pg_node_tree format, but used in the regex.
+      -- This removes all , that might be part of column names.
+      ), ','               , ''
+      -- The same applies for { and }, although those are used a lot in pg_node_tree.
+      -- We remove the escaped ones, which might be part of column names again.
+      ), E'\\\\{'            , ''
+      ), E'\\\\}'            , ''
+      -- The fields we need are formatted as json manually to protect them from the regex.
+      ), ' :targetList '   , ',"targetList":'
+      ), ' :resno '        , ',"resno":'
+      ), ' :resorigtbl '   , ',"resorigtbl":'
+      ), ' :resorigcol '   , ',"resorigcol":'
+      -- Make the regex also match the node type, e.g. \`{QUERY ...\`, to remove it in one pass.
+      ), '{'               , '{ :'
+      -- Protect node lists, which start with \`({\` or \`((\` from the greedy regex.
+      -- The extra \`{\` is removed again later.
+      ), '(('              , '{(('
+      ), '({'              , '{({'
+      -- This regex removes all unused fields to avoid the need to format all of them correctly.
+      -- This leads to a smaller json result as well.
+      -- Removal stops at \`,\` for used fields (see above) and \`}\` for the end of the current node.
+      -- Nesting can't be parsed correctly with a regex, so we stop at \`{\` as well and
+      -- add an empty key for the followig node.
+      ), ' :[^}{,]+'       , ',"":'              , 'g'
+      -- For performance, the regex also added those empty keys when hitting a \`,\` or \`}\`.
+      -- Those are removed next.
+      ), ',"":}'           , '}'
+      ), ',"":,'           , ','
+      -- This reverses the "node list protection" from above.
+      ), '{('              , '('
+      -- Every key above has been added with a \`,\` so far. The first key in an object doesn't need it.
+      ), '{,'              , '{'
+      -- pg_node_tree has \`()\` around lists, but JSON uses \`[]\`
+      ), '('               , '['
+      ), ')'               , ']'
+      -- pg_node_tree has \` \` between list items, but JSON uses \`,\`
+      ), ' '             , ','
+    )::json as view_definition
+  from views
+),
+target_entries as(
+  select
+    view_id, view_schema, view_name,
+    json_array_elements(view_definition->0->'targetList') as entry
+  from transform_json
+),
+results as(
+  select
+    view_id, view_schema, view_name,
+    (entry->>'resno')::int as view_column,
+    (entry->>'resorigtbl')::oid as resorigtbl,
+    (entry->>'resorigcol')::int as resorigcol
+  from target_entries
+),
+-- CYCLE detection according to PG docs: https://www.postgresql.org/docs/current/queries-with.html#QUERIES-WITH-CYCLE
+-- Can be replaced with CYCLE clause once PG v13 is EOL.
+recursion(view_id, view_schema, view_name, view_column, resorigtbl, resorigcol, is_cycle, path) as(
+  select
+    r.*,
+    false,
+    ARRAY[resorigtbl]
+  from results r
+  where ${props.schemaFilter ? `view_schema ${props.schemaFilter}` : "true"}
+  union all
+  select
+    view.view_id,
+    view.view_schema,
+    view.view_name,
+    view.view_column,
+    tab.resorigtbl,
+    tab.resorigcol,
+    tab.resorigtbl = ANY(path),
+    path || tab.resorigtbl
+  from recursion view
+  join results tab on view.resorigtbl=tab.view_id and view.resorigcol=tab.view_column
+  where not is_cycle
+),
+repeated_references as(
+  select
+    view_id,
+    view_schema,
+    view_name,
+    resorigtbl,
+    resorigcol,
+    array_agg(attname) as view_columns
+  from recursion
+  join pg_attribute vcol on vcol.attrelid = view_id and vcol.attnum = view_column
+  group by
+    view_id,
+    view_schema,
+    view_name,
+    resorigtbl,
+    resorigcol
+)
+select
+  sch.nspname as table_schema,
+  tbl.relname as table_name,
+  rep.view_schema,
+  rep.view_name,
+  pks_fks.conname as constraint_name,
+  pks_fks.contype as constraint_type,
+  jsonb_agg(
+    jsonb_build_object('table_column', col.attname, 'view_columns', view_columns) order by pks_fks.ord
+  ) as column_dependencies
+from repeated_references rep
+join pks_fks using (resorigtbl, resorigcol)
+join pg_class tbl on tbl.oid = rep.resorigtbl
+join pg_attribute col on col.attrelid = tbl.oid and col.attnum = rep.resorigcol
+join pg_namespace sch on sch.oid = tbl.relnamespace
+group by sch.nspname, tbl.relname,  rep.view_schema, rep.view_name, pks_fks.conname, pks_fks.contype, pks_fks.ncol
+-- make sure we only return key for which all columns are referenced in the view - no partial PKs or FKs
+having ncol = array_length(array_agg(row(col.attname, view_columns) order by pks_fks.ord), 1)
+`;

package/dist/sort.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonical ordering pass for {@link GeneratorMetadata}.
+ *
+ * The language generators consume the metadata collections in array order.
+ * This pass is the single, generator-agnostic stabilizer: it returns a new
+ * `GeneratorMetadata` whose every collection is ordered so that any producer
+ * (the bundled SQL `introspect()` or a custom injected adapter) yields
+ * byte-stable codegen. Generators document that they expect input pre-sorted
+ * with this function; ordering is intentionally NOT enforced inside
+ * `introspect()` so the concern lives in one place.
+ *
+ * **The TypeScript generator is the source of truth for ordering.** The keys
+ * below replicate the sorts that `generateTypescript` historically applied
+ * internally (schemas/tables/views/functions/types/columns/relationships by
+ * name; function args by name), so that generator can drop its own sorting and
+ * stay byte-identical. The other generators then inherit the same canonical
+ * order for free.
+ *
+ * Keys are **semantic** (schema + name + signature), never oid: equivalent
+ * databases assign different oids, so an oid sort would still churn output
+ * across environments. `id` is only a final tie-breaker for a total order.
+ *
+ * Composite type `attributes` and enum values are left untouched — their order
+ * is semantically meaningful (struct field / enum-label order) and must be
+ * preserved. Function `args` are sorted by name because PostgREST RPC args are
+ * addressed by name (the generated type is an object), matching TypeScript.
+ */
+import type { GeneratorMetadata } from "./types.ts";
+/**
+ * Return a new {@link GeneratorMetadata} with every collection ordered by a
+ * stable, total, semantic key (matching the TypeScript generator's ordering).
+ * Pure (does not mutate the input) and idempotent. Apply this after
+ * introspection and before any `generate*` call.
+ */
+export declare function sortGeneratorMetadata(metadata: GeneratorMetadata): GeneratorMetadata;

package/dist/sort.js

@@ -0,0 +1,48 @@
+// Relations (tables/views/materialized views/foreign tables) and types share a
+// (schema, name) identity within a database; `id` breaks any residual tie.
+const bySchemaName = (a, b) => a.schema.localeCompare(b.schema) ||
+    a.name.localeCompare(b.name) ||
+    a.id - b.id;
+// Mirrors the TypeScript generator's historical `relationships.sort`.
+const byRelationship = (a, b) => a.foreign_key_name.localeCompare(b.foreign_key_name) ||
+    a.referenced_relation.localeCompare(b.referenced_relation) ||
+    JSON.stringify(a.referenced_columns).localeCompare(JSON.stringify(b.referenced_columns));
+/**
+ * Return a new {@link GeneratorMetadata} with every collection ordered by a
+ * stable, total, semantic key (matching the TypeScript generator's ordering).
+ * Pure (does not mutate the input) and idempotent. Apply this after
+ * introspection and before any `generate*` call.
+ */
+export function sortGeneratorMetadata(metadata) {
+    return {
+        version: metadata.version,
+        schemas: [...metadata.schemas].sort((a, b) => a.name.localeCompare(b.name) || a.id - b.id),
+        tables: [...metadata.tables].sort(bySchemaName),
+        foreignTables: [...metadata.foreignTables].sort(bySchemaName),
+        views: [...metadata.views].sort(bySchemaName),
+        materializedViews: [...metadata.materializedViews].sort(bySchemaName),
+        // Group columns by their table's (schema, name); name-order within a table
+        // (matches the TypeScript generator's per-table `columns.sort(by name)`).
+        columns: [...metadata.columns].sort((a, b) => a.schema.localeCompare(b.schema) ||
+            a.table.localeCompare(b.table) ||
+            a.name.localeCompare(b.name)),
+        // Grouped by table like `columns`; within a table the SQL's declared
+        // column order (`array_position(indkey, attnum)`) is preserved by the
+        // stable sort, since composite key order is meaningful.
+        primaryKeys: [...metadata.primaryKeys].sort((a, b) => a.schema.localeCompare(b.schema) ||
+            a.table_name.localeCompare(b.table_name)),
+        relationships: [...metadata.relationships].sort(byRelationship),
+        // Functions can overload, so the signature is part of the identity. Args
+        // are addressed by name in generated RPC types, so sort them by name too.
+        functions: [...metadata.functions]
+            .sort((a, b) => a.schema.localeCompare(b.schema) ||
+            a.name.localeCompare(b.name) ||
+            a.identity_argument_types.localeCompare(b.identity_argument_types) ||
+            a.id - b.id)
+            .map((fn) => ({
+            ...fn,
+            args: [...fn.args].sort((a, b) => a.name.localeCompare(b.name)),
+        })),
+        types: [...metadata.types].sort(bySchemaName),
+    };
+}