@syncify/ansi
Version:
ANSI Colors, Symbols and TUI related terminal enchancements for Syncify.
2,219 lines (2,207 loc) • 61.7 kB
text/typescript
import { Ansis } from 'ansis';
export { Ansis } from 'ansis';
import { LiteralUnion } from 'type-fest';
import { Console } from 'node:console';
import update from 'log-update';
export { default as update } from 'log-update';
import { Options } from 'wrap-ansi';
export { default as wrap } from 'wrap-ansi';
/**
* Sanitizes the log message passed. Converts a `Buffer`, `number`, `object`,
* `boolean` or an `array` type to a readable string.
*
* @example
*
* sanitize(true) => 'true'
* sanitize({ x: 1 }) => '{"x":1}'
* sanitize(1000) => '1000'
*/
declare function sanitize(message: number | boolean | string | Buffer | object | any[]): string;
/**
* Detect ANSI Codes
*
* Returns the regex expression or `false`
*
* @param string The string to detect ANSI occurances
* @param option Whether or not to apply `g` flag
*/
declare function detect(string: string, { onlyFirst }?: {
onlyFirst?: boolean;
}): false | RegExpMatchArray;
/**
* Single whitspace characters
*
* ` `
*/
declare const WSP = " ";
/**
* 2 whitspace characters
*
* ` `
*/
declare const WSR = " ";
/**
* Newline Character
*
* `\n`
*/
declare const NWL = "\n";
/**
* 2 Newline Characters
*
* `\n\n`
*/
declare const NLR = "\n\n";
/**
* Empty string
*
* ``
*/
declare const NIL = "";
type Colors = ('cyan' | 'cyanBright' | 'red' | 'redBright' | 'green' | 'greenBright' | 'yellow' | 'yellowBright' | 'magenta' | 'magentaBright' | 'blue' | 'blueBright' | 'white' | 'whiteBright' | 'gray' | 'underline' | 'bold' | 'reset' | 'italic' | 'strike' | 'lightGray' | 'midGray' | 'neonCyan' | 'neonGreen' | 'neonRouge' | 'neonMagenta' | 'neonTeal' | 'orange' | 'pink' | 'teal' | 'brown' | 'lavender');
/**
* Clear console but preserve history
*/
declare const clear = "\u001B[H\u001B[2J";
/**
* Clear console and history
*/
declare const purge = "\u001B[2J\u001B[3J\u001B[H\u001Bc";
declare const cyan: Ansis;
declare const red: Ansis;
declare const green: Ansis;
declare const yellow: Ansis;
declare const magenta: Ansis;
declare const blue: Ansis;
declare const white: Ansis;
declare const gray: Ansis;
declare const dim: Ansis;
declare const cyanBright: Ansis;
declare const redBright: Ansis;
declare const greenBright: Ansis;
declare const yellowBright: Ansis;
declare const magentaBright: Ansis;
declare const blueBright: Ansis;
declare const whiteBright: Ansis;
declare const strip: (s: string) => string;
declare const underline: Ansis;
declare const bold: Ansis;
declare const reset: Ansis;
declare const strikethrough: Ansis;
declare const lightGray: Ansis;
declare const midGray: Ansis;
declare const pink: Ansis;
declare const brown: Ansis;
declare const teal: Ansis;
declare const orange: Ansis;
declare const lavender: Ansis;
declare const neonGreen: Ansis;
declare const neonCyan: Ansis;
declare const neonRouge: Ansis;
declare const neonMagenta: Ansis;
declare const neonTeal: Ansis;
/**
* Terminal Size
*
* Returns the terminal width (columns) and height (rows).
*
* @see https://github.com/sindresorhus/term-size
*/
declare function tsize(): {
wrap: number;
cols: number;
rows: number;
};
/**
* Warning ALT symbol in yellow
*
* ```bash
* ⚠
* ```
*/
declare const WRN: string;
/**
* Letter `v` in small caps
*
* ```bash
* ᴠ
* ```
*/
declare const VER: string;
/**
* Pipe character in gray
*
* ```bash
* |
* ```
*/
declare const PIP: string;
/**
* Hash character in gray
*
* ```bash
* #
* ```
*/
declare const HSH: string;
/**
* Plus character in gray
*
* ```bash
* +
* ```
*/
declare const PLS: string;
/**
* Micro character in gray
*
* ```bash
* µ
* ```
*/
declare const MIC: string;
/**
* Minus character in gray
*
* ```bash
* -
* ```
*/
declare const MIN: string;
/**
* Comma character in gray
*
* ```bash
* ,
* ```
*/
declare const COM: string;
/**
* Checkmark character in neonGreen
*
* ```bash
* ✓
* ```
*/
declare const CHK: string;
/**
* Cross character in redBright
*
* ```bash
* ✕
* ```
*/
declare const BAD: string;
/**
* Colon character in gray
*
* ```bash
* :
* ```
*/
declare const COL: string;
/**
* Right Arrow character in gray
*
* ```bash
* ➔
* ```
*/
declare const ARR: string;
/**
* Right double Chevron character in gray
*
* ```bash
* »
* ```
*/
declare const NXT: string;
/**
* Right Chevron solid character in gray
*
* ```bash
* ➤
* ```
*/
declare const CHV: string;
/**
* Right + Small Left Arrow character in gray
*
* ```bash
* ⥂
* ```
*/
declare const ARL: string;
/**
* Tilde character in gray
*
* ```bash
* ~
* ```
*/
declare const TLD: string;
/**
* Long EnDash character in gray
*
* ```bash
* —
* ```
*/
declare const DSH: string;
/**
* Left Parenthesis in gray
*
* ```bash
* (
* ```
*/
declare const LPR: string;
/**
* Right Parenthesis in gray
*
* ```bash
* )
* ```
*/
declare const RPR: string;
/**
* Left Curly Brace in gray
*
* ```bash
* {
* ```
*/
declare const LCB: string;
/**
* Right Curly Brace in gray
*
* ```bash
* }
* ```
*/
declare const RCB: string;
/**
* Left Square Brace in gray
*
* ```bash
* [
* ```
*/
declare const LSB: string;
/**
* Right Square Brace in gray
*
* ```bash
* ]
* ```
*/
declare const RSB: string;
/**
* Left Angle Brace in gray
*
* ```bash
* <
* ```
*/
declare const LAN: string;
/**
* Right Angle Brace in gray
*
* ```bash
* >
* ```
*/
declare const RAN: string;
/**
* Tree Characters
*/
declare const Tree: {
/**
* Tree Line Top
*
* ```js
* '┌─ ' // appended with 1 spaces
* ```
*/
open: string;
/**
* Tree Line Stub
*
* ```js
* '├ ' // appended with 2 spaces
* ```
*/
stub: string;
/**
* Tree Line Dash
*
* ```js
* '├─ ' // appended with 1 space
* ```
*/
dash: string;
/**
* Tree Line (without suffixed whitespace)
*
* ```js
* '│' // appended with no space
* ```
*/
trim: string;
/**
* Tree Line
*
* ```js
* '│ ' // appended with 2 spaces
* ```
*/
line: string;
/**
* Tree Line Next - (`\n` will prepend)
*
* ```js
* '\n│' // appended with no space
* ```
*/
next: string;
/**
* Tree Line Next - (`\n` will prepend)
*
* ```js
* '│\n'
* '│ ' // appended with 2 spaces
* ```
*/
newline: string;
/**
* Tree Line After - (`\n` will append)
*
* ```js
* '│\n' // appended with no space
* ```
*/
after: string;
/**
* Tree Line Wrap
*
* Newlines and line (i.e: `\n` will prepend and append)
*
* ```js
* '\n│\n' // appended with no space
* ```
*/
wrap: string;
/**
* Tree Line Base
*
* ```js
* '└─' // appended with 1 space
* ```
*/
base: string;
/**
* Tree Line Red (Red Dim)
*
* ```js
* '│ ' // appended with 2 spaces
* ```
*/
red: string;
/**
* Tree Line Red (Red Dim)
*
* ```js
* '│' // appended with no space
* ```
*/
redTrim: string;
/**
* Tree Yello Line Dash
*
* ```js
* '├─ ' // appended with 1 space
* ```
*/
redDash: string;
/**
* Tree Red Line stub
*
* ```js
* '├ ' // appended with 1 space
* ```
*/
redStub: string;
/**
* Tree Line Warning (Yellow Dim)
*
* ```js
* '│ ' // appended with 2 spaces
* ```
*/
yellow: string;
/**
* Tree Line Warning (Yellow Dim)
*
* ```js
* '│' // appended with no space
* ```
*/
yellowTrim: string;
/**
* Tree Yello Line Dash
*
* ```js
* '├─ ' // appended with 1 space
* ```
*/
yellowDash: string;
/**
* Tree Red Line stub
*
* ```js
* '├ ' // appended with 1 space
* ```
*/
yellowStub: string;
/**
* Tree Line Indentation
*
* Symbols used for next level lines
*/
indent: {
/**
* Tree Indent Line Top
*
* ```js
* '├──┬─ ' // appended with 1 space
* ```
*/
edge: string;
/**
* Tree Indent Line Fall
*
* ```js
* '├──┐ ' // appended with 1 space
* ```
*/
fall: string;
/**
* Tree Indent Line
*
* ```js
* '│ │ ' // appended with 1 space
* ```
*/
line: string;
/**
* Tree Indent Line Stub
*
* ```js
* '│ ├ ' // appended with 1 space
* ```
*/
stub: string;
/**
* Tree Indent Line Dash
*
* ```js
* '│ ├─' // appended with 1 space
* ```
*/
dash: string;
/**
* Tree Indent Line Base
*
* ```js
* '│ └─' // appended with 1 space
* ```
*/
base: string;
};
};
/**
* Log Prefixes
*
* The CLI logs will be prefixed with the different naming groups.
* Each prefix name infers an action pertaining to an executed operation.
* Depending on the prefix name character length of the arrow separator
* will equally distributed.
*/
type Prefixes = LiteralUnion<('changed' | 'create' | 'created' | 'creating' | 'delete' | 'deleted' | 'deleting' | 'deletion' | 'elapsed' | 'export' | 'external' | 'failed' | 'failures' | 'ignored' | 'importer' | 'invalid' | 'minified' | 'pending' | 'process' | 'processing' | 'transferred' | 'progress' | 'publish' | 'queued' | 'rejected' | 'reloaded' | 'release' | 'retrying' | 'skipped' | 'syncing' | 'transform' | 'template' | 'updated' | 'updating' | 'uploaded' | 'version' | 'warning'), string>;
/**
* ANSI Prefix
*
* Equally distributes whitespace following the `prefix` parameter.
* Optionally accepts a `suffix[]` string spread. Depending on the number
* of suffix appends passed, different output is produced. When passing
* `3 or 4` suffixes the last known suffix will apply `~` appenditure.
*
* See below examples:
*
* ---
*
* **Passing 0 `suffix` parameters**
*
* ```bash
* │ prefix
* ```
*
* ---
*
* **Passing 1 `suffix` parameter**
*
* ```bash
* │ prefix » action
* ```
* ---
*
* **Passing 2 `suffix` parameters (applies append is timer)**
*
* ```bash
* │ prefix » action → suffix
* │ prefix » action ~ append
* ```
*
* ---
*
* **Passing 3 `suffix` parameters**
*
* ```bash
* │ prefix » action → suffix ~ append
* ```
*
* ---
*
* **Passing 4 `suffix` parameters**
*
* ```bash
* │ prefix » handle ⥂ joiner → action ~ append
* ```
*/
declare function Prefix(name: Prefixes, ...suffix: [
handle?: string,
joiner?: string,
action?: string,
append?: string
]): string;
/**
* Suffix in gray with Tilde `~` prefix
*
* **Examples**
*
* ```bash
* ~ 250ms
* ~ Lorem Ipsum
* ```
*/
declare function Append(input: string): string;
/**
* ANSI Infix
*
* Infixes input with certain characters. Optionally accepts a
* `spaced` value, when provided, the _encase_ will be surrounded
* with a single whitespace character.
*
* **Encase Shortcodes**
*
* - **AN** ~ `<input>`
* - **CB** ~ `{input}`
* - **PR** ~ `(input)`
* - **SB** ~ `[input]`
*
* ---
*
* **Spaced Settings**
*
* Whether or not to encase with single whitespace characters.
* When `true` the `input` and encase character are expressed as:
*
* - `< input >`
* - `{ input }`
* - `( input )`
* - `[ input ]`
*
*/
declare function Encase(encase: 'AN' | 'CB' | 'PR' | 'SB', input: string, { spaced }?: {
spaced?: boolean;
}): string;
declare const Suffix: {
/**
* Warning in yellow stdin suffix with Tilde `~` prefix
*
* ```bash
* ~ Type w and press enter to view
* ```
*/
warning: string;
/**
* Error in red stdin suffix with Tilde `~` prefix
*
* ```bash
* ~ Type v and press enter to view
* ```
*/
error: string;
/**
* Bulk log inspection suffix
*
* ```bash
* ~ Type v and press enter to view
* ```
*/
bulk: string;
/**
* Stack Trace in Gray applied to error contexts
*
* ```bash
* Type s and press enter to view stack trace
* ```
*/
stack: string;
};
/**
* TUI Horizontal Line
*
* Prints a horizontal line separator which will default to
* spanning the `wrap` of the terminal pane.
*
* ```bash
* │\n
* ├────────────────────────────────────────────────
* │
* ```
*/
declare const Ruler: (width?: any, newlines?: boolean) => string;
/**
* Tree Top
*
* ```
* '\n┌─ Label ~ 01:59:20'
* ```
*/
declare function Top(label: string, timestamp?: boolean): string;
type MultilineParams = string[] | [string[], style?: {
color?: Ansis;
line?: string;
}] | [...string[], {
color?: Ansis;
line?: string;
}];
/**
* Tree Multiline
*
* Prefixes a multiline string with tree line but does not respect wrap.
* If a string with newlines is passed, the newline occurance will be
* respected.
*
* > **NOTE**
* >
* > Any extraneous newline applied will be sliced in the result. This
* > means that you need to pass `\n` to the multiline to ensure ending
* > newline applied, e.g, `Multiline('abc\n')`. If multiline string does
* > not include an ending newline one will not be applied.
*
* ```bash
* │ lorem ipsum lorem ipsum\n
* │ lorem ipsum lorem ipsum\n
* │ lorem ipsum lorem ipsum
* ```
*/
declare const Multiline: (...input: MultilineParams) => string;
interface WrapOptions {
/**
* The color of the message
*
* @default null
*/
color?: Ansis;
/**
* The `Tree.line` to apply
*
* @default Tree.line
*/
line?: string;
/**
* Whether or not the first line is to begin like Tree line.
*
* Default behaviour: `{ firstLineTree: true }`
*
* ```js
* '│ lorem ipsum lorem ipsum' // this line begins with │
* '│ lorem ipsum lorem ipsum'
* '│ lorem ipsum lorem ipsum'
* ```
*
* When disabled: `{ firstLineTree: false }`
*
* ```js
* 'lorem ipsum lorem ipsum' // this line does not apply prefix
* '│ lorem ipsum lorem ipsum'
* '│ lorem ipsum lorem ipsum'
* ```
*
* @default true
*/
firstLineTree?: boolean;
}
/**
* Tree Wrap
*
* Accepts `string[]` or `...string[]` spread. The last entry accepts an
* optional **style** config, which can be used to pass in **Ansis** color
* and/or tree line type (e.g: `Tree.red` or `Tree.yellow`). The `line` key
* will default to using `Tree.line` (i.e: _lightGray_) and `color` defaults
* to `null` and will apply according to what was passed.
*
*
* ```
* │ lorem ipsum lorem ipsum
* │ lorem ipsum lorem ipsum
* │ lorem ipsum lorem ipsum
* ```
*/
declare const Wrap: <T extends WrapOptions>(...input: [string[], T?] | (string | T)[]) => string;
/**
* Tree Line Break
*
* ```
* │
* │ input
* │
* ```
*/
declare const Header: (input: string) => string;
/**
* Tree Line Break Red
*
* ```
* │
* │ input
* │
* ```
*/
declare const HeaderRed: (input: string) => string;
/**
* Tree Line Break
*
* ```bash
* │
* │ input
* │
* ```
*/
declare function HeaderYellow(input: string): string;
/**
* Tree Line
*
* ```bash
* │ input
* ```
*/
declare function Line(input: string): string;
/**
* Tree Red Line
*
* ```bash
* │ input
* ```
*/
declare function LineRed(input: string): string;
/**
* Tree Warn Line
*
* ```bash
* │ input
* ```
*/
declare function LineYellow(input: string): string;
/**
* Tree Next Line
*
* ```bash
* │\n
* │ input
* ```
*/
declare function NextLine(input: string): string;
/**
* Tree Line Next
*
* ```bash
* │ input\n
* │
* ```
*/
declare function Next(input: string): string;
/**
* Tree Dash
*
* ```bash
* ├─ input
* ```
*/
declare function Dash(input: string): string;
/**
* Tree End
*
* ```bash
* └─ input\n
* ```
*/
declare function End(input: string, timestamp?: boolean): string;
/**
* Tree Indent Line
*
* ```bash
* │ │ input
* ```
*/
declare function IndentLine(input: string): string;
/**
* Tree Indent Line Dash
*
* ```bash
* │ ├─ input
* ```
*/
declare function IndentDash(input: string): string;
/** Tree Indent Line Dash
*
* ```bash
* │ └─ input\n
* │
* ```
*/
declare function IndentEnd(input: string): string;
/**
* Tree Count up rendered
*
* ```bash
* │ └─ input\n
* │
* ```
*/
declare function CountUp(count?: number, total?: number, color?: Ansis): string;
interface IssueContext {
/**
* The type of context to generate
*
* @default 'error'
*/
type?: 'error' | 'warning';
/**
* Whether or not tree line prefix is to apply
*
* @default true
*/
tree?: boolean;
/**
* The stack trace messages, typically provided by the error.
*
* When `stack` message are passed, they will be prepended above
* the `entries`.
*
* When `true` then stack will be stored in running `$` state
* and made available via stdin input, this will result in a
* stack suffix being appended to the context,
*
* If this value is `false` (or `undefined`) then no stack
* handling is done.
*
* @default false
*/
stack?: boolean | string;
/**
* Whether or not the stack should be cleaned using `cleanStack`
* module. This helps bring sanity to errors, not always a good choice.
*
* > **NOTE**
* >
* > If `stack` is `false` this option is ignored,
*
* @default false
*/
cleanStack?: boolean;
/**
* Context entries - This a collection of `key` > `value`
* pairs to be appended.
*/
entries: {
[name: string]: any;
};
}
/**
* Error and/or Warning context normalizer.
*
* There is special handling for entries with a `failed` key,
* this accepts an array of strings.
*
* **Example**
*
* ```
* │
* │ code: 422
* │ status: Unprocessed Entity
* │ failed: ~source/sections/file.liquid
* │ failed: ~source/sections/file.liquid
* │
* │ Type s and press enter to view stack trace
* ```
*/
declare function Context(data: IssueContext): any;
declare class Log extends Console {
static get stdout(): NodeJS.WriteStream & {
fd: 1;
};
static get stderr(): NodeJS.WriteStream & {
fd: 2;
};
static update: typeof update;
constructor();
write(message: string): void;
info(message: string, color?: Ansis): void;
dash(message: string, color?: Ansis): void;
error(message: string): void;
warn(message: string): void;
header(message: string, color?: Ansis): this;
wrap(...input: (string[] | string | Ansis)[]): this;
tree(type?: LiteralUnion<'red' | 'yellow', string>): this;
break(): this;
}
interface toString {
/**
* Clears the stack. Passing id entries will result in specific stack entries
* being pruned, typically those with track identifiers. This can be used to
* reset only certain stack entries.
*
* - `default: true` when `toString()`
* - `default: false` when `Log()`
*/
clear?: boolean | string | string[];
/**
* Clears specific stack entries, typically those with track
* identifiers. This can be used to reset only certain stack entries.
*
* > Passing `true` to `clear` will override and ignore these references
*/
prune?: string | string[];
/**
* Applies a slice of the current stack. The stack is preserved with
* only the entries starting from the provided index being logged.
*
* @default 0
*/
from?: number;
/**
* Whether or not to disable final `trimEnd()` on the stack entry.
*
* - `default: true` when `toString()`
* - `default: false` when `Log()`
*/
trim?: boolean;
/**
* Wrap the stack in a specific color
*
* @default undefined
*/
color?: Ansis;
}
interface TUIOptions {
/**
* The type of tree message to generate - This will
* default the `Tree.line` to a specific color, meaning
* the `.line()` will be output according to the type.
*
* @default 'info
*/
type?: LiteralUnion<'info' | 'warning' | 'error', string>;
/**
* Optionally provide an existing structure to build from.
*
* @default []
*/
stack?: string[];
/**
* Whether or not tree printing applies
*
* @default true
*/
tree?: boolean;
/**
* @deprecated Use stack instead.
*/
text?: string[];
}
type toStringParam = ([toString?] | [((message: string) => any)] | [toString, ((message: string) => any)]);
interface TemplateOptions<ID = string> {
/**
* An identifier reference for updates. This is **required** and
* must be provided.
*/
id: ID;
/**
* Whether or not the template is hidden. When `true` the template
* message can be assigned but not be added to the stack, instead it
* will lay dormant in the track store until the `Update` method
* is triggered.
*
* @default false
*/
hidden?: boolean;
/**
* The color of the message, this will persist
* across all updated applied, unless overwritten via `Update`
*/
color?: Ansis;
/**
* Whether or not input should apply inline insertion, no Tree
* prefix is applied, content is inserted as-is.
*
* @example
* _.Template('id', { insert: true })
*
* // Assuming the current stack is:
* [ '│ hello' ]
*
* // Later on when calling update, insert will behave like:
* _.Update('id','bar baz qux') => [ '│ hello', 'bar baz qux' ]
*
*/
insert?: boolean;
/**
* Whether or not to apply tree line dash, default to `├─`
*
* @default false
*/
dash?: boolean;
/**
* Whether or not `Update` should use the `id` and pass it to `_.Prefix`
* By default, this will be `false`. Pass a `string` to use instead of
* `id`.
*
* @example
* _.Template('random', { prefix: true })
*
* // Later on when calling update, the output will use the id as prefixer
* _.Update('random', 'a b c') => '│ random → some message'
*/
prefix?: boolean | string;
}
/**
* Terminal User Interface
*
* Static string builder for constructing a console log that
* will be printed to `stdout` or `stderr`. Maintains a stack
* for updates and quick referencing along with methods for
* composing output.
*/
declare class Tui<Templates extends string = string> {
/**
* Maintain Store
*
* Optional store reference used to maintain different TUI
* instances without variable assignment.
*/
static store: Map<string, Tui>;
/**
* CLI Spinner instance
*/
private spin;
/**
* Store ID
*
* When TUI is created with a self-maintaining instance.
* If this value is `null`, variable assignment instance was created.
*
* @default null
*/
private id;
/**
* The type of tree message to generate - This will
* default the `Tree.line` to a specific color, meaning
* the `.line()` will be output according to the type.
*
* > `info`
* >
* > Output will be coloured `white` and Tree lines will be gray.
*
* > `warning`
* >
* > Output will be coloured `yellowBright` and Tree lines will be yellow.
*
* > `error`
* >
* > Output will be coloured `red` and Tree lines will be red.
*
* @default 'info
*/
private type;
/**
* Stack entry track
*
* @default Map
*/
private track;
/**
* The Tree line color based on message type
*
* @default Tree.line
*/
private line;
/**
* The Tree trim color based on message type
*
* @default Tree.trim
*/
private trim;
/**
* The Tree dash color based on message type
*
* @default Tree.dash
*/
private dash;
/**
* The `Tree()` method was called and line changed if `switch` is true. Enable determines render
*/
private tree;
/**
* Optionally provide an existing structure to build from.
*
* @default []
*/
private stack?;
/**
* Lambda functions
*/
private lamdas?;
/**
* Write index reference
*/
private writes?;
/**
* Optional data store
*/
data?: any;
/**
* The log-update instance
*/
private get update();
/**
* Constructor
*/
constructor(options?: TUIOptions & {
id?: string;
});
/**
* Log Output
*
* Writes to `process.stdout` or `process.stderr` or if custom stream was defined.
* Calling this option will apply the following `toString` options:
*
* ```js
* {
* clear: false, // stack will NOT clear when calling toLog()
* trim: false, // trim will NOT apply when calling toLog()
* color: undefined
* }
* ```
*
* **Example Usage**
*
* ```js
* import * as _ from '@syncify/ansi'
*
* // Calling no parameter
* _.Create().Line('foo').Line('bar').toLog()
*
* // Passing a callback function
* _.Create().Line('foo').Line('bar').toLog((message) => {})
*
* // Passing options with callback function
* _.Create().Line('foo').Line('bar').toLog({ clear: true },(message) => {})
* ```
*/
toLog(...input: toStringParam): this;
/**
* Write Output
*
* Can be called multiple times, keeps track of stack index for each
* call and prints from the last known index. This method is different
* from `.toLog()` and `.toUpdate()` in the sense that stack is persisted
* and only new stack entries print.
*
* ```js
* {
* clear: false, // stack will NOT clear when calling toWrite()
* trim: false, // trim will NOT apply when calling toWrite()
* color: undefined
* }
* ```
*
* **Example Usage**
*
* ```js
* import * as _ from '@syncify/ansi'
*
* const write = _.Create();
*
* // Stack: ['│ foo']
* write
* .Line('foo')
* .toWrite() // Logs: │ foo\n
*
* // Stack: ['│ foo\n', '│ bar\n']
* write
* .Line('bar')
* .toWrite() // Logs: │ bar\n
*
* // Stack: ['│ foo\n', '│ bar\n', '│ baz\n']
* write
* .Line('baz')
* .toWrite() // Logs: │ bar\n
* ```
*/
toWrite(params?: Omit<toString, 'from'>): this;
/**
* Generate string with ending line
*
* Applies a `.join` glue to the `this.stack[]`. Unlike other output
* methods, the `toLine` only accepts an {@link Ansis} color.
*
* Calling this option will apply the following `toString` options:
*
* ```js
* {
* clear: true, // stack will be reset
* trim: true, // trim applies because newline line appends
* color: undefined // Applied based on the parameter
* }
* ```
*
* **Example**
*
* ```js
* import * as _ from '@syncify/ansi'
*
* // Calling no parameter
* _.Create().Line('foo').toLine() => '│ foo\n│ bar\n│'
*
* // Passing an ansis color
* _.Create().Line('foo').toLine(_.gray)
* ```
*/
toLine(color?: Ansis): string;
/**
* Log Update
*
* Updates the previous `stdout` using {@link update} module. The
* stack will be preserved and the last write will be removed, updated
* with the current stack.
*
* Calling this option will apply the following `toString` options:
*
* ```js
* {
* clear: false, // stack is preserved by default in toUpdate
* trim: false, // trim is not applied by default in toUpdate
* update: [] // controls log update, accepts ['done', 'clear']
* }
* ```
*
* > The instance of log update is returned, so chaining cannot apply.
*
* **Example Usage**
*
* ```js
* import * as _ from '@syncify/ansi'
*
* // Calling no parameter
* _.Create().Line('foo').toUpdate()
*
* // Controls Log Update
*
* // Calls log.update.done()
* _.Create().Line('foo').toUpdate({ update: ['done'] })
* // Calls log.update.clear() and then log.update.done()
* _.Create().Line('foo').toUpdate({ update: ['clear', 'done'] })
* // Calls log.update.clear()
* _.Create().Line('foo').toUpdate({ update: ['clear'] })
* ```
*/
toUpdate(options?: {
clear?: boolean;
trim?: boolean;
update?: [
'clear',
'done'
] | [
'clear' | 'done'
];
}): this;
/**
* Generate string
*
* Applies a `.join` glue to the `text[]`, returning a string.
* Applies trim any newlines in last entry, clears the `this.stack[]` array
* and `track` Map. The resets can be prevented by passing `{ clear: false }`
* as option. The defaults are as followed:
*
* ```js
* {
* clear: true, // stack will be reset
* trim: true, // trim applies because newline line appends
* color: undefined // Applied based on the parameter
* }
* ```
*/
toString(...input: toStringParam): any;
/**
* Return Structure
*
* Returns the current structure being built.
*
* @example
* _.toStack() => ['│ foo', '│ bar', '│ baz']
*/
toStack(): string[];
/**
* Function Lambda
*
* Tracks a function callback and fires on every call.
*
* @example
* _.Lambda('foo', () => console.label('hello'))
*
* _.Lambda('foo')
*/
Lambda(id: string, callback?: (this: Tui, tui: Tui) => void): this;
/**
* String
*
* Similar to `toString()` but returns instance
*/
String(options: toString, callback: (message: string) => void): this;
/**
* True Conditional
*
* If parameter 1 is `truthy`, parameter to will trigger.
*
* @example
* _.True(foo === false, function(tui) {
*
* // context is parameter
* tui.Line('Hello World')
*
* // this binding applies
* this.Line('Hello World')
* })
*/
True(condition: any, callback: (this: Tui, tui?: Tui) => void): this;
/**
* False Conditional
*
* If parameter 1 is `falsy`, parameter to will trigger.
*
* @example
* _.False(foo === false, function(tui) {
*
* // context is parameter
* tui.Line('Hello World')
*
* // this binding applies
* this.Line('Hello World')
* })
*/
False(condition: any, callback: (this: Tui, tui?: Tui) => void): this;
/**
* Update the newline lines
*
* Allows for the tree lines to be changed, but no modification applies to text.
*/
Tree(tree?: LiteralUnion<'error' | 'warning' | 'info' | 'nil', string>): this;
/**
* Each Iterator
*
* Acccepts a array and callback function.
*
* @example
* _.Each(['foo', 'bar'], item => _.Line(item))
*/
Each<T>(array: T[], callback: (this: Tui, item?: T, index?: number) => void): this;
/**
* Reset stack and track
*
* Empties the `stack[]` and clears the `track` map.
*/
Reset(): void;
/**
* is Empty
*
* Whether or not the message stack is empty
*/
get isEmpty(): boolean;
/**
* is Endline
*
* Whether or not the last item in the stack ends with a newline character
*/
get isEndline(): boolean;
/**
* Get Line
*
* Returns a line at the specific index. Defaults to last known line
*/
Get(at?: string | number): any;
/**
* Track Stack entry
*
* When called, an index in the stack is tracked. The message in the stack
* can then be referenced and updated at a later time using `Update`. If
* the stack is empty, no track applies.
*
* The function **must** be called following a write method and the last known
* entry index in the stack is what is saved. If a tacked reference exists
* with the `id` provided, it will be overwritten.
*
* All tracked references are cleared on `toString` or `toLine`
*/
Template(...input: [
message: string | string[],
options: TemplateOptions<Templates>
] | [
options: TemplateOptions<Templates>
]): this;
/**
* Tree Update
*
* Updates a stack entry at either a `Track()` identifier index or index (depending on `id`)
* parameter `type` provided. The stack will be augmented and updated, at the index provided.
* Passing an `string[]` input will result in spliced insertion.
*
* @example
* // Assuming Template('ref') was called during message creation
*
* // If ref was index 1 in the stack
* _.Update('ref', ['hello', 'world'])
*
* // Before
* ['│ foo\n', '│ bar\n', '│ baz\n']
* // After
* ['│ foo\n', '│ hello\n', '│ world\n', '│ baz\n']
*/
Update(id: Templates, input?: string | string[], newColor?: Ansis): this;
/**
* TUI Spinner
*
* Prints a spinning loading and persists within stack Calling `this.toUpdate()` each interval.
* Can be used with `this.Stop()`. Renders a `Header` entry.
*
* @example
* // Spinner will begin immediately
* _.Line('foo').Spinner('bar')
*
* // Stack input - notice how a header is applied
* ['│ foo\n', '│\n│ ◓ bar\n│\n']
*
* // When we want to stop and clear spinner
* _.Stop()
*/
Spinner(message: string, options?: {
style?: 'spinning' | 'brielle';
color?: Ansis;
indent?: number;
}): this;
/**
* TUI Stop Spinner
*
* When spinner is active, calling this will stop and remove the spinner
* from the stack. Optionally update the spinner value to preserve.
*
* > **NOTE** Passing an update will render as line, not Header
*/
Stop(update?: string, color?: Ansis): this;
/**
* Checks if previous stack entry is tree line and pops it
* if determined to be true.
*/
Trim(): this;
/**
* Remove Line
*
* Removes a line at specific index. Can apply a slice or splice.
* Passing a `deleteCount` value of `Infinity` will slice stack at the index.
*
* @example
* // Assuming the stack contains the following:
* [
* '│ foo',
* '│ bar',
* '│ baz'
* ]
*
* // Calling .remove(0) will remove first index
* [
* '│ bar',
* '│ baz'
* ]
*/
Remove(at: number | string, deleteCount?: number | string): this;
/**
* Mark Stack
*
* Inserts a fake placeholder that is to be removed or replaced at a later time.
* The `track` Map will assign `insert` to `true` to prevent newline line insertion.
*
* @example
* _.Mark('xxx')
*
* // Before
* [ '│ foo', '│ bar' ]
*
* // After
* [ '│ foo', '│ bar', '']
*
* // Later on
* _.Remove('xxx')
*
* // Use Infinity to slice at mark
* _.Remove('xxx', Infinity)
*/
Mark(id: string): this;
/**
* Replace and persist
*
* Replaces an entry at the provided index. Line is prefixed and not required in `input`
*
* @example
* _.Replace(1, 'qux')
*
* // Before
* [ '│ foo', '│ bar', '│ baz' ]
*
* // After
* [ '│ foo', '│ qux', '│ baz' ]
*/
Replace(at: number | string, input: string, color?: Ansis): this;
/**
* Tree Horizontal Line
*
* Prints a horizontal line separator which will default to
* spanning the `wrap` of the terminal pane.
*
* ```bash
* # When Tree is enabled
* │\n
* ├─────────────────────\n
* │\n
*
* # When Tree is disabled
* ──────────────────────\n
* ```
*/
Ruler(width?: number, { noLines }?: {
noLines?: boolean;
}): this;
/**
* Returns the current text index in the stack
*/
get index(): number;
get newlines(): number;
/**
* Tree Newline
*
* Works the same as `Newline()` but is exposed as getter
*
* ```bash
* │\n
* ```
*/
get NL(): this;
/**
* Newline only
*
* Pushed a newline into the stack
*
* ```bash
* \n
* ```
*/
get BR(): this;
/**
* Newline only
*
* Pushes a single `\n` newline into the stack or
* multiple newlines if `repeat` parameter is provided.
*
* ```bash
* \n
* ```
*/
Break(repeat?: number): this;
/**
* Tree Pop
*
* Removes the last entry in the message stack. Accepts
* a number parameter to increase the amount of removals
* to occur.
*
* ```bash
* │\n
* ```
*
* @example
* // Assuming the stack contains the following:
* [
* '│ foo',
* '│ bar',
* '│ baz'
* ]
*
* // Calling .pop() will remove the last entry:
* [
* '│ foo',
* '│ bar'
* ]
*/
Pop(amount?: number): this;
/**
* Tree Newline
*
* Returns a newline, accepts `addLines` parameter that accepts a `number`
* and when provided will generate multiple newlines. In addition (or optionally)
* a `color` can be provided, which expects a valid color string name.
*
* ```bash
* │\n
* ```
*
* ---
*
* **Passing Color**
*
* Passing `Newlines('red')` will a line in red.
*
* ```bash
* │\n
* ```
*
* ---
*
* **Passing Lines and Color**
*
* Passing `Newlines(2, 'red')` will generate the following string in red.
*
* ```bash
* │\n
* │\n
* ```
*/
Newline(addLines?: number | LiteralUnion<'line' | 'red' | 'yellow', string>, color?: LiteralUnion<'red' | 'yellow', string>): this;
/**
* Tree Inline
*
* Appends to the previous entry. If no entries exist in the message, a new one is
* created with tree line prefix.
*
* > Use `Push()` method to insert entry without line prefix.
*
* @example
* _.Inline('baz qux')
*
* // Before
* [ '│ hello', '│ foo bar\n' ]
*
* // After
* [ '│ hello', '│ foo bar baz qux\n' ]
*
* // If the stack is empty, default behaviour applied
*
* // Before
* []
*
* // After
* [ '│ baz qux' ]
*/
Inline(input: string, ...options: [number?, Ansis?] | [Ansis?] | [number?]): this;
/**
* Tree Insert
*
* Pushes input onto the stack, but does not prefix line or append newline.
* Inserts the `input` as is, and accepts an optional `color` function.
*
* @example
* _.Insert('bar baz qux')
*
* // Before
* [ '│ hello', '│ foo' ]
*
* // After
* [ '│ hello', '│ foo', 'bar baz qux' ]
*/
Insert(input: string, color?: Ansis): this;
/**
* Tree Line
*
* Pushes a string onto the message stack. Prefixes with a `│` and
* suffixes with newline `\n`. This is _typically_ the most common method.
*
* ```bash
* │ input\n
* ```
*
* @example
* _.Line('world')
*
* // Before
* [ '│ hello\n' ]
*
* // After
* [ '│ hello\n', '│ world\n' ]
*/
Line(input: string, color?: Ansis): this;
/**
* Tree Prefix
*
* Applies the {@link Prefix} render on a line.
*
* Equally distributes whitespace following the `prefix` parameter.
* Optionally accepts a `suffix[]` string spread. Depending on the number
* of suffix appends passed, different output is produced. When passing
* `3 or 4` suffixes the last known suffix will apply `~` appenditure.
*
* See below examples:
*
* ---
*
* **Passing 0 `suffix` parameters**
*
* ```bash
* │ prefix
* ```
*
* ---
*
* **Passing 1 `suffix` parameter**
*
* ```bash
* │ prefix » action
* ```
* ---
*
* **Passing 2 `suffix` parameters**
*
* ```bash
* │ prefix » action → suffix
* ```
*
* ---
*
* **Passing 3 `suffix` parameters**
*
* ```bash
* │ prefix » action → suffix ~ append
* ```
*
* ---
*
* **Passing 4 `suffix` parameters**
*
* ```bash
* │ prefix » handle ⥂ joiner → action ~ append
* ```
*/
Prefix(label: Prefixes, ...suffix: [
string,
Ansis?
] | [
string,
string,
Ansis?
] | [
string,
string,
string,
Ansis?
] | [
string,
string,
string,
string,
Ansis?
]): this;
/**
* Prepend Line
*
* Pushes a string onto the message stack with a newline line prepended
*
* ```bash
* │\n
* │ input\n
* ```
*
* @example
* _.Prepend('world')
*
* // Before
* [ '│ hello\n' ]
*
* // After
* [ '│ hello\n', '│\n│ world\n' ]
*/
Prepend(input: string, color?: Ansis): this;
/**
* Append Line
*
* Pushes a string onto the message stack. Appended with a newline line `│` and
* suffixes with newline `\n`.
*
* ```bash
* │ input\n
* │\n
* ```
*
* @example
* _.Append('world')
*
* // Before
* [ '│ hello\n' ]
*
* // After
* [ '│ hello\n', '│ world\n│\n' ]
*/
Append(input: string, color?: Ansis): this;
/**
* Tree Error Line (red)
*
* Same as `Line()` but tree line suffix is `red`
*
* ```bash
* │ input\n
* ```
*/
Error(input: string, color?: Ansis): this;
/**
* Tree Warn Line (yellow)
*
* Same as `Line()` but tree line suffix is `yellow`
*
* ```bash
* │ input\n
* ```
*/
Warn(input: string, color?: Ansis): this;
/**
* Tree Line Break
*
* Appends and Prepends newlines, effectively wrapping the `input` in
* paragraphical format.
*
* ```js
* // When tree is enabled
* │\n
* │ input\n
* │\n
*
* // When tree is disabled
* \n
* input\n
* \n
* ```
*/
Header(message: string, color?: Ansis): this;
/**
* Tree Top
*
* ```
* '\n┌─ Label ~ 01:59:20\n'
* ```
*/
Top(label: string, timestamp?: boolean): this;
/**
* Tree End
*
* Returns a tree ender with optional timestamp suffix appended.
* Timestamp suffix defaults to `true` and will be applied.
*
* ```js
* '└─ input ~ 01:59:20\n' // Passing true to timestamp (default)
* // OR
* '└─ input\n' // Passing false to timestamp
* ```
*/
End(input: string, timestamp?: boolean): this;
/**
* Tree Context
*
* Accepts a contextual model. The context will be parsed and
* pushed onto the stack.
*
* ```
* │
* │ code: 422
* │ file: ~source/dir/filename.liquid
* │ status: Unprocessed Entity
* │
* │ Type s and press enter to view stack trace
* ```
*/
Context(data: IssueContext): this;
/**
* Tree Dash
*
* Applies prefixed tree dash to input
*
* ```js
* // When tree is enabled
* ├─ input\n
*
* // When tree is disabled
* — input\n
* ```
*/
Dash(input: string, color?: Ansis): this;
/**
* Tree Multiline
*
* Prefixes a multiline string with tree line. This method does
* not apply wrap, but instead applies a `.split('\n')` on string
* input (if single string is passed). The method accepts `...string`
* spread or `string[]` parameter value.
*
* ```
* │ lorem ipsum lorem ipsum\n
* │ lorem ipsum lorem ipsum\n
* │ lorem ipsum lorem ipsum\n
* ```
*
* @example
* // Passing a string with newlines
* _.Multline('hello\nworld') => [ '│ hello\n', '│ world\n' ]
*
* // Passing an array of strings
* _.Multline(['hello', 'world']) => [ '│ hello\n', '│ world\n' ]
*
* // Passing a spread
* _.Multline('hello', 'world') => [ '│ hello\n', '│ world\n' ]
*/
Multiline(...input: [string[]] | string[]): this;
/**
* Tree Unshift
*
* Inserts a string onto the message stack at index `0`. Prefixes with a `│` and
* suffixes with newline `\n`.
*
* > If `type` is `error` or `warning` and you want to prevent the red or yellow
* color highlighting, then pass a value of `null` to color parameter.
*
* ```bash
* │ input\n
* ```
*
* @example
* _.Unshift('world', 0)
*
* // Before
* [ '│ hello\n' ]
*
* // After
* ['│ world\n', '│ hello\n' ]
*/
Unshift(input: string, color?: Ansis): this;
/**
* Tree Wrap
*
* Accepts `string[]` or `...string[]` spread. The last entry accepts an
* optional Ansis color. The **input** will be passed to {@link Wrap} and the
* returning output will end with newline.
*
* ```
* │ lorem ipsum lorem ipsum\n
* │ lorem ipsum lorem ipsum\n
* │ lorem ipsum lorem ipsum\n
* ```
*/
Wrap(...input: (string[] | string | Ansis | ((message: string) => string))[]): this;
}
type CreateParams = [id: string, options?: TUIOptions] | [options?: TUIOptions];
/**
* Create a TUI Instance
*
* ```bash
* ┌─
* │
* ├─
* │
* └─
* ```
*/
declare function Create<Templates extends string>(...params: CreateParams): Tui<string>;
/**
* Create Self-Maintained TUI Instance
*
* ```bash
* ┌─
* │
* ├─
* │
* └─
* ```
*/
declare function TUI(id: string): Tui<string>;
interface Progress {
/**
* Increment progress
*
* @param incrementBy Defaults to `1`
*/
increment: (incrementBy?: number) => void;
/**
* Reset the `total` and percentage to `0`
*
* @param newTotal Defaults to `undefined`
*/
reset: (newTotal?: number) => void;
/**
* Decrement progress
*
* @param decrementBy Defaults to `1`
*/
decrement: (decrementBy?: number) => void;
/**
* Render the progress bar - Returns the string for console.
*
* Optionally provide a percentage color
*
* @returns string
*/
render: (percentColor?: Ansis) => string;
/**
* Stops progress and clears console
*/
stop: () => void;
/**
* Returns the current percentage completion
*/
get percent(): number;
}
/**
* Progress Rendering Options
*/
interface ProgressOptions {
/**
* Whether or not percentage should be appended.
*
* ---
*
* ```bash
*
* # true (default)
* ▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱ 50%
*
* # false
* ▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱
*
* ```
*
* @default true
*/
showPercentage?: boolean;
/**
* Accepts a {@link Tree} line prefix on text to prepend. Can be `null`
*
* @default
* '│ ' // appended with 2 spaces
*/
prepend?: string;
/**
* The color of the percentage number. If `showPercentage`
* is disabled (`false`) then this option will be ignored.
*
* @default 'whiteBright'
*/
percentColor?: Colors;
/**
* The progress bar color. By default, empty progress characters
* will apply `lightGray`.
*
* @default 'neonGreen'
*/
barColor?: Colors;
/**
* The progress bar width. By default, progress bars will be
* set to 40 columns.
*
* @default 40
*/
barSize?: number;
/**
* Whether or not console should be cleared upon progress completion
*
* @default false
*/
clearOnComplete?: boolean;
}
/**
* CLI Progress
*
* Renders a progress bar to the terminal and returns incremental/decrement
* methods for controlling the progress amount.
*
* @param total The progress to amount
* @param opts The progress options
*
*
* ```bash
*
* # EXAMPLE
*
* ▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱ 50%
*
* ```
*/
declare function progress(total: number, opts?: ProgressOptions): Progress;
type SpinnerStyles = 'brielle' | 'arrows' | 'spinning';
interface SpinnerOptions {
/**
* Whether or not a line prefix is applied
*
* @default true
* @example │ ⠋
*/
line?: boolean;
/**
* An actionable spinner renders differently and will impose
* an arrows spinner style.
*
* **Examples**
*
* ```bash
* # when input param is passed
* │ input → before ▹▹▹▹▹ after
*
* # when input param is omitted
* │ before ▹▹▹▹▹ after
*
* ```
*
* @default null
*/
action?: {
/**
* The arrows loading color, if `color` is passed it will inherit,
* otherwise when set to defaults, it uses `neonGreen`
*
* @default 'neonGreen'
*/
color?: Ansis;
/**
* The before label
*
* ```bash
* before ▹▹▹▹▹
* ```
*/
before: string;
/**
* The after label
*