@travetto/terminal 3.0.0-rc.8 → 3.0.0

package/README.md

@@ -6,4 +6,84 @@
 **Install: @travetto/terminal**
 ```bash
 npm install @travetto/terminal
+
+# or
+
+yarn add @travetto/terminal
 ```
+
+This module provides basic support for interacting with the terminal, and provides the basis for output colorization and the basic command line interactions.  The functionality can be broken down into: 
+
+   
+   *  Output Colorization
+   *  Terminal Interactions
+
+## Output Colorization
+
+Oddly enough, colorizing output in a terminal is a fairly complex process.  The standards are somewhat inconsistent and detection can be a tricky process. For terminals, [Node](https://nodejs.org) supports 4 different levels of coloring:
+   
+   *  0 - One color, essentially uncolored output
+   *  1 - Basic color support, 16 colors
+   *  2 - Enhanced color support, 225 colors, providing a fair representation of most colors
+   *  3 - True color, 24bit color with R, G, B each getting 8-bits.  Can represent any color needed
+
+This module provides the ability to define color palettes using RGB or [named colors](https://github.com/travetto/travetto/tree/main/module/terminal/src/named-colors.ts#L1) modeled after the standard HTML color names.  The module also provides the ability to specify palettes based on a dark or light background for a given terminal.  Support for this is widespread, but when it fails, it will gracefully assume a dark background. 
+
+These palettes then are usable at runtime, with the module determine light or dark palettes, as well as falling back to the closest color value based on what the existing terminal supports.  This means a color like 'olivegreen', will get the proper output in 24bit color support, a close approximation in enhanced color support, fall back to green in basic color support, and will be color less at level 0.
+
+**Code: CLI Color Palette**
+```typescript
+import { Util } from '@travetto/base';
+import { GlobalTerminal } from '@travetto/terminal';
+
+const tplFn = GlobalTerminal.templateFunction({
+  input: 'oliveDrab',
+  output: 'pink',
+  path: 'teal',
+  success: 'green',
+  failure: 'red',
+  param: 'yellow',
+  type: 'cyan',
+  description: 'white',
+  title: 'brightWhite',
+  identifier: 'dodgerBlue',
+  subtitle: 'lightGray',
+  subsubtitle: 'darkGray'
+});
+
+export const cliTpl = Util.makeTemplate(tplFn);
+```
+
+When the color palette is combined with [Base](https://github.com/travetto/travetto/tree/main/module/base#readme "Environment config and common utilities for travetto applications.")'s Util.makeTemplate, you produce a string template function that will automatically colorize:
+
+**Code: Sample Template Usage**
+```typescript
+cliTpl`Build finished: status=${{success: "complete"}}, output=${{path: "/build.zip"}}`
+```
+
+This would then produce colorized output based on the palette, and the terminal capabilities.
+
+This module follows the pattern [Node](https://nodejs.org) follows with respect to the environment variables: `NO_COLOR`, `FORCE_COLOR` and `NODE_DISABLE_COLORS`
+
+**Terminal: Node help on colors**
+```bash
+$ /usr/bin/node -h | grep -i color
+
+FORCE_COLOR                 when set to 'true', 1, 2, 3, or an
+                            empty string causes NO_COLOR and
+                            NODE_DISABLE_COLORS to be ignored.
+NO_COLOR                    Alias for NODE_DISABLE_COLORS
+NODE_DISABLE_COLORS         set to 1 to disable colors in the REPL
+```
+
+## Terminal Interactions
+Within the [Travetto](https://travetto.dev) framework, there are plenty of command line interactions that are enhanced with additional interactivity.  This mainly revolves around indicating progress while a program is executing.  The module provides support for:
+
+   
+   *  Progress Bars
+   *  Waiting Indicators
+   *  Streaming Content
+
+This is generally meant for use within the framework, and so is highly tailored to the specific needs and scenarios.  You can see this pattern play out in the [Compiler](https://github.com/travetto/travetto/tree/main/module/compiler#readme "The compiler infrastructure for the Travetto framework") progress output, or in [Pack](https://github.com/travetto/travetto/tree/main/module/pack#readme "Code packing utilities")'s output.
+
+In these scenarios, the dynamic behaviors are dependent on having an interactive TTY.  When running without access to a proper stdin, the output will default to basic line printing.    This dynamic behavior can also be disabled using the environment variable `TRV_QUIET`.  When set to `1` will provide a minimal text-based experience.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/terminal",
-  "version": "3.0.0-rc.8",
+  "version": "3.0.0",
   "description": "General terminal support",
   "keywords": [
     "terminal",

package/src/operation.ts

@@ -1,6 +1,6 @@
 import { IterableUtil } from './iterable';
 import { TerminalWriter } from './writer';
-import { Indexed, TermCoord, TerminalProgressRender, TerminalWaitingConfig, TermLinePosition, TermState } from './types';
+import { Indexed, TerminalProgressRender, TerminalStreamingConfig, TerminalWaitingConfig, TermState } from './types';
 import { ColorOutputUtil, TermStyleInput } from './color-output';
 
 const STD_WAIT_STATES = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'.split('');
@@ -10,8 +10,10 @@ export class TerminalOperation {
   /**
    * Allows for writing at top, bottom, or current position while new text is added
    */
-  static async streamToPosition(term: TermState, source: AsyncIterable<string>, pos: TermLinePosition = 'inline', curPos?: TermCoord): Promise<void> {
-    curPos ??= { ...await term.getCursorPosition() };
+  static async streamToPosition(term: TermState, source: AsyncIterable<string>, config: TerminalStreamingConfig = {}): Promise<void> {
+    const curPos = config.at ?? { ...await term.getCursorPosition() };
+    const pos = config.position ?? 'inline';
+
     const writePos = pos === 'inline' ?
       { ...curPos, x: 0 } :
       { x: 0, y: pos === 'top' ? 0 : -1 };
@@ -33,7 +35,9 @@ export class TerminalOperation {
       for await (const text of source) {
         await TerminalWriter.for(term).setPosition(writePos).write(text).clearLine(1).commit(true);
       }
-      await TerminalWriter.for(term).setPosition(writePos).clearLine().commit(true);
+      if (config.clearOnFinish ?? true) {
+        await TerminalWriter.for(term).setPosition(writePos).clearLine().commit(true);
+      }
     } finally {
       const finalCursor = await term.getCursorPosition();
       await TerminalWriter.for(term).scrollRangeClear().setPosition(finalCursor).showCursor().commit();
@@ -59,15 +63,15 @@ export class TerminalOperation {
   /**
    * Waiting indicator, streamed to a specific position, can be canceled
    */
-  static streamWaiting(term: TermState, message: string, config: TerminalWaitingConfig = {}, curPos?: TermCoord): () => Promise<void> {
+  static streamWaiting(term: TermState, message: string, config: TerminalWaitingConfig = {}): () => Promise<void> {
     const { stop, stream } = IterableUtil.cycle(STD_WAIT_STATES);
     const indicator = IterableUtil.map(
       stream,
       IterableUtil.DELAY(config),
-      (ch, i) => config.end ? `${message} ${ch}` : (i === 0 ? `${ch} ${message}` : ch)
+      (ch, i) => config.end ? `${message} ${ch}` : `${ch} ${message}`
     );
 
-    const final = this.streamToPosition(term, indicator, config.position ?? 'inline', curPos);
+    const final = this.streamToPosition(term, indicator, config);
     return async () => { stop(); return final; };
   }
 
@@ -100,12 +104,15 @@ export class TerminalOperation {
     let writer: (() => Promise<unknown>) | undefined;
     let line: string | undefined;
 
+    let pos = await term.getCursorPosition();
+
+
     const commitLine = async (): Promise<void> => {
       await writer?.();
       if (line) {
-        const msg = cfg.commitedPrefix ? `${cfg.commitedPrefix} ${line}` : line;
+        const msg = cfg.committedPrefix ? `${cfg.committedPrefix} ${line}` : line;
         if (cfg.position === 'inline') {
-          await TerminalWriter.for(term).setPosition({ x: 0 }).changePosition({ y: -1 }).writeLine(msg).commit();
+          await TerminalWriter.for(term).setPosition(pos).write(msg).commit(true);
         } else {
           await TerminalWriter.for(term).writeLine(msg).commit();
         }
@@ -113,13 +120,12 @@ export class TerminalOperation {
       }
     };
 
-    const pos = await term.getCursorPosition();
-
     for await (let msg of lines) {
       await commitLine();
       if (msg !== undefined) {
         msg = msg.replace(/\n$/, '');
-        writer = this.streamWaiting(term, msg, cfg, pos);
+        pos = await term.getCursorPosition();
+        writer = this.streamWaiting(term, msg, { ...cfg, at: pos, clearOnFinish: false });
         line = msg;
       }
     }

package/src/terminal.ts

@@ -93,6 +93,7 @@ export class Terminal implements TermState {
           () => this.interactive ? this.#query.backgroundColor() : undefined
         );
       })();
+      process.on('exit', () => this.reset());
     }
     return this.#init;
   }
@@ -132,7 +133,7 @@ export class Terminal implements TermState {
     if (!this.interactive) {
       for await (const line of lines) {
         if (line !== undefined) {
-          const out = config.commitedPrefix ? `${config.commitedPrefix} ${line}` : line;
+          const out = config.committedPrefix ? `${config.committedPrefix} ${line}` : line;
           await this.writeLines(out);
         }
       }
@@ -174,7 +175,7 @@ export class Terminal implements TermState {
       await IterableUtil.drain(source);
       return;
     }
-    return TerminalOperation.streamToPosition(this, IterableUtil.map(source, resolve), config?.position);
+    return TerminalOperation.streamToPosition(this, IterableUtil.map(source, resolve), config);
   }
 
   /**
@@ -203,7 +204,4 @@ export class Terminal implements TermState {
   }
 }
 
-export const GlobalTerminal = new Terminal({ output: process.stdout });
-
-// Trigger
-GlobalTerminal.init();
+export const GlobalTerminal = new Terminal({ output: process.stdout });

package/src/types.ts

@@ -13,7 +13,8 @@ export type TerminalTableEvent = { idx: number, text: string, done?: boolean };
 export type TerminalTableConfig = { header?: string[], forceNonInteractiveOrder?: boolean };
 export type TerminalProgressEvent = { idx: number, total?: number, text?: string };
 export type TerminalProgressRender = (ev: TerminalProgressEvent) => string;
-export type TerminalWaitingConfig = { position?: TermLinePosition, end?: boolean, commitedPrefix?: string } & DelayedConfig;
+export type TerminalStreamingConfig = { position?: TermLinePosition, clearOnFinish?: boolean, at?: TermCoord };
+export type TerminalWaitingConfig = { end?: boolean, committedPrefix?: string } & TerminalStreamingConfig & DelayedConfig;
 
 export type TermColorLevel = 0 | 1 | 2 | 3;
 export type TermColorScheme = 'dark' | 'light';