README.md

Description

Erre is a modern, performant and tiny (~0.5kb minified) streams script using generators that runs on modern browsers and node. It can be used to manage any kind of sync and async event series and it's inspired to bigger libraries like:

• baconjs
• RxJS

Installation

npm i erre -S

Usage

You can use it to create and manipulate simple event streams

import erre from 'erre'

const stream = erre(
  string => string.toUpperCase(),
  string => [...string].reverse().join('')
)

stream.on.value(console.log) // EVOL, ETAH

stream.push('love')
stream.push(async () => await 'hate') // async values

It supports async and sync event chains thanks to ruit

const userNamesStream = erre(
  async user => await patchUsers(user), // async function returning a users collection
  users => users.map(user => user.name)
)

userNamesStream.on.value(console.log) // ['John'...]

userNamesStream.push({
  name: 'John',
  role: 'Doctor',
  age: 24
})

API

erre(...functions)

@returns stream

Create an erre stream object. The initial functions list is optional and it represents the chain of async or sync events needed to generate the final stream output received via on.value callbacks

stream

It's an enhanced Generator object having additional API methods

stream.push(value)

@returns stream

Push a new value into the stream that will be asynchronously modified and returned as argument to stream.on.value method

Example

const stream = erre()
stream.on.value(console.log) // 1
stream.push(1)

stream.on.value(callback)

@returns stream

Add a callback that will be called receiving the output of the stream asynchronously

Example

const stream = erre(val => val + 1)

stream.on.value(console.log) // 2
stream.on.value(val => console.log(val * 2)) // 4

stream.push(1)

stream.on.error(callback)

@returns stream

Add a callback that will be called in case of errors or promise rejections during the output generation

Example

const stream = erre(val => {
  throw 'error'
})

stream.on.value(console.log) // never called!!
stream.on.error(console.log) // 'error'

stream.push(1)

stream.on.end(callback)

@returns stream

Add a callback that will be called when the stream will be ended

Example

const stream = erre()

stream.on.end(() => console.log('ended!')) // ended!

stream.end()

stream.off.value(callback)

@returns stream

@throws Error if callback isn't registered

Removes a previously-registered callback

Example

const stream = erre()

const handler = (value) => console.log('handling', value)
stream.on.value(handler)
stream.push(1) // handler called, logs: handling 1

stream.off.value(handler)
stream.push(2) // handler is not called

// throws, because the handler is not registered
const someOtherHandler = () => console.log(`don't register me`)
stream.off.value(someOtherHandler)

stream.off.error(callback)

@returns stream

@throws Error if callback isn't registered

stream.off.end(callback)

@returns stream

@throws Error if callback isn't registered

stream.connect(function)

@returns stream

Enhance the stream adding a new operation to the functions chain to generate its output

Example

const stream = erre(val => val + 1)

stream.on.value(console.log) // 2, 4
stream.push(1)

// enhance the stream
stream.connect(val => val * 2)
stream.push(1)

stream.end()

@returns stream

End the stream

Example

const stream = erre(val => val + 1)

stream.on.value(console.log) // 2
stream.push(1)

// end the stream
stream.end()

// no more events
stream.push(1)
stream.push(1)
stream.push(1)

stream.fork()

@returns new stream object

Create a new stream object inheriting the function chain from its parent

Example

const stream = erre(val => val + 1)

stream.on.value(console.log) // 2, 3
stream.push(1)

const fork = stream.fork()
fork.on.value(console.log)
fork.connect(val => val * 10) // 20, 60

// 2 independent streams
fork.push(1)
stream.push(2)
fork.push(5)

stream.next(value)

@returns { done: true|false, value: Promise|undefined }

Run a single stream sequence (without dispatching any event) returning as value a promise result of the stream computation. If the stream was ended the done value will be true and the value will be undefined.

Example

const stream = erre(val => val + 1)

stream.on.value(console.log) // never called

const { value } = stream.next(1)

value.then(console.log) // 2

erre.cancel()

Static function that if returned by any of the stream functions chain can be used to filter or stop the computation

Example

const stream = erre(val => {
  if (typeof val !== 'number') return erre.cancel()
  return val + 1
})

stream.on.value(console.log) // 2, 3
stream.push(1)
stream.push('foo') // filtered
stream.push('1') // filtered
stream.push(2)

erre.off()

Static function that if returned by any of the subscribed callbacks can be used to unsubscribe it

Example

const stream = erre(val => val + 1)

stream.on.value(val => {
  // if this condition will be matched, this callback will be unsubscribed
  if (typeof val !== 'number') return erre.off()
  console.log(val)
}) // 2
stream.push(1)
// this value will let the previous listener unsubscribe itself
stream.push('foo')
stream.push('1')
// this value will not be logged because the stream.on.value was unsubscribed
stream.push(2)

erre.install(name, fn)

@returns erre

Extend erre adding custom API methods. Any plugin must have at lease a name (as string) and a function

Example

// alias the `console.log` with `erre.log`
erre.install('log', console.log)

const stream = erre(val => val + 1)

stream.on.value(erre.log) // 2, 3
stream.push(1)
stream.push(2)

TODO List

• erre.fromDOM - to stream DOM nodes events
• erre.merge - to merge multiple stream results into one