@supabase/postgrest-typegen 0.2.0 → 0.2.2

package/README.md

@@ -23,6 +23,14 @@ deprecated in favor of this package. 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.
 
+> [!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,
+> a fix landed here would have to be made a second time in the destination
+> repository, and it also breaks byte parity with postgres-meta until a release
+> propagates. Please open an issue describing the bug instead, so it can be
+> tracked and carried across the move.
+
 ## Design
 
 There is a hard split between **introspection** (database → metadata) and
@@ -128,6 +136,10 @@ Not yet published; consumed in-repo for now (`packages/postgrest-typegen`).
 npm install pg
 ```
 
+## 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.
+
 ## License
 
 MIT

package/dist/collation.d.ts

@@ -0,0 +1,2 @@
+/** Compare two strings with the pinned English collation. */
+export declare function compareStrings(a: string, b: string): number;

package/dist/collation.js

@@ -0,0 +1,15 @@
+/**
+ * The one string comparison every ordering in this package uses.
+ *
+ * Generated output is ordered by name, and `String.prototype.localeCompare`
+ * without a locale follows the host's default locale, so the same database
+ * produced differently ordered code on differently configured machines (a
+ * Swedish host sorts `ä` after `z`, an English one next to `a`). Pinning the
+ * collator to English keeps the order postgres-meta's output has on the
+ * English CI runners and makes it the same everywhere else.
+ */
+const collator = new Intl.Collator("en");
+/** Compare two strings with the pinned English collation. */
+export function compareStrings(a, b) {
+    return collator.compare(a, b);
+}

package/dist/generation/go.js

@@ -58,6 +58,34 @@ function formatForGoTypeName(name) {
     })
         .join("");
 }
+/**
+ * Renders the `json` struct tag for a column or composite attribute name.
+ *
+ * The name is quoted with `JSON.stringify`, whose escape sequences are a
+ * subset of Go's, so `reflect.StructTag.Get("json")` recovers the exact name
+ * via `strconv.Unquote` even when it contains quotes, backslashes or control
+ * characters. The tag is emitted as a raw string literal like before, except
+ * when the name contains a backtick: Go raw literals cannot contain one, so
+ * such tags fall back to an interpreted literal with a second round of
+ * escaping. Names the marshaler cannot represent still compile and
+ * round-trip through `reflect.StructTag`, but `encoding/json` applies its
+ * own tag rules at runtime: a comma splits the name from tag options (so
+ * only the part before it is used as the JSON name), and a name it rejects
+ * outright (for example one containing a quote) falls back to the Go field
+ * name. That is a limitation of the struct tag convention itself, not of
+ * the generated source.
+ *
+ * @example
+ * ```ts
+ * formatForGoStructTag('name') // `json:"name"`
+ * formatForGoStructTag('a"b') // `json:"a\"b"`
+ * formatForGoStructTag('back`tick') // "json:\"back`tick\""
+ * ```
+ */
+function formatForGoStructTag(name) {
+    const tag = `json:${JSON.stringify(name)}`;
+    return tag.includes("`") ? JSON.stringify(tag) : `\`${tag}\``;
+}
 function generateTableStruct(schema, table, columns, types, operation) {
     // Storing columns as a tuple of [formattedName, type, name] rather than creating the string
     // representation of the line allows us to pre-format the entries. Go formats
@@ -97,7 +125,7 @@ function generateTableStruct(schema, table, columns, types, operation) {
     // Pad the formatted name and type to align the struct fields, then join
     // create the final string representation of the struct fields.
     const formattedColumnEntries = columnEntries.map(([formattedName, type, name]) => {
-        return `  ${formattedName.padEnd(maxFormattedNameLength)} ${type.padEnd(maxTypeLength)} \`json:"${name}"\``;
+        return `  ${formattedName.padEnd(maxFormattedNameLength)} ${type.padEnd(maxTypeLength)} ${formatForGoStructTag(name)}`;
     });
     return `
 type ${formatForGoTypeName(schema.name)}${formatForGoTypeName(table.name)}${operation} struct {
@@ -134,7 +162,7 @@ function generateCompositeTypeStruct(schema, type, types) {
     // Pad the formatted name and type to align the struct fields, then join
     // create the final string representation of the struct fields.
     const formattedAttributeEntries = attributeEntries.map(([formattedName, type, name]) => {
-        return `  ${formattedName.padEnd(maxFormattedNameLength)} ${type.padEnd(maxTypeLength)} \`json:"${name}"\``;
+        return `  ${formattedName.padEnd(maxFormattedNameLength)} ${type.padEnd(maxTypeLength)} ${formatForGoStructTag(name)}`;
     });
     return `
 type ${formatForGoTypeName(schema.name)}${formatForGoTypeName(type.name)} struct {

package/dist/generation/index.d.ts

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

package/dist/generation/python.js

@@ -26,13 +26,12 @@ from typing import (
     Any,
     List,
     Literal,
-    NotRequired,
     Optional,
-    TypeAlias,
     TypedDict,
 )
+from typing_extensions import NotRequired, TypeAlias
 
-from pydantic import BaseModel, Field, Json
+from pydantic import BaseModel, Field, JsonValue
 
 ${concatLines(Object.values(ctx.user_enums))}
 
@@ -100,7 +99,9 @@ class PythonContext {
         });
         const attributeEntries = attributes.map((attribute) => {
             const type = this.parsePgType(attribute.type.name);
-            return new PythonBaseModelAttr(attribute.name, type, false);
+            // Composite type attributes cannot carry NOT NULL constraints in
+            // Postgres, so every field is inherently nullable.
+            return new PythonBaseModelAttr(attribute.name, type, true);
         });
         const schema = this.schemas[type.schema];
         return new PythonBaseModel(type.name, schema, attributeEntries);
@@ -146,7 +147,9 @@ class PythonEnum {
         this.variants = type.enums;
     }
     serialize() {
-        const variants = this.variants.map((item) => `"${item}"`).join(", ");
+        const variants = this.variants
+            .map((item) => escapePythonString(item))
+            .join(", ");
         return `${this.name}: TypeAlias = Literal[${variants}]`;
     }
 }
@@ -183,7 +186,7 @@ class PythonBaseModelAttr {
         const py_type = this.nullable
             ? `Optional[${this.py_type.serialize()}]`
             : this.py_type.serialize();
-        return `    ${this.name}: ${py_type} = Field(alias="${this.pg_name}")`;
+        return `    ${this.name}: ${py_type} = Field(alias=${escapePythonString(this.pg_name)})`;
     }
 }
 class PythonBaseModel {
@@ -221,7 +224,7 @@ class PythonTypedDictAttr {
         const py_type = this.nullable
             ? `Optional[${this.py_type.serialize()}]`
             : this.py_type.serialize();
-        const annotation = `Annotated[${py_type}, Field(alias="${this.pg_name}")]`;
+        const annotation = `Annotated[${py_type}, Field(alias=${escapePythonString(this.pg_name)})]`;
         const rhs = this.not_required ? `NotRequired[${annotation}]` : annotation;
         return `    ${this.name}: ${rhs}`;
     }
@@ -251,6 +254,15 @@ class PythonTypedDict {
 function concatLines(items) {
     return items.map((item) => item.serialize()).join("\n\n");
 }
+/**
+ * Emits a Postgres name as a double-quoted Python string literal. JSON string
+ * escaping is a subset of Python's (`\"`, `\\`, `\n`, `\uXXXX`), so
+ * `JSON.stringify` yields a literal Python parses to the exact original name
+ * and keeps quotes, backslashes and newlines from breaking out of it.
+ */
+function escapePythonString(value) {
+    return JSON.stringify(value);
+}
 const PY_TYPE_MAP = {
     // Bool
     bool: "bool",
@@ -276,9 +288,11 @@ const PY_TYPE_MAP = {
     uuid: "uuid.UUID",
     vector: "list[Any]",
     interval: "str",
-    // JSON
-    json: "Json[Any]",
-    jsonb: "Json[Any]",
+    // JSON. PostgREST returns these columns already deserialized, so the
+    // generated models must accept parsed values (JsonValue), not JSON strings
+    // (which is what pydantic's Json[...] validates and parses).
+    json: "JsonValue",
+    jsonb: "JsonValue",
     // Range types (can be adjusted to more complex types if needed)
     int4range: "str",
     int4multirange: "str",

package/dist/generation/swift.js

@@ -1,3 +1,4 @@
+import { compareStrings } from "../collation.js";
 function formatForSwiftSchemaName(schema) {
     return `${formatForSwiftTypeName(schema)}Schema`;
 }
@@ -94,10 +95,52 @@ function pgCompositeTypeToSwiftStruct(type, { types, views, tables, }) {
 function generateProtocolConformances(protocols) {
     return protocols.length === 0 ? "" : `: ${protocols.join(", ")}`;
 }
+/**
+ * Serializes a database-provided value as a Swift string literal. Backslashes
+ * would otherwise start escape or interpolation sequences (`\(`), double
+ * quotes would terminate the literal early, and line breaks or control
+ * characters are not allowed in single-line literals, so all of them are
+ * escaped per Swift's string literal grammar. U+2028 and U+2029 are legal in
+ * Swift literals but are escaped anyway because other tooling mishandles
+ * them. Swift unescapes at compile time, so raw values round-trip unchanged.
+ */
+function swiftStringLiteral(value) {
+    let escaped = "";
+    for (const character of value) {
+        switch (character) {
+            case "\\":
+                escaped += "\\\\";
+                break;
+            case '"':
+                escaped += '\\"';
+                break;
+            case "\t":
+                escaped += "\\t";
+                break;
+            case "\n":
+                escaped += "\\n";
+                break;
+            case "\r":
+                escaped += "\\r";
+                break;
+            default: {
+                const codePoint = character.codePointAt(0);
+                escaped +=
+                    codePoint < 0x20 ||
+                        codePoint === 0x7f ||
+                        codePoint === 0x2028 ||
+                        codePoint === 0x2029
+                        ? `\\u{${codePoint.toString(16)}}`
+                        : character;
+            }
+        }
+    }
+    return `"${escaped}"`;
+}
 function generateEnum(enum_, { accessControl, level }) {
     return [
         `${ident(level)}${accessControl} enum ${enum_.formattedEnumName}${generateProtocolConformances(enum_.protocolConformances)} {`,
-        ...enum_.cases.map((case_) => `${ident(level + 1)}case ${case_.formattedName} = "${case_.rawValue}"`),
+        ...enum_.cases.map((case_) => `${ident(level + 1)}case ${case_.formattedName} = ${swiftStringLiteral(case_.rawValue)}`),
         `${ident(level)}}`,
     ];
 }
@@ -144,10 +187,10 @@ export const generateSwift = (metadata, opts = {}) => {
         ...schemas.flatMap((schema) => {
             const schemaTables = [...tables, ...foreignTables]
                 .filter((table) => table.schema === schema.name)
-                .sort(({ name: a }, { name: b }) => a.localeCompare(b));
+                .sort(({ name: a }, { name: b }) => compareStrings(a, b));
             const schemaViews = [...views, ...materializedViews]
                 .filter((table) => table.schema === schema.name)
-                .sort(({ name: a }, { name: b }) => a.localeCompare(b));
+                .sort(({ name: a }, { name: b }) => compareStrings(a, b));
             const schemaEnums = types.filter((type) => type.schema === schema.name && type.enums.length > 0);
             const schemaCompositeTypes = types.filter((type) => type.schema === schema.name && type.attributes.length > 0);
             return [
@@ -220,6 +263,12 @@ const pgTypeToSwiftType = (pgType, nullable, { types, views, tables, }) => {
     }
     else if (["json", "jsonb"].includes(pgType)) {
         swiftType = "AnyJSON";
+        // `void` and `record` are pseudo-types: Postgres rejects them as a column or
+        // composite attribute type ("column has pseudo-type void"), and this
+        // generator only renders columns and attributes, never functions. So these
+        // two arms are unreachable today and deliberately untested. They are kept
+        // because they are the mappings to use if Swift ever emits functions, which
+        // is where these types do appear.
     }
     else if (pgType === "void") {
         swiftType = "Void";

package/dist/generation/typescript.d.ts

@@ -1,4 +1,4 @@
-import type { GeneratorMetadata, PostgresSchema, PostgresTable, PostgresType, PostgresView } from "../types.ts";
+import type { GeneratorMetadata, PostgresForeignTable, PostgresMaterializedView, PostgresSchema, PostgresTable, PostgresType, PostgresView } from "../types.ts";
 export interface GenerateTypescriptOptions {
     /**
      * Emit `isOneToOne` on each relationship entry. Mirrors postgres-meta's
@@ -24,6 +24,22 @@ export interface GenerateTypescriptOptions {
      */
     format?: (code: string) => Promise<string>;
 }
+/**
+ * Collections `pgTypeToTsType` resolves a relation-typed value against.
+ *
+ * Foreign tables are generated under `Tables` and materialized views under
+ * `Views`, exactly like their plain counterparts, so a value typed as one has
+ * a `Row` to point at and belongs here. Both are optional so the exported
+ * `pgTypeToTsType` signature stays backwards compatible.
+ */
+export type TypeResolutionContext = {
+    types: PostgresType[];
+    schemas: PostgresSchema[];
+    tables: PostgresTable[];
+    views: PostgresView[];
+    foreignTables?: PostgresForeignTable[];
+    materializedViews?: PostgresMaterializedView[];
+};
 /**
  * Does not re-sort collections; pass input pre-sorted with
  * `sortGeneratorMetadata` first. Still merge-sorts tables+foreign tables and
@@ -31,9 +47,4 @@ export interface GenerateTypescriptOptions {
  * can't be expressed by the single-collection `sortGeneratorMetadata` pass.
  */
 export declare const generateTypescript: (metadata: GeneratorMetadata, opts?: GenerateTypescriptOptions) => Promise<string>;
-export declare const pgTypeToTsType: (schema: PostgresSchema, pgType: string, { types, schemas, tables, views, }: {
-    types: PostgresType[];
-    schemas: PostgresSchema[];
-    tables: PostgresTable[];
-    views: PostgresView[];
-}, typeSchema?: string) => string;
+export declare const pgTypeToTsType: (schema: PostgresSchema, pgType: string, context: TypeResolutionContext, typeSchema?: string) => string;