caique
API reference

caique/clack

Every export of caique/clack, with its signature and doc comment: CANCEL_SYMBOL, formatInstructionFooter, isCancel, isCI, isTTY, MULTISELECT_INSTRUCTIONS and 54 more, plus 26 types.

caique/clack — @clack/prompts' API on caique's own engine: its twelve prompts, its writers, its symbols and its settings, under the names clack gives them.

Read this before reading the compatibility number

@clack/prompts' own suite is 606 cases, and 289 of its 444 assertions are toMatchSnapshot(), spread across 17 of its 19 files. Those seventeen files grade clack's exact frames — every bar, every colour, every cursor move — and they stay subtracted from the row by D-001: agreeing with them byte for byte would mean copying clack's renderer, which is not what a drop-in owes a caller.

What is left is seventeen cases in two files, and this module passes sixteen:

  • limit-options.test.ts, 14 cases — the sliding window a list draws through (clack-limit.ts).
  • guide.test.ts, 3 cases — all twelve prompts render the same grey guide, and none renders one when withGuide is false. Until D-152 this module exported only limitOptions, and the first two were written off as "the drawing"; they are not — they grade that the twelve prompts exist, take clack's options and streams, cancel on escape and draw clack's layout, which is the whole of what a caller migrating a prompt needs. They pass now.
  • The third, no prompt renders a guide when withGuide is globally false, calls updateSettings imported from @clack/core and asserts our prompts obey it. That is module state in a package caique does not depend on (U6) and cannot read, so it is the row's one ceiling. updateSettings from this module does the same job for a program that imports it from here.

Not built, and named so it is a decision rather than a silence: box, progress and taskLog, which no graded case reaches (D-152).

import { CANCEL_SYMBOL, formatInstructionFooter, isCancel, … } from 'caique/clack';

Functions

formatInstructionFooter

The key hints under a list: one line, and the closing guide under it when there is one.

function formatInstructionFooter(instructions: string[], hasGuide: boolean): string[];
ParameterType
instructionsstring[]
hasGuideboolean

Returns string[]

limitOptions

The window of options a list should draw, as lines, with ... where it was cut.

The order of the four decisions is the behaviour, and every one of them is a graded case:

  1. How many options may show at all — the smaller of maxItems and the rows left after rowPadding, but never fewer than five. "clamps to 5 rows minimum" is that floor, and it is why a list in a seven-row terminal still shows something.
  2. Where the window starts — it only slides once the cursor comes within three of the bottom, and it stops at the end of the list rather than running past it.
  3. Which ends get an ellipsis — each ... costs a line, so it is counted before the options are, not after.
  4. What to give up when the options wrapped — options are dropped whole, away from the cursor first, and an ellipsis appears wherever something was dropped. The three "multi-line item clamping" cases are start, middle and end of that.
function limitOptions<TOption>({ cursor, options, style, output, maxItems, columnPadding, rowPadding, }: LimitOptionsParams<TOption>): string[];
ParameterType
{ cursor, options, style, output, maxItems, columnPadding, rowPadding, }LimitOptionsParams<TOption>

Returns string[]

updateSettings

Change the settings every later prompt reads.

These are caique's settings, not @clack/core's, and that is the one place this subpath cannot follow the incumbent: clack's live in a module caique does not depend on (U6), so a program that calls @clack/core's updateSettings is changing a package our prompts never read. A program that imports this one from caique/clack gets the behaviour.

function updateSettings(updates: ClackSettings): void;
ParameterType
updatesClackSettings

Returns void

Constants

autocomplete

autocomplete — select with a search box over the list.

const autocomplete: <Value>(opts: AutocompleteOptions<Value>) => Answer<Value>;

autocompleteMultiselect

autocompleteMultiselect — multiselect with a search box over the list.

const autocompleteMultiselect: <Value>(opts: AutocompleteMultiSelectOptions<Value>) => Answer<Value[]>;

cancel

Closes a session that was cancelled: the end of the guide, and the message in red.

const cancel: (message?: string, opts?: CommonOptions) => void;

CANCEL_SYMBOL

What every prompt resolves to when it is cancelled. Test it with isCancel.

const CANCEL_SYMBOL: unique symbol;

confirm

confirm — yes or no: arrows toggle, y and n answer at once.

const confirm: (opts: ConfirmOptions) => Answer<boolean>;

date

date — a date typed field by field, or stepped with the arrows inside minDate…maxDate.

const date: (opts: DateOptions) => Answer<Date>;

group

Ask a set of prompts in order; a cancelled one is recorded as 'canceled' when onCancel is given.

const group: <T>(prompts: PromptGroup<T>, opts?: PromptGroupOptions<T>) => Promise<Prettify<PromptGroupAwaitedReturn<T>>>;

groupMultiselect

groupMultiselect — a multi-selection in named groups; a group toggles all of its options.

const groupMultiselect: <Value>(opts: GroupMultiSelectOptions<Value>) => Answer<Value[]>;

intro

Opens a session: the top of the guide, and a title beside it.

const intro: (title?: string, opts?: CommonOptions) => void;

isCancel

Whether a prompt's answer is a cancellation rather than an answer.

const isCancel: (value: unknown) => value is symbol;

isCI

Whether CI is the string true, which is the test clack makes. This and the glyph table above stay clack's rules rather than roundel's: interactive() asks whether a person can answer, which clack never asks, and clack's table counts CI where roundel's unicode() does not.

const isCI: () => boolean;

isTTY

Whether a stream is a terminal.

const isTTY: (output: {
    isTTY?: boolean;
}) => boolean;

log

clack's log: a message on the guide, with a symbol for its kind.

const log: {
    message: typeof message;
    info: (text: string, opts?: LogMessageOptions) => void;
    success: (text: string, opts?: LogMessageOptions) => void;
    step: (text: string, opts?: LogMessageOptions) => void;
    warn: (text: string, opts?: LogMessageOptions) => void;
    /** An alias for `log.warn()`. */
    warning: (text: string, opts?: LogMessageOptions) => void;
    error: (text: string, opts?: LogMessageOptions) => void;
};

multiline

multiline — typing across lines; a second enter at the end submits, or tab reaches [ submit ].

const multiline: (opts: MultiLineOptions) => Answer<string>;

multiselect

multiselect — any number of options: space toggles, a toggles all, i inverts.

const multiselect: <Value>(opts: MultiSelectOptions<Value>) => Answer<Value[]>;

MULTISELECT_INSTRUCTIONS

const MULTISELECT_INSTRUCTIONS: string[];

note

A message in a box on the guide, with a title in its top edge.

const note: (text?: string, title?: string, opts?: NoteOptions) => void;

outro

Closes a session: the end of the guide, and a last message beside it.

const outro: (message?: string, opts?: CommonOptions) => void;

password

password — typing that is drawn as a mask and never echoed.

const password: (opts: PasswordOptions) => Answer<string>;

path

path — an autocomplete over the filesystem, starting at root or the working directory.

const path: (opts: PathOptions) => Answer<string>;

S_BAR

const S_BAR: string;

S_BAR_END

const S_BAR_END: string;

S_BAR_END_RIGHT

const S_BAR_END_RIGHT: string;

S_BAR_H

const S_BAR_H: string;

S_BAR_START

const S_BAR_START: string;

S_BAR_START_RIGHT

const S_BAR_START_RIGHT: string;

S_CHECKBOX_ACTIVE

const S_CHECKBOX_ACTIVE: string;

S_CHECKBOX_INACTIVE

const S_CHECKBOX_INACTIVE: string;

S_CHECKBOX_SELECTED

const S_CHECKBOX_SELECTED: string;

S_CONNECT_LEFT

const S_CONNECT_LEFT: string;

S_CORNER_BOTTOM_LEFT

const S_CORNER_BOTTOM_LEFT: string;

S_CORNER_BOTTOM_RIGHT

const S_CORNER_BOTTOM_RIGHT: string;

S_CORNER_TOP_LEFT

const S_CORNER_TOP_LEFT: string;

S_CORNER_TOP_RIGHT

const S_CORNER_TOP_RIGHT: string;

S_ERROR

const S_ERROR: string;

S_INFO

const S_INFO: string;

S_PASSWORD_MASK

const S_PASSWORD_MASK: string;

S_RADIO_ACTIVE

const S_RADIO_ACTIVE: string;

S_RADIO_INACTIVE

const S_RADIO_INACTIVE: string;

S_STEP_ACTIVE

const S_STEP_ACTIVE: string;

S_STEP_CANCEL

const S_STEP_CANCEL: string;

S_STEP_ERROR

const S_STEP_ERROR: string;

S_STEP_SUBMIT

const S_STEP_SUBMIT: string;

S_SUCCESS

const S_SUCCESS: string;

S_WARN

const S_WARN: string;

select

select — one option from a list, drawn through limitOptions.

const select: <Value>(opts: SelectOptions<Value>) => Answer<Value>;

SELECT_INSTRUCTIONS

const SELECT_INSTRUCTIONS: string[];

selectKey

selectKey — one option, chosen by pressing the first letter of its value.

const selectKey: <Value extends string>(opts: SelectKeyOptions<Value>) => Answer<Value>;

settings

The process-wide settings every prompt here reads, and updateSettings writes.

const settings: {
    actions: Set<Action>;
    aliases: Map<string, Action>;
    messages: {
        cancel: string;
        error: string;
    };
    withGuide: boolean;
};

spinner

A spinner on the guide: animated on a terminal outside CI, printed once per message anywhere else.

const spinner: (opts?: SpinnerOptions) => SpinnerResult;

stream

clack's stream: log, for text that arrives in pieces.

const stream: {
    message: typeof streamed;
    info: (chunks: Chunks) => Promise<void>;
    success: (chunks: Chunks) => Promise<void>;
    step: (chunks: Chunks) => Promise<void>;
    warn: (chunks: Chunks) => Promise<void>;
    warning: (chunks: Chunks) => Promise<void>;
    error: (chunks: Chunks) => Promise<void>;
};

symbol

The glyph that opens a prompt's title line, coloured for its state.

const symbol: (state: State) => string;

symbolBar

The guide bar beside a prompt's body, coloured for its state; none while it validates.

const symbolBar: (state: State) => string | undefined;

tasks

Run tasks one after another, each under its own spinner, each ending on what it returned.

const tasks: (list: Task[], opts?: CommonOptions) => Promise<void>;

text

text — one line of typing, with a placeholder, a default and a validator.

const text: (opts: TextOptions) => Answer<string>;

unicode

Whether the terminal can draw clack's box characters; read once, as the incumbent reads it.

const unicode: boolean;

unicodeOr

The first glyph where the terminal draws unicode, the second where it does not.

const unicodeOr: (glyph: string, fallback: string) => string;

Interfaces

AutocompleteMultiSelectOptions

interface AutocompleteMultiSelectOptions<Value> extends AutocompleteSharedOptions<Value> {
    initialValues?: Value[];
    required?: boolean;
}

AutocompleteOptions

interface AutocompleteOptions<Value> extends AutocompleteSharedOptions<Value> {
    initialValue?: Value;
    initialUserInput?: string;
    completeOnTab?: boolean;
}

ClackSettings

What updateSettings takes.

interface ClackSettings {
    /** Extra keys for an action — `{ w: 'up' }` — which never replace an existing alias. */
    aliases?: Record<string, Action>;
    messages?: {
        cancel?: string;
        error?: string;
    };
    /** `false` draws every prompt without its left-hand guide. */
    withGuide?: boolean;
}

CommonOptions

The streams and settings every clack call accepts.

interface CommonOptions {
    input?: NodeJS.ReadableStream;
    output?: NodeJS.WritableStream & SizedOutput;
    signal?: AbortSignal;
    withGuide?: boolean;
}

ConfirmOptions

interface ConfirmOptions extends CommonOptions {
    message: string;
    active?: string;
    inactive?: string;
    initialValue?: boolean;
    vertical?: boolean;
}

DateOptions

interface DateOptions extends CommonOptions {
    message: string;
    format?: DateFormat;
    locale?: string;
    defaultValue?: Date;
    initialValue?: Date;
    minDate?: Date;
    maxDate?: Date;
    validate?: Validate<Date>;
}

GroupMultiSelectOptions

interface GroupMultiSelectOptions<Value> extends CommonOptions {
    message: string;
    options: Record<string, Option<Value>[]>;
    initialValues?: Value[];
    maxItems?: number;
    required?: boolean;
    cursorAt?: Value;
    selectableGroups?: boolean;
    groupSpacing?: number;
    showInstructions?: boolean;
}

LimitOptionsParams

What limitOptions takes. Named as the incumbent names it, because callers import it.

interface LimitOptionsParams<TOption> extends CommonOptions {
    /** The list to display. */
    options: TOption[];
    /** The index of the active option. */
    cursor: number;
    /** Renders one option, told whether it is the active one. */
    style: (option: TOption, active: boolean) => string;
    /** The most options to show, before the terminal's own height is taken into account. */
    maxItems?: number | undefined;
    /** Columns taken by something else on the line — a bar, an indent. */
    columnPadding?: number | undefined;
    /** Rows taken by something else on the screen — a message, a footer. */
    rowPadding?: number | undefined;
}

LogMessageOptions

interface LogMessageOptions extends CommonOptions {
    symbol?: string;
    spacing?: number;
    secondarySymbol?: string;
}

MultiLineOptions

interface MultiLineOptions extends TextOptions {
    /** Draw a `[ submit ]` button, reached with tab, instead of submitting on a second enter. */
    showSubmit?: boolean;
}

MultiSelectOptions

interface MultiSelectOptions<Value> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValues?: Value[];
    maxItems?: number;
    required?: boolean;
    cursorAt?: Value;
    showInstructions?: boolean;
}

NoteOptions

interface NoteOptions extends CommonOptions {
    /** Applied to every line of the message. */
    format?: (line: string) => string;
}

PasswordOptions

interface PasswordOptions extends CommonOptions {
    message: string;
    mask?: string;
    validate?: Validate<string>;
    clearOnError?: boolean;
}

PathOptions

interface PathOptions extends CommonOptions {
    message: string;
    root?: string;
    directory?: boolean;
    initialValue?: string;
    validate?: Validate<string>;
}

PromptGroupOptions

interface PromptGroupOptions<T> {
    /** Called when a prompt in the group is cancelled, with the answers so far. */
    onCancel?: (opts: {
        results: Prettify<Partial<PromptGroupAwaitedReturn<T>>>;
    }) => void;
}

SelectKeyOptions

interface SelectKeyOptions<Value extends string> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValue?: Value;
    caseSensitive?: boolean;
}

SelectOptions

interface SelectOptions<Value> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValue?: Value;
    maxItems?: number;
    showInstructions?: boolean;
}

SizedOutput

A stream a list can measure itself against. Anything with a size, including a test double.

interface SizedOutput {
    columns?: number;
    rows?: number;
    isTTY?: boolean;
}

SpinnerOptions

interface SpinnerOptions extends CommonOptions {
    indicator?: 'dots' | 'timer';
    onCancel?: () => void;
    cancelMessage?: string;
    errorMessage?: string;
    frames?: string[];
    delay?: number;
    styleFrame?: (frame: string) => string;
}

SpinnerResult

interface SpinnerResult {
    start(msg?: string): void;
    stop(msg?: string): void;
    cancel(msg?: string): void;
    error(msg?: string): void;
    message(msg?: string): void;
    clear(): void;
    readonly isCancelled: boolean;
}

Task

interface Task {
    title: string;
    task: (message: (string: string) => void) => string | Promise<string> | void | Promise<void>;
    enabled?: boolean;
}

TextOptions

interface TextOptions extends CommonOptions {
    message: string;
    placeholder?: string;
    defaultValue?: string;
    initialValue?: string;
    validate?: Validate<string>;
}

Types

DateFormat

The date field order, as clack names it.

type DateFormat = 'YMD' | 'MDY' | 'DMY';

Option

One choice in a list: a primitive value may go without a label, anything else may not.

type Option<Value> = Value extends Primitive ? {
    value: Value;
    label?: string;
    hint?: string;
    disabled?: boolean;
} : {
    value: Value;
    label: string;
    hint?: string;
    disabled?: boolean;
};

PromptGroup

A named set of prompts, each told the answers before it.

type PromptGroup<T> = {
    [P in keyof T]: (opts: {
        results: Prettify<Partial<PromptGroupAwaitedReturn<Omit<T, P>>>>;
    }) => undefined | Promise<T[P] | undefined>;
};

PromptGroupAwaitedReturn

What a group resolves to: every prompt's answer, with the cancel symbol taken out of the type.

type PromptGroupAwaitedReturn<T> = {
    [P in keyof T]: Exclude<Awaited<T[P]>, symbol>;
};

caique/binding

Every export of caique/binding, with its signature and doc comment: resolvePrompts, plus 4 types.

caique/decide

Every export of caique/decide, with its signature and doc comment: decide, plus 4 types.

On this page

Read this before reading the compatibility numberFunctionsformatInstructionFooterlimitOptionsupdateSettingsConstantsautocompleteautocompleteMultiselectcancelCANCEL_SYMBOLconfirmdategroupgroupMultiselectintroisCancelisCIisTTYlogmultilinemultiselectMULTISELECT_INSTRUCTIONSnoteoutropasswordpathS_BARS_BAR_ENDS_BAR_END_RIGHTS_BAR_HS_BAR_STARTS_BAR_START_RIGHTS_CHECKBOX_ACTIVES_CHECKBOX_INACTIVES_CHECKBOX_SELECTEDS_CONNECT_LEFTS_CORNER_BOTTOM_LEFTS_CORNER_BOTTOM_RIGHTS_CORNER_TOP_LEFTS_CORNER_TOP_RIGHTS_ERRORS_INFOS_PASSWORD_MASKS_RADIO_ACTIVES_RADIO_INACTIVES_STEP_ACTIVES_STEP_CANCELS_STEP_ERRORS_STEP_SUBMITS_SUCCESSS_WARNselectSELECT_INSTRUCTIONSselectKeysettingsspinnerstreamsymbolsymbolBartaskstextunicodeunicodeOrInterfacesAutocompleteMultiSelectOptionsAutocompleteOptionsClackSettingsCommonOptionsConfirmOptionsDateOptionsGroupMultiSelectOptionsLimitOptionsParamsLogMessageOptionsMultiLineOptionsMultiSelectOptionsNoteOptionsPasswordOptionsPathOptionsPromptGroupOptionsSelectKeyOptionsSelectOptionsSizedOutputSpinnerOptionsSpinnerResultTaskTextOptionsTypesDateFormatOptionPromptGroupPromptGroupAwaitedReturn