@supabase/postgrest-typegen 0.0.1

package/src/sort.ts

@@ -0,0 +1,102 @@
+/**
+ * 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, PostgresRelationship } from "./types.ts";
+
+// 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: { schema: string; name: string; id: number },
+  b: { schema: string; name: string; id: number },
+): number =>
+  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: PostgresRelationship,
+  b: PostgresRelationship,
+): number =>
+  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: GeneratorMetadata,
+): GeneratorMetadata {
+  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),
+  };
+}

package/src/types.ts

@@ -0,0 +1,237 @@
+/**
+ * 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",
+});
+export type PostgresColumn = typeof postgresColumnSchema.infer;
+
+const postgresForeignTableSchema = type({
+  id: "number",
+  schema: "string",
+  name: "string",
+  comment: "string | null",
+  "columns?": postgresColumnSchema.array(),
+});
+export type PostgresForeignTable = typeof postgresForeignTableSchema.infer;
+
+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"),
+});
+export type PostgresFunction = typeof postgresFunctionSchema.infer;
+
+const postgresMaterializedViewSchema = type({
+  id: "number",
+  schema: "string",
+  name: "string",
+  is_populated: "boolean",
+  comment: "string | null",
+  "columns?": postgresColumnSchema.array(),
+});
+export type PostgresMaterializedView =
+  typeof postgresMaterializedViewSchema.infer;
+
+const postgresPrimaryKeySchema = type({
+  schema: "string",
+  table_name: "string",
+  name: "string",
+  table_id: "number",
+});
+export type PostgresPrimaryKey = typeof postgresPrimaryKeySchema.infer;
+
+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[]",
+});
+export type PostgresRelationship = typeof postgresRelationshipSchema.infer;
+
+const postgresSchemaSchema = type({
+  id: "number",
+  name: "string",
+  owner: "string",
+});
+export type PostgresSchema = typeof postgresSchemaSchema.infer;
+
+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(),
+});
+export type PostgresTable = typeof postgresTableSchema.infer;
+
+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",
+});
+export type PostgresType = typeof postgresTypeSchema.infer;
+
+const postgresViewSchema = type({
+  id: "number",
+  schema: "string",
+  name: "string",
+  is_updatable: "boolean",
+  comment: "string | null",
+  "columns?": postgresColumnSchema.array(),
+});
+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 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(),
+});
+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 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: GeneratorMetadata,
+): string {
+  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: unknown): GeneratorMetadata {
+  const out = generatorMetadataSchema(data);
+  if (out instanceof type.errors) {
+    throw new TypeError(`Invalid GeneratorMetadata: ${out.summary}`);
+  }
+  return out;
+}