typeconf
v0.6.2
Published
A typesafe hierarchical configuration manager for Node.js and the browser.
Downloads
36
Maintainers
Readme
TypeConf is a universal, typesafe, hierarchical configuration manager for Node.js and the browser.
Usage
With TypeConf it's easy to retrieve typed configuration values from different sources:
import TypeConf = require('typeconf');
const conf = new TypeConf()
.withFile('./conf.json');
.withEnv();
const port: number = conf.getNumber('port');
const secret: string = conf.getString('secret');
Hierarchical configuration
TypeConf supports different storage backends for configuration values:
All versions:
- withStore(store: object, name?: string) JavaScript object
- withSupplier(supplier: (key: string) => any, name?: string) Supplier function
- set(key: string, value: any) Set or override a value
Node.js only:
- withArgv() Command line arguments (requires
minimist
) - withEnv(prefix?: string) Environment variables
- withFile(file: string) JSON or YAML files (.yaml files require
js-yaml
)
Browser only:
- withDOMNode(id: string, attribute?: string) DOM element with encoded
content
attribute
Backends are queried for existing values in the reverse order that they were added. For example:
const conf = new TypeConf()
.withFile('./conf.json');
.withEnv()
.withArgv();
const example = conf.get('example');
In this case TypeConf will check for existing values in the following order:
- A command line argument
--example
- An evironment variable
EXAMPLE
- An configuration file entry
"example": ...
Nested object properties
TypeConf can merge and extract nested object properties from environment varibles:
const conf = new TypeConf()
.withStore({
example: {
test: 'test'
}
})
.withEnv();
This example configuration uses a static object store and environment variables. In order to add or override properties on the example
object we can do the following:
export EXAMPLE__TEST="override"
export EXAMPLE__OTHER="another property"
By default, TypeConf uses two "underscore" characters (__
) as a separator. We can even define completely new objects using this method:
export ANOTHER__A="property a"
export ANOTHER__B__C="property b.c"
const another = conf.getObject('another');
another === { a: 'property a', b: { c: 'property b.c' } };
API documentation
withStore(store: object, name?: string): TypeConf
Use a JavaScript object as a source. Optionally provide a unique name for the store.
withSupplier(supplier: (key: string) => any, name?: string): TypeConf
Use a supplier function as a source. Optionally provide a unique name for the store.
withArgv(parser?: (args: string[]) => { [key: string]: any }): TypeConf
Node.js only. Use command line arguments as a source. Optionally provide a custom argument parser (uses minimist by default).
withEnv(prefix?: string, separator?: string): TypeConf
Node.js only. Use environment variables as a source. If a prefix is configured, it will be prepended to configuration value names during lookup. The default separator for nested object values is __
. For example:
export PREFIX_OBJECT__A="a"
export PREFIX_OBJECT__B__BB="bb"
conf.getObject('object') === { a: 'a', b: { bb: 'bb' } };
withFile(file: string): TypeConf
Node.js only. Use a configuration file as a source. JSON and YAML (requires js-yaml) are supported.
withDOMNode(id: string, attribute?: string): TypeConf
Browser only. Use a DOM element as a source. The configuration must be a Base64-encoded JSON string in an attribute of the element (default: content
). For example:
<meta id="conf" content="eyJhIjoiYiJ9" />
set(key: string, value: any): TypeConf
Set an override value.
unset(key: string): TypeConf
Delete an override value.
get(name: string): any
Get a raw value.
get<T>(name: string, transform: (x: any) => T): T
Get a value that is transformed by the supplied function.
getString(name: string, fallback?: string): string | undefined
Get an existing value as a string (using JSON.stringify
if necessary) or return an optional fallback string. Throws TypeError if fallback
is defined but not a string.
getNumber(name: string, fallback?: number): number | undefined
Get an existing value as a number (using parseFloat
if necessary) or return an optional fallback number. Throws TypeError if an existing value cannot be interpreted as a number or if fallback
is defined but not a number.
getBoolean(name: string): boolean
Get a value as a boolean. An existing value is always interpreted as true
unless it is false
or "false"
. A non-existing value is always interpreted as false
.
getObject(name: string, fallback?: object): object | undefined
Get an existing value as an object (using JSON.parse
if necessary) or return an optional fallback object. Throws TypeError if an existing value cannot be interpreted as an object or if fallback
is defined but not an object.
getType<T>(name: string, Newable: Newable<T>, fallback?: T): T | undefined
Get an existing value as an instance of type T
(by passing the raw value as the only argument to the constructor) or return an optional fallback value of the same type. Throws TypeError if an error occurs during the instantiation of type T
(constructors should validate the raw configuration value).
toJSON(): object
Aggregate all values from all supported stores as a plain JavaScript object. There are several limitations:
- Supplier-function stores cannot be aggregated.
- Environment-variable stores without a defined prefix cannot be aggregated.
- All command-line arguments are included if the default parser is used.
toBase64(): string
Aggregate all values from all supported stores and encode them as a Base64 JSON string. The same limitations as for toJSON()
apply.