Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yannickdot/taskorama
⚙ A Task/Future data type for JavaScript
https://github.com/yannickdot/taskorama
async functional-programming javascript promise tasks
Last synced: about 6 hours ago
JSON representation
⚙ A Task/Future data type for JavaScript
- Host: GitHub
- URL: https://github.com/yannickdot/taskorama
- Owner: YannickDot
- License: mit
- Created: 2017-01-04T23:08:48.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-06-23T20:36:51.000Z (over 6 years ago)
- Last Synced: 2024-10-01T10:48:41.698Z (about 1 month ago)
- Topics: async, functional-programming, javascript, promise, tasks
- Language: JavaScript
- Homepage:
- Size: 232 KB
- Stars: 89
- Watchers: 3
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Taskorama
Taskorama is a Task/Future data type for JavaScript
Taskorama is an implementation of the Task data type.
It is used to express **concurrent**, **asynchronous** and **cancellable computations** using **functional programming** constructs.
The semantics is pretty close to the ones provided by Promises but it has many subtle differencies explained in the [Rationale](#rationale) section.
Here is an example of how you can use them :
```js
import Task from 'taskorama'
// Let's create a Task
const myTimeoutTask = Task(function (reject, resolve) {
// complete task succesfully after 3s
let timer = setTimeout(resolve, 3000)
// execute `cancel` to stop the timeout
let cancel = () => clearTimeout(timer)
return {cancel}
})
// Start `myTimeoutTask`
const myTimeoutExec = myTimeoutTask.fork(
(rej) => console.log('failure:', rej),
(res) => console.log('success:', res),
(err) => console.error('caught error:', err)
)
// Cancel `myTimeoutTask` when you need to !
myTimeoutExec.cancel()
```
It's like a Promise but pure, deferrable and cancellable 🤗
## Install
```sh
> npm install --save taskorama
```
or
```sh
> yarn add taskorama
```
or CDN
```
https://unpkg.com/taskorama
```
## Usage
_The full API docs is available here : [Taskorama Docs](https://github.com/YannickDot/taskorama/wiki/API)_
### Creating a Task
```js
const task = Task((resolve, reject) => {
// Do your thing ...
resolve(the_result)
// An error ?
reject(the_error)
// A closure that cancels stuff running in the task
const cancel = () => console.log('cancelled !')
// return it inside an object
return {cancel}
})
```
### Running (forking) and cancelling a Task
```js
// the failure handler
const failureEffect = (err) => {}
// the success handler
const successEffect = (res) => {}
// the error handler (optional)
const errorEffect = (res) => {}
// Let's start the task
const runningTask = task.fork(
failureEffect,
successEffect,
errorEffect
)
// Let's cancel it
runningTask.cancel() // --> 'cancelled !'
```
# Rationale
I created this lib when I tried to implement Tasks in JavaScript in order to understand how do they work.
I like using Promises but they have major design flaws IMHO :
- They run as soon as the promise is declared : what if I want to defer the computation ?
- They are **async by default** : i.e. `Promise.resolve(2)` ***always*** runs on the next tick
- They are not cancellable (it's unfortunate that we can't cancel `window.fetch` http request when necessary)
Tasks happen to be really simple and have richer semantics than Promises :
- Tasks are pure : they do not perform any side-effect as long as they are not executed by calling `.fork()` .
- Tasks make a clear separation between **definition** and **execution**, while Promises mix the two. **@andrestaltz** explained it way better than me in [this comment](https://gist.github.com/jakearchibald/199f4e44880aa07c0b78f025238d14ed#gistcomment-2014667) and [this post](https://staltz.com/promises-are-not-neutral-enough.html)
So I decided to replace Promises by Tasks in my code in order to separate pure data processing resulting of an async computation and side-effects.
I started this project after watching [this talk](https://www.youtube.com/watch?v=uQ1zhJHclvs) about Observables.
The internals of Taskorama are similar to the one used in case explained in this video.
## License
Taskorama is released under the MIT license. See LICENSE for details.