@lakutata/logger 0.0.0-stage → 3.0.0-beta.0

package/dist/cjs/Logger.js

@@ -0,0 +1,185 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const node_stream_1 = require("node:stream");
+const Record_js_1 = require("./lib/Record.js");
+const Serializers_js_1 = require("./lib/Serializers.js");
+const Pretty_js_1 = require("./lib/Pretty.js");
+const Colors_js_1 = require("./lib/Colors.js");
+const Destination_js_1 = require("./lib/Destination.js");
+//The loggers with buffered lines to write when the process exits
+const activeLoggers = new Set();
+process.once('exit', () => activeLoggers.forEach((logger) => logger.flush()));
+/**
+ * The logger component of the applications built with `lakutata`: the package presets it as the `log` component (and
+ * creates it first), so the framework and the application log through it. It writes the pino log format: one JSON
+ * object per line, with `level` (10 trace, 20 debug, 30 info, 40 warn, 50 error, 60 fatal), `time` (milliseconds since the epoch),
+ * `pid`, `hostname`, `name` (the application's name), the properties of the logged object and `msg`; with `pretty` on
+ * (the default), it writes readable lines instead: `[HH:MM:ss.SSS] LEVEL (name/pid): message`, then one indented line
+ * per property, in the local time zone.
+ *
+ * Configure it through the `log` entry of the application's `components` (no `class` needed:
+ * `log: {level: 'info', pretty: false}`), and get it with `@Inject('log')` or `getObject('log')`; it is a singleton.
+ * The lines are buffered and written at the next turn of the event loop (or once 16 KB are pending), and the pending
+ * lines are written synchronously when the process exits or the component is destroyed; `sync: true` writes each line
+ * at once instead. A stream with a file descriptor (stdout, stderr, an opened file) is written synchronously through
+ * it, so the lines keep their order.
+ *
+ * An HTTP request or response logged as the object of a line is written under `req` or `res` with the values of its
+ * credential headers (`Authorization`, `Cookie`, `Set-Cookie`, `Proxy-Authorization`) replaced by `[Redacted]` (see
+ * the `redactedHeaders` option). Nothing else is redacted and there are no child loggers: the other properties are
+ * written as is, so log the fields you need rather than secrets or whole objects holding them.
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {Logger} from 'lakutata/com/logger'
+ *
+ * class Orders extends Component {
+ *     @Inject('log')
+ *     protected readonly log: Logger
+ *
+ *     public pay(orderId: number, amount: number): void {
+ *         //{"level":30,...,"orderId":42,"msg":"order 42 paid: 9.90"}
+ *         this.log.info({orderId: orderId}, 'order %d paid: %s', orderId, amount.toFixed(2))
+ *     }
+ *
+ *     public fail(error: Error): void {
+ *         //The error serialized under "err", its message as the message unless one is given
+ *         this.log.error(error, 'payment failed')
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'shop.app',
+ *     name: 'Shop',
+ *     components: {
+ *         //The preset logger: JSON lines from the info level in production
+ *         log: {level: 'info', pretty: process.env.NODE_ENV !== 'production'},
+ *         orders: {class: Orders}
+ *     }
+ * }))
+ * ```
+ */
+let Logger = class Logger extends core_1.Component {
+    #threshold;
+    #bindings;
+    #pretty;
+    #outputs;
+    #redacted;
+    /**
+     * Set up the destinations and the level, and register the logger to flush its pending lines when the process exits.
+     * @protected
+     */
+    async init() {
+        this.#threshold = Record_js_1.LEVELS[this.level];
+        this.#bindings = (0, Record_js_1.logBindings)(core_1.Application.appName);
+        this.#redacted = new Set(this.redactedHeaders.map((name) => name.toLowerCase()));
+        this.#outputs = this.destinations.map((stream) => ({
+            destination: new Destination_js_1.Destination(stream, this.sync),
+            palette: this.pretty ? (stream === process.stdout && this.colorize ? Colors_js_1.COLOR_PALETTE : Colors_js_1.PLAIN_PALETTE) : undefined
+        }));
+        this.#pretty = this.#outputs.some((output) => !!output.palette);
+        activeLoggers.add(this);
+    }
+    /**
+     * Write the pending lines and stop flushing at the process exit.
+     * @protected
+     */
+    async destroy() {
+        activeLoggers.delete(this);
+        this.flush();
+    }
+    /**
+     * Build a log line and write it to every destination, unless its level is below the configured `level`.
+     * @param level The numeric level of the line: 10 trace, 20 debug, 30 info, 40 warn, 50 error, 60 fatal.
+     * @param args The arguments of the log method: `[obj, msg, ...args]` or `[msg, ...args]`.
+     * @protected
+     */
+    write(level, args) {
+        if (level < this.#threshold)
+            return;
+        const record = (0, Record_js_1.buildRecord)(level, this.#bindings, args, this.#pretty, this.#redacted);
+        let prettyLines;
+        for (const output of this.#outputs) {
+            if (!output.palette) {
+                output.destination.write(record.line);
+                continue;
+            }
+            prettyLines ??= new Map();
+            let line = prettyLines.get(output.palette);
+            if (line === undefined) {
+                //The parsed line is changed by the formatting, it is used once
+                line = (0, Pretty_js_1.pretty)(record.line.slice(0, -1), output.palette, prettyLines.size ? undefined : record.log);
+                prettyLines.set(output.palette, line);
+            }
+            output.destination.write(line);
+        }
+    }
+    /**
+     * Write the buffered lines now, synchronously for the streams with a file descriptor (before a `process.exit()`
+     * in a signal handler, for instance). Does nothing with `sync: true`.
+     */
+    flush() {
+        this.#outputs?.forEach((output) => output.destination.flush());
+    }
+    fatal(obj, ...msg) {
+        this.write(60, [obj, ...msg]);
+        //The process may end without a turn of the event loop
+        this.flush();
+    }
+    error(obj, ...msg) {
+        return this.write(50, [obj, ...msg]);
+    }
+    warn(obj, ...msg) {
+        return this.write(40, [obj, ...msg]);
+    }
+    info(obj, ...msg) {
+        return this.write(30, [obj, ...msg]);
+    }
+    debug(obj, ...msg) {
+        return this.write(20, [obj, ...msg]);
+    }
+    trace(obj, ...msg) {
+        return this.write(10, [obj, ...msg]);
+    }
+};
+exports.Logger = Logger;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Boolean().optional().default(true)),
+    __metadata("design:type", Boolean)
+], Logger.prototype, "pretty", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().valid(...Object.keys(Record_js_1.LEVELS)).optional().default('trace')),
+    __metadata("design:type", String)
+], Logger.prototype, "level", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Boolean().optional().default(true)),
+    __metadata("design:type", Boolean)
+], Logger.prototype, "colorize", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Boolean().optional().default(false)),
+    __metadata("design:type", Boolean)
+], Logger.prototype, "sync", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array(core_1.DTO.InstanceOf(node_stream_1.Stream)).optional().default(() => [process.stdout])),
+    __metadata("design:type", Array)
+], Logger.prototype, "destinations", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array(core_1.DTO.String()).optional().default(() => [...Serializers_js_1.REDACTED_HEADERS])),
+    __metadata("design:type", Array)
+], Logger.prototype, "redactedHeaders", void 0);
+exports.Logger = Logger = __decorate([
+    (0, di_1.Singleton)()
+], Logger);

package/dist/cjs/exports/Logger.d.ts

@@ -0,0 +1,2 @@
+export * from '../Logger.js';
+export type { ILogger, ILogMethod } from '@lakutata/core/com/logger';

package/dist/cjs/exports/Logger.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("../Logger.js"), exports);
+
+//The default of the entry: the entry itself (scripts/package-build/cjs-package.mjs)
+if (!Object.prototype.hasOwnProperty.call(exports, 'default')) Object.defineProperty(exports, 'default', {value: exports})

package/dist/cjs/lib/Colors.d.ts

@@ -0,0 +1,8 @@
+export type Colorize = (input: unknown) => string;
+export type Palette = {
+    level: Record<string, Colorize>;
+    message: Colorize;
+    property: Colorize;
+};
+export declare const PLAIN_PALETTE: Palette;
+export declare const COLOR_PALETTE: Palette;

package/dist/cjs/lib/Colors.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COLOR_PALETTE = exports.PLAIN_PALETTE = void 0;
+/**
+ * Replace the close sequences of a text by the open sequence, so a color is not closed early by a nested one
+ * @param text
+ * @param index
+ * @param close
+ * @param open
+ */
+function replaceClose(text, index, close, open) {
+    let result = '';
+    let tail = text;
+    while (index >= 0) {
+        result += tail.substring(0, index) + open;
+        tail = tail.substring(index + close.length);
+        index = tail.indexOf(close);
+    }
+    return result + tail;
+}
+/**
+ * An ANSI color
+ * @param open
+ * @param close
+ */
+function color(open, close) {
+    const openSequence = `\x1b[${open}m`;
+    const closeSequence = `\x1b[${close}m`;
+    return (input) => {
+        //Empty texts stay uncolored
+        if (input === '' || input === undefined)
+            return '';
+        const text = `${input}`;
+        const index = text.indexOf(closeSequence, openSequence.length + 1);
+        return index < 0 ? openSequence + text + closeSequence : openSequence + replaceClose(text, index, closeSequence, openSequence) + closeSequence;
+    };
+}
+const plain = (input) => input;
+exports.PLAIN_PALETTE = {
+    level: { default: plain, 60: plain, 50: plain, 40: plain, 30: plain, 20: plain, 10: plain },
+    message: plain,
+    property: plain
+};
+exports.COLOR_PALETTE = {
+    level: { default: color(37, 39), 60: color(41, 49), 50: color(31, 39), 40: color(33, 39), 30: color(32, 39), 20: color(34, 39), 10: color(90, 39) },
+    message: color(36, 39),
+    property: color(35, 39)
+};

package/dist/cjs/lib/Destination.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A destination of the log lines, buffered unless synchronous
+ * The buffered lines are written in the next event loop iteration, and synchronously when the process exits
+ * The streams with a file descriptor (stdout, stderr, files) are written through it, so the lines stay in order
+ */
+export declare class Destination {
+    #private;
+    protected readonly stream: NodeJS.WritableStream;
+    protected readonly sync: boolean;
+    constructor(stream: NodeJS.WritableStream, sync: boolean);
+    /**
+     * The file descriptor of the stream, if it has one
+     * @protected
+     */
+    protected get fd(): number | undefined;
+    /**
+     * Write a text to the file descriptor, retrying when the descriptor is busy
+     * @param fd
+     * @param text
+     * @protected
+     */
+    protected writeFd(fd: number, text: string): void;
+    /**
+     * Write a text
+     * @param text
+     */
+    write(text: string): void;
+    /**
+     * Write a text to the stream, through its file descriptor if it has one
+     * @param text
+     * @protected
+     */
+    protected output(text: string): void;
+    /**
+     * Write the buffered text
+     */
+    flush(): void;
+}

package/dist/cjs/lib/Destination.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Destination = void 0;
+const node_fs_1 = require("node:fs");
+//The buffered text written at once
+const HIGH_WATER_MARK = 16384;
+/**
+ * The array the writes wait on while a pipe is full, created when first needed: SharedArrayBuffer is missing where the
+ * logger may be loaded without logging (a renderer of Electron which is not cross-origin isolated)
+ */
+let sleeper;
+/**
+ * Wait synchronously
+ * @param ms
+ */
+function sleepSync(ms) {
+    if (typeof SharedArrayBuffer === 'function') {
+        sleeper ??= new Int32Array(new SharedArrayBuffer(4));
+        Atomics.wait(sleeper, 0, 0, ms);
+        return;
+    }
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        //Busy wait, without SharedArrayBuffer
+    }
+}
+/**
+ * A destination of the log lines, buffered unless synchronous
+ * The buffered lines are written in the next event loop iteration, and synchronously when the process exits
+ * The streams with a file descriptor (stdout, stderr, files) are written through it, so the lines stay in order
+ */
+class Destination {
+    #buffer = '';
+    #scheduled = false;
+    constructor(stream, sync) {
+        this.stream = stream;
+        this.sync = sync;
+    }
+    /**
+     * The file descriptor of the stream, if it has one
+     * @protected
+     */
+    get fd() {
+        const fd = this.stream.fd;
+        return typeof fd === 'number' ? fd : undefined;
+    }
+    /**
+     * Write a text to the file descriptor, retrying when the descriptor is busy
+     * @param fd
+     * @param text
+     * @protected
+     */
+    writeFd(fd, text) {
+        let data = Buffer.from(text);
+        while (data.length) {
+            try {
+                data = data.subarray((0, node_fs_1.writeSync)(fd, data));
+            }
+            catch (e) {
+                if (e.code !== 'EAGAIN')
+                    throw e;
+                //A pipe is full, wait for its reader
+                sleepSync(10);
+            }
+        }
+    }
+    /**
+     * Write a text
+     * @param text
+     */
+    write(text) {
+        if (this.sync)
+            return this.output(text);
+        this.#buffer += text;
+        if (this.#buffer.length >= HIGH_WATER_MARK)
+            return this.flush();
+        if (this.#scheduled)
+            return;
+        this.#scheduled = true;
+        setImmediate(() => this.flush());
+    }
+    /**
+     * Write a text to the stream, through its file descriptor if it has one
+     * @param text
+     * @protected
+     */
+    output(text) {
+        const fd = this.fd;
+        fd === undefined ? this.stream.write(text) : this.writeFd(fd, text);
+    }
+    /**
+     * Write the buffered text
+     */
+    flush() {
+        this.#scheduled = false;
+        if (!this.#buffer)
+            return;
+        const text = this.#buffer;
+        this.#buffer = '';
+        this.output(text);
+    }
+}
+exports.Destination = Destination;

package/dist/cjs/lib/Format.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Format a log message with its arguments: %s, %d, %f, %i, %o, %O, %j and %%
+ * The arguments without placeholder are ignored
+ * @param template
+ * @param args
+ */
+export declare function format(template: unknown, args: unknown[]): unknown;

package/dist/cjs/lib/Format.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.format = format;
+//Derived from the upstream projects listed in THIRD_PARTY_NOTICES.md (rewritten in TypeScript)
+const Stringify_js_1 = require("./Stringify.js");
+/**
+ * Format a log message with its arguments: %s, %d, %f, %i, %o, %O, %j and %%
+ * The arguments without placeholder are ignored
+ * @param template
+ * @param args
+ */
+function format(template, args) {
+    if (typeof template === 'object' && template !== null) {
+        const count = args.length + 1;
+        if (count === 1)
+            return template;
+        //Serialize the object and the arguments after the first one (the behavior of 2.x)
+        const objects = new Array(count);
+        objects[0] = (0, Stringify_js_1.stringify)(template);
+        for (let index = 1; index < count; index++)
+            objects[index] = (0, Stringify_js_1.stringify)(args[index]);
+        return objects.join(' ');
+    }
+    if (typeof template !== 'string' || !args.length)
+        return template;
+    let result = '';
+    let argument = 0;
+    let last = -1;
+    const length = template.length;
+    for (let index = 0; index < length;) {
+        if (template.charCodeAt(index) === 37 && index + 1 < length) {
+            last = last > -1 ? last : 0;
+            switch (template.charCodeAt(index + 1)) {
+                //d, f
+                case 100:
+                case 102:
+                    if (argument >= args.length || args[argument] == null)
+                        break;
+                    if (last < index)
+                        result += template.slice(last, index);
+                    result += Number(args[argument]);
+                    last = index + 2;
+                    index++;
+                    break;
+                //i
+                case 105:
+                    if (argument >= args.length || args[argument] == null)
+                        break;
+                    if (last < index)
+                        result += template.slice(last, index);
+                    result += Math.floor(Number(args[argument]));
+                    last = index + 2;
+                    index++;
+                    break;
+                //O, o, j
+                case 79:
+                case 111:
+                case 106: {
+                    if (argument >= args.length || args[argument] === undefined)
+                        break;
+                    if (last < index)
+                        result += template.slice(last, index);
+                    const value = args[argument];
+                    if (typeof value === 'string') {
+                        result += `'${value}'`;
+                    }
+                    else if (typeof value === 'function') {
+                        result += value.name || '<anonymous>';
+                    }
+                    else {
+                        result += (0, Stringify_js_1.stringify)(value);
+                    }
+                    last = index + 2;
+                    index++;
+                    break;
+                }
+                //s
+                case 115:
+                    if (argument >= args.length)
+                        break;
+                    if (last < index)
+                        result += template.slice(last, index);
+                    result += String(args[argument]);
+                    last = index + 2;
+                    index++;
+                    break;
+                //%
+                case 37:
+                    if (last < index)
+                        result += template.slice(last, index);
+                    result += '%';
+                    last = index + 2;
+                    index++;
+                    argument--;
+                    break;
+            }
+            ++argument;
+        }
+        ++index;
+    }
+    if (last === -1)
+        return template;
+    if (last < length)
+        result += template.slice(last);
+    return result;
+}

package/dist/cjs/lib/Pretty.d.ts

@@ -0,0 +1,9 @@
+import { Palette } from './Colors.js';
+/**
+ * Format a JSON log line for humans:
+ * [time] LEVEL (name/pid): message, then the properties on their own lines
+ * @param line the JSON log line, without its line terminator
+ * @param palette
+ * @param parsed the parsed line, if it is known (the log is changed)
+ */
+export declare function pretty(line: string, palette: Palette, parsed?: Record<string, unknown>): string;