@typesql/pg 0.0.2 → 0.0.4

package/dist/type-map.d.ts

@@ -1,21 +1,14 @@
-import type { DefaultTypeMap } from "@typesql/core";
+import type { DefaultParamTypeMap, DefaultTypeMap } from "@typesql/core";
 /**
  * The object node-postgres returns for an `interval` column (package `postgres-interval` 1.x,
  * wired up by `pg-types`). Fields are only present when non-zero; `toPostgres()` renders the
  * value back to Postgres syntax and `toISO()`/`toISOString()` produce an ISO 8601 duration.
+ *
+ * Written inline in `PgTypeMap` (this alias only reads it back), so row types stay plain
+ * object types: declaration emit in a package without a direct `@typesql/pg` dependency does
+ * not need to name `PgInterval` (TS2883).
  */
-export interface PgInterval {
-    years?: number;
-    months?: number;
-    days?: number;
-    hours?: number;
-    minutes?: number;
-    seconds?: number;
-    milliseconds?: number;
-    toPostgres(): string;
-    toISO(): string;
-    toISOString(): string;
-}
+export type PgInterval = PgTypeMap["interval"];
 /**
  * Canonical Postgres type name → TS type as `pg` 8.x returns it with its default type
  * parsers (`pg-types` 2.x, text protocol). Verified against `pg-types/lib/textParsers.js`:
@@ -50,13 +43,48 @@ export interface PgInterval {
  *     line[], lseg[], box[], path[], polygon[], int4range[], int8range[], tsrange[],
  *     tstzrange[], daterange[], macaddr8[], regclass[]/regtype[]/regproc[], record[].
  * Register your own parser (`pg.types.setTypeParser`) or cast in SQL if you depend on these.
+ * The two that `PgCatalog` columns use are declared here as the text pg returns: `aclitem[]`
+ * (`relacl`, `datacl`, ...) and `"char"[]` (`proargmodes`).
  */
 export interface PgTypeMap extends Omit<DefaultTypeMap, "bytea" | "interval" | "record" | "void"> {
+    /** What parameters accept on top of the row types. */
+    $params: PgParamTypeMap;
     bytea: Buffer;
-    interval: PgInterval;
+    interval: {
+        years?: number;
+        months?: number;
+        days?: number;
+        hours?: number;
+        minutes?: number;
+        seconds?: number;
+        milliseconds?: number;
+        toPostgres(): string;
+        toISO(): string;
+        toISOString(): string;
+    };
     /** Anonymous `ROW(...)` results have no parser: raw text such as `"(1,foo)"`. */
     record: string;
     /** `void`-returning functions (`pg_sleep`) yield an empty string. */
     void: string;
+    /** No array parser: the raw `{...}` text, e.g. `"{postgres=arwdDxtm/postgres}"`. */
+    "aclitem[]": string;
+    /** No array parser for `"char"[]`: the raw `{...}` text, e.g. `"{i,o}"`. */
+    "char[]": string;
+}
+/**
+ * TS types `pg` parameters accept on top of the row type (`PgTypeMap["$params"]`). Verified
+ * against `pg/lib/utils.js` (`prepareValue`, 8.x): a `Date` is sent as a timestamp with the
+ * local offset, `Buffer`/typed arrays as bytea, a `bigint` or number with `toString()`, and
+ * objects with `toPostgres()` (such as `PgInterval`) through it; Postgres parses the text.
+ *
+ *   int8, numeric, money          number | bigint | string
+ *   date, timestamp, timestamptz  Date | string
+ *   interval                      string, besides the `PgInterval` row type
+ *   bytea                         Uint8Array, besides `Buffer`
+ *
+ * Plain objects are `JSON.stringify`d and arrays become Postgres array literals, so neither is
+ * listed for other types.
+ */
+export interface PgParamTypeMap extends DefaultParamTypeMap {
 }
 //# sourceMappingURL=type-map.d.ts.map

package/dist/type-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-map.d.ts","sourceRoot":"","sources":["../src/type-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,IAAI,MAAM,CAAC;IACrB,KAAK,IAAI,MAAM,CAAC;IAChB,WAAW,IAAI,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/F,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,UAAU,CAAC;IACrB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"type-map.d.ts","sourceRoot":"","sources":["../src/type-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEzE;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/F,sDAAsD;IACtD,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,IAAI,MAAM,CAAC;QACrB,KAAK,IAAI,MAAM,CAAC;QAChB,WAAW,IAAI,MAAM,CAAC;KACvB,CAAC;IACF,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAe,SAAQ,mBAAmB;CAAG"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@typesql/pg",
-  "version": "0.0.2",
-  "description": "node-postgres (pg) adapter for typesql.",
+  "version": "0.0.4",
+  "description": "node-postgres (pg) adapter for typesql, with `typesql introspect` to generate a schema from a live database.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,8 +16,15 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./introspect": {
+      "types": "./dist/introspect/index.d.ts",
+      "default": "./dist/introspect/index.js"
     }
   },
+  "bin": {
+    "typesql": "./dist/bin.js"
+  },
   "files": [
     "dist",
     "src",
@@ -28,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@typesql/core": "0.0.2"
+    "@typesql/core": "0.0.4"
   },
   "peerDependencies": {
     "pg": ">=8"

package/src/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/** `typesql`: `typesql introspect` writes the typesql schema of a live database. */
+import { main } from "./introspect/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/src/client.ts

@@ -1,4 +1,4 @@
-import type { Executor, Query, RowType } from "@typesql/core";
+import { mapRows, type Executor, type Query, type RowType } from "@typesql/core";
 
 /** The subset of a `pg` query result the helpers rely on. */
 export interface PgResult {
@@ -44,15 +44,21 @@ function run(client: PgQueryable, q: AnyQuery): Promise<PgResult> {
   return client.query(q.text, Array.from(q.values));
 }
 
-/** An `Executor` for core's `q.execute()`: runs queries on `client` and resolves to the rows. */
+/**
+ * An `Executor` for core's `q.execute()`: runs queries on `client` and resolves to
+ * `{ rows, rowCount }` (pg's `rowCount`, so `q.executeCount()` works).
+ */
 export function executor(client: PgQueryable): Executor {
-  return async (text, values) => (await client.query(text, Array.from(values))).rows;
+  return async (text, values) => {
+    const { rows, rowCount } = await client.query(text, Array.from(values));
+    return { rows, rowCount };
+  };
 }
 
 /** Run a query and return all rows, typed from the query. */
 export async function query<Q extends AnyQuery>(client: PgQueryable, q: Q): Promise<RowType<Q>[]> {
   const result = await run(client, q);
-  return result.rows as RowType<Q>[];
+  return mapRows(q, result.rows);
 }
 
 /** Exactly one row, otherwise throws `RowCountError`. */

package/src/index.ts

@@ -1,9 +1,9 @@
-import { createSql as createCoreSql, type Sql } from "@typesql/core";
+import { createSql as createCoreSql, type RowKeys, type Sql, type SqlOptions } from "@typesql/core";
 import { executor, type PgQueryable } from "./client.js";
 import type { PgTypeMap } from "./type-map.js";
 
 export { NoResultError, type Executor } from "@typesql/core";
-export type { PgInterval, PgTypeMap } from "./type-map.js";
+export type { PgInterval, PgParamTypeMap, PgTypeMap } from "./type-map.js";
 export {
   query,
   one,
@@ -24,7 +24,10 @@ export {
 /**
  * `createSql<DB>()` from core, pre-bound to `PgTypeMap` (`count(*)` is `string`, `int8` is `string`, dates are `Date`).
  * With a `client` (a `Pool`, `Client` or `PoolClient`), the queries' `execute*` methods run on it.
+ * `{ rowKeys: "camelCase" }` camelCases the rows' keys, in the types and at runtime.
  */
-export function createSql<DB>(client?: PgQueryable): Sql<DB, PgTypeMap> {
-  return createCoreSql<DB, PgTypeMap>(client && executor(client));
+export function createSql<DB>(client: PgQueryable | undefined, options: { readonly rowKeys: "camelCase" }): Sql<DB, PgTypeMap, "camelCase">;
+export function createSql<DB>(client?: PgQueryable, options?: { readonly rowKeys?: "preserve" }): Sql<DB, PgTypeMap>;
+export function createSql<DB>(client?: PgQueryable, options?: SqlOptions): Sql<DB, PgTypeMap, RowKeys> {
+  return createCoreSql<DB, PgTypeMap>(client && executor(client), options as { readonly rowKeys: "camelCase" });
 }

package/src/introspect/cli.ts

@@ -0,0 +1,138 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import type { PgQueryable } from "../client.js";
+import { generateSource, type GenerateOptions } from "./emit.js";
+import { introspect, type IntrospectOptions } from "./introspect.js";
+
+/** What a `--config` module exports as its default: CLI settings plus every generator option. */
+export interface IntrospectConfig extends GenerateOptions, IntrospectOptions {
+  /** Connection string. Default: `--url`, then `$DATABASE_URL`. */
+  readonly url?: string;
+  /** Output file, relative to the working directory. Default: stdout. */
+  readonly out?: string;
+}
+
+const USAGE = `Usage: typesql introspect [options]
+
+Reads a live Postgres database and writes its typesql schema (tables, views, enums).
+
+Options:
+  --url <url>          connection string (default: $DATABASE_URL)
+  --out <file>         write the schema to <file> instead of stdout
+  --schema <name>      schema to read; repeat or comma-separate (default: all but system schemas)
+  --exclude <pattern>  relation to leave out (name or schema.name, * wildcard); repeat or comma-separate
+  --type-name <name>   name of the schema interface (default: DB)
+  --import-from <mod>  module the column helpers come from (default: @typesql/core)
+  --config <file>      module whose default export holds these options and more
+                       (columnTypes for JSON columns, imports, column(...) hook)
+  --no-comments        omit JSDoc from comments, domains and generated columns
+  -h, --help           show this help
+`;
+
+interface Io {
+  readonly stdout: (s: string) => void;
+  readonly stderr: (s: string) => void;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly cwd: string;
+  /** Opens a client for a connection string; default: a `pg.Client`. */
+  readonly connect?: (url: string) => Promise<PgQueryable & { end(): Promise<void> }>;
+}
+
+const defaultIo = (): Io => ({
+  stdout: (s) => process.stdout.write(s),
+  stderr: (s) => process.stderr.write(s),
+  env: process.env,
+  cwd: process.cwd(),
+});
+
+async function pgConnect(url: string): Promise<PgQueryable & { end(): Promise<void> }> {
+  let Client: typeof import("pg").Client;
+  try {
+    ({ Client } = (await import("pg")).default);
+  } catch {
+    throw new Error('typesql introspect needs the "pg" package: npm install pg');
+  }
+  const client = new Client({ connectionString: url });
+  await client.connect();
+  return client;
+}
+
+/** Runs the `typesql` CLI with `argv` (without `node` and the script). Returns the exit code. */
+export async function main(argv: readonly string[], io: Io = defaultIo()): Promise<number> {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: [...argv],
+      allowPositionals: true,
+      options: {
+        url: { type: "string" },
+        out: { type: "string" },
+        schema: { type: "string", multiple: true },
+        exclude: { type: "string", multiple: true },
+        "type-name": { type: "string" },
+        "import-from": { type: "string" },
+        config: { type: "string" },
+        "no-comments": { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+      },
+    });
+  } catch (err) {
+    io.stderr(`${(err as Error).message}\n\n${USAGE}`);
+    return 2;
+  }
+  const { values, positionals } = parsed;
+  if (values.help || positionals.length === 0) {
+    (values.help ? io.stdout : io.stderr)(USAGE);
+    return values.help ? 0 : 2;
+  }
+  if (positionals[0] !== "introspect" || positionals.length > 1) {
+    io.stderr(`unknown command: ${positionals.join(" ")}\n\n${USAGE}`);
+    return 2;
+  }
+
+  try {
+    let config: IntrospectConfig = {};
+    if (values.config) {
+      const mod = (await import(pathToFileURL(resolve(io.cwd, values.config)).href)) as { default?: IntrospectConfig };
+      config = mod.default ?? {};
+    }
+    const url = values.url ?? config.url ?? io.env["DATABASE_URL"];
+    if (!url) {
+      io.stderr("typesql introspect: pass --url or set DATABASE_URL\n");
+      return 2;
+    }
+    const list = (v: string[] | undefined) => v?.flatMap((s) => s.split(",").map((x) => x.trim()).filter(Boolean));
+    const schemas = list(values.schema) ?? config.schemas;
+    const exclude = list(values.exclude) ?? config.exclude;
+    const options: IntrospectConfig = {
+      ...config,
+      ...(schemas !== undefined && { schemas }),
+      ...(exclude !== undefined && { exclude }),
+      ...(values["type-name"] !== undefined && { typeName: values["type-name"] }),
+      ...(values["import-from"] !== undefined && { importFrom: values["import-from"] }),
+      ...(values["no-comments"] && { comments: false }),
+    };
+    const client = await (io.connect ?? pgConnect)(url);
+    let source: string;
+    try {
+      source = generateSource(await introspect(client, options), options);
+    } finally {
+      await client.end();
+    }
+    const out = values.out ?? config.out;
+    if (out === undefined) {
+      io.stdout(source);
+    } else {
+      const file = resolve(io.cwd, out);
+      await mkdir(dirname(file), { recursive: true });
+      await writeFile(file, source);
+      io.stderr(`typesql introspect: wrote ${out}\n`);
+    }
+    return 0;
+  } catch (err) {
+    io.stderr(`typesql introspect: ${(err as Error).message}\n`);
+    return 1;
+  }
+}

package/src/introspect/emit.ts

@@ -0,0 +1,168 @@
+import type { IntrospectedColumn, IntrospectedDatabase, IntrospectedRelation } from "./introspect.js";
+
+export interface GenerateOptions {
+  /** Name of the exported schema interface. Default `"DB"`. */
+  readonly typeName?: string;
+  /** Module the column helpers are imported from. Default `"@typesql/core"`. */
+  readonly importFrom?: string;
+  /** Extra lines after the helper import, e.g. `import type { HistoryItem } from "./json.js";`. */
+  readonly imports?: readonly string[];
+  /**
+   * TypeScript types of `json` / `jsonb` columns: a map keyed `"table.column"` (public) or
+   * `"schema.table.column"`, or a function returning the TS type source for a column (or
+   * `undefined`). Such a column is declared as `Json<T>`: still jsonb to the SQL, read as `T`,
+   * written with `sql.json(value)`. Other columns are an error (use `column` for those).
+   */
+  readonly columnTypes?:
+    | Readonly<Record<string, string>>
+    | ((column: IntrospectedColumn, relation: IntrospectedRelation) => string | undefined);
+  /**
+   * Full control over one column: return the TypeScript source of its descriptor
+   * (`Col<"jsonb">`, a helper of your own, ...) or `undefined` to keep the default.
+   */
+  readonly column?: (column: IntrospectedColumn, relation: IntrospectedRelation) => string | undefined;
+  /** Emit table and column comments and notes as JSDoc. Default `true`. */
+  readonly comments?: boolean;
+}
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const key = (name: string): string => (IDENT.test(name) ? name : JSON.stringify(name));
+const str = (s: string): string => JSON.stringify(s);
+
+function doc(lines: readonly string[], indent: string): string {
+  const text = lines.flatMap((l) => l.split("\n")).map((l) => l.replace(/\*\//g, "*\\/").trimEnd());
+  if (text.length === 0) return "";
+  if (text.length === 1) return `${indent}/** ${text[0]} */\n`;
+  return `${indent}/**\n${text.map((l) => `${indent} *${l ? ` ${l}` : ""}`).join("\n")}\n${indent} */\n`;
+}
+
+type Helper = "Col" | "Nullable" | "Generated" | "NullableGenerated" | "Json";
+const helperFor = (nullable: boolean, hasDefault: boolean): Helper =>
+  nullable ? (hasDefault ? "NullableGenerated" : "Nullable") : hasDefault ? "Generated" : "Col";
+
+function columnNotes(c: IntrospectedColumn): string[] {
+  const notes: string[] = [];
+  if (c.comment) notes.push(c.comment);
+  if (c.domain) notes.push(`Domain \`${c.domain}\`.`);
+  else if (c.declaredType === "citext") notes.push("`citext`: typed as `text`.");
+  if (c.generated !== null) notes.push(`\`GENERATED ALWAYS AS (${c.generated}) STORED\`: cannot be written.`);
+  if (c.identity === "always") notes.push("`GENERATED ALWAYS AS IDENTITY`: written only with `OVERRIDING SYSTEM VALUE`.");
+  return notes;
+}
+
+/**
+ * TypeScript source declaring the typesql schema of an introspected database: `public`
+ * relations at the top level, other schemas nested (`DB["auth"]["sessions"]`), views and
+ * materialized views as `View<…>`, enums under `$types`.
+ */
+export function generateSource(db: IntrospectedDatabase, options: GenerateOptions = {}): string {
+  const typeName = options.typeName ?? "DB";
+  const comments = options.comments ?? true;
+  const columnTypes = options.columnTypes ?? {};
+  const used = new Set<string>();
+  const usedKeys = new Set<string>();
+
+  /** The TS type `columnTypes` gives a column, if any. */
+  const customType = (rel: IntrospectedRelation, col: IntrospectedColumn): string | undefined => {
+    const qualified = `${rel.schema}.${rel.name}.${col.name}`;
+    const short = `${rel.name}.${col.name}`;
+    let ts: string | undefined;
+    if (typeof columnTypes === "function") ts = columnTypes(col, rel);
+    else {
+      const k = qualified in columnTypes ? qualified : rel.schema === "public" && short in columnTypes ? short : undefined;
+      if (k !== undefined) {
+        usedKeys.add(k);
+        ts = columnTypes[k];
+      }
+    }
+    if (ts !== undefined && col.type !== "json" && col.type !== "jsonb") {
+      throw new Error(`columnTypes: ${JSON.stringify(rel.schema === "public" ? short : qualified)} has type ${col.type}; columnTypes only types json / jsonb columns (use the column hook for others)`);
+    }
+    return ts;
+  };
+
+  /** `Json<T>`, `Json<T, { nullable: true }>`, `Json<T, {}, "json">`, … */
+  const jsonDescriptor = (col: IntrospectedColumn, ts: string): string => {
+    const flags = [...(col.nullable ? ["nullable: true"] : []), ...(col.hasDefault ? ["hasDefault: true"] : [])];
+    const flagSource = flags.length > 0 ? `{ ${flags.join("; ")} }` : "{}";
+    used.add("Json");
+    if (col.type === "json") return `Json<${ts}, ${flagSource}, "json">`;
+    return flags.length > 0 ? `Json<${ts}, ${flagSource}>` : `Json<${ts}>`;
+  };
+
+  const relation = (rel: IntrospectedRelation, indent: string): string => {
+    const isView = rel.kind === "view" || rel.kind === "materialized view";
+    const cols = rel.columns.map((c) => {
+      let descriptor = options.column?.(c, rel);
+      if (descriptor === undefined) {
+        const custom = customType(rel, c);
+        if (custom !== undefined) descriptor = jsonDescriptor(c, custom);
+        else {
+          const helper = helperFor(c.nullable, c.hasDefault);
+          used.add(helper);
+          descriptor = `${helper}<${str(c.type)}>`;
+        }
+      }
+      return `${comments ? doc(columnNotes(c), `${indent}  `) : ""}${indent}  ${key(c.name)}: ${descriptor};`;
+    });
+    const body = `{\n${cols.join("\n")}\n${indent}}`;
+    if (!isView) return body;
+    used.add("View");
+    return `View<${body}>`;
+  };
+
+  const relDoc = (rel: IntrospectedRelation, indent: string): string => {
+    if (!comments) return "";
+    const kind = rel.kind === "table" ? [] : [`${rel.kind[0]!.toUpperCase()}${rel.kind.slice(1)}.`];
+    return doc([...(rel.comment ? [rel.comment] : []), ...kind], indent);
+  };
+
+  const topLevel = new Set(db.relations.filter((r) => r.schema === "public").map((r) => r.name));
+  const lines: string[] = [];
+  const namespaces = new Map<string, IntrospectedRelation[]>();
+  for (const rel of db.relations) {
+    if (rel.schema === "public") lines.push(`${relDoc(rel, "  ")}  ${key(rel.name)}: ${relation(rel, "  ")};`);
+    else namespaces.set(rel.schema, [...(namespaces.get(rel.schema) ?? []), rel]);
+  }
+  for (const [schema, rels] of namespaces) {
+    if (topLevel.has(schema)) {
+      throw new Error(`schema "${schema}" has the same name as the table "public.${schema}": typesql keeps public relations and schemas in one object`);
+    }
+    const body = rels.map((r) => `${relDoc(r, "    ")}    ${key(r.name)}: ${relation(r, "    ")};`);
+    lines.push(`  ${key(schema)}: {\n${body.join("\n")}\n  };`);
+  }
+
+  if (db.enums.length > 0) {
+    // typesql's enum registry is flat (`Col<"mood">`, schema qualifiers are dropped), so enums
+    // of the same name in different schemas share an entry.
+    const byName = new Map<string, { values: Set<string>; schemas: string[] }>();
+    for (const e of db.enums) {
+      const entry = byName.get(e.name) ?? { values: new Set<string>(), schemas: [] };
+      for (const v of e.values) entry.values.add(v);
+      entry.schemas.push(e.schema);
+      byName.set(e.name, entry);
+    }
+    const entries = [...byName].map(([name, { values, schemas }]) => {
+      const notes = comments && schemas.length > 1 ? doc([`Enums of the same name in ${schemas.map((s) => `\`${s}\``).join(", ")}.`], "    ") : "";
+      return `${notes}    ${key(name)}: ${[...values].map(str).join(" | ") || "never"};`;
+    });
+    lines.push(`  $types: {\n${entries.join("\n")}\n  };`);
+  }
+
+  const helpers = ["Col", "Generated", "Json", "Nullable", "NullableGenerated", "View"].filter((h) => used.has(h));
+  const out = [
+    `// Generated by \`typesql introspect\` (@typesql/pg) from PostgreSQL ${db.version.split(/[.\s]/)[0]}. Do not edit.`,
+    ...(helpers.length > 0 ? [`import type { ${helpers.join(", ")} } from ${str(options.importFrom ?? "@typesql/core")};`] : []),
+    ...(options.imports ?? []),
+    "",
+    `export interface ${key(typeName)} {`,
+    ...lines,
+    "}",
+    "",
+  ];
+  const unknownKeys = typeof columnTypes === "function" ? [] : Object.keys(columnTypes).filter((k) => !usedKeys.has(k));
+  if (unknownKeys.length > 0 && options.column === undefined) {
+    throw new Error(`columnTypes: no column ${unknownKeys.map((k) => JSON.stringify(k)).join(", ")} (keys are "table.column" for public tables, else "schema.table.column")`);
+  }
+  return out.join("\n");
+}

package/src/introspect/index.ts

@@ -0,0 +1,12 @@
+export {
+  introspect,
+  type IntrospectOptions,
+  type IntrospectedDatabase,
+  type IntrospectedRelation,
+  type IntrospectedColumn,
+  type IntrospectedEnum,
+  type RelationKind,
+} from "./introspect.js";
+export { generateSource, type GenerateOptions } from "./emit.js";
+export { ViewNullability, parseNodeTree, type NullabilityOptions, type QueryFn } from "./nullability.js";
+export { main, type IntrospectConfig } from "./cli.js";