A functional rules system based on the promise pattern
npm install foolsThis is an attempt to use the promise pattern to create functional rules system in Javascript.
Each of the classes take one or more functions as constructor arguments and return a function.
The resulting function always takes a single argument.
Ordinary functions and logic flow structures are immutable; once a function is defined it is a closed system.
Foools components can be adjusted on the fly; you can change the fork's 'then' clause at any time, or it's
else clause.
It is also very easy to load process structures from configuration files, and compose them with each other.
Almost every Fools function has an optional error function that will trap (most) errors in execution
and respond to the output error. The result of the error trapper is returned in the place that the
original function is called. Note, no effort is made by Fools to determine which context the
error came from -- if that is important, you will want to catch and pipe errors yourself and add
context hints to them.
To add error handling to a fools function call fools_function.err(function(err){...}).
------------
Fools.all calls each function in its roster with the input value. They are called in order
and any errors emitted by a function are trapped and emitted as one composite error.
Like until there is a my_all.last(last_fn) method that is always done after the added methods.
Fools.all is (barring errors) functionally identical to map.
``javsacript`
var my_all = Fools.all(fn_a, fn_b, fn_c...)
and/or
`javascript
var my_all = Fools.all().add(fn_a).add(fn_b).add(fn_c)...
`
each has a set of tests and true is returned when all of the tests pass.
It is the equivalent of _.every.
` javascript
var each = Fools.each()
.add(_.isNumber)
.add(function (n) {
return n > 0
})
.add(function (n) {
return !(n % 2)
});
_.each(['g', -4, 0, 1, 2, 3, 4, {}], function(n){
console.log('"%s" is positive odd number: %s', n, each(n));
});
/**
"g" is positive odd number: false
"-4" is positive odd number: false
"0" is positive odd number: false
"1" is positive odd number: false
"2" is positive odd number: true
"3" is positive odd number: false
"4" is positive odd number: true
"[object Object]" is positive odd number: false
*/
`
Fork is functionally identical to the "if" (or a ? b : c) statement.
Fork takes one function that returns true or false and calls the second function (with the original argument)
if the first result is true, and the third function if the first function returns false.
`javascript`
var my_fork = Fools.fork(test, if_true_fn, if_else_fn)
or
` javascript
var my_fork = Fools.Fork(test).then(if_true_fn).else(if_false_fn)
`
returns a function that can be called repeatedly with arguments; whether or not the true test is passed determines
whether the true function or the false function is called (also, with those arguments).
Note because Fools.fork returns a function (not an instance) you can nest forks for a binary branching
expert system.
You can also call my_fork.err(on_err_fn) to create an error trapping function that receives any errors emitted by
the test or either of its branches.
`javascript
function if_odd(n){
return (n % 2);
}
function ifPositive(n){
return n > 0;
}
var test = Fools.fork(ifPositive)
.then(
Fools.fork(if_odd)
.then(function(n){ return 2 * n})
.else(_.identity) // if even
).else(function(){ return 0; }); // if not positive
console.log(_.map(_.range(-5, 6), test));
// result: [ 0, 0, 0, 0, 0, 0, 2, 2, 6, 4, 10 ]
`Fools.gauntlet : {function}
Gauntlet is similar to until in that a series of tests are run until one of them is true.
Unlike until, gauntlet returns an arbitrary value from the truthy test -- the return value of the test function
is not related to the truthiness of the test.
Gauntlet calls a series of tests on an input until one of them is true, and returns that tests' result.
In order for a function to both return true/false and return the maximum range of results, the
tests are passed a second parameter, isGood; call this method to validate the result.
` javascript
var bot_loc = {x: 0, y: 2};
var min_x = 0;
var max_x = 2;
var min_y = 0;
var max_y = 2;
var gauntlet = Fools.gauntlet()
.add(function (input, good) {
if (bot_loc.y > min_y) {
good();
bot_loc.y -= 1;
}
return 'N';
}).add(function (input, good) {
if (bot_loc.x < max_x) {
good();
bot_loc.x += 1;
}
return 'E';
});
gauntlet.if_last = function () {
return '0';
};
it ('should move north', function(){
gauntlet().should.eql('N');
bot_loc.should.eql({x: 0, y: 1});
});
it ('should move north again', function(){
gauntlet().should.eql('N');
bot_loc.should.eql({x: 0, y: 0});
});
it('should move east', function(){
gauntlet().should.eql('E');
bot_loc.should.eql({x: 1, y: 0});
});
it('should move east again', function(){
gauntlet().should.eql('E');
bot_loc.should.eql({x: 2, y: 0});
});
it('should not move', function(){
gauntlet().should.eql('0');
bot_loc.should.eql({x: 2, y: 0});
});
`Fools.loop(iterator(iter: {Object}) : {function}): {function}
This is a method of walking a multidimensional matrix. The loop function has a similar profile to reduce:
it takes a memo argument that is passed as the second argument to the iterator (the first being an amalgam
of the dimensions being walked.
Use of a memo / the return value of loop is optional.
` javascript
console.log(
Fools.loop(function(iter, memo){
memo.push(_.clone(iter));
return memo;
})
.dim('i', -1, 1)
.dim('j', -1, 1)([])
);
/** responds
[ { i: -1, j: -1 },
{ i: 0, j: -1 },
{ i: 1, j: -1 },
{ i: -1, j: 0 },
{ i: 0, j: 0 },
{ i: 1, j: 0 },
{ i: -1, j: 1 },
{ i: 0, j: 1 },
{ i: 1, j: 1 } ]
*/
`
note -- the iterator is an object that is changed from iteration to iteration -- saving its value requires
use of clone or some similar method of extracting the values of the iter parameter.
Range is a function that takes a value and executes a function over it depending on where it falls in a
numeric range of possible values. It is useful for examples to take a range of values and sorting them into bins.
Range is configured by calling .add(min_value, result_function) multiple times to define how you want to respondmin_value
to a value that is >= the min but less than all larger min_values set. can be any numeric value.
the .add_min and .add_max methods allow for handling values outside the defined range.
note - the handler for the last bracket is never called; use .add_max to handle the last bracket.
` javascript
var negatives = [];
var positives = [];
var small = 0;
var large = 1;
var range = Fools.range()
.add(-10, function (n) {
negatives.push(n);
})
.add(0, function (n) {
positives.push(n)
})
.add(11, function () {
large++;
})
.add_min(function () {
small++;
})
.add_max(function () {
throw new Error('never called');
});
// call range 1000 times.
_.each(_.range(0, 1000), function () {
// call range with a random value in the -15 ... 15 range.
range(Math.round(Math.random() * 30 - 15));
});
console.log('small: %s', small);
console.log('large: %s', large);
console.log('negatives: %s', _.sortBy(negatives, _.identity));
console.log('positives: %s', _.sortBy(positives, _.identity));
/**
results similar to
small: 150
large: 165
negatives: -10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-10,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-9,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-8,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-7,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-6,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-5,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-3,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-2,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1
positives: 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,8,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,9,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10
*/
`
Fools executes its test one by one until one of them fails.
you can stack any number of functions in Fools.until chains.
For any given input, the functions are called in order until one of them returns true.
until returns the index of the function that retrned true;
You can force a given function to be executed last by calling my_until.last(last_fn).
Errors can be trapped as with fork.
If no function returns true, until throws an error -- and that error will NOT be trapped by
your error trapper.
`javsacript`
var my_until = Fools.until(fn_a, fn_b, fn_c...)
and/or
`javascript
var my_until = Fools.until().add(fn_a).add(fn_b).add(fn_c)...
`
` javascript
var Fools = require('./../fools');
var _ = require('lodash');
var until = Fools.until()
.add(function (n) {
return !_.isNumber(n);
})
.add(function (n) {
return n < 0
})
.add(function (n) {
return (n % 2);
})
.add(function(n){
return true;
});
_.each(['g', -4, 0, 1, 2, 3, 4, {}], function (n) {
var index = until(n);
if ( index == 3){
console.log('%s is a positive even number', n);
} else {
console.log('"%s" failed at test: %s', n, index);
}
});
/**
"g" failed at test: 0
"-4" failed at test: 1
0 is a positive even number
"1" failed at test: 2
2 is a positive even number
"3" failed at test: 2
4 is a positive even number
"[object Object]" failed at test: 0
*/
`Fools.rate
rate is a very specialized method to rank items on a weighted curve; it keeps a database
in closure that allows you to poll for the best and worst candidates.
You configure the rate function by adding properties to be considered, using the prop method:
` javascript
function letterToNumber(grade){
switch(grade){
case 'A':
return 4;
break;
case 'B':
return 3;
break;
case 'F':
return 0;
break;
default:
return 0;
}
}
rate.prop('science') // returns the science rating unfiltered
rate.prop('science', letterToNumber) // returns the numeric value of a letter grade
rate.prop('science', null, 2) // returns 2 * the value of the grade
rate.prop('science', letterToNumber, 2) returns 2 * the numeric value of a letter grade
`
Calling rate(target) returns a numeric rating of a target.rate.add(target)
calling adds the target to an internal collection for the purposebest()
of enabling the , select(min, max), and worst() methods.
Here are some examples of the rate system in action:
` javascript
var util = require('util');
var rate = Fools.rate()
.prop('brains')
.prop('looks', null, 5);
var peter = {brains: 2, looks: 8, birth_year: 2014 - 45, name: 'Peter Griffin'};
var lois = {brains: 6, looks: 12, birth_year: 2014 - 43, name: 'Lois Griffin'};
var stewie = {brains: 14, looks: 5, birth_year: 2014 - 2, name: 'Stewie Griffin'};
var brian = {brains: 8, looks: 6, birth_year: 2014 - 8, name: 'Brian Griffin'};
var meg = {brains: 4, looks: 3, birth_year: 2014 - 16, name: 'Meg Griffin'};
console.log(' ----------- rating (looks biased) --------- ');
_.each([peter, lois, stewie, brian, meg], function (item) {
console.log('rating of %s: %s', item.name, rate(item));
console.log(' (%s * 5 + %s) / %s', item.looks, item.brains, rate.scale());
rate.add(item);
});
var best = (rate.best());
console.log('best: %s (%s)', best.data.name, best.rating);
var worst = (rate.worst());
console.log('worst: %s (%s)', worst.data.name, worst.rating);
console.log(' ----------- rating (brains biased) --------- ');
var rate2 = Fools.rate()
.prop('brains', null, 5)
.prop('looks');
_.each([peter, lois, stewie, brian, meg], function (item) {
console.log('rating of %s: %s', item.name, rate2(item)); // echoes the rating but doesn't record the candidate
rate2.add(item); // records the candidate for relative comparison
});
best = (rate2.best());
console.log('best: %s (%s)', best.data.name, best.rating);
worst = (rate2.worst());
console.log('worst: %s (%s)', worst.data.name, worst.rating);
console.log(' ----------- rating (age biased) --------- ');
var rate2 = Fools.rate()
.prop('brains', null, 2)
.prop('birth_year', function(birth_year){
return 2014 - birth_year
}, 3)
.prop('looks');
_.each([peter, lois, stewie, brian, meg], function (item) {
console.log('rating of %s: %s', item.name, rate2(item)); // echoes the rating but doesn't record the candidate
console.log(' (%s 2 + %s 3 + %s) / %s',
item.brains,
2014 - item.birth_year,
item.looks,
rate.scale());
rate2.add(item); // records the candidate for relative comparison
});
best = (rate2.best());
console.log('best: %s (%s)', best.data.name, best.rating);
worst = (rate2.worst());
console.log('worst: %s (%s)', worst.data.name, worst.rating);
``