flagstaff 0.0.1 → 0.1.0

package/dist/ora.d.ts

@@ -0,0 +1,82 @@
+export interface SpinnerDefinition {
+    interval?: number;
+    frames: string[];
+}
+/** Every spinner cli-spinners ships, unedited — ora re-exports it and so do we. */
+export declare const spinners: Record<string, SpinnerDefinition>;
+export type Color = 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white' | 'gray';
+/** What ora writes to: `process.stderr` by default, anything stream-shaped in a test. */
+export interface OraStream {
+    write(chunk: string, encoding?: unknown, callback?: unknown): boolean;
+    isTTY?: boolean;
+    columns?: number;
+    rows?: number;
+    cursorTo?(x: number): unknown;
+    moveCursor?(dx: number, dy: number): unknown;
+    clearLine?(direction: number): unknown;
+    once?(event: string, listener: () => void): unknown;
+    removeListener?(event: string, listener: () => void): unknown;
+}
+/** A prefix or suffix, resolved on every frame when it is a function. */
+export type Affix = string | (() => string);
+export interface Options {
+    text?: string;
+    prefixText?: Affix;
+    suffixText?: Affix;
+    spinner?: SpinnerDefinition | string;
+    color?: Color | false;
+    hideCursor?: boolean;
+    indent?: number;
+    interval?: number | undefined;
+    stream?: OraStream;
+    isEnabled?: boolean;
+    isSilent?: boolean;
+    discardStdin?: boolean;
+}
+export interface PersistOptions {
+    symbol?: string;
+    text?: string;
+    prefixText?: Affix;
+    suffixText?: Affix;
+}
+export interface PromiseOptions<T> extends Options {
+    successText?: string | ((result: T) => string);
+    failText?: string | ((error: unknown) => string);
+    successSymbol?: string;
+    failSymbol?: string;
+}
+export declare class Ora {
+    #private;
+    constructor(options?: Options | string);
+    get indent(): number;
+    set indent(indent: number | undefined);
+    get interval(): number;
+    get spinner(): SpinnerDefinition;
+    set spinner(spinner: SpinnerDefinition | string | undefined);
+    get text(): string;
+    set text(value: string | undefined);
+    get prefixText(): Affix;
+    set prefixText(value: Affix | undefined);
+    get suffixText(): Affix;
+    set suffixText(value: Affix | undefined);
+    get isSpinning(): boolean;
+    get color(): Color | false | undefined;
+    set color(value: Color | false | undefined);
+    get isEnabled(): boolean;
+    set isEnabled(value: boolean);
+    get isSilent(): boolean;
+    set isSilent(value: boolean);
+    frame(): string;
+    clear(): this;
+    render(): this;
+    start(text?: string): this;
+    stop(): this;
+    succeed(text?: string): this;
+    fail(text?: string): this;
+    warn(text?: string): this;
+    info(text?: string): this;
+    stopAndPersist(options?: PersistOptions): this;
+}
+export default function ora(options?: Options | string): Ora;
+/** Run an action under a spinner, and land on the right symbol whichever way it ends. */
+export declare function oraPromise<T>(action: Promise<T> | ((spinner: Ora) => Promise<T>), options?: PromiseOptions<T> | string): Promise<T>;

package/dist/ora.js

@@ -0,0 +1,515 @@
+import { Buffer } from 'node:buffer';
+import process from 'node:process';
+import chalk from 'roundel/chalk';
+import { HIDE_CURSOR, restoreCursorOnExit, SHOW_CURSOR } from './cursor.js';
+import spinnerCorpus from './spinners.json' with { type: 'json' };
+import { lineCount } from './width.js';
+export const spinners = spinnerCorpus;
+function isUnicodeSupported() {
+    const { env } = process;
+    const { TERM, TERM_PROGRAM } = env;
+    if (process.platform !== 'win32')
+        return TERM !== 'linux';
+    return (Boolean(env['WT_SESSION']) ||
+        Boolean(env['TERMINUS_SUBLIME']) ||
+        env['ConEmuTask'] === '{cmd::Cmder}' ||
+        TERM_PROGRAM === 'Terminus-Sublime' ||
+        TERM_PROGRAM === 'vscode' ||
+        TERM === 'xterm-256color' ||
+        TERM === 'alacritty' ||
+        TERM === 'rxvt-unicode' ||
+        TERM === 'rxvt-unicode-256color' ||
+        env['TERMINAL_EMULATOR'] === 'JetBrains-JediTerm');
+}
+function isInteractive(stream) {
+    return Boolean(stream?.isTTY) && process.env['TERM'] !== 'dumb' && !('CI' in process.env);
+}
+const UNICODE = isUnicodeSupported();
+const logSymbols = {
+    info: chalk.blue(UNICODE ? 'ℹ' : 'i'),
+    success: chalk.green(UNICODE ? '✔' : '√'),
+    warning: chalk.yellow(UNICODE ? '⚠' : '‼'),
+    error: chalk.red(UNICODE ? '✖' : '×'),
+};
+const ASCII_ETX_CODE = 0x03;
+class StdinDiscarder {
+    #activeCount = 0;
+    #stdin;
+    #stdinWasPaused = false;
+    #stdinWasRaw = false;
+    #handleInput = (chunk) => {
+        const length = chunk?.length;
+        if (length === undefined || length === 0)
+            return;
+        const code = typeof chunk === 'string' ? chunk.codePointAt(0) : chunk[0];
+        if (code === ASCII_ETX_CODE)
+            process.kill(process.pid, 'SIGINT');
+    };
+    start() {
+        this.#activeCount += 1;
+        if (this.#activeCount === 1)
+            this.#realStart();
+    }
+    stop() {
+        if (this.#activeCount === 0)
+            return;
+        this.#activeCount -= 1;
+        if (this.#activeCount === 0)
+            this.#realStop();
+    }
+    #realStart() {
+        const stdin = process.stdin;
+        if (process.platform === 'win32' || stdin?.isTTY !== true || typeof stdin.setRawMode !== 'function') {
+            this.#stdin = undefined;
+            return;
+        }
+        this.#stdin = stdin;
+        this.#stdinWasPaused = stdin.isPaused();
+        this.#stdinWasRaw = Boolean(stdin.isRaw);
+        stdin.setRawMode(true);
+        stdin.prependListener('data', this.#handleInput);
+        if (this.#stdinWasPaused)
+            stdin.resume();
+    }
+    #realStop() {
+        const stdin = this.#stdin;
+        if (stdin === undefined)
+            return;
+        stdin.off('data', this.#handleInput);
+        if (stdin.isTTY === true)
+            stdin.setRawMode?.(this.#stdinWasRaw);
+        if (this.#stdinWasPaused)
+            stdin.pause();
+        this.#stdin = undefined;
+        this.#stdinWasPaused = false;
+        this.#stdinWasRaw = false;
+    }
+}
+const stdinDiscarder = new StdinDiscarder();
+const RENDER_DEFERRAL_TIMEOUT = 200;
+const SYNCHRONIZED_OUTPUT_ENABLE = '\u001B[?2026h';
+const SYNCHRONIZED_OUTPUT_DISABLE = '\u001B[?2026l';
+const FALLBACK_INTERVAL = 100;
+const DEFAULT_COLUMNS = 80;
+const TRUNCATION_RESERVE = 1;
+const activeHooksPerStream = new Map();
+const validColors = new Set(['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white', 'gray']);
+function paint(color, text) {
+    if (color === undefined || color === false)
+        return text;
+    return chalk[color]?.(text) ?? text;
+}
+export class Ora {
+    #linesToClear = 0;
+    #frameIndex = -1;
+    #lastFrameTime = 0;
+    #options;
+    #spinner;
+    #stream;
+    #id;
+    #hookedStreams = new Map();
+    #isInternalWrite = false;
+    #drainHandler;
+    #deferRenderTimer;
+    #isDiscardingStdin = false;
+    #color;
+    constructor(options) {
+        const given = typeof options === 'string' ? { text: options } : options;
+        this.#options = { color: 'cyan', stream: process.stderr, discardStdin: true, hideCursor: true, isEnabled: false, isSilent: false, indent: 0, ...given };
+        this.color = this.#options.color;
+        this.#stream = this.#options.stream;
+        if (typeof given?.isEnabled !== 'boolean')
+            this.#options.isEnabled = isInteractive(this.#stream);
+        if (typeof given?.isSilent !== 'boolean')
+            this.#options.isSilent = false;
+        if (this.#options.interval !== undefined && !(Number.isInteger(this.#options.interval) && this.#options.interval > 0)) {
+            throw new Error('The `interval` option must be a positive integer');
+        }
+        const userInterval = this.#options.interval;
+        this.spinner = this.#options.spinner;
+        this.#options.interval = userInterval;
+        this.text = this.#options.text;
+        this.prefixText = this.#options.prefixText;
+        this.suffixText = this.#options.suffixText;
+        this.indent = this.#options.indent;
+        if (process.env['NODE_ENV'] === 'test')
+            this.#exposeTestProperties();
+    }
+    #exposeTestProperties() {
+        const self = this;
+        self['_stream'] = this.#stream;
+        self['_isEnabled'] = this.#options.isEnabled;
+        Object.defineProperty(this, '_linesToClear', {
+            get: () => this.#linesToClear,
+            set: (value) => {
+                this.#linesToClear = value;
+            },
+        });
+        Object.defineProperty(this, '_frameIndex', { get: () => this.#frameIndex });
+        Object.defineProperty(this, '_lineCount', {
+            get: () => {
+                const columns = this.#stream.columns ?? DEFAULT_COLUMNS;
+                const prefixText = typeof this.#options.prefixText === 'function' ? '' : this.#options.prefixText;
+                const suffixText = typeof this.#options.suffixText === 'function' ? '' : this.#options.suffixText;
+                const fullPrefixText = typeof prefixText === 'string' && prefixText !== '' ? `${prefixText} ` : '';
+                const fullSuffixText = typeof suffixText === 'string' && suffixText !== '' ? ` ${suffixText}` : '';
+                const text = typeof this.#options.text === 'string' ? ` ${this.#options.text}` : '';
+                return lineCount(`${' '.repeat(this.#options.indent)}${fullPrefixText}-${text}${fullSuffixText}`, columns);
+            },
+        });
+    }
+    get indent() {
+        return this.#options.indent;
+    }
+    set indent(indent) {
+        const value = indent === undefined ? 0 : indent;
+        if (!(value >= 0 && Number.isInteger(value)))
+            throw new Error('The `indent` option must be an integer from 0 and up');
+        this.#options.indent = value;
+    }
+    get interval() {
+        return this.#options.interval ?? this.#spinner.interval ?? FALLBACK_INTERVAL;
+    }
+    get spinner() {
+        return this.#spinner;
+    }
+    set spinner(spinner) {
+        this.#frameIndex = -1;
+        this.#options.interval = undefined;
+        if (typeof spinner === 'object') {
+            if (!Array.isArray(spinner.frames) || spinner.frames.length === 0 || spinner.frames.some((frame) => typeof frame !== 'string')) {
+                throw new Error('The given spinner must have a non-empty `frames` array of strings');
+            }
+            if (spinner.interval !== undefined && !(Number.isInteger(spinner.interval) && spinner.interval > 0)) {
+                throw new Error('`spinner.interval` must be a positive integer if provided');
+            }
+            this.#spinner = spinner;
+            return;
+        }
+        const named = spinner === undefined || spinner === 'default' ? undefined : spinners[spinner];
+        if (!isUnicodeSupported())
+            this.#spinner = spinners['line'];
+        else if (spinner === undefined)
+            this.#spinner = spinners['dots'];
+        else if (named !== undefined)
+            this.#spinner = named;
+        else
+            throw new Error(`There is no built-in spinner named '${spinner}'. See https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json for a full list.`);
+    }
+    get text() {
+        return this.#options.text;
+    }
+    set text(value) {
+        this.#options.text = value === undefined ? '' : value;
+    }
+    get prefixText() {
+        return this.#options.prefixText;
+    }
+    set prefixText(value) {
+        this.#options.prefixText = value === undefined ? '' : value;
+    }
+    get suffixText() {
+        return this.#options.suffixText;
+    }
+    set suffixText(value) {
+        this.#options.suffixText = value === undefined ? '' : value;
+    }
+    get isSpinning() {
+        return this.#id !== undefined;
+    }
+    get color() {
+        return this.#color;
+    }
+    set color(value) {
+        if (value !== undefined && value !== false && !validColors.has(value))
+            throw new Error('The `color` option must be a valid color or `false` to disable');
+        this.#color = value;
+    }
+    get isEnabled() {
+        return this.#options.isEnabled && !this.#options.isSilent;
+    }
+    set isEnabled(value) {
+        if (typeof value !== 'boolean')
+            throw new TypeError('The `isEnabled` option must be a boolean');
+        this.#options.isEnabled = value;
+    }
+    get isSilent() {
+        return this.#options.isSilent;
+    }
+    set isSilent(value) {
+        if (typeof value !== 'boolean')
+            throw new TypeError('The `isSilent` option must be a boolean');
+        this.#options.isSilent = value;
+    }
+    frame() {
+        const now = Date.now();
+        if (this.#frameIndex === -1 || now - this.#lastFrameTime >= this.interval) {
+            this.#frameIndex = (this.#frameIndex + 1) % this.#spinner.frames.length;
+            this.#lastFrameTime = now;
+        }
+        const frame = paint(this.#color, this.#spinner.frames[this.#frameIndex] ?? '');
+        const text = typeof this.#options.text === 'string' ? ` ${this.#options.text}` : '';
+        return this.#fullPrefixText() + frame + text + this.#fullSuffixText();
+    }
+    clear() {
+        if (!this.isEnabled || this.#stream.isTTY !== true)
+            return this;
+        this.#internalWrite(() => {
+            this.#stream.cursorTo?.(0);
+            for (let index = 0; index < this.#linesToClear; index += 1) {
+                if (index > 0)
+                    this.#stream.moveCursor?.(0, -1);
+                this.#stream.clearLine?.(1);
+            }
+            if (this.#options.indent)
+                this.#stream.cursorTo?.(this.#options.indent);
+            return undefined;
+        });
+        this.#linesToClear = 0;
+        return this;
+    }
+    render() {
+        if (!this.isEnabled || this.#drainHandler || this.#deferRenderTimer)
+            return this;
+        const useSynchronizedOutput = this.#stream.isTTY === true;
+        let shouldDisableSynchronizedOutput = false;
+        try {
+            if (useSynchronizedOutput) {
+                this.#internalWrite(() => this.#stream.write(SYNCHRONIZED_OUTPUT_ENABLE));
+                shouldDisableSynchronizedOutput = true;
+            }
+            this.clear();
+            let frameContent = this.frame();
+            const columns = this.#stream.columns ?? DEFAULT_COLUMNS;
+            const actualLineCount = lineCount(frameContent, columns);
+            const consoleHeight = this.#stream.rows;
+            if (consoleHeight !== undefined && consoleHeight > 1 && actualLineCount > consoleHeight) {
+                const lines = frameContent.split('\n');
+                frameContent = [...lines.slice(0, consoleHeight - TRUNCATION_RESERVE), '... (content truncated to fit terminal)'].join('\n');
+            }
+            const canContinue = this.#internalWrite(() => this.#stream.write(frameContent));
+            if (canContinue === false && this.#stream.isTTY === true) {
+                this.#drainHandler = () => {
+                    this.#drainHandler = undefined;
+                    this.#tryRender();
+                };
+                this.#stream.once?.('drain', this.#drainHandler);
+            }
+            this.#linesToClear = lineCount(frameContent, columns);
+        }
+        finally {
+            if (shouldDisableSynchronizedOutput)
+                this.#internalWrite(() => this.#stream.write(SYNCHRONIZED_OUTPUT_DISABLE));
+        }
+        return this;
+    }
+    start(text) {
+        if (text !== undefined)
+            this.text = text;
+        if (this.isSilent)
+            return this;
+        if (!this.isEnabled) {
+            const symbol = this.text ? '-' : '';
+            const line = ' '.repeat(this.#options.indent) + this.#buildOutputLine(symbol, this.text, this.#options.prefixText, this.#options.suffixText);
+            if (line.trim() !== '')
+                this.#internalWrite(() => this.#stream.write(`${line}\n`));
+            return this;
+        }
+        if (this.isSpinning)
+            return this;
+        if (this.#options.hideCursor)
+            this.#hideCursor();
+        if (this.#options.discardStdin && process.stdin.isTTY) {
+            stdinDiscarder.start();
+            this.#isDiscardingStdin = true;
+        }
+        this.#installHook();
+        this.render();
+        this.#id = setInterval(this.render.bind(this), this.interval);
+        return this;
+    }
+    stop() {
+        clearInterval(this.#id);
+        this.#id = undefined;
+        this.#frameIndex = -1;
+        this.#lastFrameTime = 0;
+        this.#clearRenderDeferral();
+        this.#uninstallHook();
+        if (this.#drainHandler) {
+            this.#stream.removeListener?.('drain', this.#drainHandler);
+            this.#drainHandler = undefined;
+        }
+        if (this.isEnabled) {
+            this.clear();
+            if (this.#options.hideCursor)
+                this.#showCursor();
+        }
+        if (this.#isDiscardingStdin) {
+            this.#isDiscardingStdin = false;
+            stdinDiscarder.stop();
+        }
+        return this;
+    }
+    succeed(text) {
+        return this.stopAndPersist({ symbol: logSymbols.success, ...(text === undefined ? {} : { text }) });
+    }
+    fail(text) {
+        return this.stopAndPersist({ symbol: logSymbols.error, ...(text === undefined ? {} : { text }) });
+    }
+    warn(text) {
+        return this.stopAndPersist({ symbol: logSymbols.warning, ...(text === undefined ? {} : { text }) });
+    }
+    info(text) {
+        return this.stopAndPersist({ symbol: logSymbols.info, ...(text === undefined ? {} : { text }) });
+    }
+    stopAndPersist(options = {}) {
+        if (this.isSilent)
+            return this;
+        const symbol = options.symbol ?? ' ';
+        const text = options.text ?? this.text;
+        const prefixText = options.prefixText ?? this.#options.prefixText;
+        const suffixText = options.suffixText ?? this.#options.suffixText;
+        const textToWrite = `${this.#buildOutputLine(symbol, text, prefixText, suffixText)}\n`;
+        this.stop();
+        this.#internalWrite(() => this.#stream.write(textToWrite));
+        return this;
+    }
+    #internalWrite(fn) {
+        this.#isInternalWrite = true;
+        try {
+            return fn();
+        }
+        finally {
+            this.#isInternalWrite = false;
+        }
+    }
+    #tryRender() {
+        if (this.isSpinning)
+            this.render();
+    }
+    #hideCursor() {
+        if (this.#stream.isTTY !== true)
+            return;
+        restoreCursorOnExit();
+        this.#stream.write(HIDE_CURSOR);
+    }
+    #showCursor() {
+        if (this.#stream.isTTY !== true)
+            return;
+        this.#stream.write(SHOW_CURSOR);
+    }
+    #formatAffix(value, separator, placeBefore) {
+        const resolved = typeof value === 'function' ? value() : value;
+        if (typeof resolved === 'string' && resolved !== '')
+            return placeBefore ? separator + resolved : resolved + separator;
+        return '';
+    }
+    #fullPrefixText(prefixText = this.#options.prefixText, postfix = ' ') {
+        return this.#formatAffix(prefixText, postfix, false);
+    }
+    #fullSuffixText(suffixText = this.#options.suffixText, prefix = ' ') {
+        return this.#formatAffix(suffixText, prefix, true);
+    }
+    #buildOutputLine(symbol, text, prefixText, suffixText) {
+        const separator = symbol ? ' ' : '';
+        const fullText = typeof text === 'string' ? separator + text : '';
+        return this.#fullPrefixText(prefixText, ' ') + symbol + fullText + this.#fullSuffixText(suffixText, ' ');
+    }
+    #scheduleRenderDeferral() {
+        if (this.#deferRenderTimer)
+            return;
+        this.#deferRenderTimer = setTimeout(() => {
+            this.#deferRenderTimer = undefined;
+            if (this.isSpinning)
+                this.#tryRender();
+        }, RENDER_DEFERRAL_TIMEOUT);
+        this.#deferRenderTimer.unref?.();
+    }
+    #clearRenderDeferral() {
+        if (this.#deferRenderTimer) {
+            clearTimeout(this.#deferRenderTimer);
+            this.#deferRenderTimer = undefined;
+        }
+    }
+    #installHook() {
+        if (!this.isEnabled || this.#hookedStreams.size > 0)
+            return;
+        for (const stream of new Set([this.#stream, process.stdout, process.stderr]))
+            this.#hookStream(stream);
+    }
+    #hookStream(stream) {
+        if (!stream || this.#hookedStreams.has(stream) || stream.isTTY !== true || typeof stream.write !== 'function')
+            return;
+        if (activeHooksPerStream.has(stream)) {
+            console.warn('[ora] Multiple concurrent spinners detected. This may cause visual corruption. Use one spinner at a time.');
+        }
+        const originalWrite = stream.write;
+        this.#hookedStreams.set(stream, originalWrite);
+        activeHooksPerStream.set(stream, this);
+        stream.write = (chunk, encoding, callback) => this.#hookedWrite(stream, originalWrite, chunk, encoding, callback);
+    }
+    #uninstallHook() {
+        for (const [stream, originalWrite] of this.#hookedStreams) {
+            stream.write = originalWrite;
+            if (activeHooksPerStream.get(stream) === this)
+                activeHooksPerStream.delete(stream);
+        }
+        this.#hookedStreams.clear();
+    }
+    #hookedWrite(stream, originalWrite, chunk, encoding, callback) {
+        const [enc, cb] = typeof encoding === 'function' ? [undefined, encoding] : [encoding, callback];
+        if (this.#isInternalWrite)
+            return originalWrite.call(stream, chunk, enc, cb);
+        this.clear();
+        const chunkString = stringifyChunk(chunk, enc);
+        const terminatesLine = chunkString.endsWith('\n') || chunkString.endsWith('\r');
+        const writeResult = originalWrite.call(stream, chunk, enc, cb);
+        if (terminatesLine)
+            this.#clearRenderDeferral();
+        else if (chunkString.length > 0)
+            this.#scheduleRenderDeferral();
+        if (this.isSpinning && !this.#deferRenderTimer)
+            this.render();
+        return writeResult;
+    }
+}
+function stringifyChunk(chunk, encoding) {
+    if (chunk === undefined || chunk === null)
+        return '';
+    if (typeof chunk === 'string')
+        return chunk;
+    if (Buffer.isBuffer(chunk) || ArrayBuffer.isView(chunk)) {
+        const normalized = typeof encoding === 'string' && encoding !== '' && encoding !== 'buffer' ? encoding : 'utf8';
+        return Buffer.from(chunk).toString(normalized);
+    }
+    return String(chunk);
+}
+export default function ora(options) {
+    return new Ora(options);
+}
+export async function oraPromise(action, options) {
+    const actionIsFunction = typeof action === 'function';
+    const actionIsPromise = typeof action?.then === 'function';
+    if (!actionIsFunction && !actionIsPromise)
+        throw new TypeError('Parameter `action` must be a Function or a Promise');
+    const settings = typeof options === 'object' && options !== null ? options : {};
+    const { successText, failText, successSymbol, failSymbol } = settings;
+    const spinner = ora(options).start();
+    try {
+        const result = await (actionIsFunction ? action(spinner) : action);
+        const text = successText === undefined ? undefined : typeof successText === 'string' ? successText : successText(result);
+        if (successSymbol === undefined)
+            spinner.succeed(text);
+        else
+            spinner.stopAndPersist({ symbol: successSymbol, ...(text === undefined ? {} : { text }) });
+        return result;
+    }
+    catch (error) {
+        const text = failText === undefined ? undefined : typeof failText === 'string' ? failText : failText(error);
+        if (failSymbol === undefined)
+            spinner.fail(text);
+        else
+            spinner.stopAndPersist({ symbol: failSymbol, ...(text === undefined ? {} : { text }) });
+        throw error;
+    }
+}