ConfigurationSchema API

Overview

The ConfigurationSchema class defines the configurable fields for your application.

Constructor

new ConfigurationSchema(options)

Param	Type	Description
[options]	object	Optional settings (described below)
[options.condition]	function	optional condition to check before processing anything associated with this schema
[options.linkedParentFieldName]	string	A field in the parent schema that must be set for this schema to be processed
[options.linkedParentFieldValue]	string	Value that linkedParentFieldName must be set to in the parent

The ConfigurationSchema is likely to be app-specific, but it may be useful to create reusable subclasses of Types and/or Validators that can be imported by multiple applications using Configurator.

When a condition function is provided, it should have the signature

function condition(field:FieldOptions, value: any, configuration: object): boolean {/*...*/}

If the condition function returns a falsey value, all assignments to fields in this schema will be skipped.

Methods

field(name, options:FieldOptions):ConfigurationSchema

Define a new configurable field in this schema. (Returns the schema for method chaining.)

Param	Type	Description
name	string	Field name (required)
[options]	object	Field options (described below)
[options.type]	string	Type name that will be used for value resolution; defaults to "string"
[options.validator]	function|string|RegEx|object	Additional validations to run after type resolution
[options.condition]	function	Per-field conditional evaluation (overrides schema condition)
[options.required]	boolean	If true, an error will be thrown if no value is set
[options.default]	any	Default value to assign if nothing else overrides (see SchemaDefaultsSource)
[options.allowEmpty]	boolean	Whether or not an empty value allowed (arrays or strings)
[options.flagHint]	string	Request a specific command-line single-character flag
[options.description]	string	Used to display help text for the field
[options.advanced]	boolean	Used to filter some fields out of default help text
[options.hidden]	boolean	Used to completely suppress some fields from the help text

The type name is used to look up a type resolver in the TypeRegistry, which is then used to convert an input request value into a proper output value.

See the documentation on Types and Validators for more information on how these options should be used.

A few of the field options are used directly by ConfigurationSchema or Configurator, but the field options object is deliberately kept open for extra properties to allow private contracts between field definitions and individual ConfigurationSource implementations. For example, the last four options (flagHint, description, advanced, and hidden) are defined here for reference, as they're very commonly used, but are actually only consumed by CommandLineSource.

getFields(): Map<string,FieldOptions>

Return all fields defined in this schema.

child(name, options):ConfigurationSchema

child(name, ConfigurationSchema):ConfigurationSchema

Create a new child ConfigurationSchema, either by cloning the provided schema, or creating a new one from the options passed. The newly created schema is returned for method chaining. Normal ConfiguratorSchema options are permitted.

Param	Type	Description
name	string	Child schema property name; will be used in final object hierarchy
[options]	object	Options to pass to child schema constructor (see above)

getChildren(): Map<string,ConfigurationSchema>

Return all child schemas.

getAllFieldPaths(): Map<string,FieldOptions>

Return a flattened view of all configured fields in the schema hierarchy, with the Map keys as dotted "field paths". This representation is used by the processAssignments method.

async processAssignments(fpaList, options:object):object

Process field-path assignment maps generated from sequence of ConfigurationSource implementations. Generates a candidate configuration object, then calls validate on it.

Returns the validated object, or throws if there are errors.

This method is public, but not generally used unless you are extending Configurator.

Param	Type	Description
fpaList	Array<Map<string,any>>	list of field-path assignment maps, in source sequence order
[options]	object	assignment options
[options.strict]	boolean	strict validation (default: true)
[options.types]	Types	override types
[options.configuration]	object	initial configuration object

async validate(inputConfig:object, options:object):object

Validate a candidate configuration object against the schema.

Returns the validated object, or throws if there are errors.

Param	Type	Description
inputConfig	object	object to validate against the schema
[options]	object	validation options, described below
[options.types]	Types	pass in Types registry to do a typecheck pass during validation
[options.validators]	Validators	allows you to override schema's Validators registry
[options.strict]	boolean	enable strict validation
[options.populateDefaults]	boolean	enable fallback defaults mode

You can omit passing types if you have already typechecked the assignments.

The strict option will throw an error if unknown fields exist in the object, or if any types are unknown.

The populateDefaults option provides a fallback method to setting fields in implementations where the DefaultsSource was not used.

This method is public, but not generally used unless you are extending Configurator.

Accessors

Accessor	Type	Description
fields	Map<string,FieldOptions>	Fields defined in the schema (getFields() clones)
children	Array<ConfigurationSchema>	Children defined in the schema (`getChildren() clones)
parent	[ConfigurationSchema]	Parent schema, if this schema is a child
path	string	Dotted path to this schema from the root