Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gianlucaguarini/erre
Modern, performant and tiny (~0.5kb) streams script using generators for browsers and node.js
https://github.com/gianlucaguarini/erre
Last synced: 2 days ago
JSON representation
Modern, performant and tiny (~0.5kb) streams script using generators for browsers and node.js
- Host: GitHub
- URL: https://github.com/gianlucaguarini/erre
- Owner: GianlucaGuarini
- License: mit
- Created: 2017-12-16T17:29:03.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2023-09-22T20:57:00.000Z (about 1 year ago)
- Last Synced: 2024-09-16T13:18:14.271Z (17 days ago)
- Language: JavaScript
- Homepage:
- Size: 214 KB
- Stars: 30
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[![Build Status][ci-image]][ci-url]
[![NPM version][npm-version-image]][npm-url]
[![NPM downloads][npm-downloads-image]][npm-url]
[![MIT License][license-image]][license-url]
## 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](https://baconjs.github.io/)
- [RxJS](http://reactivex.io/rxjs/)
## Installation
```sh
npm i erre -S
```
## Usage
You can use it to create and manipulate simple event streams
```js
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](https://github.com/GianlucaGuarini/ruit)
```js
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`](#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`](#streamonvaluecallback) callbacks
### stream
It's an enhanced [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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`](#streamonvaluecallback) method
Example
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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`](#errefunctions)
Extend erre adding custom API methods. Any plugin must have at lease a `name` (as string) and a `function`
Example
```js
// 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
- [x] [erre.fromDOM](https://github.com/GianlucaGuarini/erre.fromDOM) - to stream DOM nodes events
- [x] [erre.merge](https://github.com/GianlucaGuarini/erre.merge) - to merge multiple stream results into one
[ci-image]: https://img.shields.io/github/actions/workflow/status/gianlucaguarini/erre/test.yml?style=flat-square
[ci-url]: https://github.com/gianlucaguarini/erre/actions
[license-image]:http://img.shields.io/badge/license-MIT-000000.svg?style=flat-square
[license-url]:LICENSE
[npm-version-image]:http://img.shields.io/npm/v/erre.svg?style=flat-square
[npm-downloads-image]:http://img.shields.io/npm/dm/erre.svg?style=flat-square
[npm-url]:https://npmjs.org/package/erre