Dymexjs/config

Dymexjs stands for DYnamic, Modular, EXtensible JavaScript/Typescript framework.

Configuration system that allows the use of multiple providers, with support for validation.

• Dymexjs/config
  • Instalation
  • Basic Usage
  • Description
    • Types
      • ConfigSourceOptions
      • ValidatorFunc
      • IConfiguration
      • TConfiguration
    • Functions ConfigurationBuilder
      • addEnvVariablesConfiguration
      • addInMemoryConfiguration
      • addJsonFileConfiguration
      • addJsFileConfiguration
      • addUserSecretsConfiguration
      • addEnvFileConfiguration
    • Configuration
      • get
      • has
      • set
      • getSection
      • getRequiredSection
  • Advanced Usage
  • Code of Conduct
  • How to Contribute
  • License 📝
  • Contributors ✨

Instalation

npm install --save @dymexjs/config

Basic Usage

import { ConfigurationBuilder } from "@dymexjs/config";
import { env } from "process";

env.test_ENV = "test";
env.test_VARIABLES = "test";
env.test2_PORT = "3000";

const configBuilder = new ConfigurationBuilder();
//import variables from 'env' based on prefix
configBuilder.addEnvVariablesConfiguration(["test_", "test2_"]);
configBuilder.addInMemoryConfiguration({ MEMORY: "test" });
// { JSON: "test" }
configBuilder.addJsonFileConfiguration("env.json");
// export default { JS: "test" }
configBuilder.addJsFileConfiguration("env.js");
// { USER_SECRETS: "test" }
configBuilder.addUserSecretsConfiguration("id", "env.json");
// ENVFILE=test
configBuilder.addEnvFileConfiguration(".env");

const config = await configBuilder.build();
console.log(config.configuration);
/*
    {
        test_ENV: "test",
        test_VARIABLES: "test",
        MEMORY: "test",
        JSON: "test",
        JS: "test",
        USER_SECRETS: "test",
        ENVFILE: "test",
        test2_PORT: "3000",
    }
*/
console.log(config.get("JSON"));
// test

Description

Types

ConfigSourceOptions

type ConfigSourceOptions = {
  expandVariables?: boolean; // default: true
  validation?: ValidatorFunc;
};

expand variables allows for the transformation of values like db://${user}:${password}@${host} into something like db://username:password@localhost depending that the keys used are already loaded into the configuration, see Advanced Usage

ValidatorFunc

type ValidatorFunc = (
  config: TConfiguration,
) => Promise<TConfiguration | IConfiguration>;

IConfiguration

interface IConfiguration {
  configuration: TConfiguration;
  get<T>(key: string): T | undefined;
  has(key: string): boolean;
  set(key: string | TConfiguration, value?: unknown): void;
  getSection(key: string): IConfiguration;
  getRequiredSection(key: string): IConfiguration;
}

TConfiguration

type TConfiguration = {
  [key: string]: string | number | boolean | TConfiguration;
};

Functions ConfigurationBuilder

addEnvVariablesConfiguration

Loads variables from peocess.env based on the prefix(es) passed into the function

Note: If the prefix is empty then all the process.env variables will be loaded.

    addEnvVariablesConfiguration(
        prefix?: string | Array<string>,
        options?: ConfigSourceOptions,
    ): ConfigurationBuilder;

addInMemoryConfiguration

Adds an object of key:value pairs to the configuration

addInMemoryConfiguration(
            config: TConfiguration | IConfiguration,
            options?: ConfigSourceOptions,
        ): ConfigurationBuilder

addJsonFileConfiguration

Adds key:value pairs from a json file to the configuration

addJsonFileConfiguration(path: PathLike, options?: ConfigSourceOptions): ConfigurationBuilder

addJsFileConfiguration

Adds key:value pairs from a js file to the configuration

addJsFileConfiguration(path: PathLike, options?: ConfigSourceOptions): ConfigurationBuilder

addUserSecretsConfiguration

Adds key:value pairs from a user secrets file (json) to the configuration

addUserSecretsConfiguration(id: string, path?: PathLike, options?: ConfigSourceOptions): ConfigurationBuilder

This is a special method to load a file not present in the repository of the application to allow for the setup of configuration properties private to the user.

The id should represent a unique id defined for the application.

If the path is defined then that will be the path used for loading the file, if not the method will try to find a file in

const p = env.HOME || env.home || env.appdata || env.userprofile;
path = join(p, ".config", id, "secrets.json");

addEnvFileConfiguration

Adds key:value pairs from a .env file to the configuration

addEnvFileConfiguration(path: PathLike, options?: ConfigSourceOptions): ConfigurationBuilder

Configuration

get

Returns the value associated with the given key.

If the key is not present returns the default value.

get<T>(key: string): T | undefined

has

Checks if the configuration has a value associated with the given key.

has(key: string): boolean

set

Sets the value associated with the given key.

If the key is an object it will be merged with the current configuration.

If the key is a string with a dot (.) it will be interpreted as a path and the value will be set at the corresponding path in the configuration.

If the key is a string without a dot it will be interpreted as a direct property of the configuration object.

set(key: string | TConfiguration, value?: unknown): void

getSection

Gets a section of the configuration based on the provided key.

getSection(key: string): IConfiguration

getRequiredSection

Gets a section of the configuration based on the provided key, throws an error if the section is not found.

getRequiredSection(key: string): IConfiguration

Advanced Usage

import { ConfigurationBuilder } from "@dymexjs/config";
import { env } from "process";

env.test_ENV = "test";
env.test_VARIABLES = "test";
const configBuilder = new ConfigurationBuilder();
configBuilder.addEnvVariablesConfiguration("test_");
configBuilder.addInMemoryConfiguration({
  MEMORY: "test",
  MEMORY_ENV: "${test_ENV}",
  MEMORY_JSON: "memory",
});
/*
{
    JSON: "test",
    JSON_ENV: "${MEMORY_JSON}",
    JSON_JS: "json",
    JSON_PASSWORD: "password",
}
*/
configBuilder.addJsonFileConfiguration("env.json");
/*
{
    JS: "test",
    JS_ENV: "${JSON_JS}",
    JS_USER: "user",
    "JS_MONGO.DB.URI": "mongodb://${JS_USER}:${JSON_PASSWORD}@localhost:27017/test",
}
*/
configBuilder.addJsFileConfiguration("env.js");
/*
{
    USER_SECRETS: "test",
    USER_ENV: "${JS_USER}",
    USER: "envfile",
    KEY1: { KEY2: "${JS_USER}" },
    MONGODB: "${JS_MONGO.DB.URI}",
}
*/
configBuilder.addUserSecretsConfiguration("id", "env.json");
/*
ENVFILE=test
test_ENV=development
FILE_ENV=${USER}
MULTI_LINE="This is
a multi line
string"
*/
configBuilder.addEnvFileConfiguration(".env");

const config = await configBuilder.build();
console.log(config.configuration);
/*
{
    test_ENV: "development",
    test_VARIABLES: "test",
    MEMORY: "test",
    MEMORY_ENV: "test",
    MEMORY_JSON: "memory",
    JSON: "test",
    JSON_ENV: "memory",
    JSON_JS: "json",
    JSON_PASSWORD: "password",
    JS: "test",
    JS_ENV: "json",
    JS_USER: "user",
    USER_SECRETS: "test",
    USER_ENV: "user",
    USER: "envfile",
    ENVFILE: "test",
    FILE_ENV: "envfile",
    KEY1: { KEY2: "user" },
    JS_MONGO: {
        DB: {
            URI: "mongodb://user:password@localhost:27017/test",
        },
    },
    MONGODB: "mongodb://user:password@localhost:27017/test",
    MULTI_LINE: "This is\na multi line\nstring",
}
*/

console.log(config.get("USER_ENV"));
// "user"

console.log(config.get("JS_MONGO.DB.URI"));
// "mongodb://user:password@localhost:27017/test"

config.set("new.property", "value");

console.log(config.get("new.property"));
// "value"

Code of Conduct

We expect everyone to abide by our Code of Conduct. Please read it.

How to Contribute

Check out our Contributing Guide for information on contributing.

License 📝

Licensed under the MIT License.

Contributors ✨

This project follows the all-contributors specification. Contributions of any kind welcome!