@travetto/terminal 3.4.0 → 4.0.0-rc.0

package/README.md

@@ -23,31 +23,28 @@ Oddly enough, colorizing output in a terminal is a fairly complex process.  The
    *  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. 
+This module provides the ability to define color palettes using RGB colors, and additionally provides support for 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.
+These palettes then are usable at runtime, with the module determining 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', 'goldenrod'],
-  type: 'cyan',
-  description: ['white', 'gray'],
-  title: ['brightWhite', 'black'],
-  identifier: 'dodgerBlue',
-  subtitle: ['lightGray', 'darkGray'],
-  subsubtitle: 'darkGray'
+import { StyleUtil } from '@travetto/terminal';
+
+export const cliTpl = StyleUtil.getTemplate({
+  input: '#6b8e23', // Olive drab
+  output: '#ffc0cb', // Pink
+  path: '#008080', // Teal
+  success: '#00ff00', // Green
+  failure: '#ff0000', // Red
+  param: ['#ffff00', '#daa520'], // Yellow / Goldenrod
+  type: '#00ffff', // Teal
+  description: ['#e5e5e5', '#808080'], // White / Gray
+  title: ['#ffffff', '#000000'], // Bright white / black
+  identifier: '#1e90ff', // Dodger blue
+  subtitle: ['#d3d3d3', '#a9a9a9'], // Light gray / Dark Gray
+  subsubtitle: '#a9a9a9' // Dark gray
 });
-
-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:

package/__index__.ts

@@ -1,10 +1,5 @@
-export * from './src/codes';
-export * from './src/color-define';
-export * from './src/color-output';
-export * from './src/iterable';
-export * from './src/named-colors';
-export * from './src/operation';
-export * from './src/query';
+/// <reference path="./src/trv.d.ts" />
+export * from './src/style';
 export * from './src/terminal';
-export * from './src/types';
-export * from './src/writer';
+export * from './src/writer';
+export * from './src/util';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/terminal",
-  "version": "3.4.0",
+  "version": "4.0.0-rc.0",
   "description": "General terminal support",
   "keywords": [
     "terminal",
@@ -23,6 +23,10 @@
     "url": "https://github.com/travetto/travetto.git",
     "directory": "module/terminal"
   },
+  "dependencies": {
+    "@travetto/base": "^4.0.0-rc.0",
+    "chalk": "^4.1.2"
+  },
   "travetto": {
     "displayName": "Terminal"
   },

package/src/style.ts

@@ -0,0 +1,122 @@
+import chalk from 'chalk';
+
+import { Env, TypedObject, Primitive } from '@travetto/base';
+
+type TemplatePrim = Primitive | RegExp;
+type Color = `#${string}`;
+export type TermStyleInput = Color | { text: Color, background?: Color, inverse?: boolean, bold?: boolean, italic?: boolean, underline?: boolean };
+type TermStylePairInput = TermStyleInput | [dark: TermStyleInput, light: TermStyleInput];
+export type TermStyleFn = (input: TemplatePrim) => string;
+type TermStyledTemplate<T extends string> = (values: TemplateStringsArray, ...keys: (Partial<Record<T, TemplatePrim>> | string)[]) => string;
+export type ColorLevel = 0 | 1 | 2 | 3;
+
+// eslint-disable-next-line no-control-regex
+const ANSI_CODE_REGEX = /(\x1b|\x1B)[\[\]][?]?[0-9;]+[A-Za-z]/g;
+
+export class StyleUtil {
+
+  static #darkAnsi256 = new Set([
+    0, 1, 2, 3, 4, 5, 6, 16, 17, 18, 19, 20, 22, 23, 24, 25, 26, 28, 29, 30, 31, 32, 34, 35, 36, 37, 38, 40, 41, 42, 43, 44, 52, 53, 54,
+    55, 56, 58, 59, 60, 64, 65, 66, 70, 76, 88, 89, 90, 91, 92, 94, 95, 96, 100, 101, 106, 112, 124, 125, 126, 127, 128, 130, 136, 142,
+    148, 160, 161, 162, 163, 164, 166, 172, 178, 184, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243
+  ]);
+
+  static #scheme: { key: string, dark: boolean } = { key: '', dark: true };
+
+  /**
+   * Create text render function from style input using current color levels
+   */
+  static getStyle(input: TermStyleInput): TermStyleFn {
+    if (typeof input === 'string') {
+      return chalk.hex(input);
+    } else {
+      let style: chalk.Chalk = chalk;
+      for (const key of TypedObject.keys(input)) {
+        switch (key) {
+          case 'text': style = style.hex(input[key]!); break;
+          case 'background': style = style.bgHex(input[key]!); break;
+          default: style = (input[key] ? style[key] : style); break;
+        }
+      }
+      return style;
+    }
+  }
+
+  /**
+   * Read foreground/background color if env var is set
+   */
+  static isBackgroundDark(): boolean {
+    const key = Env.COLORFGBG.val ?? '';
+
+    if (this.#scheme.key === key) {
+      return this.#scheme.dark;
+    }
+
+    const [, bg = '0'] = key.split(';');
+    const dark = this.#darkAnsi256.has(+bg);
+    Object.assign(this.#scheme, { key, dark });
+    return dark;
+  }
+
+  /**
+   * Create renderer from input source
+   */
+  static getThemedStyle(input: TermStylePairInput): TermStyleFn {
+    const [dark, light] = (Array.isArray(input) ? input : [input]);
+    const isDark = this.isBackgroundDark();
+    return isDark ? this.getStyle(dark) : this.getStyle(light ?? dark);
+  }
+
+  /**
+   * Is styling currently enabled
+   */
+  static get enabled(): boolean {
+    return chalk.level > 0;
+  }
+
+  /**
+   * Build style palette, with support for background theme awareness
+   */
+  static getPalette<K extends string>(inp: Record<K, TermStylePairInput>): Record<K, TermStyleFn> {
+    return TypedObject.fromEntries(
+      TypedObject.entries(inp).map(([k, v]) => [k, this.getThemedStyle(v)]));
+  }
+
+  /**
+   * Make a template function based on the input set
+   */
+  static getTemplate<K extends string>(input: Record<K, TermStylePairInput>): TermStyledTemplate<K> {
+    const palette = this.getPalette(input);
+
+    return (values: TemplateStringsArray, ...keys: (Partial<Record<K, TemplatePrim>> | string)[]) => {
+      if (keys.length === 0) {
+        return values[0];
+      } else {
+        const out = keys.map((el, i) => {
+          let final = el;
+          if (typeof el !== 'string') {
+            const subKeys = TypedObject.keys(el);
+            if (subKeys.length !== 1) {
+              throw new Error('Invalid template variable, one and only one key should be specified');
+            }
+            const [k] = subKeys;
+            const v = el[k]!;
+            final = v === undefined ? '' : palette[k](v)!;
+          }
+          return `${values[i] ?? ''}${final ?? ''}`;
+        });
+        if (values.length > keys.length) {
+          out.push(values[values.length - 1]);
+        }
+        return out.join('');
+      }
+    };
+  }
+
+  /**
+   * Remove style escape sequences
+   */
+  static cleanText(text: string): string {
+    return text.replace(ANSI_CODE_REGEX, '');
+  }
+}

package/src/terminal.ts

@@ -1,208 +1,155 @@
-import tty from 'tty';
-
-import { IterableUtil, MapFn } from './iterable';
-import {
-  TermColorLevel, TermColorScheme, TerminalProgressEvent, TerminalTableConfig,
-  TerminalTableEvent, TerminalWaitingConfig, TermLinePosition, TermState, TermCoord
-} from './types';
-import { TerminalOperation } from './operation';
-import { TerminalQuerier } from './query';
-import { TerminalWriter } from './writer';
-import { ColorOutputUtil, Prim, TermColorFn, TermColorPalette, TermColorPaletteInput, TermStyleInput } from './color-output';
-
-type TerminalStreamPositionConfig = {
-  position?: TermLinePosition;
-  staticMessage?: string;
-  minDelay?: number;
-};
-
-type TerminalProgressConfig = TerminalStreamPositionConfig & {
-  style?: TermStyleInput;
-};
-
-/**
- * An enhanced tty write stream
- */
-export class Terminal implements TermState {
-
-  static async for(config: Partial<TermState>): Promise<Terminal> {
-    const term = new Terminal(config);
-    await term.init();
-    return term;
-  }
+import timers from 'node:timers/promises';
+import tty from 'node:tty';
 
-  #init: Promise<void>;
-  #output: tty.WriteStream;
-  #input: tty.ReadStream;
-  #interactive: boolean;
-  #width?: number;
-  #backgroundScheme?: TermColorScheme;
-  #colorLevel?: TermColorLevel;
-  #query: TerminalQuerier;
-
-  constructor(config: Partial<TermState>) {
-    this.#output = config.output ?? process.stdout;
-    this.#input = config.input ?? process.stdin;
-    this.#interactive = config.interactive ?? (this.#output.isTTY && !/^(true|yes|on|1)$/i.test(process.env.TRV_QUIET ?? ''));
-    this.#width = config.width;
-    this.#colorLevel = config.colorLevel;
-    this.#backgroundScheme = config.backgroundScheme;
-    this.#query = TerminalQuerier.for(this.#input, this.#output);
-  }
-
-  get output(): tty.WriteStream {
-    return this.#output;
-  }
+import { Env, Util } from '@travetto/base';
 
-  get input(): tty.ReadStream {
-    return this.#input;
-  }
+import { TerminalWriter } from './writer';
 
-  get interactive(): boolean {
-    return this.#interactive;
-  }
+type TerminalStreamingConfig = { minDelay?: number, outputStreamToMain?: boolean };
+type Coord = { x: number, y: number };
 
-  get width(): number {
-    return this.#width ?? (this.#output.isTTY ? this.#output.columns : 120);
-  }
+export const WAIT_TOKEN = '%WAIT%';
+const STD_WAIT_STATES = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'.split('');
 
-  get height(): number {
-    return (this.#output.isTTY ? this.#output.rows : 120);
-  }
+const lineStatus = (l: string): string => l.replace(WAIT_TOKEN, ' ');
+const lineMain = (l: string): string => l.replace(WAIT_TOKEN, '').trim();
 
-  get colorLevel(): TermColorLevel {
-    return this.#colorLevel ?? 0;
-  }
+/** An basic tty wrapper */
+export class Terminal {
 
-  get backgroundScheme(): TermColorScheme {
-    return this.#backgroundScheme ?? 'dark';
-  }
-
-  writer(): TerminalWriter {
-    return TerminalWriter.for(this);
-  }
-
-  async writeLines(...text: string[]): Promise<void> {
-    return this.writer().writeLines(text, this.interactive).commit();
-  }
+  #interactive: boolean;
+  #writer: TerminalWriter;
+  #reset: () => Promise<void>;
+  #cleanExit = 0;
+  #width: number;
+  #height: number;
+  #output: tty.WriteStream;
 
-  async init(): Promise<void> {
-    if (!this.#init) {
-      this.#init = (async (): Promise<void> => {
-        this.#colorLevel ??= await ColorOutputUtil.readTermColorLevel(this.#output);
-        this.#backgroundScheme ??= await ColorOutputUtil.readBackgroundScheme(
-          this.#output,
-          () => this.interactive ? this.#query.backgroundColor() : undefined
-        );
-      })();
-      process.on('exit', () => this.reset());
+  async #showWaitingIndicator(pos: Coord, signal: AbortSignal): Promise<void> {
+    let done = false;
+    signal.addEventListener('abort', () => done = true);
+    let i = 0;
+    while (!done) {
+      await this.#writer.setPosition(pos).write(STD_WAIT_STATES[i++ % STD_WAIT_STATES.length]).commit(true);
+      await timers.setTimeout(100);
     }
-    return this.#init;
   }
 
-  reset(): void {
-    this.#query.close();
-    if (this.interactive) {
-      this.#output.write(this.writer().resetCommands());
+  #cleanOnExit(): () => void {
+    if (this.#cleanExit === 0) {
+      process.on('exit', this.#reset);
     }
+    this.#cleanExit += 1;
+    return () => (this.#cleanExit -= 1) === 0 && process.off('exit', this.#reset);
   }
 
-  getCursorPosition(): Promise<TermCoord> {
-    return this.#query.cursorPosition();
+  constructor(output?: tty.WriteStream, config?: { width?: number, height?: number }) {
+    this.#output = output ?? process.stdout;
+    this.#interactive = this.#output.isTTY && !Env.TRV_QUIET.isTrue;
+    this.#width = config?.width ?? (this.#output.isTTY ? this.#output.columns : 120);
+    this.#height = config?.height ?? (this.#output.isTTY ? this.#output.rows : 120);
+    const w = this.#writer = new TerminalWriter(this);
+    this.#reset = (): Promise<void> => w.softReset().commit();
   }
 
-  /**
-   * Waiting message with a callback to end
-   */
-  async withWaiting<T>(message: string, work: Promise<T> | (() => Promise<T>), config: TerminalWaitingConfig = {}): Promise<T> {
-    const res = (typeof work === 'function' ? work() : work);
-    if (!this.interactive) {
-      await this.writeLines(`${message}...`);
-      return res;
-    }
-    return res.finally(TerminalOperation.streamWaiting(this, message, config));
-  }
+  get output(): tty.WriteStream { return this.#output; }
+  get width(): number { return this.#width; }
+  get height(): number { return this.#height; }
+  get writer(): TerminalWriter { return this.#writer; }
+  get interactive(): boolean { return this.#interactive; }
 
   /**
-   * Stream line output, showing a waiting indicator for each line until the next one occurs
-   *
-   * @param lines
-   * @param config
-   * @returns
+   * Stream lines if interactive, with waiting indicator, otherwise print out
    */
-  async streamLinesWithWaiting(lines: AsyncIterable<string | undefined>, config: TerminalWaitingConfig): Promise<void> {
-    if (!this.interactive) {
-      for await (const line of lines) {
+  async streamLines(source: AsyncIterable<string | undefined>): Promise<void> {
+    if (!this.#interactive) {
+      for await (const line of source) {
         if (line !== undefined) {
-          const out = config.committedPrefix ? `${config.committedPrefix} ${line}` : line;
-          await this.writeLines(out);
+          await this.#writer.writeLine(`> ${line}`).commit();
         }
       }
     } else {
-      return TerminalOperation.streamLinesWithWaiting(this, lines, { position: 'bottom', ...config });
+      await this.streamToBottom(Util.mapAsyncItr(source, x => `%WAIT% ${x}`), { outputStreamToMain: true });
     }
   }
 
   /**
-   * Consumes a stream, of events, tied to specific list indices, and updates in place
+   * Allows for writing at bottom of screen with scrolling support for main content
    */
-  async streamList<T>(source: AsyncIterable<T>, resolve: MapFn<T, TerminalTableEvent>, config: TerminalTableConfig = {}): Promise<void> {
-    const resolved = IterableUtil.map(source, resolve);
-
-    await this.writeLines(...(config.header ?? []));
-
-    if (!this.interactive) {
-      const isDone = IterableUtil.filter(resolved, ev => !!ev.done);
-      if (config.forceNonInteractiveOrder) {
-        await this.writeLines(...(await IterableUtil.drain(isDone)).map(x => x.text), '');
-      } else {
-        await IterableUtil.drain(IterableUtil.map(isDone, ev => this.writeLines(ev.text)));
-        await this.writeLines('');
+  async streamToBottom(source: AsyncIterable<string | undefined>, config: TerminalStreamingConfig = {}): Promise<void> {
+    const writePos = { x: 0, y: -1 };
+    const minDelay = config.minDelay ?? 0;
+    const remove = this.#cleanOnExit();
+
+    let prev: string | undefined;
+    let stop: AbortController | undefined;
+    let start = Date.now();
+
+    try {
+      await this.#writer.hideCursor()
+        .storePosition().scrollRange({ end: -2 }).restorePosition()
+        .changePosition({ y: -1 }).write('\n')
+        .commit();
+
+      for await (const line of source) {
+        // Previous line
+        if (prev && config.outputStreamToMain) {
+          await this.writer.writeLine(lineMain(prev)).commit();
+        }
+
+        if (line && (Date.now() - start) >= minDelay) {
+          start = Date.now();
+          stop?.abort();
+          this.writer.setPosition(writePos).write(lineStatus(line)).clearLine(1).commit(true);
+
+          const idx = line.indexOf(WAIT_TOKEN);
+          if (idx >= 0) {
+            stop = new AbortController();
+            this.#showWaitingIndicator({ y: writePos.y, x: idx }, stop.signal);
+          }
+        }
+
+        prev = line;
+      }
+
+      stop?.abort();
+      if (prev !== undefined && config.outputStreamToMain) {
+        await this.writer.writeLine(lineMain(prev)).commit();
       }
-      return;
-    }
 
-    await TerminalOperation.streamList(this, resolved);
+      await this.#writer.setPosition(writePos).clearLine().commit(true);
+    } finally {
+      await this.#writer.softReset().commit();
+      remove();
+    }
   }
 
   /**
-   * Streams an iterable to a specific location, with support for non-interactive ttys
+   * Consumes a stream, of events, tied to specific list indices, and updates in place
    */
-  async streamToPosition<T>(source: AsyncIterable<T>, resolve: MapFn<T, string>, config?: TerminalStreamPositionConfig): Promise<void> {
-    if (!this.interactive) {
-      if (config?.staticMessage) {
-        await this.writeLines(config.staticMessage);
+  async streamList(source: AsyncIterable<{ idx: number, text: string, done?: boolean }>): Promise<void> {
+    if (!this.#interactive) {
+      const collected = [];
+      for await (const ev of source) {
+        if (ev.done) {
+          collected[ev.idx] = ev.text;
+        }
       }
-      await IterableUtil.drain(source);
+      await this.#writer.writeLines(collected).commit();
       return;
     }
-    return TerminalOperation.streamToPosition(this, IterableUtil.map(source, resolve), config);
-  }
-
-  /**
-   * Track progress of an asynchronous iterator, allowing the showing of a progress bar if the stream produces idx and total
-   */
-  async trackProgress<T, V extends TerminalProgressEvent>(
-    source: AsyncIterable<T>, resolve: MapFn<T, V>, config?: TerminalProgressConfig
-  ): Promise<void> {
-    const render = TerminalOperation.buildProgressBar(this, config?.style ?? { background: 'limeGreen', text: 'black' });
-    return this.streamToPosition(source, async (v, i) => render(await resolve(v, i)), config);
-  }
-
-  /** Creates a colorer function */
-  colorer(style: TermStyleInput | [light: TermStyleInput, dark: TermStyleInput]): TermColorFn {
-    return ColorOutputUtil.colorer(this, style);
-  }
-
-  /** Creates a color palette based on input styles */
-  palette<P extends TermColorPaletteInput>(input: P): TermColorPalette<P> {
-    return ColorOutputUtil.palette(this, input);
-  }
 
-  /** Convenience method to creates a color template function based on input styles */
-  templateFunction<P extends TermColorPaletteInput>(input: P): (key: keyof P, val: Prim) => string {
-    return ColorOutputUtil.templateFunction(this, input);
+    const remove = this.#cleanOnExit();
+    let max = 0;
+    try {
+      await this.#writer.hideCursor().commit();
+      for await (const { idx, text } of source) {
+        max = Math.max(idx, max);
+        await this.#writer.write('\n'.repeat(idx)).setPosition({ x: 0 }).write(text).clearLine(1).changePosition({ y: -idx }).commit();
+      }
+    } finally {
+      await this.#writer.changePosition({ y: max + 1 }).writeLine('\n').softReset().commit();
+      remove();
+    }
   }
-}
-
-export const GlobalTerminal = new Terminal({ output: process.stdout });
+}

package/src/trv.d.ts

@@ -0,0 +1,32 @@
+import type { ColorLevel } from './style';
+
+declare global {
+  interface TravettoEnv {
+    /**
+     * Flag for node to disable colors
+     */
+    NODE_DISABLE_COLORS: boolean;
+    /** 
+     * Terminal colors provided as ansi 256 color schemes
+     */
+    COLORFGBG: string;
+    /** 
+     * Enables color, even if `tty` is not available 
+     * @default undefined
+     */
+    FORCE_COLOR: boolean | ColorLevel;
+    /** 
+     * Disables color even if `tty` is available
+     * @default false
+     */
+    NO_COLOR: boolean;
+    /**
+     * Determines terminal color level
+     */
+    COLORTERM: string;
+    /**
+      * Terminal operation mode, false means simple output
+      */
+    TRV_QUIET: boolean;
+  }
+}

package/src/util.ts

@@ -0,0 +1,43 @@
+import { StyleUtil, TermStyleFn, TermStyleInput } from './style';
+import { Terminal, WAIT_TOKEN } from './terminal';
+
+type ProgressEvent<T> = { total?: number, idx: number, value: T };
+type ProgressStyle = { complete: TermStyleFn, incomplete?: TermStyleFn };
+
+export class TerminalUtil {
+
+  /**
+   * Create a progress bar updater, suitable for streaming to the bottom of the screen
+   */
+  static progressBarUpdater(
+    term: Terminal,
+    cfg?: {
+      withWaiting?: boolean;
+      style?: { complete: TermStyleInput, incomplete?: TermStyleInput } | (() => ProgressStyle);
+    }
+  ): (ev: ProgressEvent<string>) => string {
+    const styleBase = typeof cfg?.style !== 'function' ? {
+      complete: StyleUtil.getStyle(cfg?.style?.complete ?? { background: '#32cd32', text: '#ffffff' }),
+      incomplete: cfg?.style?.incomplete ? StyleUtil.getStyle(cfg.style.incomplete) : undefined,
+    } : undefined;
+
+    const style = typeof cfg?.style === 'function' ? cfg.style : (): ProgressStyle => styleBase!;
+
+    let width: number;
+    return ev => {
+      const text = ev.value ?? (ev.total ? '%idx/%total' : '%idx');
+      const pct = ev.total === undefined ? 0 : (ev.idx / ev.total);
+      if (ev.total) {
+        width ??= Math.trunc(Math.ceil(Math.log10(ev.total ?? 10000)));
+      }
+      const state: Record<string, string> = { total: `${ev.total}`, idx: `${ev.idx}`.padStart(width ?? 0), pct: `${Math.trunc(pct * 100)}` };
+      const line = text.replace(/[%](idx|total|pct)/g, (_, k) => state[k]);
+      const full = term.writer.padToWidth(line, cfg?.withWaiting ? 2 : 0);
+      const mid = Math.trunc(pct * term.width);
+      const [l, r] = [full.substring(0, mid), full.substring(mid)];
+
+      const { complete, incomplete } = style();
+      return `${cfg?.withWaiting ? `${WAIT_TOKEN} ` : ''}${complete(l)}${incomplete?.(r) ?? r}`;
+    };
+  }
+}