IF Commons GitHub

host/console

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

The console: the one code of IFC TypeScript that writes for a person to standard output or standard error (commons 0001-telemetry FR-024). It is a processor of the signal pipeline (src/signals.ts's Processor): every span that starts, records progress or ends and every log record goes through the kernel's pure renderer (src/render.ts), and the frames it returns are written. The mode is the one asked for (the option, else IFC_CONSOLE=attended|plain|quiet|silent|json), else attended at a terminal and plain elsewhere (system/tty's look decides what a terminal is, and whether colour and emoji may be used). In attended mode a timer, which never keeps the process alive, redraws the live region so elapsed times move. At shutdown it asks the exporting processors it watches to flush, says once, dimmed, where signals were not sent (FR-024), ends the live region and waits, a bounded time, for the writes to drain.

installUncaught makes an uncaught exception or an unhandled rejection an error log record (exception.type, exception.message, exception.stacktrace) emitted through the telemetry, so it is rendered and exported like any other signal; the telemetry is then shut down (bounded) and the process exits with status 1. Its kind, exception, is declared in uncaughtSignals, to spread into a registry.

It depends only on the kernel's interfaces, so it plugs into any telemetry.

import { createTelemetry, defineSignals } from "../signals.ts";
import { consoleProcessor, installUncaught, uncaughtSignals } from "./console.ts";
const registry = defineSignals({ ...uncaughtSignals, "build.step": { signal: "span", role: "step", attributes: { target: "string" } } });
const telemetry = createTelemetry({ registry, processors: [consoleProcessor({ registry })], ...rest });
installUncaught(telemetry);

Source: commons/telemetry/src/host/console.ts

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

consolenamespace
namespace console
console.Watchedtypeno test imports it
type Watched = { stats(): ProcessorStats; forceFlush(timeoutMs: number): Promise<FlushResult> };

A processor whose exports the console watches, to say at the end where signals were not sent (an ExportingProcessor).

console.ConsoleOptionstypeno test imports it
type ConsoleOptions = { /** The registry that gives each kind its presentation role. */ readonly registry: Registry<… (1182 characters)
type ConsoleOptions = {
  /** The registry that gives each kind its presentation role. */
  readonly registry: Registry<Declarations>;
  /** The mode; by default the one `IFC_CONSOLE` names, else `attended` at a terminal and `plain` elsewhere. */
  readonly mode?: Mode;
  /** The stream written to: standard error by default, standard output in `json` mode. */
  readonly stream?: "stdout" | "stderr";
  /** What the terminal shows; by default `currentLook` of the stream. */
  readonly look?: Look;
  /** The environment the mode is read from; this process's by default. */
  readonly env?: Readonly<Record<string, string | undefined>>;
  /** The exporting processors to ask, at shutdown, whether everything was sent. */
  readonly exporters?: readonly Watched[];
  /** How often the live region is redrawn, in milliseconds (200 by default). */
  readonly tickMs?: number;
  /** The time now, in nanoseconds since the Unix epoch, for elapsed times; the system's clock by default. */
  readonly now?: () => bigint;
  /** A signal's text from its kind and attributes (`render.ts`'s `defaultText` by default). */
  readonly text?: (name: string, attributes: Attributes) => string;
};

How a console is made; everything but the registry has a default.

console.ConsoleProcessortypeno test imports it
type ConsoleProcessor = Processor & {
  /** The mode it writes in. */
  readonly mode: Mode;
  /** Keeps a warning about an export, said once, dimmed, at the end of the run (FR-024). */
  warn(message: string): void;
};

The console: a processor, with its mode, and a way to add an export warning said at the end.

console.consoleProcessorfunctionno test imports it
function consoleProcessor(options: ConsoleOptions): ConsoleProcessor

A console processor: renders every signal it is handed and writes the frames for a person (FR-026).

console.uncaughtSignalsconstno test imports it
const uncaughtSignals: { readonly exception: { readonly signal: "log"; readonly role: "error"; readonly severity: 21; readonly description: "An uncaught exception or an unhandled rejection, after which the process exits with status 1."; readonly attributes: { readonly "exception.type": "string"; readonly "exception.message": "string"; readonly "exception.stacktrace?": "string"; }; }; }

The kind of log record an uncaught exception or an unhandled rejection becomes, to spread into a registry.

console.ExceptionAttributestypeno test imports it
type ExceptionAttributes = {
  readonly "exception.type": string;
  readonly "exception.message": string;
  readonly "exception.stacktrace"?: string;
};

The attributes of an exception log record.

console.UncaughtTargettypeno test imports it
type UncaughtTarget = {
  log(kind: "exception", attributes: ExceptionAttributes, body?: AnyValue): void;
  shutdown(timeoutMs: number): Promise<FlushResult>;
};

What installUncaught needs of a telemetry: a Telemetry whose registry declares uncaughtSignals is one.

console.UncaughtOptionstypeno test imports it
type UncaughtOptions = { readonly timeoutMs?: number; readonly exit?: (code: number) => void };

How installUncaught ends the process: the most time the telemetry has to shut down, and the exit (proc.exit by default).

console.exceptionOffunctionno test imports it
function exceptionOf(thrown: unknown): { readonly attributes: ExceptionAttributes; readonly text: string; }

The attributes and the text of the error log record for a thrown value.

console.installUncaughtfunctionno test imports it
function installUncaught(telemetry: UncaughtTarget, options?: UncaughtOptions): () => void

On an uncaught exception or an unhandled rejection: an exception log record through the telemetry (so the console renders it), the telemetry shut down within timeoutMs (1000 by default), and exit status 1 (FR-026). A second one while this happens exits at once. Returns what removes the handlers.

Watchedtypeno test imports it
type Watched = { stats(): ProcessorStats; forceFlush(timeoutMs: number): Promise<FlushResult> };

A processor whose exports the console watches, to say at the end where signals were not sent (an ExportingProcessor).

ConsoleOptionstypeno test imports it
type ConsoleOptions = { /** The registry that gives each kind its presentation role. */ readonly registry: Registry<… (1182 characters)
type ConsoleOptions = {
  /** The registry that gives each kind its presentation role. */
  readonly registry: Registry<Declarations>;
  /** The mode; by default the one `IFC_CONSOLE` names, else `attended` at a terminal and `plain` elsewhere. */
  readonly mode?: Mode;
  /** The stream written to: standard error by default, standard output in `json` mode. */
  readonly stream?: "stdout" | "stderr";
  /** What the terminal shows; by default `currentLook` of the stream. */
  readonly look?: Look;
  /** The environment the mode is read from; this process's by default. */
  readonly env?: Readonly<Record<string, string | undefined>>;
  /** The exporting processors to ask, at shutdown, whether everything was sent. */
  readonly exporters?: readonly Watched[];
  /** How often the live region is redrawn, in milliseconds (200 by default). */
  readonly tickMs?: number;
  /** The time now, in nanoseconds since the Unix epoch, for elapsed times; the system's clock by default. */
  readonly now?: () => bigint;
  /** A signal's text from its kind and attributes (`render.ts`'s `defaultText` by default). */
  readonly text?: (name: string, attributes: Attributes) => string;
};

How a console is made; everything but the registry has a default.

ConsoleProcessortypeno test imports it
type ConsoleProcessor = Processor & {
  /** The mode it writes in. */
  readonly mode: Mode;
  /** Keeps a warning about an export, said once, dimmed, at the end of the run (FR-024). */
  warn(message: string): void;
};

The console: a processor, with its mode, and a way to add an export warning said at the end.

consoleProcessorfunction
function consoleProcessor(options: ConsoleOptions): ConsoleProcessor

A console processor: renders every signal it is handed and writes the frames for a person (FR-026).

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

uncaughtSignalsconst
const uncaughtSignals: { readonly exception: { readonly signal: "log"; readonly role: "error"; readonly severity: 21; readonly description: "An uncaught exception or an unhandled rejection, after which the process exits with status 1."; readonly attributes: { readonly "exception.type": "string"; readonly "exception.message": "string"; readonly "exception.stacktrace?": "string"; }; }; }

The kind of log record an uncaught exception or an unhandled rejection becomes, to spread into a registry.

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

ExceptionAttributestypeno test imports it
type ExceptionAttributes = {
  readonly "exception.type": string;
  readonly "exception.message": string;
  readonly "exception.stacktrace"?: string;
};

The attributes of an exception log record.

UncaughtTargettype
type UncaughtTarget = {
  log(kind: "exception", attributes: ExceptionAttributes, body?: AnyValue): void;
  shutdown(timeoutMs: number): Promise<FlushResult>;
};

What installUncaught needs of a telemetry: a Telemetry whose registry declares uncaughtSignals is one.

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

UncaughtOptionstypeno test imports it
type UncaughtOptions = { readonly timeoutMs?: number; readonly exit?: (code: number) => void };

How installUncaught ends the process: the most time the telemetry has to shut down, and the exit (proc.exit by default).

exceptionOffunction
function exceptionOf(thrown: unknown): { readonly attributes: ExceptionAttributes; readonly text: string; }

The attributes and the text of the error log record for a thrown value.

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

installUncaughtfunctionno test imports it
function installUncaught(telemetry: UncaughtTarget, options?: UncaughtOptions): () => void

On an uncaught exception or an unhandled rejection: an exception log record through the telemetry (so the console renders it), the telemetry shut down within timeoutMs (1000 by default), and exit status 1 (FR-026). A second one while this happens exits at once. Returns what removes the handlers.

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