# cleopatra

> Module for creating and managing promise based pipelines

Latest version **0.2.4** (published 2018-04-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install cleopatra
pnpm add cleopatra
yarn add cleopatra
bun add cleopatra
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.4 |
| Published | 2018-04-20 |
| First published | 2017-09-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 49.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Robert Ontiu |
| Maintainers | liquidsoft |
| Keywords | promise, pipeline |

## Links

- npm: https://www.npmjs.com/package/cleopatra
- Repository: https://github.com/liquidsoft/cleopatra
- Homepage: https://github.com/liquidsoft/cleopatra#readme
- Issues: https://github.com/liquidsoft/cleopatra/issues
- npm.io page: https://npm.io/package/cleopatra

## Dependencies (2)

- [es6-promise](https://npm.io/package/es6-promise.md) ^4.1.1
- [object-assign](https://npm.io/package/object-assign.md) ^4.1.1

## Alternatives

- [byte-size](https://npm.io/package/byte-size.md) — 2.1M weekly downloads
- [speed-limiter](https://npm.io/package/speed-limiter.md) — 16.0K weekly downloads
- [@powersync/node](https://npm.io/package/@powersync/node.md) — 10.9K weekly downloads
- [@ledgerhq/coin-cardano](https://npm.io/package/@ledgerhq/coin-cardano.md) — 1.0K weekly downloads
- [@jayesol/jayeson.lib.streamfinder](https://npm.io/package/@jayesol/jayeson.lib.streamfinder.md) — 1.0K weekly downloads

## Recent versions

- 0.2.4 (latest) — 2018-04-20
- 0.2.3 — 2018-03-16
- 0.2.2 — 2018-03-13
- 0.2.1 — 2018-03-05
- 0.2.0 — 2018-03-05
- 0.1.9 — 2018-02-26
- 0.1.8 — 2018-02-26
- 0.1.7 — 2017-12-08
- 0.1.6 — 2017-10-06
- 0.1.5 — 2017-09-28
- 0.1.4 — 2017-09-25
- 0.1.3 — 2017-09-25
- 0.1.2 — 2017-09-25
- 0.1.1 — 2017-09-25
- 0.1.0 — 2017-09-25
- … 2 more at https://npm.io/package/cleopatra/versions

## README

# cleopatra
Module for creating and managing promise based pipelines.

```js
const {createPipeline} = require("cleopatra");
const myPipeline = createPipeline()
	.from(payload => {
		console.log("Initial payload: ", payload);
	})
	.to(payload => {
		console.log("Final payload: ", payload);
	})
	.through(payload => {
		payload.mutation = "Changed this attribute";
	});

myPipeline.dispatch({ myProp: "Initial value" }).then(result => {
	console.log("Pipeline finished with result", result);
});
```

## Pipeline
A pipeline is a directional set of nodes that digest an object (the **payload**) passing it through to the other nodes. Each node can hold for as long as is needed or even change the payload before passing it further (**async**).

Each pipeline consists of three elements:
- an initial node (**from**)
- an array of inner nodes
- a final node (**to**)

The payload object is sent through the pipeline starting at the initial node and ending at the final node (if no error or rejection is encountered within the process).

A **node** is typically a callback that receives a payload object and does something with it. The callback may return nothing (original payload is passed through), a new payload object, a promise (**async**) or **false** (the pipeline chain is broken and the main promise is rejected).

A **report** node may also be defined that would capture any errors and pass them through.
```js
createPipeline().report(error => console.error(error));
```
**Dispatching** a payload through the pipeline returns a promise that provides the result of the chain.

### Methods
> **from(node)**

Sets the initial node in the pipeline.

> **to(node)**

Sets the last node in the pipeline.

> **through(...nodes)**

Pushes new nodes into the pipeline.

> **report(node)**

Sets the error handling node.

> **intercept(...interceptors)**

Registers a new interceptor into the pipeline.

> **dispatch(payload = {})**

Sends a payload through the pipeline and returns a promise.

> **pipe(...nodes)**

Alias of **through**.

> **capture(node)**

Alias of **to**.

### Interceptors
While a node is typically a function it can be any kind of variable. By default you may pass a **function** or a **pipeline**, otherwise you will have to define interceptors.

An interceptor is a function that receives a node and returns a callback that connects to that node. Interceptors will be passed each node in the pipeline (including the **report** node) and should return a **callback** if the node matches the case or nothing (**null**). First interceptor to return a callback will be used for that specific node.

```js
class MyNode {
	run(payload) {
		console.log(payload);
	}
}

const myNodeInterceptor = node => {
	return node instanceof MyNode ? (payload) => node.run(payload) : null;
};

createPipeline().intercept(myNodeInterceptor).through(new MyNode());
```
Interceptors can also be registered globally, however, the local interceptors will always have first choice.
```js
const {registerGlobalInterceptor, createPipeline} = require("cleopatra");

registerGlobalInterceptor(myNodeInterceptor);
createPipeline().through(new MyNode());
```
## Container
A container is a simple pipeline manager that stores and handles named pipelines.

### Methods
> **pipeline(name)**

Creates or returns the pipeline with that name.

> **pipe(name, ...nodes)**

Pushes new nodes into the pipeline with that name.

> **report(node)**

Sets the error handler node at the container level. Pipelines within this container will report errors through this handler unless manually set to report through something else.

> **dispatch(name, payload = {})**

Dispatches the payload through the pipeline with that name.

```js
const {createContainer} = require("cleopatra");
const container = createContainer().report(error => console.error(error));

container.pipe("my-pipeline", payload => { console.log(payload); });
container.dispatch("my-other-pipeline");
container.dispatch("my-pipeline", {prop: "the payload"});
```

---
_Source: https://npm.io/package/cleopatra · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._