README
object-fusion2
Another way to combine outline and content into an object.
This is a fork of object-fusion and used as a component for [doubleshot][doubleshot] to combine specification with content.
The reason this is a fork, is object-fusion supports a simpler outline but lacks order. This fork requires arrays and therefore has order at each level.
Getting Started
Install the module with: npm install object-fusion2
// Load in objectFusion
var objectFusion2 = require('object-fusion2');
// An outline acts as the shell that keys will line up to
var outline = {
'One': ['is equal to one']
};
// Content acts as the values to match up to the keys of value
var content = {
'One': function () {
this.one = 1;
},
'is equal to one': function () {
assert.strictEqual(this.one, 1);
}
};
// Match up the strings to the values
var fusedObject = objectFusion2({
outline: outline,
content: content
});
// The result looks like
{
'nodeName': 'One',
'value': function () {
this.one = 1;
},
'childNodes': [{
'nodeName': 'is equal to one',
'value': function () {
assert.strictEqual(this.one, 1);
}
}]
}
Documentation
objectFusion
exposes a single function for you to use.
objectFusion(params);
/**
* Fuse outline and content objects together
* @param {Object} params Container for parameters
* @param {Object} params.outline Object containing strings or nested objects of similar format
* @param {Object} params.content Key/value pairs that correspond to those in params.outline
* @param {Function} [params['value proxy']] Optional proxy for `value` once looked up
* @param {Function} [params['child proxy']] Optional proxy for `child` once looked up
* @param {Object} [params['events']] Optional channel -> listener object for emitted events
* @returns {Object} Combined object fused by params.outline values to params.content keys
*/
There is the Fuser
, available as objectFusion.Fuser
, which does the heavy lifting. If you provide a proxy, it will be invoked in a Fuser
context.
Fuser() - Constructor for fusing mechanism
Fuser.set(name, val) - Bind settings to instance (e.g. fuser.set('value proxy', fn);)
Fuser.get(name) - Retrieve settings from instance (e.g. fuser.get('value proxy');)
Fuser.addValue(name, val) - Add value for translation
Fuser.addValues(valueObj) - Add object of values for translation
Fuser.getValue(name) - Look up (and proxy) value by name (uses those stored via Fuser.addValue/addValues)
Fuser.getChild(obj, name) - Look up (and proxy) child from obj by name
Fuser.translate(obj) - Walk obj (depth-first), looking up value and child of each node
// Fuser inherits from node's EventEmitter so feel free to use those methods
// During looping, we expose:
// `this.get('value key');` - the key used for accessing the value
// `this.get('child key');` - the key used for accessing the child
// `this.get('node');` - the node being returned
// Emits `this.emit('value key used', valueKey);` when a value key is used
// Emits `this.emit('value key not found', valueKey);` when a value key's value is not found
// Emits `this.emit('child key used', childKey);` when a child key is used
// Emits `this.emit('child key not found', childKey);` when a child key's value is not found
Lastly, there are proxies available which allow for key aliasing and array expansion.
objectFusion.aliasProxy
- Allows for aliasing of content values (e.g.{'uno': 'one'}
)- Emits
this.emit('content aliased', key, val);
when aliasing occurs
- Emits
objectFusion.expandProxy
- Allows for expansion of content values (e.g.{'two': ['one', 'plusOne']}
- Emits
this.emit('content expanded', key, val);
when expansion occurs
- Emits
objectFusion.aliasAndExpandProxy
- Allows for both aliasing and expansion of content values
Examples
Here is an advanced example using the aliasAndExpandProxy
// Create an outline and content to fuse
var outline = {
'1 + 2': ['= 3']
};
var content = {
'1 + 2': ['1', '+ 2'],
'1': 'One',
'One': function () {
this.sum = 1;
},
'+ 2': 'plus two',
'plus two': function () {
this.sum += 2;
},
'= 3': 'is equal to three',
'is equal to three': function () {
assert.strictEqual(this.sum, 3);
}
};
// Fuse them together
var fusedObject = objectFusion({
outline: outline,
content: content,
'value proxy': objectFusion.aliasAndExpandProxy
});
// The result looks like
{
'nodeName': '1 + 2',
'value': [
function () {
this.sum = 1;
},
function () {
this.sum += 2;
}
],
'childNodes': [{
'nodeName': '= 3',
'value': function () {
assert.strictEqual(this.sum, 3);
}
}]
}
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint your code using grunt and test via npm test
.
License
Copyright (c) 2013 Todd Wolfson
Licensed under the MIT license.