@supabase/postgrest-typegen 0.4.0 → 0.6.0

package/README.md

@@ -1,31 +1,28 @@
 # @supabase/postgrest-typegen
 
 Type generation for [PostgREST](https://postgrest.org) from a PostgreSQL
-schema. This is the type-generation engine behind `supabase gen types`,
-extracted from [postgres-meta](https://github.com/supabase/postgres-meta) into a
-small, driver-agnostic library.
+schema: the type-generation engine behind `supabase gen types`, as a small,
+driver-agnostic library.
 
-> **Status:** alpha. The public API is settling as generators and introspection
-> are ported.
+> **Status:** alpha. The public API may still change between minor versions.
 
-## Scope: introspection is permanent, four generators are transitional
+## Scope: introspection is permanent, three generators are transitional
 
 This package's permanent job is introspection and the `GeneratorMetadata`
 contract (see "Out-of-process generators" below): any *new* language's
 generator lives in that language's own SDK repo, consuming this package's
 JSON output, not inside `postgrest-typegen`.
 
-The TypeScript, Go, Python, and Swift generators bundled here are a
+The TypeScript, Go, and Python generators bundled here are a
 **deliberate transition**, not the target architecture for new languages.
-They were ported byte-for-byte from postgres-meta's own templates so
-`supabase gen types` kept working unchanged; postgres-meta has since deleted
-its copies and consumes this package instead. It's decided that all four
-eventually move out to their own SDK repos too (tracked in SDK-1641), not yet
-scheduled — sequenced after postgres-meta's cutover to this package settles.
+They move out one language at a time, TypeScript first into supabase-js, then
+Go and Python. Swift's generator is the `supabase-typegen` executable in
+[supabase-swift](https://github.com/supabase/supabase-swift), which
+`supabase gen types --lang swift` runs.
 
 > [!IMPORTANT]
-> **We are no longer accepting contributions that fix the bundled generators.**
-> Because each of the four is moving out to its own language's SDK repository,
+> **We do not accept contributions that fix the bundled generators.**
+> Because each of the three is moving out to its own language's SDK repository,
 > a fix landed here would have to be made a second time in the destination
 > repository, and postgres-meta and the CLI only pick it up once they bump
 > their pinned version of this package. Please open an issue describing the
@@ -57,7 +54,7 @@ generators.
 
 ### Stable ordering (`sortGeneratorMetadata`)
 
-The Go/Python/Swift generators emit tables, views, and materialized views in
+The Go/Python generators emit tables, views, and materialized views in
 `GeneratorMetadata` order, so their output depends on how the producer ordered
 its collections (a SQL introspector returns rows in environment-dependent heap
 order). `sortGeneratorMetadata` is a pure pass that canonically sorts every
@@ -65,6 +62,76 @@ collection; **apply it after introspection and before any `generate*` call** so
 output is deterministic regardless of the producer. Generators expect
 pre-sorted input and do not re-sort it themselves.
 
+### RPC functions (`rpcFunctions`, `resolveRpcFunctions`)
+
+`functions` is `pg_proc` as introspected. Which of those functions PostgREST
+exposes under `/rpc`, how overloads group, what a call returns and whether a
+function doubles as a computed field or an embeddable relation are PostgREST
+rules, so `introspect()` applies them once and attaches the result as
+`rpcFunctions`. A generator in any language reads that collection instead of
+reimplementing the rules:
+
+```ts
+for (const fn of metadata.rpcFunctions ?? resolveRpcFunctions(metadata)) {
+  // fn.schema, fn.name, and one entry per overload PostgREST can resolve.
+  for (const overload of fn.overloads) {
+    overload.args; // input parameters: name, mode, type reference, has_default, relation_id
+    overload.returns; // type reference, plus relation_id or RETURNS TABLE columns
+    overload.is_set_returning; // the response is an array
+    overload.setof_options; // embeddable like a relation: from, to, is_one_to_one
+    overload.computed_field_of; // selectable as a column of this relation
+    overload.error; // why PostgREST cannot resolve a call, else null
+  }
+}
+```
+
+A type reference carries `type_id`, `format` (the type's name, spelled like
+`PostgresColumn.format`) and `type_schema`, so a generator maps it with the
+same table it uses for columns. An overload's `error` is the message the
+TypeScript generator emits as the `Returns` type of an unresolvable overload:
+two overloads PostgREST cannot tell apart, or a sole unnamed row parameter,
+which PostgREST never matches under `/rpc` (such a function is a computed
+field or computed relationship, reached by embedding it from its relation).
+Overloads are ordered by argument list, then by return type; the
+TypeScript generator emits them in that order.
+
+`resolveRpcFunctions` is pure and deterministic, so a custom producer attaches
+it the same way, and a document without the collection (produced before it
+existed) still generates: the TypeScript generator falls back to running the
+pass itself.
+
+### View column nullability
+
+PostgreSQL never marks view columns `NOT NULL`, so `introspect()` works out
+`is_nullable` for view and materialized view columns from the view's query
+tree. A column is not nullable when it is a plain reference to a `NOT NULL`
+column (directly, through another view, a subquery, a non-recursive CTE, a
+join alias or a `GROUP BY` key) and nothing on the way puts it on the nullable
+side of an outer join, in a set operation such as `UNION` or under
+`GROUPING SETS`/`ROLLUP`/`CUBE`. This works the same on every supported
+PostgreSQL version. Expressions stay nullable, even ones that cannot return
+null.
+
+For a column the catalog cannot prove non-null, such as `coalesce(x, 0)` or
+`count(*)`, add a line containing only `@notNull` to its comment:
+
+```sql
+comment on column my_view.total is '@notNull';
+```
+
+The directive is honored on view and materialized view columns only, and the
+comment is passed through unchanged.
+
+The inference describes the rows a query reads, so a few values can still be
+null where the type says otherwise:
+
+- Rows returned by a write through an `INSTEAD OF` trigger are the trigger's
+  `NEW`, so a column the trigger leaves unset comes back null.
+- PostgreSQL does not enforce `NOT NULL` inside composite values, so a column
+  whose type is a view's row type can hold a row with null fields.
+- A materialized view keeps the rows of its last refresh, including nulls from
+  before its source column became `NOT NULL`.
+
 ### Runtime validation (opt-in)
 
 `GeneratorMetadata` is backed by an [ArkType](https://arktype.io) schema, so a
@@ -104,10 +171,48 @@ const json = serializeGeneratorMetadata(sortGeneratorMetadata(metadata));
 generatorMetadataJsonSchema;
 ```
 
-`GeneratorMetadata.version` is bumped whenever the shape changes in a way a
-consumer should branch on, since an out-of-process consumer only sees the
-serialized document and can't otherwise detect a shape change until something
-breaks at read time.
+### Contract compatibility (`GeneratorMetadata.version`)
+
+`GeneratorMetadata` is read by code that does not install this package: an
+out-of-process generator sees only the serialized document, and postgres-meta
+and the Supabase CLI consume it through a pinned registry version. The shape
+therefore changes under one rule:
+
+- **A new field is optional and has a documented fallback.** The fallback
+  lives in the consumers that read the field, so a document produced by any
+  released version still parses and generates what it generated before. The
+  view flags `is_insert_enabled` and `is_update_enabled` are the model: they
+  are optional, and the TypeScript generator, the only one that emits view
+  write types, falls back to `is_updatable` when they are absent. The
+  `rpcFunctions` collection follows the same rule: a generator that does not
+  find it runs `resolveRpcFunctions` on the raw `functions` itself.
+- **Anything else moves `GENERATOR_METADATA_VERSION`:** removing or renaming a
+  field, making one required, narrowing its type, or changing what an existing
+  value means. The version is `1`.
+
+`parseGeneratorMetadata` and `generatorMetadataJsonSchema` pin the exact
+version string, so a consumer on another version fails at parse time with a
+clear error instead of misreading the document. An out-of-process generator
+should do the same and exit distinctly when it meets a version it does not
+know; `@supabase/typegen` maps Dart's exit code 65 to `MetadataRejectedError`
+for that reason.
+
+The contract version and the package version are independent:
+
+- `GENERATOR_METADATA_VERSION` changes only with an incompatible shape change.
+  A release that moves it is marked breaking in the changelog, and consumers
+  that read the serialized document pin this number, not the npm version.
+- The package follows semantic versioning and is on `0.x`. A minor release
+  may change generated output or the TypeScript
+  API, with breaking changes called out in the changelog; a patch release
+  changes neither on purpose. The four generators' output is part of the
+  public surface: any change to it is described in the pull request so it
+  reaches the release notes that postgres-meta and the CLI read before bumping.
+
+Changes to `src/types.ts` and `src/introspection/` are reviewed by
+[@spydon](https://github.com/spydon), listed in `CODEOWNERS` for this package
+next to the SDK team, so every contract change has one person who checks it
+against this rule.
 
 ### Generators
 
@@ -116,7 +221,6 @@ import {
   generateTypescript, // async (formats its output)
   generateGo,
   generatePython,
-  generateSwift,
 } from "@supabase/postgrest-typegen/generation";
 ```
 
@@ -125,7 +229,6 @@ import {
 | `generateTypescript` | `{ detectOneToOneRelationships?, postgrestVersion?, defaultSchema?, format? }` |
 | `generateGo`         | —                                                                              |
 | `generatePython`     | —                                                                              |
-| `generateSwift`      | `{ accessControl?: 'internal' \| 'public' \| 'private' \| 'package' }`         |
 
 Every generator returns the complete contents of the generated file, ending
 with a single newline, so consumers write the result as-is.
@@ -138,6 +241,22 @@ worker-pool-backed formatter) and it is never loaded or needed. Calling
 `generateTypescript` without `format` when `oxfmt` is missing throws an error
 saying so.
 
+## Generating types without database credentials
+
+`GeneratorMetadata` is the pluggable contract, so generating types for a
+project without its database password means replacing the introspection
+producer, not touching any generator. No such producer ships in this package.
+
+Generating from PostgREST's OpenAPI output needs PostgREST to include the
+introspection details the generators depend on: the standard OpenAPI document
+alone carries about half of what the TypeScript output needs. That is the
+`x-postgrest-typegen-metadata` extension proposed in
+[supabase/postgrest#6](https://github.com/supabase/postgrest/pull/6). A
+producer that reads it and matches `introspect()` byte for byte exists in
+[supabase/pg-toolbelt#303](https://github.com/supabase/pg-toolbelt/pull/303)
+and is the starting point for porting one here once the extension is
+available.
+
 ## Installation
 
 Not yet published; consumed in-repo for now (`packages/postgrest-typegen`).
@@ -149,6 +268,20 @@ npm install pg
 npm install oxfmt@0.66.0
 ```
 
+## postgrest-js type tests
+
+Every pull request that touches this package also runs postgrest-js's type tests against the TypeScript this pull request generates. The `postgrest-js type tests` job in `postgrest-typegen-validate.yml` checks out supabase-js, starts the database fixture in `packages/core/postgrest-js/test/supabase`, writes `test/types.generated.ts` with `bun run generate:postgrest-js-types`, and runs `test:types:ci` over every TypeScript version postgrest-js supports. The assertions are the hand-written `*.test-d.ts` files in supabase-js, so the generated file is allowed to change as long as they keep passing.
+
+To run it locally, start that fixture with `supabase --workdir packages/core/postgrest-js/test db start` in a supabase-js checkout, then:
+
+```bash
+bun run generate:postgrest-js-types postgresql://postgres:postgres@127.0.0.1:54322/postgres <supabase-js>/packages/core/postgrest-js/test/types.generated.ts
+```
+
+Then run `node scripts/update-json-type.js`, `pnpm exec prettier --write test/types.generated.ts` and `pnpm run test:types:ci` in `packages/core/postgrest-js`.
+
+This job covers TypeScript only. Findings in the Go and Python generators stay with their own unit tests here, and move with those generators to their SDK repositories.
+
 ## Releasing
 
 Unlike the rest of this repo, merging a change here does not open a release pull request on its own. Releases are cut on demand: run the `Release postgrest-typegen` workflow from the Actions tab, which runs release-please against `release-please-config.postgrest-typegen.json` and opens (or updates) the release pull request for this package. Merging that pull request tags the release and publishes to npm. Once npm serves the new version, the same workflow opens a pull request that bumps the exact pin in `packages/typegen`.

package/dist/generation/index.d.ts

@@ -2,4 +2,3 @@ export { sortGeneratorMetadata } from "../sort.ts";
 export { generateGo } from "./go.ts";
 export { generatePython } from "./python.ts";
 export { generateTypescript, type GenerateTypescriptOptions, pgTypeToTsType, type TypeResolutionContext, } from "./typescript.ts";
-export { type AccessControl, generateSwift, type GenerateSwiftOptions, } from "./swift.ts";

package/dist/generation/index.js

@@ -2,4 +2,3 @@ export { sortGeneratorMetadata } from "../sort.js";
 export { generateGo } from "./go.js";
 export { generatePython } from "./python.js";
 export { generateTypescript, pgTypeToTsType, } from "./typescript.js";
-export { generateSwift, } from "./swift.js";

package/dist/generation/typescript.d.ts

@@ -13,7 +13,8 @@ export interface GenerateTypescriptOptions {
     /**
      * Schema treated as the default for the generated `Tables`/`Enums`/etc.
      * helper types. Replaces postgres-meta's `GENERATE_TYPES_DEFAULT_SCHEMA`
-     * env read. Default `'public'`.
+     * env read. Default `'public'`. When it is not among the generated schemas,
+     * the first generated schema is used instead, so the helpers keep resolving.
      */
     defaultSchema?: string;
     /**