fun-helpers
fun-helpers
is a small collection of simple functions I've got used to use daily with promises. I finally packaged them here. It's very similar to fn.js or fun.js except its main purpose is to be "Promise-friendly" and as light as possible (no fancy autoCurry).
What I mean by "Promise-friendly" is that every method of this API returns a single-parameter function, ready to be used in your then
s. For example map
will not take two arguments but only one, the mapping function, and will return a function taking an array as parameter and returning the result of applying the mapping function over it.
Example
var lowerNames = // get all users' names // call method from each string // make a function neutral (return its first argument)
Compatibility
Written for Node.js but should be compatible with any modern browser (including Internet Explorer ≥ 9) using browserify
or the pre-built versions in dist
folder.
Installation
For Node.js:
npm install fun-helpers
If you target browser and don't use browserify
, you can download a pre-built standalone version:
- standard (6.3K)
- minified (5.2K)
- sourcemapped for debugging (16K)
- If you don't use any loading system, a global variable
Fun
will contain the API.
API
Read next section if you don't know how to read this API.
Note: All methods are safe (they do not mutate their input), and will have no side-effect in case of multiple then
s on same promise.
all(test)
any -> boolean
->[any] -> boolean
- Checks if all elements of the promised array pass the test
any(test)
any -> boolean
->[any] -> boolean
- Checks if any element in the promised array pass the test
call(name, args…)
(string, any…)
->Object -> any
- Calls method "name" of the promised object, with optional additional arguments
defaults(values)
Object
->Object -> Object
- Sets all undefined keys of promised object to those from input object
equals(value)
any
->any -> boolean
- Checks if promised value is identical (triple equal) to input value
every(test)
is an alias toall(test)
filter(test)
any -> boolean
->[any] -> [any]
- Filters promised array, keeping only values passing the test
get(property)
string
->Object -> any
- Returns property by its name from promised object
ifndef(default)
-> any
->any -> any
- Returns default value if promised value is null or undefined (default can be a function returning the value, or directly the fallback value)
isA(type)
string or function
->any -> boolean
- Checks promised value is of the given type (can be a type name or a constructor function)
is(value)
is an alias toequals(value)
map(transform)
any -> any
->[any] -> [any]
- Returns the result of applying transform on every item of promised array
merge
- Sets all keys of promised object (defined or not, it overwrites) to those from input object
neutral(foo)
any… -> any
->any -> any
- Will apply foo on promised value and return promised value, whatever foo was supposed to return
- This is especially useful for loggers or function that do not return their input and would break the chain
not(foo)
any -> boolean
->any -> boolean
- Applies foo on promised value and returns reversed result
partial(foo, fixedArgs…)
(any… -> any), any…
->any… -> any
- The usual partial tool, will return a function like foo but with the n first parameters fixed
promisify(foo, PromiseImpl)
(any…, (Error, any<T>))
->any… -> Promise<T>
- Transform a callback-style asynchronous function into a function returning a promise (provide
Promise
implementation if no globalPromise
object exists)
- Transform a callback-style asynchronous function into a function returning a promise (provide
reduce(foo)
any, any, number, [any] -> any
->[any] -> any
- Applies a reduction on promised array
reduceRight
is likereduce
but will work with reversed arrayresolve(value)
any
->any -> any
- Returns a function returning the given value whatever its input is.
set(property, value)
string, any
->Object -> Object
- Sets the property of promised object to given value
set(object, property)
Object, string
->any -> Object
- Sets the property of given object to promised value
some
is an alias toany(test)
spread(foo)
any… -> any
->[any] -> any
- Will create a new function accepting a single Array argument, and returning the result of
foo
applied to those spread arguments - An additional parameter can be passed to set foo's
this
- Will create a new function accepting a single Array argument, and returning the result of
unset(property)
string
->Object -> Object
- Deletes property from promised object
How to read type notation
Notation used here is inspired by (more and more common) Haskell type formatting:
(x, y) -> z
Can be read as a function taking two arguments of type x and y, and returning a value of type z.
Take all(test)
for example:
all
(any -> boolean)
->[any] -> boolean
Means all
takes a parameter like function (anything) { return aBoolean }
, and returns a result like function (array) { return aBoolean }
.