<commit_before># value-mapper [![Build status](https://travis-ci.org/twolfson/value-mapper.png?branch=master)](https://travis-ci.org/twolfson/value-mapper)

Lookup values from a dictionary with aliasing, mapping, and flattenining.

This is used by [doubleshot][doubleshot] to map values inside of `content`.

[doubleshot]: https://github.com/twolfson/doubleshot

## Getting Started
Install the module with: `npm install value-mapper`

```javascript
// Create a mapper
var ValueMapper = require('value-mapper'),
    mapper = new ValueMapper({
      '1 + 2': ['One', 'plus two'],
      'One': function () {
        this.sum = 1;
      },
      'plus two': function () {
        this.sum += 2;
      },
      '= 3': 'equals three',
      'equals three': function () {
        assert.strictEqual(this.sum, 3);
      }
    });

// Lookup the values on a per-key basis
mapper.lookup('1 + 2', {
  alias: true,
  map: true
});
/*
[
  function () {
    this.sum = 1;
  },
  function () {
    this.sum += 2;
  }
]
*/
```

## Documentation
`ValueMapper` is a constructor function

```js
/**
 * Constructor for mapping values
 * @param {Object} input Key-value pairs to map values across
 */
```

To find values, use the `lookup` method

```js
mapper.lookup(key);
mapper.lookup(key, options);
/**
 * Resolve the value of a key
 * @param {String} key Name to lookup value by
 * @param {Object} [options] Flags to adjust how the mapping is performed
 * @param {Boolean} [options.alias] If the value is a string, `value = input[value]`
 * @param {Boolean} [options.map] If a value is an array, its values will be processed via the aliasing proxy.
 * @param {Boolean} [options.flatten] If the value is an array and contains arrays, the array will be flattened.
 * @param {Function[]} [options.middlewares] If provided, these functions will be appended to the array of middlewares.
 * @returns {Object} retObj Container for value and meta information
 * @returns {Mixed} retObj.value Aliased, mapped, and flattened copy of `key`
 * @returns {String[]} retObj.aliasesUsed Array of aliased keys used while looking up
 * @returns {String[]} retObj.aliasesNotFound Array of aliased not found while looking up
 */
```

If you choose to write your own middleware, the method signature will have to look like

```js
/**
 * @param {Mixed} val Value to perform operations on
 * @returns {Object} retObj Container for value and meta information
 * @returns {Mixed} retObj.value Manipulated value of `val`
 * @returns {String[]} retObj.aliasesUsed Array of aliased keys used while looking up
 * @returns {String[]} retObj.aliasesNotFound Array of aliased not found while looking up
```

Inside of your middleware, you have the context (i.e. `this`) of `mapper` (allowing you to call `this.lookup`) and access to the `key` of the current lookup call via `this.key`.

## Examples
Here is an example using `map`, `alias`, and `flatten`.

```js
// A complex mapping
var mapper = ValueMapper({
      'A fruit': 'A banana',
      'A banana': function () {
        this.color = 'yellow';
        this.fruit = new Banana();
      },
      'is yellow': ['hasColor', 'assertColor'],
      'when peeled is white': ['when peeled', 'is white'],
      'when peeled': function () {
        this.color = 'white';
        this.fruit = this.fruit.peel();
      },
      'is white': ['hasColor', 'assertColor'],
      'hasColor': function () {
        assert(this.fruit.color);<commit_msg>Rushing through adding new docs<commit_after># value-mapper [![Build status](https://travis-ci.org/twolfson/value-mapper.png?branch=master)](https://travis-ci.org/twolfson/value-mapper)

Lookup values from a dictionary with aliasing, mapping, and flattenining.

This is used by [doubleshot][doubleshot] to map values inside of `content`.

[doubleshot]: https://github.com/twolfson/doubleshot

## Getting Started
Install the module with: `npm install value-mapper`

```javascript
// Create a mapper
var ValueMapper = require('value-mapper'),
    mapper = new ValueMapper({
      '1 + 2': ['One', 'plus two'],
      'One': function () {
        this.sum = 1;
      },
      'plus two': function () {
        this.sum += 2;
      },
      '= 3': 'equals three',
      'equals three': function () {
        assert.strictEqual(this.sum, 3);
      }
    }, {
      middlewares: ['alias', 'map']
    });

// Lookup the values on a per-key basis
mapper.lookup('1 + 2');
/*
[
  function () {
    this.sum = 1;
  },
  function () {
    this.sum += 2;
  }
]
*/
```

## Documentation
`ValueMapper` is a constructor function

```js
new ValueMapper(input);
new ValueMapper(input, options);
/**
 * Constructor for mapping values
 * @param {Object} input Key-value pairs to map values across
 * @param {Object} [options] Flags to adjust how the mapping is performed
 * @param {Function[]} [options.middlewares] Middlewares to process resolved value through
 *   Built-in middlewares can be used via a 'string'.
 *   'alias': If `value` is a string, returns `value = input[value];`
 *   'map': If `value` is an array, each value will be processed via 'alias'
 *   'flatten': If `value` is an array and contains arrays, flatten it
 */
```

To find values, use the `lookup` method

```js
mapper.lookup(key);
/**
 * Resolve the value of a key
 * @param {String} key Name to lookup value by
 */
```

If you choose to write your own middleware, the method signature will have to look like

```js
/**
 * @param {Mixed} val Value to perform operations on
 * @returns {Object} retObj Container for value and meta information
 * @returns {Mixed} retObj.value Manipulated value of `val`
 * @returns {String[]} retObj.aliasesUsed Array of aliased keys used while looking up
 * @returns {String[]} retObj.aliasesNotFound Array of aliased not found while looking up
```

Inside of your middleware, you have the context (i.e. `this`) of `mapper` (allowing you to call `this.lookup`) and access to the `key` of the current lookup call via `this.key`.

Values can be procesed through middlewares via `process(val);`

New middlewares can be added to an instance via `addMiddleware(key);` (accepts built-in name or function)

Built-in middlewares can be added via `ValueMapper.addMiddleware(name, fn);`

## Examples
Here is an example using `map`, `alias`, and `flatten`.

```js
// A complex mapping
var mapper = ValueMapper({
      'A fruit': 'A banana',
      'A banana': function () {
        this.color = 'yellow';
        this.fruit = new Banana();
      },
      'is yellow': ['hasColor', 'assertColor'],
      'when peeled is white': ['when peeled', 'is white'],
      'when peeled': function () {
        this.color = 'white';
        this.fruit = this.fruit.peel();
      },
      'is white': ['hasColor', 'assertColor'],
      'hasColor': function () {
        assert(this.fruit.color);
{'fraction_non_alphanumeric': 0.1361164192268117, 'fraction_numerical': 0.0029398794649419372, 'mean_word_length': 3.418181818181818, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2419585', 'n_tokens_mistral': 2115, 'n_tokens_neox': 2044, 'n_words': 768}