@travetto/terminal 3.0.2 → 3.1.0-rc.0

package/README.md

@@ -1,6 +1,7 @@
 <!-- This file was generated by @travetto/doc and should not be modified directly -->
-<!-- Please modify https://github.com/travetto/travetto/tree/main/module/terminal/DOC.ts and execute "npx trv doc" to rebuild -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/terminal/DOC.tsx and execute "npx trv doc" to rebuild -->
 # Terminal
+
 ## General terminal support
 
 **Install: @travetto/terminal**
@@ -12,21 +13,16 @@ npm install @travetto/terminal
 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: 
-
-   
+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.
@@ -42,12 +38,12 @@ const tplFn = GlobalTerminal.templateFunction({
   path: 'teal',
   success: 'green',
   failure: 'red',
-  param: 'yellow',
+  param: ['yellow', 'goldenrod'],
   type: 'cyan',
-  description: 'white',
-  title: 'brightWhite',
+  description: ['white', 'gray'],
+  title: ['brightWhite', 'black'],
   identifier: 'dodgerBlue',
-  subtitle: 'lightGray',
+  subtitle: ['lightGray', 'darkGray'],
   subsubtitle: 'darkGray'
 });
 
@@ -61,7 +57,7 @@ When the color palette is combined with [Base](https://github.com/travetto/trave
 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 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`
 
@@ -78,12 +74,9 @@ 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.
+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.2",
+  "version": "3.1.0-rc.0",
   "description": "General terminal support",
   "keywords": [
     "terminal",

package/src/color-output.ts

@@ -9,7 +9,7 @@ export type TermStyle =
 
 export type TermStyleInput = TermStyle | RGBInput;
 export type Prim = string | number | boolean | Date | RegExp;
-export type TermColorPaletteInput = Record<string, TermStyleInput | [TermStyleInput, TermStyleInput]>;
+export type TermColorPaletteInput = Record<string, TermStyleInput | [dark: TermStyleInput, light: TermStyleInput]>;
 export type TermColorFn = (text: Prim) => string;
 export type TermColorPalette<T> = Record<keyof T, TermColorFn>;
 
@@ -92,7 +92,7 @@ export class ColorOutputUtil {
   /**
    * Make a simple primitive colorer
    */
-  static colorer(term: TermState, style: TermStyleInput | [light: TermStyleInput, dark: TermStyleInput]): TermColorFn {
+  static colorer(term: TermState, style: TermStyleInput | [dark: TermStyleInput, light: TermStyleInput]): TermColorFn {
     const schemes = {
       light: this.getStyledLevels(Array.isArray(style) ? style[1] ?? style[0] : style),
       dark: this.getStyledLevels(Array.isArray(style) ? style[0] : style),

package/src/operation.ts

@@ -32,9 +32,23 @@ export class TerminalOperation {
       }
       await batch.commit();
 
+      let start = Date.now();
+      const minDelay = config.minDelay ?? 0;
+
+      let line: string = '';
       for await (const text of source) {
-        await TerminalWriter.for(term).setPosition(writePos).write(text).clearLine(1).commit(true);
+        line = text;
+        if ((Date.now() - start) >= minDelay) {
+          start = Date.now();
+          await TerminalWriter.for(term).setPosition(writePos).write(line).clearLine(1).commit(true);
+          line = '';
+        }
+      }
+
+      if (line) {
+        await TerminalWriter.for(term).setPosition(writePos).write(line).clearLine(1).commit(true);
       }
+
       if (config.clearOnFinish ?? true) {
         await TerminalWriter.for(term).setPosition(writePos).clearLine().commit(true);
       }

package/src/query.ts

@@ -1,4 +1,5 @@
-import tty from 'tty';
+import type tty from 'tty';
+import { spawn } from 'child_process';
 
 import { ANSICodes } from './codes';
 import { IterableUtil } from './iterable';
@@ -7,6 +8,31 @@ import { RGB, TermCoord, TermQuery } from './types';
 const to256 = (x: string): number => Math.trunc(parseInt(x, 16) / (16 ** (x.length - 2)));
 const COLOR_RESPONSE = /(?<r>][0-9a-f]+)[/](?<g>[0-9a-f]+)[/](?<b>[0-9a-f]+)[/]?(?<a>[0-9a-f]+)?/i;
 
+// @ts-expect-error
+const queryScript = (function (...bytes) {
+  const i = process.stdin;
+  i.setRawMode(true);
+  i.resume();
+  i.once('readable', function () {
+    const inp = i.read();
+    /* @ts-expect-error */
+    process.send(Buffer.isBuffer(inp) ? inp.toString('utf8') : inp);
+    i.setRawMode(false);
+  });
+  process.stdout.write(String.fromCharCode(...bytes));
+});
+
+const runQuery = async (input: tty.ReadStream, output: tty.WriteStream, code: string): Promise<Buffer> => {
+  const script = queryScript.toString().replaceAll('\'', '"').replaceAll('\n', '');
+  const fullScript = `(${script})(${code.split('').map(x => x.charCodeAt(0))})`
+  const proc = spawn(process.argv0, ['-e', fullScript], { stdio: [input, output, 2, 'ipc'], detached: true });
+  const text = await new Promise<string>((res, rej) => {
+    proc.once('message', res);
+    proc.on('error', rej);
+  });
+  return Buffer.from(text, 'utf8');
+};
+
 const ANSIQueries = {
   /** Parse xterm color response */
   color: (field: 'background' | 'foreground'): TermQuery<RGB | undefined> => ({
@@ -43,43 +69,15 @@ export class TerminalQuerier {
   #queue = IterableUtil.simpleQueue();
   #output: tty.WriteStream;
   #input: tty.ReadStream;
+  #restore?: () => void;
 
   constructor(input: tty.ReadStream, output: tty.WriteStream) {
     this.#input = input;
     this.#output = output;
   }
 
-  async #readInput(query: string): Promise<Buffer> {
-    const isRaw = this.#input.isRaw;
-    const isPaused = this.#input.isPaused();
-    const data = this.#input.listeners('data');
-    try {
-      this.#input.removeAllListeners('data');
-
-      if (isPaused) {
-        this.#input.resume();
-      }
-
-      this.#input.setRawMode(true);
-      // Send data, but do not wait on it
-      this.#output.write(query);
-      await new Promise(res => this.#input.once('readable', res));
-      const val: Buffer | string = this.#input.read();
-      return typeof val === 'string' ? Buffer.from(val, 'utf8') : val;
-    } finally {
-      if (isPaused) {
-        this.#input.pause();
-      }
-      this.#input.setRawMode(isRaw);
-      for (const fn of data) {
-        // @ts-ignore
-        this.#input.on('data', fn);
-      }
-    }
-  }
-
   query<T>(q: TermQuery<T>): Promise<T> {
-    return this.#queue.add(() => this.#readInput(q.query()).then(q.response));
+    return this.#queue.add(() => runQuery(this.#input, this.#output, q.query()).then(q.response));
   }
 
   cursorPosition(): Promise<TermCoord> {
@@ -90,7 +88,8 @@ export class TerminalQuerier {
     return this.query(ANSIQueries.color('background'));
   }
 
-  close(): Promise<void> {
-    return this.#queue.close();
+  close(): void {
+    this.#restore?.();
+    this.#queue.close();
   }
 }

package/src/terminal.ts

@@ -13,6 +13,7 @@ import { ColorOutputUtil, Prim, TermColorFn, TermColorPalette, TermColorPaletteI
 type TerminalStreamPositionConfig = {
   position?: TermLinePosition;
   staticMessage?: string;
+  minDelay?: number;
 };
 
 type TerminalProgressConfig = TerminalStreamPositionConfig & {
@@ -98,12 +99,11 @@ export class Terminal implements TermState {
     return this.#init;
   }
 
-  async reset(): Promise<void> {
-    await this.#query.close();
+  reset(): void {
+    this.#query.close();
     if (this.interactive) {
-      await this.writer().reset().commit();
+      this.#output.write(this.writer().resetCommands());
     }
-    return;
   }
 
   getCursorPosition(): Promise<TermCoord> {

package/src/types.ts

@@ -13,7 +13,7 @@ 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 TerminalStreamingConfig = { position?: TermLinePosition, clearOnFinish?: boolean, at?: TermCoord };
+export type TerminalStreamingConfig = { position?: TermLinePosition, clearOnFinish?: boolean, at?: TermCoord, minDelay?: number };
 export type TerminalWaitingConfig = { end?: boolean, committedPrefix?: string } & TerminalStreamingConfig & DelayedConfig;
 
 export type TermColorLevel = 0 | 1 | 2 | 3;

package/src/writer.ts

@@ -137,10 +137,16 @@ export class TerminalWriter {
 
   /** Reset */
   reset(): this {
-    return this
-      .write(ANSICodes.POSITION_SAVE())
-      .write(ANSICodes.SHOW_CURSOR())
-      .write(ANSICodes.SCROLL_RANGE_CLEAR())
-      .write(ANSICodes.POSITION_RESTORE());
+    return this.write(this.resetCommands());
+  }
+
+  /** Reset Commands */
+  resetCommands(): string {
+    return [
+      ANSICodes.POSITION_SAVE(),
+      ANSICodes.SHOW_CURSOR(),
+      ANSICodes.SCROLL_RANGE_CLEAR(),
+      ANSICodes.POSITION_RESTORE()
+    ].join('');
   }
 }