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[];| Parameter | Type |
|---|---|
runtime | Runtime |
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;| Parameter | Type |
|---|---|
plugin | unknown |
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;| Parameter | Type |
|---|---|
template | string |
runtime | Runtime |
Returns string \| undefined
validate
Refuse a plugin that cannot contribute a resolver, at the door.
function validate(plugin: unknown): asserts plugin is Plugin;| Parameter | Type |
|---|---|
plugin | unknown |
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';bellpull/cross-spawn
Every export of bellpull/cross-spawn, with its signature and doc comment: _enoent, crossSpawn, parse, spawn, sync, ChildProcess and 1 more, plus 3 types.
FAQ
Short answers about bellpull — execa, non-zero exits, the default timeout, shells, Windows, which binary ran, plugins, CommonJS and what is not built — each with where to read more.