@rushstack/operation-graph 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+@rushstack/operation-graph
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,12 @@
+# @rushstack/operation-graph
+
+This library contains logic for managing and executing tasks in a directed acyclic graph. It supports single execution or executing in a loop.
+
+## Links
+
+- [CHANGELOG.md](
+  https://github.com/microsoft/rushstack/blob/main/libraries/operation-graph/CHANGELOG.md) - Find
+  out what's new in the latest version
+- [API Reference](https://rushstack.io/pages/api/operation-graph/)
+
+`@rushstack/operation-graph` is part of the [Rush Stack](https://rushstack.io/) family of projects.

package/dist/operation-graph.d.ts

@@ -0,0 +1,572 @@
+/// <reference types="node" />
+
+import { ITerminal } from '@rushstack/node-core-library';
+
+/**
+ * The set of known messages from the host to the watch loop.
+ * @beta
+ */
+export declare type CommandMessageFromHost = ICancelCommandMessage | IExitCommandMessage | IRunCommandMessage | ISyncCommandMessage;
+
+/**
+ * The set of known messages from the watch loop to the host.
+ * @beta
+ */
+export declare type EventMessageFromClient = IRequestRunEventMessage | IAfterExecuteEventMessage | ISyncEventMessage;
+
+/**
+ * A message sent to the host upon completion of a run of this task.
+ *
+ * @beta
+ */
+export declare interface IAfterExecuteEventMessage {
+    event: 'after-execute';
+    status: OperationStatus;
+}
+
+/**
+ * A message sent by the host to tell the watch loop to cancel the current run.
+ *
+ * @beta
+ */
+export declare interface ICancelCommandMessage {
+    command: 'cancel';
+}
+
+/**
+ * Information provided to `executeAsync` by the `OperationExecutionManager`.
+ *
+ * @beta
+ */
+export declare interface IExecuteOperationContext extends Omit<IOperationRunnerContext, 'isFirstRun' | 'requestRun'> {
+    /**
+     * Function to invoke before execution of an operation, for logging.
+     */
+    beforeExecute(operation: Operation, state: IOperationState): void;
+    /**
+     * Function to invoke after execution of an operation, for logging.
+     */
+    afterExecute(operation: Operation, state: IOperationState): void;
+    /**
+     * Function used to schedule the concurrency-limited execution of an operation.
+     */
+    queueWork<T>(workFn: () => Promise<T>, priority: number): Promise<T>;
+    /**
+     * A callback to the overarching orchestrator to request that the operation be invoked again.
+     * Used in watch mode to signal that inputs have changed.
+     */
+    requestRun?: (requestor?: string) => void;
+    /**
+     * Terminal to write output to.
+     */
+    terminal: ITerminal;
+}
+
+/**
+ * A message sent by the host to tell the watch loop to shutdown gracefully.
+ *
+ * @beta
+ */
+export declare interface IExitCommandMessage {
+    command: 'exit';
+}
+
+/**
+ * Options for the current run.
+ *
+ * @beta
+ */
+export declare interface IOperationExecutionOptions {
+    abortSignal: AbortSignal;
+    parallelism: number;
+    terminal: ITerminal;
+    requestRun?: (requestor?: string) => void;
+}
+
+/**
+ * Options for constructing a new Operation.
+ * @beta
+ */
+export declare interface IOperationOptions {
+    /**
+     * The name of this operation, for logging.
+     */
+    name?: string | undefined;
+    /**
+     * The group that this operation belongs to. Will be used for logging and duration tracking.
+     */
+    groupName?: string | undefined;
+    /**
+     * When the scheduler is ready to process this `Operation`, the `runner` implements the actual work of
+     * running the operation.
+     */
+    runner?: IOperationRunner | undefined;
+    /**
+     * The weight used by the scheduler to determine order of execution.
+     */
+    weight?: number | undefined;
+}
+
+/**
+ * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
+ * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * implementation manages the actual process for running a single operation.
+ *
+ * @beta
+ */
+export declare interface IOperationRunner {
+    /**
+     * Name of the operation, for logging.
+     */
+    readonly name: string;
+    /**
+     * Indicates that this runner is architectural and should not be reported on.
+     */
+    silent: boolean;
+    /**
+     * Method to be executed for the operation.
+     */
+    executeAsync(context: IOperationRunnerContext): Promise<OperationStatus>;
+}
+
+/**
+ * Information passed to the executing `IOperationRunner`
+ *
+ * @beta
+ */
+export declare interface IOperationRunnerContext {
+    /**
+     * An abort signal for the overarching execution. Runners should do their best to gracefully abort
+     * as soon as possible if the signal is aborted.
+     */
+    abortSignal: AbortSignal;
+    /**
+     * If this is the first time this operation has been executed.
+     */
+    isFirstRun: boolean;
+    /**
+     * A callback to the overarching orchestrator to request that the operation be invoked again.
+     * Used in watch mode to signal that inputs have changed.
+     */
+    requestRun?: () => void;
+}
+
+/**
+ * Interface contract for a single state of an operation.
+ *
+ * @beta
+ */
+export declare interface IOperationState {
+    /**
+     * The status code for the operation.
+     */
+    status: OperationStatus;
+    /**
+     * Whether the operation has been run at least once.
+     */
+    hasBeenRun: boolean;
+    /**
+     * The error, if the status is `OperationStatus.Failure`.
+     */
+    error: OperationError | undefined;
+    /**
+     * Timing information for the operation.
+     */
+    stopwatch: Stopwatch;
+}
+
+/**
+ * Interface contract for the current and past state of an operation.
+ *
+ * @beta
+ */
+export declare interface IOperationStates {
+    /**
+     * The current state of the operation.
+     */
+    readonly state: Readonly<IOperationState> | undefined;
+    /**
+     * The previous state of the operation.
+     */
+    readonly lastState: Readonly<IOperationState> | undefined;
+}
+
+/**
+ * The interface contract for IPC send/receive, to support alternate channels and unit tests.
+ *
+ * @beta
+ */
+export declare type IPCHost = Pick<typeof process, 'on' | 'send'>;
+
+/**
+ * A message sent to the host to ask it to run this task.
+ *
+ * @beta
+ */
+export declare interface IRequestRunEventMessage {
+    event: 'requestRun';
+    requestor?: string;
+}
+
+/**
+ * A message sent by the host to tell the watch loop to perform a single run.
+ *
+ * @beta
+ */
+export declare interface IRunCommandMessage {
+    command: 'run';
+}
+
+/**
+ * A message sent by the host to ask for to resync status information.
+ *
+ * @beta
+ */
+export declare interface ISyncCommandMessage {
+    command: 'sync';
+}
+
+/**
+ * A message sent to the host upon connection of the channel, to indicate
+ * to the host that this task supports the protocol and to provide baseline status information.
+ *
+ * @beta
+ */
+export declare interface ISyncEventMessage {
+    event: 'sync';
+    status: OperationStatus;
+}
+
+/**
+ * Callbacks for the watch loop.
+ *
+ * @beta
+ */
+export declare interface IWatchLoopOptions {
+    /**
+     * Callback that performs the core work of a single iteration.
+     */
+    executeAsync: (state: IWatchLoopState) => Promise<OperationStatus>;
+    /**
+     * Logging callback immediately before execution occurs.
+     */
+    onBeforeExecute: () => void;
+    /**
+     * Logging callback when a run is requested (and hasn't already been).
+     */
+    onRequestRun: (requestor?: string) => void;
+    /**
+     * Logging callback when a run is aborted.
+     */
+    onAbort: () => void;
+}
+
+/**
+ * The public API surface of the watch loop, for use in the `executeAsync` callback.
+ *
+ * @beta
+ */
+export declare interface IWatchLoopState {
+    get abortSignal(): AbortSignal;
+    requestRun: (requestor?: string) => void;
+}
+
+/**
+ * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
+ * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * implementation manages the actual process of running a single operation.
+ *
+ * The graph of `Operation` instances will be cloned into a separate execution graph after processing.
+ *
+ * @beta
+ */
+export declare class Operation implements IOperationStates {
+    /**
+     * A set of all dependencies which must be executed before this operation is complete.
+     */
+    readonly dependencies: Set<Operation>;
+    /**
+     * A set of all operations that wait for this operation.
+     */
+    readonly consumers: Set<Operation>;
+    /**
+     * If specified, the name of a grouping to which this Operation belongs, for logging start and end times.
+     */
+    readonly groupName: string | undefined;
+    /**
+     * The name of this operation, for logging.
+     */
+    readonly name: string | undefined;
+    /**
+     * When the scheduler is ready to process this `Operation`, the `runner` implements the actual work of
+     * running the operation.
+     */
+    runner: IOperationRunner | undefined;
+    /**
+     * This number represents how far away this Operation is from the furthest "root" operation (i.e.
+     * an operation with no consumers). This helps us to calculate the critical path (i.e. the
+     * longest chain of projects which must be executed in order, thereby limiting execution speed
+     * of the entire operation tree.
+     *
+     * This number is calculated via a memoized depth-first search, and when choosing the next
+     * operation to execute, the operation with the highest criticalPathLength is chosen.
+     *
+     * Example:
+     *        (0) A
+     *             \\
+     *          (1) B     C (0)         (applications)
+     *               \\   /|\\
+     *                \\ / | \\
+     *             (2) D  |  X (1)      (utilities)
+     *                    | / \\
+     *                    |/   \\
+     *                (2) Y     Z (2)   (other utilities)
+     *
+     * All roots (A & C) have a criticalPathLength of 0.
+     * B has a score of 1, since A depends on it.
+     * D has a score of 2, since we look at the longest chain (e.g D-\>B-\>A is longer than D-\>C)
+     * X has a score of 1, since the only package which depends on it is A
+     * Z has a score of 2, since only X depends on it, and X has a score of 1
+     * Y has a score of 2, since the chain Y-\>X-\>C is longer than Y-\>C
+     *
+     * The algorithm is implemented in AsyncOperationQueue.ts as calculateCriticalPathLength()
+     */
+    criticalPathLength: number | undefined;
+    /**
+     * The weight for this operation. This scalar is the contribution of this operation to the
+     * `criticalPathLength` calculation above. Modify to indicate the following:
+     * - `weight` === 1: indicates that this operation has an average duration
+     * - `weight` &gt; 1: indicates that this operation takes longer than average and so the scheduler
+     *     should try to favor starting it over other, shorter operations. An example might be an operation that
+     *     bundles an entire application and runs whole-program optimization.
+     * - `weight` &lt; 1: indicates that this operation takes less time than average and so the scheduler
+     *     should favor other, longer operations over it. An example might be an operation to unpack a cached
+     *     output, or an operation using NullOperationRunner, which might use a value of 0.
+     */
+    weight: number;
+    /**
+     * The state of this operation the previous time a manager was invoked.
+     */
+    lastState: IOperationState | undefined;
+    /**
+     * The current state of this operation
+     */
+    state: IOperationState | undefined;
+    /**
+     * A cached execution promise for the current OperationExecutionManager invocation of this operation.
+     */
+    private _promise;
+    /**
+     * If true, then a run of this operation is currently wanted.
+     * This is used to track state from the `requestRun` callback passed to the runner.
+     */
+    private _runPending;
+    constructor(options?: IOperationOptions);
+    addDependency(dependency: Operation): void;
+    deleteDependency(dependency: Operation): void;
+    reset(): void;
+    /**
+     * @internal
+     */
+    _executeAsync(context: IExecuteOperationContext): Promise<OperationStatus>;
+    private _executeInnerAsync;
+}
+
+/**
+ * Encapsulates information about an error
+ *
+ * @beta
+ */
+export declare class OperationError extends Error {
+    protected _type: string;
+    constructor(type: string, message: string);
+    get message(): string;
+    toString(): string;
+}
+
+/**
+ * A class which manages the execution of a set of tasks with interdependencies.
+ * Initially, and at the end of each task execution, all unblocked tasks
+ * are added to a ready queue which is then executed. This is done continually until all
+ * tasks are complete, or prematurely fails if any of the tasks fail.
+ *
+ * @beta
+ */
+export declare class OperationExecutionManager {
+    /**
+     * The set of operations that will be executed
+     */
+    private readonly _operations;
+    /**
+     * Group records are metadata-only entities used for tracking the start and end of a set of related tasks.
+     * This is the only extent to which the operation graph is aware of Heft phases.
+     */
+    private readonly _groupRecordByName;
+    /**
+     * The total number of non-silent operations in the graph.
+     * Silent operations are generally used to simplify the construction of the graph.
+     */
+    private readonly _trackedOperationCount;
+    constructor(operations: ReadonlySet<Operation>);
+    /**
+     * Executes all operations which have been registered, returning a promise which is resolved when all the
+     * operations are completed successfully, or rejects when any operation fails.
+     */
+    executeAsync(executionOptions: IOperationExecutionOptions): Promise<OperationStatus>;
+}
+
+/**
+ * Meta-entity that tracks information about a group of related operations.
+ *
+ * @beta
+ */
+export declare class OperationGroupRecord {
+    private readonly _operations;
+    private _remainingOperations;
+    private _groupStopwatch;
+    private _hasCancellations;
+    private _hasFailures;
+    readonly name: string;
+    get duration(): number;
+    get finished(): boolean;
+    get hasCancellations(): boolean;
+    get hasFailures(): boolean;
+    constructor(name: string);
+    addOperation(operation: Operation): void;
+    startTimer(): void;
+    setOperationAsComplete(operation: Operation, state: IOperationState): void;
+    reset(): void;
+}
+
+/**
+ * Enumeration defining potential states of an operation
+ * @beta
+ */
+export declare enum OperationStatus {
+    /**
+     * The Operation is on the queue, ready to execute
+     */
+    Ready = "READY",
+    /**
+     * The Operation is on the queue, waiting for one or more depencies
+     */
+    Waiting = "WAITING",
+    /**
+     * The Operation is currently executing
+     */
+    Executing = "EXECUTING",
+    /**
+     * The Operation completed successfully and did not write to standard output
+     */
+    Success = "SUCCESS",
+    /**
+     * The Operation failed
+     */
+    Failure = "FAILURE",
+    /**
+     * The operation was aborted
+     */
+    Aborted = "ABORTED",
+    /**
+     * The Operation could not be executed because one or more of its dependencies failed
+     */
+    Blocked = "BLOCKED",
+    /**
+     * The operation performed no meaningful work.
+     */
+    NoOp = "NO OP"
+}
+
+/**
+ * Represents a typical timer/stopwatch which keeps track
+ * of elapsed time in between two events.
+ *
+ * @public
+ */
+export declare class Stopwatch {
+    private _startTime;
+    private _endTime;
+    private _running;
+    constructor();
+    /**
+     * Static helper function which creates a stopwatch which is immediately started
+     */
+    static start(): Stopwatch;
+    get isRunning(): boolean;
+    /**
+     * Starts the stopwatch. Note that if end() has been called,
+     * reset() should be called before calling start() again.
+     */
+    start(): Stopwatch;
+    /**
+     * Stops executing the stopwatch and saves the current timestamp
+     */
+    stop(): Stopwatch;
+    /**
+     * Resets all values of the stopwatch back to the original
+     */
+    reset(): Stopwatch;
+    /**
+     * Displays how long the stopwatch has been executing in a human readable format.
+     */
+    toString(): string;
+    /**
+     * Get the duration in seconds.
+     */
+    get duration(): number;
+    /**
+     * Return the start time of the most recent stopwatch run.
+     */
+    get startTime(): number | undefined;
+    /**
+     * Return the end time of the most recent stopwatch run.
+     */
+    get endTime(): number | undefined;
+}
+
+/**
+ * This class implements a watch loop.
+ *
+ * @beta
+ */
+export declare class WatchLoop implements IWatchLoopState {
+    private readonly _options;
+    private readonly _outerSignals;
+    private _abortController;
+    private _isRunning;
+    private _runRequested;
+    private _requestRunPromise;
+    private _resolveRequestRun;
+    constructor(options: IWatchLoopOptions);
+    /**
+     * Runs the inner loop until the abort signal is cancelled or a run completes without a new run being requested.
+     */
+    runUntilStableAsync(abortSignal: AbortSignal): Promise<OperationStatus>;
+    /**
+     * Runs the inner loop until the abort signal is aborted. Will otherwise wait indefinitely for a new run to be requested.
+     */
+    runUntilAbortedAsync(abortSignal: AbortSignal, onWaiting: () => void): Promise<void>;
+    /**
+     * Sets up an IPC handler that will run the inner loop when it receives a "run" message from the host.
+     * Runs until receiving an "exit" message from the host, or aborts early if an unhandled error is thrown.
+     */
+    runIPCAsync(host?: IPCHost): Promise<void>;
+    /**
+     * Requests that a new run occur.
+     */
+    requestRun: (requestor?: string) => void;
+    /**
+     * The abort signal for the current iteration.
+     */
+    get abortSignal(): AbortSignal;
+    /**
+     * Cancels the current iteration (if possible).
+     */
+    private _abortCurrent;
+    /**
+     * Resets the abort signal and run request state.
+     */
+    private _reset;
+}
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.37.0"
+    }
+  ]
+}

package/lib/IOperationRunner.d.ts

@@ -0,0 +1,85 @@
+/// <reference types="node" />
+import type { OperationStatus } from './OperationStatus';
+import type { OperationError } from './OperationError';
+import type { Stopwatch } from './Stopwatch';
+/**
+ * Information passed to the executing `IOperationRunner`
+ *
+ * @beta
+ */
+export interface IOperationRunnerContext {
+    /**
+     * An abort signal for the overarching execution. Runners should do their best to gracefully abort
+     * as soon as possible if the signal is aborted.
+     */
+    abortSignal: AbortSignal;
+    /**
+     * If this is the first time this operation has been executed.
+     */
+    isFirstRun: boolean;
+    /**
+     * A callback to the overarching orchestrator to request that the operation be invoked again.
+     * Used in watch mode to signal that inputs have changed.
+     */
+    requestRun?: () => void;
+}
+/**
+ * Interface contract for a single state of an operation.
+ *
+ * @beta
+ */
+export interface IOperationState {
+    /**
+     * The status code for the operation.
+     */
+    status: OperationStatus;
+    /**
+     * Whether the operation has been run at least once.
+     */
+    hasBeenRun: boolean;
+    /**
+     * The error, if the status is `OperationStatus.Failure`.
+     */
+    error: OperationError | undefined;
+    /**
+     * Timing information for the operation.
+     */
+    stopwatch: Stopwatch;
+}
+/**
+ * Interface contract for the current and past state of an operation.
+ *
+ * @beta
+ */
+export interface IOperationStates {
+    /**
+     * The current state of the operation.
+     */
+    readonly state: Readonly<IOperationState> | undefined;
+    /**
+     * The previous state of the operation.
+     */
+    readonly lastState: Readonly<IOperationState> | undefined;
+}
+/**
+ * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
+ * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * implementation manages the actual process for running a single operation.
+ *
+ * @beta
+ */
+export interface IOperationRunner {
+    /**
+     * Name of the operation, for logging.
+     */
+    readonly name: string;
+    /**
+     * Indicates that this runner is architectural and should not be reported on.
+     */
+    silent: boolean;
+    /**
+     * Method to be executed for the operation.
+     */
+    executeAsync(context: IOperationRunnerContext): Promise<OperationStatus>;
+}
+//# sourceMappingURL=IOperationRunner.d.ts.map

package/lib/IOperationRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IOperationRunner.d.ts","sourceRoot":"","sources":["../src/IOperationRunner.ts"],"names":[],"mappings":";AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC;IAEzB;;OAEG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,MAAM,EAAE,eAAe,CAAC;IACxB;;OAEG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;OAEG;IACH,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC;IAClC;;OAEG;IACH,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,SAAS,CAAC;IACtD;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,SAAS,CAAC;CAC3D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC1E"}