A fantasy-land compliant monadic IO library for Node.js.

Building a simple cli that tells you if a number is even can look something like this:

#!/usr/bin/node

const io = require('future-io')
const ioProcess = require('future-io/node/process')

const even = ioProcess.argv
  .map(argv => (parseInt(argv[2]) % 2) === 0)
  .chain(even => ioProcess.stdout.write('Is even: ' + even))

io.unsafePerform(even)

To get you started fast this library mimics the interface of the native node modules. It just returns io's instead of taking callbacks!

Getting complete coverage of all io related functionality in node is still a work in progress. If you're missing something, please feel free to open an issue or pull request.

At the moment the following modules are exported. For some recipes demonstrating their use check out the examples directory.

This will execute the io. If the io represents an error value, this function will throw. If this is not what you want, use IO.prototype.catch.

IO implements the fantasy-land Functor, Apply and Monad specifications.

Often you'll find the need to define your own io returning functions, or wrap functions provided by a library. Luckily, this is very simple:

  const io = require('future-io')

  // Wrapping a function performing some side effects in an IO.
  // The `customOperation` function should return a promise, task or plan value.
  const customIO = io.wrapMethod(
    'customOperation',
    customOperation
  )

Testing code performing a lot of IO is usually pretty painful. Not so when using future-io!

Simply use fakePerform instead of unsafePerform to execute your IO actions in tests. Now you can step through your io functions step by step, checking the arguments being passed in and choosing values to return.

fakePerform() return an object with three methods:

• take(actionName): Proceed until the next action call. Assert it has type actionName. Return a promise containg the arguments the action is being called with as an array
• put(returnValue): Call after a take resolves to send a return value. Also call this when not returning a value, to ensure execution of the IO continues.
• error(ioError): Like put, but returns an error value.

When the io execution finishes, fakePerform triggers a last end action. This action is passed an ioError, if one exists, in the first-argument position.

import test from 'ava'
import {fakePerform} from 'future-io'
import ioProcess from 'future-io/node/process'

test('logging the current working directory', async t => {
  const io = ioProcess.cwd().chain(ioProcess.stdout.write)
  const { put, take } = fakePerform(io)
  const cwd = '/home/foo'

  await take('process.cwd')
  put(cwd)

  const [ loggedCwd ] = await take('process.stdout.write')
  t.is(loggedCwd, cwd)
  put()

  const [ ioError ] = await take('end')
  t.falsy(ioError)
})

import co from 'co'
import {fakePerform} from 'future-io'
import ioProcess from 'future-io/node/process'
import assert from 'assert'

it('logs the current working directory', co.wrap(function* () {
  const io = ioProcess.cwd().chain(ioProcess.stdout.write)
  const { put, take } = fakePerform(io)
  const cwd = '/home/foo'

  yield take('process.cwd')
  yield put(cwd)

  const [ loggedCwd ] = yield take('process.stdout.write')
  assert.equal(loggedCwd, cwd)
  put()

  const [ ioError ] = yield take('end')
  assert.ifError(ioError)
}))