@supabase/typegen
v0.4.0
Published
Language registry for supabase gen types: maps each --lang to its generator
Readme
@supabase/typegen
The language registry behind supabase gen types --lang <language>. It maps
each language name to the generator that renders PostgREST types for it, so that
adding a language is a pull request in this repository plus a dependency bump in
the Supabase CLI, with no per-language code in the CLI itself.
Status: alpha. The
Host,TypegenLanguage, option and error types are the contract with the CLI and follow semver from1.0.0on; before that, minor versions may change them.
Where it sits
Supabase CLI connects to the database, introspects it with the
introspect() re-exported here, looks --lang up here
|
@supabase/typegen this package: language name to generator
|
+-- in-process entry imports a generator function and calls it
| with the GeneratorMetadata object
|
+-- out-of-process entry runs the language's own tool in the user's
project with the GeneratorMetadata JSON
document on stdin, reads the code from stdoutIntrospection is not part of this package's logic. The consumer runs
introspect() and hands the resulting GeneratorMetadata to the language it
looked up here. introspect, Queryable, IntrospectOptions,
GeneratorMetadata and GENERATOR_METADATA_VERSION are re-exported from
@supabase/postgrest-typegen, so a consumer depends on this package alone: one
dependency to bump, and the document is always produced by the same
postgrest-typegen version the in-process generators were built against. That
is why the dependency is pinned to an exact version rather than a range. As soon
as each release is on npm, the Release postgrest-typegen workflow opens a
typegen release pull request that bumps the pin. Depending on both packages
directly would let a lockfile resolve two versions, introspecting with one and
generating with the other.
The two kinds of generator relate to postgrest-typegen differently:
- In-process generators import its types, so they depend on it. Today those are
the three bundled inside
postgrest-typegen; permanently it will be the TypeScript generator once it lives in supabase-js and is published to npm. - Out-of-process generators depend on nothing here. They read the JSON document,
whose shape is published as
generatorMetadataJsonSchemaand versioned byGENERATOR_METADATA_VERSION, and can be written in any language.supabase_typegenfor Dart was the first;supabase-typegenfor Swift is the second.
This is why the registry is its own package rather than part of
postgrest-typegen: once the TypeScript generator is imported from supabase-js,
which itself imports postgrest-typegen's types, a registry inside
postgrest-typegen would close a dependency cycle. A registry above both does
not.
Languages
| --lang | Runs | How | Flags |
| ------------ | -------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| typescript | in-process | generateTypescript from @supabase/postgrest-typegen | consumer: detect-one-to-one-relationships, postgrest-version, default-schema |
| go | in-process | generateGo from @supabase/postgrest-typegen | |
| python | in-process | generatePython from @supabase/postgrest-typegen | |
| swift | out-of-process | supabase-typegen --access-control <level>, built | --swift-access-control internal\|public, --swift-typegen-source <source> |
| dart | out-of-process | dart run supabase_typegen --output - in the project | |
The three in-process entries are a transition: as each generator relocates to its SDK repository (SDK-1641), its entry here changes to an out-of-process command, or for TypeScript to an import of the new npm package, and consumers notice nothing but a dependency bump.
Swift moved first. supabase-typegen is an executable in supabase-swift's
tools/supabase-typegen, not a package dependency: as a SwiftPM product its
swift-format dependency would pin every app's swift-syntax, and an Xcode project
without a Package.swift has nothing to swift run from.
The output targets one commit's @Table macro, so the generator must match the
project's supabase-swift. The entry builds it from source at a supabase-swift
commit, which it picks in this order:
--swift-typegen-source, when given. The value is read in a fixed order, without guessing:- A value that starts with
./,../,/or~/is a local checkout. Relative paths must start with./or../, so a folder named3.0.0is never read as a version, and~means the home folder. The entry checks that the checkout hastools/supabase-typegen, runsswift build -c release --package-path <checkout>/tools/supabase-typegenin the checkout's own.buildfolder, so later builds are incremental, and runs the binary from there. It never caches it, since the working tree can hold uncommitted changes. This is the form for working on the generator, or for a fork. - 40 hex characters are a commit SHA. An abbreviated SHA is refused.
- A semantic version, with or without a leading
v, is the commit its tagv<version>(or<version>) points at, pergit ls-remote; an annotated tag's commit wins. A version below 3 is refused, since supabase-swift 2.x has no generator. - Anything else is a branch, resolved to its commit with
git ls-remoteon every run, so new commits are picked up. A branch name that starts with-or holds whitespace,.., control characters or anything else git could read as an option or a refspec is refused before git runs.
A lookup that finds nothing names what it looked for, and for a branch name that is also a folder in
cwd, the./form to build it.- A value that starts with
The supabase-swift pin of the nearest
Package.resolvedthat has one: incwdor a parent, SwiftPM's or Xcode's inside the.xcodeprojor.xcworkspace. Lockfiles without a supabase-swift pin are skipped. For a monorepo run from its root, when no parent has a pin, the entry also looks up to two levels belowcwd, skipping.git,.build,node_modules,PodsandDerivedData; the pins found there must agree on the revision, or the run fails and asks for--swift-typegen-source. The pin'srevisionis built, so version, branch and revision pins all work.The latest supabase-swift 3.x release from
git ls-remote --tags: the highest stable 3.x once there is one, the highest 3.x prerelease before that (with semantic version precedence, soalpha.10followsalpha.9), and never another major version. A notice on stderr says so and asks to run from the app's directory, or to pass--swift-typegen-source, to match the pinned version.
Every run prints the commit it uses to stderr, for example
Using branch `main` at `4f2a9c1…`.. Except for a local checkout, the build
then goes:
- Only a 40-character lowercase hex SHA reaches
gitas a revision, a version must be a semantic version and a branch a plain branch name. Only regular files the user owns count asPackage.resolved, so another user's file in a shared parent such as/tmpcannot pick the commit, and a malformed one counts as no pin. - A binary already in
$XDG_CACHE_HOME/supabase/typegen/<revision>/(default~/Library/Cacheson macOS,~/.cacheelsewhere; an empty or relativeXDG_CACHE_HOMEis ignored) runs with no build. - Otherwise it checks that
gitandswift(Swift 6.2 / Xcode 26 or newer) are on PATH and, for a commit that did not come from upstream's own tags or branches, that it is upstream's. GitHub serves every commit of the fork network through the upstream URL, pull request heads included, so a version pin's tag (<version>orv<version>, pergit ls-remote) must point at the revision, and a branch pin's revision must be an ancestor of that upstream branch (a bare revision pin, or a SHA passed to--swift-typegen-source: the default branch), checked in a commits-only clone (--filter=tree:0, about 1.5 MB and a second). It then fetches the single commit into a temporary folder, checks thatHEADis the revision, and runsswift build -c release --package-path tools/supabase-typegen --disable-automatic-resolution. The flag builds the generator's committedPackage.resolvedexactly and fails rather than resolve other dependency versions. Linux adds--static-swift-stdlib, so the cached binary keeps working after the toolchain that built it is removed or upgraded. Git's repository variables (GIT_DIR,GIT_INDEX_FILEand the rest ofgit rev-parse --local-env-vars) are removed from these steps, so running inside a git hook cannot touch the user's repository. - For a version, from the pin, the flag or the latest release,
supabase-typegen --versionmust print that version. - The binary is copied beside its cache path and renamed into place, so concurrent runs are safe. The temporary folder is removed in every case.
The first build prints a line to stderr and takes a few minutes, mostly
compiling swift-syntax: about 5.5 minutes on an Apple M3 with Swift 6.4, and
about the same on Linux aarch64 with Swift 6.2 in Docker on that machine. A
pinned build trusts nothing the app does not already run: the supabase-swift
source at the pinned commit, the generator's pinned dependencies and the user's
toolchain. A version or the latest release trusts the tag at the time of the
run, and a branch anyone who can push to it, which is why a branch is never a
default. supabase-swift 2.x has no tools/supabase-typegen and fails with a
request to update to 3.0.0-alpha.1 or newer. The entry never runs a
supabase-typegen from PATH, and SUPABASE_TYPEGEN is gone: a stale binary
could generate code for the wrong version without a warning, and a local
checkout covers the development loop. Windows is not supported.
--swift-access-control lost private and package, which the new generator
does not accept.
Using the registry
import {
createNodeHost,
findLanguage,
introspect,
TypegenError,
} from "@supabase/typegen";
const language = findLanguage(lang);
if (!language) {
throw new Error(`unknown language ${lang}`);
}
const metadata = await introspect(pool, { includedSchemas: ["public"] });
const host = createNodeHost({ cwd: process.cwd() });
const code = await language.generate(metadata, { "swift-access-control": "public" }, host);
process.stdout.write(code);languages is the full list in display order, and each entry's options
describes its flags declaratively (name, audience, kind, default,
help, choices), so a consumer can render every language's flags without
knowing the languages. Option names are the flag names without dashes and are
also the keys of the values passed to generate. Missing values take the
defaults; unknown names and values outside a choice raise an
InvalidOptionError.
audience says who sets an option. user options are the CLI flags; render
options.filter((option) => option.audience === "user"). consumer options are
set by the calling program from what it knows about the target and never shown
to users. TypeScript has three: detect-one-to-one-relationships (default on;
the consumer turns it off for PostgREST 9 and below, where one-to-one joins come
back as arrays), postgrest-version (emitted as
__InternalSupabase.PostgrestVersion) and default-schema (default public).
postgres-meta's hosted route sets them from its
detect_one_to_one_relationships query parameter, POSTGREST_VERSION and
GENERATE_TYPES_DEFAULT_SCHEMA. The Supabase CLI already sniffs the local
stack's PostgREST version and used to expose the first one inverted as
--postgrest-v9-compat, usable only with --db-url; its adapter keeps that
flag as a deprecated alias that sets the option to false.
generate sorts the metadata with sortGeneratorMetadata itself, so callers
may pass introspect()'s output directly. It returns the complete contents of
the generated file for every language, so the consumer writes the result as-is
with no per-language handling. The in-process entries return the generator's
output verbatim: every bundled generator ends its file with a single newline,
and the registry adds one only when a Host.format implementation dropped it.
For Dart it is the tool's stdout verbatim, which is what makes
supabase gen types --lang dart match dart run supabase_typegen byte for
byte.
Hosted consumers that cannot spawn processes, such as postgres-meta's
/generators/* routes, filter on language.inProcess.
The Host
A Host is what the consumer knows and the registry does not:
cwd: the user's project directory. Out-of-process tools run there so they pick up the project's own toolchain and dependencies.env: environment for spawned tools, usuallyprocess.env.signal: optionalAbortSignal; aborting cancels the generation and kills a spawned tool.spawn(request): optional. Runs a command to completion and resolves with its exit code, stdout and stderr. It must reject with an error whosecodeis"ENOENT"when the executable is not found, as Node'schild_processdoes. A host that cannot run processes leaves it out; an out-of-process language then fails withSpawnUnavailableError, so hosted consumers offer onlyinProcesslanguages.format(code, fileName): optional. Replaces the formatter of in-process generators that format their own output. Only TypeScript does today, throughoxfmt, with the file nameoutput.ts. The CLI passes an identity function so its output stays byte-identical to what it emits today andoxfmtstays out of its bundle. Leave it out to get each generator's default, which for TypeScript needsoxfmtinstalled: it is an optional peer dependency, loaded only when the default formatter runs, so hosts that always passformatnever need it.
createNodeHost({ cwd, env, signal, format }) is a ready-made Host on
node:child_process for consumers without their own process runner. On Windows
it resolves the command through PATH and PATHEXT and runs .bat and .cmd
scripts through the command interpreter, since Flutter ships dart as
dart.bat there and spawn cannot start those directly; a command it cannot
find is reported as ENOENT like everywhere else. A host built on another
process runner needs the same treatment; planSpawn is exported so it starts
the same cmd.exe line, and the pieces it is built from
(resolveWindowsCommand, isWindowsScript, quoteForCmd) are exported for a
host that has to assemble the line itself. A token holding a double quote or a
line break is refused, since cmd.exe toggles quoting on every " and nothing
can escape it; a path holding % cannot be passed reliably either, since
%VAR% expands even inside quotes.
Errors
Every failure the registry raises extends TypegenError and carries the
language, so a consumer maps them to its own error model once:
InvalidOptionError(option): a value the language's option spec rejects.SpawnUnavailableError(tool): an out-of-process language was asked to generate through a host withoutspawn.ToolNotInstalledError(tool,installHint): the executable or package an out-of-process generator needs is missing incwd. For Dart that is either the Dart SDK or thesupabase_typegendev dependency of the project.ToolFailedError(command,exitCode,stderr): the tool exited unsuccessfully; the message includes its stderr.MetadataRejectedError(extendsToolFailedError, addsversion): the tool refused theGeneratorMetadatadocument, usually because it does not understand thisGENERATOR_METADATA_VERSION. The fix is updating the tool or the CLI so both agree.
Anything a generator throws itself, or a spawn rejection other than a missing
executable, passes through unchanged.
Adding a language
Add an entry to src/languages/ and list it in languages. Two shapes exist:
In-process (inProcessLanguage): wraps a generator function called in this
process. Every dependency of that generator lands in the CLI bundle, so this is
reserved for the transitional entries and, permanently, for TypeScript imported
from supabase-js.
Out-of-process (externalLanguage): describes a command line. The registry
runs it in the host's cwd with the sorted document from
serializeGeneratorMetadata on stdin and returns its stdout as the generated
code. The tool's contract:
- Read the JSON document from stdin; its
versionisGENERATOR_METADATA_VERSIONand its schema isgeneratorMetadataJsonSchema, both from@supabase/postgrest-typegen. - Write only the generated code to stdout; diagnostics and summaries go to stderr.
- Exit
0on success. The entry'sclassifymaps the tool's other exits to the typed failures, for example Dart's exit65(data error) toMetadataRejectedErrorand its "could not find package" stderr toToolNotInstalledErrorwith adart pub addhint.
Language flags are declared as OptionSpecs on the entry and reach generate
as validated values. Keep names identical to the flags users already know, and
mark settings that only a calling program supplies as audience: "consumer".
Testing splits by ownership: this package unit-tests each entry against a fake
host (arguments, working directory, stdin document, error classification), the
CLI keeps its end-to-end matrix for in-process languages plus a fake external
tool for the handoff, and each SDK repository owns the end-to-end test of its
tool against the CLI (supabase gen types --lang dart --local must produce the
same file as dart run supabase_typegen --local).
Development
bun install
bun run test # bun:test, no Docker needed
bun run check-types # tsc --noEmit
bun run check-types:consumer # type-check the way the CLI does, through @tsconfig/bun
bun run format-and-lint # oxfmt + oxlint check
bun run knip # unused code and dependencies
bun run build # emits dist/Releases
Released with release-please as its own component, tagged typegen/vX.Y.Z, and
published to npm as @supabase/typegen through OIDC trusted publishing. A
change to the --lang list or to the Host, option or error types is a change
to the CLI's public surface: describe it in the pull request so it reaches the
release notes the CLI reads before bumping.
