precedence ordered config with configurable inputs
Last updated 2 months ago by from-nibly .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @fromnibly/config 
SYNC missed versions from official npm registry.


A precedence ordered config management library with configurable inputs.


No need to install typescript types. They are included in this repository.

npm install --save @fromnibly/config

Getting Started

To start you need to create a PropertyDatabase. The PropertyDatabase is the main object you will interact with.

import { PropertyDatabase } from '@fromnibly/config';

let config = new PropertyDatabase();

By default the property database is not configured with any PropertyLoaders. @fromnibly/config includes a couple of default property loaders you can configure your property database with.

import { EnvironmentPropertyLoader, FilePropertyLoader } from '@fromnibly/config';

  .withPropertyLoader(new EnvironmentPropertyLoader(process.env))
  .whichOverrides(new FilePropertyLoader('./config'));

You can make your own PropertyLoaders as well. the EnvironmentPropertyLoader is a good example to get you started.

Once you have configured your property loaders you need to load the properties. Since property loaders can be async the loadProperties() call is also async.

  .then(() => /* start your app */)
  .catch((err) => /* something went wrong */);

// or

await config.loadProperties();

Getting A Configuration Property

Once your properties are loaded the property sources will be merged, flattened, lowercased and dot delimited. As an example the following property sources...

  http.port: 8080
    port: 443
  level: 'info'
export SERVER_HTTP_HOST=localhost

...will result in the following properties being set


and can be retrieved in the following ways.

let httpsPort = config.get('server.https.port').asNumber();
let logLevel = config.get('logger.level').asString();
let httpConfig = config.get('server.http').asObject();


currently all leaf properties returned by .asObject() will be strings.

Default values

Calling asString(), asNumber() or asObject() will throw an exception if the property is not set. This is to prevent your app from starting without all of the properties set. Although defaults can often be packged with your app in something like an application.yml file you can also call any of these with a default value like so.

let httpsPort = config.get('server.https.port').asNumber(8080);
let logLevel = config.get('logger.level').asString('debug');
// Because this call normally returns string leaf nodes
// you should return strings and cast to numbers later.
let httpConfig = config.get('server.http').asObject({ port: '8080' });


You can also check if the property is set before trying to cast it.

let cert = config.get('server.https.cert');
if (cert.isSet()) {
  // start https server
} else {
  // start http server

Advanced Deserialization

You can add property mappers to customize how properties are inflated.

Either on the fly like this:

let convertToNumberObject = obj => {
  if (obj.port) {
    return { port: parseInt(obj.port) };
  } else {
    return {};
let httpConfig = config.get('server.http').asMapped(convertToNumberObject);
// { port: 8080 }

or set at load time like this:

config.registerMapper('server.http', convertToNumberObject);


You can also convert maps to arrays with asMappedArray.

    type: file
    filePath: /mnt/backup
    type: google-drive
    url: https://drive.google.com
    secret: '*****'
let backups = config.get('backups').asMappedArray((name: string, obj: any) => {
  return {
// [ { name: 'disk', type: 'file', ...}, { name: 'cloud', type: 'google-drive', ...}]


Profiles allow you to scope different properties. Profiles must be supported by the individual PropertyLoader. For instance the FilePropertyLoader loads properties to a profile based on the name of the file ie. application-dev.yml would be given the dev profile. Using profiles limits when properties from certain sources become available. You set which properties should be loaded when creating the PropertyDatabase.

let config = new PropertyDatabase(['dev', 'local']);

However it is not really useful to hard code the profiles. Something like this is usually a good idea.

let config = new PropertyDatabase(process.env['CONFIG_PROFILES'].split(','));

Properties in profiles specified later in the array will overwrite properties in profiles specified earlier in the array.

Included PropertyLoaders


The EnvironmentPropertyLoader turns environment vaiables into properties by lowercasing, and dot delimiting them.


The FilePropertyLoader supports json, yaml, and java properties files. It looks for files recursively in the root folder configured that are named application-<profile>.<ext>, or application.<ext> for profile-less files.

Current Tags

  • 1.9.0                                ...           latest (2 months ago)

18 Versions

  • 1.9.0                                ...           2 months ago
  • 1.8.2                                ...           4 months ago
  • 1.8.1                                ...           6 months ago
  • 1.8.0                                ...           6 months ago
  • 1.7.4                                ...           6 months ago
  • 1.7.3                                ...           6 months ago
  • 1.7.2                                ...           6 months ago
  • 1.7.1                                ...           7 months ago
  • 1.7.0                                ...           7 months ago
  • 1.6.0                                ...           7 months ago
  • 1.5.1                                ...           8 months ago
  • 1.5.0                                ...           8 months ago
  • 1.4.0                                ...           8 months ago
  • 1.3.1                                ...           9 months ago
  • 1.3.0                                ...           9 months ago
  • 1.2.0                                ...           9 months ago
  • 1.1.0                                ...           9 months ago
  • 1.0.2                                ...           9 months ago
Maintainers (1)
Today 0
This Week 0
This Month 39
Last Day 0
Last Week 36
Last Month 2
Dev Dependencies (3)
Dependents (0)

Copyright 2014 - 2017 © taobao.org |