@travetto/config

Configuration

Configuration support

Install: @travetto/config

npm install @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:

• YAML files
• environment variables
• configuration classes

Config loading follows a defined resolution path, below is the order in increasing specificity:

1. resources/application.yml - Load the default application.yml if available.
2. resources/*.yml - Load profile specific configurations as defined by the values in process.env.TRV_PROFILES
3. resources/{env}.yml - Load environment specific profile configurations as defined by the values of process.env.TRV_ENV.
4. process.env - Read startup configuration from environment to allow for overriding any values. Because we are overriding a YAML based configuration we need to compensate for the differences in usage patterns. Generally all environment variables are passed in as UPPER_SNAKE_CASE. When reading from process.env we will map UPPER_SNAKE_CASE to upper.snake.case, and will attempt to match by case-insensitive name.

By default all configuration data is inert, and will only be applied when constructing an instance of a configuration class. This is due to the fact that environment data, as well as configuration data can only be interpreted in light of a class structure, as the data binding is what makes the configuration valid.

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.yml

--
database:
  host: prod - host - db
  creds:
    user: admin - user

with environment variables

Config: Environment variables

TRV_ENV = prod
TRV_PROFILES = prod
DATABASE_PORT = 1234
DATABASE_CREDS_PASSWORD = %secret%

At runtime the resolved config would be:

Terminal: Runtime Resolution

$ trv main doc/resolve.ts

Config {
  sources: [
    'doc.1 - file:@travetto/config/resources/doc.yml',
    'override.3 - memory://override'
  ],
  active: {
    DBConfig: {
      host: 'localhost',
      port: 2000,
      creds: creds_7_45Ⲑsyn { user: 'test', password: 'test' }
    }
  }
}

Secrets

By default, when in production mode, the application startup will request redacted secrets to log out. These secrets follow a standard set of rules, but can be amended by listing regular expressions under config.redacted.

Consuming

The Configuration 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.

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;
  };
}

Using the above config files, you'll notice that the port is not specified (its only specified in the environment variables). This means when the application attempts to start up, it will fail if the port is not specified via an 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,
  class: '@travetto/config:doc/dbconfig￮DBConfig',
  file: '@travetto/config/doc/dbconfig.ts',
  errors: [
    {
      kind: 'required',
      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: [
    'doc.1 - file:@travetto/config/resources/doc.yml',
    'override.3 - memory://override'
  ],
  active: {
    DBConfig: {
      host: 'localhost',
      port: 200,
      creds: creds_7_45Ⲑsyn { user: 'test', password: 'test' }
    }
  }
}