@rushstack/operation-graph 0.1.0

package/lib/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 { 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  onRequestRun: (requestor?: string) => void;\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: (requestor?: string) => void;\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  private readonly _outerSignals: WeakSet<AbortSignal>;\n\n  private _abortController: AbortController;\n  private _isRunning: boolean;\n  private _runRequested: boolean;\n  private _requestRunPromise: Promise<string | undefined>;\n  private _resolveRequestRun!: (requestor?: 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 | undefined>((resolve) => {\n      this._resolveRequestRun = resolve;\n    });\n\n    this._outerSignals = new WeakSet();\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    if (!this._outerSignals.has(abortSignal)) {\n      once(abortSignal, 'abort').finally(this._abortCurrent);\n    }\n\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      this._reset();\n\n      this._options.onBeforeExecute();\n      try {\n        this._isRunning = true;\n        result = await this._options.executeAsync(this);\n      } catch (err) {\n        if (!(err instanceof AlreadyReportedError)) {\n          throw err;\n        } else {\n          result = OperationStatus.Failure;\n        }\n      } finally {\n        this._isRunning = false;\n      }\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  }\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    // eslint-disable-next-line no-constant-condition\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 requestRunFromHost(requestor?: string): void {\n        if (runRequestedFromHost) {\n          return;\n        }\n\n        runRequestedFromHost = true;\n\n        const requestRunMessage: IRequestRunEventMessage = {\n          event: 'requestRun',\n          requestor\n        };\n\n        host.send!(requestRunMessage);\n      }\n\n      function sendSync(): void {\n        const syncMessage: ISyncEventMessage = {\n          event: 'sync',\n          status\n        };\n        host.send!(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              this._requestRunPromise.finally(requestRunFromHost);\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              host.send!(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: (requestor?: string) => void = (requestor?: string) => {\n    if (!this._runRequested) {\n      this._options.onRequestRun(requestor);\n      this._runRequested = true;\n      if (this._isRunning) {\n        this._options.onAbort();\n        this._abortCurrent();\n      }\n    }\n    this._resolveRequestRun(requestor);\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 | undefined>((resolve) => {\n        this._resolveRequestRun = resolve;\n      });\n    }\n  }\n}\n"]}

package/lib/calculateCriticalPath.d.ts

@@ -0,0 +1,22 @@
+export interface ISortableOperation<T extends ISortableOperation<T>> {
+    name: string | undefined;
+    criticalPathLength?: number | undefined;
+    weight: number;
+    consumers: Set<T>;
+}
+/**
+ * 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 declare function calculateCriticalPathLengths<T extends ISortableOperation<T>>(operations: Iterable<T>): T[];
+/**
+ * Calculates the shortest path from `startOperation` to `endOperation`.
+ * Used when printing out circular dependencies.
+ */
+export declare function calculateShortestPath<T extends ISortableOperation<T>>(startOperation: T, endOperation: T): T[];
+/**
+ * Perform a depth-first search to find critical path length to the provided operation.
+ * Cycle detection comes at minimal additional cost.
+ */
+export declare function calculateCriticalPathLength<T extends ISortableOperation<T>>(operation: T, dependencyChain: Set<T>): number;
+//# sourceMappingURL=calculateCriticalPath.d.ts.map

package/lib/calculateCriticalPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculateCriticalPath.d.ts","sourceRoot":"","sources":["../src/calculateCriticalPath.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC;IACjE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAW1G;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACnE,cAAc,EAAE,CAAC,EACjB,YAAY,EAAE,CAAC,GACd,CAAC,EAAE,CAiCL;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACzE,SAAS,EAAE,CAAC,EACZ,eAAe,EAAE,GAAG,CAAC,CAAC,CAAC,GACtB,MAAM,CAuCR"}

package/lib/calculateCriticalPath.js

@@ -0,0 +1,89 @@
+"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.calculateCriticalPathLength = exports.calculateShortestPath = exports.calculateCriticalPathLengths = void 0;
+/**
+ * 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`.
+ */
+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;
+}
+exports.calculateCriticalPathLengths = calculateCriticalPathLengths;
+/**
+ * Calculates the shortest path from `startOperation` to `endOperation`.
+ * Used when printing out circular dependencies.
+ */
+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;
+}
+exports.calculateShortestPath = calculateShortestPath;
+/**
+ * Perform a depth-first search to find critical path length to the provided operation.
+ * Cycle detection comes at minimal additional cost.
+ */
+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;
+}
+exports.calculateCriticalPathLength = calculateCriticalPathLength;
+//# sourceMappingURL=calculateCriticalPath.js.map

package/lib/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/index.d.ts

@@ -0,0 +1,10 @@
+export type { IOperationRunner, IOperationRunnerContext, IOperationState, IOperationStates } from './IOperationRunner';
+export type { IAfterExecuteEventMessage, ISyncEventMessage, IRequestRunEventMessage, EventMessageFromClient, ICancelCommandMessage, IExitCommandMessage, IRunCommandMessage, ISyncCommandMessage, CommandMessageFromHost, IPCHost } from './protocol.types';
+export { type IExecuteOperationContext, type IOperationOptions, Operation } from './Operation';
+export { OperationError } from './OperationError';
+export { type IOperationExecutionOptions, OperationExecutionManager } from './OperationExecutionManager';
+export { OperationGroupRecord } from './OperationGroupRecord';
+export { OperationStatus } from './OperationStatus';
+export { Stopwatch } from './Stopwatch';
+export { type IWatchLoopOptions, type IWatchLoopState, WatchLoop } from './WatchLoop';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,yBAAyB,EACzB,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,OAAO,EACR,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE/F,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,KAAK,0BAA0B,EAAE,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,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/lib/index.js

@@ -0,0 +1,20 @@
+"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 = exports.Stopwatch = exports.OperationStatus = exports.OperationGroupRecord = exports.OperationExecutionManager = exports.OperationError = exports.Operation = void 0;
+var Operation_1 = require("./Operation");
+Object.defineProperty(exports, "Operation", { enumerable: true, get: function () { return Operation_1.Operation; } });
+var OperationError_1 = require("./OperationError");
+Object.defineProperty(exports, "OperationError", { enumerable: true, get: function () { return OperationError_1.OperationError; } });
+var OperationExecutionManager_1 = require("./OperationExecutionManager");
+Object.defineProperty(exports, "OperationExecutionManager", { enumerable: true, get: function () { return OperationExecutionManager_1.OperationExecutionManager; } });
+var OperationGroupRecord_1 = require("./OperationGroupRecord");
+Object.defineProperty(exports, "OperationGroupRecord", { enumerable: true, get: function () { return OperationGroupRecord_1.OperationGroupRecord; } });
+var OperationStatus_1 = require("./OperationStatus");
+Object.defineProperty(exports, "OperationStatus", { enumerable: true, get: function () { return OperationStatus_1.OperationStatus; } });
+var Stopwatch_1 = require("./Stopwatch");
+Object.defineProperty(exports, "Stopwatch", { enumerable: true, get: function () { return Stopwatch_1.Stopwatch; } });
+var WatchLoop_1 = require("./WatchLoop");
+Object.defineProperty(exports, "WatchLoop", { enumerable: true, get: function () { return WatchLoop_1.WatchLoop; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAsB3D,yCAA+F;AAA/B,sGAAA,SAAS,OAAA;AAEzE,mDAAkD;AAAzC,gHAAA,cAAc,OAAA;AAEvB,yEAAyG;AAA/D,sIAAA,yBAAyB,OAAA;AAEnE,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAE7B,qDAAoD;AAA3C,kHAAA,eAAe,OAAA;AAExB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAElB,yCAAsF;AAA/B,sGAAA,SAAS,OAAA","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 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 { type IExecuteOperationContext, type IOperationOptions, Operation } 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/protocol.types.d.ts

@@ -0,0 +1,80 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import type { OperationStatus } from './OperationStatus';
+/**
+ * A message sent to the host to ask it to run this task.
+ *
+ * @beta
+ */
+export interface IRequestRunEventMessage {
+    event: 'requestRun';
+    requestor?: string;
+}
+/**
+ * A message sent to the host upon completion of a run of this task.
+ *
+ * @beta
+ */
+export interface IAfterExecuteEventMessage {
+    event: 'after-execute';
+    status: OperationStatus;
+}
+/**
+ * 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 interface ISyncEventMessage {
+    event: 'sync';
+    status: OperationStatus;
+}
+/**
+ * A message sent by the host to tell the watch loop to cancel the current run.
+ *
+ * @beta
+ */
+export interface ICancelCommandMessage {
+    command: 'cancel';
+}
+/**
+ * A message sent by the host to tell the watch loop to shutdown gracefully.
+ *
+ * @beta
+ */
+export interface IExitCommandMessage {
+    command: 'exit';
+}
+/**
+ * A message sent by the host to tell the watch loop to perform a single run.
+ *
+ * @beta
+ */
+export interface IRunCommandMessage {
+    command: 'run';
+}
+/**
+ * A message sent by the host to ask for to resync status information.
+ *
+ * @beta
+ */
+export interface ISyncCommandMessage {
+    command: 'sync';
+}
+/**
+ * The set of known messages from the host to the watch loop.
+ * @beta
+ */
+export type CommandMessageFromHost = ICancelCommandMessage | IExitCommandMessage | IRunCommandMessage | ISyncCommandMessage;
+/**
+ * The set of known messages from the watch loop to the host.
+ * @beta
+ */
+export type EventMessageFromClient = IRequestRunEventMessage | IAfterExecuteEventMessage | ISyncEventMessage;
+/**
+ * The interface contract for IPC send/receive, to support alternate channels and unit tests.
+ *
+ * @beta
+ */
+export type IPCHost = Pick<typeof process, 'on' | 'send'>;
+//# sourceMappingURL=protocol.types.d.ts.map

package/lib/protocol.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.types.d.ts","sourceRoot":"","sources":["../src/protocol.types.ts"],"names":[],"mappings":";;AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,KAAK,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAC9B,qBAAqB,GACrB,mBAAmB,GACnB,kBAAkB,GAClB,mBAAmB,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,GAAG,yBAAyB,GAAG,iBAAiB,CAAC;AAE7G;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,OAAO,EAAE,IAAI,GAAG,MAAM,CAAC,CAAC"}

package/lib/protocol.types.js

@@ -0,0 +1,5 @@
+"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 });
+//# sourceMappingURL=protocol.types.js.map

package/lib/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  requestor?: 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

@@ -0,0 +1,36 @@
+{
+  "name": "@rushstack/operation-graph",
+  "version": "0.1.0",
+  "description": "Library for managing and executing operations in a directed acyclic graph.",
+  "main": "lib/index.js",
+  "typings": "dist/operation-graph.d.ts",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/microsoft/rushstack.git",
+    "type": "git",
+    "directory": "libraries/operation-graph"
+  },
+  "dependencies": {
+    "@rushstack/node-core-library": "3.60.0"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "0.59.0",
+    "@rushstack/heft-node-rig": "2.2.23",
+    "@types/heft-jest": "1.0.1",
+    "@types/node": "18.17.15",
+    "@rushstack/eslint-config": "3.3.4"
+  },
+  "peerDependencies": {
+    "@types/node": "*"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "heft run --only test -- --clean"
+  }
+}