TypeScript codegen

pg-flux gen --lang ts --out ./src/db

# .pg-flux-codegen.yml
outputs:
  - lang: ts
    out: ./src/db
    column_case: camel
    null_style: optional
    enum_style: const-object
    branded_ids: true
    insert_update_helpers: true
    validators: zod
    functions: true

import type { User, InsertUser, UserRole } from './src/db';

// null_style: union  (default)
export interface User {
  id: bigint;
  email: string;
  display_name: string | null;   // nullable
  deleted_at: Date | null;       // nullable
}

// null_style: undefined
export interface User {
  id: bigint;
  email: string;
  display_name: string | undefined;  // nullable
  deleted_at: Date | undefined;      // nullable
}

// null_style: optional
export interface User {
  id: bigint;
  email: string;
  display_name?: string;    // nullable — property is optional
  deleted_at?: Date;        // nullable — property is optional
}

CREATE TYPE user_role AS ENUM ('admin', 'member', 'guest');

/** PG enum public.user_role */
export type UserRole =
  | "admin"
  | "member"
  | "guest";

/** PG enum public.user_role */
export const UserRole = {
  Admin: "admin",
  Member: "member",
  Guest: "guest",
} as const;
export type UserRole = (typeof UserRole)[keyof typeof UserRole];

function isAdmin(role: UserRole) {
  return role === UserRole.Admin;
}

/** PG enum public.user_role */
export enum UserRole {
  Admin = "admin",
  Member = "member",
  Guest = "guest",
}

// brands.ts  (generated)
export type PostId = number & { readonly __brand: "PostId" };
export type UserId = number & { readonly __brand: "UserId" };

export interface Post {
  id: PostId;   // was: number
  title: string;
}

export interface User {
  id: UserId;   // was: number
  email: string;
}

function getPost(id: PostId): Promise<Post> { ... }

const userId: UserId = 42 as UserId;
getPost(userId);  // Error: Argument of type 'UserId' is not assignable to parameter of type 'PostId'

export interface User {
  id: UserId;
  email: string;
  display_name?: string;   // nullable (optional)
  role: UserRole;
  readonly created_at: Date;  // server-managed
}

// Server-managed and nullable columns become optional in the Insert helper.
export type InsertUser = Omit<User, "display_name" | "created_at"> & Partial<Pick<User, "display_name" | "created_at">>;

// Every field is optional in the Update helper (for PATCH semantics).
export type UpdateUser = Partial<User>;

// POST /users
async function createUser(body: InsertUser): Promise<User> { ... }

// PATCH /users/:id
async function updateUser(id: UserId, body: UpdateUser): Promise<User> { ... }

/** Read-only row from view public.active_user_summary. */
export interface ActiveUserSummary {
  user_id: bigint | null;
  email: string | null;
  post_count: number | null;
}

export interface ActiveUserSummary {
  user_id?: bigint;
  email?: string;
  post_count?: number;
}

CREATE TYPE address AS (
  street text,
  city   text,
  zip    text
);

/** Composite type public.address. */
export interface Address {
  street: string;
  city: string;
  zip: string;
}

export interface Store {
  id: number;
  name: string;
  location: Address | null;
}

CREATE DOMAIN email_address AS text
  CHECK (VALUE ~* '^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$');

/** Domain public.email_address over text. */
export type EmailAddress = string;

// validators.ts  (generated)
import { z } from "zod";

export const UserRoleSchema = z.enum(["admin", "member", "guest"]);

export const AddressSchema = z.object({
  street: z.string(),
  city: z.string(),
  zip: z.string(),
});

export const UserSchema = z.object({
  id: z.number(),
  email: z.string(),
  displayName: z.string().nullable(),
  role: UserRoleSchema,
  createdAt: z.string(),   // date_as: string
  deletedAt: z.string().nullable(),
  metadata: z.unknown().nullable(),
});

import { UserSchema } from './db/validators';

// Validate an incoming request body
app.post('/users', async (req, res) => {
  const result = UserSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json(result.error.format());
  }
  const user = result.data;
  // user is fully typed as User
});

CREATE FUNCTION search_users(query text, limit_n int DEFAULT 20)
  RETURNS TABLE(id bigint, email text, score float8) ...;

CREATE FUNCTION string_length(s text) RETURNS integer ...;

CREATE PROCEDURE archive_user(user_id bigint) ...;

/** Input parameters for public.search_users. */
export interface SearchUsersParams {
  query: string;
  limit_n?: number;   // has DEFAULT → optional
}

/** One row returned by public.search_users. */
export interface SearchUsersResult {
  id: bigint;
  email: string;
  score: number;
}

/** Input parameters for public.string_length. */
export interface StringLengthParams {
  s: string;
}

/** Scalar value returned by public.string_length. */
export type StringLengthRow = number;

/** Input parameters for public.archive_user. */
export interface ArchiveUserParams {
  user_id: bigint;
}

outputs:
  - lang: ts
    out: ./src/db
    json_shapes:
      public.posts.metadata: "{ source: string; ip?: string }"
      public.users.settings: "UserSettings"

export interface Post {
  id: bigint;
  title: string;
  metadata: { source: string; ip?: string } | null;   // was: unknown | null
}

COMMENT ON COLUMN posts.metadata IS 'pg-flux: tstype={ source: string; ip?: string }';

outputs:
  - lang: ts
    out: ./src/db
    type_overrides:
      numeric: string   # already the default; shown for illustration
      interval: number  # treat interval as milliseconds

export interface Job {
  id: bigint;
  name: string;
  duration: number;   // was: string before override; maps interval → number
}

// index.ts  (generated)
export * from './brands';
export * from './enums';
export * from './types';
export * from './tables';
export * from './views';
export * from './functions';
export * from './validators';

import type { User, InsertUser, UserRole, UserSchema } from './src/db';