Srcer Config

Option-setting quickstart for Node libraries. Combine passed-in object parameters with config files and default settings in whichever order you choose.

Install

npm install @srcer/config

Include

const Config = require('@srcer/config');

Usage

Call Config.import statically and pass in any object or class instance as the first parameter:

let options = {
    count: 12,
    state: 'off',
    title: 'Config'
}
let myObj = Config.import({}, options, 'my-file');

The resulting myObj would be an object merging the options object with the contents of the my-file.config.js or my-file.config.json file in the project's root if it exists. You can also import settings straight into your class:

    class MyClass extends Config {
        constructor(options) {
            super(options, 'my-file');
        }
    }

Or:

     class MyClass  {
        constructor(options) {
            Config.import(this, options, 'my-file');
        }
    }

Optionally customize the behavior of Srcer Config by passing a settings object as the second parameter rather than a filename string:

    Config.import({}, options, {
        file: 'my-file',
        extension:'ts',
        priority: ['file', 'params', 'defaults']
    });

Settings

1. path
   Default: null
   Path to the config file to be read from and/or written to. If this is set then settings.file, settings.root, and settings.extension will be ignored. Leave all four settings empty if you don't want a config file to be used at all.

2. root Default: process.cwd()
   Root directory of the config file to be read from and/or written to.

3. file (or filename)
   Default: null
   Prefix for the file to be read from and/or written to provided that settings.path is not set. This value will be appended with .config and settings.extension

4. extension(s) (or extension, extensions, ext, exts)
   Default: ['js', 'json']
   A string or an array listing the extensions to look for on the file path formed by the above settings. If this value is an array, the extensions will be looked for in the order of the array. Once a file is found the search is aborted. If no file is found the value of the config file will be {}

5. save Default: false
   If this is set to true, a JSON file reflecting the state of the object after import will be written to the path of the config file. If the original config file had a json extension, it will be overwritten, otherwise the file will be created.

6. defaults (or default)
   Default: {}
   Set default values for any required fields here.

7. valid
   Default: null
   If you want to secure your object and restrict what keys can be added to it, pass an array of the valid keys here and all other keys will be skipped over. If this value is truthy and not an array, the keys from settings.defaults will be used, so be careful not to make this truthy and have no defaults, because then Srcer Config can only return an empty object.

8. priority (or priorities)
   Default: ['params', 'file', 'defaults']
   If this value isn't present, values from the config file will overwrite defaults and values in the passed-in options parameter will overwrite everything. To change that you can pass an array here using the following keys ordered from most to least important:

   • params: the object passed as the first parameter to the Config contructor or Config.import method
   • file: the values retrieved from the config file
   • defaults: the values set in settings.defaults

9. onWrite
   Default: null
   Optionally pass a callback to be called after the new config file is saved. Will only be called if settings.save is true. Parameters passed are settings.path and the object written to file.

10. onEnd
    Default: null
    Optionally pass a callback to be called after config is imported. Generally this will be called before onWrite. The imported object is the only parameter passed.