IF Commons GitHub

render

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-telemetry FR-021

The console as a rendering of OpenTelemetry signals (commons 0001-telemetry FR-021 to FR-023): a pure reducer from a state, an input (a span that started, recorded an event or ended, a log record, an export that failed, a tick of the clock, the end of the run) and the time, to the next state and the frames to write. The runtime's console.ts feeds it and writes what it returns; a test feeds it and reads the frames through vt.ts's screen.

Five modes (FR-021):

  • attended: a live region of the spans in progress, nested by parent, each with its elapsed time and its progress (FR-023), redrawn in place (cursor up, erase in display); a line that is final (a span that ended, a log record) is written above the region and stays. Every line is cut to the terminal's width by display width, so nothing wraps.
  • plain: the final lines only, appended, with no escape sequence at all (no colour, no cursor movement), for a log or a pipe; a line is not cut.
  • quiet: the final lines that are warnings, errors (a span that failed, a log record of the role warning or error, or of severity WARN or more), actions (the role action: a step that is the person's to take, FR-027) or results (the role result), appended; coloured where the look allows it.
  • silent: nothing.
  • json: one OTLP JSON document per line, each an ExportLogsServiceRequest (otlp.ts's encodeLogs) holding one log record: a log record as it is; a span that ended as a log record whose eventName is the span's name, whose time is its end, whose severity is ERROR where it failed and INFO otherwise, whose body is its line as plain writes it (without indentation, with ASCII marks), with its attributes and its trace and span ids; the export warning as a WARN record named ifc.console.export.

Only a signal whose kind has a presentation role (signals.ts's roleOf) other than none is shown; an undeclared kind is not. A span that is not shown still nests: its children are shown at its depth. How a span ended: ⏭️ where it recorded an event named skipped, ⏹️ where it recorded one named cancelled (and for a span still open at the end of the run), ❌ where its status is an error, ✅ otherwise; marks and colours come from palette.ts, with its ASCII fallbacks and colour only where the look allows (FR-022).

An export that failed is said once, dimmed, at the end of the run, and nowhere else (FR-024). Text from a signal is cleaned of control characters, so a signal never moves the cursor. Time comes only from the now given (nanoseconds since the Unix epoch, as signals' times).

import { initial, render } from "./render.ts";
import { defineSignals } from "./signals.ts";
const registry = defineSignals({ "build.step": { signal: "span", role: "step", attributes: { target: "string" } } });
let state = initial({ mode: "plain", look: { colour: false, emoji: true, columns: 80 }, registry });
// ...for each signal: ({ state, frames } = render(state, { kind: "span-end", span, source }, now)); write(frames);

Source: commons/telemetry/src/render.ts

23 of 29 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

rendernamespace
namespace render
render.Modetype
type Mode = "attended" | "plain" | "quiet" | "silent" | "json";

How the console writes: see the module.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.MODESconst
const MODES: readonly Mode[]

Every mode, in a fixed order.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.parseModefunction
function parseMode(text: string): Mode | undefined

A mode by its name; undefined for another text.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.chooseModefunction
function chooseMode(facts: { readonly requested?: string | undefined; readonly tty: boolean; }): Mode

The mode to use: the one asked for where it names one, else attended at a terminal and plain elsewhere (FR-026).

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.Inputtype
type Input = | { readonly kind: "span-start"; readonly span: SpanStart; readonly source: Source } | { readonly kind:… (508 characters)
type Input =
  | { readonly kind: "span-start"; readonly span: SpanStart; readonly source: Source }
  | { readonly kind: "span-event"; readonly span: SpanStart; readonly event: SpanEvent; readonly source: Source }
  | { readonly kind: "span-end"; readonly span: SpanData; readonly source: Source }
  | { readonly kind: "log"; readonly record: LogRecord; readonly source: Source }
  | { readonly kind: "export-warning"; readonly message: string }
  | { readonly kind: "tick" }
  | { readonly kind: "finish" };

What the renderer is given: the processor's signals, a failed export, a tick of the clock (to redraw elapsed times), the end of the run.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.RenderConfigtype
type RenderConfig = { readonly mode: Mode; /** What the terminal shows: colour, emoji, its width (a `Look` of `syste… (629 characters)
type RenderConfig = {
  readonly mode: Mode;
  /** What the terminal shows: colour, emoji, its width (a `Look` of `system/tty` is one). */
  readonly look: Capabilities;
  /** The registry that gives each kind its presentation role. */
  readonly registry: Registry<Declarations>;
  /** A signal's text from its kind and attributes; `defaultText` where not given (a log record's string body comes first). */
  readonly text?: (name: string, attributes: Attributes) => string;
  /** The most lines the live region takes (10 by default, at least 2); the spans beyond are counted on its last line. */
  readonly maxLive?: number;
};

What a renderer is made with.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.Statetype
type State = { readonly config: RenderConfig; /** Every span started and not ended, shown or not, by trace and span … (669 characters)
type State = {
  readonly config: RenderConfig;
  /** Every span started and not ended, shown or not, by trace and span id. */
  readonly spans: ReadonlyMap<string, Known>;
  /** The shown spans in progress, in the order they started. */
  readonly live: readonly Live[];
  /** The lines of the live region on the screen (attended). */
  readonly drawn: number;
  /** The export warnings, each once, said at the end. */
  readonly warnings: readonly string[];
  /** The last source seen, for the records `json` writes of its own. */
  readonly source: Source | undefined;
  /** Whether the run has finished; nothing is written after. */
  readonly finished: boolean;
};

The renderer's state: what is open, what the screen shows of the live region, the warnings kept for the end.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.Steptype
type Step = { readonly state: State; readonly frames: string };

A reducer's step: the next state and the frames to write (empty for none).

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.initialfunction
function initial(config: RenderConfig): State

The state a renderer starts in.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.cleanfunction
function clean(text: string): string

A text with every control character but the line feed replaced (a tab by a space, the rest by ?), so it never moves the cursor.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.defaultTextfunction
function defaultText(name: string, attributes: Readonly<Record<string, AttributeValue>>, signal?: "log" | "span"): string

The text of a signal by default: a span's is its kind and its attributes' values, in their order, separated by spaces (build site); a log record's is its attributes' values alone, or its kind where it has none (a log record with a string body shows the body).

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.durationfunction
function duration(ns: bigint): string

A duration in nanoseconds as a person reads it: 420ms, 1.2s, 3m04s, 2h05m (cut, never rounded up; a negative one is 0ms).

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.progressTextfunction
function progressText(done: number, total?: number | undefined): string

How far a span has come: done/total and the percentage where there is a positive total, else done.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.outcomeOffunction
function outcomeOf(span: SpanData): MarkKind

How a span ended, as a mark: a skipped or cancelled event first, then its status.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

render.renderfunction
function render(state: State, input: Input, now: bigint): Step

The next state and the frames to write for an input at the time now (nanoseconds since the Unix epoch). Pure: the same state, input and time give the same step. After finish, every input gives no frame.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

Modetype
type Mode = "attended" | "plain" | "quiet" | "silent" | "json";

How the console writes: see the module.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

MODESconstno test imports it
const MODES: readonly Mode[]

Every mode, in a fixed order.

parseModefunction
function parseMode(text: string): Mode | undefined

A mode by its name; undefined for another text.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

chooseModefunction
function chooseMode(facts: { readonly requested?: string | undefined; readonly tty: boolean; }): Mode

The mode to use: the one asked for where it names one, else attended at a terminal and plain elsewhere (FR-026).

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

Inputtype
type Input = | { readonly kind: "span-start"; readonly span: SpanStart; readonly source: Source } | { readonly kind:… (508 characters)
type Input =
  | { readonly kind: "span-start"; readonly span: SpanStart; readonly source: Source }
  | { readonly kind: "span-event"; readonly span: SpanStart; readonly event: SpanEvent; readonly source: Source }
  | { readonly kind: "span-end"; readonly span: SpanData; readonly source: Source }
  | { readonly kind: "log"; readonly record: LogRecord; readonly source: Source }
  | { readonly kind: "export-warning"; readonly message: string }
  | { readonly kind: "tick" }
  | { readonly kind: "finish" };

What the renderer is given: the processor's signals, a failed export, a tick of the clock (to redraw elapsed times), the end of the run.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

RenderConfigtypeno test imports it
type RenderConfig = { readonly mode: Mode; /** What the terminal shows: colour, emoji, its width (a `Look` of `syste… (629 characters)
type RenderConfig = {
  readonly mode: Mode;
  /** What the terminal shows: colour, emoji, its width (a `Look` of `system/tty` is one). */
  readonly look: Capabilities;
  /** The registry that gives each kind its presentation role. */
  readonly registry: Registry<Declarations>;
  /** A signal's text from its kind and attributes; `defaultText` where not given (a log record's string body comes first). */
  readonly text?: (name: string, attributes: Attributes) => string;
  /** The most lines the live region takes (10 by default, at least 2); the spans beyond are counted on its last line. */
  readonly maxLive?: number;
};

What a renderer is made with.

Statetype
type State = { readonly config: RenderConfig; /** Every span started and not ended, shown or not, by trace and span … (669 characters)
type State = {
  readonly config: RenderConfig;
  /** Every span started and not ended, shown or not, by trace and span id. */
  readonly spans: ReadonlyMap<string, Known>;
  /** The shown spans in progress, in the order they started. */
  readonly live: readonly Live[];
  /** The lines of the live region on the screen (attended). */
  readonly drawn: number;
  /** The export warnings, each once, said at the end. */
  readonly warnings: readonly string[];
  /** The last source seen, for the records `json` writes of its own. */
  readonly source: Source | undefined;
  /** Whether the run has finished; nothing is written after. */
  readonly finished: boolean;
};

The renderer's state: what is open, what the screen shows of the live region, the warnings kept for the end.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

Steptypeno test imports it
type Step = { readonly state: State; readonly frames: string };

A reducer's step: the next state and the frames to write (empty for none).

initialfunction
function initial(config: RenderConfig): State

The state a renderer starts in.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

cleanfunctionno test imports it
function clean(text: string): string

A text with every control character but the line feed replaced (a tab by a space, the rest by ?), so it never moves the cursor.

defaultTextfunctionno test imports it
function defaultText(name: string, attributes: Readonly<Record<string, AttributeValue>>, signal?: "log" | "span"): string

The text of a signal by default: a span's is its kind and its attributes' values, in their order, separated by spaces (build site); a log record's is its attributes' values alone, or its kind where it has none (a log record with a string body shows the body).

durationfunction
function duration(ns: bigint): string

A duration in nanoseconds as a person reads it: 420ms, 1.2s, 3m04s, 2h05m (cut, never rounded up; a negative one is 0ms).

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

progressTextfunction
function progressText(done: number, total?: number | undefined): string

How far a span has come: done/total and the percentage where there is a positive total, else done.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

outcomeOffunctionno test imports it
function outcomeOf(span: SpanData): MarkKind

How a span ended, as a mark: a skipped or cancelled event first, then its status.

Titles, headings, exports, tables, columns and requirements. Esc closes.