Skip to content

Latest commit

 

History

History
345 lines (241 loc) · 12.5 KB

README.md

File metadata and controls

345 lines (241 loc) · 12.5 KB

node-etc

Configuration loader for node.js applications.

Build Status

Idea

Your application probably needs to load configuration from multiple sources and make them available as one object. Etc is here to help!

Etc provides a fairly complete API for loading configuration from a variety of sources, however, its been engineered to easily load config from (in order of precedence): argv, environment, files in /etc/, package.json, and defaults.

Etc. also allows you to edit and save your configuration.

When relative path is supplied for fileName in any of the functions, the file is looked for in (order) in:

  1. the cwd path moving down one level till it is found
  2. /etc/${appName}
  3. ~/etc/${appName}
  4. {projectRoot}/etc
  5. {projectRoot}/.etc
  6. {projectRoot}/config
  7. {projectRoot}/config

Preparatory

Remember to change cwd to the root of your application so node-etc does not fail for global packages. Do this by setting the following in you entry js file

process.chdir(__dirname);

Examples

Create configuration

const conf = require('node-etc');

// supply absolute path. If script is not run as sudo, the file will be created in ~/etc/${appName}/conf.yaml
const appName = conf.packageJson().name
conf.createConfig(`/etc/${appName}/conf.yaml`);

// filename supplied. creates config file in root directory of your project
conf.createConfig('conf2.yaml');

Get Root Directory of Your project

const conf = require('node-etc');

const rootDir = conf.projectRoot()
console.log(rootDir)

read package.json

const conf = require('node-etc');

// from current project
conf.packageJson();

// from absolute path
conf.packageJson('/home/brian/Code/CSECO/csycms'); // will read /home/brian/Code/CSECO/csycms/package.json

// from /etc/ ~/etc
conf.packageJson('CSECO'); // will read /etc/${appName}/CSECO/package.json or ~/etc/${appName}/CSECO/package.json

read json file

const conf = require('node-etc');

// from absolute path
let output = conf.parseJSON('/home/brian/Code/CSECO/csycms'); // will read /home/brian/Code/CSECO/csycms.json
console.log(output)
// from /etc/ ~/etc
output = conf.parseJSON('CSECO'); // will read /etc/${appName}/CSECO.json or ~/etc/${appName}/CSECO.json
console.log(output)

read yaml file

const conf = require('node-etc');

// from absolute path
let output = conf.parseYAML('/home/brian/Code/CSECO/csycms'); // will read /home/brian/Code/CSECO/csycms.yaml/.yml
console.log(output)
// from /etc/ ~/etc
output = conf.parseYAML('CSECO'); // will read /etc/${appName}/CSECO.json or ~/etc/${appName}/CSECO.yaml/.yml
console.log(output)

add values to configuration

const conf = require('node-etc');

conf.addConfig('yaml', '/etc/node-etc/conf.yaml', { Field: "value", Ta: "bitha" }));
conf.addConfig('env', '/etc/node-etc/.env', { Field: "value", Ta: "bitha" }));

Load configuration from argv, env, a file, and defaults.

const conf = require('node-etc');

// read package.json
conf.packageJson('/home/brian/Code/CSECO/csycms');
conf.packageJson('CSECO');
conf.packageJson();


conf.argv());

// read all enviroment values
conf.env());

// read from yaml
conf.parseYAML('/etc/node-etc/conf.yml');
conf.parseYAML('conf.yml');
conf.parseYAML();

// read all possible configuration files from directory
conf.directory('/etc/node-etc');

API

Refer to the documentation

etc

Kind: global class

new etc()

constructor

etc.createConfig(filePath)

create configuration file in filePath if it does not exists

Kind: instance method of etc

Param Type Description
filePath string with the extensions [.json

etc.packageJson([dir]) ⇒ object

Read package.json [1] of current project or [2] from any other location. If relative path is supplied for dir such as package.json or node-etc/package.json(=node-etc), the file will we looked for in [1] the cwd path moving down one level till it is found, [2] in /etc/${appName}, [3] in ~/etc/${appName}, [4] {projectRoot}/etc, [5] {projectRoot}/.etc, [6] {projectRoot}/config, [7] {projectRoot}/config

Kind: instance method of etc
Returns: object - - Returns json object found or empty object

Param Type Default Description
[dir] string "'package.json'" Either absolute or relative path, with/without package.json at the end.

etc.projectRoot() ⇒ string

Get the root dir of current project by locating package.json

Kind: instance method of etc
Returns: string - - project root directory

etc.parseJSON(filePath) ⇒ object

Read json file

Kind: instance method of etc
Returns: object - - Returns json object found or empty object

Param Type Description
filePath string relative or absolute path of file to read. If relative path is supplied for dir such as package.json or node-etc/package.json(=node-etc), the file will we looked for in [1] the cwd path moving down one level till it is found, [2] in /etc/${appName}, [3] in ~/etc/${appName}, [4] {projectRoot}/etc, [5] {projectRoot}/.etc, [6] {projectRoot}/config, [7] {projectRoot}/config

etc.argv() ⇒ object

return command line arguments

Kind: instance method of etc
Returns: object - - Returns object containing command line arguments

etc.directory(dir) ⇒ object

read configuration from .yaml/.yml, .env and json files in given directory.

Kind: instance method of etc

Param Type Description
dir string absolute path of directory

etc.parseYAML([filePath]) ⇒ object

Read yaml file

Kind: instance method of etc
Returns: object - - Returns json object found or empty object

Param Type Default Description
[filePath] string "'conf'" relative or absolute path of file to read, with either .yaml/.yml extension or without. If argument supplied is file.yaml, but file.yml is found instead, file.yml will be returned. If relative path is supplied for filePath such as config.yaml or node-etc/config.yaml(=node-etc/config), the file will we looked for in [1] the cwd path moving down one level till it is found, [2] in /etc/${appName}, [3] in ~/etc/${appName}, [4] {projectRoot}/etc, [5] {projectRoot}/.etc, [6] {projectRoot}/config, [7] {projectRoot}/config

etc.env([dir]) ⇒ object

Loads environment variables from a .env file in either [1] current project or [2] from any other location and returns process.env. If dir is not supplied, the function moves up the directories in the cwd path and returns the first .env file found. If absolute path is not given for dir, it also loads .env from /etc/{dir}. If dir is not given, it is taken as the program name as contained in the package.json file in the root directory of the project.

Kind: instance method of etc
Returns: object - - Returns json object found or empty object

Param Type Default Description
[dir] string "''" directory name from which to read .env file. Can be either a directory name or absolute path of directory

etc.getFilePath(configType, fileName)

Get filepath if file with given name exists in: [1] the cwd path moving down one level till it is found [2] /etc/${appName} [3] ~/etc/${appName} [4] {projectRoot}/etc [5] {projectRoot}/.etc [6] {projectRoot}/config [7] {projectRoot}/config

Kind: instance method of etc

Param Type
configType 'json' | 'yaml' | 'yml' | 'env'
fileName string

etc.readConfigData(configType, filePath, config)

readConfiguration of configType from given path

Kind: instance method of etc

Param Type Description
configType 'json' | 'yaml' | 'yml' | 'env'
filePath string filename with/without extension/ absolute path
config object

etc.addConfig(configType, filePath, config)

Add new values to config/modify existing ones

Kind: instance method of etc

Param Type Description
configType 'json' | 'yaml' | 'yml' | 'env'
filePath string filename with/without extension/ absolute path
config object

etc.deleteConfig(configType, filePath, config)

Delete values from config

Kind: instance method of etc

Param Type Description
configType 'json' | 'yaml' | 'yml' | 'env'
filePath string filename with/without extension/ absolute path
config array fields to remove

etc.editConfig(configType, filePath, config)

Add new values to config/modify existing ones

Kind: instance method of etc

Param Type Description
configType 'json' | 'yaml' | 'yml' | 'env'
filePath string filename with/without extension/ absolute path
config object

etc.save(configType, filePath, config)

Save config values

Kind: instance method of etc

Param Type Description
configType 'json' | 'yaml' | 'yml' | 'env'
filePath string absolute path
config array fields to save

etc.all()

Load all configurations

Kind: instance method of etc

Credits

Inspired by cpsubrian/node-etc

Developed by CSECO

CSECO is a mechatronics firm specializing in engineering technology to be cheap enough to be affordable to low income earners.

http://www.cseco.co.ke