@zero/config-codegen

@zero/config-codegen (Zero config codegen) generates typed TypeScript configuration files from a declarative YAML schema.

In short:

• define config fields in .zero/configuration.yml,
• generate one config.ts,
• use the generated Config type everywhere in your application,
• validate runtime config values with validateConfig/loadConfig.

This avoids hand-written duplicated config interfaces and manual validation spread across the codebase.

Link with ZeroOS

This package is part of the ZeroOS project for organization-focused development tooling. It follows the same conventions used by ZeroOS teams and can be found under the standards repository:

• https://github.com/ZeroOS/standards

The repo includes conventions and examples for operational setup, including how configuration contracts are described.

What it generates

From a schema like .zero/configuration.yml, the tool generates:

• export type Config = ... (typed contract),
• export function validateConfig(value: unknown): asserts value is Config (runtime validation),
• export async function loadConfig(filePath: string): Promise<Config> (YAML loader + validation),
• internal schema object used by the validator.

The generated file includes a guard comment (// Do not edit manually.).

Install

npm install @zero/config-codegen
# or
pnpm add @zero/config-codegen
# or
yarn add @zero/config-codegen

CLI

zero-config generate <configuration.yml> <output.ts>

Example:

node node_modules/@zero/config-codegen/dist/cli.js generate .zero/configuration.yml src/generated/config.ts

npm/pnpm scripts can be used too:

{
  "scripts": {
    "config:generate": "zero-config generate .zero/configuration.yml src/generated/config.ts"
  }
}

.zero/configuration.yml schema

Minimal supported format:

version: 1

templates:
  database:
    host:
      kind: string
    port:
      kind: number

configuration:
  database:
    kind: object
    template: database
  logLevel:
    kind: string
    required: false

Top-level keys:

• version (required): currently only 1 is supported.
• templates (optional): reusable field definitions.
• configuration (required): root config contract.

Field kinds:

• string
• number
• boolean
• array (requires items)
• record (requires values)
• object (supports properties and optional template)

Other options:

• required: false: mark a field optional (default is required),
• secret: true: mark secret-bearing fields in schema metadata.

Validation rules

The generated runtime validator checks:

• missing required fields,
• wrong value types (string, number, boolean, array, object, record),
• recursive nested object/array/record structure.

Non-empty string checks are enforced (empty string is invalid for string fields).

Typical usage in TypeScript

import { loadConfig, type Config } from "./generated/config.js";

const configPath = process.env.CONFIG_PATH ?? "config.yml";
const config = await loadConfig(configPath);

function boot(appConfig: Config) {
  // fully typed access:
  const mongoHost: string = appConfig.mongodb?.host ?? "";
}

boot(config);

Error handling

During generation:

• unknown DSL fields or template names,
• malformed DSL shapes (items, properties, or values missing),
• unsupported version.

During load/validation:

• required keys missing,
• incompatible field types,
• malformed YAML root.

Each issue throws a clear error with the offending path in dot notation.