rendernamespacenamespace renderThe 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);rendernamespacenamespace renderrender.Modetypetype Mode = "attended" | "plain" | "quiet" | "silent" | "json";How the console writes: see the module.
render.MODESconstconst MODES: readonly Mode[]Every mode, in a fixed order.
render.parseModefunctionfunction parseMode(text: string): Mode | undefinedA mode by its name; undefined for another text.
render.chooseModefunctionfunction chooseMode(facts: { readonly requested?: string | undefined; readonly tty: boolean; }): ModeThe mode to use: the one asked for where it names one, else attended at a terminal and plain elsewhere (FR-026).
render.Inputtypetype 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.
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.
render.Statetypetype 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.
render.Steptypetype Step = { readonly state: State; readonly frames: string };A reducer's step: the next state and the frames to write (empty for none).
render.initialfunctionfunction initial(config: RenderConfig): StateThe state a renderer starts in.
render.cleanfunctionfunction clean(text: string): stringA text with every control character but the line feed replaced (a tab by a space, the rest by ?), so it never moves the cursor.
render.defaultTextfunctionfunction defaultText(name: string, attributes: Readonly<Record<string, AttributeValue>>, signal?: "log" | "span"): stringThe 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).
render.durationfunctionfunction duration(ns: bigint): stringA duration in nanoseconds as a person reads it: 420ms, 1.2s, 3m04s, 2h05m (cut, never rounded up; a negative one is 0ms).
render.progressTextfunctionfunction progressText(done: number, total?: number | undefined): stringHow far a span has come: done/total and the percentage where there is a positive total, else done.
render.outcomeOffunctionfunction outcomeOf(span: SpanData): MarkKindHow a span ended, as a mark: a skipped or cancelled event first, then its status.
render.renderfunctionfunction render(state: State, input: Input, now: bigint): StepThe 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.
Modetypetype Mode = "attended" | "plain" | "quiet" | "silent" | "json";How the console writes: see the module.
MODESconstno test imports itconst MODES: readonly Mode[]Every mode, in a fixed order.
parseModefunctionfunction parseMode(text: string): Mode | undefinedA mode by its name; undefined for another text.
chooseModefunctionfunction chooseMode(facts: { readonly requested?: string | undefined; readonly tty: boolean; }): ModeThe mode to use: the one asked for where it names one, else attended at a terminal and plain elsewhere (FR-026).
Inputtypetype 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.
RenderConfigtypeno test imports ittype 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.
Statetypetype 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.
Steptypeno test imports ittype Step = { readonly state: State; readonly frames: string };A reducer's step: the next state and the frames to write (empty for none).
initialfunctionfunction initial(config: RenderConfig): StateThe state a renderer starts in.
cleanfunctionno test imports itfunction clean(text: string): stringA 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 itfunction defaultText(name: string, attributes: Readonly<Record<string, AttributeValue>>, signal?: "log" | "span"): stringThe 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).
durationfunctionfunction duration(ns: bigint): stringA duration in nanoseconds as a person reads it: 420ms, 1.2s, 3m04s, 2h05m (cut, never rounded up; a negative one is 0ms).
progressTextfunctionfunction progressText(done: number, total?: number | undefined): stringHow far a span has come: done/total and the percentage where there is a positive total, else done.
outcomeOffunctionno test imports itfunction outcomeOf(span: SpanData): MarkKindHow a span ended, as a mark: a skipped or cancelled event first, then its status.