Beech
A JavaScript object-tree processor, i.e. a 'collection pipeline' as described by Fowler here.
Installation
npm install beech --save
Usage
General Description
Beech allows processing of a collection's items and applying different kinds of transformations to it.
- Method chaining: every method (except the 'terminating' methods, e.g.
materialize()
) returns the beech object, which allows chaining. - Constructor accepts a JavaScript value (scalar, array, hash) as argument. This value is taken as initial collection inside the beech object.
- Beech's methods don't modify the initial collection but construct new collection instances at every transformation. Callbacks can modify items of the initial collection however.
- Internally the current collection is seen as an array consisting of single values and/or special key-value pairs at root level (allowing duplicate key-value pairs). Higher levels stay the JavaScript values they are.
- Beech uses the initial collection at first (processing/transformation) method call. That means: any modification to the initial collection (root-level) outside of beech is effective to beech only before the first method call and ignored afterwards.
Below descriptions of beech's methods, cf. Fowler's Operation Catalog.
map()
Method - The method accepts a callback function as argument.
- Beech applies the callback to all items of the current collection.
- Beech passes the item to the callback: if single value as one argument, if key-value pair as two arguments.
- Beech appends the callback's return value to the resulting collection, if presented.
- If no return value is passed, beech will add all members added to the callback's
this
to the resulting collection.
var createBeechObjectTreeProcessor = ; var {}; var collection = 'one' : 1 'two' : someFunction 'three' : 'A string value' ; var { return value; }; var processor = ; processor; // Internally beech now holds [1, someFunction, 'A string value'] { thiskey + 'x' = value; }; processor = ; processor; // Internally beech now holds a collection consisting of key-value pairs: ('onex' : 1), ('twox' : someFunction), ('threex' : 'A string value')
filter()
Method - The method accepts a callback function as argument.
- Beech applies the callback to all items of the current collection.
- Beech passes the item to the callback: if single value as one argument, if key-value pair as two arguments.
- Beech appends the current item to the resulting collection, if the callback's return value is a truthy value.
var createBeechObjectTreeProcessor = ; var {}; var collection = 'one' : 1 'two' : someFunction 'three' : 'A string value' ; var { return key === 'one' || key === 'three'; }; var processor = ; processor; // Internally beech is now holding a collection consisting of key-value pairs: ('one' : 1), ('three' : 'A string value')
reduce()
Method - The method accepts a callback function as argument.
- Beech applies the callback to all items of the current collection.
- Beech passes an accumulator-value and the item to the callback: if item is single value as one additional argument, if it is a key-value pair as two additional arguments.
- Beech takes the callback's return value as the new accumulator-value that it passes to the next call.
var createBeechObjectTreeProcessor = ; var {}; var collection = 'one' : 1 'two' : someFunction 'three' : 'A string value' ; var { return aAccumulator + aKey + ' is of type "' + typeof aValue + '" '; }; var processor = ; processor; // Internally beech is now holding a collection consisting of one single value (a string): 'one is of type "number" two is of type "function" three is of type "string" '
flatten()
Method - The method accepts as an optional argument the level (numeric value, starting at 1) to which it should flatten out the collection.
- Beech adds all 'leaf'-values of the collection-tree to the resulting collection thereby flattening the tree.
var createBeechObjectTreeProcessor = ; var collection = 'one' : 1 'two' : 'keyx' : 'valuex' 'three' : 'A string value' ; var processor = ; processor; // Internally beech is now holding a collection consisting of single values: 'one', 1, 'two', 'keyx', 'valuex', 'three', 'A string value'
concat()
Method - The method accepts as argument a further collection.
- Beech adds all items of the supplied collection to the current collection thereby concatenating the current and the supplied collection.
- Concatenation can lead to duplicate items in the resulting collection.
var createBeechObjectTreeProcessor = ; var {}; var collection = 'one' : 1 'two' : someFunction 'three' : 'A string value' ; var furtherCollection = 'one' : 100 'deux' : someFunction 'three' : 'A string value' ; var processor = ; processor; // Internally beech is now holding a collection consisting of key-value pairs: ('one' : 1), ('two' : someFunction), ('three' : 'A string value'), ('one' : 100), ('deux' : someFunction), ('three' : 'A string value')
difference()
Method - The method accepts as argument a further collection.
- Beech removes all items of the supplied collection from the current collection resulting in a collection that contains the difference between the latter and the first.
var createBeechObjectTreeProcessor = ; var {}; var collection = 'one' : 1 'two' : someFunction 'three' : 'A string value' ; var furtherCollection = 'one' : 100 'deux' : someFunction 'three' : 'A string value' ; var processor = ; processor; // Internally beech is now holding a collection consisting of key-value pairs: ('one' : 1), ('two' : someFunction)
intersection()
Method - The method accepts as argument a further collection.
- Beech retains all items of the current collection that are also contained in the supplied collection resulting in a collection that contains the intersection of both.
var createBeechObjectTreeProcessor = ; var {}; var collection = 'one' : 1 'two' : someFunction 'three' : 'A string value' ; var furtherCollection = 'one' : 100 'deux' : someFunction 'three' : 'A string value' ; var processor = ; processor; // Internally beech is now holding a collection consisting of one key-value pair: ('three' : 'A string value')
materialize()
Method - The method doesn't take arguments.
- The method returns the current beech collection as a 'plain' JavaScript collection.
- If the beech collection contains at least one key-value pair, beech produces a JavaScript Object populated by only key-value pairs.
- If the beech collection contains exactly one value entry, beech produces this value as a JavaScript Scalar.
- If the beech collection contains more than one value entry but no key-value pair, beech produces a JavaScript Array containing these entries.
var createBeechObjectTreeProcessor = ; var collection = 'one' : 1 'two' : 2 'three' : 3 ; var otherCollection = 'two' : 'dos' 'four' : 'cuatro' ; var processor = ; var resultCollection = processor; // resultCollection is {'one' : 1, 'two' : 'dos', 'three' : 3, 'four' : 'cuatro'}
Tests
npm test
License
Published under the MIT-License, see LICENSE-MIT.txt file.
Contact
Your feedback is appreciated, please e-mail me at alaarmann@gmx.net
Release History
- 0.1.0 Initial release
- 0.2.0 Implementation of map(), filter(), reduce(), flatten(), concat(), difference(), intersection()
- 0.3.0 Implementation of materialize()