footprintjs - v11.2.0
    Preparing search index...

    Interface NarrativeFormatter

    Pluggable formatter for narrative output. Turns structured event context objects into the text lines that make up the narrative array.

    In web terminology "renderer" usually means "turn data into a visible UI" (pixels, DOM, HTML). This interface does something smaller: it converts event context into a text string. That is more accurately called a formatter.

    Each method is optional — unimplemented methods fall back to the default English formatter. Return null from renderOp to exclude that entry from the narrative entirely.

    const rec = narrative({
      renderer: {
        renderOp(ctx) {
          if (ctx.key.startsWith('_internal')) return null; // filter out internal keys
          return `${ctx.type === 'read' ? 'Read' : 'Wrote'} ${ctx.key}: ${ctx.valueSummary}`;
        },
      },
    });
    interface NarrativeFormatter {
        renderAttempt?(ctx: AttemptRenderContext): string | null | undefined;
        renderBreak?(ctx: BreakRenderContext): string;
        renderDecision?(ctx: DecisionRenderContext): string;
        renderEmit?(ctx: EmitRenderContext): string | null | undefined;
        renderError?(ctx: ErrorRenderContext): string;
        renderFork?(ctx: ForkRenderContext): string;
        renderLoop?(ctx: LoopRenderContext): string;
        renderOp?(ctx: OpRenderContext): string | null | undefined;
        renderSelected?(ctx: SelectedRenderContext): string;
        renderStage?(ctx: StageRenderContext): string;
        renderSubflow?(ctx: SubflowRenderContext): string;
    }
    Index
    renderAttempt? renderBreak? renderDecision? renderEmit? renderError? renderFork? renderLoop? renderOp? renderSelected? renderStage? renderSubflow?

    • Format one attempt of a retried stage (10.1) into a narrative line — a depth-1 sub-item of its stage, between the attempts' reads and writes (for a stage that failed for good, beneath its error line). It replaces the 9.15–10.0 renderRetry, which is removed: this line says "retrying" too.

      • string → use as the narrative line
      • null → deliberately exclude this entry
      • undefined → fall back to the library's default sentence (Attempt 2 of 3 at Fetch failed in 12ms (…), retrying in 1s.)

      Parameters

      Returns string | null | undefined

    • Format a consumer-emitted event (from scope.$emit(name, payload)) into a narrative line.

      • string → use as the narrative line
      • null → deliberately exclude this entry
      • undefined → this formatter does not handle this emit; fall back to the library's default template

      Typical pattern: switch on ctx.name (or a prefix of it) and return a domain-specific text line for the event types you care about; return undefined for everything else so the default template handles it.

      Parameters

      Returns string | null | undefined

    • Format an op (scope read/write, or subflow-input key) into a narrative line.

      • string → use as the narrative line
      • null → deliberately exclude this entry from the narrative
      • undefined → this formatter does not handle this op; fall back to the library's default template

      The undefined return lets a domain-aware formatter handle only the keys it knows about and leave the rest to the library default — without having to re-implement the whole default inline.

      Parameters

      Returns string | null | undefined

    Settings
    Member Visibility

    On This Page
    Why "Formatter", not "Renderer"Behaviour
    Methods