P is the type of the plugin’s phrasebook. Use definePlugin(plugin) to have it inferred from phrases.en.
Fields
string
required
A unique name. Locales override this plugin’s phrases under
locale.plugins[name].{ en: P } & { [locale: string]: P }
Phrasebooks keyed by locale id.
en is required. A phrasebook may also include glossary, constants and errorLabels, which the engine merges over the plugin’s own fields.{ name: string; versions: string }
The npm package this plugin reads and the semver range it was written against. The engine doesn’t enforce it; guard rules with
e.usesLibrary and pick readings with e.libraryMajor. See Plugin versioning. With library set, call and condition rules also match the library’s exports when they’re imported under another name or through a namespace. See Imports under another name.Vocabulary
Glossary entries, acronyms, verbs and predicate prefixes used to read identifiers.
string[]
Identifiers that are plumbing, dropped from argument lists and member chains. The built-in
std plugin marks ctx as ambient.string[] | RegExp
Constructor names whose instances are errors. The built-in
std plugin uses /Error$/.Record<string, string>
How to name an error class when it’s thrown.
Record<string, string>
Exact source text mapped to a phrase.
Record<string, CallRule<P>>
Call rules keyed by callee. See rule keys and the key grammar. A key no code can match is reported with
console.warn when the plugin loads.Record<string, CondRule<P>>
Condition rules, used when a call appears where a yes or no answer is expected.
Record<string, MemberRule<P>>
Property-read rules keyed by
Obj.prop, *.owner.prop, *.prop, Obj.* or *.owner.*, tried in that order. See member rules.JsxRule<P>
Reads a JSX element or fragment wherever the engine meets one. Later plugins’ rules are tried first.
StmtRule<P>[]
Rules that can take over a whole statement. Each returns
true once it has emitted lines, or false.(e, n, say) => string | null
Describes a schema-builder expression as a type, or returns
null if the node isn’t one.Rules
N
The call expression, member expression, JSX element or statement.
N is an ESTree node from oxc. For tagged template keys, it is the tagged template and args[0] is its template literal.N[]
The call’s arguments.
N | null
The receiver for
Obj.method and *.method keys, otherwise null. For member rules, the object whose property is read.string
For member rules, the property name.
boolean
true when the call is a statement on its own, so it should read as an action (“Send the receipt”) rather than a noun (“the receipt that was sent”).boolean
For condition rules,
true when the condition is negated.number
For statement rules, the indent depth to emit lines at. Return
true once you’ve emitted lines, or false to let the engine handle the statement.P
This plugin’s phrasebook for the active locale.
null or undefined to let the next rule try. A string result is treated as a Doc with no block lines.
A rule that throws, or returns anything else, is treated as if it returned null (or false for a statement rule), and any lines it emitted are removed. The failure is recorded in the narration’s stats.ruleErrors as { plugin, rule, message, count }, where rule reads like calls["*.plus"], statements[0], jsx or describeSchema. See When a rule fails.