caique/binding

Resolving a whole command's prompts in one pass (R2, R3) — the piece a framework calls from its preAction hook, after the environment and config layers have had their turn.

The design sketched this as caique/burgee, one binding per host. It is one binding for all of them instead, and that is the better answer: what a host actually supplies is a record of options, the values parsed so far, and a runtime. None of that needs burgee's types, so nothing here imports them — which keeps the family's rule that no package requires another, and means burgee, burgee/commander and burgee/yargs share one implementation rather than three that drift.

The order is the declaration order, because --interactive asks for several things at once and a person answering them needs the sequence to match the help they just read.

import { resolvePrompts } from 'caique/binding';

FunctionsCopy Anchor Link

resolvePromptsCopy Anchor Link

Walk the command's options in order, asking only what has to be asked.

Stops at the first refusal: the caller is about to exit, and a person told about six missing flags — one of which they would have answered interactively — has been given a worse message than one told about the first.

function resolvePrompts<O extends PromptableOption>({ options, values, runtime, flags, io }: ResolveInput<O>): Promise<Resolved>;

Returns Promise<Resolved>

InterfacesCopy Anchor Link

PromptableOptionCopy Anchor Link

What a host tells us about one option. Structural: any framework's spec satisfies it.

interface PromptableOption {
    required?: boolean;
    prompt?: PromptSpec;
}

ResolvedCopy Anchor Link

interface Resolved {
    /** The values with every answered prompt written in. The input is not mutated. */
    values: Record<string, unknown>;
    /**
     * The first refusal, or nothing. First rather than all: the caller is about to exit, and
     * a person told about six missing flags one of which they will answer interactively has
     * been given a worse message than one told about the first.
     */
    failure?: ResolveFailure;
}

ResolveFailureCopy Anchor Link

interface ResolveFailure {
    option: string;
    code: 'USAGE' | 'CANCELLED';
    message: string;
    fix?: string;
}

ResolveInputCopy Anchor Link

interface ResolveInput<O extends PromptableOption = PromptableOption> {
    /** The command's options by name, in declaration order — a record preserves it. */
    options: Record<string, O>;
    /** What the values are after every other source has been consulted. */
    values: Record<string, unknown>;
    runtime: Runtime;
    flags?: Flags;
    io: Io;
}