class-configuration v0.5.0

Class-Configuration

The config package to define and read the configuration

Prepare

This package just support Typescript.

You should install reflect-metadata package. And set follow code on tsconfig.json.

// tsconfig.json
{
  "compilerOptions": {
    ...
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    ...
  }
}

Usage

Define a config class

First, You can use @Config define your configuration class. Next, use @ConfigField defined a configuration field.

import 'reflect-metadata';
import { BaseConfig, Config, ConfigField, DefaultValue, FromEnv, init } from 'class-configuration';

@Config()
class Configuration extends BaseConfig {
  /**
   * The server host
   */
  @ConfigField()
  public host!: string;

  /**
   * The server port
   */
  @ConfigField()
  public port!: number;
}

Load config with environment

You can use @FromEnv load config field from environment.

For example:

import 'reflect-metadata';
import { BaseConfig Config, ConfigField, DefaultValue, FromEnv } from 'class-configuration';

process.env.SERVER_HOST = 'localhost';
process.env.SERVER_PORT = '8080';

@Config()
class Configuration extends BaseConfig {
  /**
   * The server host
   */
  @ConfigField()
  @FromEnv('SERVER_HOST')
  public host!: string;

  /**
   * The server port
   */
  @ConfigField()
  @FromEnv('SERVER_PORT')
  public port!: number;
}

// configuration = { "host": "localhost", "port": 8080 }
const configuration = await Configuration.initAsync<Configuration>();

If have no params set, Will use field name.

import 'reflect-metadata';
import { BaseConfig, Config, ConfigField, DefaultValue, FromEnv } from 'class-configuration';

process.env.SERVER_HOST = 'localhost';
process.env.SERVER_PORT = '8080';

@Config()
class Configuration {
  /**
   * The server host
   */
  @ConfigField()
  @FromEnv()  // Will load environment by name 'SERVER_HOST'
  public serverHost!: string;

  /**
   * The server port
   */
  @ConfigField()
  @FromEnv()   // Will load environment by name 'SERVER_PORT'
  public serverPort!: number;
}

// configuration = { "host": "localhost", "port": 8080 }
const configuration = await Configuration.initAsync<Configuration>();

Load config with default value

You can use @DefaultValue load config field by default value.

For example:

import 'reflect-metadata';
import { BaseConfig, Config, ConfigField, DefaultValue, FromEnv } from 'class-configuration';

@Config()
class Configuration extends BaseConfig {
  /**
   * The server host
   */
  @ConfigField()
  @DefaultValue('localhost')
  public host!: string;

  /**
   * The server port
   */
  @ConfigField()
  @DefaultValue(8080)
  public port!: number;
}

// configuration = { "host": "localhost", "port": 8080 }
const configuration = await Configuration.initAsync<Configuration>();

Basic

import 'reflect-metadata';
import { BaseConfig, Config, ConfigField, DefaultValue, FromEnv } from 'class-configuration';

@Config()
class Configuration extends BaseConfig {
  /**
   * The server host
   */
  @ConfigField()
  @FromEnv('SERVER_HOST')
  @DefaultValue('localhost')
  public host!: string;

  /**
   * The server port
   */
  @ConfigField()
  @FromEnv('SERVER_PORT')
  @DefaultValue('8080')
  public port!: number;
}

// configuration = { "host": "localhost", "port": 8080 }
const configuration = await Configuration.initAsync<Configuration>();

Class config

import 'reflect-metadata';
import { BaseConfig, Config, ConfigField, DefaultValue, FromEnv } from 'class-configuration';

@Config()
class Database extends BaseConfig {
  /**
   * The server host
   */
  @ConfigField()
  @FromEnv('SERVER_HOST')
  @DefaultValue('localhost')
  public host!: string;

  /**
   * The server port
   */
  @ConfigField()
  @FromEnv('SERVER_PORT')
  @DefaultValue('8080')
  public port!: number;
}

@Config()
class Configuration {
  /**
   * Database config
   */
  @ConfigField()
  public database!: Database;
}

// configuration = { "database: { "host": "localhost", "port": 8080 } }
const configuration = await Configuration.initAsync<Configuration>();

Customize parser

You can customize a field's parser by @ClassField

@Config()
class DatabaseConfig extends BaseConfig {
  /**
   * Database hosts
   */
  @ConfigField({
    parser: (value) => value.split(','),
  })
  @FromEnv()
  public hosts!: string[];
}

// configuration = { "hosts": ["127.0.0.1", "127.0.0.2"] }
const configuration = await DatabaseConfig.initAsync<DatabaseConfig>();

Notice: This package does not check the type of the return value of the custom parser. If you want change it, please use class-validator.