caique/ask

import { ask, projection } from 'caique/ask';

function ask(prompt: BoundPrompt | PromptSpec, io: Io): Promise<Asked>;

function projection(spec: PromptSpec): string;

interface Io {
    reader: Reader;
    writer: Writer;
    /**
     * The run's language for what caique draws itself — the instruction under a list, a problem
     * with an answer, the giving-up line — never the author's question (`localised-human-surfaces`
     * R6). `sayFor(runtime.locale)` from `caique/locale` builds it; absent, it is English.
     */
    say?: (english: string) => string;
}

interface Reader {
    line(options?: ReadOptions): Promise<string | undefined>;
}

interface ReadOptions {
    /**
     * Do not echo what is typed. Set for `password`, and honoured by whatever is reading —
     * this module never sees a terminal, so it cannot hide anything itself, and a widget
     * that never writes back what it read cannot leak it either.
     */
    hidden?: boolean;
}

interface Writer {
    write(text: string): void;
    /**
     * How many columns the terminal behind this writer is, when it knows. Line mode never
     * reads it; the raw renderer does, because a row wider than the terminal occupies more
     * than one row of screen and the repaint has to climb all of them.
     */
    readonly columns?: number | undefined;
    /**
     * How many rows the terminal is, when it knows. The raw renderer windows a list to it, so a
     * list longer than the screen never climbs above the top row on a repaint.
     */
    readonly rows?: number | undefined;
}

type Answer = string | boolean | string[];

type Asked = {
    ok: true;
    value: Answer;
} | {
    ok: false;
    reason: 'cancelled';
};