caique/inquirer

import { usePrefix, useKeypress, createPrompt, … } from 'caique/inquirer';

FunctionsCopy Anchor Link

createPromptCopy Anchor Link

Turn a render function into a prompt.

Two lines, because the interesting half is runPrompt and the only thing this one adds is the call site — captured now rather than at the throw, since the error a render function gets for returning nothing names the file createPrompt was called from.

function createPrompt<Value, Config>(view: ViewFunction<Value, Config>): Prompt<Value, Config>;

Returns Prompt<Value, Config>

getDefaultKeybindingsCopy Anchor Link

INQUIRER_KEYBINDINGS split on whitespace or commas, lowercased, unknown names dropped and duplicates collapsed — so 'vim emacs unknown vim' is ['vim', 'emacs'].

function getDefaultKeybindings(): Keybinding[];

Returns Keybinding[]

getDefaultThemeCopy Anchor Link

The defaults with the environment's keybindings folded in, read fresh on every call.

function getDefaultTheme(): Theme;

Returns Theme

makeThemeCopy Anchor Link

Merge any number of partial themes over the defaults, last one winning per leaf.

null and undefined entries are dropped rather than merged, because a prompt passes config.theme straight through and a caller who set no theme passes undefined.

function makeTheme<Extension = object>(...themes: readonly (PartialTheme<Extension> | undefined)[]): Theme & Extension;

Returns Theme & Extension

useEffectCopy Anchor Link

A side effect, queued when its dependency array changes and cleaned up before it re-runs.

The comparison is Object.is per element, like the incumbent's, so a useRef handed back as a dependency is stable and an object literal is not.

function useEffect(cb: (rl: PromptReadline) => Cleanup, depArray: readonly unknown[]): void;

Returns void

useKeypressCopy Anchor Link

Register a keypress handler for as long as the prompt is rendering.

ignore rather than only removeListener, because readline emits every keypress in one data event synchronously: a handler removed during that burst would still be called for the keys already queued behind the one that settled the prompt. Two graded cases — "after the prompt is done" and "after the prompt is aborted" — are that exact race.

function useKeypress(userHandler: (event: KeypressEvent, rl: PromptReadline) => void | Promise<void>): void;

Returns void

useMemoCopy Anchor Link

A memoised value.

Compared with !== rather than Object.is, and by length first, exactly as upstream does it — a drop-in that quietly tightened the comparison would recompute where the incumbent does not, and the graded case counts the calls.

function useMemo<Value>(fn: () => Value, dependencies: readonly unknown[]): Value;

Returns Value

usePrefixCopy Anchor Link

The prefix a prompt draws, and the spinner that replaces it while the prompt is loading.

The 300 ms delay before the spinner appears is not decoration: it is what stops a prompt that resolves quickly from flickering a frame of spinner on its way past, and the graded case advances fake timers by exactly delay + interval to see the first frame.

function usePrefix({ status, theme }: {
    status?: Status;
    theme?: PartialTheme;
}): string;

Returns string

useRefCopy Anchor Link

A box that survives re-renders. One useState slot holding an object that never changes. The no-argument form, for a box a later render fills — useRef<Timeout | undefined>().

function useRef<Value>(value: Value): {
    current: Value;
};

function useRef<Value>(value?: Value): {
    current: Value | undefined;
};

Returns { current: Value; }

useStateCopy Anchor Link

State that survives a re-render, addressed by call order.

The setter accepts a value or a reducer, and does nothing at all when the next value is Object.is-equal to the current one — which is why setValue(NaN) on a NaN state does not re-render, and why a reducer returning its argument is free. The no-argument form, for state a later keypress fills.

function useState<Value>(defaultValue: NotFunction<Value> | (() => Value)): [Value, SetState<Value>];

function useState<Value>(defaultValue?: NotFunction<Value> | (() => Value)): [Value | undefined, SetState<Value | undefined>];

Returns [Value, SetState<Value>]

ClassesCopy Anchor Link

AbortPromptErrorCopy Anchor Link

Thrown when the AbortSignal handed to a prompt aborts.

class AbortPromptError extends Error {
    name: string;
    message: string;
    constructor(options?: {
        cause?: unknown;
    });
}

CancelPromptErrorCopy Anchor Link

Thrown when a caller calls .cancel() on the returned promise.

class CancelPromptError extends Error {
    name: string;
    message: string;
}

ExitPromptErrorCopy Anchor Link

Thrown when the process is going away under the prompt — Ctrl-C, or a signalled exit.

class ExitPromptError extends Error {
    name: string;
}

HookErrorCopy Anchor Link

Thrown when a hook is called outside a prompt render, where there is no store to read.

class HookError extends Error {
    name: string;
}

SeparatorCopy Anchor Link

A non-choice in a list of choices.

isSeparator is a duck type rather than an instanceof check, and deliberately so: a caller who built { type: 'separator', separator: '----' } by hand — or who has two copies of the package in their tree — must still have it recognised. One of the three graded cases is exactly that object literal.

class Separator {
    readonly separator: string;
    readonly type = "separator";
    constructor(separator?: string);
    /** Whether `choice` is a separator — by shape, never by class. */
    static isSeparator(choice: unknown): choice is Separator;
}

ValidationErrorCopy Anchor Link

Thrown when a hook is called correctly but handed something it cannot use.

class ValidationError extends Error {
    name: string;
}

ConstantsCopy Anchor Link

defaultThemeCopy Anchor Link

The incumbent's defaults, byte for byte where a byte is observable.

styleText is node:util's, which is the whole colour dependency: roundel owns colour for caique's own widgets, and reaching for it here would put a second policy on a subpath whose job is to behave like somebody else's package.

const defaultTheme: Theme;

isBackspaceKeyCopy Anchor Link

Backspace.

const isBackspaceKey: (key: KeypressEvent) => boolean;

isDownKeyCopy Anchor Link

The down arrow always; j under vim; Ctrl-N under emacs.

const isDownKey: (key: KeypressEvent, keybindings?: readonly Keybinding[]) => boolean;

isEnterKeyCopy Anchor Link

Enter, under either name readline gives it.

const isEnterKey: (key: KeypressEvent) => boolean;

isNumberKeyCopy Anchor Link

A digit. name is a single character for these, so a substring test is the whole test.

const isNumberKey: (key: KeypressEvent) => boolean;

isShiftKeyCopy Anchor Link

Whether shift was held. Returns the flag itself, so an absent flag reads as false.

const isShiftKey: (key: KeypressEvent) => boolean;

isSpaceKeyCopy Anchor Link

The space bar.

const isSpaceKey: (key: KeypressEvent) => boolean;

isTabKeyCopy Anchor Link

Tab.

const isTabKey: (key: KeypressEvent) => boolean;

isUpKeyCopy Anchor Link

The up arrow always; k under vim; Ctrl-P under emacs. Nothing else, ever.

const isUpKey: (key: KeypressEvent, keybindings?: readonly Keybinding[]) => boolean;

InterfacesCopy Anchor Link

ContextCopy Anchor Link

The streams and lifetime a caller may hand a prompt.

interface Context {
    input?: NodeJS.ReadableStream;
    output?: NodeJS.WritableStream;
    clearPromptOnDone?: boolean;
    signal?: AbortSignal;
}

KeypressEventCopy Anchor Link

What node:readline hands a keypress listener. Widened to what the predicates read.

interface KeypressEvent {
    name: string;
    ctrl?: boolean;
    shift?: boolean;
    meta?: boolean;
    sequence?: string;
}

ThemeCopy Anchor Link

The whole theme, as a prompt sees it after makeTheme has merged the defaults in.

interface Theme {
    prefix: ThemePrefix;
    spinner: ThemeSpinner;
    keybindings: Keybinding[];
    style: ThemeStyle;
}

TypesCopy Anchor Link

CancelablePromiseCopy Anchor Link

The promise a prompt returns: cancellable, so a caller can take the question back.

type CancelablePromise<Value> = Promise<Value> & {
    cancel: () => void;
};

KeybindingCopy Anchor Link

The two named keybinding sets the incumbent understands. Anything else is ignored.

type Keybinding = 'emacs' | 'vim';

PartialThemeCopy Anchor Link

What a caller may hand makeTheme: any subset, nested.

type PartialTheme<Extension = object> = Partial<Omit<Theme, 'style' | 'spinner'>> & {
    spinner?: Partial<ThemeSpinner>;
    style?: Partial<ThemeStyle>;
} & Partial<Extension>;

PromptCopy Anchor Link

A prompt, ready to be called with its config.

type Prompt<Value, Config> = (config: Config, context?: Context) => CancelablePromise<Value>;

SetStateCopy Anchor Link

The setter useState returns: a new value, or a reducer over the current one.

type SetState<Value> = (newValue: NotFunction<Value> | ((current: Value) => Value)) => void;

StatusCopy Anchor Link

The lifecycle a prompt reports through theme.prefix. Open, so a caller may add states.

type Status = 'loading' | 'idle' | 'done' | (string & {});

ViewFunctionCopy Anchor Link

What a render function returns: one string, or a body and a line below the cursor.

type ViewFunction<Value, Config> = (config: Config, done: (value: Value) => void) => string | [string, string | undefined];