@oclif/multi-stage-output 0.7.9 → 0.7.11

package/lib/components/stages.d.ts

@@ -28,6 +28,10 @@ type Info<T extends Record<string, unknown>> = {
      * Set to `true` to prevent this key-value pair or message from being collapsed when the window is too short. Defaults to false.
      */
     neverCollapse?: boolean;
+    /**
+     * Set to `true` to only show this key-value pair or message at the very end of the CI output. Defaults to false.
+     */
+    onlyShowAtEndInCI?: boolean;
 };
 export type KeyValuePair<T extends Record<string, unknown>> = Info<T> & {
     /**

package/lib/multi-stage-output.d.ts

@@ -53,25 +53,44 @@ export type MultiStageOutputOptions<T extends Record<string, unknown>> = {
     readonly jsonEnabled: boolean;
 };
 declare class CIMultiStageOutput<T extends Record<string, unknown>> {
+    private readonly completedStages;
     private data?;
     private readonly design;
     private readonly hasElapsedTime?;
     private readonly hasStageTime?;
-    private lastUpdateTime;
-    private readonly messageTimeout;
+    /**
+     * Amount of time (in milliseconds) between heartbeat updates
+     */
+    private readonly heartbeat;
+    /**
+     * Time of the last heartbeat
+     */
+    private lastHeartbeatTime;
+    /**
+     * Map of the last time a specific piece of info was updated. This is used for throttling messages
+     */
+    private readonly lastUpdateByInfo;
     private readonly postStagesBlock?;
     private readonly preStagesBlock?;
-    private readonly seenInfo;
-    private readonly seenStages;
+    private readonly seenStrings;
     private readonly stages;
     private readonly stageSpecificBlock?;
     private readonly startTime;
     private readonly startTimes;
+    /**
+     * Amount of time (in milliseconds) between throttled updates
+     */
+    private readonly throttle;
     private readonly timerUnit;
+    /**
+     * Map of intervals used to trigger heartbeat updates
+     */
+    private readonly updateIntervals;
     constructor({ data, design, postStagesBlock, preStagesBlock, showElapsedTime, showStageTime, stageSpecificBlock, stages, timerUnit, title, }: MultiStageOutputOptions<T>);
     stop(stageTracker: StageTracker): void;
     update(stageTracker: StageTracker, data?: Partial<T>): void;
-    private printInfo;
+    private maybePrintInfo;
+    private maybeStdout;
 }
 declare class MultiStageOutputBase<T extends Record<string, unknown>> implements Disposable {
     protected readonly ciInstance: CIMultiStageOutput<T> | undefined;

package/lib/multi-stage-output.js

@@ -33,21 +33,39 @@ function shouldUseCIMode() {
 }
 const isInCi = shouldUseCIMode();
 class CIMultiStageOutput {
+    completedStages = new Set();
     data;
     design;
     hasElapsedTime;
     hasStageTime;
-    lastUpdateTime;
-    messageTimeout = Number.parseInt(env.SF_CI_MESSAGE_TIMEOUT ?? '5000', 10) ?? 5000;
+    /**
+     * Amount of time (in milliseconds) between heartbeat updates
+     */
+    heartbeat = Number.parseInt(env.OCLIF_CI_HEARTBEAT_FREQUENCY_MS ?? env.SF_CI_HEARTBEAT_FREQUENCY_MS ?? '300000', 10) ?? 300_000;
+    /**
+     * Time of the last heartbeat
+     */
+    lastHeartbeatTime;
+    /**
+     * Map of the last time a specific piece of info was updated. This is used for throttling messages
+     */
+    lastUpdateByInfo = new Map();
     postStagesBlock;
     preStagesBlock;
-    seenInfo = new Set();
-    seenStages = new Set();
+    seenStrings = new Set();
     stages;
     stageSpecificBlock;
     startTime;
     startTimes = new Map();
+    /**
+     * Amount of time (in milliseconds) between throttled updates
+     */
+    throttle = Number.parseInt(env.OCLIF_CI_UPDATE_FREQUENCY_MS ?? env.SF_CI_UPDATE_FREQUENCY_MS ?? '5000', 10) ?? 5000;
     timerUnit;
+    /**
+     * Map of intervals used to trigger heartbeat updates
+     */
+    updateIntervals = new Map();
     constructor({ data, design, postStagesBlock, preStagesBlock, showElapsedTime, showStageTime, stageSpecificBlock, stages, timerUnit, title, }) {
         this.design = constructDesignParams(design);
         this.stages = stages;
@@ -58,7 +76,7 @@ class CIMultiStageOutput {
         this.stageSpecificBlock = stageSpecificBlock;
         this.timerUnit = timerUnit ?? 'ms';
         this.data = data;
-        this.lastUpdateTime = Date.now();
+        this.lastHeartbeatTime = Date.now();
         if (title)
             ux.stdout(`───── ${title} ─────`);
         ux.stdout('Stages:');
@@ -73,20 +91,24 @@ class CIMultiStageOutput {
     stop(stageTracker) {
         this.update(stageTracker);
         ux.stdout();
-        this.printInfo(this.preStagesBlock, 0, true);
-        this.printInfo(this.postStagesBlock, 0, true);
+        this.maybePrintInfo(this.preStagesBlock, 0, true);
+        this.maybePrintInfo(this.postStagesBlock, 0, true);
         if (this.startTime) {
             const elapsedTime = Date.now() - this.startTime;
             ux.stdout();
             const displayTime = readableTime(elapsedTime, this.timerUnit);
             ux.stdout(`Elapsed time: ${displayTime}`);
         }
+        for (const interval of this.updateIntervals.values()) {
+            clearInterval(interval);
+        }
     }
+    // eslint-disable-next-line complexity
     update(stageTracker, data) {
         this.data = { ...this.data, ...data };
         for (const [stage, status] of stageTracker.entries()) {
             // no need to re-render completed, failed, or skipped stages
-            if (this.seenStages.has(stage))
+            if (this.completedStages.has(stage))
                 continue;
             switch (status) {
                 case 'pending': {
@@ -96,13 +118,33 @@ class CIMultiStageOutput {
                 case 'current': {
                     if (!this.startTimes.has(stage))
                         this.startTimes.set(stage, Date.now());
-                    if (Date.now() - this.lastUpdateTime < this.messageTimeout)
-                        break;
-                    this.lastUpdateTime = Date.now();
-                    ux.stdout(`${this.design.icons.current.figure} ${stage}…`);
-                    this.printInfo(this.preStagesBlock, 3);
-                    this.printInfo(this.stageSpecificBlock?.filter((info) => info.stage === stage), 3);
-                    this.printInfo(this.postStagesBlock, 3);
+                    const stageInfos = this.stageSpecificBlock?.filter((info) => info.stage === stage);
+                    const iconAndStage = `${this.design.icons.current.figure} ${stage}…`;
+                    if (Date.now() - this.lastHeartbeatTime < this.heartbeat) {
+                        // only print if it hasn't been seen before
+                        this.maybeStdout(iconAndStage);
+                        this.maybePrintInfo(this.preStagesBlock, 3);
+                        this.maybePrintInfo(stageInfos, 3);
+                        this.maybePrintInfo(this.postStagesBlock, 3);
+                    }
+                    else {
+                        // force a reprint if it's been too long
+                        this.lastHeartbeatTime = Date.now();
+                        if (stageInfos?.length) {
+                            // only reprint the stage infos if it has them
+                            this.maybePrintInfo(stageInfos, 3, true);
+                        }
+                        else {
+                            // only reprint the stage
+                            this.maybeStdout(iconAndStage, 0, true);
+                        }
+                    }
+                    if (!this.updateIntervals.has(stage)) {
+                        // set interval to update the stage message - this is used for long running stages in CI environments that timeout after a certain period without output
+                        this.updateIntervals.set(stage, setInterval(() => {
+                            this.update(stageTracker);
+                        }, this.heartbeat));
+                    }
                     break;
                 }
                 case 'failed':
@@ -112,24 +154,35 @@ class CIMultiStageOutput {
                 case 'async':
                 case 'warning':
                 case 'completed': {
-                    this.seenStages.add(stage);
+                    // clear the heartbeat interval since it's no longer needed
+                    const interval = this.updateIntervals.get(stage);
+                    if (interval) {
+                        clearInterval(interval);
+                        this.updateIntervals.delete(stage);
+                    }
+                    // clear all throttled messages since the stage is done
+                    for (const key of this.lastUpdateByInfo.keys()) {
+                        this.lastUpdateByInfo.delete(key);
+                    }
+                    const stageInfos = this.stageSpecificBlock?.filter((info) => info.stage === stage);
+                    this.completedStages.add(stage);
                     if (this.hasStageTime && status !== 'skipped') {
                         const startTime = this.startTimes.get(stage);
                         const elapsedTime = startTime ? Date.now() - startTime : 0;
                         const displayTime = readableTime(elapsedTime, this.timerUnit);
-                        ux.stdout(`${this.design.icons[status].figure} ${stage} (${displayTime})`);
-                        this.printInfo(this.preStagesBlock, 3);
-                        this.printInfo(this.stageSpecificBlock?.filter((info) => info.stage === stage), 3);
-                        this.printInfo(this.postStagesBlock, 3);
+                        this.maybeStdout(`${this.design.icons[status].figure} ${stage} (${displayTime})`);
+                        this.maybePrintInfo(this.preStagesBlock, 3);
+                        this.maybePrintInfo(stageInfos, 3);
+                        this.maybePrintInfo(this.postStagesBlock, 3);
                     }
                     else if (status === 'skipped') {
-                        ux.stdout(`${this.design.icons[status].figure} ${stage} - Skipped`);
+                        this.maybeStdout(`${this.design.icons[status].figure} ${stage} - Skipped`);
                     }
                     else {
-                        ux.stdout(`${this.design.icons[status].figure} ${stage}`);
-                        this.printInfo(this.preStagesBlock, 3);
-                        this.printInfo(this.stageSpecificBlock?.filter((info) => info.stage === stage), 3);
-                        this.printInfo(this.postStagesBlock, 3);
+                        this.maybeStdout(`${this.design.icons[status].figure} ${stage}`);
+                        this.maybePrintInfo(this.preStagesBlock, 3);
+                        this.maybePrintInfo(stageInfos, 3);
+                        this.maybePrintInfo(this.postStagesBlock, 3);
                     }
                     break;
                 }
@@ -138,21 +191,34 @@ class CIMultiStageOutput {
             }
         }
     }
-    printInfo(infoBlock, indent = 0, force = false) {
-        const spaces = ' '.repeat(indent);
+    maybePrintInfo(infoBlock, indent = 0, force = false) {
         if (infoBlock?.length) {
             for (const info of infoBlock) {
+                if (info.onlyShowAtEndInCI && !force)
+                    continue;
                 const formattedData = info.get ? info.get(this.data) : undefined;
                 if (!formattedData)
                     continue;
+                const key = info.type === 'message' ? formattedData : info.label;
                 const str = info.type === 'message' ? formattedData : `${info.label}: ${formattedData}`;
-                if (!force && this.seenInfo.has(str))
+                const lastUpdateTime = this.lastUpdateByInfo.get(key);
+                // Skip if the info has been printed before the throttle time
+                if (lastUpdateTime && Date.now() - lastUpdateTime < this.throttle && !force)
                     continue;
-                ux.stdout(`${spaces}${str}`);
-                this.seenInfo.add(str);
+                const didPrint = this.maybeStdout(str, indent, force);
+                if (didPrint)
+                    this.lastUpdateByInfo.set(key, Date.now());
             }
         }
     }
+    maybeStdout(str, indent = 0, force = false) {
+        const spaces = ' '.repeat(indent);
+        if (!force && this.seenStrings.has(str))
+            return false;
+        ux.stdout(`${spaces}${str}`);
+        this.seenStrings.add(str);
+        return true;
+    }
 }
 class MultiStageOutputBase {
     ciInstance;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/multi-stage-output",
   "description": "Terminal output for oclif commands with multiple stages",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/multi-stage-output/issues",
   "dependencies": {