Codegen

The biref CLI connects to a live database, scans it, and emits TypeScript files with a BirefSchema type that mirrors the schema.

Single-file mode

Everything in one ./biref/biref.schema.ts:

pnpm exec biref gen \
  --url postgres://user:pass@localhost/mydb \
  --namespace public \
  --namespace billing

Split mode

One file per entity plus an index.ts:

pnpm exec biref gen \
  --url postgres://user:pass@localhost/mydb \
  --split \
  --all-namespaces

Output:

biref/
  index.ts                      # re-exports + BirefSchema type
  biref.schema.overrides.ts     # scaffolded once, never regenerated
  identity/
    users.ts
    accounts.ts
  catalog/
    products.ts
    ...

CLI flags

Flag	Effect
--url <connection>	Required. Database connection URL.
--out <path>	Output file or folder. Defaults to ./biref/biref.schema.ts or ./biref.
--split	Emit per-entity files + an index.
--namespace <name>	Scan this namespace. Repeatable.
--all-namespaces	Scan every non-system namespace.
--overwrite / --no-overwrite	Overwrite generated files (default) or refuse.
--adapter <name>	Pick an adapter when multiple are registered.

Overrides

Type your JSON columns or override any auto-inferred type:

// biref.schema.overrides.ts
export interface Overrides {
  'public.users': {
    profile: { plan: 'free' | 'pro'; prefs: { darkMode: boolean } };
  };
}

After the next regen, profile is typed as { plan: 'free' | 'pro'; prefs: { darkMode: boolean } } | null instead of unknown | null.

The overrides file is scaffolded once and never overwritten by subsequent runs.

Programmatic API

Every piece the CLI uses is exported:

import {
  generateSchema,       // (model: DataModel): string
  generateSchemaFiles,  // (model: DataModel): readonly SchemaFile[]
  overridesScaffold,    // (): string
  tsTypeFor,            // (fieldType, nullable): string
} from '@biref/scanner';

Example: custom codegen script

import { writeFileSync } from 'node:fs';
import { generateSchema, Biref, postgresAdapter } from '@biref/scanner';
import pg from 'pg';

const client = new pg.Client({ connectionString: process.env.DATABASE_URL });
await client.connect();

const biref = Biref.builder()
  .withAdapter(postgresAdapter.create(client))
  .build();

const model = await biref.scan({ namespaces: 'all' });
writeFileSync('./biref/biref.schema.ts', generateSchema(model));

await client.end();