feat: add supabase_typegen package generating typed table definitions

[spydon]

What kind of change does this PR introduce?

Feature (draft, layer 2 of the typed table access work, stacked on #1634). Adds a new supabase_typegen package: a standalone code generator that turns a database schema into the typed table definitions introduced in #1634, so users get the fully typed surface without writing any of it by hand.

Linear: SDK-1362

What is the new behavior?

supabase gen types --lang json --local > schema.json
dart run supabase_typegen --input schema.json

reads the language-neutral GeneratorMetadata introspection document (the @supabase/postgrest-typegen contract from supabase/pg-toolbelt#302, which postgres-meta itself consumes after supabase/postgres-meta#1084; --input - reads it from stdin) and emits one Dart file containing, per table:

• a zero-cost row extension type over the decoded JSON map with typed getters (DateTime parsing, double/num coercion, List casts, Postgres enum mapping),
• Insert and Update value extension types that implement Map<String, dynamic>, with required parameters derived from NOT NULL-without-default columns and null-aware omission for everything else; explicit SQL NULL writes go through generated set…ToNull copy methods that only exist for nullable, writable columns,
• a PostgrestTable definition plus TableColumn tokens for compile-time checked filters,
• Dart enums for Postgres enums with wire-name mapping (toString returns the wire name so enum values work directly in filters).

See packages/supabase_typegen/test/goldens/supabase_schema.dart for what the output looks like for the fixture schema.

Design choices worth reviewing:

• Introspection source: the GeneratorMetadata contract of @supabase/postgrest-typegen (feat(postgrest-typegen): add package with multi-language code generation pg-toolbelt#302), the same document the TypeScript, Go, Swift, and Python generators consume; structural validation rejects non-matching documents. It comes straight from the database catalog, so the output is exact where API-derived descriptions are lossy: NOT NULL columns with a database default read as non-nullable but stay optional on insert, identity columns are recognized, and GENERATED ALWAYS columns appear in the row type but are excluded from the insert and update types. This is the single introspection source; the parser is a pure function over the JSON document behind the SchemaDescription model.
• Naming: books emits BooksRow/BooksInsert/BooksUpdate plus a Books namespace class (no English singularization, so names stay predictable). Identifiers are sanitized against Dart reserved words and Map member names with a $ suffix, and collisions are deduplicated.
• Lint-clean output: the emitted code (checked in as a golden) passes supabase_lints and DCM with zero issues, including the strict extension type rules.

Deliberately deferred: foreign key relationship getters (the fk targets are already parsed into the model) and typed rpc functions.

Additional context

• Depends on the postgrest-typegen extraction (feat(postgrest-typegen): add package with multi-language code generation pg-toolbelt#302, feat: consume @supabase/postgrest-typegen for type generation postgres-meta#1084, with the json output in feat: add json output exposing the GeneratorMetadata contract postgres-meta#1110) for producing the metadata document, plus feat(gen): add dart and json output languages to gen types cli#6230 exposing it as supabase gen types --lang json and --lang dart.
• The package is excluded from the SDK compliance scan via .sdk-parse-ignore since it is a development-time tool, not SDK client surface; the symbol, drift and schema checks pass locally against the base branch.
• supabase_typegen is added to the CI dart test matrix; tests are fully mocked/fixture-based (introspection unit tests over a checked-in metadata fixture, a whitespace-insensitive golden comparison with a tool/regenerate_goldens.dart refresh script, and behavior tests that run the generated golden code against a mock HTTP client to verify wire formats end to end).
• publish_to: none until the API settles.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/supabase-gen

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}