---
title: Pipelines
---
import EnvBadges from '@theme/EnvBadges';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Pipe an input through a series of type-safe routines and tasks to produce an output, or simply, run
logic in a series of stages.
## Installation
```bash
yarn add @boost/pipeline
```
```bash
pnpm add @boost/pipeline
```
```bash
npm install @boost/pipeline
```
## Pipelines
A pipeline can be used to process an input, either in parallel or serial, through a series of
actions known as work units, to produce an output. If you don't need an input, but merely need to
process work in stages, the pipeline supports that as well. There are multiple types of
[work units](#work-types) and [pipelines](#pipeline-types), so choose the best one for each use
case.
To begin, instantiate a pipeline with a [context](#contexts), and an _optional_ input value.
```ts
import { Context, ConcurrentPipeline } from '@boost/pipeline';
import { referenceFunction } from './example';
const input = 123;
const pipeline = new ConcurrentPipeline(new Context(), input);
```
Once instantiated, we must register work units (either a [task](#task) or [routine](#routine)) that
will process the input value, either with
[`ParallelPipeline#add()`](/api/pipeline/class/ParallelPipeline#add) or
[`SerialPipeline#pipe()`](/api/pipeline/class/SerialPipeline#pipe). All work units require a
descriptive title, and are passed the context and current value when being executed.
```ts
// Tasks
pipeline.add('Task using an anonymous function', (context, value) => value);
pipeline.add('Task using a function reference', referenceFunction);
pipeline.add(new Task('Task using a class instance', referenceFunction));
// Routines
pipeline.add(new ExampleRoutine('key', 'Explicit routine using a class instance'));
```
And to finish, we can execute our pipeline to process each work unit and produce the final output
value.
```ts
const output = await pipeline.run();
```
### Contexts
A [`Context`](/api/pipeline/class/Context) is merely a plain class that provides contextual
information to all work units, and is passed as the 1st argument when executing. It's highly
encouraged to create custom contexts with typed properties, helper methods, and more.
```ts
import { Context } from '@boost/pipeline';
export default class ProcessContext extends Context {
readonly cwd: string;
readonly root: string;
constructor(root: string, cwd?: string) {
this.cwd = cwd || process.cwd();
this.root = root;
}
}
```
A unique feature of contexts is the ability to deep clone itself using
[`Context#clone()`](/api/pipeline/class/Context#clone). This method is extremely useful when a
context of the same shape must be passed to another pipeline without collisions or mutations
occurring.
```ts
const newContext = context.clone();
```
### Input & output types
The input type is inferred from the 2nd constructor argument, while the output type defaults to the
input type. If you need to customize either the input or output type manually, the pipeline generics
can be customized upon instantiation.
```ts
const pipeline = new ConcurrentPipeline(new Context(), 123);
```
## Work types
There are 2 types of work units that can be registered in a pipeline.
### Task
A task is simply a function/method (in any form) that accepts an input and returns an output. It can
be represented by a standard function or a [`Task`](/api/pipeline/class/Task) instance.
```ts
import { Context } from '@boost/pipeline';
function task(context: Context, value: number): string {
return value.toLocaleString();
}
parallelPipeline.add('A title for this task', task);
```
```ts
import { Context, Task } from '@boost/pipeline';
const task = new Task('A title for this task', (context: Context, value: number) =>
value.toLocaleString(),
);
serialPipeline.pipe(task);
```
### Routine
A [`Routine`](/api/pipeline/class/Routine) is a specialized work unit implemented with a class. It
provides helper methods, the ability to create nested hierarchical pipelines, and an implicit
encapsulation of similar logic and tasks.
To begin, import and extend the `Routine` class and implement the
[`Routine#blueprint()`](/api/pipeline/class/Routine#blueprint) and
[`Routine#execute()`](/api/pipeline/class/Routine#execute) methods. The class requires 3 generics to
be defined, starting with an output type (defaults to `unknown`), an input type (defaults to
`unknown`), and an options interface (defaults to an empty object).
The blueprint method is inherited from [`Contract`](./common.mdx#class-contracts), and should return
an object that matches the structure of the generic options interface. The execute method should
accept the input type and return the expected output type.
```ts
import { Blueprint, Schemas, Bind } from '@boost/common';
import { Routine } from '@boost/pipeline';
interface ExampleOptions {
limit?: number;
}
type Input = number;
type Output = string;
export default class ExampleRoutine extends Routine