FPO (/หefpล/) is an FP Library for JavaScript. The main aesthetic difference is that the FPO.*
core API methods are all styled to use named-arguments (object parameter destructuring) instead of individual positional arguments.
// positional arguments
foo( 1, 2, 3 );
// named arguments
foo({ z: 3, x: 1, y: 2 });
Not only do named-arguments eliminate having to remember a method signature's parameter order -- named arguments can be provided in any order! -- they also make skipping optional parameters (to apply defaults) simple.
This elimination of ordering concern and/or skipping arguments particularly comes in handy when you're currying. You don't have to juggle the parameter order at all; just pass in whichever named argument(s) you want, in whatever sequence you need!
The other benefit is that these API methods will automatically work with your program's named-argument style functions. If you need to interoperate between both styles of function parameters in your program, adapt either style to the other using the FPO.apply(..)
and FPO.unapply(..)
methods.
For convenience and familiarity sake, FPO also exposes all its methods in the traditional positional argument form, under FPO.std.*
. These methods are very similar to their equivalents in Ramda, for example.
Note: If you're not fully confident in your FP skills, I've written a book on FP in JavaScript: Functional-Light JavaScript. Go check it out!
This library uses ES6+ features. If you need to support ES<=5 environments, transpile it first (with Babel, etc).
// the classic/traditional method style
// (on the `FPO.std.*` namespace)
FPO.std.reduce(
(acc,v) => acc + v,
undefined,
[3,7,9]
); // 19
// FPO named-argument method style
FPO.reduce({
arr: [3,7,9],
fn: ({acc,v}) => acc + v
}); // 19
Instead of needing to provide an undefined
placeholder in the second argument position to skip specifying an initial value, named-argument style allows us to just omit that argument. We also specified arr
first and fn
second just to show order doesn't matter anymore!
As with most FP libraries, all public FPO methods are curried. Currying with named-arguments (in any sequence!) is a breeze:
var f = FPO.reduce({ arr: [3,7,9] });
// later:
f( {fn: ({acc,v}) => acc + v} ); // 19
f( {fn: ({acc,v}) => acc * v} ); // 189
The equivalent using a standard FP library would look like:
var f = curry( flip( partialRight( reduce, [[3,7,9]] ) ) )( 0 );
f( (acc,v) => acc + v ); // 19
Phew, that's a lot of argument juggling! FPO eliminates all that noisy distraction.
-
See Core API for documentation on all the methods in the
FPO.*
namespace. -
See Standard API for documenation on the methods in the
FPO.std.*
namespace.All core methods have a standard positional-parameter form available under the
FPO.std.*
namespace. In many respects, their conceptual behavior is the same, but in some cases there's some differences to be aware of.There are also a few methods on the
FPO.std.*
namespace that have no equivalent in the core API as they are unnecessary or don't make sense.
What if you have a traditional parameter-style function you want to use with one of the object-parameter style FPO API methods? Adapt it using the object-parameter-aware FPO.apply(..)
:
// traditional-parameter style function
function add(acc,v) { return acc + v; }
FPO.reduce({
arr: [3,7,9],
fn: FPO.apply( {fn: add} )
}); // 19
Adapting isn't limited to just interoperating with FPO methods. You can use FPO.apply(..)
and FPO.unapply(..)
to seamlessly adapt between functions of both styles in your own application code:
// note: cb is expected to be an "error-first" style
// traditional callback function
function ajax(url,cb) { .. }
// our object-parameter style function
function onResponse({ resp, err }) {
if (!err) {
console.log( resp );
}
}
// adapt `ajax(..)` to accept named arguments
var request = FPO.apply( {fn: ajax} );
// now we can provide arguments in any order!
request({
cb:
// adapt the object-parameter style `onResponse(..)`
// to work as a standard positional-argument function, as
// expected by `ajax(..)`
FPO.unapply( {fn: onResponse, props:["err","resp"]} ),
url: "http://some.url"
});
What if you have a function that expects a certain named parameter, but it needs to accept a differently named argument? For example:
function uppercase({ str }) { return str.toUpperCase(); }
FPO.map( {fn: uppercase, arr: ["hello","world"]} );
// TypeError (`str` is undefined)
The problem here is that FPO.map(..)
expects to call its mapper function with a v
named argument, but uppercase(..)
expects str
.
FPO.remap(..)
-- despite the name similarity, no particular relationship to FPO.map(..)
, except that it's our example -- lets you adapt a function to remap its expected named parameters:
function uppercase({ str }) { return str.toUpperCase(); }
FPO.map( {
fn: FPO.remap( {fn: uppercase, args: {str: "v"}} ),
arr: ["hello","world"]
} );
// ["HELLO","WORLD"]
Note: The FPO.remap(..)
utility passes through any non-remapped arguments as-is.
The exchange we make for not needing to remember or juggle argument order is that we need to know/remember the parameter names. For example, FPO.reduce(..)
expects named arguments of fn
, v
, and arr
. If you don't use those names, it won't work correctly.
To aid in getting used to that tradeoff in usability, FPO uses straightforward conventions for parameter names; once learned, it should be mostly trivial to use any of the API methods.
The named argument naming conventions (in order of precedence):
- When a method expects a function, the named argument is
fn
. - When a method expects a number, the named argument is
n
. - When a method expects a value, the named argument is
v
. - When a method expects an array of functions, the named argument is
fns
. - When a method expects a single array, the named argument is
arr
. - When a method expects two arrays, the named arguments are
arr1
andarr2
. - When a method expects a single object-property name, the named argument is
prop
. - When a method expects a list of object-property names, the named argument is
props
. - When a mapper function is called, it will be passed these named arguments:
v
(value),i
(index),arr
(array). - When a predicate function is called, it will be passed these named arguments:
v
(value),i
(index),arr
(array). - When a reducer function is called, it will be passed these named arguments:
acc
(accumulator),v
(value),i
(index),arr
(array). - When a transducer combination function is called, it will be passed these named arguments:
acc
(accumulator),v
(value).
Some exceptions to these naming conventions:
-
FPO.setProp(..)
expects:prop
(object-property name),o
(object),v
(value). -
FPO.partial(..)
expects:fn
(function),args
(object containing the named-argument/value pairs to partially apply). -
FPO.flatten(..)
expects:v
(array),n
(count of nesting levels to flatten out). -
FPO.transduce(..)
expects:fn
(transducer function),co
(combination function),v
(initial value),arr
(array). -
FPO.compose(..)
andFPO.pipe(..)
produce functions that expect a{ v: .. }
object argument. These utilities further assume that each function in the composition expects the output of the previous function to be rewrapped in a{ v: .. }
-style object argument.This also applies to transducers.
FPO.transducers.filter(..)
andFPO.transducers.map(..)
, whether composed together or used standalone, are curried to expect the combination function to be passed to them as a{ v: .. }
-style object argument. -
FPO.reassoc(..)
expects:props
(object withsourceProp: targetProp
remapping key/value pairs),v
(object)
Arity is typically defined as the number of declared parameters (expected arguments) for a function. With traditional style functions, this is just a simple numeric count.
For named-argument style functions, the situation is more nuanced. One interpretation of arity would be a raw count of named-arguments (how many properties present). Another interpretation would limit this counting to only the set of expected named-arguments.
For currying, FPO assumes the straight numeric count interpretation. FPO.curry( {fn: foo, n: 3} )
makes a curried function that accepts the first 3 properties, one at a time, regardless of what they're named.
For unary(..)
, binary(..)
, and nAry(..)
, FPO requires a list of properties (props
) to filter through for the underlying function. FPO.binary({fn: foo, props:["x","y"]})
makes a function that only lets x
and y
named arguments through to foo(..)
.
The strictest definition of currying is that each call only allows through one argument (foo(1)(2)(3)
). That's consistent with how currying works in Haskell, for example.
However, for convenience, most FP libraries in JS use a looser definition of currying where multiple arguments can be passed in with each call (foo(1,2)(3)
).
FPO supports both approaches. FPO.curry(..)
(and FPO.std.curry(..)
) use the stricter one-at-a-time definition -- subsequent arguments in each call are ignored -- while FPO.curryMultiple(..)
(and FPO.std.curryMultiple(..)
) use the looser multiple-arguments definition.
All FPO methods are multiple-curried for convenience.
The distribution library file (dist/fpo.js
) comes pre-built with the npm package distribution, so you shouldn't need to rebuild it under normal circumstances.
However, if you download this repository via Git:
-
The included build utility (
scripts/build-core.js
) builds (and minifies)dist/fpo.js
from source. The build utility expects Node.js version 6+. -
To install the build and test dependencies, run
npm install
from the project root directory. -
Because of how npm lifecycle events (currently: npm v4) work,
npm install
will have the side effect of automatically running the build and test utilities for you. So, no further action should be needed on your part. Starting with npm v5, the build utility will still be run automatically onnpm install
, but the test utility will not.
To run the build utility with npm:
npm run build
To run the build utility directly without npm:
node scripts/build-core.js
A comprehensive test suite is included in this repository, as well as the npm package distribution. The default test behavior runs the test suite using src/fpo.src.js
.
-
You can run the tests in a browser by opening up
tests/index.html
(requires ES6+ browser environment). -
The included Node.js test utility (
scripts/node-tests.js
) runs the test suite. This test utility expects Node.js version 6+. -
Ensure the Node.js test utility dependencies are installed by running
npm install
from the project root directory. -
Because of how npm lifecycle events (currently: npm v4) work,
npm install
will have the side effect of automatically running the build and test utilities for you. So, no further action should be needed on your part. Starting with npm v5, the build utility will still be run automatically onnpm install
, but the test utility will not.
To run the test utility with npm:
npm test
Other npm test scripts:
-
npm run test:dist
will run the test suite againstdist/fpo.js
. -
npm run test:package
will run the test suite as if the package had just been installed via npm. This ensurespackage.json
:main
properly referencesdist/fpo.js
for inclusion. -
npm run test:all
will run all three modes of the test suite. This is what's automatically run when you firstnpm install
the build and test dependencies.
To run the test utility directly without npm:
node scripts/node-tests.js
If you have Istanbul already installed on your system (requires v1.0+), you can use it to check the test coverage:
npm run coverage
Then open up coverage/lcov-report/index.html
in a browser to view the report.
To run Istanbul directly without npm:
istanbul cover scripts/node-tests.js
Note: The npm script coverage:report
is only intended for use by project maintainers. It sends coverage reports to Coveralls.
All code and documentation are (c) 2019 Kyle Simpson and released under the MIT License. A copy of the MIT License is also included.