https://github.com/xtuc/unmarshaller
Toolbox for configuration
https://github.com/xtuc/unmarshaller
Last synced: over 1 year ago
JSON representation
Toolbox for configuration
- Host: GitHub
- URL: https://github.com/xtuc/unmarshaller
- Owner: xtuc
- Created: 2017-04-04T19:28:03.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-04-16T20:55:46.000Z (over 8 years ago)
- Last Synced: 2024-09-18T12:52:07.824Z (almost 2 years ago)
- Language: JavaScript
- Size: 50.8 KB
- Stars: 10
- Watchers: 4
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Unmarshaller
[](https://greenkeeper.io/)
> Toolbox for configuration
[](https://travis-ci.org/xtuc/unmarshaller)
## Motivations
- A declarative way for defining configuration
- Reusability and composability
- Flexible and generic
## Installation
```shell
npm install --save unmarshaller
```
## Example
```js
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:
```js
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| fallbacks to `defaultValue` and `null`.|
|parser|function|provide an custom parser function (usually when you want your own types)|
### Or
```js
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
```js
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).
```js
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`.