Reference
Classes
Runner<Node, Result>
Defined in: index.ts:370
Asynchronous graph runner
Extends
RunnerBase<Node,Result,false,RunnerOptions<Node,Result>>
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Constructors
new Runner()
new Runner<Node, Result>(options, from?): Runner<Node, Result>Defined in: index.ts:201
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptions |
from? | Callable |
Returns
Runner<Node, Result>
Inherited from
Properties
| Property | Type | Default value | Description | Inherited from |
|---|---|---|---|---|
dependents | Map<Node, Set<Node>> | undefined | Set of dependents (direct & transitive) on each node | RunnerBase.dependents |
directDependents | Map<Node, Set<Node>> | undefined | Set of direct dependents on each node | RunnerBase.directDependents |
errors | unknown[] | [] | Rejections and Errors encountered in the traversal | RunnerBase.errors |
failFast | boolean | undefined | True if we are in failFast mode | RunnerBase.failFast |
from | Callable | undefined | Function defining the callsite where the traversal was initiated, used for Error.captureStackTrace. | RunnerBase.from |
options | RunnerOptions | undefined | Options provided to constructor | RunnerBase.options |
promiseWaiting | Map<Node, Set<Node>> | undefined | Track which node's promise is waiting for which other nodes | - |
results | Map<Node, Result> | undefined | The map of traversal results | RunnerBase.results |
running | Map<Node, Promise<void>> | undefined | Map of nodes currently awaiting completion | - |
settled | SettledMap<Node, Result> | undefined | The map of PromiseSettledResult objects | RunnerBase.settled |
Methods
getDeps()
getDeps(n): Promise<Node[]>Defined in: index.ts:382
Get the dependencies of a given node
Parameters
| Parameter | Type |
|---|---|
n | Node |
Returns
Promise<Node[]>
Overrides
onCycle()
onCycle(
n,
cycle,
path): Promise<void>Defined in: index.ts:406
Calls the options.onCycle() method when a cycle is detected.
Parameters
| Parameter | Type |
|---|---|
n | Node |
cycle | Node[] |
path | Node[] |
Returns
Promise<void>
Overrides
route()
route(n, d): undefined | [Node, ...path: Node[]]Defined in: index.ts:264
For a Node n that depends directly or transitively on Node d, find the
shortest known dependency path from n to d. This is done by walking
backwards breadth-first up the dependency relations from d until n is
found.
If no known path can be found, then undefined is returned. Otherwise,
a path array is returned that starts with n and ends with d.
Note that self-referential links are never considered, since they're by definition cyclical.
Parameters
| Parameter | Type |
|---|---|
n | Node |
d | Node |
Returns
undefined | [Node, ...path: Node[]]
Inherited from
run()
run(): Promise<void>Defined in: index.ts:507
Initiate the graph traversal, resolving/returning when complete
Returns
Promise<void>
Overrides
visit()
visit(
n,
path,
depResults): Promise<Result>Defined in: index.ts:397
Visit a node. Calls options.visit()
Parameters
| Parameter | Type |
|---|---|
n | Node |
path | Node[] |
depResults | DepResults<Node, Result> |
Returns
Promise<Result>
Overrides
abstract RunnerBase<Node, Result, Sync, O>
Defined in: index.ts:151
Base class of Runner and RunnerSync
Extended by
Type Parameters
| Type Parameter | Default type |
|---|---|
Node | - |
Result | void |
Sync extends boolean | false |
O extends Sync extends true ? RunnerOptionsSync<Node, Result> : RunnerOptions<Node, Result> | Sync extends true ? RunnerOptionsSync<Node, Result> : RunnerOptions<Node, Result> |
Constructors
new RunnerBase()
new RunnerBase<Node, Result, Sync, O>(options, from?): RunnerBase<Node, Result, Sync, O>Defined in: index.ts:201
Parameters
| Parameter | Type |
|---|---|
options | O |
from? | Callable |
Returns
RunnerBase<Node, Result, Sync, O>
Properties
| Property | Type | Default value | Description |
|---|---|---|---|
dependents | Map<Node, Set<Node>> | undefined | Set of dependents (direct & transitive) on each node |
directDependents | Map<Node, Set<Node>> | undefined | Set of direct dependents on each node |
errors | unknown[] | [] | Rejections and Errors encountered in the traversal |
failFast | boolean | undefined | True if we are in failFast mode |
from | Callable | undefined | Function defining the callsite where the traversal was initiated, used for Error.captureStackTrace. |
options | O | undefined | Options provided to constructor |
results | Map<Node, Result> | undefined | The map of traversal results |
settled | SettledMap<Node, Result> | undefined | The map of PromiseSettledResult objects |
Methods
getDeps()
abstract getDeps(n): Sync extends true ? Node[] : Promise<Node[]>Defined in: index.ts:232
Get the dependencies of a given node
Parameters
| Parameter | Type |
|---|---|
n | Node |
Returns
Sync extends true ? Node[] : Promise<Node[]>
onCycle()
abstract onCycle(
n,
cycle,
path): Sync extends true ? void : void | Promise<void>Defined in: index.ts:246
Calls the options.onCycle() method when a cycle is detected.
Parameters
| Parameter | Type |
|---|---|
n | Node |
cycle | Node[] |
path | Node[] |
Returns
Sync extends true ? void : void | Promise<void>
route()
route(n, d): undefined | [Node, ...path: Node[]]Defined in: index.ts:264
For a Node n that depends directly or transitively on Node d, find the
shortest known dependency path from n to d. This is done by walking
backwards breadth-first up the dependency relations from d until n is
found.
If no known path can be found, then undefined is returned. Otherwise,
a path array is returned that starts with n and ends with d.
Note that self-referential links are never considered, since they're by definition cyclical.
Parameters
| Parameter | Type |
|---|---|
n | Node |
d | Node |
Returns
undefined | [Node, ...path: Node[]]
run()
abstract run(): Sync extends true ? void : Promise<void>Defined in: index.ts:229
Initiate the graph traversal, resolving/returning when complete
Returns
Sync extends true ? void : Promise<void>
visit()
abstract visit(
n,
path,
depResults): Sync extends true ? Result : Promise<Result>Defined in: index.ts:237
Visit a node. Calls options.visit()
Parameters
| Parameter | Type |
|---|---|
n | Node |
path | Node[] |
depResults | DepResults<Node, Result> |
Returns
Sync extends true ? Result : Promise<Result>
RunnerSync<Node, Result>
Defined in: index.ts:517
Synchronous graph runner
Extends
RunnerBase<Node,Result,true,RunnerOptionsSync<Node,Result>>
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Constructors
new RunnerSync()
new RunnerSync<Node, Result>(options, from?): RunnerSync<Node, Result>Defined in: index.ts:201
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptionsSync |
from? | Callable |
Returns
RunnerSync<Node, Result>
Inherited from
Properties
| Property | Type | Default value | Description | Inherited from |
|---|---|---|---|---|
dependents | Map<Node, Set<Node>> | undefined | Set of dependents (direct & transitive) on each node | RunnerBase.dependents |
directDependents | Map<Node, Set<Node>> | undefined | Set of direct dependents on each node | RunnerBase.directDependents |
errors | unknown[] | [] | Rejections and Errors encountered in the traversal | RunnerBase.errors |
failFast | boolean | undefined | True if we are in failFast mode | RunnerBase.failFast |
from | Callable | undefined | Function defining the callsite where the traversal was initiated, used for Error.captureStackTrace. | RunnerBase.from |
options | RunnerOptionsSync | undefined | Options provided to constructor | RunnerBase.options |
results | Map<Node, Result> | undefined | The map of traversal results | RunnerBase.results |
settled | SettledMap<Node, Result> | undefined | The map of PromiseSettledResult objects | RunnerBase.settled |
Methods
getDeps()
getDeps(n): Node[]Defined in: index.ts:523
Get the dependencies of a given node
Parameters
| Parameter | Type |
|---|---|
n | Node |
Returns
Node[]
Overrides
onCycle()
onCycle(
n,
cycle,
path): voidDefined in: index.ts:533
Calls the options.onCycle() method when a cycle is detected.
Parameters
| Parameter | Type |
|---|---|
n | Node |
cycle | Node[] |
path | Node[] |
Returns
void
Overrides
route()
route(n, d): undefined | [Node, ...path: Node[]]Defined in: index.ts:264
For a Node n that depends directly or transitively on Node d, find the
shortest known dependency path from n to d. This is done by walking
backwards breadth-first up the dependency relations from d until n is
found.
If no known path can be found, then undefined is returned. Otherwise,
a path array is returned that starts with n and ends with d.
Note that self-referential links are never considered, since they're by definition cyclical.
Parameters
| Parameter | Type |
|---|---|
n | Node |
d | Node |
Returns
undefined | [Node, ...path: Node[]]
Inherited from
run()
run(): Map<Node, Result>Defined in: index.ts:571
Initiate the graph traversal, resolving/returning when complete
Returns
Map<Node, Result>
Overrides
visit()
visit(
n,
path,
depResults): ResultDefined in: index.ts:528
Visit a node. Calls options.visit()
Parameters
| Parameter | Type |
|---|---|
n | Node |
path | Node[] |
depResults | DepResults<Node, Result> |
Returns
Result
Overrides
Interfaces
RunnerOptions<Node, Result>
Defined in: index.ts:63
Options that define the graph and how to traverse it
Extended by
Type Parameters
| Type Parameter | Default type |
|---|---|
Node | - |
Result | void |
Properties
| Property | Type | Description |
|---|---|---|
failFast? | boolean | Set to false to continue operations even if errors occur. If set to false, then an AggregateError will be raised on failure containing all failures (even if only one). If true, then a normal Error will be raised on failure. Default true |
getDeps | (node: Node) => Node[] | Promise<Node[]> | get the dependencies of a given node |
graph | [Node, ...rest: Node[]] | Array of one or more entry nodes. |
onCycle? | (node: Node, cycle: Node[], path: Node[]) => void | Promise<void> | Called when a cycle is encountered. Throw in this method to enforce a DAG graph. If left undefined, then cycles are silently ignored and skipped. node parameter is the dependency that is being skipped. cycle is the route from the dependent back to itself via the parent. path is the path to the dependent who wanted this dep to be loaded. |
signal? | AbortSignal | a signal that will trigger the graph traversal to end prematurely |
visit | (node: Node, signal: AbortSignal, path: Node[], depResults: DepResults<Node, Result>) => Result | Promise<Result> | action to take on each node |
RunnerOptionsSync<Node, Result>
Defined in: index.ts:118
Options that can define a synchronous graph traversal.
Note that if the visit() method is async, then the promises themselves
will be used as the Result type, which is likely not what you want!
Extends
RunnerOptions<Node,Result>
Type Parameters
| Type Parameter | Default type |
|---|---|
Node | - |
Result | void |
Properties
| Property | Type | Description | Overrides | Inherited from |
|---|---|---|---|---|
failFast? | boolean | Set to false to continue operations even if errors occur. If set to false, then an AggregateError will be raised on failure containing all failures (even if only one). If true, then a normal Error will be raised on failure. Default true | - | RunnerOptions.failFast |
getDeps | (node: Node) => Node[] | Get a set of dependency nodes synchronously | RunnerOptions.getDeps | - |
graph | [Node, ...rest: Node[]] | Array of one or more entry nodes. | - | RunnerOptions.graph |
onCycle? | (node: Node, cycle: Node[], path: Node[]) => void | Handle cycles synchronously | RunnerOptions.onCycle | - |
signal? | AbortSignal | a signal that will trigger the graph traversal to end prematurely | - | RunnerOptions.signal |
visit | (node: Node, signal: AbortSignal, path: Node[], depResults: DepResults<Node, Result>) => Result | Visit a node synchronously | RunnerOptions.visit | - |
Type Aliases
Callable
type Callable = Function | (...a) => unknown | (...a) => unknown;Defined in: index.ts:144
Any function or class. Used for Error.captureStackTrace
DepResults<Node, Result>
type DepResults<Node, Result> = Map<Node, Result | undefined>;Defined in: index.ts:110
Type Parameters
| Type Parameter |
|---|
Node |
Result |
ErrorCause<Node>
type ErrorCause<Node> = object &
| {
code: "GRAPHRUN_NO_NODES";
found: unknown;
wanted: string;
}
| {
code: "GRAPHRUN_CYCLE_WITHOUT_PATH";
}
| {
cause: Error;
code: "GRAPHRUN_TRAVERSAL";
node: Node;
path: Node[];
};Defined in: index.ts:23
Type declaration
| Name | Type |
|---|---|
code | ErrorCode |
Type Parameters
| Type Parameter |
|---|
Node |
ErrorCode
type ErrorCode =
| "GRAPHRUN_NO_NODES"
| "GRAPHRUN_CYCLE_WITHOUT_PATH"
| "GRAPHRUN_TRAVERSAL";Defined in: index.ts:18
Codes indicating the type of error that was encountered.
These are found on the Error.cause.code field.
They are:
'GRAPHRUN_TRAVERSAL'The command run on a given node has failed, either by throwing an error, or by returning a rejected promise.'GRAPHRUN_NO_NODES'An empty list of initial nodes was provided to the graph run operation. At least one starting node must be present in the list.'GRAPHRUN_CYCLE_WITHOUT_PATH'- A cycle in the graph was detected, but the path to the node where the cycle was detected could not be determined. This is impossible, and cannot ever happen.
SettledMap<Node, Result>
type SettledMap<Node, Result> = Map<Node, PromiseSettledResult<Result>>;Defined in: index.ts:138
A map of nodes to their PromiseSettledResult value
Type Parameters
| Type Parameter | Default type |
|---|---|
Node | - |
Result | void |
Functions
allSettled()
function allSettled<Node, Result>(options): Promise<SettledMap<Node, Result>>Defined in: index.ts:629
Asynchronous graph traversal, capturing all error/result statuses.
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptions<Node, Result> |
Returns
Promise<SettledMap<Node, Result>>
allSettledSync()
function allSettledSync<Node, Result>(options): SettledMap<Node, Result>Defined in: index.ts:644
Synchronous graph traversal, capturing all error/result statuses.
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptionsSync<Node, Result> |
Returns
SettledMap<Node, Result>
any()
function any<Node, Result>(options): Promise<Result>Defined in: index.ts:660
Asynchronous graph traversal, returning the first successful visit. If all visits fail, then an AggregateError is raised with all errors encountered.
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptions<Node, Result> |
Returns
Promise<Result>
anySync()
function anySync<Node, Result>(options): ResultDefined in: index.ts:700
Synchronous graph traversal, returning the first successful visit. If all visits fail, then an AggregateError is thrown with all errors encountered.
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptionsSync<Node, Result> |
Returns
Result
graphRun()
function graphRun<Node, Result>(options): Promise<Map<Node, Result>>Defined in: index.ts:586
Asynchronous graph traversal method
If failFast:false is set in the options, then an AggregateError
will be raised if there were any failures. Otherwise, a normal Error
is raised on failure.
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptions<Node, Result> |
Returns
Promise<Map<Node, Result>>
graphRunSync()
function graphRunSync<Node, Result>(options): Map<Node, Result>Defined in: index.ts:609
Synchronous graph traversal method
If failFast:false is set in the options, then an AggregateError
will be thrown if there were any failures. Otherwise, a normal Error
is thrown on failure.
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptionsSync<Node, Result> |
Returns
Map<Node, Result>
isGraphRunError()
function isGraphRunError<Node>(er): er is Error & { cause: ErrorCause<Node> }Defined in: index.ts:40
Type Parameters
| Type Parameter |
|---|
Node |
Parameters
| Parameter | Type |
|---|---|
er | unknown |
Returns
er is Error & { cause: ErrorCause<Node> }
race()
function race<Node, Result>(options): Promise<Result>Defined in: index.ts:739
Asynchronous graph traversal, resolving or rejecting when the first visit resolves or rejects.
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptions<Node, Result> |
Returns
Promise<Result>
raceSync()
function raceSync<Node, Result>(options): ResultDefined in: index.ts:768
Synchronous graph traversal, returning or throwing when the first visit is completed.
Type Parameters
| Type Parameter |
|---|
Node |
Result |
Parameters
| Parameter | Type |
|---|---|
options | RunnerOptionsSync<Node, Result> |
Returns
Result