ConfigObjectModel

ConfigObjectModel

new ConfigObjectModel(rawSchema, optionsopt, scope)

Source:

Class for configNode, created with blueconfig class. This class is declared by const config = blueconfig(schema).

The global getter config will be cloned to local config. You must refresh getters configs if you apply global change to local (configuration instance).

Example
const config = blueconfig({
  env: {
    doc: 'The applicaton environment.',
    format: ['production', 'development', 'test'],
    default: 'development',
    env: 'NODE_ENV'
  },
  log_file_path: {
    'doc': 'Log file path',
    'format': String,
    'default': '/tmp/app.log'
  }
});
// or
config = blueconfig('/some/path/to/a/config-schema.json');
Parameters:
rawSchema string | object

Schema object or a path to a schema JSON file

options object

Options:

Sub properties
options.env object

Override process.env if specified using an object {'NODE_ENV': 'production'}.

options.args Array.<string>

Override process.argv if specified using an array ['--argname', 'value'] or a string --argname value.

options.defaultSubstitute string

Override '$~default', this value will be replaced by 'default' during the schema parsing.

options.strictParsing string

Throw an error if default or format properties are omitted.

scope object

workers

Sub properties
scope.Getter Getter

Getter worker

scope.Parser Parser

Parser worker

scope.Ruler Ruler

Ruler worker

Methods

default(name) → {*}

Source:

Returns the default value of the name property (defined in the schema). name can use dot notation to reference nested values.

Example
config.default('db.host')
Parameters:
name string

Target property, name can use dot notation to reference

Returns:

Returns the default value.

Type
*

get(name) → {*}

Source:

Returns the current getter name of the name value origin. name can use dot notation to reference nested values.

Example
config.get('db.host')
// or
config.get('db').host
// also
config.get('db[0]')
// with dot:
config.get('db["www.airbus.com"]') { 'db': { 'www.airbus.com': 'air company'} }
// in the first level
config.get("['site.fr']") // { 'site.fr': 'french site' }
Parameters:
name string

Target property, name can use dot notation to reference

Returns:

Returns the current value of the name property

Type
*

getArgs() → {Array.<string>}

Source:

Parse constructor arguments. Returns the list of process arguments (not including the launcher and application file arguments). Defaults to process.argv unless an override is specified using the args key of the second (options) argument of the blueconfig function.

Returns:

Returns custom args {options.args} or process.argv.slice(2)

Type
Array.<string>

getEnv() → {object}

Source:

Gets the environment variable map, using the override passed to the blueconfig function or process.env if no override was passed.

Returns the list of environment variables. Defaults to process.env unless an override is specified using the env key of the second argument (options) argument of the blueconfig function.

Returns:

Returns custom args {options.env} or process.env

Type
object

getGettersOrder() → {Array.<string>}

Source:
See:
  • Blueconfig.getGettersOrder

Returns getter order. Local (configuration instance) version of blueconfig.sortGetters().

Returns:

Returns current getter order

Type
Array.<string>

getOrigin(name) → {string}

Source:

Returns the current getter name of the name value origin. name can use dot notation to reference nested values.

Example
config.getOrigin('db.host')
Parameters:
name string

Target property, name can use dot notation to reference

Returns:

Returns the getter name with is the current origin of the value.

Type
string

getProperties() → {object}

Source:

Exports all the properties (that is the keys and their current values)

Returns:

Returns properties

Type
object

getSchema({debug) → {object}

Source:

Exports the schema (as blueconfig understands your schema, may be more strict).

Parameters:
{debug boolean

When debug is true, returns Schema Node Model (as stored in blueconfig database).

Returns:

Returns schema object

Type
object

getSchemaString({debug) → {string}

Source:

Exports the schema as a JSON string.

Parameters:
{debug boolean

When debug is true, returns Schema Node Model (as stored in blueconfig database).

Returns:

Returns schema as a JSON string

Type
string

has(name) → {boolean}

Source:

Checks if the property name is set.

Example
if (config.has('db.host')) {
// Your code
}
Parameters:
name string

Target property, name can use dot notation to reference

Returns:

Returns true if the property name is defined, or false otherwise.

Type
boolean

load(obj) → {this}

Source:
Deprecated:
  • since v6.0.0, use `.merge(obj)` instead or strict way: `.merge(obj, 'data')`

Merges a JavaScript object into config

Parameters:
obj object

Load object

Returns:
Type
this

loadFile(paths) → {this}

Source:
Deprecated:
  • since v6.0.0, use `.merge(string|string[])` instead or strict way: `.merge(string|string[], 'filepath')`

Merges a JavaScript properties files into config

Parameters:
paths string | Array.<string>

Config file paths

Returns:
Type
this

merge() → {this}

Source:

Merges a JavaScript object/files into config

Examples
// Loads/merges a JavaScript object into `config`.
config.merge({
  'env': 'test',
  'ip': '127.0.0.1',
  'port': 80
})
// If you set contentType to data, blueconfig will parse array like config and not like several config.
config.merge([
  {'ip': 'test'},
  {'ip': '127.0.0.1'},
  {'ip': 80}
], 'data').getProperties() // === [{'ip': 'test'}, {'ip': '127.0.0.1'}, {'ip': 80}]

config.merge([
  {'ip': 'test'},
  {'ip': '127.0.0.1'},
  {'ip': 80}
]).getProperties() // === {'ip': 80}

// Merges one or multiple JSON configuration files into `config`.
config.merge('./config/' + conf.get('env') + '.json')

// Or, merging multiple files at once.
config.merge(process.env.CONFIG_FILES.split(','))
// -> where env.CONFIG_FILES=/path/to/production.json,/path/to/secrets.json,/path/to/sitespecific.json
Returns:
Type
this

refreshGetters()

Source:

Reclone global getters config to local getters config and update configuration object value depending on new getters' order.

value set with .merge()/.set() will be replaced by schema/getter value depending of Origin priority.

Example
blueconfig.getGettersOrder() // ['default', 'value', 'env', 'arg', 'force']

const config = blueconfig(schema) // will clone: ['default', 'value', 'env', 'arg', 'force']

// ### Two ways to do:
// 1) Global change
blueconfig.sortGetters(['value', 'default', 'arg', 'env', 'force'])

config.getGettersOrder() // ['default', 'value', 'env', 'arg', 'force']
blueconfig.getGettersOrder() // ['value', 'default', 'arg', 'env', 'force']

// apply global change on local
config.refreshGetters() // refresh and apply global change to local

config.getGettersOrder() // ['value', 'default', 'arg', 'env', 'force']
// 2) Local change
config.sortGetters(['default', 'value', 'env', 'arg', 'force'])
config.getGettersOrder() // ['default', 'value', 'env', 'arg', 'force']
blueconfig.getGettersOrder() // ['value', 'default', 'arg', 'env', 'force']

reset(name) → {this}

Source:

Resets a property to its default value as defined in the schema

Example
config.reset('db.host')
Parameters:
name string

Target property, name can use dot notation to reference

Returns:
Type
this

set(name, priorityopt, respectPriorityopt) → {this}

Source:

Sets the value name to value.

Example
config.set('property.that.may.not.exist.yet', 'some value')
config.get('property.that.may.not.exist.yet')
config.get('.property.that.may.not.exist.yet') // For path which start with `.` are ignored
// "some value"

config.set('color', 'green', true) // getter: 'force'
// .get('color') --> 'green'

config.set('color', 'orange', false, true) // getter: 'value' and respectPriority = true
// value will be not change because  ^^^^ respectPriority = true and value priority < force priority
// .get('color') --> 'green'

config.set('color', 'pink', false) // getter: 'value'
// value will change because respectPriority is not active.
// .get('color') --> 'pink'

config.set('color', 'green', true) // getter: 'force'
// .get('color') --> 'green'

config.merge({color: 'blue'}) // getter: 'value'
// value will not change because value priority < force priority
// .get('color') --> 'green'
Parameters:
name string

Target property, name can use dot notation to reference nested values, e.g. "db.name". If objects in the chain don't yet exist, they will be initialized to empty objects.

priority string

Optional, can be a boolean or getter name (a string). You must declare this property in the schema to use this option. set will change the property getter origin depending on priority value:

  • false: priority set to value.
  • true: priority set to force, can be only changed if you do another .set(name, value). Make sure that .refreshGetters() will not overwrite your value.
  • <string>: must be a getter name (e.g.: default, env, arg).

respectPriority string

Optional, if this argument is true this function will change the value only if priority is higher than or equal to the property getter origin.

Returns:
Type
this

sortGetters(newOrder) → {this}

Source:
See:
  • Blueconfig.sortGetters

Sorts getter depending of array order, priority uses ascending order.

Local (configuration instance) version of blueconfig.sortGetters().

Example
config.sortGetters(['default', 'value', 'env', 'arg', 'force'])
Parameters:
newOrder Array.<string>

The new getter order

Returns:
Type
this

toString() → {string}

Source:

Exports all the properties (that is the keys and their current values) as a JSON string, with sensitive values masked. Sensitive values are masked even if they aren't set, to avoid revealing any information.

Returns:

Returns properties as a JSON string

Type
string

validate(optionsopt) → {this}

Source:

Validates the config considering the schema (iterates each SchemaNode.validate() in your config). All errors are collected and thrown or displayed at once.

Example
config.validate({
  allowed: 'strict',
  output: require('debug')('blueconfig:validate:error')
})
Parameters:
options object

Options, accepts: options.allow and options.output:

Sub properties
options.allowed string

Any properties specified in config files that are not declared in the schema will print a warning or throw an error depending on this setting:

  • 'warn': is the default behavior, will print a warning.
  • 'strict': will throw errors. This is to ensure that the schema and the config files are sync.

options.output string

You can replace the default output console.log by your own output function. You can use debug module like the example.

Returns:
Type
this

Type Definitions

getterCallback(value, mySchema, value) → {*}

Source:

Will get an external value depending of custom getter/code

Example
blueconfig.addGetter({
  property: 'accept-undefined',
  getter: (value, schema, stopPropagation) => schema._cvtCoerce(fs.readFileSync(value, 'utf-8').toString()),
  usedOnlyOnce: true // use file only once
});
Parameters:
value *

Value to coerce

mySchema string

Value to coerce

value function

Stop propagation (accept undefined value). By default, undefined don't stop the getter queue, this mean Blueconfig will continue to call other getter to find a value not undefined.

Returns:

value Returns coerced value

Type
*