@rushstack/operation-graph 0.5.7 → 0.6.1

package/lib-esm/OperationStatus.js

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * Enumeration defining potential states of an operation
+ * @beta
+ */
+export var OperationStatus;
+(function (OperationStatus) {
+    /**
+     * The Operation is on the queue, ready to execute
+     */
+    OperationStatus["Ready"] = "READY";
+    /**
+     * The Operation is on the queue, waiting for one or more depencies
+     */
+    OperationStatus["Waiting"] = "WAITING";
+    /**
+     * The Operation is currently executing
+     */
+    OperationStatus["Executing"] = "EXECUTING";
+    /**
+     * The Operation completed successfully and did not write to standard output
+     */
+    OperationStatus["Success"] = "SUCCESS";
+    /**
+     * The Operation failed
+     */
+    OperationStatus["Failure"] = "FAILURE";
+    /**
+     * The operation was aborted
+     */
+    OperationStatus["Aborted"] = "ABORTED";
+    /**
+     * The Operation could not be executed because one or more of its dependencies failed
+     */
+    OperationStatus["Blocked"] = "BLOCKED";
+    /**
+     * The operation performed no meaningful work.
+     */
+    OperationStatus["NoOp"] = "NO OP";
+})(OperationStatus || (OperationStatus = {}));
+//# sourceMappingURL=OperationStatus.js.map

package/lib-esm/OperationStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OperationStatus.js","sourceRoot":"","sources":["../src/OperationStatus.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D;;;GAGG;AACH,MAAM,CAAN,IAAY,eAiCX;AAjCD,WAAY,eAAe;IACzB;;OAEG;IACH,kCAAe,CAAA;IACf;;OAEG;IACH,sCAAmB,CAAA;IACnB;;OAEG;IACH,0CAAuB,CAAA;IACvB;;OAEG;IACH,sCAAmB,CAAA;IACnB;;OAEG;IACH,sCAAmB,CAAA;IACnB;;OAEG;IACH,sCAAmB,CAAA;IACnB;;OAEG;IACH,sCAAmB,CAAA;IACnB;;OAEG;IACH,iCAAc,CAAA;AAChB,CAAC,EAjCW,eAAe,KAAf,eAAe,QAiC1B","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/**\n * Enumeration defining potential states of an operation\n * @beta\n */\nexport enum OperationStatus {\n  /**\n   * The Operation is on the queue, ready to execute\n   */\n  Ready = 'READY',\n  /**\n   * The Operation is on the queue, waiting for one or more depencies\n   */\n  Waiting = 'WAITING',\n  /**\n   * The Operation is currently executing\n   */\n  Executing = 'EXECUTING',\n  /**\n   * The Operation completed successfully and did not write to standard output\n   */\n  Success = 'SUCCESS',\n  /**\n   * The Operation failed\n   */\n  Failure = 'FAILURE',\n  /**\n   * The operation was aborted\n   */\n  Aborted = 'ABORTED',\n  /**\n   * The Operation could not be executed because one or more of its dependencies failed\n   */\n  Blocked = 'BLOCKED',\n  /**\n   * The operation performed no meaningful work.\n   */\n  NoOp = 'NO OP'\n}\n"]}

package/lib-esm/Stopwatch.js

@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * Represents a typical timer/stopwatch which keeps track
+ * of elapsed time in between two events.
+ *
+ * @public
+ */
+export class Stopwatch {
+    constructor() {
+        this._startTime = undefined;
+        this._endTime = undefined;
+        this._running = false;
+    }
+    /**
+     * Static helper function which creates a stopwatch which is immediately started
+     */
+    static start() {
+        return new Stopwatch().start();
+    }
+    get isRunning() {
+        return this._running;
+    }
+    /**
+     * Starts the stopwatch. Note that if end() has been called,
+     * reset() should be called before calling start() again.
+     */
+    start() {
+        if (this._startTime !== undefined) {
+            throw new Error('Call reset() before starting the Stopwatch');
+        }
+        this._startTime = performance.now();
+        this._endTime = undefined;
+        this._running = true;
+        return this;
+    }
+    /**
+     * Stops executing the stopwatch and saves the current timestamp
+     */
+    stop() {
+        this._endTime = this._startTime !== undefined ? performance.now() : undefined;
+        this._running = false;
+        return this;
+    }
+    /**
+     * Resets all values of the stopwatch back to the original
+     */
+    reset() {
+        this._endTime = this._startTime = undefined;
+        this._running = false;
+        return this;
+    }
+    /**
+     * Displays how long the stopwatch has been executing in a human readable format.
+     */
+    toString() {
+        if (!this._running && this._startTime === undefined) {
+            return '0.00 seconds (stopped)';
+        }
+        const totalSeconds = this.duration;
+        if (totalSeconds > 60) {
+            const minutes = Math.floor(totalSeconds / 60);
+            const seconds = totalSeconds % 60.0;
+            return `${minutes.toFixed(0)} minute${minutes === 1 ? '' : 's'} ${seconds.toFixed(1)} seconds`;
+        }
+        else {
+            return `${totalSeconds.toFixed(2)} seconds`;
+        }
+    }
+    /**
+     * Get the duration in seconds.
+     */
+    get duration() {
+        if (this._startTime === undefined) {
+            return 0;
+        }
+        const curTime = this._endTime !== undefined ? this._endTime : performance.now();
+        return (curTime - this._startTime) / 1000.0;
+    }
+    /**
+     * Return the start time of the most recent stopwatch run.
+     */
+    get startTime() {
+        return this._startTime;
+    }
+    /**
+     * Return the end time of the most recent stopwatch run.
+     */
+    get endTime() {
+        return this._endTime;
+    }
+}
+//# sourceMappingURL=Stopwatch.js.map

package/lib-esm/Stopwatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stopwatch.js","sourceRoot":"","sources":["../src/Stopwatch.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D;;;;;GAKG;AACH,MAAM,OAAO,SAAS;IAKpB;QACE,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACxB,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,KAAK;QACjB,OAAO,IAAI,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC;IACjC,CAAC;IAED,IAAW,SAAS;QAClB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;OAGG;IACI,KAAK;QACV,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,IAAI;QACT,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9E,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,KAAK;QACV,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,QAAQ;QACb,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACpD,OAAO,wBAAwB,CAAC;QAClC,CAAC;QACD,MAAM,YAAY,GAAW,IAAI,CAAC,QAAQ,CAAC;QAE3C,IAAI,YAAY,GAAG,EAAE,EAAE,CAAC;YACtB,MAAM,OAAO,GAAW,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;YACtD,MAAM,OAAO,GAAW,YAAY,GAAG,IAAI,CAAC;YAE5C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;QACjG,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;QAC9C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAW,QAAQ;QACjB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,OAAO,GAAW,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;QAExF,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,IAAW,SAAS;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/**\n * Represents a typical timer/stopwatch which keeps track\n * of elapsed time in between two events.\n *\n * @public\n */\nexport class Stopwatch {\n  private _startTime: number | undefined;\n  private _endTime: number | undefined;\n  private _running: boolean;\n\n  public constructor() {\n    this._startTime = undefined;\n    this._endTime = undefined;\n    this._running = false;\n  }\n\n  /**\n   * Static helper function which creates a stopwatch which is immediately started\n   */\n  public static start(): Stopwatch {\n    return new Stopwatch().start();\n  }\n\n  public get isRunning(): boolean {\n    return this._running;\n  }\n\n  /**\n   * Starts the stopwatch. Note that if end() has been called,\n   * reset() should be called before calling start() again.\n   */\n  public start(): Stopwatch {\n    if (this._startTime !== undefined) {\n      throw new Error('Call reset() before starting the Stopwatch');\n    }\n    this._startTime = performance.now();\n    this._endTime = undefined;\n    this._running = true;\n    return this;\n  }\n\n  /**\n   * Stops executing the stopwatch and saves the current timestamp\n   */\n  public stop(): Stopwatch {\n    this._endTime = this._startTime !== undefined ? performance.now() : undefined;\n    this._running = false;\n    return this;\n  }\n\n  /**\n   * Resets all values of the stopwatch back to the original\n   */\n  public reset(): Stopwatch {\n    this._endTime = this._startTime = undefined;\n    this._running = false;\n    return this;\n  }\n\n  /**\n   * Displays how long the stopwatch has been executing in a human readable format.\n   */\n  public toString(): string {\n    if (!this._running && this._startTime === undefined) {\n      return '0.00 seconds (stopped)';\n    }\n    const totalSeconds: number = this.duration;\n\n    if (totalSeconds > 60) {\n      const minutes: number = Math.floor(totalSeconds / 60);\n      const seconds: number = totalSeconds % 60.0;\n\n      return `${minutes.toFixed(0)} minute${minutes === 1 ? '' : 's'} ${seconds.toFixed(1)} seconds`;\n    } else {\n      return `${totalSeconds.toFixed(2)} seconds`;\n    }\n  }\n\n  /**\n   * Get the duration in seconds.\n   */\n  public get duration(): number {\n    if (this._startTime === undefined) {\n      return 0;\n    }\n    const curTime: number = this._endTime !== undefined ? this._endTime : performance.now();\n\n    return (curTime - this._startTime) / 1000.0;\n  }\n\n  /**\n   * Return the start time of the most recent stopwatch run.\n   */\n  public get startTime(): number | undefined {\n    return this._startTime;\n  }\n\n  /**\n   * Return the end time of the most recent stopwatch run.\n   */\n  public get endTime(): number | undefined {\n    return this._endTime;\n  }\n}\n"]}

package/lib-esm/WatchLoop.js

@@ -0,0 +1,210 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { once } from 'node:events';
+import { AlreadyReportedError } from '@rushstack/node-core-library';
+import { OperationStatus } from './OperationStatus';
+/**
+ * This class implements a watch loop.
+ *
+ * @beta
+ */
+export class WatchLoop {
+    constructor(options) {
+        /**
+         * Requests that a new run occur.
+         */
+        this.requestRun = (requestor, detail) => {
+            if (!this._runRequested) {
+                this._options.onRequestRun(requestor, detail);
+                this._runRequested = true;
+                if (this._isRunning) {
+                    this._options.onAbort();
+                    this._abortCurrent();
+                }
+            }
+            this._resolveRequestRun([requestor, detail]);
+        };
+        /**
+         * Cancels the current iteration (if possible).
+         */
+        this._abortCurrent = () => {
+            this._abortController.abort();
+        };
+        this._options = options;
+        this._abortController = new AbortController();
+        this._isRunning = false;
+        // Always start as true, so that any requests prior to first run are silenced.
+        this._runRequested = true;
+        this._requestRunPromise = new Promise((resolve) => {
+            this._resolveRequestRun = resolve;
+        });
+    }
+    /**
+     * Runs the inner loop until the abort signal is cancelled or a run completes without a new run being requested.
+     */
+    async runUntilStableAsync(abortSignal) {
+        if (abortSignal.aborted) {
+            return OperationStatus.Aborted;
+        }
+        abortSignal.addEventListener('abort', this._abortCurrent, { once: true });
+        try {
+            let result = OperationStatus.Ready;
+            do {
+                // Always check the abort signal first, in case it was aborted in the async tick since the last executeAsync() call.
+                if (abortSignal.aborted) {
+                    return OperationStatus.Aborted;
+                }
+                result = await this._runIterationAsync();
+            } while (this._runRequested);
+            // Even if the run has finished, if the abort signal was aborted, we should return `Aborted` just in case.
+            return abortSignal.aborted ? OperationStatus.Aborted : result;
+        }
+        finally {
+            abortSignal.removeEventListener('abort', this._abortCurrent);
+        }
+    }
+    /**
+     * Runs the inner loop until the abort signal is aborted. Will otherwise wait indefinitely for a new run to be requested.
+     */
+    async runUntilAbortedAsync(abortSignal, onWaiting) {
+        if (abortSignal.aborted) {
+            return;
+        }
+        const abortPromise = once(abortSignal, 'abort');
+        while (!abortSignal.aborted) {
+            await this.runUntilStableAsync(abortSignal);
+            onWaiting();
+            await Promise.race([this._requestRunPromise, abortPromise]);
+        }
+    }
+    /**
+     * 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.
+     */
+    async runIPCAsync(host = process) {
+        await new Promise((resolve, reject) => {
+            let abortController = new AbortController();
+            let runRequestedFromHost = true;
+            let status = OperationStatus.Ready;
+            function tryMessageHost(message) {
+                if (!host.send) {
+                    return reject(new Error('Host does not support IPC'));
+                }
+                try {
+                    host.send(message);
+                }
+                catch (err) {
+                    reject(new Error(`Unable to communicate with host: ${err}`));
+                }
+            }
+            function requestRunFromHost(requestor, detail) {
+                if (runRequestedFromHost) {
+                    return;
+                }
+                runRequestedFromHost = true;
+                const requestRunMessage = {
+                    event: 'requestRun',
+                    requestor,
+                    detail
+                };
+                tryMessageHost(requestRunMessage);
+            }
+            function sendSync() {
+                const syncMessage = {
+                    event: 'sync',
+                    status
+                };
+                tryMessageHost(syncMessage);
+            }
+            host.on('message', async (message) => {
+                switch (message.command) {
+                    case 'exit': {
+                        return resolve();
+                    }
+                    case 'cancel': {
+                        if (this._isRunning) {
+                            abortController.abort();
+                            abortController = new AbortController();
+                            // This will terminate the currently executing `runUntilStableAsync` call.
+                        }
+                        return;
+                    }
+                    case 'run': {
+                        runRequestedFromHost = false;
+                        status = OperationStatus.Executing;
+                        try {
+                            status = await this.runUntilStableAsync(abortController.signal);
+                            // ESLINT: "Promises must be awaited, end with a call to .catch, end with a call to .then ..."
+                            this._requestRunPromise.then(([requestor, detail]) => requestRunFromHost(requestor, detail), (error) => {
+                                // Unreachable code. The promise will never be rejected.
+                            });
+                        }
+                        catch (err) {
+                            status = OperationStatus.Failure;
+                            return reject(err);
+                        }
+                        finally {
+                            const afterExecuteMessage = {
+                                event: 'after-execute',
+                                status
+                            };
+                            tryMessageHost(afterExecuteMessage);
+                        }
+                        return;
+                    }
+                    case 'sync': {
+                        return sendSync();
+                    }
+                    default: {
+                        return reject(new Error(`Unexpected command from host: ${message}`));
+                    }
+                }
+            });
+            sendSync();
+        });
+    }
+    /**
+     * The abort signal for the current iteration.
+     */
+    get abortSignal() {
+        return this._abortController.signal;
+    }
+    /**
+     * Resets the abort signal and run request state.
+     */
+    _reset() {
+        if (this._abortController.signal.aborted) {
+            this._abortController = new AbortController();
+        }
+        if (this._runRequested) {
+            this._runRequested = false;
+            this._requestRunPromise = new Promise((resolve) => {
+                this._resolveRequestRun = resolve;
+            });
+        }
+    }
+    /**
+     * Runs a single iteration of the loop.
+     * @returns The status of the iteration.
+     */
+    async _runIterationAsync() {
+        this._reset();
+        this._options.onBeforeExecute();
+        try {
+            this._isRunning = true;
+            return await this._options.executeAsync(this);
+        }
+        catch (err) {
+            if (!(err instanceof AlreadyReportedError)) {
+                throw err;
+            }
+            else {
+                return OperationStatus.Failure;
+            }
+        }
+        finally {
+            this._isRunning = false;
+        }
+    }
+}
+//# sourceMappingURL=WatchLoop.js.map

package/lib-esm/WatchLoop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WatchLoop.js","sourceRoot":"","sources":["../src/WatchLoop.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport { once } from 'node:events';\n\nimport { AlreadyReportedError } from '@rushstack/node-core-library';\n\nimport type { OperationRequestRunCallback } from './Operation';\nimport { OperationStatus } from './OperationStatus';\nimport type {\n  IAfterExecuteEventMessage,\n  IPCHost,\n  CommandMessageFromHost,\n  ISyncEventMessage,\n  IRequestRunEventMessage\n} from './protocol.types';\n\n/**\n * Callbacks for the watch loop.\n *\n * @beta\n */\nexport interface IWatchLoopOptions {\n  /**\n   * Callback that performs the core work of a single iteration.\n   */\n  executeAsync: (state: IWatchLoopState) => Promise<OperationStatus>;\n  /**\n   * Logging callback immediately before execution occurs.\n   */\n  onBeforeExecute: () => void;\n  /**\n   * Logging callback when a run is requested (and hasn't already been).\n   *\n   * @param requestor - The name of the operation requesting a rerun.\n   * @param detail - Optional detail about why the rerun is requested, e.g. the name of a changed file.\n   */\n  onRequestRun: OperationRequestRunCallback;\n  /**\n   * Logging callback when a run is aborted.\n   */\n  onAbort: () => void;\n}\n\n/**\n * The public API surface of the watch loop, for use in the `executeAsync` callback.\n *\n * @beta\n */\nexport interface IWatchLoopState {\n  get abortSignal(): AbortSignal;\n  requestRun: OperationRequestRunCallback;\n}\n\n/**\n * This class implements a watch loop.\n *\n * @beta\n */\nexport class WatchLoop implements IWatchLoopState {\n  private readonly _options: Readonly<IWatchLoopOptions>;\n\n  private _abortController: AbortController;\n  private _isRunning: boolean;\n  private _runRequested: boolean;\n  private _requestRunPromise: Promise<[string, string?]>;\n  private _resolveRequestRun!: (value: [string, string?]) => void;\n\n  public constructor(options: IWatchLoopOptions) {\n    this._options = options;\n\n    this._abortController = new AbortController();\n    this._isRunning = false;\n    // Always start as true, so that any requests prior to first run are silenced.\n    this._runRequested = true;\n    this._requestRunPromise = new Promise<[string, string?]>((resolve) => {\n      this._resolveRequestRun = resolve;\n    });\n  }\n\n  /**\n   * Runs the inner loop until the abort signal is cancelled or a run completes without a new run being requested.\n   */\n  public async runUntilStableAsync(abortSignal: AbortSignal): Promise<OperationStatus> {\n    if (abortSignal.aborted) {\n      return OperationStatus.Aborted;\n    }\n\n    abortSignal.addEventListener('abort', this._abortCurrent, { once: true });\n\n    try {\n      let result: OperationStatus = OperationStatus.Ready;\n\n      do {\n        // Always check the abort signal first, in case it was aborted in the async tick since the last executeAsync() call.\n        if (abortSignal.aborted) {\n          return OperationStatus.Aborted;\n        }\n\n        result = await this._runIterationAsync();\n      } while (this._runRequested);\n\n      // Even if the run has finished, if the abort signal was aborted, we should return `Aborted` just in case.\n      return abortSignal.aborted ? OperationStatus.Aborted : result;\n    } finally {\n      abortSignal.removeEventListener('abort', this._abortCurrent);\n    }\n  }\n\n  /**\n   * Runs the inner loop until the abort signal is aborted. Will otherwise wait indefinitely for a new run to be requested.\n   */\n  public async runUntilAbortedAsync(abortSignal: AbortSignal, onWaiting: () => void): Promise<void> {\n    if (abortSignal.aborted) {\n      return;\n    }\n\n    const abortPromise: Promise<unknown> = once(abortSignal, 'abort');\n\n    while (!abortSignal.aborted) {\n      await this.runUntilStableAsync(abortSignal);\n\n      onWaiting();\n      await Promise.race([this._requestRunPromise, abortPromise]);\n    }\n  }\n\n  /**\n   * Sets up an IPC handler that will run the inner loop when it receives a \"run\" message from the host.\n   * Runs until receiving an \"exit\" message from the host, or aborts early if an unhandled error is thrown.\n   */\n  public async runIPCAsync(host: IPCHost = process): Promise<void> {\n    await new Promise<void>((resolve, reject) => {\n      let abortController: AbortController = new AbortController();\n\n      let runRequestedFromHost: boolean = true;\n      let status: OperationStatus = OperationStatus.Ready;\n\n      function tryMessageHost(\n        message: ISyncEventMessage | IRequestRunEventMessage | IAfterExecuteEventMessage\n      ): void {\n        if (!host.send) {\n          return reject(new Error('Host does not support IPC'));\n        }\n\n        try {\n          host.send(message);\n        } catch (err) {\n          reject(new Error(`Unable to communicate with host: ${err}`));\n        }\n      }\n\n      function requestRunFromHost(requestor: string, detail?: string): void {\n        if (runRequestedFromHost) {\n          return;\n        }\n\n        runRequestedFromHost = true;\n\n        const requestRunMessage: IRequestRunEventMessage = {\n          event: 'requestRun',\n          requestor,\n          detail\n        };\n\n        tryMessageHost(requestRunMessage);\n      }\n\n      function sendSync(): void {\n        const syncMessage: ISyncEventMessage = {\n          event: 'sync',\n          status\n        };\n        tryMessageHost(syncMessage);\n      }\n\n      host.on('message', async (message: CommandMessageFromHost) => {\n        switch (message.command) {\n          case 'exit': {\n            return resolve();\n          }\n\n          case 'cancel': {\n            if (this._isRunning) {\n              abortController.abort();\n              abortController = new AbortController();\n              // This will terminate the currently executing `runUntilStableAsync` call.\n            }\n            return;\n          }\n\n          case 'run': {\n            runRequestedFromHost = false;\n\n            status = OperationStatus.Executing;\n\n            try {\n              status = await this.runUntilStableAsync(abortController.signal);\n              // ESLINT: \"Promises must be awaited, end with a call to .catch, end with a call to .then ...\"\n              this._requestRunPromise.then(\n                ([requestor, detail]) => requestRunFromHost(requestor, detail),\n                (error: Error) => {\n                  // Unreachable code. The promise will never be rejected.\n                }\n              );\n            } catch (err) {\n              status = OperationStatus.Failure;\n              return reject(err);\n            } finally {\n              const afterExecuteMessage: IAfterExecuteEventMessage = {\n                event: 'after-execute',\n                status\n              };\n              tryMessageHost(afterExecuteMessage);\n            }\n            return;\n          }\n\n          case 'sync': {\n            return sendSync();\n          }\n\n          default: {\n            return reject(new Error(`Unexpected command from host: ${message}`));\n          }\n        }\n      });\n\n      sendSync();\n    });\n  }\n\n  /**\n   * Requests that a new run occur.\n   */\n  public requestRun: OperationRequestRunCallback = (requestor: string, detail?: string) => {\n    if (!this._runRequested) {\n      this._options.onRequestRun(requestor, detail);\n      this._runRequested = true;\n      if (this._isRunning) {\n        this._options.onAbort();\n        this._abortCurrent();\n      }\n    }\n    this._resolveRequestRun([requestor, detail]);\n  };\n\n  /**\n   * The abort signal for the current iteration.\n   */\n  public get abortSignal(): AbortSignal {\n    return this._abortController.signal;\n  }\n\n  /**\n   * Cancels the current iteration (if possible).\n   */\n  private _abortCurrent = (): void => {\n    this._abortController.abort();\n  };\n\n  /**\n   * Resets the abort signal and run request state.\n   */\n  private _reset(): void {\n    if (this._abortController.signal.aborted) {\n      this._abortController = new AbortController();\n    }\n\n    if (this._runRequested) {\n      this._runRequested = false;\n      this._requestRunPromise = new Promise<[string, string?]>((resolve) => {\n        this._resolveRequestRun = resolve;\n      });\n    }\n  }\n\n  /**\n   * Runs a single iteration of the loop.\n   * @returns The status of the iteration.\n   */\n  private async _runIterationAsync(): Promise<OperationStatus> {\n    this._reset();\n\n    this._options.onBeforeExecute();\n    try {\n      this._isRunning = true;\n      return await this._options.executeAsync(this);\n    } catch (err) {\n      if (!(err instanceof AlreadyReportedError)) {\n        throw err;\n      } else {\n        return OperationStatus.Failure;\n      }\n    } finally {\n      this._isRunning = false;\n    }\n  }\n}\n"]}

package/lib-esm/WorkQueue.js

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { Async, MinimumHeap } from '@rushstack/node-core-library';
+import { OperationStatus } from './OperationStatus';
+export class WorkQueue {
+    constructor(abortSignal) {
+        // Sort by priority descending. Thus the comparator returns a negative number if a has higher priority than b.
+        this._queue = new MinimumHeap((a, b) => b.priority - a.priority);
+        this._abortSignal = abortSignal;
+        this._abortPromise = abortSignal.aborted
+            ? Promise.resolve()
+            : new Promise((resolve) => {
+                abortSignal.addEventListener('abort', () => resolve(), { once: true });
+            });
+        [this._pushPromise, this._resolvePush] = Async.getSignal();
+        this._resolvePushTimeout = undefined;
+    }
+    async *[Symbol.asyncIterator]() {
+        while (!this._abortSignal.aborted) {
+            while (this._queue.size > 0) {
+                const item = this._queue.poll();
+                yield item.task;
+            }
+            await Promise.race([this._pushPromise, this._abortPromise]);
+        }
+    }
+    pushAsync(task, priority) {
+        return new Promise((resolve, reject) => {
+            this._queue.push({
+                task: () => task().then(resolve, reject),
+                priority
+            });
+            // ESLINT: "Promises must be awaited, end with a call to .catch, end with a call to .then ..."
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
+            this._abortPromise.finally(() => resolve(OperationStatus.Aborted));
+            this._resolvePushDebounced();
+        });
+    }
+    _resolvePushDebounced() {
+        if (!this._resolvePushTimeout) {
+            this._resolvePushTimeout = setTimeout(() => {
+                this._resolvePushTimeout = undefined;
+                this._resolvePush();
+                [this._pushPromise, this._resolvePush] = Async.getSignal();
+            });
+        }
+    }
+}
+//# sourceMappingURL=WorkQueue.js.map

package/lib-esm/WorkQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkQueue.js","sourceRoot":"","sources":["../src/WorkQueue.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAElE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAOpD,MAAM,OAAO,SAAS;IASpB,YAAmB,WAAwB;QACzC,8GAA8G;QAC9G,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,CAAC,CAAa,EAAE,CAAa,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QACzF,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;QAChC,IAAI,CAAC,aAAa,GAAG,WAAW,CAAC,OAAO;YACtC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE;YACnB,CAAC,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAC5B,WAAW,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACzE,CAAC,CAAC,CAAC;QAEP,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;QAC3D,IAAI,CAAC,mBAAmB,GAAG,SAAS,CAAC;IACvC,CAAC;IAEM,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,GAAe,IAAI,CAAC,MAAM,CAAC,IAAI,EAAG,CAAC;gBAC7C,MAAM,IAAI,CAAC,IAAI,CAAC;YAClB,CAAC;YAED,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAEM,SAAS,CAAC,IAAoC,EAAE,QAAgB;QACrE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC;gBACxC,QAAQ;aACT,CAAC,CAAC;YAEH,8FAA8F;YAC9F,mEAAmE;YACnE,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;YAEnE,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC/B,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,qBAAqB;QAC3B,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC9B,IAAI,CAAC,mBAAmB,GAAG,UAAU,CAAC,GAAG,EAAE;gBACzC,IAAI,CAAC,mBAAmB,GAAG,SAAS,CAAC;gBACrC,IAAI,CAAC,YAAY,EAAE,CAAC;gBAEpB,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC7D,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport { Async, MinimumHeap } from '@rushstack/node-core-library';\n\nimport { OperationStatus } from './OperationStatus';\n\ninterface IQueueItem {\n  task: () => Promise<void>;\n  priority: number;\n}\n\nexport class WorkQueue {\n  private readonly _queue: MinimumHeap<IQueueItem>;\n  private readonly _abortSignal: AbortSignal;\n  private readonly _abortPromise: Promise<void>;\n\n  private _pushPromise: Promise<void>;\n  private _resolvePush: () => void;\n  private _resolvePushTimeout: NodeJS.Timeout | undefined;\n\n  public constructor(abortSignal: AbortSignal) {\n    // Sort by priority descending. Thus the comparator returns a negative number if a has higher priority than b.\n    this._queue = new MinimumHeap((a: IQueueItem, b: IQueueItem) => b.priority - a.priority);\n    this._abortSignal = abortSignal;\n    this._abortPromise = abortSignal.aborted\n      ? Promise.resolve()\n      : new Promise<void>((resolve) => {\n          abortSignal.addEventListener('abort', () => resolve(), { once: true });\n        });\n\n    [this._pushPromise, this._resolvePush] = Async.getSignal();\n    this._resolvePushTimeout = undefined;\n  }\n\n  public async *[Symbol.asyncIterator](): AsyncIterableIterator<() => Promise<void>> {\n    while (!this._abortSignal.aborted) {\n      while (this._queue.size > 0) {\n        const item: IQueueItem = this._queue.poll()!;\n        yield item.task;\n      }\n\n      await Promise.race([this._pushPromise, this._abortPromise]);\n    }\n  }\n\n  public pushAsync(task: () => Promise<OperationStatus>, priority: number): Promise<OperationStatus> {\n    return new Promise((resolve, reject) => {\n      this._queue.push({\n        task: () => task().then(resolve, reject),\n        priority\n      });\n\n      // ESLINT: \"Promises must be awaited, end with a call to .catch, end with a call to .then ...\"\n      // eslint-disable-next-line @typescript-eslint/no-floating-promises\n      this._abortPromise.finally(() => resolve(OperationStatus.Aborted));\n\n      this._resolvePushDebounced();\n    });\n  }\n\n  private _resolvePushDebounced(): void {\n    if (!this._resolvePushTimeout) {\n      this._resolvePushTimeout = setTimeout(() => {\n        this._resolvePushTimeout = undefined;\n        this._resolvePush();\n\n        [this._pushPromise, this._resolvePush] = Async.getSignal();\n      });\n    }\n  }\n}\n"]}

package/lib-esm/calculateCriticalPath.js

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * For every operation in the input, computes the length of the longest chain of operations that depend on it.
+ * This value is stored as `operation.criticalPathLength`.
+ */
+export function calculateCriticalPathLengths(operations) {
+    // Clone the set of operations as an array, so that we can sort it.
+    const queue = Array.from(operations);
+    // Create a collection for detecting visited nodes
+    const cycleDetectorStack = new Set();
+    for (const operation of queue) {
+        calculateCriticalPathLength(operation, cycleDetectorStack);
+    }
+    return queue;
+}
+/**
+ * Calculates the shortest path from `startOperation` to `endOperation`.
+ * Used when printing out circular dependencies.
+ */
+export function calculateShortestPath(startOperation, endOperation) {
+    // Map of each operation to the most optimal parent
+    const parents = new Map([[endOperation, undefined]]);
+    let finalParent;
+    // Run a breadth-first search to find the shortest path between the start and end operations
+    outer: for (const [operation] of parents) {
+        for (const consumer of operation.consumers) {
+            // Since this is a breadth-first traversal, the first encountered path to a given node
+            // will be tied for shortest, so only the first encountered path needs to be tracked
+            if (!parents.has(consumer)) {
+                parents.set(consumer, operation);
+            }
+            if (consumer === startOperation) {
+                finalParent = operation;
+                break outer;
+            }
+        }
+    }
+    if (!finalParent) {
+        throw new Error(`Could not find a path from "${startOperation.name}" to "${endOperation.name}"`);
+    }
+    // Walk back up the path from the end operation to the start operation
+    let currentOperation = finalParent;
+    const path = [startOperation];
+    while (currentOperation !== undefined) {
+        path.push(currentOperation);
+        currentOperation = parents.get(currentOperation);
+    }
+    return path;
+}
+/**
+ * Perform a depth-first search to find critical path length to the provided operation.
+ * Cycle detection comes at minimal additional cost.
+ */
+export function calculateCriticalPathLength(operation, dependencyChain) {
+    if (dependencyChain.has(operation)) {
+        // Ensure we have the shortest path to the cycle
+        const shortestPath = calculateShortestPath(operation, operation);
+        throw new Error('A cyclic dependency was encountered:\n  ' +
+            shortestPath.map((visitedTask) => visitedTask.name).join('\n  -> '));
+    }
+    let { criticalPathLength } = operation;
+    if (criticalPathLength !== undefined) {
+        // This has been visited already
+        return criticalPathLength;
+    }
+    criticalPathLength = 0;
+    if (operation.consumers.size) {
+        dependencyChain.add(operation);
+        for (const consumer of operation.consumers) {
+            criticalPathLength = Math.max(criticalPathLength, calculateCriticalPathLength(consumer, dependencyChain));
+        }
+        dependencyChain.delete(operation);
+    }
+    // Include the contribution from the current operation
+    criticalPathLength += operation.weight ?? 1;
+    // Record result
+    operation.criticalPathLength = criticalPathLength;
+    // Directly writing operations to an output collection here would yield a topological sorted set
+    // However, we want a bit more fine-tuning of the output than just the raw topology
+    return criticalPathLength;
+}
+//# sourceMappingURL=calculateCriticalPath.js.map

package/lib-esm/calculateCriticalPath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculateCriticalPath.js","sourceRoot":"","sources":["../src/calculateCriticalPath.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nexport interface ISortableOperation<T extends ISortableOperation<T>> {\n  name: string | undefined;\n  criticalPathLength?: number | undefined;\n  weight: number;\n  consumers: Set<T>;\n}\n\n/**\n * For every operation in the input, computes the length of the longest chain of operations that depend on it.\n * This value is stored as `operation.criticalPathLength`.\n */\nexport function calculateCriticalPathLengths<T extends ISortableOperation<T>>(operations: Iterable<T>): T[] {\n  // Clone the set of operations as an array, so that we can sort it.\n  const queue: T[] = Array.from(operations);\n\n  // Create a collection for detecting visited nodes\n  const cycleDetectorStack: Set<T> = new Set();\n  for (const operation of queue) {\n    calculateCriticalPathLength(operation, cycleDetectorStack);\n  }\n\n  return queue;\n}\n\n/**\n * Calculates the shortest path from `startOperation` to `endOperation`.\n * Used when printing out circular dependencies.\n */\nexport function calculateShortestPath<T extends ISortableOperation<T>>(\n  startOperation: T,\n  endOperation: T\n): T[] {\n  // Map of each operation to the most optimal parent\n  const parents: Map<T, T | undefined> = new Map([[endOperation, undefined]]);\n  let finalParent: T | undefined;\n\n  // Run a breadth-first search to find the shortest path between the start and end operations\n  outer: for (const [operation] of parents) {\n    for (const consumer of operation.consumers) {\n      // Since this is a breadth-first traversal, the first encountered path to a given node\n      // will be tied for shortest, so only the first encountered path needs to be tracked\n      if (!parents.has(consumer)) {\n        parents.set(consumer, operation);\n      }\n\n      if (consumer === startOperation) {\n        finalParent = operation;\n        break outer;\n      }\n    }\n  }\n\n  if (!finalParent) {\n    throw new Error(`Could not find a path from \"${startOperation.name}\" to \"${endOperation.name}\"`);\n  }\n\n  // Walk back up the path from the end operation to the start operation\n  let currentOperation: T = finalParent;\n  const path: T[] = [startOperation];\n  while (currentOperation !== undefined) {\n    path.push(currentOperation);\n    currentOperation = parents.get(currentOperation)!;\n  }\n  return path;\n}\n\n/**\n * Perform a depth-first search to find critical path length to the provided operation.\n * Cycle detection comes at minimal additional cost.\n */\nexport function calculateCriticalPathLength<T extends ISortableOperation<T>>(\n  operation: T,\n  dependencyChain: Set<T>\n): number {\n  if (dependencyChain.has(operation)) {\n    // Ensure we have the shortest path to the cycle\n    const shortestPath: T[] = calculateShortestPath(operation, operation);\n\n    throw new Error(\n      'A cyclic dependency was encountered:\\n  ' +\n        shortestPath.map((visitedTask) => visitedTask.name).join('\\n  -> ')\n    );\n  }\n\n  let { criticalPathLength } = operation;\n\n  if (criticalPathLength !== undefined) {\n    // This has been visited already\n    return criticalPathLength;\n  }\n\n  criticalPathLength = 0;\n  if (operation.consumers.size) {\n    dependencyChain.add(operation);\n    for (const consumer of operation.consumers) {\n      criticalPathLength = Math.max(\n        criticalPathLength,\n        calculateCriticalPathLength(consumer, dependencyChain)\n      );\n    }\n    dependencyChain.delete(operation);\n  }\n  // Include the contribution from the current operation\n  criticalPathLength += operation.weight ?? 1;\n\n  // Record result\n  operation.criticalPathLength = criticalPathLength;\n\n  // Directly writing operations to an output collection here would yield a topological sorted set\n  // However, we want a bit more fine-tuning of the output than just the raw topology\n\n  return criticalPathLength;\n}\n"]}

package/lib-esm/index.js

@@ -0,0 +1,10 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+export { Operation } from './Operation';
+export { OperationError } from './OperationError';
+export { OperationExecutionManager } from './OperationExecutionManager';
+export { OperationGroupRecord } from './OperationGroupRecord';
+export { OperationStatus } from './OperationStatus';
+export { Stopwatch } from './Stopwatch';
+export { WatchLoop } from './WatchLoop';
+//# sourceMappingURL=index.js.map

package/lib-esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAwB3D,OAAO,EAGL,SAAS,EAEV,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAmC,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAEzG,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAgD,SAAS,EAAE,MAAM,aAAa,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/// <reference types=\"node\" preserve=\"true\" />\n\nexport type {\n  IOperationRunner,\n  IOperationRunnerContext,\n  IOperationState,\n  IOperationStates\n} from './IOperationRunner';\n\nexport type {\n  IAfterExecuteEventMessage,\n  ISyncEventMessage,\n  IRequestRunEventMessage,\n  EventMessageFromClient,\n  ICancelCommandMessage,\n  IExitCommandMessage,\n  IRunCommandMessage,\n  ISyncCommandMessage,\n  CommandMessageFromHost,\n  IPCHost\n} from './protocol.types';\n\nexport {\n  type IExecuteOperationContext,\n  type IOperationOptions,\n  Operation,\n  type OperationRequestRunCallback\n} from './Operation';\n\nexport { OperationError } from './OperationError';\n\nexport { type IOperationExecutionOptions, OperationExecutionManager } from './OperationExecutionManager';\n\nexport { OperationGroupRecord } from './OperationGroupRecord';\n\nexport { OperationStatus } from './OperationStatus';\n\nexport { Stopwatch } from './Stopwatch';\n\nexport { type IWatchLoopOptions, type IWatchLoopState, WatchLoop } from './WatchLoop';\n"]}

package/lib-esm/protocol.types.js

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+export {};
+//# sourceMappingURL=protocol.types.js.map

package/lib-esm/protocol.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.types.js","sourceRoot":"","sources":["../src/protocol.types.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { OperationStatus } from './OperationStatus';\n\n/**\n * A message sent to the host to ask it to run this task.\n *\n * @beta\n */\nexport interface IRequestRunEventMessage {\n  event: 'requestRun';\n  /**\n   * The name of the operation requesting a rerun.\n   */\n  requestor: string;\n  /**\n   * Optional detail about why the rerun is requested, e.g. the name of a changed file.\n   */\n  detail?: string;\n}\n\n/**\n * A message sent to the host upon completion of a run of this task.\n *\n * @beta\n */\nexport interface IAfterExecuteEventMessage {\n  event: 'after-execute';\n  status: OperationStatus;\n}\n\n/**\n * A message sent to the host upon connection of the channel, to indicate\n * to the host that this task supports the protocol and to provide baseline status information.\n *\n * @beta\n */\nexport interface ISyncEventMessage {\n  event: 'sync';\n  status: OperationStatus;\n}\n\n/**\n * A message sent by the host to tell the watch loop to cancel the current run.\n *\n * @beta\n */\nexport interface ICancelCommandMessage {\n  command: 'cancel';\n}\n\n/**\n * A message sent by the host to tell the watch loop to shutdown gracefully.\n *\n * @beta\n */\nexport interface IExitCommandMessage {\n  command: 'exit';\n}\n\n/**\n * A message sent by the host to tell the watch loop to perform a single run.\n *\n * @beta\n */\nexport interface IRunCommandMessage {\n  command: 'run';\n}\n\n/**\n * A message sent by the host to ask for to resync status information.\n *\n * @beta\n */\nexport interface ISyncCommandMessage {\n  command: 'sync';\n}\n\n/**\n * The set of known messages from the host to the watch loop.\n * @beta\n */\nexport type CommandMessageFromHost =\n  | ICancelCommandMessage\n  | IExitCommandMessage\n  | IRunCommandMessage\n  | ISyncCommandMessage;\n\n/**\n * The set of known messages from the watch loop to the host.\n * @beta\n */\nexport type EventMessageFromClient = IRequestRunEventMessage | IAfterExecuteEventMessage | ISyncEventMessage;\n\n/**\n * The interface contract for IPC send/receive, to support alternate channels and unit tests.\n *\n * @beta\n */\nexport type IPCHost = Pick<typeof process, 'on' | 'send'>;\n"]}

package/package.json

@@ -1,9 +1,32 @@
 {
   "name": "@rushstack/operation-graph",
-  "version": "0.5.7",
+  "version": "0.6.1",
   "description": "Library for managing and executing operations in a directed acyclic graph.",
-  "main": "lib/index.js",
-  "typings": "dist/operation-graph.d.ts",
+  "main": "./lib-commonjs/index.js",
+  "module": "./lib-esm/index.js",
+  "types": "./dist/operation-graph.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/operation-graph.d.ts",
+      "node": "./lib-commonjs/index.js",
+      "import": "./lib-esm/index.js",
+      "require": "./lib-commonjs/index.js"
+    },
+    "./lib/*": {
+      "types": "./lib-dts/*.d.ts",
+      "node": "./lib-commonjs/*.js",
+      "import": "./lib-esm/*.js",
+      "require": "./lib-commonjs/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "lib/*": [
+        "lib-dts/*"
+      ]
+    }
+  },
   "license": "MIT",
   "repository": {
     "url": "https://github.com/microsoft/rushstack.git",
@@ -11,11 +34,11 @@
     "directory": "libraries/operation-graph"
   },
   "dependencies": {
-    "@rushstack/node-core-library": "5.19.1",
-    "@rushstack/terminal": "0.21.0"
+    "@rushstack/node-core-library": "5.20.1",
+    "@rushstack/terminal": "0.22.1"
   },
   "devDependencies": {
-    "@rushstack/heft": "1.1.7",
+    "@rushstack/heft": "1.2.0",
     "eslint": "~9.37.0",
     "decoupled-local-node-rig": "1.0.0"
   },
@@ -27,6 +50,7 @@
       "optional": true
     }
   },
+  "sideEffects": false,
   "scripts": {
     "build": "heft build --clean",
     "_phase:build": "heft run --only build -- --clean",