A collection of F(unctional) Util(ities). Resistance is futile.
Mostly, these are generic utilities that could conceivably be part of a library like lodash/fp, but for some reason or other are not.
See our changelog
npm i -S futil-js
This package requires lodash/fp, so make sure that's available in your app.
import * as f from futil-js
or
import {x,y,z} from futil-js
The syntax: import f from futil-js is not currently supported.
(fn, a, b) -> fn(a, b) If fn is a function, call the function with the passed-in arguments. Otherwise, return false.
(fn, a, b) -> fn(a, b) If fn is a function, call the function with the passed-in arguments. Otherwise, return fn.
(a, Monoid f) -> f[a] :: f a Binds a function of an object to it's object.
http://ramdajs.com/docs/#converge
(f, g) => x => f(g(x))(x)
A combinator that combines compose and apply
([f, g]) -> !f(x) && !g(x) Creates a function that checks if none of the predicates return truthy when invoked with the arguments it receives.
http://ramdajs.com/docs/#ifElse + lodash shorthand and f.callOrReturn support
http://ramdajs.com/docs/#when + lodash shorthand and f.callOrReturn support
http://ramdajs.com/docs/#unless + lodash shorthand and f.callOrReturn support
when curried with Boolean
when curried with exists
...fns:functions -> map:function Runs a map function that runs a flow of the functions passed in to this method.
f -> x -> f(find(f, x))
A version of find that also applies the predicate function to the result. Useful in gets
map :: (a -> b) -> [a] -> [b]
Maps a function over an iterable. Works by default for Arrays and Plain Objects.
deepMap :: (a -> b) -> [a] -> [b]
Maps a function over a recursive iterable. Works by default for nested Arrays, nested Plain Objects and mixed
nested Arrays and Plain Objects. Also works for any other iterable data type as long as
two other values are sent: a mapping function, and a type checker (See the
unit tests for deepMap).
These are conversions of lodash fp methods.
getIn, hasIn, includesIn, pickIn
lodash/fp is great, but sometimes the curry order isn't exactly what you want.
These methods provide alternative orderings that are sometimes more convenient.
The idea of In methods is to name them by convention, so when ever you need a method that actually takes the collection first (e.g. a get where the data is static but the field is dynamic), you can just add In to the end (such as getIn which takes the object first)
extendOn, defaultsOn, mergeOn, setOn
lodash/fp likes to keep things pure, but sometimes JS can get pretty dirty.
These methods are alternatives for working with data that--for whatever the use case is--needs to be mutable
Any methods that interact with mutable data will use the On convention (as it is some action occuring On some data)
mapIndexed, eachIndexed, reduceIndexed, mapValuesIndexed
lodash/fp caps iteratees to one argument by default, but sometimes you need the index.
These methods are uncapped versions of lodash's methods.
Any method with uncapped iteratee arguments will use the Indexed convention.
join:string -> data:array -> result:string Joins an array after compacting.
data:array -> result:string Compacts and joins an array with '.'
data:array -> result:array Returns an array of elements that are repeated in the array.
([[], [], []]) -> [[], []] Takes any number of ranges and return the result of merging them all.
Example: [[0,7], [3,9], [11,15]] -> [[0,9], [11,15]]
insertAtIndex -> (index, val, string) -> string Insert a string at a specific index.
Example: (1, '123', 'hi') -> 'h123i'
(val, array) -> array Return the array with the val pushed
[a, b...] -> a -> b Creates a function that always return the element next to the one received, based on an input previously received.
[k, v, a] -> result:object Creates an object from an array by generating a key/value pair by running each element through the key and value mapper functions.
(k, v) -> {k: v} Creates an object with a key and value.
(v, k) -> {k: v} Flipped version of singleObject.
({a, b}) -> [{a}, {b}] Breaks an object into an array of objects with one key each.
Remove properties with falsey values.
Example: ({ a: 1, b: null, c: false }) -> {a:1}
Check if the variable is an empty object ({}).
Check if the variable is not an empty object ({}).
Omit properties whose values are empty objects.
Example: { a:1, b:{}, c:2 } -> {a:1, c:2}
(TODO remame to omitEmptyObjects)
Checks if an object's property is equal to a value.
Returns true if object keys are only elements from signature list. (but does not require all signature keys to be present)
TODO
from:string -> to:string: -> target:object -> result:object
Rename a property on an object.
Example: renameProperty('a', 'b', {a:1}) -> {b:1)
Just like mongo's $unwind.
Example: { x:['a','b'], y:1 } -> [{ x:'a', y:1 }, { x:'b', y:1 }]
Flatten an object with the paths for keys.
Example: { a: { b: { c: 1 } } } => { 'a.b.c' : 1 }.
Unlatten an object with the paths for keys.
Example: { 'a.b.c' : 1 } => { a: { b: { c: 1 } } }.
Deprecated in favor of lodash update Applies a map function at a specific path
Example: mapProp(double, 'a', {a: 2, b: 1}) -> {a: 4, b: 1}.
_.get that returns the target object if lookup fails
_.get that returns the prop if lookup fails
Flipped alias
A _.get that takes an array of paths and returns the value at the first path that matches
Flipped cascade
A _.get that takes an array of paths and returns the first path that matched
A _.get that takes an array of paths and returns the first value that has an existing path
A _.get that takes an array of paths and returns the first path that exists
{a:x, b:y} -> [{...x, a}, {...y, b}] Opposite of _.keyBy. Creates an array from an object where the key is merged into the values with a property with the name passed in. If no key is passed in, it will use each prop's key as both the key and value.
(from, to) -> simpleDiff Produces a simple flattened (see flattenObject) diff between two objects. For each (flattened) key, it produced a from and a to value. Note that this will omit any values that aren't present in the deltas object.
(from, to) -> [simpleDiffChanges] Same as simpleDiff, but produces an array instead of {field, from, to} objects instead of {field: {from, to}
'asdf' -> '(asdf)' Wraps a string in parenthesis.
Maps _.trim through all the strings of a given object or array.
string -> string Converts strings like variable names to labels (generally) suitable for GUIs, including support for acronyms and numbers. It's basically _.startCase with acronym and number support.
string -> {value:string, label:string} Creates a {value, label} which applies autoLabel the string parameter on puts it on the label property, with the original on the value property. You can also pass in an object with value or with both value and label.
[string] -> [{value:string, label:string}] Applies autoLabelOption to a collection. Useful for working with option lists like generating select tag options from an array of strings.
regex -> string -> bool Just like ramda test, creates a function to test a regex on a string.
options:string -> string -> regex A curried implementation of RegExp construction.
options:string -> string -> (string -> bool) Makes and tests a RegExp with makeRegex and testRegex.
string -> string -> bool Returns true if the second string matches any of the words in the first string.
string -> string -> bool Returns true if the second string matches all of the words in the first string.
regex -> string -> [Range:[number, number]] Returns an array of postings (position ranges) for a regex and string to test.
start:string -> end:string -> postings:[Range:[number, number]] -> input:string -> string Highlights postings in a string wrapping in start and end.
Example: ('<b>', '<b>', [[0,1]], 'hi') -> '<b>h</b>i'
number -> bool Returns true if number is greater than one.
Language level utilities
Just throws whatever it is passed.
Tap error will run the provided function and then throw the first argument. It's like _.tap for rethrowing errors.
Negated _.isNil
Returns true if the input has a length property > 1, such as arrays, strings, or custom objects with a lenth property
A curried, flipped add
A lens is a getter and setter pair, which can be used to interface to some part of an object graph. Methods that operate on lenses can encapsulate common operations independent of knowledge of their surrounding context. Unlike some traditional functional lenses (like Ramda's), the set methods here are generally mutable.
An object lens is simply an object that has a get and set function.
An example of this is a mobx boxed observable.
A function lens is a lense expressed as a single function that takes the value to set or returns the current value if nothing is passed. Examples of this in the wild are knockout observables and jquery plugin api style methods.
The utilities in this library expect can accept either kind of lens, and utilities are provided to seamless convert between the two.
Lens stubs are primarily a reference implementation, but are useful for testing and mocking purposes
Takes a value and returns a function lens for that value
Takes a value and returns a object lens for that value
Methods to convert between lens types
Converts a function lens an object lens
Converts an object lens to a function lens
This the first main way you'll generally interact with the lens API
lensProp :: string -> object -> { get: () -> T, set: T -> T }
Creates an object lens for a given property on an object. .get returns the value at that path and set places a new value at that path
{a: T, b: T} -> {a:ObjectLens, b:ObjectLens}
Takes an object and returns an object with lenses at the values of each path. Basically mapValues(lensProp).
Lens -> T
Gets the value of the lens, regardless of if it's a function or object lens
Lens -> (() -> T)
Returns a function that gets the value of the lens, regardless of if it's a function or object lens
T -> Lens -> T
Sets the value of the lens, regardless of if it's a function or object lens
Creates a function that will set a lens with the provided value
Takes a lens and negates its value
Returns a function that will set a lens to true
Returns a function that will set a lens to false
Aspects provide a functional oriented implementation of Aspect Oriented Programming. An aspect wraps a function and allows you run code at various points like before and after execution. Notably, aspects in this library allow you to have a shared state object between aspects and are very useful for automating things like status indicators, etc on functions.
There is a lot of prior art in the javascript world, but most of them assume a vaguely object oriented context.
The implementation in futil-js is done in just 20 lines of code and seems to capture all of the use cases of AOP.
Note: To do OO style AOP with this these aspects, just use lodash's
_.updatemethod and optionallyboundMethodfromfutilifthismatters
Caveat: While you can and should compose (or
_.flow) aspects together, don't put non aspects in the middle of the composition. Aspects rely on a.stateproperty on the wrapped function that they propagate through, but the chain will break if a non-aspect is mixed in between. Additionally, if you need external access to the state, make sure the aspects are the outer most part of the composition so the.stateproperty will be available on the result of the composition.
aspect: {options} -> f -> ()
The aspect api takes an options object and returns a function which takes a function to wrap.
The wrapped function will be decorated with a state object and should referentially transparent (e.g. it can be called in the same way as the function it's replacing).
Options supports the following parameters:
| Name | Description |
|---|---|
init: (state) -> () |
A function for setting any inital state requirements. Should mutate the shared state object. |
after: (result, state, params) -> () |
Runs after the wrapped function executes and recieves the shared state and the result of the function. Can be async. |
before: (params, state) -> () |
Runs before the wrapped function executes and receves the shared state and the params passed to the wrapped function. Can be async. |
onError: (error, state, params) -> () |
Runs if the wrapped function throws an error. If you don't throw inside this, it will swallow any errors that happen. |
always: (state, params) -> () |
Runs after the wrapped function whether it throws an error or not, similar to a Promise.catch |
Example Usage:
let exampleAspect = aspect({
before: () => console.log('pre run'),
after: () => console.log('post run')
})
let f = () => console.log('run')
let wrapped = exampleAspect(f)
wrapped()
// Logs to the console:
// pre run
// run
// post runThis is a synchronous version of aspect, for situations when it's not desirable to await a method you're adding aspects to. The API is the same, but things like onError won't work if you pass an async function to the aspect.
There are a few basic aspects included because they seem to be universally useful.
All of the provided aspects take an extend function to allow customizing the state mutation method (e.g. in mobx, you'd use extendObservable).
If null, they default to defaultsOn from futil-js - check the unit tests for example usage.
Logs adds a logs array to the function state and just pushes in results on each run
Captures any exceptions thrown and set it on an error error it puts on state
Captures any exceptions thrown and pushes them sequentially into an errors array it puts on state
Adds a status property that is set to processing before the wrapped function runs and succeeded when it's done or failed if it threw an exception. Also adds shortcuts on state for processing, succeeded, and failed, which are booleans which are based on the value of status. Also adds a setStatus method which is used internally to update these properties.
Sets status to null after provided timeout (default is 500ms) elapses. If a null timeout is passed, it will never set status to null.
Prevents a function from running if it's state has processing set to true at the time of invocation
Flows together status, clearStatus, concurrency, and error, taking extend and timeout as optional parameters to construct the aspect
Utility for marking functions as deprecated - it's just a before with a console.warn. Takes the name of thing being deprecated, optionally deprecation version, and optionally an alternative and returns a higher order function which you can wrap deprecated methods in. This is what's used internally to mark deprecations. Includes a partial stack trace as part of the deprecation warning.