Toolbox for configuration
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
src
test
.babelrc
.eslintrc.js
.flowconfig
.gitignore
.npmignore
.travis.yml
README.md
package.json

README.md

Unmarshaller

Greenkeeper badge

Toolbox for configuration

Build Status

Motivations

  • A declarative way for defining configuration
  • Reusability and composability
  • Flexible and generic

Installation

npm install --save unmarshaller

Example

import {builder, unmarshal} from 'unmarshaller';

const unmarshaller = {
  editor: builder.string('EDITOR'),
  browser: builder.string('BROWSER'),
};

const lookupFn = (key) => process.env[key];
const config = unmarshal(lookupFn, unmarshaller);

console.log(config);

Basics

Lookup function

You need to provide to the unmarshal function a way to lookup from keys in configuration.

The example above returns the value found in the process's environment:

const lookupFn = (key) => process.env[key];

Unmarshaller

Just an object which represents your configuration.

Builder

Helper functions to build the unmarshaller object.

Default types

type
string
boolean
number
object
holder
or

Default options

name type description
defaultValue string fallback value if the lookup returned undefined or null
of array provide an enumeration of possible values
parser function provide an custom parser function (usually when you want your own types)

Or

const unmarshaller = {
  foo: builder.or(
    builder.string('foo_a'),
    builder.string('foo_b'),
  )
};

The unmarshalling process will call the lookup function until a value (not undefined or null) is returned.

Extending an existing holder

import {extend, builder} from 'unmarshaller';

const holder = builder.holder({
  editor: builder.string('EDITOR'),
  browser: builder.string('BROWSER'),
});

const extendedHolder = extend(holder, {
  version: builder.string('VERSION'),
});

Extending the default builder

The builder is a regular JavaScript object.

Customizing the builder gives you the possiblity to use your own data converters.

The following example use a custom type: color (which in my use case parses a string into a structure).

import {builder as defaultBuilder} from 'unmarshaller';

export const builder = {
  ...defaultBuilder,
  color: (name, options) => ({
    name,
    parser: parseColor,
    type: 'color',
    ...options
  }),
};

You need to provide a custom parser function (parseColor in the example above). The definition is: function(value: string): string.