app-etc

etc

Application configuration.

Installation

$ npm install app-etc

Usage

var etc = require( 'app-etc' );

etc( [options] )

Returns an application configuration.

var config = etc();

The function accepts the following options:

• etc: application configuration directory. Default: ./etc.
• defaultsFile: basename of a file within the application configuration directory which contains default application settings. Default: defaults.
• user: user configuration directory. The default value is determined according to the host OS.
• userFile: basename of a file within the user configuration directory which contains user application settings. The default value is the application name.
• env: application runtime environment. Default: dev.
• envFile: basename of a file within the application configuration directory which maps environment variables to application settings. Default: env.
• order: defines the configuration hierarchy. Default: ['defaults','user','app','env'].

Note: if a file extension is omitted when specifying file basenames, this module will search for the first file having the basename and a supported extension. For supported extensions, see app-etc-load.

Configuration Directory

By default, the application configuration directory is a directory named etc located in the application's root directory. This directory may contain default configuration settings, mappings between environment variables and configuration settings, various application-specific configuration files tailored for different runtime environments, and more. To specify a different directory, set the etc option:

var config = etc({
	'etc': './config'
});

Default Configuration

A defaults file should contain default application configuration settings; e.g., if applicable, a default log level, port, etc. By default, this module looks for a file with the basename defaults. To specify a different basename, set the defaultsFile option:

var config = etc({
	'defaultsFile': 'shared_settings'
});

User Configuration

The user directory option specifies the location of a directory containing user-specific configuration files. The location of this directory is typically OS specific. To specify a directory, set the user option:

var config = etc({
	'user': '/Users/<name>/Library/Preferences'
});

A user file should contain user-specific configuration settings. By default, this module searches for a file having a basename equal to the application name. To specify a different basename, set the userFile option:

var config = etc({
	'userFile': 'configgie.json' 
});

Runtime Configuration

Often different runtime environments require different application configurations. For example, in development, the application may connect to local resources; whereas, in production, the application may connect to various remote endpoints. To handle the different runtimes, applications will utilize environment specific configuration files; e.g., production.json, development.json, test.json, local.json, etc. This module sets the default runtime environment to dev and looks for a corresponding configuration file of the same name in the application configuration directory. To override this option, either set the NODE_ENV environment variable or set the env option:

var config = etc({
	'env': 'local'
});

Runtime environments (e.g., containers) frequently use environment variables for configuration. To map environment variables to configuration settings, this module searches the application configuration directory for a file which maps each environment variable to a particular setting. By default, this module looks for a file having the basename env. To specify a different basename, set the envFile option:

var config = etc({
	'envFile': 'env_mapping'
});

The file contents should include each relevant environment variable and a corresponding setting. For example, a JSON mapping file:

{
	"GITHUB_API_KEY": {
		"keypath": "gKey"
	},
	"DEBUG_LEVEL": {
		"keypath": "logger.level"
	},
	"PORT": {
		"keypath": "server.port",
		"type": "number"
	},
	"SSL_KEY": {
		"keypath": "server.key",
		"type": "string"
	},
	"SSL_CERT": {
		"keypath": "server.cert",
		"type": "string"
}

A TOML mapping file:

# A TOML file which maps environment variables to configuration settings...

[GITHUB_API_KEY]
keypath = "gKey"

# Logger environment variables:
[DEBUG_LEVEL]
keypath = "logger.level"

# Server environment variables:
[PORT]
keypath = "server.port"
type = "number"

[SSL_KEY]
keypath = "server.key"
type = "string"

[SSL_CERT]
keypath = "server.cert"
type = "string"

Notes:

• A configuration setting is specified by a keypath.
• Nested configuration setting keypaths must be . separated.
• A configuration setting type may be specified by providing a type. Possible types include:
  • string (default)
  • number
  • boolean
  • object
• If an environment variable cannot be cast as a specified type, the module will throw an error.
• If an environment variable does not exist, the module skips that variable.

Configuration Hierarchy

Configuration sources are many; e.g., user-specific, application-specific, environment variables, and more. The following sources are supported:

• defaults: default application settings
• user: user-specific settings
• app : application-specific settings
• env: environment variable runtime settings

The order option exists to impose a configuration hierarchy. By default, the hierarchy is

[
	'defaults', // read first
	'user',
	'app',
	'env'       // read last
]

To specify a different order, set the order option:

// Only use application and environment variables as configuration sources...
var config = etc({
	'order': [
		'app',
		'env'
	]
});

etc.parser( extname[, parser] )

Returns a parser for the specified extension.

var parser = etc.parser( '.json' );

Including the . when specifying an extension is optional.

var parser = etc.parser( 'json' );

To support additional file formats or to override a parser, provide a parser function for an associated extension.

var parser = require( 'my-special-fmt-parser' );

etc.parser( '<my-ext>', parser );

Once a parser is set, all configuration instances will parse provided files accordingly.

config.load( './file.<my-ext>' );

For more details, see app-etc-load.

Examples

var path = require( 'path' ),
	etc = require( 'app-etc' );

var config = etc({
	'etc': path.join( __dirname, 'etc' )
});
console.dir( config.get() );
/*
	{
		'server': {
			'port': 8080,
			'address': '127.0.0.1',
			'ssl': false,
			'key': '',
			'cert': ''
		},
		'logger': {
			'level': 'debug'
		},
		'env': 'dev'
	}
*/

To run the example code from the top-level application directory,

$ NODE_ENV=dev PORT=8080 node ./examples/index.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

---

License

MIT license.

Copyright

Copyright © 2015. Athan Reines.