@travetto/config

Configuration

Configuration support

Install: @travetto/config

npm install @travetto/config

# or

yarn add @travetto/config

The config module provides support for loading application config on startup. Configuration values support the common YAML constructs as defined in yaml. Additionally, the configuration is built upon the Schema module, to enforce type correctness, and allow for validation of configuration as an entrypoint into the application. Given that all @Config classes are @Schema-based classes, all the standard @Schema and @Field functionality applies.

Resolution

The configuration information is comprised of:

• configuration files - YAML, JSON, and basic properties file
• configuration classes Config loading follows a defined resolution path, below is the order in increasing specificity (ext can be yaml, yml, json, properties):

1. resources/application.<ext> - Priority 100 - Load the default application.<ext> if available.
2. resources/{env}.<ext> - Priority 200 - Load environment specific profile configurations as defined by the values of process.env.TRV_ENV.
3. resources/*.<ext> - Priority 300 - Load profile specific configurations as defined by the values in process.env.TRV_PROFILES
4. @Injectable ConfigSource - Priority ??? - These are custom config sources provided by the module, and are able to define their own priorities
5. OverrideConfigSource - Priority 999 - This is for EnvVar overrides, and is at the top priority for all built-in config sources. By default all configuration data is inert, and will only be applied when constructing an instance of a configuration class.

Mono Repo Support

When working in a monorepo, the parent resources folder will also be searched with a lower priority than the the module's specific resources. This allows for shared-global configuration that can be overridden at the module level. The general priority is:

1. Mono-repo root
2. Module root
3. Folders for TRV_RESOURCES, in order

A Complete Example

A more complete example setup would look like:

Config: resources/application.yml

---
database:
  host: localhost
  creds:
    user: test
    password: test

Config: resources/prod.json

{
  "database": {
    "host": "prod-host-db",
    "creds": {
      "user": "admin-user"
    }
  }
}

with environment variables

Config: Environment variables

TRV_ENV = prod

At runtime the resolved config would be:

Terminal: Runtime Resolution

$ trv main doc/resolve.ts

Config {
  sources: [
    {
      priority: 100,
      source: 'file://application',
      detail: 'resources/application.yaml'
    },
    {
      priority: 101,
      source: 'file://application',
      detail: 'module/config/doc/resources/application.yml'
    },
    {
      priority: 300,
      source: 'file://prod',
      detail: 'module/config/doc/resources/prod.json'
    },
    { priority: 999, source: 'memory://override' }
  ],
  active: {
    DBConfig: { host: 'prod-host-db', port: 2000, creds: { user: 'admin-user' } }
  }
}

Standard Configuration Extension

The framework provides two simple base classes that assist with existing patterns of usage to make adding in new configuration sources as easy as possible. The goal here is for the developer to either instantiate or extend these classes and produce a configuration source unique to their needs:

Code: Memory Provider

import { ConfigData } from '../parser/types';
import { ConfigSource, ConfigSpec } from './types';

/**
 * Meant to be instantiated and provided as a unique config source
 */
export class MemoryConfigSource implements ConfigSource {
  #spec: ConfigSpec;

  constructor(key: string, data: ConfigData, priority: number = 500) {
    this.#spec = { data, priority, source: `memory://${key}` };
  }

  get(): ConfigSpec {
    return this.#spec;
  }
}

Code: Environment JSON Provider

import { ConfigSource, ConfigSpec } from './types';

/**
 * Represents the environment mapped data as a JSON blob
 */
export class EnvConfigSource implements ConfigSource {
  #envKey: string;
  #priority: number;

  constructor(key: string, priority: number) {
    this.#envKey = key;
    this.#priority = priority;
  }

  get(): ConfigSpec | undefined {
    try {
      const data = JSON.parse(process.env[this.#envKey] || '{}');
      return { data, priority: this.#priority, source: `env://${this.#envKey}` };
    } catch (e) {
      console.error(`env.${this.#envKey} is an invalid format`, { text: process.env[this.#envKey] });
    }
  }
}

Custom Configuration Provider

In addition to files and environment variables, configuration sources can also be provided via the class itself. This is useful for reading remote configurations, or dealing with complex configuration normalization. The only caveat to this pattern, is that the these configuration sources cannot rely on the ConfigurationService service for input. This means any needed configuration will need to be accessed via specific patterns.

Code: Custom Configuration Source

import { ConfigData, ConfigSource } from '@travetto/config';
import { Injectable } from '@travetto/di';

@Injectable()
export class CustomConfigSource implements ConfigSource {
  priority = 2000;
  source = 'custom://override';

  async getData(): Promise<ConfigData> {
    return { user: { name: 'bob' } };
  }
}

Startup

At startup, the ConfigurationService service will log out all the registered configuration objects. The configuration state output is useful to determine if everything is configured properly when diagnosing runtime errors. This service will find all configurations, and output a redacted version with all secrets removed. The default pattern for secrets is /password|private|secret/i. More values can be added in your configuration under the path config.secrets. These values can either be simple strings (for exact match), or /pattern/ to create a regular expression.

Consuming

The ConfigurationService service provides injectable access to all of the loaded configuration. For simplicity, a decorator, @Config allows for classes to automatically be bound with config information on post construction via the Dependency Injection module. The decorator will install a postConstruct method if not already defined, that performs the binding of configuration. This is due to the fact that we cannot rewrite the constructor, and order of operation matters.

Environment Variables

Additionally there are times in which you may want to also support configuration via environment variables. EnvVar supports override configuration values when environment variables are present.

The decorator takes in a namespace, of what part of the resolved configuration you want to bind to your class. Given the following class:

Code: Database config object

import { Config, EnvVar } from '@travetto/config';

@Config('database')
export class DBConfig {
  host: string;
  @EnvVar('DATABASE_PORT')
  port: number;
  creds: {
    user: string;
    password: string;
  };
}

You can see that the DBConfig allows for the port to be overridden by the DATABASE_PORT environment variable.

Terminal: Resolved database config

$ trv main doc/dbconfig-run.ts

{
  message: 'Failed to construct @travetto/config:doc/dbconfig￮DBConfig as validation errors have occurred',
  category: 'data',
  type: 'ValidationResultError',
  at: '2029-03-14T04:00:00.618Z',
  details: {
    class: '@travetto/config:doc/dbconfig￮DBConfig',
    import: '@travetto/config/doc/dbconfig.ts',
    errors: [
      {
        kind: 'required',
        active: true,
        value: undefined,
        message: 'port is required',
        path: 'port',
        type: undefined
      }
    ]
  }
}

What you see, is that the configuration structure must be honored and the application will fail to start if the constraints do not hold true. This helps to ensure that the configuration, as input to the system, is verified and correct.

By passing in the port via the environment variable, the config will construct properly, and the application will startup correctly:

Terminal: Resolved database config

$ DATABASE_PORT=200 trv main doc/dbconfig-run.ts

Config {
  sources: [
    {
      priority: 100,
      source: 'file://application',
      detail: 'resources/application.yaml'
    },
    {
      priority: 101,
      source: 'file://application',
      detail: 'module/config/doc/resources/application.yml'
    },
    {
      priority: 300,
      source: 'file://prod',
      detail: 'module/config/doc/resources/prod.json'
    },
    { priority: 999, source: 'memory://override' }
  ],
  active: {
    DBConfig: { host: 'prod-host-db', port: 200, creds: { user: 'admin-user' } }
  }
}

Additionally you may notice that the password field is missing, as it is redacted by default.