@zamatica/configuration

Framework-agnostic runtime configuration for TypeScript apps. Static-method service, builder-pattern parameter definitions, layered resolution (CLI > env > default), directory access checks, and Zod-validated YAML.

Designed to be available before any framework (NestJS, Express, etc.) is bootstrapped — no DI container required.

Install

bun add @zamatica/configuration

Quick example

import {
  Configuration,
  ConfigurationParameter,
  ConfigurationService,
} from '@zamatica/configuration';
import { z } from 'zod';

@Configuration(
  'MyApp',
  ConfigurationParameter.named('PORT')
    .number()
    .default(8080)
    .description('HTTP listen port')
    .required()
    .build(),
  ConfigurationParameter.named('CONFIG_DIR')
    .directory()
    .default('/etc/myapp')
    .createIfMissing()
    .build(),
  ConfigurationParameter.named('SERVICES')
    .yaml()
    .schema(z.object({ services: z.array(z.string()) }))
    .default('services.yaml')
    .build(),
)
class MyApp {
  static async start() {
    ConfigurationService.setAppEnvVarPrefix('MYAPP');
    ConfigurationService.initialize(); // throws if any required is missing

    const port = ConfigurationService.get<number>('PORT');
    const dir = ConfigurationService.resolveDirectory('CONFIG_DIR');
    const services = ConfigurationService.resolveYaml<{ services: string[] }>('SERVICES');
    /* ... */
  }
}

Resolution priority

For each registered parameter, ConfigurationService.get() consults:

1. CLI argument — set externally via ConfigurationService.setCliArgs({...}). The argument key is the configuration key in camelCase (PORT → port, LOG_LEVEL → logLevel).
2. Environment variable — <APP_PREFIX>_<KEY> (e.g. MYAPP_PORT). Set the prefix via setAppEnvVarPrefix(); defaults to empty (bare key) if not set.
3. Default — declared via .default(value) on the builder.

If a parameter is .required() and none of the above provide a value, get() throws.

Parameter types

• .string() / .number() / .boolean() — simple primitives. Coerced from the source value (env vars and CLI strings → typed values).
• .directory() — string-valued; resolveDirectory() performs path resolution (relative paths joined under CONFIGURATION_BASE_DIRECTORY), existence/access checks, and optional createIfMissing()/requireWritable().
• .yaml() — string-valued (the file path); resolveYaml() reads the file, parses YAML, and validates against the optional Zod schema. With a schema, the return type is narrowed via z.infer<typeof schema>.

Logger

A small ConfigurationLogger interface (debug/info/warn/error). Default implementation is BufferingLogger that holds entries in memory; pass any ConfigurationLogger (e.g. new ConsoleLogger() or a NestJS-bridged logger) to setLogger() and the buffer flushes to it. This makes pre-bootstrap logs available once the real logger comes up.

See also

• @zamatica/bootstrap — adds commander integration, app metadata, and --generate-dot-env on top of this library.