Configuration¶

Overview¶

Katal supports typed options binding with validation via app.configure(...).

Katal also auto-loads project config files from <project-root>/config/*.json during app.boot(). Each config file is stored using its filename as key: - config/app.json -> app.getConfig("app") - config/cache.json -> app.getConfig("cache")

This enables an ASP.NET-style options pattern: - bind from direct source object - fallback to environment variables - validate using Katal validation schema

It also supports env.* references inside config files: - "host": "env.DB_HOST" - "port": "env.DB_PORT"

Quick Start¶

import { Application, type ValidationSchema } from "katal";

const app = new Application({ port: 3000 });

type MailOptions = {
    host: string;
    port: number;
    secure: boolean;
};

const mailSchema: ValidationSchema = {
    host: { required: true, type: "string" },
    port: { required: true, type: "number", min: 1, max: 65535 },
    secure: { required: true, type: "boolean" },
};

const mail = app.configure<MailOptions>("mail", mailSchema, {
    source: {
        host: "smtp.example.com",
    },
    envPrefix: "MAIL_", // MAIL_PORT, MAIL_SECURE
});

console.log(mail.host, mail.port, mail.secure);

// Later
const resolved = app.getConfig<MailOptions>("mail");

Environment Binding Rules¶

Field name port maps to env key PORT by default.
With envPrefix: "MAIL_", port maps to MAIL_PORT.
Camel case fields are normalized to uppercase snake case:
apiKey -> API_KEY

For auto-loaded config files, any string matching env.VAR_NAME is resolved from process env.

Value Parsing¶

Environment values are parsed as: - "true"/"false" -> boolean - numeric strings -> number - JSON objects/arrays -> parsed JSON - otherwise -> string

Validation Failures¶

app.configure(...) throws when schema validation fails.

Example error shape: - Configuration 'mail' is invalid. port: port is required

Auto-loaded App Config Overrides¶

If config/app.json exists and includes these keys, Katal applies them to runtime app config: - port - host - cors - bodyParser