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

package/dist/cjs/lib/Stringify.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringify = stringify;
+//Derived from the upstream projects listed in THIRD_PARTY_NOTICES.md (rewritten in TypeScript)
+const MAXIMUM_DEPTH = 5;
+const MAXIMUM_BREADTH = 100;
+const TypedArrayToStringTag = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Int8Array.prototype), Symbol.toStringTag).get;
+/**
+ * The count of the omitted items
+ * @param count
+ */
+function itemCount(count) {
+    return count === 1 ? '1 item' : `${count} items`;
+}
+/**
+ * Serialize a value which JSON cannot (circular references, bigints):
+ * sorted keys, circular references as "[Circular]", limited depth and breadth
+ * @param key
+ * @param value
+ * @param stack
+ */
+function safeStringify(key, value, stack) {
+    switch (typeof value) {
+        case 'string':
+            return JSON.stringify(value);
+        case 'number':
+            return isFinite(value) ? String(value) : 'null';
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'bigint':
+            return String(value);
+        case 'object': {
+            if (value === null)
+                return 'null';
+            if (typeof value.toJSON === 'function') {
+                value = value.toJSON(key);
+                if (typeof value !== 'object')
+                    return safeStringify(key, value, stack);
+                if (value === null)
+                    return 'null';
+            }
+            if (stack.includes(value))
+                return '"[Circular]"';
+            let result = '';
+            if (Array.isArray(value)) {
+                if (!value.length)
+                    return '[]';
+                if (MAXIMUM_DEPTH < stack.length + 1)
+                    return '"[Array]"';
+                stack.push(value);
+                const count = Math.min(value.length, MAXIMUM_BREADTH);
+                for (let index = 0; index < count; index++) {
+                    result += `${index ? ',' : ''}${safeStringify(String(index), value[index], stack) ?? 'null'}`;
+                }
+                if (value.length - 1 > MAXIMUM_BREADTH)
+                    result += `,"... ${itemCount(value.length - MAXIMUM_BREADTH - 1)} not stringified"`;
+                stack.pop();
+                return `[${result}]`;
+            }
+            let keys = Object.keys(value);
+            const keyCount = keys.length;
+            if (!keyCount)
+                return '{}';
+            if (MAXIMUM_DEPTH < stack.length + 1)
+                return '"[Object]"';
+            let separator = '';
+            let count = Math.min(keyCount, MAXIMUM_BREADTH);
+            if (value.length !== undefined && TypedArrayToStringTag.call(value) !== undefined && value.length !== 0) {
+                const items = Math.min(value.length, MAXIMUM_BREADTH);
+                for (let index = 0; index < items; index++)
+                    result += `${index ? ',' : ''}"${index}":${value[index]}`;
+                keys = keys.slice(value.length);
+                count -= value.length;
+                separator = ',';
+            }
+            keys.sort();
+            stack.push(value);
+            for (let index = 0; index < count; index++) {
+                const item = safeStringify(keys[index], value[keys[index]], stack);
+                if (item === undefined)
+                    continue;
+                result += `${separator}${JSON.stringify(keys[index])}:${item}`;
+                separator = ',';
+            }
+            if (keyCount > MAXIMUM_BREADTH)
+                result += `${separator}"...":"${itemCount(keyCount - MAXIMUM_BREADTH)} not stringified"`;
+            stack.pop();
+            return `{${result}}`;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Serialize a value to JSON, the values JSON cannot serialize are serialized safely
+ * @param value
+ */
+function stringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        try {
+            return safeStringify('', value, []);
+        }
+        catch {
+            return '"[unable to serialize, circular reference is too complex to analyze]"';
+        }
+    }
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/Logger.js

@@ -0,0 +1,182 @@
+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);
+};
+import { Application, Component, DTO } from '@lakutata/core';
+import { Configurable, Singleton } from '@lakutata/core/decorator/di';
+import { Stream } from 'node:stream';
+import { logBindings, buildRecord, LEVELS } from './lib/Record.js';
+import { REDACTED_HEADERS } from './lib/Serializers.js';
+import { pretty } from './lib/Pretty.js';
+import { COLOR_PALETTE, PLAIN_PALETTE } from './lib/Colors.js';
+import { Destination } from './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 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 = LEVELS[this.level];
+        this.#bindings = logBindings(Application.appName);
+        this.#redacted = new Set(this.redactedHeaders.map((name) => name.toLowerCase()));
+        this.#outputs = this.destinations.map((stream) => ({
+            destination: new Destination(stream, this.sync),
+            palette: this.pretty ? (stream === process.stdout && this.colorize ? COLOR_PALETTE : 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 = 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 = 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]);
+    }
+};
+__decorate([
+    Configurable(DTO.Boolean().optional().default(true)),
+    __metadata("design:type", Boolean)
+], Logger.prototype, "pretty", void 0);
+__decorate([
+    Configurable(DTO.String().valid(...Object.keys(LEVELS)).optional().default('trace')),
+    __metadata("design:type", String)
+], Logger.prototype, "level", void 0);
+__decorate([
+    Configurable(DTO.Boolean().optional().default(true)),
+    __metadata("design:type", Boolean)
+], Logger.prototype, "colorize", void 0);
+__decorate([
+    Configurable(DTO.Boolean().optional().default(false)),
+    __metadata("design:type", Boolean)
+], Logger.prototype, "sync", void 0);
+__decorate([
+    Configurable(DTO.Array(DTO.InstanceOf(Stream)).optional().default(() => [process.stdout])),
+    __metadata("design:type", Array)
+], Logger.prototype, "destinations", void 0);
+__decorate([
+    Configurable(DTO.Array(DTO.String()).optional().default(() => [...REDACTED_HEADERS])),
+    __metadata("design:type", Array)
+], Logger.prototype, "redactedHeaders", void 0);
+Logger = __decorate([
+    Singleton()
+], Logger);
+export { Logger };

package/dist/esm/exports/Logger.js

@@ -0,0 +1 @@
+export * from '../Logger.js';

package/dist/esm/lib/Colors.js

@@ -0,0 +1,45 @@
+/**
+ * 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;
+export const PLAIN_PALETTE = {
+    level: { default: plain, 60: plain, 50: plain, 40: plain, 30: plain, 20: plain, 10: plain },
+    message: plain,
+    property: plain
+};
+export const 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/esm/lib/Destination.js

@@ -0,0 +1,99 @@
+import { writeSync } from '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
+ */
+export 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(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);
+    }
+}

package/dist/esm/lib/Format.js

@@ -0,0 +1,103 @@
+//Derived from the upstream projects listed in THIRD_PARTY_NOTICES.md (rewritten in TypeScript)
+import { stringify } from './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
+ */
+export 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] = stringify(template);
+        for (let index = 1; index < count; index++)
+            objects[index] = 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 += 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;
+}