@dokebi/config

Version 0.4.2 (unpublished). It is installed automatically as a required dependency of @dokebi/core. You never call app.register for it; it loads and checks YAML and prepares each app's read-only configuration. It creates no DB, Redis or NATS connections.

Configuration file

The runtime configuration is a single dokebi.yaml with schemaVersion: 1 and an options object. The app's and the plugins' settings under options are read through core's app.config. For example options.redis.connections.cache and options.redis.connections.coordination keep the settings of two independent connections apart. Each plugin's schema and runtime contract check the actual connection names, references and required values.

Keep the real file out of Git and share only a dokebi.example.yaml without secrets. There is no environment-variable substitution and no file merging, and the example file never replaces the real configuration. Reading the file again while the app runs is core's configuration reload (D-0154), which reads it with readConfigFile as loadConfig does.

Loading explicitly

import { Application, loadConfig } from "@dokebi/core";

const document = await loadConfig("dokebi.yaml");
const app = new Application({ config: document.options });
await app.start();
try {
  app.logger.log("info", "Application started");
} finally {
  await app.stop();
}

loadConfig(path, guard?) returns Promise<ConfigDocument<T>>, and parseConfig(text, guard?) returns the same document without file I/O. An optional type guard checks the real shape of options and lets TypeScript infer the type. You cannot skip the check by giving only a type argument. Constructing an Application never searches the current folder or reads a file. The configuration is readable right after construction and after stop, and it is isolated from later changes to the input object and from other apps.

The factory's app and the context.app of setup/start are the same ApplicationView. It is created once per app, frozen, and offers only state, config, logger and runtime; it has no start, stop, register or get. A plugin gets its options from app.config[<plugin name>].

Checks and limits

YAML is limited to one 1.2 document, 1 MiB, depth 64 and 10,000 nodes. Duplicate keys, anchors, aliases, explicit tags, merge keys and __proto__ are refused; plain constructor and prototype keys are allowed. Finite numbers are allowed, but integers must be JavaScript safe integers (-9007199254740991 to 9007199254740991). Write larger identifiers as quoted strings.

The size of programmatic input is a budget that adds up the UTF-8 length of strings and keys and a cost per node; it is not the same measurement as the file's raw byte limit. Passing the file limits does not mean a plugin's settings are valid for its purpose.

ConfigValidator's check(schema, options) returns an errors array and validate(schema, options) throws ConfigError on a data mismatch. It uses JSON Schema 2020-12 objects with a 128 KiB limit, strict mode, and no external references or async schemas. It never coerces types, injects defaults or removes extra fields. parseSchema(text) and loadSchema(path) read schemas. An invalid schema fails in check too. ConfigValidator({ allErrors?: boolean }) defaults to false.

ConfigError has code, line, column, issues, plugin ('dokebi-config') and fix. The codes are CONFIG_READ_FAILED, CONFIG_LIMIT_EXCEEDED, INVALID_YAML, INVALID_CONFIG, INVALID_OPTIONS_SCHEMA and INVALID_CONFIG_OPTIONS. Diagnostics never include the original values; the original cause is kept only where it holds no configuration value (CONFIG_READ_FAILED: the file system error; INVALID_OPTIONS_SCHEMA: the schema problem; INVALID_YAML from the YAML library: its name and code only). An error that is not the YAML's fault is thrown as it is. issues hold only instancePath and keyword, plus missingProperty (a field name from the schema, never a user value) for required errors. Never print the whole configuration object to a log yourself: it can expose secrets.

It uses yaml 2.9.1 (ISC) and Ajv 8.20.0. This package is MIT licensed and does not depend on core. See the AI guide and the config design notes in the repository.