state-buffer

[deprecated]: Before finishing this I discovered inflight which has both a simpler interface and solves the problem in a smarter way. I recommend using inflight.

Manage in-flight application state changes.

Installation

$ npm install state-buffer

Usage

const buffer = require('state-buffer')

// wrap an async function
const b = buffer((data, end) => {
  // do async stuff
  end(err, res)
})

// call the wrapped async function
// and call a callback when done.
// only a single call is allowed
b(data, (err, res) => {
  if (err) return console.error('uh oh, error state')
  console.log('all good!')
})

Retries

state-buffer doesn't retry when locked. Here's an example retry engine:

const buffer = require('state-buffer')
const b = queue(queueHandler)

const buffer = []
b.on('overflow', val => buffer.push(val))
b.on('finish', () => {
  if (!buffer.length) return
  b(buffer.shift())
})

API

b = buffer(data, cb(end))

Create a state buffer that executes a function when called. end must be called when done to unlock the buffer.

b(data, cb)

Pass data into the state buffer, calling the callback once done. The state buffer is locked until the callback is called, and will emit an 'overflow' event if multiple writes occur.

b.on(event, cb)

Listen for events.

locked = b.locked

Return whether or not the state buffer is locked.

Events

error     error occurred
start     started working
finish    finished working
success   finished successfully
overflow  received data while locked

Why?

Optimistic updates within your application state are dangerous if rollbacks aren't dealt with properly. state-buffer manages these updates in a non-destructive way while also taking care of race-conditions. This approach is inspired by how Facebook's Relay handles mutation persistance.

License

MIT