@vltpkg/graph-run

Classes

Runner<Node, Result>

Defined in: index.ts:370

Asynchronous graph runner

Extends

RunnerBase<Node, Result, false, RunnerOptions<Node, Result>>

Type Parameters

• Node

• Result

Constructors

new Runner()

new Runner<Node, Result>(options, from?): Runner<Node, Result>

Defined in: index.ts:201

Parameters

options

RunnerOptions

from?

Callable

Returns

Runner<Node, Result>

Inherited from

RunnerBase.constructor

Properties

dependents

readonly dependents: Map<Node, Set<Node>>;

Defined in: index.ts:169

Set of dependents (direct & transitive) on each node

Inherited from

RunnerBase.dependents

directDependents

readonly directDependents: Map<Node, Set<Node>>;

Defined in: index.ts:172

Set of direct dependents on each node

Inherited from

RunnerBase.directDependents

errors

readonly errors: unknown[] = [];

Defined in: index.ts:193

Rejections and Errors encountered in the traversal

Inherited from

RunnerBase.errors

failFast

readonly failFast: boolean;

Defined in: index.ts:190

True if we are in failFast mode

Inherited from

RunnerBase.failFast

from

readonly from: Callable;

Defined in: index.ts:199

Function defining the callsite where the traversal was initiated, used for Error.captureStackTrace.

Inherited from

RunnerBase.from

options

readonly options: RunnerOptions;

Defined in: index.ts:175

Options provided to constructor

Inherited from

RunnerBase.options

promiseWaiting

readonly promiseWaiting: Map<Node, Set<Node>>;

Defined in: index.ts:380

Track which node’s promise is waiting for which other nodes

results

readonly results: Map<Node, Result>;

Defined in: index.ts:163

The map of traversal results

Inherited from

RunnerBase.results

running

readonly running: Map<Node, Promise<void>>;

Defined in: index.ts:377

Map of nodes currently awaiting completion

settled

readonly settled: SettledMap<Node, Result>;

Defined in: index.ts:166

The map of PromiseSettledResult objects

Inherited from

RunnerBase.settled

Methods

getDeps()

getDeps(n): Promise<Node[]>

Defined in: index.ts:382

Get the dependencies of a given node

Parameters

n

Node

Returns

Promise<Node[]>

Overrides

RunnerBase.getDeps

onCycle()

onCycle(
   n,
   cycle,
path): Promise<void>

Defined in: index.ts:406

Calls the options.onCycle() method when a cycle is detected.

Parameters

n

Node

cycle

Node[]

path

Node[]

Returns

Promise<void>

Overrides

RunnerBase.onCycle

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

n

Node

d

Node

Returns

undefined | [Node, ...path: Node[]]

Inherited from

RunnerBase.route

run()

run(): Promise<void>

Defined in: index.ts:507

Initiate the graph traversal, resolving/returning when complete

Returns

Promise<void>

Overrides

RunnerBase.run

visit()

visit(
   n,
   path,
depResults): Promise<Result>

Defined in: index.ts:397

Visit a node. Calls options.visit()

Parameters

n

Node

path

Node[]

depResults

DepResults<Node, Result>

Returns

Promise<Result>

Overrides

RunnerBase.visit

RunnerBase<Node, Result, Sync, O>

Defined in: index.ts:151

Base class of Runner and RunnerSync

Type Parameters

• 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

options

O

from?

Callable

Returns

RunnerBase<Node, Result, Sync, O>

Properties

dependents

readonly dependents: Map<Node, Set<Node>>;

Defined in: index.ts:169

Set of dependents (direct & transitive) on each node

directDependents

readonly directDependents: Map<Node, Set<Node>>;

Defined in: index.ts:172

Set of direct dependents on each node

errors

readonly errors: unknown[] = [];

Defined in: index.ts:193

Rejections and Errors encountered in the traversal

failFast

readonly failFast: boolean;

Defined in: index.ts:190

True if we are in failFast mode

from

readonly from: Callable;

Defined in: index.ts:199

Function defining the callsite where the traversal was initiated, used for Error.captureStackTrace.

options

readonly options: O;

Defined in: index.ts:175

Options provided to constructor

results

readonly results: Map<Node, Result>;

Defined in: index.ts:163

The map of traversal results

settled

readonly settled: SettledMap<Node, Result>;

Defined in: index.ts:166

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

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

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

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

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

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

• Node

• Result

Constructors

new RunnerSync()

new RunnerSync<Node, Result>(options, from?): RunnerSync<Node, Result>

Defined in: index.ts:201

Parameters

options

RunnerOptionsSync

from?

Callable

Returns

RunnerSync<Node, Result>

Inherited from

RunnerBase.constructor

Properties

dependents

readonly dependents: Map<Node, Set<Node>>;

Defined in: index.ts:169

Set of dependents (direct & transitive) on each node

Inherited from

RunnerBase.dependents

directDependents

readonly directDependents: Map<Node, Set<Node>>;

Defined in: index.ts:172

Set of direct dependents on each node

Inherited from

RunnerBase.directDependents

errors

readonly errors: unknown[] = [];

Defined in: index.ts:193

Rejections and Errors encountered in the traversal

Inherited from

RunnerBase.errors

failFast

readonly failFast: boolean;

Defined in: index.ts:190

True if we are in failFast mode

Inherited from

RunnerBase.failFast

from

readonly from: Callable;

Defined in: index.ts:199

Function defining the callsite where the traversal was initiated, used for Error.captureStackTrace.

Inherited from

RunnerBase.from

options

readonly options: RunnerOptionsSync;

Defined in: index.ts:175

Options provided to constructor

Inherited from

RunnerBase.options

results

readonly results: Map<Node, Result>;

Defined in: index.ts:163

The map of traversal results

Inherited from

RunnerBase.results

settled

readonly settled: SettledMap<Node, Result>;

Defined in: index.ts:166

The map of PromiseSettledResult objects

Inherited from

RunnerBase.settled

Methods

getDeps()

getDeps(n): Node[]

Defined in: index.ts:523

Get the dependencies of a given node

Parameters

n

Node

Returns

Node[]

Overrides

RunnerBase.getDeps

onCycle()

onCycle(
   n,
   cycle,
   path): void

Defined in: index.ts:533

Calls the options.onCycle() method when a cycle is detected.

Parameters

n

Node

cycle

Node[]

path

Node[]

Returns

void

Overrides

RunnerBase.onCycle

route()

route(n, d): undefined | [Node, ...path: Node[]]

Defined in: index.ts:264

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

n

Node

d

Node

Returns

undefined | [Node, ...path: Node[]]

Inherited from

RunnerBase.route

run()

run(): Map<Node, Result>

Defined in: index.ts:571

Initiate the graph traversal, resolving/returning when complete

Returns

Map<Node, Result>

Overrides

RunnerBase.run

visit()

visit(
   n,
   path,
   depResults): Result

Defined in: index.ts:528

Visit a node. Calls options.visit()

Parameters

n

Node

path

Node[]

depResults

DepResults<Node, Result>

Returns

Result

Overrides

RunnerBase.visit

Interfaces

RunnerOptions<Node, Result>

Defined in: index.ts:63

Options that define the graph and how to traverse it

Extended by

RunnerOptionsSync

Type Parameters

• Node

• Result = void

Properties

failFast?

optional failFast: boolean;

Defined in: index.ts:104

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()

getDeps: (node) => Node[] | Promise<Node[]>;

Defined in: index.ts:68

get the dependencies of a given node

Parameters

node

Node

Returns

Node[] | Promise<Node[]>

graph

graph: [Node, ...rest: Node[]];

Defined in: index.ts:65

Array of one or more entry nodes.

onCycle()?

optional onCycle: (node, cycle, path) => void | Promise<void>;

Defined in: index.ts:91

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.

Parameters

node

Node

cycle

Node[]

path

Node[]

Returns

void | Promise<void>

signal?

optional signal: AbortSignal;

Defined in: index.ts:107

a signal that will trigger the graph traversal to end prematurely

visit()

visit: (node, signal, path, depResults) => Result | Promise<Result>

Defined in: index.ts:71

action to take on each node

Parameters

node

Node

signal

AbortSignal

path

Node[]

depResults

DepResults<Node, Result>

Returns

Result | Promise<Result>

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

• Node

• Result = void

Properties

failFast?

optional failFast: boolean;

Defined in: index.ts:104

Default

true

Inherited from

RunnerOptions.failFast

getDeps()

getDeps: (node) => Node[];

Defined in: index.ts:123

Get a set of dependency nodes synchronously

Parameters

node

Node

Returns

Node[]

Overrides

RunnerOptions.getDeps

graph

graph: [Node, ...rest: Node[]];

Defined in: index.ts:65

Array of one or more entry nodes.

Inherited from

RunnerOptions.graph

onCycle()?

optional onCycle: (node, cycle, path) => void;

Defined in: index.ts:134

Handle cycles synchronously

Parameters

node

Node

cycle

Node[]

path

Node[]

Returns

void

Overrides

RunnerOptions.onCycle

signal?

optional signal: AbortSignal;

Defined in: index.ts:107

a signal that will trigger the graph traversal to end prematurely

Inherited from

RunnerOptions.signal

visit()

visit: (node, signal, path, depResults) => Result

Defined in: index.ts:126

Visit a node synchronously

Parameters

node

Node

signal

AbortSignal

path

Node[]

depResults

DepResults<Node, Result>

Returns

Result

Overrides

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

• 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

code

code: ErrorCode

Type Parameters

• 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

• 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

• Node

• Result

Parameters

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

• Node

• Result

Parameters

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

• Node

• Result

Parameters

options

RunnerOptions<Node, Result>

Returns

Promise<Result>

anySync()

function anySync<Node, Result>(options): Result

Defined 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

• Node

• Result

Parameters

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

• Node

• Result

Parameters

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

• Node

• Result

Parameters

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

• Node

Parameters

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

• Node

• Result

Parameters

options

RunnerOptions<Node, Result>

Returns

Promise<Result>

raceSync()

function raceSync<Node, Result>(options): Result

Defined in: index.ts:768

Synchronous graph traversal, returning or throwing when the first visit is completed.

Type Parameters

• Node

• Result

Parameters

options

RunnerOptionsSync<Node, Result>

Returns

Result

On this page

@vltpkg/graph-run

Classes

Runner<Node, Result>

Extends

Type Parameters

Constructors

new Runner()

Parameters

options

from?

Returns

Inherited from

Properties

dependents

Inherited from

directDependents

Inherited from

errors

Inherited from

failFast

Inherited from

from

Inherited from

options

Inherited from

promiseWaiting

results

Inherited from

running

settled

Inherited from

Methods

getDeps()

Parameters

n

Returns

Overrides

onCycle()

Parameters

n

cycle

path

Returns

Overrides

route()

Parameters

n

d

Returns

Inherited from

run()

Returns

Overrides

visit()

Parameters

n

path

depResults

Returns

Overrides

RunnerBase<Node, Result, Sync, O>

Extended by

Type Parameters

Constructors

new RunnerBase()

Parameters

options

from?

Returns

Properties

dependents

directDependents

errors

failFast

from

options

results

settled

Methods