cleopatra v0.2.4

cleopatra

Module for creating and managing promise based pipelines.

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.

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.

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.

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.

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"});