flagstaff/loop

The frame loop (R1). hoist() raises a component, update() changes its state, lower() takes it down and leaves the static line behind. Which of the four projections runs is the output policy's decision (roundel/policy), read once from the runtime; this file never looks at a stream's isTTY or an environment variable itself (U2).

import { hoist, manualClock } from 'flagstaff/loop';

FunctionsCopy Anchor Link

hoistCopy Anchor Link

Hoist a component in its initial state. Pass { json: true } when the run was asked for --json.

function hoist<S>(component: Component<S>, rt: Runtime, initial: S, opts?: ModeOptions): Hoisted<S>;

Returns Hoisted<S>

manualClockCopy Anchor Link

A clock that moves only when told (R9): the same frames every run, so a spinner snapshots.

function manualClock(start?: number): ManualClock;

Returns ManualClock

InterfacesCopy Anchor Link

ClockCopy Anchor Link

Time as the loop sees it: burgee's Runtime.clock satisfies it, so does manualClock().

interface Clock {
    now(): number;
    schedule(fn: () => void, ms: number): () => void;
}

HoistedCopy Anchor Link

interface Hoisted<S> {
    readonly mode: OutputMode;
    update(state: S): void;
    /** Lower the flag: the final state's static projection is what stays on screen. */
    lower(state?: S): void;
}

ManualClockCopy Anchor Link

interface ManualClock extends Clock {
    /** Advance by `ms`, running every callback that falls due, earliest first. */
    tick(ms: number): void;
}

RuntimeCopy Anchor Link

What the loop needs from the world: the policy's slice plus the two streams and a clock.

interface Runtime extends PolicyRuntime {
    stdout: Writer;
    stderr: Writer;
    clock: Clock;
}

WriterCopy Anchor Link

interface Writer {
    write(chunk: string): unknown;
}