Rapt is a small package that wraps any value, allowing you to map over it. A bit like Lodash’s chain, or Gulp’s pipe, but for values rather than collections or streams.
Rapt does not exist to reduce the number of characters in your code, nor to make your code run faster. For many, it will not even be the clearest way to write your code. But if, like me, you find it easier to read and understand a list of functions than a variety of assignments, operators and returns, then Rapt might help you enjoy the code you write a little more.
It lends itself to a highly functional style of JS programming, allowing you to work with and transform values without having to assign them to variables. It works best with immutable values (numbers, strings, immutable collections). It is particularly well suited to the latter, and is very satisfying if you hate using let
just so you can reassign an immutable value after modifying it, i.e. let x = Map(); x = x.set('a', 1)
.
It can be used with plain mutable objects and arrays but it may be counter-productive in terms of clarity, as the functions you pass to
Rapt#map()
will no longer be side-effect-free.
Rapt is particularly useful when you want to avoid unnecessarily executing expensive operations, but you don’t want to give up your functional style.
Installation
Rapt is available on npm.
npm install --save rapt
yarn add rapt
Usage
CommonJS
const rapt = // orconst rapt = default
ES Modules
Examples
// without Raptconst processUser = { let userMap = Mapuser if emailHasBeenVerified userMap = userMap return userMap} // with Raptconst processUser =
// without Raptconst countItems = { let arr = _compacthugeArrayOfItems if shouldFilter arr = arr const count = arrlength console return count} // with Raptconst countItems =
Types
Rapt is written using Flow, and works well with it – with the caveat that currently, due to an issue with how Flow handles booleans, the type of the first argument to Rapt#mapIf()
must be true | false
rather than boolean
(no, they’re currently not the same thing!).
Promises / async
Rapt offers first-class support for asynchronous JavaScript with .thenMap()
, but it also works well without that method:
// async function, returns a Promiseconst fetchUserFromDatabase = database // sync function, returns the userObject, mutatedconst processUser = const getUser = // returns a promise because we used fetchUserFromDatabase // Equivalent to:const getUser = // returns a promise because we used fetchUserFromDatabase await
API
.map(Function)
Transform your wrapped value by mapping over it.
// returns 'hello world'
.mapIf(true | false, Function)
Transform your wrapped value by mapping over it, if another value is truthy. Otherwise, do nothing and pass on the value for further chaining.
// returns 'hello world' // returns 'hello'
.flatMap(Function)
Like .map()
, but you should return a Rapt
in your function (equivalent to .map().flatten()
).
// returns 'HELLO WORLD!'
.thenMap(Function)
Like .map()
, but best used in a rapt
chain that wraps a Promise
. It calls Promise.resolve()
on your wrapped value however, so it will also work on immediate values.
const asyncHello = // returns a Promise of 'HELLO WORLD!' // logs 'HELLO WORLD!' // returns a Promise of 'HELLO WORLD!' // logs 'HELLO WORLD!'
.flatten()
Unwraps a “nested” Rapt
(see also .flatMap()
).
// returns 'HELLO WORLD!'
.tap(Function)
Execute a side effect on your wrapped value without breaking the chain.
// logs 'hello' // returns 'hello world' // returns 'hello' // Careful of side effects when working with a mutable value! // returns {a: 1, b: 2}
.forEach(Function)
Execute a side effect on your wrapped value and end the chain (use if you don’t need to return the wrapped value).
// logs 'hello world' // returns undefined
.val()
or .value()
Unwrap your value and return it.
// returns an instance of Rapt // returns 'hello world' value // returns 'hello world'
isRapt()
A predicate function to check if a value is wrapped with Rapt
.
// orconst isRapt = const a = const b = // returns false // returns true // returns false // returns true