closeout/plugin

The plugin host for closeout's half of the contract (plugin-contract R1, R5a, R6, R8).

import { validate, register, reset, … } from 'closeout/plugin';

FunctionsCopy Anchor Link

attachCopy Anchor Link

Hand every contributed handler to a closeout's registry, each in its own phase.

function attach(host: HandlerHost): () => void;

Returns () => void

contributionsCopy Anchor Link

Every handler every registered plugin contributed, in the order they will run.

function contributions(): Contribution[];

Returns Contribution[]

registerCopy Anchor Link

Register a plugin. Later wins, like ESLint flat config — but "wins" is a weaker word here than it is for a colour token: handlers do not shadow each other, they accumulate. Order is kept because two handlers in the same phase run in it, and because a plugin check wants to print the list a reader will see.

function register(plugin: unknown): void;

Returns void

registeredCopy Anchor Link

The plugins registered, in registration order.

function registered(): readonly Plugin[];

Returns readonly Plugin[]

resetCopy Anchor Link

Forget every registered plugin. For tests, and for a program that re-plugs at runtime.

function reset(): void;

Returns void

validateCopy Anchor Link

Refuse a plugin that cannot contribute a handler, at the door.

function validate(plugin: unknown): asserts plugin is Plugin;

Returns asserts plugin is Plugin

ClassesCopy Anchor Link

PluginErrorCopy Anchor Link

A refused plugin says what is wrong and what to do about it — the family's one vocabulary.

class PluginError extends Error {
    readonly code: PluginErrorCode;
    readonly fix: string;
    constructor(code: PluginErrorCode, message: string, fix: string);
}

ConstantsCopy Anchor Link

CONTRACTCopy Anchor Link

The plugin contract version. One number for the family — the same 1 flagstaff declares, written out rather than imported for the reason in the file comment above.

const CONTRACT = 1;

PLUGIN_PHASESCopy Anchor Link

The phases a plugin may put a handler in.

const PLUGIN_PHASES: readonly ["flush", "release"];

InterfacesCopy Anchor Link

ContributionCopy Anchor Link

One contributed handler, with the plugin it came from and the phase it resolved to.

interface Contribution {
    /** `"<plugin>:<handler>"` — the name a report prints. */
    id: string;
    phase: Phase;
    from: string;
    run: ExitHandler;
}

HandlerHostCopy Anchor Link

The half of a Registry this needs — declared structurally so a caller can attach to something it built itself, and so this file does not pull the process wiring in.

interface HandlerHost {
    add(handler: ExitHandler, spec?: HandlerSpec): () => void;
}

PluginCopy Anchor Link

The keys closeout reads. Declared structurally: any object with these fields is a plugin here, whatever else it carries.

interface Plugin {
    name: string;
    contract?: number;
    handlers?: readonly PluginHandler[];
}

PluginHandlerCopy Anchor Link

One contributed handler: a name to report it by, a phase to order it by, and the work.

interface PluginHandler {
    /** How the handler is named in a report — including the one the deadline prints. */
    name: string;
    /** Defaults to `release`. Never `restore`; see {@link PLUGIN_PHASES}. */
    phase?: (typeof PLUGIN_PHASES)[number];
    /** The cleanup itself. May be async; the phase is awaited before the next one begins. */
    run: ExitHandler;
}

TypesCopy Anchor Link

PluginErrorCodeCopy Anchor Link

type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_CONTRIBUTION';