@rushstack/operation-graph 0.1.0

package/lib/OperationExecutionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OperationExecutionManager.js","sourceRoot":"","sources":["../src/OperationExecutionManager.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 type { ITerminal } from '@rushstack/node-core-library';\n\nimport type { IOperationState } from './IOperationRunner';\nimport type { IExecuteOperationContext, Operation } from './Operation';\nimport { OperationGroupRecord } from './OperationGroupRecord';\nimport { OperationStatus } from './OperationStatus';\nimport { calculateCriticalPathLengths } from './calculateCriticalPath';\n\n/**\n * Options for the current run.\n *\n * @beta\n */\nexport interface IOperationExecutionOptions {\n  abortSignal: AbortSignal;\n  parallelism: number;\n  terminal: ITerminal;\n\n  requestRun?: (requestor?: string) => void;\n}\n\n/**\n * A class which manages the execution of a set of tasks with interdependencies.\n * Initially, and at the end of each task execution, all unblocked tasks\n * are added to a ready queue which is then executed. This is done continually until all\n * tasks are complete, or prematurely fails if any of the tasks fail.\n *\n * @beta\n */\nexport class OperationExecutionManager {\n  /**\n   * The set of operations that will be executed\n   */\n  private readonly _operations: Operation[];\n  /**\n   * Group records are metadata-only entities used for tracking the start and end of a set of related tasks.\n   * This is the only extent to which the operation graph is aware of Heft phases.\n   */\n  private readonly _groupRecordByName: Map<string, OperationGroupRecord>;\n  /**\n   * The total number of non-silent operations in the graph.\n   * Silent operations are generally used to simplify the construction of the graph.\n   */\n  private readonly _trackedOperationCount: number;\n\n  public constructor(operations: ReadonlySet<Operation>) {\n    const groupRecordByName: Map<string, OperationGroupRecord> = new Map();\n    this._groupRecordByName = groupRecordByName;\n\n    let trackedOperationCount: number = 0;\n    for (const operation of operations) {\n      const { groupName } = operation;\n      let group: OperationGroupRecord | undefined = undefined;\n      if (groupName && !(group = groupRecordByName.get(groupName))) {\n        group = new OperationGroupRecord(groupName);\n        groupRecordByName.set(groupName, group);\n      }\n\n      group?.addOperation(operation);\n\n      if (!operation.runner?.silent) {\n        // Only count non-silent operations\n        trackedOperationCount++;\n      }\n    }\n\n    this._trackedOperationCount = trackedOperationCount;\n\n    this._operations = calculateCriticalPathLengths(operations);\n\n    for (const consumer of operations) {\n      for (const dependency of consumer.dependencies) {\n        if (!operations.has(dependency)) {\n          throw new Error(\n            `Operation ${JSON.stringify(consumer.name)} declares a dependency on operation ` +\n              `${JSON.stringify(dependency.name)} that is not in the set of operations to execute.`\n          );\n        }\n      }\n    }\n  }\n\n  /**\n   * Executes all operations which have been registered, returning a promise which is resolved when all the\n   * operations are completed successfully, or rejects when any operation fails.\n   */\n  public async executeAsync(executionOptions: IOperationExecutionOptions): Promise<OperationStatus> {\n    let hasReportedFailures: boolean = false;\n\n    const { abortSignal, parallelism, terminal, requestRun } = executionOptions;\n\n    const startedGroups: Set<OperationGroupRecord> = new Set();\n    const finishedGroups: Set<OperationGroupRecord> = new Set();\n\n    const maxParallelism: number = Math.min(this._operations.length, parallelism);\n    const groupRecords: Map<string, OperationGroupRecord> = this._groupRecordByName;\n    for (const groupRecord of groupRecords.values()) {\n      groupRecord.reset();\n    }\n\n    for (const operation of this._operations) {\n      operation.reset();\n    }\n\n    terminal.writeVerboseLine(`Executing a maximum of ${maxParallelism} simultaneous tasks...`);\n\n    const executionContext: IExecuteOperationContext = {\n      terminal,\n      abortSignal,\n\n      requestRun,\n\n      queueWork: <T>(workFn: () => Promise<T>, priority: number): Promise<T> => {\n        // TODO: Update to throttle parallelism\n        // Can just be a standard priority queue from async\n        return workFn();\n      },\n\n      beforeExecute: (operation: Operation): void => {\n        // Initialize group if uninitialized and log the group name\n        const { groupName } = operation;\n        const groupRecord: OperationGroupRecord | undefined = groupName\n          ? groupRecords.get(groupName)\n          : undefined;\n        if (groupRecord && !startedGroups.has(groupRecord)) {\n          startedGroups.add(groupRecord);\n          groupRecord.startTimer();\n          terminal.writeLine(` ---- ${groupRecord.name} started ---- `);\n        }\n      },\n\n      afterExecute: (operation: Operation, state: IOperationState): void => {\n        const { groupName } = operation;\n        const groupRecord: OperationGroupRecord | undefined = groupName\n          ? groupRecords.get(groupName)\n          : undefined;\n        if (groupRecord) {\n          groupRecord.setOperationAsComplete(operation, state);\n        }\n\n        if (state.status === OperationStatus.Failure) {\n          // This operation failed. Mark it as such and all reachable dependents as blocked.\n          // Failed operations get reported, even if silent.\n          // Generally speaking, silent operations shouldn't be able to fail, so this is a safety measure.\n          const message: string | undefined = state.error?.message;\n          if (message) {\n            terminal.writeErrorLine(message);\n          }\n          hasReportedFailures = true;\n        }\n\n        // Log out the group name and duration if it is the last operation in the group\n        if (groupRecord?.finished && !finishedGroups.has(groupRecord)) {\n          finishedGroups.add(groupRecord);\n          const finishedLoggingWord: string = groupRecord.hasFailures\n            ? 'encountered an error'\n            : groupRecord.hasCancellations\n            ? 'cancelled'\n            : 'finished';\n          terminal.writeLine(\n            ` ---- ${groupRecord.name} ${finishedLoggingWord} (${groupRecord.duration.toFixed(3)}s) ---- `\n          );\n        }\n      }\n    };\n\n    await Promise.all(this._operations.map((record: Operation) => record._executeAsync(executionContext)));\n\n    const finalStatus: OperationStatus =\n      this._trackedOperationCount === 0\n        ? OperationStatus.NoOp\n        : abortSignal.aborted\n        ? OperationStatus.Aborted\n        : hasReportedFailures\n        ? OperationStatus.Failure\n        : OperationStatus.Success;\n\n    return finalStatus;\n  }\n}\n"]}

package/lib/OperationGroupRecord.d.ts

@@ -0,0 +1,25 @@
+import type { IOperationState } from './IOperationRunner';
+import type { Operation } from './Operation';
+/**
+ * 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;
+}
+//# sourceMappingURL=OperationGroupRecord.d.ts.map

package/lib/OperationGroupRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OperationGroupRecord.d.ts","sourceRoot":"","sources":["../src/OperationGroupRecord.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C;;;;GAIG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,oBAAoB,CAA6B;IAEzD,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,iBAAiB,CAAkB;IAC3C,OAAO,CAAC,YAAY,CAAkB;IAEtC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,IAAW,gBAAgB,IAAI,OAAO,CAErC;IAED,IAAW,WAAW,IAAI,OAAO,CAEhC;gBAEkB,IAAI,EAAE,MAAM;IAIxB,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC,UAAU,IAAI,IAAI;IAKlB,sBAAsB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAiB1E,KAAK,IAAI,IAAI;CAMrB"}

package/lib/OperationGroupRecord.js

@@ -0,0 +1,65 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperationGroupRecord = void 0;
+const node_core_library_1 = require("@rushstack/node-core-library");
+const OperationStatus_1 = require("./OperationStatus");
+const Stopwatch_1 = require("./Stopwatch");
+/**
+ * Meta-entity that tracks information about a group of related operations.
+ *
+ * @beta
+ */
+class OperationGroupRecord {
+    get duration() {
+        return this._groupStopwatch ? this._groupStopwatch.duration : 0;
+    }
+    get finished() {
+        return this._remainingOperations.size === 0;
+    }
+    get hasCancellations() {
+        return this._hasCancellations;
+    }
+    get hasFailures() {
+        return this._hasFailures;
+    }
+    constructor(name) {
+        this._operations = new Set();
+        this._remainingOperations = new Set();
+        this._groupStopwatch = new Stopwatch_1.Stopwatch();
+        this._hasCancellations = false;
+        this._hasFailures = false;
+        this.name = name;
+    }
+    addOperation(operation) {
+        this._operations.add(operation);
+    }
+    startTimer() {
+        // Keep this undefined until needed, then start to avoid subsequent calls to startTimer()
+        this._groupStopwatch.start();
+    }
+    setOperationAsComplete(operation, state) {
+        if (!this._remainingOperations.has(operation)) {
+            throw new node_core_library_1.InternalError(`Operation ${operation.name} is not in the group ${this.name}`);
+        }
+        if (state.status === OperationStatus_1.OperationStatus.Aborted) {
+            this._hasCancellations = true;
+        }
+        else if (state.status === OperationStatus_1.OperationStatus.Failure) {
+            this._hasFailures = true;
+        }
+        this._remainingOperations.delete(operation);
+        if (this._remainingOperations.size === 0) {
+            this._groupStopwatch.stop();
+        }
+    }
+    reset() {
+        this._remainingOperations = new Set(this._operations);
+        this._groupStopwatch.reset();
+        this._hasCancellations = false;
+        this._hasFailures = false;
+    }
+}
+exports.OperationGroupRecord = OperationGroupRecord;
+//# sourceMappingURL=OperationGroupRecord.js.map

package/lib/OperationGroupRecord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OperationGroupRecord.js","sourceRoot":"","sources":["../src/OperationGroupRecord.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAE3D,oEAA6D;AAI7D,uDAAoD;AACpD,2CAAwC;AAExC;;;;GAIG;AACH,MAAa,oBAAoB;IAU/B,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,IAAW,gBAAgB;QACzB,OAAO,IAAI,CAAC,iBAAiB,CAAC;IAChC,CAAC;IAED,IAAW,WAAW;QACpB,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,YAAmB,IAAY;QAzBd,gBAAW,GAAmB,IAAI,GAAG,EAAE,CAAC;QACjD,yBAAoB,GAAmB,IAAI,GAAG,EAAE,CAAC;QAEjD,oBAAe,GAAc,IAAI,qBAAS,EAAE,CAAC;QAC7C,sBAAiB,GAAY,KAAK,CAAC;QACnC,iBAAY,GAAY,KAAK,CAAC;QAqBpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAEM,YAAY,CAAC,SAAoB;QACtC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAEM,UAAU;QACf,yFAAyF;QACzF,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;IAC/B,CAAC;IAEM,sBAAsB,CAAC,SAAoB,EAAE,KAAsB;QACxE,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;YAC7C,MAAM,IAAI,iCAAa,CAAC,aAAa,SAAS,CAAC,IAAI,wBAAwB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;SACzF;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,iCAAe,CAAC,OAAO,EAAE;YAC5C,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;SAC/B;aAAM,IAAI,KAAK,CAAC,MAAM,KAAK,iCAAe,CAAC,OAAO,EAAE;YACnD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;SAC1B;QAED,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,IAAI,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC,EAAE;YACxC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;SAC7B;IACH,CAAC;IAEM,KAAK;QACV,IAAI,CAAC,oBAAoB,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACtD,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;IAC5B,CAAC;CACF;AA9DD,oDA8DC","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 { InternalError } from '@rushstack/node-core-library';\n\nimport type { IOperationState } from './IOperationRunner';\nimport type { Operation } from './Operation';\nimport { OperationStatus } from './OperationStatus';\nimport { Stopwatch } from './Stopwatch';\n\n/**\n * Meta-entity that tracks information about a group of related operations.\n *\n * @beta\n */\nexport class OperationGroupRecord {\n  private readonly _operations: Set<Operation> = new Set();\n  private _remainingOperations: Set<Operation> = new Set();\n\n  private _groupStopwatch: Stopwatch = new Stopwatch();\n  private _hasCancellations: boolean = false;\n  private _hasFailures: boolean = false;\n\n  public readonly name: string;\n\n  public get duration(): number {\n    return this._groupStopwatch ? this._groupStopwatch.duration : 0;\n  }\n\n  public get finished(): boolean {\n    return this._remainingOperations.size === 0;\n  }\n\n  public get hasCancellations(): boolean {\n    return this._hasCancellations;\n  }\n\n  public get hasFailures(): boolean {\n    return this._hasFailures;\n  }\n\n  public constructor(name: string) {\n    this.name = name;\n  }\n\n  public addOperation(operation: Operation): void {\n    this._operations.add(operation);\n  }\n\n  public startTimer(): void {\n    // Keep this undefined until needed, then start to avoid subsequent calls to startTimer()\n    this._groupStopwatch.start();\n  }\n\n  public setOperationAsComplete(operation: Operation, state: IOperationState): void {\n    if (!this._remainingOperations.has(operation)) {\n      throw new InternalError(`Operation ${operation.name} is not in the group ${this.name}`);\n    }\n\n    if (state.status === OperationStatus.Aborted) {\n      this._hasCancellations = true;\n    } else if (state.status === OperationStatus.Failure) {\n      this._hasFailures = true;\n    }\n\n    this._remainingOperations.delete(operation);\n    if (this._remainingOperations.size === 0) {\n      this._groupStopwatch.stop();\n    }\n  }\n\n  public reset(): void {\n    this._remainingOperations = new Set(this._operations);\n    this._groupStopwatch.reset();\n    this._hasCancellations = false;\n    this._hasFailures = false;\n  }\n}\n"]}

package/lib/OperationStatus.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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"
+}
+//# sourceMappingURL=OperationStatus.d.ts.map

package/lib/OperationStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OperationStatus.d.ts","sourceRoot":"","sources":["../src/OperationStatus.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,oBAAY,eAAe;IACzB;;OAEG;IACH,KAAK,UAAU;IACf;;OAEG;IACH,OAAO,YAAY;IACnB;;OAEG;IACH,SAAS,cAAc;IACvB;;OAEG;IACH,OAAO,YAAY;IACnB;;OAEG;IACH,OAAO,YAAY;IACnB;;OAEG;IACH,OAAO,YAAY;IACnB;;OAEG;IACH,OAAO,YAAY;IACnB;;OAEG;IACH,IAAI,UAAU;CACf"}

package/lib/OperationStatus.js

@@ -0,0 +1,45 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperationStatus = void 0;
+/**
+ * Enumeration defining potential states of an operation
+ * @beta
+ */
+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 = exports.OperationStatus || (exports.OperationStatus = {}));
+//# sourceMappingURL=OperationStatus.js.map

package/lib/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,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,GAAf,uBAAe,KAAf,uBAAe,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/Stopwatch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=Stopwatch.d.ts.map

package/lib/Stopwatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stopwatch.d.ts","sourceRoot":"","sources":["../src/Stopwatch.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,QAAQ,CAAU;;IAQ1B;;OAEG;WACW,KAAK,IAAI,SAAS;IAIhC,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;;OAGG;IACI,KAAK,IAAI,SAAS;IAUzB;;OAEG;IACI,IAAI,IAAI,SAAS;IAMxB;;OAEG;IACI,KAAK,IAAI,SAAS;IAMzB;;OAEG;IACI,QAAQ,IAAI,MAAM;IAgBzB;;OAEG;IACH,IAAW,QAAQ,IAAI,MAAM,CAO5B;IAED;;OAEG;IACH,IAAW,SAAS,IAAI,MAAM,GAAG,SAAS,CAEzC;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,MAAM,GAAG,SAAS,CAEvC;CACF"}

package/lib/Stopwatch.js

@@ -0,0 +1,97 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stopwatch = void 0;
+/**
+ * Represents a typical timer/stopwatch which keeps track
+ * of elapsed time in between two events.
+ *
+ * @public
+ */
+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;
+    }
+}
+exports.Stopwatch = Stopwatch;
+//# sourceMappingURL=Stopwatch.js.map

package/lib/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,MAAa,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;YACjC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;SAC/D;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;YACnD,OAAO,wBAAwB,CAAC;SACjC;QACD,MAAM,YAAY,GAAW,IAAI,CAAC,QAAQ,CAAC;QAE3C,IAAI,YAAY,GAAG,EAAE,EAAE;YACrB,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;SAChG;aAAM;YACL,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;SAC7C;IACH,CAAC;IAED;;OAEG;IACH,IAAW,QAAQ;QACjB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE;YACjC,OAAO,CAAC,CAAC;SACV;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;AAlGD,8BAkGC","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/WatchLoop.d.ts

@@ -0,0 +1,80 @@
+/// <reference types="node" />
+import { OperationStatus } from './OperationStatus';
+import type { IPCHost } from './protocol.types';
+/**
+ * Callbacks for the watch loop.
+ *
+ * @beta
+ */
+export 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 interface IWatchLoopState {
+    get abortSignal(): AbortSignal;
+    requestRun: (requestor?: string) => void;
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=WatchLoop.d.ts.map

package/lib/WatchLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WatchLoop.d.ts","sourceRoot":"","sources":["../src/WatchLoop.ts"],"names":[],"mappings":";AAOA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAEV,OAAO,EAIR,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACnE;;OAEG;IACH,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B;;OAEG;IACH,YAAY,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,WAAW,IAAI,WAAW,CAAC;IAC/B,UAAU,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED;;;;GAIG;AACH,qBAAa,SAAU,YAAW,eAAe;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuB;IAErD,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,UAAU,CAAU;IAC5B,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,kBAAkB,CAA8B;IACxD,OAAO,CAAC,kBAAkB,CAAgC;gBAEvC,OAAO,EAAE,iBAAiB;IAc7C;;OAEG;IACU,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAsCpF;;OAEG;IACU,oBAAoB,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBjG;;;OAGG;IACU,WAAW,CAAC,IAAI,GAAE,OAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgFhE;;OAEG;IACI,UAAU,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,IAAI,CAU7C;IAEF;;OAEG;IACH,IAAW,WAAW,IAAI,WAAW,CAEpC;IAED;;OAEG;IACH,OAAO,CAAC,aAAa,CAEnB;IAEF;;OAEG;IACH,OAAO,CAAC,MAAM;CAYf"}

package/lib/WatchLoop.js

@@ -0,0 +1,191 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WatchLoop = void 0;
+const node_events_1 = require("node:events");
+const node_core_library_1 = require("@rushstack/node-core-library");
+const OperationStatus_1 = require("./OperationStatus");
+/**
+ * This class implements a watch loop.
+ *
+ * @beta
+ */
+class WatchLoop {
+    constructor(options) {
+        /**
+         * Requests that a new run occur.
+         */
+        this.requestRun = (requestor) => {
+            if (!this._runRequested) {
+                this._options.onRequestRun(requestor);
+                this._runRequested = true;
+                if (this._isRunning) {
+                    this._options.onAbort();
+                    this._abortCurrent();
+                }
+            }
+            this._resolveRequestRun(requestor);
+        };
+        /**
+         * 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;
+        });
+        this._outerSignals = new WeakSet();
+    }
+    /**
+     * 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_1.OperationStatus.Aborted;
+        }
+        if (!this._outerSignals.has(abortSignal)) {
+            (0, node_events_1.once)(abortSignal, 'abort').finally(this._abortCurrent);
+        }
+        let result = OperationStatus_1.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_1.OperationStatus.Aborted;
+            }
+            this._reset();
+            this._options.onBeforeExecute();
+            try {
+                this._isRunning = true;
+                result = await this._options.executeAsync(this);
+            }
+            catch (err) {
+                if (!(err instanceof node_core_library_1.AlreadyReportedError)) {
+                    throw err;
+                }
+                else {
+                    result = OperationStatus_1.OperationStatus.Failure;
+                }
+            }
+            finally {
+                this._isRunning = false;
+            }
+        } 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_1.OperationStatus.Aborted : result;
+    }
+    /**
+     * 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 = (0, node_events_1.once)(abortSignal, 'abort');
+        // eslint-disable-next-line no-constant-condition
+        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_1.OperationStatus.Ready;
+            function requestRunFromHost(requestor) {
+                if (runRequestedFromHost) {
+                    return;
+                }
+                runRequestedFromHost = true;
+                const requestRunMessage = {
+                    event: 'requestRun',
+                    requestor
+                };
+                host.send(requestRunMessage);
+            }
+            function sendSync() {
+                const syncMessage = {
+                    event: 'sync',
+                    status
+                };
+                host.send(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_1.OperationStatus.Executing;
+                        try {
+                            status = await this.runUntilStableAsync(abortController.signal);
+                            this._requestRunPromise.finally(requestRunFromHost);
+                        }
+                        catch (err) {
+                            status = OperationStatus_1.OperationStatus.Failure;
+                            return reject(err);
+                        }
+                        finally {
+                            const afterExecuteMessage = {
+                                event: 'after-execute',
+                                status
+                            };
+                            host.send(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;
+            });
+        }
+    }
+}
+exports.WatchLoop = WatchLoop;
+//# sourceMappingURL=WatchLoop.js.map