feat: Stricter, more expressive type generation (enums, overrides, types-only) + correctness fixes

[rtolsma]

Summary

A series of atomic commits making generated types substantially stricter and more expressive, plus fixes for several open correctness issues. Each commit is independently revertable and states its own verification.

1. Strongly typed columns (cd4421a) — closes #32, addresses #37

• Enums → string literal unions (automatic). The plugin previously ignored GenerateRequest.catalog, so CREATE TYPE status AS ENUM (...) columns came out as plain string. They now generate:

  export type Status = "active" | "inactive" | "banned";
  export const StatusValues: readonly Status[] = ["active", "inactive", "banned"];

  and every column/parameter of that type references the union.

• overrides plugin option (opt-in), modeled on sqlc-gen-go's. Match a SQL type by name (db_type — covers Postgres domains, which previously silently collapsed to string) or a single column (column: "table.column"), and emit any TypeScript type expression, with an optional type-only import — enabling branded/nominal ID types and concrete JSON payload types:

  options:
    overrides:
    - db_type: "email"
      ts_type: "Email"
      import: { path: "./brands", name: "Email" }
    - db_type: "user_id"
      ts_type: 'string & { readonly __brand: "user_id" }'
    - column: "users.meta"
      ts_type: "UserMeta"
      import: { path: "./brands", name: "UserMeta" }

  Resolution order: column override → db_type override → schema enum → built-in driver mapping. Nullability (| null) and array (T[]) wrapping compose on top. Implemented as a CustomTypeRegistry (src/customTypes.ts); each driver consults the resolver before its built-in switch, so behavior is identical across all four drivers.

2. Type-only imports (903881e) — fixes #55, fixes #61

All driver preamble imports are now import type (the mysql2 default+named import is split in two, since type-only imports cannot combine them). Generated output now compiles under verbatimModuleSyntax.

3. Valid code for non-identifier column names (74e1a5e) — fixes #70

Columns like "invalid-name" now emit quoted property keys and args["invalid-name"] element access instead of unparseable code.

4. Escape backticks/${/backslashes in query literals (6d4de97) — fixes #40

MySQL backtick-quoted queries (and SQL literals containing ${ or backslashes) no longer corrupt the emitted template literal; the runtime string is byte-identical to the source SQL (verified by evaluating the emitted literal).

5. types_only option (9198dca) — fixes #71

types_only: true emits only Args/Row interfaces, enum unions, and override imports — no driver imports or query functions — for sharing DB types with a frontend.

6. :execlastid respects big number options (e71d7f0) — fixes #22

The mysql2 insert id now follows the same rules as the bigint column mapping: big_number_strings → string (via String(...)), support_big_numbers alone → number | string, default unchanged.

7. Positional fallback names for unnamed parameters (77e343e) — fixes #29

WHERE uid = ANY($1::uuid[]) previously generated { "": string[] }; unnamed parameters now fall back to arg_N matching their placeholder number. (Array parameter types themselves already worked; this makes them usable.)

Testing

• tsc --noEmit clean at every commit; wasm built via the documented esbuild + javy flow (javy 1.4.0, sqlc v1.31.1).
• No unintended output changes: all seven example configs regenerate byte-for-byte identical except where a commit intentionally changes them (type-only imports; node-mysql2 Promise<string>), and those regenerated files are included in the respective commits. The node-pg and node-mysql2 example projects compile with their own tsconfigs.
• End-to-end tests: Postgres schema with enum (as column and parameter), domains, column-level jsonb override, arrays, nullables, a hyphenated column name, and an ANY($1::uuid[]) parameter; MySQL schema with backtick quoting, ${/backslash literals, and :execlastid under both big-number option combinations. All generated output compiles under tsc --strict, and the pg output additionally under verbatimModuleSyntax.

The README gains sections documenting enum generation, overrides, and types_only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GFyrFwpJC2eivaBRyNBJqv