paratext/plugin

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

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

FunctionsCopy Anchor Link

attachCopy Anchor Link

Hand every contributed capability to a registry.

function attach(host?: CapabilityHost): void;

Returns void

contributionsCopy Anchor Link

Every capability every registered plugin contributed, with who won each name.

function contributions(): Contribution[];

Returns Contribution[]

registerCopy Anchor Link

Register a plugin. Later wins, like ESLint flat config: the array is ordered, a caller reads it top to bottom, and the last word on a capability name is the one nearest the program — which is also the registry's own rule, since register() in capability.ts replaces by name so a caller can correct a guess we got wrong.

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 capability, 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;
    /** Each problem apart, with its own code and fix, where one refusal reports several. */
    readonly problems?: readonly Refusal[] | undefined;
    constructor(code: PluginErrorCode, message: string, fix: string, 
    /** Each problem apart, with its own code and fix, where one refusal reports several. */
    problems?: readonly Refusal[] | undefined);
}

ConstantsCopy Anchor Link

CONTRACTCopy Anchor Link

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

const CONTRACT = 1;

InterfacesCopy Anchor Link

CapabilityHostCopy Anchor Link

The half of the capability registry this needs — declared structurally so a caller can attach to something it built itself, and so a host can watch what arrives.

interface CapabilityHost {
    register(capability: Capability): void;
}

ContributionCopy Anchor Link

One contributed capability, with the plugin it came from and the plugins it displaced.

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

PluginCopy Anchor Link

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

interface Plugin {
    name: string;
    contract?: number;
    /** Capabilities by name. The key and the record's own `name` must agree; see {@link validate}. */
    capabilities?: Record<string, Capability>;
}

RefusalCopy Anchor Link

One thing wrong with a plugin, in the family's vocabulary: the code, the line, the fix.

interface Refusal {
    code: PluginErrorCode;
    message: string;
    fix: string;
}

TypesCopy Anchor Link

PluginErrorCodeCopy Anchor Link

Three codes, all of them already in flagstaff's PluginErrorCode — the vocabulary home (scripts/plugin-error-vocabulary-lock.test.ts). E_NO_STATIC_PROJECTION is the one worth noticing: flagstaff raises it for a component with no static form and caique for a widget with no static, and a capability with no fallback is the same defect wearing OSC. One code, one fix shape, three layers.

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