0.0.1 • Public • Published


Declarative side-effects

npm install affection

npm Build Status Greenkeeper badge

Affection is a library for describing side-effects as plain data and providing composition utilities. This project aims to improve on similar libraries by not using generators.

Generators make testing difficult in that:

  • They can have internal state.
  • Each segment of the function cannot be tested in isolation.
  • Each segment of the function can only be reach after the segments before it.
  • Generators are awkward. Conversing with a generator with next() isn't as simple as function calling.
  • Composition of generators is harder than functions inherently.

So Affection is all about functions, with the goals:

  • Improve testability through the use of pure functions.
  • Improve code reuse through la-a-carte composition of side-effects.

Let's see how we do.


This first example does not use any composition.

import { run, call, callMethod } from 'affection'
const getJSON = url => [
  call(fetch, url),
  resp => [callMethod(resp, 'json')]
async function main () {
  const payload = await run(getJSON(''))

This second example does the same as the first. Here we are using the composition utilities.

import { step, runStep, batchSteps, call, callMethod } from 'affection'
const fetchUrl = url => call(fetch, [url])
const readJSON = resp => callMethod(resp, 'json')
const getJSON = batchSteps([fetchUrl, readJSON].map(step))
async function main () {
  const payload = await runStep(getJSON, '')


The package contains the following:


See defaultHandle for adding more.



call(func: function, args: Array<any>, context: any): Effect

Describes a function call of func.apply(context, args).


callMethod(obj: any, method: String, args: Array<any>): Effect

Describes a method call of obj[method].apply(obj, args)


all(effects: Array<Effect>): Effect

Describes combining effects. Like Promise.all.


race(effects: Array<Effect>): Effect

Describes racing effects. Like Promise.race.


itself(value: any): Effect

Describes a value. This is an identity function for Effects.


defaultHandle(effect: Effect, handle: function): any

Performs the action described by a particular effect. defaultHandle provides the handling for the effects included in Affection. To add more, create a new handle that wraps defaultHandle and pass that to run.

For example, say we want to add a timeout effect:

import { defaultHandle } from 'affection'
export function timeout (duration) {
  return { type: 'timeout', duration }
export function myHandle (effect, handle) {
  if (effect.type === 'timeout') {
    return new Promise(resolve => setTimeout(resolve, effect.duration))
  return defaultHandle(effect, handle)
// Later...
async function main () {
  await run([timeout(1000)], myHandler)
  // Will have waited a second


run(plan: [Effect, function?], handle: function = defaultHandle): any

Executes a plan. A plan is an array where the first element is an Effect to be handled using handle and the second element is a function to call with the result of the Effect. If the function is not provided, execution terminates and the result is returned.


step(makeEffect: any -> Effect): Step

Creates a step. A step is a means of encapsulating an effect without needing a plan (as described by run).

This is hard to understand without an understanding of how run works. The run function is recursively executing plans until there is nothing more to do. A step is a way of saying, "Execute this effect; we might be done, might not." There could be 5 more effects to run or it's the end result; the step doesn't need to know.

This is for code reuse: effects should be decoupled from their consumers.


mapStep(step: Step, transform: function): Step

Creates a new step which will return the result of transform called with the input to the step makeEffect and the result of the Effect.

This is good for passing along context without mucking up simple steps. For example, we are building a dictionary of the most used word for each country. We want to retain the country we are querying about in the result.

const getMostUsedWordInCountry = country => call(MyAPI, country)
const countryWordStep = step(getMostUsedWordInCountry)
const getCountryWord = mapStep(countryWordStep, (result, country) => ({ country, word: result }))
runStep(getCountryWord, 'Canada').then(result => {
  // => { country: 'Canada', word: 'Sorry' }


batchSteps(steps: Array<Step>): Step

Creates a new step which will call each step passing the result of first step to the next and so on.


runStep(step: Step, input: any, handle: function = defaultHandle): any

Executes a step with a given input. Uses run so handle works in the same way.


npm i affection

DownloadsWeekly Downloads






Unpacked Size

11 kB

Total Files


Last publish


  • andrejewski