@mmutils/logger 0.0.0-stage → 0.1.0

package/dist/types/time.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Default timestamp pattern, local time: `2026/03/16 15:35:00`. Change the
+ * default here; see `compileTimestamp` for the tokens.
+ */
+export declare const DEFAULT_TIMESTAMP_FORMAT = "YYYY/MM/DD HH:mm:ss";
+/**
+ * Formats the time of a log.
+ *
+ * @param time Epoch time in whole milliseconds.
+ * @param timeNs Nanoseconds within the millisecond (0-999,999); `0` unless
+ * the logger's clock is `'precise'`.
+ */
+export type TimestampFormatter = (time: number, timeNs: number) => string;
+export interface CompileTimestampOptions {
+    /** Format the time in UTC instead of local time. Default: `false`. */
+    readonly utc?: boolean;
+    /**
+     * Start of the elapsed time tokens (`E`, `EEE`), as epoch milliseconds and
+     * nanoseconds within the millisecond. Default: when the pattern is
+     * compiled, from `Date.now()`.
+     */
+    readonly start?: readonly [time: number, timeNs: number];
+}
+/**
+ * Compiles a timestamp pattern once, dayjs-style:
+ *
+ * | Token | Output |
+ * | --- | --- |
+ * | `YYYY` `YY` | `2026` `26` |
+ * | `MMMM` `MMM` `MM` `M` | `March` `Mar` `03` `3` |
+ * | `DD` `D` | `16` `16` |
+ * | `dddd` `ddd` | `Monday` `Mon` |
+ * | `HH` `H` | `15` `15` (24 hours) |
+ * | `hh` `h` `A` `a` | `03` `3` `PM` `pm` (12 hours) |
+ * | `mm` `m`, `ss` `s` | minutes, seconds |
+ * | `SSS` `SSSSSS` `SSSSSSSSS` | milliseconds, microseconds, nanoseconds |
+ * | `Z` `ZZ` | `+02:00` `+0200` |
+ * | `E` | elapsed since the start: `+1s 32ms 400µs` |
+ * | `EEE` | elapsed in milliseconds: `+1032.400123ms` |
+ * | `[text]` | `text` as is |
+ *
+ * Other characters are written as is. Text that changes at most once per
+ * second is rendered with `Date` getters and cached, so a log only pays a
+ * comparison plus its fraction and elapsed tokens.
+ *
+ * @throws RangeError when formatting a time that is not a finite number.
+ */
+export declare const compileTimestamp: (pattern: string, { utc, start }?: CompileTimestampOptions) => TimestampFormatter;

package/dist/types/types.d.ts

@@ -0,0 +1,176 @@
+import type { SecProperty } from 'style-escape-codes';
+import type { BaseLogger } from './logger.js';
+import type { TimestampFormatter } from './time.js';
+/**
+ * Supported logging levels, ordered from the lowest verbosity (`'silent'`),
+ * which suppresses all output, to the highest verbosity (`'verbose'`).
+ */
+export type LogLevel = 'silent' | 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'trace' | 'verbose';
+/**
+ * Actual message log type. Excludes `'silent'` as a message can not be silent.
+ */
+export type LogType = Exclude<LogLevel, 'silent'>;
+/**
+ * Log object travelling through the transformers pipeline. The logger creates
+ * it with `id`, `timestamp` (when enabled), `type`, `kind` and `data` keys, in
+ * that order. Each log gets its own fresh object, so transformers are free to
+ * mutate it.
+ */
+export type LogEntry = Record<string, unknown>;
+/**
+ * Named ANSI escape code strings, baked once for a particular log type.
+ * When styles are disabled every value is an empty string.
+ */
+export type BakedStyles = Readonly<Record<string, string>>;
+/**
+ * Per-log information shared by transformers, template functions and outputs.
+ */
+export interface LogContext {
+    readonly type: LogType;
+    readonly kind: string;
+    /**
+     * Epoch time of the log in whole milliseconds, read once from the logger's
+     * `clock`; the entry's `timestamp` is formatted from it. `undefined` when
+     * timestamps are off (`timestamp: false`). For outputs that need machine
+     * time, e.g. JSON.
+     */
+    readonly time?: number | undefined;
+    /**
+     * Nanoseconds within `time`'s millisecond (0-999,999), only with the
+     * `'precise'` clock; `undefined` otherwise (millisecond resolution).
+     */
+    readonly timeNs?: number | undefined;
+    /** Styles baked for `type`. */
+    readonly styles: BakedStyles;
+    /** Template map registered for `kind`, if any. */
+    readonly templateMap: TemplateMap | undefined;
+}
+/**
+ * A single step of the pipeline. Receives the current entry and returns the
+ * entry to be passed to the next step.
+ */
+export type Transformer = (entry: LogEntry, ctx: LogContext) => LogEntry;
+/**
+ * Converts a single log entry property.
+ *
+ * @param value Current value of the property.
+ * @param ctx Current log context.
+ * @param key Name of the property.
+ */
+export type TemplateFn = (value: unknown, ctx: LogContext, key: string) => unknown;
+/**
+ * Template functions keyed by log entry property name. Properties without a
+ * template function pass through unchanged.
+ */
+export type TemplateMap = Readonly<Record<string, TemplateFn>>;
+/**
+ * Final destination of a log entry, after all transformers were applied.
+ */
+export type Output = (entry: LogEntry, ctx: LogContext) => void;
+/**
+ * Anything that can be baked to an escape code string: a raw string or a
+ * `style-escape-codes` chain such as `sec.b.fgRed`.
+ */
+export type StyleInput = string | SecProperty;
+/**
+ * Named styles grouped by log type. Styles under `'*'` apply to all types and
+ * are overridden by type specific ones.
+ */
+export type StyleSheet = Partial<Record<LogType | '*', Readonly<Record<string, StyleInput>>>>;
+/**
+ * Transformer with an optional position in the logger's transformers list.
+ * Without position it is appended.
+ */
+export interface PluginTransformer {
+    readonly transformer: Transformer;
+    readonly position?: number;
+}
+/**
+ * Extension of the logger. Plugins own their configuration (usually taken by a
+ * plugin factory function), so the logger never has to know its shape.
+ *
+ * @template M Methods the plugin adds to the logger's type, usually created by
+ * `methods`. A plugin may also re-declare existing logger methods (e.g. to
+ * narrow parameters and replace docs after changing the default kind) without
+ * implementing them in `methods`.
+ */
+export interface LoggerPlugin<M extends object = object> {
+    /** Unique plugin name. A plugin can be used only once per logger. */
+    readonly name: string;
+    /** Styles available to all template maps and outputs. */
+    readonly styles?: StyleSheet;
+    /** Template maps keyed by log kind. Merged with existing maps. */
+    readonly templateMaps?: Readonly<Record<string, TemplateMap>>;
+    /** Transformers to be inserted into the pipeline. */
+    readonly transformers?: readonly PluginTransformer[];
+    /** Outputs keyed by log kind. Replace the default output for that kind. */
+    readonly outputs?: Readonly<Record<string, Output>>;
+    /** Factory for methods attached to the logger instance. */
+    readonly methods?: (logger: BaseLogger) => M;
+    /** Kind used by logs without an explicit kind, e.g. `'message'`. */
+    readonly defaultKind?: string;
+    /**
+     * Rejects functions, which would otherwise match this shape through their
+     * `name` property, e.g. `use(graphPlugin)` instead of `use(graphPlugin())`.
+     */
+    readonly call?: never;
+}
+/**
+ * Timestamp options. The pattern is compiled once, when the logger is
+ * created.
+ */
+export interface TimestampOptions {
+    /**
+     * dayjs-style pattern, e.g. `'YYYY-MM-DD HH:mm:ss.SSS'`; see
+     * `compileTimestamp` for the tokens. Default: `DEFAULT_TIMESTAMP_FORMAT`
+     * (`'YYYY/MM/DD HH:mm:ss'`).
+     */
+    readonly format?: string;
+    /** Format in UTC instead of local time. Default: `false`. */
+    readonly utc?: boolean;
+}
+/**
+ * Time source of the logs:
+ * - `'wall'`: `Date.now()`, millisecond resolution, follows the system clock;
+ * - `'precise'`: `process.hrtime` anchored to `Date.now()` when the logger
+ *   is created: nanosecond resolution and monotonic, so it can drift from
+ *   the system clock (NTP corrections, sleep) on long-running processes;
+ * - a function returning epoch milliseconds, e.g. a fixed time in tests. It
+ *   is the time of the log, not a duration: durations belong in the data.
+ */
+export type Clock = 'wall' | 'precise' | (() => number);
+type UnionToIntersection<U> = (U extends unknown ? (union: U) => void : never) extends ((intersection: infer I) => void) ? I : never;
+/**
+ * `T` with the members of `M`. Members of `T` that `M` re-declares are
+ * replaced, together with their docs, instead of being merged into overloads.
+ */
+export type Override<T, M> = [
+    keyof M & keyof T
+] extends [never] ? T & M : Omit<T, keyof M> & M;
+type MethodsOf<P> = P extends LoggerPlugin<infer M> ? M : never;
+/**
+ * Methods added by a list of plugins, combined.
+ */
+export type PluginMethods<P extends readonly LoggerPlugin[]> = UnionToIntersection<MethodsOf<P[number]>>;
+export interface LoggerOptions<P extends readonly LoggerPlugin[] = readonly LoggerPlugin[]> {
+    /** Minimum level to output. Default: `'info'`. */
+    readonly level?: LogLevel;
+    /** Plugins to use, in order. */
+    readonly plugins?: P;
+    /** Kind of logs without an explicit kind. Default: `'default'`. */
+    readonly defaultKind?: string;
+    /**
+     * Timestamp: a pattern (`'HH:mm:ss.SSS'`), options (`{ format, utc }`), a
+     * formatter `(time, timeNs) => string` called on every log, or `false` to
+     * omit timestamps (and skip reading the clock). Default:
+     * `DEFAULT_TIMESTAMP_FORMAT` in local time.
+     */
+    readonly timestamp?: string | TimestampOptions | TimestampFormatter | false;
+    /** Output used for kinds without plugin output. Default: `console.log`. */
+    readonly output?: Output;
+    /** Bake styles to escape codes or to empty strings. Default: `true`. */
+    readonly useStyles?: boolean;
+    /** Time source of the logs, see `Clock`. Default: `'wall'`. */
+    readonly clock?: Clock;
+}
+export {};

package/dist/types/utils/text.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Centers `text` by padding it left and right. Text longer than `length` is
+ * returned unchanged.
+ */
+export declare const padTextMiddle: (text: string, length: number, padString?: string) => string;
+/**
+ * Justifies two strings to the left and right of a column. If the column is
+ * too narrow, each text is placed on its own line.
+ */
+export declare const justifyLeftRight: (leftText: string, rightText: string, columnWidth: number) => string;
+/**
+ * Rules for the control characters of logged text. C0 controls (except `\t`
+ * and `\n`), DEL and C1 controls are always shown as `\xHH`, like
+ * `util.inspect`: ESC and C1 start terminal escape sequences (cursor moves,
+ * screen clears, window titles, hyperlinks, clipboard writes), `\r` and `\b`
+ * overwrite printed text.
+ */
+export interface SanitizeRules {
+    /**
+     * SGR sequences (`\x1B[...m`: colors, bold, etc.): `'keep'` them and end
+     * the text with a reset, so they can't leak into the following output, or
+     * `'escape'` them. Default: `'keep'`.
+     */
+    readonly colors?: 'keep' | 'escape';
+    /**
+     * Newlines: `'keep'` them, `'indent'` the continuation lines, so logged text
+     * can't start a line that looks like a log header, or `'escape'` them as
+     * `\x0A`. Default: `'indent'`.
+     */
+    readonly newlines?: 'keep' | 'indent' | 'escape';
+}
+/**
+ * Sanitization of logged text:
+ * - `'safe'`: colors kept, continuation lines indented, other control
+ *   characters escaped;
+ * - `'strict'`: all control characters, colors and newlines escaped;
+ * - `'none'`: text is written as is, at no cost. Only for trusted text;
+ * - `SanitizeRules`: custom rules, missing ones as in `'safe'`.
+ */
+export type Sanitize = 'none' | 'safe' | 'strict' | SanitizeRules;
+/**
+ * Sanitizing functions built by `createSanitizer`. Clean text is returned as
+ * is, without allocation.
+ */
+export interface Sanitizer {
+    /** Free text, e.g. messages: newlines follow the rules. */
+    readonly text: (text: string) => string;
+    /**
+     * Single line text, e.g. object keys, stack frames, graph labels: newlines
+     * are always escaped.
+     */
+    readonly label: (text: string) => string;
+}
+/**
+ * Creates the sanitizing functions of a given setting. Create it once (e.g. in
+ * a plugin factory) and reuse it for every log.
+ *
+ * @param sanitize Preset or custom rules. Default: `'safe'`.
+ */
+export declare const createSanitizer: (sanitize?: Sanitize) => Sanitizer;
+/**
+ * Length of text without SGR sequences: the columns it takes on a terminal,
+ * for single-width characters. Sanitized text contains no other sequences.
+ * `textWidth` also counts wide characters as two columns.
+ */
+export declare const visibleLength: (text: string) => number;
+/**
+ * Characters that are not one terminal column wide, escape codes and tabs:
+ * lines without them are wrapped by slicing. Box drawing and block
+ * characters (graphs) are not in it.
+ */
+export declare const SLOW_CHARS: RegExp;
+/**
+ * Terminal columns a code point takes: 0 for controls, combining marks,
+ * zero-width characters, variation selectors and skin tones, 2 for East
+ * Asian wide characters and most emoji, 1 otherwise.
+ */
+export declare const charWidth: (codePoint: number) => number;
+/**
+ * Terminal columns a text takes: SGR sequences take none, wide characters
+ * two. Tabs count as one column; `wrapText` expands them.
+ */
+export declare const textWidth: (text: string) => number;
+/**
+ * Describes a thrown value as `Name: message`. Never throws, even for thrown
+ * values with throwing getters or revoked proxies.
+ */
+export declare const describeThrown: (thrown: unknown) => string;
+/**
+ * Splits an error to its `name: message` head, which can span multiple
+ * lines, and its stack frames. Never throws: a head or stack that can't be
+ * read (throwing getters, `Error.prepareStackTrace`) becomes a placeholder.
+ */
+export declare const splitError: (error: Error) => [head: string, frames: string[]];
+/**
+ * Output size limits, like `util.inspect`'s `maxArrayLength` and
+ * `maxStringLength`. They keep a single log of a large buffer, array or
+ * string from blocking the process and flooding the output.
+ */
+export interface OutputLimits {
+    /**
+     * Maximum rendered array, buffer and typed array elements, object keys and
+     * map and set entries. `Infinity` for no limit. Default: `100`.
+     */
+    readonly items?: number;
+    /**
+     * Maximum characters of a string, key, error message or JSON value, cut
+     * before sanitizing. `Infinity` for no limit. Default: `10_000`.
+     */
+    readonly stringLength?: number;
+}
+export declare const DEFAULT_OUTPUT_LIMITS: {
+    readonly items: 100;
+    readonly stringLength: 10000;
+};
+/**
+ * No output limits: the default of the text utilities, which only truncate
+ * when given limits.
+ */
+export declare const NO_OUTPUT_LIMITS: {
+    readonly items: number;
+    readonly stringLength: number;
+};
+/**
+ * Fills in the default output limits and validates them.
+ *
+ * @param what Prefix of error messages, e.g. `messagePlugin`.
+ * @throws RangeError if a limit is not a positive integer or `Infinity`.
+ */
+export declare const resolveOutputLimits: (limits: OutputLimits | undefined, what: string) => Required<OutputLimits>;
+/**
+ * Note on what output limits left out: `… 3 more items`, `… 1 more item`.
+ */
+export declare const describeLeftOut: (count: number, unit: "character" | "item" | "byte" | "entry" | "frame") => string;
+/**
+ * Cuts text to `maxLength` characters, never inside a surrogate pair, and
+ * tells how many were left out: `xxx… 1000 more characters`. Shorter text is
+ * returned as is.
+ */
+export declare const truncate: (text: string, maxLength: number) => string;
+/**
+ * Keys of an object to render, at most `items`. Large arrays are indexed
+ * without listing all their keys first.
+ *
+ * @returns The keys and the number of keys left out.
+ */
+export declare const limitKeys: (data: object, items: number) => [keys: string[], more: number];
+/**
+ * JSON of an object property. Never throws: a getter that throws gives a
+ * placeholder, so one bad property doesn't hide the others.
+ */
+export declare const stringifyProperty: (data: object, key: string, limits?: Required<OutputLimits>) => string;
+/**
+ * Short description of a function, like `util.inspect`: `[Function: name]`
+ * or `[class Name]`, never its source code.
+ */
+export declare const describeFunction: (fn: object) => string;
+/**
+ * Describes buffers and typed arrays in one line, like `util.inspect`:
+ * `<Buffer 68 69 … 998 more bytes>`, `Uint8Array(3) [1, 2, 3]`. Their JSON
+ * (and their keys) would list every element.
+ */
+export declare const describeBinary: (view: ArrayBufferView, items: number) => string;
+/**
+ * Checks for errors of other realms (`vm` contexts, workers), which fail
+ * `instanceof Error`.
+ */
+export declare const isForeignError: (value: object) => boolean;
+/**
+ * Describes objects JSON shows as `{}`: dates (ISO), maps, sets, regular
+ * expressions and errors of other realms, like `util.inspect`. Entries of
+ * maps and sets are JSON, so nesting can't recurse.
+ *
+ * @returns `undefined` for other objects.
+ */
+export declare const describeObject: (value: object, limits?: Required<OutputLimits>) => string | undefined;
+/**
+ * `JSON.stringify` that never throws and describes what JSON can't:
+ * - functions and classes: `[Function: name]`, `[class Name]`, no source;
+ * - bigints: `1n`;
+ * - errors: `Name: message` and their own properties' JSON;
+ * - buffers and typed arrays: see `describeBinary`;
+ * - dates, maps, sets, regular expressions and errors of other realms that
+ *   JSON shows as `{}`: see `describeObject`;
+ * - symbols and `undefined`: `String`;
+ * - circular structures: `"[Unserializable]"`.
+ *
+ * Nested values are serialized whole by the native `JSON.stringify` and the
+ * result is cut to `limits.stringLength`.
+ *
+ * @param limits Output limits. Default: none.
+ */
+export declare const safeStringify: (value: unknown, limits?: Required<OutputLimits>) => string;
+/**
+ * Text of a top-level value that is neither a string nor an object:
+ * functions and classes are described, bigints get their `n` suffix.
+ */
+export declare const stringifyPrimitive: (value: unknown) => string;
+/**
+ * Converts any log data to text:
+ * - strings are returned as is;
+ * - errors are represented by their `name: message` and stack frames;
+ * - buffers and typed arrays are described in one line;
+ * - objects and arrays print each own property as `key: JSON` on a new line;
+ * - everything else is converted with `String`.
+ *
+ * Never throws: data that can't be read (throwing getters, revoked proxies,
+ * broken errors) gives placeholders.
+ *
+ * @param sanitizer Sanitizes strings (`text`), keys, values and stack frames
+ * (`label`). Default: none.
+ * @param limits Output limits. Default: none.
+ */
+export declare const stringifyData: (data: unknown, sanitizer?: Sanitizer, limits?: Required<OutputLimits>) => string;
+/**
+ * How the source cells overlapping a new cell are combined:
+ * - `'average'`: weighted average, a smooth trend that keeps the overall mean;
+ * - `'max'`: the largest value, keeps peaks;
+ * - `'min'`: the smallest value, keeps dips.
+ */
+export type Aggregate = 'average' | 'max' | 'min';
+/**
+ * Scales an array to a new length by combining the overlapping source cells
+ * of each new cell.
+ *
+ * @param data Values to scale.
+ * @param newLength Length of the result.
+ * @param aggregate How overlapping cells are combined. Default: `'average'`.
+ * @throws TypeError if `newLength` is not a non-negative integer.
+ */
+export declare const scaleArray: (data: readonly number[], newLength: number, aggregate?: Aggregate) => number[];

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@mmutils/logger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Plugin-extensible TypeScript logger: a transformer pipeline, baked ANSI styles, styled messages, terminal bar graphs, side-by-side columns and JSON lines.",
+  "keywords": [
+    "logger",
+    "logging",
+    "log",
+    "plugin",
+    "terminal",
+    "console",
+    "ansi",
+    "colors",
+    "graph",
+    "typescript",
+    "json",
+    "ndjson",
+    "columns",
+    "mmutils"
+  ],
+  "author": "Tihomir Trifonov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mastermind-0xff/mm-logger.git"
+  },
+  "homepage": "https://github.com/mastermind-0xff/mm-logger#readme",
+  "bugs": {
+    "url": "https://github.com/mastermind-0xff/mm-logger/issues"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "npm run clean && rollup -c && tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "demo": "node examples/demo.js",
+    "images": "node scripts/readme-images.js",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "dependencies": {
+    "@mmutils/time": "^0.0.3",
+    "style-escape-codes": "^2.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^26.6.3",
+    "@vitest/coverage-v8": "^5.0.2",
+    "eslint": "^10.11.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.9",
+    "rollup": "^4.63.5",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.70.1",
+    "vitest": "^5.0.2"
+  }
+}