npm package: @srcer/config
Description: Option-setting quickstart for Node libraries
Latest version: 1.1.3

# Srcer Config

![Test Status](https://img.shields.io/github/workflow/status/srcer/config/Build)
![Version](https://img.shields.io/npm/v/@srcer/config)
![License](https://img.shields.io/npm/l/@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
-------
```console
npm install @srcer/config
```

Include
-------
```javascript
const Config = require('@srcer/config');
```

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

```javascript
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:

```javascript
    class MyClass extends Config {
        constructor(options) {
            super(options, 'my-file');
        }
    }
```    
*Or:*
```javascript
     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:

```javascript
    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.