feat: add supabase_typegen package generating typed table definitions

.github/workflows/build.yml

@@ -136,6 +136,14 @@ jobs:
           dart pub global activate melos
           melos bootstrap
 
+      # The runner image ships a package index that goes stale as soon as a
+      # security pocket update supersedes an indexed version; resolving
+      # package versions from it then 404s, and the cache action saves an
+      # empty (poisoned) cache entry on top. Refresh the index first.
+      - name: Refresh apt package index
+        if: ${{ matrix.target == 'linux' }}
+        run: sudo apt-get update
+
       - name: Install Linux build dependencies (cached)
         if: ${{ matrix.target == 'linux' }}
         uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3

packages/supabase_realtime/lib/src/realtime_channel.dart

@@ -138,7 +138,7 @@ class RealtimeChannel {
   Map<String, dynamic> get parameters => _deepUnmodifiableMap(_parameters);
 
   static Map<String, dynamic> _deepUnmodifiableMap(Map<String, dynamic> map) {
-    return Map<String, dynamic>.unmodifiable(
+    return Map.unmodifiable(
       map.map((key, value) => MapEntry(key, _deepUnmodifiable(value))),
     );
   }

packages/supabase_typegen/README.md

@@ -1,10 +1,78 @@
 # supabase_typegen
 
-> [!WARNING]
-> This is a placeholder release that reserves the package name on pub.dev. The
-> code generator is still under development and this version does nothing yet.
+Generates typed Supabase table definitions from your database schema, so
+query results never expose raw `Map<String, dynamic>` data.
 
-A command-line code generator that turns a Supabase database schema into typed
-Dart table definitions for use with the Supabase client packages.
+For every table the generator emits:
 
-The generator implementation will land in a future release.
+- a zero-cost row extension type over the decoded JSON map with typed getters,
+- `Insert` and `Update` value types that enforce required columns at the
+  construction site,
+- a `PostgrestTable` definition and `TableColumn` tokens for compile-time
+  checked filters,
+- Dart enums for Postgres enums, with wire-name mapping.
+
+## Usage
+
+The easiest way is through the Supabase CLI, which handles the database
+connection and runs this package for you. Add `supabase_typegen` as a dev
+dependency of your project (until the package is published to
+[pub.dev](https://pub.dev), depend on it with a `git` source pointing at
+`packages/supabase_typegen` in this repository), then:
+
+```sh
+supabase gen types --lang dart --local > lib/supabase_schema.g.dart
+```
+
+Any of the CLI's connection flags work (`--local`, `--linked`, `--db-url`,
+`--project-id`).
+
+Under the hood the CLI runs the introspection of
+[`@supabase/postgrest-typegen`](https://github.com/supabase/sdk/tree/main/packages/postgrest-typegen)
+in-process against the database (the same `GeneratorMetadata` intermediate
+representation its TypeScript, Go, Swift, and Python generators consume,
+ordered with `sortGeneratorMetadata`) and hands the document to this tool
+over stdin. The types reflect the current state of the selected database:
+with `--local` the SQL in your `supabase/` directory stays the single source
+of truth, since the CLI applies your migrations to the local database and
+generates from the result, while `--linked`, `--project-id`, and `--db-url`
+generate from whatever that database currently contains.
+
+Use `--schema` to generate for a schema other than `public`, and `--import`
+to change which library the generated file imports `PostgrestTable` and
+`TableColumn` from.
+
+The metadata comes from the database catalog, so nullability, database
+defaults, and identity columns are exact: a `NOT NULL` column with a default
+reads as non-nullable but stays optional on insert, and `GENERATED ALWAYS`
+columns appear in the row type but not in the insert and update types.
+
+## Generated code in action
+
+```dart
+final books = await client.table(Books.table)
+    .select()
+    .where(Books.mood.eq(Mood.happy))
+    .order(Books.createdAt, ascending: false); // List<BooksRow>
+
+await client.table(Books.table).insert(
+  BooksInsert(title: 'A typed row', tags: ['dart']),
+);
+```
+
+## Known limitations
+
+- Passing `null` to an `Insert`/`Update` parameter omits the column. To write
+  SQL NULL explicitly, use the generated `set…ToNull` methods, for example
+  `BooksUpdate(inPrint: false).setPriceToNull()`; they only exist for
+  nullable columns, so nulling a `NOT NULL` column is a compile error.
+- Array elements are assumed non-null (`text[]` maps to `List<String>`),
+  matching the supabase-js type generator; arrays containing SQL NULL
+  elements throw when the element is read. Enum, date, and timestamp array
+  elements stay in their wire representation (`List<String>`); the Dart enum
+  for enum array elements is still generated for manual conversion.
+- `timestamptz` values are written back in UTC, naive `timestamp` values as
+  local wall time, and `date` values date-only, so calendar dates never
+  shift with the client timezone.
+- Foreign key relationship getters and typed functions (rpc) are not
+  generated yet.

packages/supabase_typegen/bin/supabase_typegen.dart

@@ -0,0 +1,106 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:args/args.dart';
+import 'package:supabase_typegen/supabase_typegen.dart';
+
+final _argParser = ArgParser()
+  ..addOption(
+    'schema',
+    defaultsTo: 'public',
+    help: 'The database schema to generate types for.',
+  )
+  ..addOption(
+    'output',
+    abbr: 'o',
+    defaultsTo: 'lib/supabase_schema.g.dart',
+    help: 'Path of the generated Dart file, or - to write the code to stdout.',
+  )
+  ..addOption(
+    'import',
+    defaultsTo: 'package:postgrest/postgrest.dart',
+    help:
+        'The import the generated file uses for PostgrestTable and '
+        'TableColumn.',
+  )
+  ..addFlag('help', abbr: 'h', negatable: false, help: 'Show this usage.');
+
+Future<void> main(List<String> arguments) async {
+  // The value returned from main is ignored by the Dart VM, so the exit
+  // code has to be set explicitly.
+  exitCode = await _run(arguments);
+}
+
+Future<int> _run(List<String> arguments) async {
+  final ArgResults options;
+  try {
+    options = _argParser.parse(arguments);
+  } on FormatException catch (error) {
+    stderr
+      ..writeln(error.message)
+      ..writeln(_argParser.usage);
+    return 64;
+  }
+
+  if (options.flag('help')) {
+    stdout
+      ..writeln(
+        'Generates typed Supabase table definitions from the '
+        'GeneratorMetadata document that postgrest-typegen emits, '
+        'read from stdin.',
+      )
+      ..writeln()
+      ..writeln('Usage: dart run supabase_typegen < <metadata document>')
+      ..writeln(_argParser.usage);
+    return 0;
+  }
+
+  if (stdin.hasTerminal) {
+    stderr.writeln(
+      'Expected a GeneratorMetadata document of '
+      '@supabase/postgrest-typegen on stdin. This tool is normally '
+      'invoked through `supabase gen types --lang dart`.',
+    );
+    return 64;
+  }
+
+  final schemaName = options.option('schema')!;
+  final SchemaDescription schema;
+  try {
+    final contents = await utf8.decodeStream(stdin);
+    schema = parseGeneratorMetadata(
+      jsonDecode(contents) as Map<String, dynamic>,
+      schemaName: schemaName,
+    );
+  } on FormatException catch (error) {
+    stderr.writeln('Could not parse the document on stdin: ${error.message}');
+    return 65;
+  }
+
+  final code = generateDartCode(schema, importUri: options.option('import')!);
+
+  final output = options.option('output')!;
+  final String generatedInto;
+  if (output == '-') {
+    stdout.write(code);
+    generatedInto = 'stdout';
+  } else {
+    final outputFile = File(output);
+    outputFile.parent.createSync(recursive: true);
+    outputFile.writeAsStringSync(code);
+    generatedInto = outputFile.path;
+  }
+
+  final emittedTables = schema.tables
+      .where((table) => table.columns.isNotEmpty)
+      .length;
+  final skippedTables = schema.tables.length - emittedTables;
+  final summarySink = output == '-' ? stderr : stdout;
+  summarySink.writeln(
+    'Generated $generatedInto with $emittedTables tables and '
+    '${schema.enums.length} enums from schema "$schemaName".'
+    '${skippedTables == 0 ? '' : ' Skipped $skippedTables tables '
+              'without columns.'}',
+  );
+  return 0;
+}