@mmutils/logger 0.0.0-stage → 0.1.0

package/dist/types/plugins/graph.d.ts

@@ -0,0 +1,243 @@
+import { type TimeUnit } from '@mmutils/time';
+import type { BakedStyles, LoggerPlugin, StyleSheet } from '../types.js';
+import { type Aggregate, type OutputLimits, type Sanitizer } from '../utils/text.js';
+import { type SanitizeOptions, type HeaderOptions } from './shared.js';
+/**
+ * Labels of the horizontal axis, displayed under the bars. Strings are shown
+ * as given. Numbers are shown as plain numbers or, when `unit` is set, as
+ * time formatted with `formatHighResTime` from `@mmutils/time`.
+ *
+ * ```ts
+ * { start: 'Mon', end: 'Fri' }                   // Mon … Fri
+ * { start: 5, end: 10 }                          // 5 … 10
+ * { start: 500, end: 1_000_500, unit: 'ns' }     // 500ns … 1ms 500ns
+ * { start: 0, end: 2025, unit: 'ms' }            // 0ms … 2s 25ms
+ * ```
+ */
+export interface GraphAxis {
+    /** Left label. */
+    readonly start?: string | number;
+    /** Right label. */
+    readonly end?: string | number;
+    /** Unit of numeric labels. When set, numbers are formatted as time. */
+    readonly unit?: TimeUnit;
+    /**
+     * Time precision: a unit or a number of units below the largest unit of the
+     * value. Default: `2`.
+     */
+    readonly capTo?: TimeUnit | number;
+}
+/**
+ * Formats an axis label. A zero time label takes the smallest unit of the
+ * other label, so both show the same precision: `0` next to `2s 25ms`
+ * reads `0ms`.
+ *
+ * @param label Label to format.
+ * @param axis Axis settings.
+ * @param other The opposite label.
+ */
+export declare const formatAxisLabel: (label: string | number | undefined, { unit, capTo }: GraphAxis, other?: string | number) => string;
+/**
+ * Where the bars of a graph start: a value, or the bottom (`'min'`) or the
+ * top (`'max'`) of the graph.
+ */
+export type GraphBaseline = number | 'min' | 'max';
+export interface GraphSettings {
+    /**
+     * Number of bar columns: the resolution values are scaled to, like `rows`
+     * for the height. The frame adds 2 characters, so the graph is `cols + 2`
+     * terminal columns wide; use `width` to set that instead. Default: `30`.
+     */
+    readonly cols?: number;
+    /**
+     * Total width in terminal columns, frame included: `width: 64` draws 62
+     * bars and every row is exactly 64 characters wide, e.g. to fit a layout
+     * column. Replaces `cols`: setting both on the plugin throws; per graph,
+     * `width` wins. At least `3`.
+     */
+    readonly width?: number;
+    /** Graph height in rows. Default: `3`. */
+    readonly rows?: number;
+    /** Title in the top row. Default: `''`. */
+    readonly title?: string;
+    /**
+     * Top of the graph. Values above it draw full bars, or nothing when the
+     * baseline is the top. Not lower than a numeric `baseline`. Default: the
+     * maximum of the original values, raised to a numeric `baseline`.
+     */
+    readonly max?: number;
+    /**
+     * Bottom of the graph. Values below it draw full bars, or nothing when the
+     * baseline is the bottom. Not higher than a numeric `baseline`. Default:
+     * the minimum of the original values, lowered to a numeric `baseline`.
+     */
+    readonly min?: number;
+    /**
+     * Where the bars start: bars grow from it up to values above it and down
+     * to values below it, in the same color. Default: `0`, moved inside `min`
+     * and `max` when they leave it out (`min: 480` alone starts at 480).
+     *
+     * - A number: the range always holds it, so with values from 80 to 85 the
+     *   bars grow from 0. Inside the range it splits the graph.
+     * - `'min'`: the bottom of the graph; bars only grow up. Zooms in on
+     *   values far from zero; the smallest value draws no bar.
+     * - `'max'`: the top of the graph; bars only grow down.
+     *
+     * A split graph places the baseline in proportion to the range, on one
+     * scale for both sides, so equal distances draw equal bars. A side gets
+     * rows only if its longest bar draws at least an eighth of a row.
+     */
+    readonly baseline?: GraphBaseline;
+    /**
+     * How values sharing a column are combined when scaled to `cols`:
+     * `'average'` (smooth trend), `'max'` (keeps peaks, e.g. latency spikes) or
+     * `'min'` (keeps dips). Statistics always use the original values.
+     * Default: `'average'`.
+     */
+    readonly aggregate?: Aggregate;
+    /** Unit appended to displayed values, e.g. `'%'`. Default: `''`. */
+    readonly unit?: string;
+    /** Displayed values precision. Default: `2`. */
+    readonly precision?: number;
+    /** Show the average value row. Default: `true`. */
+    readonly showAverage?: boolean;
+    /** Show the minimum value row. Default: `true`. */
+    readonly showMin?: boolean;
+    /** Show the maximum value row. Default: `true`. */
+    readonly showMax?: boolean;
+    /** Horizontal axis labels row under the bars. Default: none. */
+    readonly axis?: GraphAxis;
+}
+/**
+ * Data accepted by the graph kind: plain values or values with settings that
+ * override the plugin's settings for a single log.
+ */
+export type GraphData = readonly number[] | GraphDataWithSettings;
+export interface GraphDataWithSettings extends GraphSettings {
+    readonly values: readonly number[];
+}
+export interface GraphLimits extends OutputLimits {
+    /** Maximum `cols`. Default: `500`. */
+    readonly cols?: number;
+    /** Maximum `rows`. Default: `50`. */
+    readonly rows?: number;
+    /** Maximum `precision`, at most `100`. Default: `20`. */
+    readonly precision?: number;
+}
+export declare const DEFAULT_GRAPH_LIMITS: {
+    readonly cols: 500;
+    readonly rows: 50;
+    readonly precision: 20;
+};
+export interface GraphPluginOptions extends HeaderOptions, SanitizeOptions, GraphSettings {
+    /**
+     * Upper limits of the size settings. Kept out of the per-log settings, so
+     * logged data can't raise them. Default: `DEFAULT_GRAPH_LIMITS`.
+     */
+    readonly limits?: GraphLimits;
+    /** Kind rendered by this plugin. Default: `'graph'`. */
+    readonly kind?: string;
+    /** Styles merged over the default text styles. */
+    readonly styles?: StyleSheet;
+    /** String destination. Default: `console.log`. */
+    readonly write?: (text: string) => void;
+}
+/**
+ * Logs a graph of values.
+ *
+ * @param values Values to plot.
+ * @param settings Settings for this graph only.
+ */
+export type GraphMethod = (values: readonly number[], settings?: GraphSettings) => void;
+/**
+ * Graph method per log type: `infoGraph`, `errorGraph`, etc.
+ */
+export interface GraphMethods {
+    /**
+     * Logs a bar graph of values with fatal level.
+     *
+     * @param values Numeric values to plot. Scaled to the graph's columns.
+     * @param settings Settings for this graph only, e.g. `{ title: 'CPU' }`.
+     */
+    fatalGraph(values: readonly number[], settings?: GraphSettings): void;
+    /**
+     * Logs a bar graph of values with error level.
+     *
+     * @param values Numeric values to plot. Scaled to the graph's columns.
+     * @param settings Settings for this graph only, e.g. `{ title: 'CPU' }`.
+     */
+    errorGraph(values: readonly number[], settings?: GraphSettings): void;
+    /**
+     * Logs a bar graph of values with warning level.
+     *
+     * @param values Numeric values to plot. Scaled to the graph's columns.
+     * @param settings Settings for this graph only, e.g. `{ title: 'CPU' }`.
+     */
+    warningGraph(values: readonly number[], settings?: GraphSettings): void;
+    /**
+     * Logs a bar graph of values with info level.
+     *
+     * @param values Numeric values to plot. Scaled to the graph's columns.
+     * @param settings Settings for this graph only, e.g. `{ title: 'CPU' }`.
+     */
+    infoGraph(values: readonly number[], settings?: GraphSettings): void;
+    /**
+     * Logs a bar graph of values with debug level.
+     *
+     * @param values Numeric values to plot. Scaled to the graph's columns.
+     * @param settings Settings for this graph only, e.g. `{ title: 'CPU' }`.
+     */
+    debugGraph(values: readonly number[], settings?: GraphSettings): void;
+    /**
+     * Logs a bar graph of values with trace level.
+     *
+     * @param values Numeric values to plot. Scaled to the graph's columns.
+     * @param settings Settings for this graph only, e.g. `{ title: 'CPU' }`.
+     */
+    traceGraph(values: readonly number[], settings?: GraphSettings): void;
+    /**
+     * Logs a bar graph of values with verbose level.
+     *
+     * @param values Numeric values to plot. Scaled to the graph's columns.
+     * @param settings Settings for this graph only, e.g. `{ title: 'CPU' }`.
+     */
+    verboseGraph(values: readonly number[], settings?: GraphSettings): void;
+}
+type ResolvedGraphSettings = Required<Omit<GraphSettings, 'max' | 'min' | 'axis' | 'width' | 'baseline'>> & Pick<GraphSettings, 'max' | 'min' | 'axis' | 'baseline'>;
+/**
+ * Converts values to rows of bar symbols growing up from `min`, top row
+ * first.
+ *
+ * @param max Top of the graph: higher values draw full bars.
+ * @param min Bottom of the graph. Default: `0`.
+ */
+export declare const valuesToBars: (values: readonly number[], rows: number, max: number, min?: number) => string[];
+/**
+ * Renders a framed graph with an optional axis row and value statistics:
+ * title, bars, frame and values in `textHighlight`, legend labels in
+ * `textNormal`, axis labels and units in `textDim`. When the baseline splits
+ * the graph, a `baseline` row follows the average.
+ *
+ * Average, min, max and the default top and bottom are computed from the
+ * original values, so peaks blunted by scaling are still reported. Bars are
+ * scaled to `cols` with `settings.aggregate`. The top value is shown on the
+ * title row, the bottom value on the average row.
+ *
+ * Title, unit and axis labels are sanitized as single line `label`s and
+ * measured in terminal columns with `textWidth` (wide characters take two,
+ * as in columns). Default: `'safe'` (see `Sanitize`).
+ */
+export declare const renderGraph: (values: readonly number[], settings: ResolvedGraphSettings, { textNormal, textDim, textHighlight, reset, }?: BakedStyles, { label }?: Sanitizer) => string;
+/**
+ * Renders logs of a given kind as bar graphs. Adds a graph method per log
+ * type to the logger: `infoGraph`, `errorGraph`, etc.
+ *
+ * ```
+ * 2026/03/16 15:35:00 [i]   info
+ * CPU                      82.00 %
+ * │▁▁▁▂▃▃▃▄▄▄▆▆▆▇██▇▆▆▆▄▄▄▃▃▃▂▁▁▁│
+ * average: 41.33 %          0.00 %
+ * ```
+ */
+export declare const graphPlugin: (options?: GraphPluginOptions) => LoggerPlugin<GraphMethods>;
+export {};

package/dist/types/plugins/json.d.ts

@@ -0,0 +1,169 @@
+import type { LoggerPlugin } from '../types.js';
+import { type OutputLimits } from '../utils/text.js';
+type Limits = Required<OutputLimits>;
+/**
+ * Time of a JSON line, in its `time` property, from the logger's clock:
+ * - `'iso'`: ISO 8601 in UTC, a string: `"2026-03-16T15:35:00.000Z"`, with
+ *   9 fraction digits with the `'precise'` clock;
+ * - `'epoch'`: epoch milliseconds, a number: `1773675300000`; with the
+ *   `'precise'` clock followed by `"ns"`, the nanoseconds within the
+ *   millisecond;
+ * - `false`: no `time`.
+ */
+export type JsonTime = 'epoch' | 'iso' | false;
+export interface JsonPluginOptions {
+    /** Kind rendered by this plugin. Default: `'json'`. */
+    readonly kind?: string;
+    /**
+     * Make `kind` the logger's default kind, so all logs without an explicit
+     * kind are written as JSON lines. The last plugin used that sets the
+     * default wins. Use `jsonPlugin` instead of `messagePlugin`, not next to
+     * it: both render the whole log. Default: `true`.
+     */
+    readonly setAsDefault?: boolean;
+    /**
+     * Format of the `time` property, from the logger's `clock`. Lines have no
+     * time when the logger's `timestamp` is `false`. Default: `'iso'`.
+     */
+    readonly time?: JsonTime;
+    /**
+     * Output size limits: elements and keys per object, characters per string
+     * and per nested JSON value. `Infinity` turns a limit off. Default:
+     * `DEFAULT_OUTPUT_LIMITS` (`{ items: 100, stringLength: 10_000 }`).
+     */
+    readonly limits?: OutputLimits;
+    /**
+     * Also escape DEL and C1 control characters (`U+007F`-`U+009F`) as
+     * `\u00XX`. `JSON.stringify` escapes C0 controls (including ESC and
+     * newlines) but writes these raw; some terminals act on C1 controls when
+     * the lines are shown raw (`cat`, `tail -f`). The parsed JSON is the same.
+     * Costs about 1 ns per character. Default: `false`.
+     */
+    readonly escapeControls?: boolean;
+    /**
+     * Write the log's `kind` after `type`, e.g. `"kind":"audit"`. Turn it on
+     * when several JSON kinds share a destination (all logs to stdout in a
+     * container), so readers can tell them apart. Default: `false` (one
+     * destination per kind makes it redundant).
+     */
+    readonly writeKind?: boolean;
+    /** Line destination, called once per log. Default: `console.log`. */
+    readonly write?: (line: string) => void;
+}
+/**
+ * Serializes logged data to JSON text. Never throws, and always returns
+ * valid JSON (or `undefined`, like `JSON.stringify`, for `undefined`):
+ * - ordinary data is one native `JSON.stringify`;
+ * - errors, also as property values and from other realms:
+ *   `{"name","message","stack",...own properties,"cause"}`, causes up to 5
+ *   deep;
+ * - buffers and typed arrays: a one-line description (`describeBinary`);
+ * - bigints: JSON numbers with every digit; functions and symbols:
+ *   `"[Function: name]"`, `"Symbol(x)"`, never source code;
+ * - maps, sets and regular expressions: a description (`describeObject`);
+ * - strings longer than `stringLength`: cut, with `… N more characters`;
+ * - arrays and objects longer than `items` (the data and its direct
+ *   properties): the first `items` and `"… N more items"`;
+ * - arrays and objects whose JSON is longer than `stringLength`: cut
+ *   structurally, keeping their type (`cutJson`);
+ * - throwing getters and revoked proxies: placeholder strings; circular
+ *   references: `"[Circular]"`; the rest of the data still renders and
+ *   keeps its type.
+ *
+ * Errors, binary data, bigints, functions and long arrays are found one
+ * level deep only: in the data and in its direct properties (`{ err }`).
+ * This is for performance: ordinary data is one native `JSON.stringify`,
+ * and a walker for every object would slow down all logs. Deeper ones get
+ * native JSON, so a deeper error keeps only its own enumerable properties
+ * (`{ request: { err } }` loses message and stack).
+ *
+ * @param limits Output limits. Default: `DEFAULT_OUTPUT_LIMITS`.
+ */
+export declare const renderJsonData: (data: unknown, limits?: Limits) => string | undefined;
+/**
+ * Log methods re-declared by `jsonPlugin` when it becomes the default kind:
+ * any data, written as one JSON line.
+ */
+export interface JsonMethods {
+    /**
+     * Logs a fatal error that leads to an immediate halt of all operations, as
+     * a JSON line.
+     *
+     * @param data Any value, written as the line's `data`. Errors keep their
+     * name, message, stack, properties and cause.
+     * @param kind Log kind. Default: `'json'`.
+     */
+    fatal(data: unknown, kind?: string): void;
+    /**
+     * Logs an error that might lead to a halt of the current operation, as a
+     * JSON line.
+     *
+     * @param data Any value, written as the line's `data`. Errors keep their
+     * name, message, stack, properties and cause.
+     * @param kind Log kind. Default: `'json'`.
+     */
+    error(data: unknown, kind?: string): void;
+    /**
+     * Logs a warning about something that might produce an unexpected result
+     * later in the execution, as a JSON line.
+     *
+     * @param data Any value, written as the line's `data`.
+     * @param kind Log kind. Default: `'json'`.
+     */
+    warning(data: unknown, kind?: string): void;
+    /**
+     * Logs an important milestone of the execution flow, relevant in
+     * production, as a JSON line.
+     *
+     * @param data Any value, written as the line's `data`.
+     * @param kind Log kind. Default: `'json'`.
+     */
+    info(data: unknown, kind?: string): void;
+    /**
+     * Logs information that helps to debug a problem, as a JSON line.
+     *
+     * @param data Any value, written as the line's `data`.
+     * @param kind Log kind. Default: `'json'`.
+     */
+    debug(data: unknown, kind?: string): void;
+    /**
+     * Logs an execution checkpoint, to narrow down the execution path, as a
+     * JSON line.
+     *
+     * @param data Any value, written as the line's `data`.
+     * @param kind Log kind. Default: `'json'`.
+     */
+    trace(data: unknown, kind?: string): void;
+    /**
+     * Logs information of importance during a close examination of the
+     * execution flow, as a JSON line.
+     *
+     * @param data Any value, written as the line's `data`.
+     * @param kind Log kind. Default: `'json'`.
+     */
+    verbose(data: unknown, kind?: string): void;
+}
+/**
+ * Methods typed by `jsonPlugin`: the re-declared log methods, unless the
+ * plugin does not become the default kind.
+ */
+export type JsonPluginMethods<O extends JsonPluginOptions> = O extends {
+    readonly setAsDefault: false;
+} ? object : JsonMethods;
+/**
+ * Writes logs of a given kind as JSON lines (NDJSON) and, by default, makes
+ * that kind the logger's default, so `logger.info({ user: 'alice' })`
+ * writes:
+ *
+ * ```
+ * {"id":1,"time":"2026-03-16T15:35:00.000Z","type":"info","data":{"user":"alice"}}
+ * ```
+ *
+ * Logging never throws because of the data; see `renderJsonData`. Errors of
+ * `write` propagate.
+ *
+ * @throws RangeError if `time` or `limits` are invalid.
+ * @throws TypeError if `write` is not a function.
+ */
+export declare const jsonPlugin: <const O extends JsonPluginOptions = JsonPluginOptions>(options?: O) => LoggerPlugin<JsonPluginMethods<O>>;
+export {};

package/dist/types/plugins/message.d.ts

@@ -0,0 +1,181 @@
+import type { BakedStyles, LoggerPlugin, StyleSheet } from '../types.js';
+import { type OutputLimits, type Sanitizer } from '../utils/text.js';
+import { type HeaderOptions, type SanitizeOptions } from './shared.js';
+export interface MessagePluginOptions extends HeaderOptions, SanitizeOptions {
+    /**
+     * Output size limits: elements and keys per object, characters per string.
+     * `Infinity` turns a limit off. Default: `DEFAULT_OUTPUT_LIMITS`
+     * (`{ items: 100, stringLength: 10_000 }`).
+     */
+    readonly limits?: OutputLimits;
+    /** Kind rendered by this plugin. Default: `'message'`. */
+    readonly kind?: string;
+    /**
+     * Make `kind` the logger's default kind, so all logs without an explicit
+     * kind are rendered as messages. The last plugin used that sets the
+     * default wins. Use `messagePlugin` instead of `jsonPlugin`, not next to
+     * it: both render the whole log. Default: `true`.
+     */
+    readonly setAsDefault?: boolean;
+    /** Styles merged over the default text styles. */
+    readonly styles?: StyleSheet;
+    /** String destination. Default: `console.log`. */
+    readonly write?: (text: string) => void;
+}
+/**
+ * Renders message data with the text styles:
+ * - strings: `textHighlight`, on the header line;
+ * - errors: `name: message` in `textHighlight` and stack frames in `textDim`,
+ *   below the header;
+ * - objects and arrays: one `key: value` per line below the header, keys in
+ *   `textNormal` and JSON values in `textHighlight`; empty ones inline in
+ *   `textDim`;
+ * - other values: `textNormal`, on the header line.
+ *
+ * Strings, symbols, functions and error messages are sanitized as `text`;
+ * keys, values and stack frames as `label`. Default: `'safe'` (see
+ * `Sanitize`).
+ *
+ * Never throws: data that can't be read (throwing getters, revoked proxies,
+ * broken errors) gives dim placeholders.
+ */
+export declare const renderMessageData: (data: unknown, styles: BakedStyles, sanitizer?: Sanitizer, limits?: Required<OutputLimits>) => string;
+/**
+ * Log methods re-declared by `messagePlugin` when it becomes the default kind:
+ * the data is a text message, rendered as a styled line.
+ */
+export interface MessageMethods {
+    /**
+     * Logs a fatal error that leads to an immediate halt of all operations, as
+     * a styled text line.
+     *
+     * @param message Text to display.
+     * @param kind Log kind. Default: `'message'`.
+     */
+    fatal(message: string, kind?: string): void;
+    /**
+     * Logs a fatal error that leads to an immediate halt of all operations.
+     *
+     * @param data Object or array (each property on a new line) or error
+     * (message and stack on new lines).
+     * @param kind Log kind. Default: `'message'`.
+     */
+    fatal(data: object, kind?: string): void;
+    /**
+     * Logs an error that might lead to a halt of the current operation, as a
+     * styled text line.
+     *
+     * @param message Text to display.
+     * @param kind Log kind. Default: `'message'`.
+     */
+    error(message: string, kind?: string): void;
+    /**
+     * Logs an error that might lead to a halt of the current operation.
+     *
+     * @param data Object or array (each property on a new line) or error
+     * (message and stack on new lines).
+     * @param kind Log kind. Default: `'message'`.
+     */
+    error(data: object, kind?: string): void;
+    /**
+     * Logs a warning about something that might produce an unexpected result
+     * later in the execution, as a styled text line.
+     *
+     * @param message Text to display.
+     * @param kind Log kind. Default: `'message'`.
+     */
+    warning(message: string, kind?: string): void;
+    /**
+     * Logs a warning about something that might produce an unexpected result
+     * later in the execution.
+     *
+     * @param data Object or array (each property on a new line) or error
+     * (message and stack on new lines).
+     * @param kind Log kind. Default: `'message'`.
+     */
+    warning(data: object, kind?: string): void;
+    /**
+     * Logs an important milestone of the execution flow, relevant in
+     * production, as a styled text line.
+     *
+     * @param message Text to display.
+     * @param kind Log kind. Default: `'message'`.
+     */
+    info(message: string, kind?: string): void;
+    /**
+     * Logs an important milestone of the execution flow, relevant in
+     * production.
+     *
+     * @param data Object or array (each property on a new line) or error
+     * (message and stack on new lines).
+     * @param kind Log kind. Default: `'message'`.
+     */
+    info(data: object, kind?: string): void;
+    /**
+     * Logs information that helps to debug a problem, as a styled text line.
+     *
+     * @param message Text to display.
+     * @param kind Log kind. Default: `'message'`.
+     */
+    debug(message: string, kind?: string): void;
+    /**
+     * Logs information that helps to debug a problem.
+     *
+     * @param data Object or array (each property on a new line) or error
+     * (message and stack on new lines).
+     * @param kind Log kind. Default: `'message'`.
+     */
+    debug(data: object, kind?: string): void;
+    /**
+     * Logs an execution checkpoint, to narrow down the execution path, as a
+     * styled text line.
+     *
+     * @param message Text to display.
+     * @param kind Log kind. Default: `'message'`.
+     */
+    trace(message: string, kind?: string): void;
+    /**
+     * Logs an execution checkpoint, to narrow down the execution path.
+     *
+     * @param data Object or array (each property on a new line) or error
+     * (message and stack on new lines).
+     * @param kind Log kind. Default: `'message'`.
+     */
+    trace(data: object, kind?: string): void;
+    /**
+     * Logs information of importance during a close examination of the
+     * execution flow, as a styled text line.
+     *
+     * @param message Text to display.
+     * @param kind Log kind. Default: `'message'`.
+     */
+    verbose(message: string, kind?: string): void;
+    /**
+     * Logs information of importance during a close examination of the
+     * execution flow.
+     *
+     * @param data Object or array (each property on a new line) or error
+     * (message and stack on new lines).
+     * @param kind Log kind. Default: `'message'`.
+     */
+    verbose(data: object, kind?: string): void;
+}
+/**
+ * Methods typed by `messagePlugin`: the re-declared log methods, unless the
+ * plugin does not become the default kind.
+ */
+export type MessagePluginMethods<O extends MessagePluginOptions> = O extends {
+    readonly setAsDefault: false;
+} ? object : MessageMethods;
+/**
+ * Renders logs of a given kind as styled text and, by default, makes that
+ * kind the logger's default, so `logger.info('Server started')` prints:
+ *
+ * ```
+ * 2026/03/16 15:35:00 [i]   info    Server started
+ * ```
+ *
+ * Objects and arrays print each property on a new line; errors print their
+ * message and stack on new lines. See `renderMessageData` for the styles.
+ */
+export declare const messagePlugin: <const O extends MessagePluginOptions = MessagePluginOptions>(options?: O) => LoggerPlugin<MessagePluginMethods<O>>;

package/dist/types/plugins/shared.d.ts

@@ -0,0 +1,74 @@
+import type { BakedStyles, LogType, StyleSheet, TemplateMap } from '../types.js';
+import { type Sanitize, type Sanitizer } from '../utils/text.js';
+/**
+ * Default text styles shared by the bundled plugins. Plugins may override
+ * them by registering the same style names.
+ *
+ * - `textDim`: secondary information: id, timestamp, symbols, units and
+ *   stack frames. Gray.
+ * - `textNormal`: the terminal's default text style: object keys, graph
+ *   legend labels, other values.
+ * - `textHighlight`: text messages, error messages, object values; graph
+ *   titles, bars, frames and values. The level's color, bold.
+ * - `textBadge`: log type badge, the level's color as background.
+ *
+ * Colors: red for fatal (its badge white on red), bright red for error,
+ * yellow for warning, blue for info, magenta for debug, cyan for trace and
+ * gray (bright black) for verbose. They are the terminal's 16 basic colors,
+ * so they follow its theme.
+ */
+export declare const DEFAULT_TEXT_STYLES: StyleSheet;
+/**
+ * Wraps text in a style and a reset. Empty text or an empty style produce no
+ * escape codes.
+ */
+export declare const paint: (style: string, text: string, reset: string) => string;
+/**
+ * Dim placeholder for data whose rendering threw, so logging never throws
+ * because of the logged data.
+ */
+export declare const paintUnrenderable: (thrown: unknown, { textDim, reset }: BakedStyles, { label }: Sanitizer) => string;
+/**
+ * Merges style sheets group by group, so overriding one style of a type keeps
+ * the other base styles of that type.
+ *
+ * The result has no prototype and reads own groups only, so a `__proto__` key
+ * (e.g. from a sheet parsed from JSON) is a plain, unused group instead of
+ * replacing the sheet's prototype.
+ */
+export declare const mergeStyleSheets: (base: StyleSheet, override: StyleSheet | undefined) => StyleSheet;
+export interface SanitizeOptions {
+    /**
+     * Sanitization of logged text: strings, object keys and values, errors and
+     * graph labels. See `Sanitize`. Default: `'safe'`.
+     */
+    readonly sanitize?: Sanitize;
+}
+/**
+ * Default symbols in front of the type badge: three ASCII characters each,
+ * which every terminal and font draws, one column per character. Emoji are
+ * missing from some fonts and their width differs between terminals, which
+ * shifts the badge.
+ */
+export declare const DEFAULT_SYMBOLS: Readonly<Record<LogType, string>>;
+/** One symbol for every log type, or symbols per type. */
+export type Symbols = string | Readonly<Partial<Record<LogType, string>>>;
+export interface HeaderOptions {
+    /** Show the log id. Default: `false`. */
+    readonly showId?: boolean;
+    /**
+     * Symbol in front of the type badge. A string is used as is for every
+     * type (`''` for none). Symbols per type are merged over
+     * `DEFAULT_SYMBOLS` (`undefined` keeps the default) and padded with spaces
+     * to the widest one plus one, so the badges line up. Default:
+     * `DEFAULT_SYMBOLS`.
+     */
+    readonly symbol?: Symbols;
+}
+/**
+ * Template functions rendering the common log header: dim id, timestamp and
+ * symbol, the type badge and a hidden kind.
+ *
+ * @throws TypeError if a symbol is not a string.
+ */
+export declare const headerTemplates: ({ showId, symbol, }: HeaderOptions) => TemplateMap;