@zamatica/configuration 0.1.0

package/dist/parameter-builder.js

@@ -0,0 +1,133 @@
+const ENV_VAR_NAME_REGEX = /^[A-Z]([A-Z0-9_]*[A-Z0-9])?$/;
+function assertValidConfigurationKey(key) {
+    if (!ENV_VAR_NAME_REGEX.test(key)) {
+        throw new Error(`Invalid configuration key '${key}': must match SCREAMING_SNAKE_CASE (env-var convention).`);
+    }
+}
+/**
+ * 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.
+ */
+class ParameterBuilderBase {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    description(text) {
+        this.state = { ...this.state, description: text };
+        return this;
+    }
+    default(value) {
+        this.state = { ...this.state, default: value };
+        return this;
+    }
+    required() {
+        this.state = { ...this.state, required: true };
+        return this;
+    }
+    optional() {
+        this.state = { ...this.state, required: false };
+        return this;
+    }
+}
+class SimpleParameterBuilder extends ParameterBuilderBase {
+    constructorFn;
+    constructor(state, constructorFn) {
+        super(state);
+        this.constructorFn = constructorFn;
+    }
+    build() {
+        return {
+            kind: 'simple',
+            configurationKey: this.state.key,
+            description: this.state.description,
+            required: this.state.required,
+            default: this.state.default,
+            constructor: this.constructorFn,
+        };
+    }
+}
+class DirectoryParameterBuilder extends ParameterBuilderBase {
+    requireWritableFlag = false;
+    createIfMissingFlag = false;
+    constructor(state) {
+        super(state);
+    }
+    requireWritable() {
+        this.requireWritableFlag = true;
+        return this;
+    }
+    createIfMissing() {
+        this.createIfMissingFlag = true;
+        return this;
+    }
+    build() {
+        return {
+            kind: 'directory',
+            configurationKey: this.state.key,
+            description: this.state.description,
+            required: this.state.required,
+            default: this.state.default,
+            constructor: String,
+            requireWritable: this.requireWritableFlag,
+            createIfMissing: this.createIfMissingFlag,
+        };
+    }
+}
+class YamlParameterBuilder extends ParameterBuilderBase {
+    schemaValue;
+    constructor(state) {
+        super(state);
+    }
+    schema(schema) {
+        const next = new YamlParameterBuilder(this.state);
+        next.schemaValue = schema;
+        return next;
+    }
+    build() {
+        return {
+            kind: 'yaml',
+            configurationKey: this.state.key,
+            description: this.state.description,
+            required: this.state.required,
+            default: this.state.default,
+            constructor: String,
+            schema: this.schemaValue,
+        };
+    }
+}
+class ParameterTypeSelector {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    string() {
+        return new SimpleParameterBuilder(this.state, String);
+    }
+    number() {
+        return new SimpleParameterBuilder(this.state, Number);
+    }
+    boolean() {
+        return new SimpleParameterBuilder(this.state, Boolean);
+    }
+    directory() {
+        return new DirectoryParameterBuilder(this.state);
+    }
+    yaml() {
+        return new YamlParameterBuilder(this.state);
+    }
+}
+export const ConfigurationParameter = {
+    named(key) {
+        assertValidConfigurationKey(key);
+        return new ParameterTypeSelector({
+            key,
+            description: '',
+            required: false,
+            default: undefined,
+        });
+    },
+};

package/dist/parameter-types.d.ts

@@ -0,0 +1,26 @@
+import type { z } from 'zod';
+export type ConfigurationValuePrimitive = string | number | boolean;
+export type ConfigurationValueConstructor = StringConstructor | NumberConstructor | BooleanConstructor;
+export interface ConfigurationParameterDefinitionBase {
+    configurationKey: string;
+    description: string;
+    required: boolean;
+    default: ConfigurationValuePrimitive | undefined;
+}
+export interface SimpleConfigurationParameterDefinition extends ConfigurationParameterDefinitionBase {
+    kind: 'simple';
+    constructor: ConfigurationValueConstructor;
+}
+export interface DirectoryConfigurationParameterDefinition extends ConfigurationParameterDefinitionBase {
+    kind: 'directory';
+    constructor: StringConstructor;
+    requireWritable: boolean;
+    createIfMissing: boolean;
+}
+export interface YamlConfigurationParameterDefinition<TSchema extends z.ZodTypeAny = z.ZodTypeAny> extends ConfigurationParameterDefinitionBase {
+    kind: 'yaml';
+    constructor: StringConstructor;
+    schema: TSchema | undefined;
+}
+export type ConfigurationParameterDefinition = SimpleConfigurationParameterDefinition | DirectoryConfigurationParameterDefinition | YamlConfigurationParameterDefinition;
+//# sourceMappingURL=parameter-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parameter-types.d.ts","sourceRoot":"","sources":["../src/parameter-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpE,MAAM,MAAM,6BAA6B,GACrC,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,oCAAoC;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,2BAA2B,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,WAAW,sCACf,SAAQ,oCAAoC;IAC5C,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,6BAA6B,CAAC;CAC5C;AAED,MAAM,WAAW,yCACf,SAAQ,oCAAoC;IAC5C,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,oCAAoC,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAC/F,SAAQ,oCAAoC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,iBAAiB,CAAC;IAC/B,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,MAAM,gCAAgC,GACxC,sCAAsC,GACtC,yCAAyC,GACzC,oCAAoC,CAAC"}

package/dist/parameter-types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@zamatica/configuration",
+  "version": "0.1.0",
+  "description": "Framework-agnostic runtime configuration registry with builder-pattern parameter definitions, layered resolution (CLI > env > default), directory access checks, and Zod-validated YAML.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zamatica/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/*.tsbuildinfo",
+    "!**/*.spec.*",
+    "!**/*.test.*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoobroker/zamatica-libs.git",
+    "directory": "libs/configuration"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zamatica/util": "workspace:^",
+    "tslib": "^2.3.0",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  }
+}

package/src/configuration-service.ts

@@ -0,0 +1,333 @@
+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,
+  type ConfigurationLogger,
+  ConsoleLogger,
+  flushBuffer,
+} from './logger.js';
+import type {
+  ConfigurationParameterDefinition,
+  ConfigurationValuePrimitive,
+  DirectoryConfigurationParameterDefinition,
+} from './parameter-types.js';
+
+const CONFIG_BASE_DIR_KEY = 'CONFIGURATION_BASE_DIRECTORY';
+
+export class ConfigurationService {
+  private static appEnvVarPrefix = '';
+  private static cliArgs: Record<string, ConfigurationValuePrimitive | undefined> = {};
+  private static buffer = new BufferingLogger();
+  private static loggerImpl: ConfigurationLogger = ConfigurationService.buffer;
+
+  private static readonly registry = new Map<string, ConfigurationParameterDefinition>();
+  private static readonly registryByTarget = new Map<string, ConfigurationParameterDefinition[]>();
+
+  private static readonly resolvedDirectories = new Map<string, string>();
+  private static readonly resolvedYaml = new Map<string, unknown>();
+
+  private static initialized = false;
+
+  private constructor() {
+    /* static-only */
+  }
+
+  static setAppEnvVarPrefix(prefix: string): void {
+    ConfigurationService.appEnvVarPrefix = prefix.toUpperCase();
+  }
+
+  static getAppEnvVarPrefix(): string {
+    return ConfigurationService.appEnvVarPrefix;
+  }
+
+  static setCliArgs(args: Record<string, ConfigurationValuePrimitive | undefined>): void {
+    ConfigurationService.cliArgs = { ...args };
+  }
+
+  static setLogger(logger: ConfigurationLogger): void {
+    if (ConfigurationService.loggerImpl === ConfigurationService.buffer) {
+      flushBuffer(ConfigurationService.buffer, logger);
+    }
+    ConfigurationService.loggerImpl = logger;
+  }
+
+  static useConsoleLogger(): void {
+    ConfigurationService.setLogger(new ConsoleLogger());
+  }
+
+  static register(
+    parameters: ConfigurationParameterDefinition[],
+    target: string,
+  ): void {
+    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(): void {
+    const errors: string[] = [];
+    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(): boolean {
+    return ConfigurationService.initialized;
+  }
+
+  static get<T extends ConfigurationValuePrimitive>(configurationKey: string): T {
+    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: ConfigurationValuePrimitive | undefined;
+    let source: 'cli' | 'env' | 'default' | undefined;
+
+    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 as unknown as T;
+    }
+
+    ConfigurationService.loggerImpl.debug(
+      `[configuration] '${configurationKey}' resolved from ${source}: ${String(raw)}`,
+    );
+
+    return ConfigurationService.coerce(raw, parameter) as T;
+  }
+
+  static resolveDirectory(configurationKey: string): string {
+    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<string>(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<TResult = unknown>(configurationKey: string): TResult {
+    const cached = ConfigurationService.resolvedYaml.get(configurationKey);
+    if (cached !== undefined) return cached as TResult;
+
+    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<string>(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) as unknown;
+
+    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 as TResult;
+    }
+
+    ConfigurationService.loggerImpl.warn(
+      `[configuration] no schema provided for YAML key '${configurationKey}'; returning unvalidated parsed data.`,
+    );
+    ConfigurationService.resolvedYaml.set(configurationKey, parsed);
+    return parsed as TResult;
+  }
+
+  static getRegistry(): readonly ConfigurationParameterDefinition[] {
+    return Array.from(ConfigurationService.registry.values());
+  }
+
+  static getRegistryByTarget(): ReadonlyMap<string, readonly ConfigurationParameterDefinition[]> {
+    return new Map(
+      Array.from(ConfigurationService.registryByTarget.entries()).map(([target, params]) => [
+        target,
+        params.slice(),
+      ]),
+    );
+  }
+
+  static environmentVariableName(configurationKey: string): string {
+    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(): void {
+    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;
+  }
+
+  private static coerce(
+    value: ConfigurationValuePrimitive,
+    parameter: ConfigurationParameterDefinition,
+  ): ConfigurationValuePrimitive {
+    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);
+    }
+  }
+
+  private static ensureDirectoryAccess(
+    resolved: string,
+    parameter: DirectoryConfigurationParameterDefinition,
+  ): void {
+    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/src/decorators.ts

@@ -0,0 +1,42 @@
+import { ConfigurationService } from './configuration-service.js';
+import type { ConfigurationParameterDefinition } from './parameter-types.js';
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+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 function Configuration(
+  nameOrFirstParameter: string | ConfigurationParameterDefinition,
+  ...rest: ConfigurationParameterDefinition[]
+): (target: AnyClass) => void {
+  const explicitName =
+    typeof nameOrFirstParameter === 'string' ? nameOrFirstParameter : undefined;
+  const parameters: ConfigurationParameterDefinition[] =
+    explicitName === undefined
+      ? [nameOrFirstParameter as ConfigurationParameterDefinition, ...rest]
+      : rest;
+  return (target: AnyClass) => {
+    ConfigurationService.register(parameters, explicitName ?? target.name);
+  };
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+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';

package/src/logger.ts

@@ -0,0 +1,67 @@
+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 class ConsoleLogger implements ConfigurationLogger {
+  debug(message: string, ...args: unknown[]): void {
+    console.debug(message, ...args);
+  }
+  info(message: string, ...args: unknown[]): void {
+    console.info(message, ...args);
+  }
+  warn(message: string, ...args: unknown[]): void {
+    console.warn(message, ...args);
+  }
+  error(message: string, ...args: unknown[]): void {
+    console.error(message, ...args);
+  }
+}
+
+export class BufferingLogger implements ConfigurationLogger {
+  private readonly entries: BufferedLogEntry[] = [];
+
+  debug(message: string, ...args: unknown[]): void {
+    this.append('debug', message, args);
+  }
+  info(message: string, ...args: unknown[]): void {
+    this.append('info', message, args);
+  }
+  warn(message: string, ...args: unknown[]): void {
+    this.append('warn', message, args);
+  }
+  error(message: string, ...args: unknown[]): void {
+    this.append('error', message, args);
+  }
+
+  private append(level: LogLevel, message: string, args: unknown[]): void {
+    this.entries.push({ level, message, args, timestamp: new Date() });
+  }
+
+  drain(): readonly BufferedLogEntry[] {
+    const drained = this.entries.slice();
+    this.entries.length = 0;
+    return drained;
+  }
+
+  size(): number {
+    return this.entries.length;
+  }
+}
+
+export function flushBuffer(buffer: BufferingLogger, target: ConfigurationLogger): void {
+  for (const entry of buffer.drain()) {
+    target[entry.level](entry.message, ...entry.args);
+  }
+}