closeout

import { alternateScreen, assertDeadline, createRegistry, … } from 'closeout';

function alternateScreen(stream: OutputStream, closeout?: Closeout): () => void;

function assertDeadline(ms: number): number;

function createRegistry(options?: RegistryOptions): Registry;

function hideCursor(stream: OutputStream): () => void;

function install(options?: InstallOptions): Closeout;

function onExit(handler: ExitHandler, spec?: HandlerSpec): () => void;

function rawMode(input: InputStream, closeout?: Closeout): () => void;

function reportToEvent(report: ShutdownReport): ExitEvent;

function reportToJson(report: ShutdownReport): string;

function showCursor(stream: OutputStream): void;

function timeoutMessage(report: ShutdownReport, deadline: number): string;

class DeadlineError extends TypeError {
    readonly code = "USAGE";
    /** What to do instead. Always present, always actionable — contract R8's shape. */
    readonly fix: string;
    constructor(message: string, fix: string);
}

const DEADLINE_ERROR_CODE = "USAGE";

const DEFAULT_DEADLINE = 2000;

const DEFAULT_PHASE: Phase;

const EXIT_PATHS: readonly ["exit", "beforeExit", "signal", "uncaught", "rejection"];

const PHASES: readonly ["flush", "release", "restore"];

const SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT", "SIGBREAK"];

interface Closeout {
    /**
     * Register a handler. Returns the function that unregisters it.
     */
    onExit(handler: ExitHandler, spec?: HandlerSpec): () => void;
    /** Hide the cursor and register its restore; the returned function shows it again. */
    hideCursor(stream: OutputStream): () => void;
    /** Show the cursor now. Idempotent, and a no-op on a non-TTY. */
    showCursor(stream: OutputStream): void;
    /** The registry, for a caller that wants to drive shutdown itself. */
    readonly registry: Registry;
}

interface ExitEvent {
    type: 'closeout.shutdown';
    path: ExitPath;
    signal: string | null;
    code: number | null;
    error: string | null;
    timedOut: boolean;
    unfinished: string[];
}

interface ExitInfo {
    code: number | null;
    signal: string | null;
    path?: ExitPath;
    error?: unknown;
}

interface ExitReport {
    /** Which door: a normal exit, an emptied loop, a signal, a throw, a rejected promise. */
    path: ExitPath;
    /** The signal that ended it, when one did. */
    signal: string | null;
    /** The code the process is leaving with, when it is leaving by a code. */
    code: number | null;
    /** What was thrown or rejected, on the two paths that have one. `null` on the others. */
    error: unknown;
}

interface HandlerOptions {
    /** Which phase it runs in. Defaults to {@link DEFAULT_PHASE}. */
    phase?: Phase;
    /**
     * What to call it in a report.
     */
    label?: string;
}

interface InstallOptions extends RegistryOptions {
    /** Defaults to the real `process`. */
    process?: ProcessLike;
}

interface ProcessLike {
    on(event: string, listener: (...args: never[]) => void): unknown;
    removeListener(event: string, listener: (...args: never[]) => void): unknown;
    listenerCount(event: string): number;
    exit(code?: number): never;
    /**
     * Send a signal to a process. closeout passes exactly one pid — {@link ProcessLike.pid},
     * its own — because the only thing it ever does with this is re-raise the signal it just
     * handled, so that a process killed by SIGINT *dies of SIGINT* instead of reporting 130.
     */
    kill(pid: number, signal: string): unknown;
    /** This process's own id — the only one {@link ProcessLike.kill} is ever given. */
    pid: number;
    stderr: OutputStream;
    /**
     * Optional because the signal wiring has never needed it and its tests do not supply one:
     * only the terminal-restore façade picks between the two streams.
     */
    stdout?: OutputStream;
    /**
     * The code the process will leave with, which is a property of the process and not of any
     * handler. `exit-hook`'s contract is written in terms of it — a hook is handed the code the
     * program is about to exit with, and a signal overrules whatever was set — so the drop-in
     * path reads and writes it here. Typed as Node types it (`string` is legal and coerced).
     */
    exitCode?: number | string | undefined;
}

interface Registry {
    /**
     * Register a handler in a phase. Returns the function that unregisters it.
     */
    add(handler: ExitHandler, spec?: HandlerSpec): () => void;
    /**
     * Run every handler, once, phase by phase, inside the deadline. A later call runs nothing
     * and resolves with the first: it waits on a shutdown still in flight.
     */
    run(info: ExitInfo): Promise<ShutdownReport>;
    /** Run every handler synchronously, in phase order; a returned promise is abandoned. */
    runSync(info: ExitInfo): ShutdownReport;
    /** How many handlers are registered — for a caller that wants to know if any are. */
    readonly size: number;
    /** How many are registered in one phase. */
    count(phase: Phase): number;
    /** Whether shutdown has already happened. */
    readonly settled: boolean;
    /**
     * The report of the shutdown that happened, or `undefined` before one has.
     */
    readonly report: ShutdownReport | undefined;
}

interface RegistryOptions {
    /**
     * How long shutdown may take before it stops waiting, in milliseconds.
     */
    deadline?: number;
    /** Where a handler's own failure is reported. Defaults to stderr. */
    onError?: (error: unknown) => void;
    /**
     * Where a breached deadline is reported. Defaults to stderr, naming every handler that
     * had not returned. Takes the whole report, so a caller can project it as JSON or as an
     * agent event instead of a line of prose.
     */
    onTimeout?: (report: ShutdownReport) => void;
}

interface ShutdownReport extends ExitReport {
    /** Whether the deadline expired before the handlers were done. */
    timedOut: boolean;
    /**
     * The handlers that had not returned when shutdown stopped waiting — by the label their
     * caller gave them, or by the function's own `name`.
     */
    unfinished: readonly string[];
}

type ExitHandler = (report: ExitReport) => void | Promise<void>;

type ExitPath = 'exit' | 'beforeExit' | 'signal' | 'uncaught' | 'rejection';

type HandlerSpec = Phase | HandlerOptions;

type Phase = (typeof PHASES)[number];