Node's Perpetuum Mobile

    rapt

    1.2.1 • Public • Published

    Rapt logo

    npm version Build Status Greenkeeper badge

    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} = require('rapt')
    // or
    const rapt = require('rapt').default

    ES Modules

    import rapt from 'rapt'

    Examples

    import {Map} from 'immutable'
     
    // without Rapt
    const processUser = user => {
      log(user)
      let userMap = Map(user)
      if (emailHasBeenVerified) {
        userMap = userMap.set('verified', true)
      }
      syncWithServer(userMap)
      return userMap
    }
     
    // with Rapt
    const processUser = user =>
      rapt(user)
        .tap(log)
        .map(Map)
        .mapIf(emailHasBeenVerified, u => u.set('verified', true))
        .tap(syncWithServer)
        .val()
    import _ from 'lodash'
     
    // without Rapt
    const countItems = (shouldFilter, hugeArrayOfItems) => {
      let arr = _.compact(hugeArrayOfItems)
      if (shouldFilter) {
        arr = arr.filter(expensiveFilterFunction)
      }
      const count = arr.length
      console.log(`We have ${count} items`)
      return count
    }
     
    // with Rapt
    const countItems = (shouldFilter, hugeArrayOfItems) =>
      rapt(hugeArrayOfItems)
        .map(compact)
        .mapIf(shouldFilter, arr => arr.filter(expensiveFilterFunction))
        .map(items => items.length)
        .tap(count => console.log(`We have ${count} items`))
        .val()

    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 Promise
    const fetchUserFromDatabase = userId => database.child('users').child(userId)
     
    // sync function, returns the userObject, mutated
    const processUser = userObject => doSomethingToTheUserObject(userObject)
     
    const getUser = userId =>
      rapt(userId)
        .map(fetchUserFromDatabase)
        .thenMap(processUser)
        .val() // returns a promise because we used fetchUserFromDatabase
     
    // Equivalent to:
    const getUser = userId =>
      rapt(userId)
        .map(fetchUserFromDatabase)
        .map(userPromise => userPromise.then(processUser))
        .val() // returns a promise because we used fetchUserFromDatabase
     
    await getUser('user001')

    API

    .map(Function)

    Transform your wrapped value by mapping over it.

    rapt('hello')
      .map(s => `${s} world`)
      .val() // 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.

    rapt('hello')
      .mapIf(true, s => `${s} world`)
      .val() // returns 'hello world'
     
    rapt('hello')
      .mapIf(false, s => `${s} world`)
      .val() // returns 'hello'

    .flatMap(Function)

    Like .map(), but you should return a Rapt in your function (equivalent to .map().flatten()).

    rapt('hello')
      .flatMap(s => rapt(`${s} world`).map(s => `${s}!`))
      .map(s => s.toUpperCase())
      .val() // 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 = () => new Promise(resolve => resolve('hello'))
     
    rapt(asyncHello())
      .thenMap(s => `${s} world`)
      .thenMap(s => s.toUpperCase())
      .val() // returns a Promise of 'HELLO WORLD!'
      .then(str => console.log(str)) // logs 'HELLO WORLD!'
     
    rapt('hello')
      .thenMap(s => `${s} world`)
      .thenMap(s => s.toUpperCase())
      .val() // returns a Promise of 'HELLO WORLD!'
      .then(str => console.log(str)) // logs 'HELLO WORLD!'

    .flatten()

    Unwraps a “nested” Rapt (see also .flatMap()).

    rapt('hello')
      .map(s => rapt(`${s} world`).map(s => `${s}!`))
      .flatten()
      .map(s => s.toUpperCase())
      .val() // returns 'HELLO WORLD!'

    .tap(Function)

    Execute a side effect on your wrapped value without breaking the chain.

    rapt('hello')
      .tap(s => console.log(s)) // logs 'hello'
      .map(s => `${s} world`)
      .val() // returns 'hello world'
     
    rapt('hello')
      .tap(s => `${s} world`)
      .val() // returns 'hello'
     
    // Careful of side effects when working with a mutable value!
    rapt({a: 1})
      .tap(obj => {
        obj.b = 2
      })
      .val() // 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).

    rapt('hello')
      .map(s => `${s} world`)
      .forEach(s => console.log(s)) // logs 'hello world'
     
    rapt('hello').forEach(s => `${s} world`) // returns undefined

    .val() or .value()

    Unwrap your value and return it.

    rapt('hello').map(s => `${s} world`) // returns an instance of Rapt
     
    rapt('hello')
      .map(s => `${s} world`)
      .val() // returns 'hello world'
     
    rapt('hello')
      .map(s => `${s} world`)
      .value() // returns 'hello world'

    isRapt()

    A predicate function to check if a value is wrapped with Rapt.

    import {isRapt} from 'rapt'
    // or
    const {isRapt} = require('rapt')
     
    const a = rapt(3)
      .map(x => x * 2)
      .val()
     
    const b = rapt(3).map(x => x * 2)
     
    isRapt(5) // returns false
    isRapt(rapt(5)) // returns true
    isRapt(a) // returns false
    isRapt(b) // returns true

    Install

    npm i rapt

    DownloadsWeekly Downloads

    39

    Version

    1.2.1

    License

    MIT

    Unpacked Size

    13.2 kB

    Total Files

    5

    Last publish

    Collaborators

    • benadamstyles