The default Configurator setup is a great starting point for quickly providing configuration hooks for
typical applications. The Schema API is superficially similar to that of most command-line focused libraries,
so adoption is easy. Out of the box, you get a command line parser with help text generation, environment
variable parsing, configuration file loading, and a library of property validators that cover many common needs.
Extensible Schema System
The Configurator includes built-in schemas for fundamental types (string, number,
boolean, array, object, date, buffer), as well as many useful validators
(e.g. $positive, $alphanum, $directory, etc.) but developers can also define their own.
Custom schemas and validators can provide arbitrary (potentially asynchronous!) transformations from
configuration inputs to validated outputs.
Sequenced Configuration Sources
Central to the Configurator is the concept of a ConfigurationSource. Each source encapsulates the
functionality of discovering configuration property assignments from a single origin: ObjectSource understands simple
objects, EnvironmentSource reads environment variables, CommandLineSource parses command line arguments,
and so forth.
Each ConfigurationSource is loaded in sequence. Property assignments discovered later in the sequence
override assignments from earlier in the sequence.
The Configurator provides a default sequence of predefined sources, but this sequence can be changed,
and the sources individually provide options to tune their behavior. The sequence can also be extended with
additional sources.
These additional sources may be fully customized for your needs or provided by optional packages.
Whether you need to integrate with secrets management, parameter stores, feature flag systems, or database
configuration, the same priority resolution and validation pipeline applies. Custom sources participate as
first-class citizens alongside the built-in CLI, environment, and file sources.
Single Source of Truth: Configuration as a Data Model
The structure of the validated output configuration object is intended to closely mirror an "idealized" config
file format for your application. If a schema hierarchy is created to align with the structure of the
application and its subsystems, then each subsystem's configured properties will be nested inside a
property object. This property object can then be used in isolation to safely initialize that subsystem, without
extraneous data leaking in. This reduces the "dig through a random bag of whatever" output
generated by many other configuration libraries.
Built for Embedding and Integration
The extensible schema and source systems that allow Configurator to handle custom configuration requirements also
enable it to be embedded and extended for use by frameworks or application wrappers.
This philosophy is embraced by the ModuleManager package, which
builds on the Configurator foundation to provide embedded declarative schemas, strongly typed references,
dependency injection, and lifecycle management. It is a separately installed library
@versionzero/module-manager, with its own section in the documentation.
ModuleManager enables all the Configurator capabilities described in this documentation, but
with a bias towards serving applications structured as a dependency graph of modular subsystems. It enables you to keep your
configurable property definitions fully colocated with the modules that use them, and provides a structured approach to
wiring everything together.