Alinex Config: Readme

GitHub watchers GitHub stars GitHub forks

npm package latest version Travis status Coveralls status Gemnasium status GitHub issues

This package will give you an easy way to load and use configuration settings in your application or module.

It will read named files in different formats (YAML, JSON, XML, JavaScript, CoffeeScript) and supports validation and optimization/completion. Also the configuration will automatically be updated on changes in the file system and may inform it’s dependent objects.

The major features are:

  • over writable configurations
  • allows different file formats
  • supports value validation
  • supports value modification rules
  • automatically reloads on file changes

It is one of the modules of the Alinex Namespace following the code standards defined in the General Docs.

Install

NPM Downloads

The easiest way is to let npm add the module directly to your modules (from within you node modules directory):

Shell Script
npm install alinex-config --save

And update it to the latest version later:

Shell Script
npm update alinex-config --save

Always have a look at the latest changes.

Sources / File Formats

This configuration class allows multiple formats to be used alternatively or combined. So you may use the format you know best. See the alinex-format package for a detailed description of the allowed formats and description of how to write them.

As described in the link above you can use different formats but you can also split your configuration into multiple files and use different formats in each of them.

So as an first example if you have a very large configuration of three major parts you may split it up into 3 different files.

YAML Data
# config/server/http.yml listen: ip: 192.168.0.1 port: 80
YAML Data
# config/server/ftp.yml listen: ip: 192.168.0.1 port: 21
YAML Data
# config/server/mail.yml pop: port: 110 imap: port: 143

And if the program now reads config/** you will get the combined structure:

YAML Data
server: http: listen: ip: 192.168.0.1 port: 80 ftp: listen: ip: 192.168.0.1 port: 21 mail: pop: port: 110 imap: port: 143

This is because the config system will use the names behind the asterisk as structure levels automatically but you may control the combination rules using filter and path in the origin setup (see below).

Usage

To use the configuration management you have to load the module first:

CoffeeScript Code
config = require 'alinex-config'

This gives you back the main configuration instance. But before you can access your configuration you have to setup the system if not already done and initialize it:

CoffeeScript Code
# register common configuration paths for application config.register 'myapp', __dirname # add a special path on the end (highest priority) config.pushOrigin uri: 'file:///etc/my-config.yml' # and add a schema to verify the database settings are correct config.setSchema 'database', type: .... # schema # start initializing the configuration and load the data config.init (err) -> return cb err if err # all configurations are loaded successfully

Alternatively you may skip your program with a detailed error message:

CoffeeScript Code
config.init (err) -> if err console.error "FAILED: #{err.message}" console.error err.description process.exit 1

Make sure that the initialization is completely done for all configuration data before using it. If you change the setup later you have to reinit everything which causes an extra afford which you should skip if possible.

After that is done you can easily access the configuration like:

CoffeeScript Code
conf = config.data # here you have the whole registry data conf = config.get 'server' # and now you have only the server structure conf = config.get 'database/master/address' # or only a specific database connection

To don’t mess with the names: I always address the instance with config and use a short name like conf for some data out of it.

On demand you may also reload the configuration completely:

CoffeeScript Code
config.reload (err) -> if err console.error "FAILED: #{err.message}" console.error err.description process.exit 1

But if you want tp know in your app then some configuration was changed you can use the path as an event which is fired if this element or one below is changed.

CoffeeScript Code
config.on '/address', -> console.log "New addresses found, reinit the list..." myList = config.get '/address'

Debugging

If you have any problems you may debug the code with the predefined flags. It uses the debug module to let you define what to debug.

Call it with the DEBUG environment variable set to

  • ‘config’ for basic information
  • ‘config:value’ with structure after loaded
  • ‘config:access’ with info about data accessed
  • ‘config*’ for all of them

You can also combine them using comma or use only DEBUG=* to show all debug messages of all modules.

Additional value checking will be done if the debugging for the general config is enabled.

License

© Copyright 2014-2016 Alexander Schilling

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.