@oclif/multi-stage-output 0.3.3 → 0.4.0

package/README.md

@@ -8,6 +8,14 @@
 
 This is a framework for showing multi-stage output in the terminal. It's integrated with oclif's builtin [Performance](https://oclif.io/docs/performance/) capabilities so that perf metrics are automatically captured for each stage.
 
+![Demo](./assets/demo.gif?raw=true 'Demo')
+
+# Features
+
+- Integrated Performance Tracking: this is integrated with oclif's builtin [Performance](https://oclif.io/docs/performance/) capabilities so that perf metrics are automatically captured for each stage.
+- Responsive Design: elements will be added or removed based on the height of the terminal window. It even resizes itself if you resize the screen while the command is running.
+- CI Friendly Output: a simpler output will be shown inside non-tty environments like CI systems to avoid any excessive output that might be hard to read in CI logs.
+
 # Examples
 
 You can see examples of how to use it in the [examples](./examples/) directory.
@@ -18,6 +26,153 @@ You can run any of these with the following:
 node --loader=ts-node/esm examples/basic.ts
 ```
 
+# Usage
+
+## Basic Usage
+
+```typescript
+const ms = new MultiStageOutput({
+  jsonEnabled: false,
+  stages: ['stage 1', 'stage 2', 'stage 3'],
+  title: 'Basic Example',
+})
+// goto `stage 1`
+ms.goto('stage 1')
+// do some stuff
+
+// goto `stage 2`
+ms.goto('stage 2')
+
+// As a convenience, use .next() to goto the next stage
+ms.next()
+
+// stop the multi-stage output from running anymore. Pass in an Error if applicable.
+ms.stop()
+```
+
+## Adding information blocks before or after the stages output.
+
+You can add blocks on information before or after the list of stages. There are 3 kinds of information that can be displayed:
+
+- `message`: a simple string message
+- `static-key-value`: a simple key:value pair, e.g. `name: Foo`. If the value is undefined, the key will not be shown.
+- `dynamic-key-value`: a key:value pair where the value is expected to come in at an unknown time. This will display a spinner until the value is provided. If `.stop` is called with an error before the value is provided, then a `✘` will be displayed.
+
+```typescript
+const ms = new MultiStageOutput<{message: string; staticValue: string; dynamicValue: string}>({
+  jsonEnabled: false,
+  stages: ['stage 1', 'stage 2', 'stage 3'],
+  // preStagesBlock will be displayed BEFORE the list of stages
+  postStagesBlock: [
+    {
+      get: (data) => data?.message,
+      type: 'message',
+    },
+  ],
+  // postStagesBlock will be displayed AFTER the list of stages
+  postStagesBlock: [
+    {
+      get: (data) => data?.staticValue,
+      label: 'Static',
+      type: 'static-key-value',
+    },
+    {
+      get: (data) => data?.dynamicValue,
+      label: 'Dynamic',
+      type: 'dynamic-key-value',
+    },
+  ],
+})
+// Goto `stage 1` and provide partial data to use for the information blocks
+ms.goto('stage 1', {message: 'This is a message', staticValue: 'This is a static key:value pair'})
+
+// Provide more data to use
+ms.updateData({dynamicValue: 'This is a dynamic key:value pair'})
+
+// Goto `stage 2` and provide more partial data
+ms.goto('stage 2')
+
+// Goto stage 3
+ms.goto('stage 3')
+
+ms.stop()
+```
+
+## Adding information blocks on a specific stage
+
+You can also add information blocks onto specific stages, which will nest the information underneath the stage.
+
+```typescript
+const ms = new MultiStageOutput<{message: string; staticValue: string; dynamicValue: string}>({
+  jsonEnabled: false,
+  stageSpecificBlock: [
+    // This will be nested underneath `stage 1`
+    {
+      get: (data) => data?.message,
+      stage: 'one',
+      type: 'message',
+    },
+    // This will be nested underneath `stage 2`
+    {
+      get: (data) => data?.staticValue,
+      label: 'Static',
+      stage: 'two',
+      type: 'static-key-value',
+    },
+    // This will be nested underneath `stage 1`
+    {
+      get: (data) => data?.dynamicValue,
+      label: 'Dynamic',
+      stage: 'one',
+      type: 'dynamic-key-value',
+    },
+  ],
+  stages: ['stage 1', 'stage 2', 'stage 3'],
+  title: 'Stage-Specific Information Block Example',
+})
+
+ms.goto('stage 1', {message: 'This is a message', staticValue: 'This is a static key:value pair'})
+
+ms.goto('stage 2', {dynamicValue: 'This is a dynamic key:value pair'})
+
+ms.goto('stage 3')
+
+ms.stop()
+```
+
+## Customizing the Design
+
+You can customize the design of the multi-stage output using the `design` property:
+
+```typescript
+const ms = new MultiStageOutput({
+  jsonEnabled: false,
+  stages: ['stage 1', 'stage 2', 'stage 3'],
+  title: 'Basic Example',
+  design: {
+    title: {
+      textColor: 'red',
+    }
+    icons: {
+      completed: {
+        figure: 'C',
+        paddingLeft: 1,
+        color: '#00FF00'
+      }
+    }
+  }
+})
+```
+
+See [`Design`](./src/design.ts) for all the options available to you.
+
+## Other Options
+
+- `showElapsedTime`: Optional. Whether or not to show the `Elapsed Time` at the bottom. Defaults to `true`
+- `showStageTime`: Optional. Whether or not to show the time for each stage. Defaults to `true`
+- `title`: Optional. The title to show at the top.
+- `timerUnit`: The unit to use for the elapsed time and stage time. Can be `ms` or `s`. Defaults to `ms`
+
 # Contributing
 
 See the [contributing guide](./CONRTIBUTING.md).

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

@@ -1,5 +1,6 @@
 import { KeyValuePair, SimpleMessage, StageInfoBlock } from './components/stages.js';
 import { Design } from './design.js';
+import { StageStatus } from './stage-tracker.js';
 export type MultiStageOutputOptions<T extends Record<string, unknown>> = {
     /**
      * Stages to render.
@@ -66,13 +67,61 @@ export declare class MultiStageOutput<T extends Record<string, unknown>> impleme
     private readonly timerUnit?;
     private readonly title?;
     constructor({ data, design, jsonEnabled, postStagesBlock, preStagesBlock, showElapsedTime, showStageTime, stageSpecificBlock, stages, timerUnit, title, }: MultiStageOutputOptions<T>);
+    /**
+     * Stop multi-stage output from running with a failed status.
+     */
+    error(): void;
+    /**
+     * Go to a stage, marking any stages in between the current stage and the provided stage as completed.
+     *
+     * If the stage does not exist or is before the current stage, nothing will happen.
+     *
+     * If the stage is the same as the current stage, the data will be updated.
+     *
+     * @param stage Stage to go to
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
     goto(stage: string, data?: Partial<T>): void;
+    /**
+     * Moves to the next stage of the process.
+     *
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
     next(data?: Partial<T>): void;
-    stop(error?: Error): void;
+    /**
+     * Go to a stage, marking any stages in between the current stage and the provided stage as skipped.
+     *
+     * If the stage does not exist or is before the current stage, nothing will happen.
+     *
+     * If the stage is the same as the current stage, the data will be updated.
+     *
+     * @param stage Stage to go to
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
+    skipTo(stage: string, data?: Partial<T>): void;
+    /**
+     * Stop multi-stage output from running.
+     *
+     * The stage currently running will be changed to the provided `finalStatus`.
+     *
+     * @param finalStatus - The status to set the current stage to.
+     * @returns void
+     */
+    stop(finalStatus?: StageStatus): void;
     [Symbol.dispose](): void;
+    /**
+     * Updates the data of the component.
+     *
+     * @param data - The partial data object to update the component's data with.
+     * @returns void
+     */
     updateData(data: Partial<T>): void;
     private formatKeyValuePairs;
     /** shared method to populate everything needed for Stages cmp */
     private generateStagesInput;
+    private rerender;
     private update;
 }

package/lib/multi-stage-output.js

@@ -177,6 +177,23 @@ export class MultiStageOutput {
             this.inkInstance = render(React.createElement(Stages, { ...this.generateStagesInput() }));
         }
     }
+    /**
+     * Stop multi-stage output from running with a failed status.
+     */
+    error() {
+        this.stop('failed');
+    }
+    /**
+     * Go to a stage, marking any stages in between the current stage and the provided stage as completed.
+     *
+     * If the stage does not exist or is before the current stage, nothing will happen.
+     *
+     * If the stage is the same as the current stage, the data will be updated.
+     *
+     * @param stage Stage to go to
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
     goto(stage, data) {
         if (this.stopped)
             return;
@@ -186,25 +203,67 @@ export class MultiStageOutput {
         // prevent going to a previous stage
         if (this.stages.indexOf(stage) < this.stages.indexOf(this.stageTracker.current ?? this.stages[0]))
             return;
-        this.update(stage, data);
+        this.update(stage, 'completed', data);
     }
+    /**
+     * Moves to the next stage of the process.
+     *
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
     next(data) {
         if (this.stopped)
             return;
         const nextStageIndex = this.stages.indexOf(this.stageTracker.current ?? this.stages[0]) + 1;
         if (nextStageIndex < this.stages.length) {
-            this.update(this.stages[nextStageIndex], data);
+            this.update(this.stages[nextStageIndex], 'completed', data);
         }
     }
-    stop(error) {
+    /**
+     * Go to a stage, marking any stages in between the current stage and the provided stage as skipped.
+     *
+     * If the stage does not exist or is before the current stage, nothing will happen.
+     *
+     * If the stage is the same as the current stage, the data will be updated.
+     *
+     * @param stage Stage to go to
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
+    skipTo(stage, data) {
+        if (this.stopped)
+            return;
+        // ignore non-existent stages
+        if (!this.stages.includes(stage))
+            return;
+        // prevent going to a previous stage
+        if (this.stages.indexOf(stage) < this.stages.indexOf(this.stageTracker.current ?? this.stages[0]))
+            return;
+        this.update(stage, 'skipped', data);
+    }
+    /**
+     * Stop multi-stage output from running.
+     *
+     * The stage currently running will be changed to the provided `finalStatus`.
+     *
+     * @param finalStatus - The status to set the current stage to.
+     * @returns void
+     */
+    stop(finalStatus = 'completed') {
         if (this.stopped)
             return;
         this.stopped = true;
-        this.stageTracker.refresh(this.stageTracker.current ?? this.stages[0], { hasError: Boolean(error), isStopping: true });
+        this.stageTracker.refresh(this.stageTracker.current ?? this.stages[0], {
+            finalStatus,
+        });
         if (isInCi) {
             this.ciInstance?.stop(this.stageTracker);
             return;
         }
+        // The underlying components expect an Error, although they don't currently use anything on the error - they check if it exists.
+        // Instead of refactoring the components to take a boolean, we pass in a placeholder Error,
+        // which, gives us the flexibility in the future to pass in an actual Error if we want
+        const error = finalStatus === 'failed' ? new Error('Error') : undefined;
         const stagesInput = { ...this.generateStagesInput(), ...(error ? { error } : {}) };
         this.inkInstance?.rerender(React.createElement(Stages, { ...stagesInput }));
         this.inkInstance?.unmount();
@@ -212,11 +271,17 @@ export class MultiStageOutput {
     [Symbol.dispose]() {
         this.inkInstance?.unmount();
     }
+    /**
+     * Updates the data of the component.
+     *
+     * @param data - The partial data object to update the component's data with.
+     * @returns void
+     */
     updateData(data) {
         if (this.stopped)
             return;
         this.data = { ...this.data, ...data };
-        this.update(this.stageTracker.current ?? this.stages[0], data);
+        this.rerender();
     }
     formatKeyValuePairs(infoBlock) {
         return (infoBlock?.map((info) => {
@@ -245,9 +310,7 @@ export class MultiStageOutput {
             title: this.title,
         };
     }
-    update(stage, data) {
-        this.data = { ...this.data, ...data };
-        this.stageTracker.refresh(stage);
+    rerender() {
         if (isInCi) {
             this.ciInstance?.update(this.stageTracker, this.data);
         }
@@ -255,4 +318,9 @@ export class MultiStageOutput {
             this.inkInstance?.rerender(React.createElement(Stages, { ...this.generateStagesInput() }));
         }
     }
+    update(stage, bypassStatus, data) {
+        this.data = { ...this.data, ...data };
+        this.stageTracker.refresh(stage, { bypassStatus });
+        this.rerender();
+    }
 }

package/lib/stage-tracker.d.ts

@@ -7,8 +7,8 @@ export declare class StageTracker {
     entries(): IterableIterator<[string, StageStatus]>;
     get(stage: string): StageStatus | undefined;
     refresh(nextStage: string, opts?: {
-        hasError?: boolean;
-        isStopping?: boolean;
+        finalStatus?: StageStatus;
+        bypassStatus?: StageStatus;
     }): void;
     set(stage: string, status: StageStatus): void;
     values(): IterableIterator<StageStatus>;

package/lib/stage-tracker.js

@@ -19,15 +19,9 @@ export class StageTracker {
                 continue;
             if (this.map.get(stage) === 'failed')
                 continue;
-            // .stop() was called with an error => set the stage to failed
-            if (nextStage === stage && opts?.hasError) {
-                this.set(stage, 'failed');
-                this.stopMarker(stage);
-                continue;
-            }
-            // .stop() was called without an error => set the stage to completed
-            if (nextStage === stage && opts?.isStopping) {
-                this.set(stage, 'completed');
+            // .stop() was called with a finalStatus
+            if (nextStage === stage && opts?.finalStatus) {
+                this.set(stage, opts.finalStatus);
                 this.stopMarker(stage);
                 continue;
             }
@@ -40,12 +34,12 @@ export class StageTracker {
                 }
                 continue;
             }
-            // any stage before the current stage should be marked as skipped if it's still pending
+            // any pending stage before the current stage should be marked using opts.bypassStatus
             if (stages.indexOf(stage) < stages.indexOf(nextStage) && this.map.get(stage) === 'pending') {
-                this.set(stage, 'skipped');
+                this.set(stage, opts?.bypassStatus ?? 'completed');
                 continue;
             }
-            // any stage before the current stage should be as completed (if it hasn't been marked as skipped or failed yet)
+            // any stage before the current stage should be marked as completed (if it hasn't been marked as skipped or failed yet)
             if (stages.indexOf(nextStage) > stages.indexOf(stage)) {
                 this.set(stage, 'completed');
                 this.stopMarker(stage);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/multi-stage-output",
   "description": "Terminal output for oclif commands with multiple stages",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/multi-stage-output/issues",
   "dependencies": {
@@ -30,7 +30,7 @@
     "eslint-config-xo-react": "^0.27.0",
     "eslint-plugin-react": "^7.34.3",
     "eslint-plugin-react-hooks": "^4.6.2",
-    "husky": "^9.1.3",
+    "husky": "^9.1.5",
     "ink-testing-library": "^4.0.0",
     "lint-staged": "^15",
     "mocha": "^10.7.3",