Sidewinder Config
Type Safe Configurations with Sidewinder Types
Overview
This package enables type safe configuation resolution using Sidewinder Types. It is able to resolve configuration settings from environment variables, command line arguments or json configuration files.
Contents
Example
The following shows general usage. The configuration resolve() function will attempt to resolve configurations from series of resolution passes. The first resolution pass will attempt to resolve from an optional config.json file, the second pass attempts to resolve from environment variables and the final resolution pass attempts to resolve from from command line arguments. Each resolution pass will override the previous values resolved from the last allowing configurations to be partially constructed from a number of sources. If the resulting object fails to match the schematics of the type provided, the process will automatically exit with a non-zero exit code and display help information to the terminal.
import { Type, Configuration } from '@sidewinder/configuration'
// Specify the structure of the configuration expected by the application.
// Types can be optional, or with default values. This type is used to
// source configurations from the environment or command line arguments.
const configuration = Configuration(Type.Object({
port: Type.Integer({ default: 5000 }),
mongo: Type.Object({
host: Type.String()
port: Type.Integer()
}),
redis: Type.Object({
host: Type.String()
port: Type.Integer()
})
}))
// Resolves configurations from command line arguments and environment
// variable or process.exit(1) with error message. If this function
// succeeds then the application can trust the config object is of
// the expected type.
const config = configuration.resolve('config.json')
// const config = {
// port: 5000
// mongo: {
// host: '...',
// port: 6379
// },
// redis: {
// host: '...',
// port: 6379
// }
// }Environment Variables
Environment Variables are sourced from capitalized property names with an underscore _ used to seperate object context. Only JavaScript string, number, boolean values can be sourced from Environment Variable. Consider the following.
// Configurations will be resolved from the process.env object. If using
// libraries such as dotenv to source development, staging and production
// environments, ensure you assign these environment variables prior to
// calling Configuration(...).
process.env.MONGO_HOST = 'localhost'
process.env.MONGO_PORT = '6379'
process.env.PORT = '5000'
const configuration = Configuration(Type.Object({
port: Type.Integer({ default: 5000 }),
mongo: Type.Object({
host: Type.String()
port: Type.Integer()
}),
redis: Type.Object({
host: Type.String()
port: Type.Integer()
})
}))Which will source for the following environment variables.
ENABLED
MONGO_HOST
MONGO_PORT
REDIS_HOST
REDIS_PORTCommand Line Arguments
Command line arguments are sourced from process.argv' using lowercase --prefixed property names with a dash-` used to seperate object context. Only JavaScript string, number, boolean values can be sourced from Environment Variable. Consider the following.
const configuration = Configuration(Type.Object({
port: Type.Integer({ default: 5000 }),
mongo: Type.Object({
host: Type.String()
port: Type.Integer()
}),
redis: Type.Object({
host: Type.String()
port: Type.Integer()
})
}))Which will source from the following environment variables.
$ node index.js --port 5000 --redis-host localhost --redis-port 6379Documentation and Help
In the instance the .resolve() function cannot resolve an object matching the given configuration type, the process will immediately exit with an non-zero exit code and display help documentation giving hints as to what went wrong. Additionally, help information can be displayed by specifying a --help option as a command line argument to the process.
You can specify optional description and default properties for each expected value.
const configuration = Configuration(
Type.Object({
port: Type.Integer({ default: 5000, description: 'Server port' }),
mongo: Type.Object({
host: Type.String({ description: 'Mongo host' }),
port: Type.Integer({ description: 'Mongo port' }),
}),
redis: Type.Object({
host: Type.String({ default: 'localhost', description: 'Redis host' }),
port: Type.Integer({ default: '6379', description: 'Redis port' }),
}),
}),
)Which produces the following help documentation
Options:
--port PORT integer? Server port
--mongo-host MONGO_HOST string Mongo host
--mongo-port MONGO_PORT integer Mongo port
--redis-host REDIS_HOST string? Redis host
--redis-port REDIS_PORT integer? Redis port