source-configs
v0.3.6
Published
A Node.js module that harvests app-level config values from command line arguments, environment variables, or config files based on a config schema you define within your app.
Downloads
998
Readme
source-configs
A Node.js module that harvests app-level config values from command line arguments, environment variables, or config files based on a config schema you define within your app. This module was built and is maintained by the Roosevelt web framework team, but it can be used independently of Roosevelt as well.
By default configs matching a given schema are sourced from the following locations in the following order of precedence:
- Command line argument set in the schema via
commandLineArg
. - Environment variable set in the schema via
envVar
. - Deployment config file declared via:
- Command line argument:
--deploy-config-file
or--df
. - Environment variable:
DEPLOY_CONFIG
. - package.json as a
deployConfig
field.
- Command line argument:
- Default defined in the schema.
Usage
First declare source-configs
as a dependency in your app.
Then create a config schema JSON object to tell source-configs
what config values to listen for.
Here's a simple example declaring that our application will use a WebSocket with a configurable host, port, and protocol:
// your-schema-js-file.json
{
websocket: {
host: {},
port: {},
protocol: {}
}
}
Schema metadata
Schemas support the following metadata for each configurable property in order to create constraints if desired or add additional functionality:
description
[String]: Describe what this config will be used for.default
[any]: Set a default value for this config. If not set, the default is null.values
[Array]: Enumerated list of values that are valid. If not set, any value will be valid.commandLineArg
[String|Array]: Command line argument(s) to listen for that will set this config. If not set, source-configs will not listen for command line arguments to set the value for this config.envVar
[String|Array]: Environment variable(s) to listen for that will set this config. If not set, source-configs will not listen for an environment variable to set the value for this config.
User-defined functions
Additionally, a schema can be a function which has the parent config passed to it as the first argument. To do this create a key/value pair within the schema object:
- If the schema is stored in a
.js
file, set the key as the desired function name and the value as the function. - If using a
.json
file to store the schema, set the key as the desired function name and the value as'user defined function'
. Once the.json
file is required in, override the key's value with the desired function.
Below is a more complex WebSocket config example leveraging all of the above metadata options:
// your-schema-js-file.json
{
websocket: {
host: {
description: 'WebSocket host URL',
default: 'localhost',
commandLineArg: ['--websocket-host-url', '--ws-host', '-h'],
envVar: ['WEBSOCKET_HOST_URL', 'WS_HOST']
},
port: {
description: 'WebSocket port',
default: 8081,
commandLineArg: ['--ws-port', '-p'],
envVar: 'WS_PORT'
},
protocol: {
description: 'Which WebSocket protocol',
values: ['ws', 'wss'],
commandLineArg: '--ws-protocol',
envVar: 'WS_PROTOCOL'
},
url: 'user defined function'
}
}
Use in your app
Here's an example usage of source-configs using the schema defined above:
const sourceConfigs = require('source-configs')
const schema = require('./your-schema-js-file.json')
schema.websocket.url = function (config) {
return config.protocol + '://' + config.host + ':' + config.port
}
const config = sourceConfigs(schema)
// access one of the configs
console.log(config.websocket.port)
Custom configuration
In addition to the above instantiation method, source-configs also accepts an optional configuration object that can be passed to the constructor as a second object like so:
const sourceConfigs = require('source-configs')
const schema = require('./your-schema-js-file.json')
const config = sourceConfigs(schema, {
logging: true,
sources: [
'command line',
'environment variable',
'deploy config',
{ custom: 'object' }
]
})
Available parameters
logging
: Whether or not source-configs will log to console.- Default: [Boolean]
true
.
- Default: [Boolean]
sources
: An array of sources that can be a mix of built-in sources and custom source objects in order of priority.Default [Array]:
'command line', 'environment variable', 'deploy config'
Note: built-in sources can also be referenced in multiple ways:
- Command line:
command line
orcommandLineArg
. - Environment variable:
environment variable
orenvVar
- Deploy config:
deploy config
ordeployConfig
- Command line:
You can also add custom sources this way by supplying an object to this array:
'command line', 'environment variable', { custom: 'object' }
- In this example
deploy config
is ommitted from the list of sources and a custom object is the last item to source from before defaults.
- In this example
transform
: A function that can be used to mutate your config after it has been parsed and sourced but before it gets returned by source-configs.Example:
const sourceConfigs = require('source-configs') const schema = require('./your-schema-js-file.json') const config = sourceConfigs(schema, { transform: (config, commandLineArgs) => { // check for a cli flag that wouldn't normally translate into a config if (commandLineArgs.switchPort === true) { config.websocket.port = 43711 } // return the config when done return config } }) // access that config configs console.log(config.websocket.port) //=> 43711
API:
transform(config, commandLineArgs)
: Config transform method.config
: The config after being parsed by source-configs.commandLineArgs
: CLI flags as parsed by yargs-parser.
Properties of source-configs module
In addition to its constructor, source-configs exposes the following properties:
configs
[Object]: The resulting configs after running source-config's constructor.commandLineArgs
[Array]: All command line arguments passed to your application, including those not listened for by your schema. Powered by yargs-parser.yargsParser
[Function]: The instance of yargs-parser that source-configs used to compile all command line arguments passed to your application.printHelp
[Function]: A function which will generate a help menu describing the command line arguments defined in the schema. Useful for if you want to define a-h
or--help
command line argument to print all available supported command line arguments. Just printconsole.log(config.printHelp())
to print that information to your users.