consolenamespacenamespace consoleThe 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);consolenamespacenamespace consoleconsole.Watchedtypeno test imports ittype 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 ittype 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 ittype 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 itfunction consoleProcessor(options: ConsoleOptions): ConsoleProcessorA console processor: renders every signal it is handed and writes the frames for a person (FR-026).
console.uncaughtSignalsconstno test imports itconst 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 ittype ExceptionAttributes = {
readonly "exception.type": string;
readonly "exception.message": string;
readonly "exception.stacktrace"?: string;
};The attributes of an exception log record.
console.UncaughtTargettypeno test imports ittype 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 ittype 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 itfunction 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 itfunction installUncaught(telemetry: UncaughtTarget, options?: UncaughtOptions): () => voidOn 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 ittype 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 ittype 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 ittype 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.
consoleProcessorfunctionfunction consoleProcessor(options: ConsoleOptions): ConsoleProcessorA console processor: renders every signal it is handed and writes the frames for a person (FR-026).
uncaughtSignalsconstconst 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.
ExceptionAttributestypeno test imports ittype ExceptionAttributes = {
readonly "exception.type": string;
readonly "exception.message": string;
readonly "exception.stacktrace"?: string;
};The attributes of an exception log record.
UncaughtTargettypetype 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.
UncaughtOptionstypeno test imports ittype 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).
exceptionOffunctionfunction exceptionOf(thrown: unknown): { readonly attributes: ExceptionAttributes; readonly text: string; }The attributes and the text of the error log record for a thrown value.
installUncaughtfunctionno test imports itfunction installUncaught(telemetry: UncaughtTarget, options?: UncaughtOptions): () => voidOn 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.