bellpull
API reference

bellpull/plugin

Every export of bellpull/plugin, with its signature and doc comment: validate, register, reset, registered, contributions, substitute and 3 more, plus 6 types.

The plugin host for bellpull's half of the contract — plugin-contract R5a, R6, R7, R8, and PLAN step 1.5.

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

Functions

contributions

Every resolver every registered plugin contributed, in the order they will be searched.

function contributions(): Contribution[];

Returns Contribution[]

directories

The directories registered plugins contribute for this runtime, in search order.

function directories(runtime: Runtime): ContributedDirectory[];
ParameterType
runtimeRuntime

Returns ContributedDirectory[]

register

Register a plugin. Later wins, like ESLint flat config — though "wins" is narrower here than for a colour token: two resolvers under the same name shadow, and two resolvers under different names both apply, in rank order.

function register(plugin: unknown): void;
ParameterType
pluginunknown

Returns void

registered

The plugins registered, in registration order.

function registered(): readonly Plugin[];

Returns readonly Plugin[]

reset

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

function reset(): void;

Returns void

substitute

Substitute {VAR} from the environment.

function substitute(template: string, runtime: Runtime): string | undefined;
ParameterType
templatestring
runtimeRuntime

Returns string \| undefined

validate

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

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

Returns asserts plugin is Plugin

Classes

PluginError

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);
}

Constants

CONTRACT

The plugin contract version. One number for the family — the same 1 flagstaff, roundel, caique and closeout declare, written out rather than imported for the reason above.

const CONTRACT = 1;

Interfaces

ContributedDirectory

A contributed directory, and which resolver put it there.

interface ContributedDirectory {
    dir: string;
    /** The resolver's name, so a report can say why this directory is being searched. */
    resolver: string;
    rank: number;
}

Contribution

One contributed resolver, with the plugin it came from and what it shadowed.

interface Contribution {
    name: string;
    from: string;
    resolver: Resolver;
    /** Plugins that contributed this name earlier and were overridden, in order. */
    shadowed: string[];
}

Plugin

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

interface Plugin {
    name: string;
    contract?: number;
    resolvers?: Record<string, Resolver>;
}

Resolver

One contributed way of finding an executable.

interface Resolver {
    /**
     * Where this sits relative to `PATH`, which is rank `0`. A negative rank searches before
     * `PATH` — which is what a version manager's shims want, because being *after* `PATH` is
     * the same as not being installed. Ties keep registration order.
     */
    rank: number;
    /**
     * Directories to search, in order. Absolute after substitution, or dropped.
     * `{VAR}` is replaced by `runtime.env.VAR`; an unset variable drops the entry.
     */
    paths: readonly string[];
    /** Extra extensions to try, in order — `PATHEXT` for one resolver rather than the machine. */
    extensions?: readonly string[];
    /** When it applies. Absent means always. */
    when?: ResolverWhen;
}

ResolverWhen

When a resolver applies. Every clause must hold; each array is an OR within itself.

interface ResolverWhen {
    /** Platforms, as `process.platform` spells them. Absent means every platform. */
    platform?: readonly string[];
    /** Any one of these environment variables merely being set — how a version manager announces itself. */
    envAny?: readonly string[];
}

Types

PluginErrorCode

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

On this page