@zamatica/configuration 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @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
+
+```bash
+bun add @zamatica/configuration
+```
+
+## Quick example
+
+```ts
+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.

package/dist/configuration-service.d.ts

@@ -0,0 +1,41 @@
+import { type ConfigurationLogger } from './logger.js';
+import type { ConfigurationParameterDefinition, ConfigurationValuePrimitive } from './parameter-types.js';
+export declare class ConfigurationService {
+    private static appEnvVarPrefix;
+    private static cliArgs;
+    private static buffer;
+    private static loggerImpl;
+    private static readonly registry;
+    private static readonly registryByTarget;
+    private static readonly resolvedDirectories;
+    private static readonly resolvedYaml;
+    private static initialized;
+    private constructor();
+    static setAppEnvVarPrefix(prefix: string): void;
+    static getAppEnvVarPrefix(): string;
+    static setCliArgs(args: Record<string, ConfigurationValuePrimitive | undefined>): void;
+    static setLogger(logger: ConfigurationLogger): void;
+    static useConsoleLogger(): void;
+    static register(parameters: ConfigurationParameterDefinition[], target: string): void;
+    static initialize(): void;
+    static isInitialized(): boolean;
+    static get<T extends ConfigurationValuePrimitive>(configurationKey: string): T;
+    static resolveDirectory(configurationKey: string): string;
+    static resolveYaml<TResult = unknown>(configurationKey: string): TResult;
+    static getRegistry(): readonly ConfigurationParameterDefinition[];
+    static getRegistryByTarget(): ReadonlyMap<string, readonly ConfigurationParameterDefinition[]>;
+    static environmentVariableName(configurationKey: string): string;
+    /**
+     * Test-only reset. Wipes all module-singleton state (registry, resolution
+     * caches, logger, app prefix). Not re-exported from `src/index.ts` — call sites
+     * must reach in via `ConfigurationService.__resetForTesting()` directly,
+     * which is intentional friction signaling "this is for vitest, not runtime."
+     *
+     * Production code must never call this; the underscore prefix and explicit
+     * `forTesting` suffix exist to make accidental use obvious in code review.
+     */
+    static __resetForTesting(): void;
+    private static coerce;
+    private static ensureDirectoryAccess;
+}
+//# sourceMappingURL=configuration-service.d.ts.map

package/dist/configuration-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration-service.d.ts","sourceRoot":"","sources":["../src/configuration-service.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,mBAAmB,EAGzB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,gCAAgC,EAChC,2BAA2B,EAE5B,MAAM,sBAAsB,CAAC;AAI9B,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAC,eAAe,CAAM;IACpC,OAAO,CAAC,MAAM,CAAC,OAAO,CAA+D;IACrF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAyB;IAC9C,OAAO,CAAC,MAAM,CAAC,UAAU,CAAoD;IAE7E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAuD;IACvF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAyD;IAEjG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAA6B;IACxE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAA8B;IAElE,OAAO,CAAC,MAAM,CAAC,WAAW,CAAS;IAEnC,OAAO;IAIP,MAAM,CAAC,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/C,MAAM,CAAC,kBAAkB,IAAI,MAAM;IAInC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,GAAG,SAAS,CAAC,GAAG,IAAI;IAItF,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAOnD,MAAM,CAAC,gBAAgB,IAAI,IAAI;IAI/B,MAAM,CAAC,QAAQ,CACb,UAAU,EAAE,gCAAgC,EAAE,EAC9C,MAAM,EAAE,MAAM,GACb,IAAI;IAqBP,MAAM,CAAC,UAAU,IAAI,IAAI;IAmBzB,MAAM,CAAC,aAAa,IAAI,OAAO;IAI/B,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,2BAA2B,EAAE,gBAAgB,EAAE,MAAM,GAAG,CAAC;IA0C9E,MAAM,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM;IAiCzD,MAAM,CAAC,WAAW,CAAC,OAAO,GAAG,OAAO,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO;IA0DxE,MAAM,CAAC,WAAW,IAAI,SAAS,gCAAgC,EAAE;IAIjE,MAAM,CAAC,mBAAmB,IAAI,WAAW,CAAC,MAAM,EAAE,SAAS,gCAAgC,EAAE,CAAC;IAS9F,MAAM,CAAC,uBAAuB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM;IAMhE;;;;;;;;OAQG;IACH,MAAM,CAAC,iBAAiB,IAAI,IAAI;IAYhC,OAAO,CAAC,MAAM,CAAC,MAAM;IA2BrB,OAAO,CAAC,MAAM,CAAC,qBAAqB;CAyBrC"}

package/dist/configuration-service.js

@@ -0,0 +1,254 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { camelizeEnvVarName } from '@zamatica/util';
+import { parse as parseYAML } from 'yaml';
+import { BufferingLogger, ConsoleLogger, flushBuffer, } from './logger.js';
+const CONFIG_BASE_DIR_KEY = 'CONFIGURATION_BASE_DIRECTORY';
+export class ConfigurationService {
+    static appEnvVarPrefix = '';
+    static cliArgs = {};
+    static buffer = new BufferingLogger();
+    static loggerImpl = ConfigurationService.buffer;
+    static registry = new Map();
+    static registryByTarget = new Map();
+    static resolvedDirectories = new Map();
+    static resolvedYaml = new Map();
+    static initialized = false;
+    constructor() {
+        /* static-only */
+    }
+    static setAppEnvVarPrefix(prefix) {
+        ConfigurationService.appEnvVarPrefix = prefix.toUpperCase();
+    }
+    static getAppEnvVarPrefix() {
+        return ConfigurationService.appEnvVarPrefix;
+    }
+    static setCliArgs(args) {
+        ConfigurationService.cliArgs = { ...args };
+    }
+    static setLogger(logger) {
+        if (ConfigurationService.loggerImpl === ConfigurationService.buffer) {
+            flushBuffer(ConfigurationService.buffer, logger);
+        }
+        ConfigurationService.loggerImpl = logger;
+    }
+    static useConsoleLogger() {
+        ConfigurationService.setLogger(new ConsoleLogger());
+    }
+    static register(parameters, target) {
+        for (const parameter of parameters) {
+            const existing = ConfigurationService.registry.get(parameter.configurationKey);
+            if (existing) {
+                throw new Error(`Configuration key '${parameter.configurationKey}' is already registered.`);
+            }
+            ConfigurationService.registry.set(parameter.configurationKey, parameter);
+            const list = ConfigurationService.registryByTarget.get(target) ?? [];
+            list.push(parameter);
+            ConfigurationService.registryByTarget.set(target, list);
+            ConfigurationService.loggerImpl.debug(`[configuration] registered ${parameter.kind} key '${parameter.configurationKey}' for target '${target}' (default=${String(parameter.default)})`);
+        }
+    }
+    static initialize() {
+        const errors = [];
+        for (const parameter of ConfigurationService.registry.values()) {
+            if (parameter.required && parameter.default === undefined) {
+                try {
+                    ConfigurationService.get(parameter.configurationKey);
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error.message : String(error));
+                }
+            }
+        }
+        if (errors.length > 0) {
+            throw new Error(`Required configuration not satisfied:\n  - ${errors.join('\n  - ')}`);
+        }
+        ConfigurationService.initialized = true;
+    }
+    static isInitialized() {
+        return ConfigurationService.initialized;
+    }
+    static get(configurationKey) {
+        const parameter = ConfigurationService.registry.get(configurationKey);
+        if (!parameter) {
+            throw new Error(`Configuration key '${configurationKey}' is not registered.`);
+        }
+        const argumentKey = camelizeEnvVarName(configurationKey);
+        const envVarName = ConfigurationService.environmentVariableName(configurationKey);
+        let raw;
+        let source;
+        if (Object.prototype.hasOwnProperty.call(ConfigurationService.cliArgs, argumentKey) &&
+            ConfigurationService.cliArgs[argumentKey] !== undefined) {
+            raw = ConfigurationService.cliArgs[argumentKey];
+            source = 'cli';
+        }
+        else if (process.env[envVarName] !== undefined && process.env[envVarName] !== '') {
+            raw = process.env[envVarName];
+            source = 'env';
+        }
+        else if (parameter.default !== undefined) {
+            raw = parameter.default;
+            source = 'default';
+        }
+        if (raw === undefined) {
+            if (parameter.required) {
+                throw new Error(`No value found for required configuration key '${configurationKey}' in CLI argument '${argumentKey}', environment variable '${envVarName}', or default.`);
+            }
+            return undefined;
+        }
+        ConfigurationService.loggerImpl.debug(`[configuration] '${configurationKey}' resolved from ${source}: ${String(raw)}`);
+        return ConfigurationService.coerce(raw, parameter);
+    }
+    static resolveDirectory(configurationKey) {
+        const cached = ConfigurationService.resolvedDirectories.get(configurationKey);
+        if (cached !== undefined)
+            return cached;
+        const parameter = ConfigurationService.registry.get(configurationKey);
+        if (!parameter) {
+            throw new Error(`Configuration key '${configurationKey}' is not registered.`);
+        }
+        if (parameter.kind !== 'directory') {
+            throw new Error(`Configuration key '${configurationKey}' is not a directory parameter.`);
+        }
+        const configured = ConfigurationService.get(configurationKey);
+        if (configured === undefined || configured === '') {
+            if (parameter.required) {
+                throw new Error(`Required directory configuration '${configurationKey}' is empty.`);
+            }
+            return '';
+        }
+        let resolved = configured;
+        if (!path.isAbsolute(resolved) && configurationKey !== CONFIG_BASE_DIR_KEY) {
+            const base = ConfigurationService.resolveDirectory(CONFIG_BASE_DIR_KEY);
+            resolved = path.join(base, resolved);
+        }
+        else {
+            resolved = path.resolve(resolved);
+        }
+        ConfigurationService.ensureDirectoryAccess(resolved, parameter);
+        ConfigurationService.resolvedDirectories.set(configurationKey, resolved);
+        return resolved;
+    }
+    static resolveYaml(configurationKey) {
+        const cached = ConfigurationService.resolvedYaml.get(configurationKey);
+        if (cached !== undefined)
+            return cached;
+        const parameter = ConfigurationService.registry.get(configurationKey);
+        if (!parameter) {
+            throw new Error(`Configuration key '${configurationKey}' is not registered.`);
+        }
+        if (parameter.kind !== 'yaml') {
+            throw new Error(`Configuration key '${configurationKey}' is not a yaml parameter.`);
+        }
+        const configured = ConfigurationService.get(configurationKey);
+        if (configured === undefined || configured === '') {
+            throw new Error(`YAML configuration '${configurationKey}' has no value.`);
+        }
+        let resolved = configured;
+        if (!path.isAbsolute(resolved)) {
+            const base = ConfigurationService.resolveDirectory(CONFIG_BASE_DIR_KEY);
+            resolved = path.join(base, resolved);
+        }
+        else {
+            resolved = path.resolve(resolved);
+        }
+        if (!fs.existsSync(resolved)) {
+            throw new Error(`YAML file for '${configurationKey}' not found: ${resolved}`);
+        }
+        const stats = fs.statSync(resolved);
+        if (!stats.isFile()) {
+            throw new Error(`YAML path for '${configurationKey}' is not a file: ${resolved}`);
+        }
+        const raw = fs.readFileSync(resolved, 'utf8');
+        const parsed = parseYAML(raw);
+        if (parameter.schema !== undefined) {
+            const result = parameter.schema.safeParse(parsed);
+            if (!result.success) {
+                throw new Error(`YAML validation failed for '${configurationKey}' (${resolved}): ${JSON.stringify(result.error.issues, null, 2)}`);
+            }
+            ConfigurationService.resolvedYaml.set(configurationKey, result.data);
+            return result.data;
+        }
+        ConfigurationService.loggerImpl.warn(`[configuration] no schema provided for YAML key '${configurationKey}'; returning unvalidated parsed data.`);
+        ConfigurationService.resolvedYaml.set(configurationKey, parsed);
+        return parsed;
+    }
+    static getRegistry() {
+        return Array.from(ConfigurationService.registry.values());
+    }
+    static getRegistryByTarget() {
+        return new Map(Array.from(ConfigurationService.registryByTarget.entries()).map(([target, params]) => [
+            target,
+            params.slice(),
+        ]));
+    }
+    static environmentVariableName(configurationKey) {
+        return ConfigurationService.appEnvVarPrefix
+            ? `${ConfigurationService.appEnvVarPrefix}_${configurationKey}`
+            : configurationKey;
+    }
+    /**
+     * Test-only reset. Wipes all module-singleton state (registry, resolution
+     * caches, logger, app prefix). Not re-exported from `src/index.ts` — call sites
+     * must reach in via `ConfigurationService.__resetForTesting()` directly,
+     * which is intentional friction signaling "this is for vitest, not runtime."
+     *
+     * Production code must never call this; the underscore prefix and explicit
+     * `forTesting` suffix exist to make accidental use obvious in code review.
+     */
+    static __resetForTesting() {
+        ConfigurationService.appEnvVarPrefix = '';
+        ConfigurationService.cliArgs = {};
+        ConfigurationService.buffer = new BufferingLogger();
+        ConfigurationService.loggerImpl = ConfigurationService.buffer;
+        ConfigurationService.registry.clear();
+        ConfigurationService.registryByTarget.clear();
+        ConfigurationService.resolvedDirectories.clear();
+        ConfigurationService.resolvedYaml.clear();
+        ConfigurationService.initialized = false;
+    }
+    static coerce(value, parameter) {
+        switch (parameter.constructor) {
+            case Number: {
+                if (typeof value === 'number')
+                    return value;
+                if (typeof value === 'boolean')
+                    return value ? 1 : 0;
+                const parsed = Number.parseFloat(value);
+                if (Number.isNaN(parsed)) {
+                    throw new Error(`Cannot coerce value '${value}' to number for '${parameter.configurationKey}'.`);
+                }
+                return parsed;
+            }
+            case Boolean: {
+                if (typeof value === 'boolean')
+                    return value;
+                if (typeof value === 'number')
+                    return value !== 0;
+                return value.toLowerCase() === 'true' || value === '1';
+            }
+            default:
+                // Default covers String and any future constructor. Stringify whatever value we got.
+                return String(value);
+        }
+    }
+    static ensureDirectoryAccess(resolved, parameter) {
+        const exists = fs.existsSync(resolved);
+        if (!exists) {
+            if (parameter.createIfMissing) {
+                fs.mkdirSync(resolved, { recursive: true });
+            }
+            else {
+                throw new Error(`Directory '${resolved}' for configuration '${parameter.configurationKey}' does not exist and createIfMissing is false.`);
+            }
+        }
+        const stats = fs.statSync(resolved);
+        if (!stats.isDirectory()) {
+            throw new Error(`Path '${resolved}' for configuration '${parameter.configurationKey}' is not a directory.`);
+        }
+        const mode = parameter.requireWritable
+            ? fs.constants.R_OK | fs.constants.W_OK
+            : fs.constants.R_OK;
+        fs.accessSync(resolved, mode);
+    }
+}

package/dist/decorators.d.ts

@@ -0,0 +1,27 @@
+import type { ConfigurationParameterDefinition } from './parameter-types.js';
+type AnyClass = Function;
+/**
+ * Class decorator that registers a set of configuration parameters and groups
+ * them under a target name (used by `print-config` / `getRegistryByTarget()`
+ * for display, and by error messages).
+ *
+ * Pass the target name as the first argument:
+ *
+ *   @Configuration('HttpListenerConfig', ...HTTP_LISTENER_PARAMETERS)
+ *   class HttpListenerConfig { ... }
+ *
+ * Why explicit instead of `target.name`? The TypeScript `experimentalDecorators`
+ * emit produces `let Foo = class Foo { ... }` which, after a JS bundler hoists
+ * the `let` to the module scope, gets the inner class expression renamed to
+ * `Foo2` to avoid the outer/inner binding collision. A decorator reading
+ * `target.name` would then register against `Foo2`, surfacing nonsense
+ * suffixes in `print-config` output. Passing the name explicitly sidesteps
+ * the whole problem and survives any future minifier/bundler renames.
+ *
+ * If the first argument is omitted (legacy callers), the decorator falls back
+ * to `target.name` — which works fine when the class is bundled from source
+ * but is fragile when bundled from prebuilt `dist/` JS.
+ */
+export declare function Configuration(nameOrFirstParameter: string | ConfigurationParameterDefinition, ...rest: ConfigurationParameterDefinition[]): (target: AnyClass) => void;
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAC;AAG7E,KAAK,QAAQ,GAAG,QAAQ,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,oBAAoB,EAAE,MAAM,GAAG,gCAAgC,EAC/D,GAAG,IAAI,EAAE,gCAAgC,EAAE,GAC1C,CAAC,MAAM,EAAE,QAAQ,KAAK,IAAI,CAU5B"}

package/dist/decorators.js

@@ -0,0 +1,32 @@
+import { ConfigurationService } from './configuration-service.js';
+/**
+ * Class decorator that registers a set of configuration parameters and groups
+ * them under a target name (used by `print-config` / `getRegistryByTarget()`
+ * for display, and by error messages).
+ *
+ * Pass the target name as the first argument:
+ *
+ *   @Configuration('HttpListenerConfig', ...HTTP_LISTENER_PARAMETERS)
+ *   class HttpListenerConfig { ... }
+ *
+ * Why explicit instead of `target.name`? The TypeScript `experimentalDecorators`
+ * emit produces `let Foo = class Foo { ... }` which, after a JS bundler hoists
+ * the `let` to the module scope, gets the inner class expression renamed to
+ * `Foo2` to avoid the outer/inner binding collision. A decorator reading
+ * `target.name` would then register against `Foo2`, surfacing nonsense
+ * suffixes in `print-config` output. Passing the name explicitly sidesteps
+ * the whole problem and survives any future minifier/bundler renames.
+ *
+ * If the first argument is omitted (legacy callers), the decorator falls back
+ * to `target.name` — which works fine when the class is bundled from source
+ * but is fragile when bundled from prebuilt `dist/` JS.
+ */
+export function Configuration(nameOrFirstParameter, ...rest) {
+    const explicitName = typeof nameOrFirstParameter === 'string' ? nameOrFirstParameter : undefined;
+    const parameters = explicitName === undefined
+        ? [nameOrFirstParameter, ...rest]
+        : rest;
+    return (target) => {
+        ConfigurationService.register(parameters, explicitName ?? target.name);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Configuration } from './decorators.js';
+export { ConfigurationService } from './configuration-service.js';
+export { ConfigurationParameter, type AnyConfigurationParameterBuilder, type AnyConfigurationParameterDefinition, } from './parameter-builder.js';
+export { type ConfigurationParameterDefinition, type ConfigurationParameterDefinitionBase, type ConfigurationValuePrimitive, type ConfigurationValueConstructor, type SimpleConfigurationParameterDefinition, type DirectoryConfigurationParameterDefinition, type YamlConfigurationParameterDefinition, } from './parameter-types.js';
+export { type ConfigurationLogger, type LogLevel, type BufferedLogEntry, ConsoleLogger, BufferingLogger, flushBuffer, } from './logger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,sBAAsB,EACtB,KAAK,gCAAgC,EACrC,KAAK,mCAAmC,GACzC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,gCAAgC,EACrC,KAAK,oCAAoC,EACzC,KAAK,2BAA2B,EAChC,KAAK,6BAA6B,EAClC,KAAK,sCAAsC,EAC3C,KAAK,yCAAyC,EAC9C,KAAK,oCAAoC,GAC1C,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Configuration } from './decorators.js';
+export { ConfigurationService } from './configuration-service.js';
+export { ConfigurationParameter, } from './parameter-builder.js';
+export { ConsoleLogger, BufferingLogger, flushBuffer, } from './logger.js';

package/dist/internal/camelize.d.ts

@@ -0,0 +1,2 @@
+export declare function camelizeEnvVarName(envVarName: string): string;
+//# sourceMappingURL=camelize.d.ts.map

package/dist/internal/camelize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camelize.d.ts","sourceRoot":"","sources":["../../src/internal/camelize.ts"],"names":[],"mappings":"AAKA,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM7D"}

package/dist/internal/camelize.js

@@ -0,0 +1,12 @@
+function capitalizeFirstLetter(word) {
+    if (word.length === 0)
+        return '';
+    return word.charAt(0).toUpperCase() + word.slice(1);
+}
+export function camelizeEnvVarName(envVarName) {
+    return envVarName
+        .toLowerCase()
+        .split('_')
+        .map((segment, index) => (index === 0 ? segment : capitalizeFirstLetter(segment)))
+        .join('');
+}

package/dist/logger.d.ts

@@ -0,0 +1,31 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface ConfigurationLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+export interface BufferedLogEntry {
+    level: LogLevel;
+    message: string;
+    args: unknown[];
+    timestamp: Date;
+}
+export declare class ConsoleLogger implements ConfigurationLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+export declare class BufferingLogger implements ConfigurationLogger {
+    private readonly entries;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    private append;
+    drain(): readonly BufferedLogEntry[];
+    size(): number;
+}
+export declare function flushBuffer(buffer: BufferingLogger, target: ConfigurationLogger): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,qBAAa,aAAc,YAAW,mBAAmB;IACvD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAGhD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAG/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAG/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;CAGjD;AAED,qBAAa,eAAgB,YAAW,mBAAmB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAGhD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAG/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAG/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIhD,OAAO,CAAC,MAAM;IAId,KAAK,IAAI,SAAS,gBAAgB,EAAE;IAMpC,IAAI,IAAI,MAAM;CAGf;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAItF"}

package/dist/logger.js

@@ -0,0 +1,45 @@
+export class ConsoleLogger {
+    debug(message, ...args) {
+        console.debug(message, ...args);
+    }
+    info(message, ...args) {
+        console.info(message, ...args);
+    }
+    warn(message, ...args) {
+        console.warn(message, ...args);
+    }
+    error(message, ...args) {
+        console.error(message, ...args);
+    }
+}
+export class BufferingLogger {
+    entries = [];
+    debug(message, ...args) {
+        this.append('debug', message, args);
+    }
+    info(message, ...args) {
+        this.append('info', message, args);
+    }
+    warn(message, ...args) {
+        this.append('warn', message, args);
+    }
+    error(message, ...args) {
+        this.append('error', message, args);
+    }
+    append(level, message, args) {
+        this.entries.push({ level, message, args, timestamp: new Date() });
+    }
+    drain() {
+        const drained = this.entries.slice();
+        this.entries.length = 0;
+        return drained;
+    }
+    size() {
+        return this.entries.length;
+    }
+}
+export function flushBuffer(buffer, target) {
+    for (const entry of buffer.drain()) {
+        target[entry.level](entry.message, ...entry.args);
+    }
+}

package/dist/parameter-builder.d.ts

@@ -0,0 +1,59 @@
+import type { z } from 'zod';
+import type { ConfigurationParameterDefinition, ConfigurationValueConstructor, ConfigurationValuePrimitive, DirectoryConfigurationParameterDefinition, SimpleConfigurationParameterDefinition, YamlConfigurationParameterDefinition } from './parameter-types.js';
+interface BaseState {
+    key: string;
+    description: string;
+    required: boolean;
+    default: ConfigurationValuePrimitive | undefined;
+}
+/**
+ * Common methods shared by every parameter builder. Subclasses add type-specific
+ * methods (e.g. `requireWritable()` on directory builders) and implement `build()`.
+ *
+ * The builder mutates `this.state` and returns `this` for chaining; subclasses
+ * preserve that pattern so chains compose cleanly.
+ */
+declare abstract class ParameterBuilderBase<TSelf extends ParameterBuilderBase<TSelf, TDef>, TDef> {
+    protected state: BaseState;
+    protected constructor(state: BaseState);
+    description(text: string): TSelf;
+    default(value: ConfigurationValuePrimitive): TSelf;
+    required(): TSelf;
+    optional(): TSelf;
+    abstract build(): TDef;
+}
+declare class SimpleParameterBuilder extends ParameterBuilderBase<SimpleParameterBuilder, SimpleConfigurationParameterDefinition> {
+    private readonly constructorFn;
+    constructor(state: BaseState, constructorFn: ConfigurationValueConstructor);
+    build(): SimpleConfigurationParameterDefinition;
+}
+declare class DirectoryParameterBuilder extends ParameterBuilderBase<DirectoryParameterBuilder, DirectoryConfigurationParameterDefinition> {
+    private requireWritableFlag;
+    private createIfMissingFlag;
+    constructor(state: BaseState);
+    requireWritable(): this;
+    createIfMissing(): this;
+    build(): DirectoryConfigurationParameterDefinition;
+}
+declare class YamlParameterBuilder<TSchema extends z.ZodTypeAny = z.ZodTypeAny> extends ParameterBuilderBase<YamlParameterBuilder<TSchema>, YamlConfigurationParameterDefinition<TSchema>> {
+    private schemaValue;
+    constructor(state: BaseState);
+    schema<TNewSchema extends z.ZodTypeAny>(schema: TNewSchema): YamlParameterBuilder<TNewSchema>;
+    build(): YamlConfigurationParameterDefinition<TSchema>;
+}
+declare class ParameterTypeSelector {
+    private readonly state;
+    constructor(state: BaseState);
+    string(): SimpleParameterBuilder;
+    number(): SimpleParameterBuilder;
+    boolean(): SimpleParameterBuilder;
+    directory(): DirectoryParameterBuilder;
+    yaml(): YamlParameterBuilder;
+}
+export declare const ConfigurationParameter: {
+    named(key: string): ParameterTypeSelector;
+};
+export type AnyConfigurationParameterBuilder = SimpleParameterBuilder | DirectoryParameterBuilder | YamlParameterBuilder;
+export type AnyConfigurationParameterDefinition = ConfigurationParameterDefinition;
+export {};
+//# sourceMappingURL=parameter-builder.d.ts.map

package/dist/parameter-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameter-builder.d.ts","sourceRoot":"","sources":["../src/parameter-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EACV,gCAAgC,EAChC,6BAA6B,EAC7B,2BAA2B,EAC3B,yCAAyC,EACzC,sCAAsC,EACtC,oCAAoC,EACrC,MAAM,sBAAsB,CAAC;AAY9B,UAAU,SAAS;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,2BAA2B,GAAG,SAAS,CAAC;CAClD;AAED;;;;;;GAMG;AACH,uBAAe,oBAAoB,CAAC,KAAK,SAAS,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,IAAI;IACvF,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC;IAE3B,SAAS,aAAa,KAAK,EAAE,SAAS;IAItC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAKhC,OAAO,CAAC,KAAK,EAAE,2BAA2B,GAAG,KAAK;IAKlD,QAAQ,IAAI,KAAK;IAKjB,QAAQ,IAAI,KAAK;IAKjB,QAAQ,CAAC,KAAK,IAAI,IAAI;CACvB;AAED,cAAM,sBAAuB,SAAQ,oBAAoB,CACvD,sBAAsB,EACtB,sCAAsC,CACvC;IAC+B,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAhD,KAAK,EAAE,SAAS,EAAmB,aAAa,EAAE,6BAA6B;IAI3F,KAAK,IAAI,sCAAsC;CAUhD;AAED,cAAM,yBAA0B,SAAQ,oBAAoB,CAC1D,yBAAyB,EACzB,yCAAyC,CAC1C;IACC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,mBAAmB,CAAS;gBAExB,KAAK,EAAE,SAAS;IAI5B,eAAe,IAAI,IAAI;IAKvB,eAAe,IAAI,IAAI;IAKvB,KAAK,IAAI,yCAAyC;CAYnD;AAED,cAAM,oBAAoB,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAE,SAAQ,oBAAoB,CAClG,oBAAoB,CAAC,OAAO,CAAC,EAC7B,oCAAoC,CAAC,OAAO,CAAC,CAC9C;IACC,OAAO,CAAC,WAAW,CAAsB;gBAE7B,KAAK,EAAE,SAAS;IAI5B,MAAM,CAAC,UAAU,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,GAAG,oBAAoB,CAAC,UAAU,CAAC;IAM7F,KAAK,IAAI,oCAAoC,CAAC,OAAO,CAAC;CAWvD;AAED,cAAM,qBAAqB;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,SAAS;IAE7C,MAAM,IAAI,sBAAsB;IAIhC,MAAM,IAAI,sBAAsB;IAIhC,OAAO,IAAI,sBAAsB;IAIjC,SAAS,IAAI,yBAAyB;IAItC,IAAI,IAAI,oBAAoB;CAG7B;AAED,eAAO,MAAM,sBAAsB;eACtB,MAAM,GAAG,qBAAqB;CAS1C,CAAC;AAEF,MAAM,MAAM,gCAAgC,GACxC,sBAAsB,GACtB,yBAAyB,GACzB,oBAAoB,CAAC;AAEzB,MAAM,MAAM,mCAAmC,GAAG,gCAAgC,CAAC"}