@logtape/logtape 0.1.0-dev.10

package/esm/logger.js

@@ -0,0 +1,285 @@
+/**
+ * Get a logger with the given category.
+ *
+ * ```typescript
+ * const logger = getLogger(["my-app"]);
+ * ```
+ *
+ * @param category The category of the logger.  It can be a string or an array
+ *                 of strings.  If it is a string, it is equivalent to an array
+ *                 with a single element.
+ * @returns The logger.
+ */
+export function getLogger(category = []) {
+    return LoggerImpl.getLogger(category);
+}
+/**
+ * The root logger.
+ */
+let rootLogger = null;
+/**
+ * A logger implementation.  Do not use this directly; use {@link getLogger}
+ * instead.  This class is exported for testing purposes.
+ */
+export class LoggerImpl {
+    static getLogger(category = []) {
+        if (rootLogger == null) {
+            rootLogger = new LoggerImpl(null, []);
+        }
+        if (typeof category === "string")
+            return rootLogger.getChild(category);
+        if (category.length === 0)
+            return rootLogger;
+        return rootLogger.getChild(category);
+    }
+    constructor(parent, category) {
+        Object.defineProperty(this, "parent", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "children", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "category", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "sinks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "filters", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.parent = parent;
+        this.children = {};
+        this.category = category;
+        this.sinks = [];
+        this.filters = [];
+    }
+    getChild(subcategory) {
+        const name = typeof subcategory === "string" ? subcategory : subcategory[0];
+        let child = this.children[name]?.deref();
+        if (child == null) {
+            child = new LoggerImpl(this, [...this.category, name]);
+            this.children[name] = new WeakRef(child);
+        }
+        if (typeof subcategory === "string" || subcategory.length === 1) {
+            return child;
+        }
+        return child.getChild(subcategory.slice(1));
+    }
+    /**
+     * Reset the logger.  This removes all sinks and filters from the logger.
+     */
+    reset() {
+        while (this.sinks.length > 0)
+            this.sinks.shift();
+        while (this.filters.length > 0)
+            this.filters.shift();
+    }
+    /**
+     * Reset the logger and all its descendants.  This removes all sinks and
+     * filters from the logger and all its descendants.
+     */
+    resetDescendants() {
+        for (const child of Object.values(this.children)) {
+            const logger = child.deref();
+            if (logger != null)
+                logger.resetDescendants();
+        }
+        this.reset();
+    }
+    filter(record) {
+        for (const filter of this.filters) {
+            if (!filter(record))
+                return false;
+        }
+        if (this.filters.length < 1)
+            return this.parent?.filter(record) ?? true;
+        return true;
+    }
+    *getSinks() {
+        if (this.parent != null) {
+            for (const sink of this.parent.getSinks())
+                yield sink;
+        }
+        for (const sink of this.sinks)
+            yield sink;
+    }
+    emit(record, bypassSinks) {
+        if (!this.filter(record))
+            return;
+        for (const sink of this.getSinks()) {
+            if (bypassSinks?.has(sink))
+                continue;
+            try {
+                sink(record);
+            }
+            catch (error) {
+                const bypassSinks2 = new Set(bypassSinks);
+                bypassSinks2.add(sink);
+                metaLogger.log("fatal", "Failed to emit a log record to sink {sink}: {error}", { sink, error, record }, bypassSinks2);
+            }
+        }
+    }
+    log(level, message, properties, bypassSinks) {
+        let cachedProps = undefined;
+        const record = typeof properties === "function"
+            ? {
+                category: this.category,
+                level,
+                timestamp: Date.now(),
+                get message() {
+                    return parseMessageTemplate(message, this.properties);
+                },
+                get properties() {
+                    if (cachedProps == null)
+                        cachedProps = properties();
+                    return cachedProps;
+                },
+            }
+            : {
+                category: this.category,
+                level,
+                timestamp: Date.now(),
+                message: parseMessageTemplate(message, properties),
+                properties,
+            };
+        this.emit(record, bypassSinks);
+    }
+    logLazily(level, callback) {
+        let msg = undefined;
+        this.emit({
+            category: this.category,
+            level,
+            get message() {
+                if (msg == null) {
+                    msg = callback((tpl, ...values) => renderMessage(tpl, values));
+                }
+                return msg;
+            },
+            timestamp: Date.now(),
+            properties: {},
+        });
+    }
+    logTemplate(level, messageTemplate, values) {
+        this.emit({
+            category: this.category,
+            level,
+            message: renderMessage(messageTemplate, values),
+            timestamp: Date.now(),
+            properties: {},
+        });
+    }
+    debug(message, ...values) {
+        if (typeof message === "string") {
+            this.log("debug", message, (values[0] ?? {}));
+        }
+        else if (typeof message === "function") {
+            this.logLazily("debug", message);
+        }
+        else {
+            this.logTemplate("debug", message, values);
+        }
+    }
+    info(message, ...values) {
+        if (typeof message === "string") {
+            this.log("info", message, (values[0] ?? {}));
+        }
+        else if (typeof message === "function") {
+            this.logLazily("info", message);
+        }
+        else {
+            this.logTemplate("info", message, values);
+        }
+    }
+    warn(message, ...values) {
+        if (typeof message === "string") {
+            this.log("warning", message, (values[0] ?? {}));
+        }
+        else if (typeof message === "function") {
+            this.logLazily("warning", message);
+        }
+        else {
+            this.logTemplate("warning", message, values);
+        }
+    }
+    error(message, ...values) {
+        if (typeof message === "string") {
+            this.log("error", message, (values[0] ?? {}));
+        }
+        else if (typeof message === "function") {
+            this.logLazily("error", message);
+        }
+        else {
+            this.logTemplate("error", message, values);
+        }
+    }
+    fatal(message, ...values) {
+        if (typeof message === "string") {
+            this.log("fatal", message, (values[0] ?? {}));
+        }
+        else if (typeof message === "function") {
+            this.logLazily("fatal", message);
+        }
+        else {
+            this.logTemplate("fatal", message, values);
+        }
+    }
+}
+/**
+ * The meta logger.  It is a logger with the category `["logtape", "meta"]`.
+ */
+const metaLogger = LoggerImpl.getLogger(["logtape", "meta"]);
+const MESSAGE_TEMPLATE_PATTERN = /\{([^}]*)\}/g;
+/**
+ * Parse a message template into a message template array and a values array.
+ * @param template The message template.
+ * @param properties The values to replace placeholders with.
+ * @returns The message template array and the values array.
+ */
+export function parseMessageTemplate(template, properties) {
+    let lastPos = 0;
+    const message = [];
+    while (true) {
+        const match = MESSAGE_TEMPLATE_PATTERN.exec(template);
+        if (match == null) {
+            message.push(template.substring(lastPos));
+            break;
+        }
+        message.push(template.substring(lastPos, match.index));
+        const key = match[1];
+        message.push(properties[key]);
+        lastPos = match.index + match[0].length;
+    }
+    return message;
+}
+/**
+ * Render a message template with values.
+ * @param template The message template.
+ * @param values The message template values.
+ * @returns The message template values interleaved between the substitution
+ *          values.
+ */
+export function renderMessage(template, values) {
+    const args = [];
+    for (let i = 0; i < template.length; i++) {
+        args.push(template[i]);
+        if (i < values.length)
+            args.push(values[i]);
+    }
+    return args;
+}

package/esm/mod.js

@@ -0,0 +1,5 @@
+export { ConfigError, configure, } from "./config.js";
+export { getLevelFilter, toFilter, } from "./filter.js";
+export { defaultConsoleFormatter, } from "./formatter.js";
+export { getLogger } from "./logger.js";
+export { getConsoleSink } from "./sink.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/record.js

@@ -0,0 +1 @@
+export {};

package/esm/sink.js

@@ -0,0 +1,59 @@
+import { defaultConsoleFormatter, defaultTextFormatter, } from "./formatter.js";
+/**
+ * A factory that returns a sink that writes to a {@link WritableStream}.
+ *
+ * Note that the `stream` is of Web Streams API, which is different from
+ * Node.js streams.  You can convert a Node.js stream to a Web Streams API
+ * stream using [`stream.Writable.toWeb()`] method.
+ *
+ * [`stream.Writable.toWeb()`]: https://nodejs.org/api/stream.html#streamwritabletowebstreamwritable
+ *
+ * @example Sink to the standard error in Deno
+ * ```typescript
+ * const stderrSink = getStreamSink(Deno.stderr.writable);
+ * ```
+ *
+ * @example Sink to the standard error in Node.js
+ * ```typescript
+ * import stream from "node:stream";
+ * const stderrSink = getStreamSink(stream.Writable.toWeb(process.stderr));
+ * ```
+ *
+ * @param stream The stream to write to.
+ * @param formatter The text formatter to use.  Defaults to
+ *                  {@link defaultTextFormatter}.
+ * @param encoder The text encoder to use.  Defaults to an instance of
+ *                {@link TextEncoder}.
+ * @returns A sink that writes to the stream.
+ */
+export function getStreamSink(stream, formatter = defaultTextFormatter, encoder = new TextEncoder()) {
+    const writer = stream.getWriter();
+    return (record) => {
+        const bytes = encoder.encode(formatter(record));
+        writer.ready.then(() => writer.write(bytes));
+    };
+}
+/**
+ * A console sink factory that returns a sink that logs to the console.
+ *
+ * @param formatter A console formatter.  Defaults to
+ *                  {@link defaultConsoleFormatter}.
+ * @param console The console to log to.  Defaults to {@link console}.
+ * @returns A sink that logs to the console.
+ */
+export function getConsoleSink(formatter = defaultConsoleFormatter, console = globalThis.console) {
+    return (record) => {
+        const args = formatter(record);
+        if (record.level === "debug")
+            console.debug(...args);
+        else if (record.level === "info")
+            console.info(...args);
+        else if (record.level === "warning")
+            console.warn(...args);
+        else if (record.level === "error" || record.level === "fatal") {
+            console.error(...args);
+        }
+        else
+            throw new TypeError(`Invalid log level: ${record.level}.`);
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@logtape/logtape",
+  "version": "0.1.0-dev.10+d4dd53d2",
+  "description": "Simple logging library for Deno/Node.js/Bun/browsers",
+  "keywords": [
+    "logging",
+    "log",
+    "logger"
+  ],
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://github.com/dahlia/logtape",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/logtape.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dahlia/logtape/issues"
+  },
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "types": "./types/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/mod.d.ts",
+        "default": "./esm/mod.js"
+      },
+      "require": {
+        "types": "./types/mod.d.ts",
+        "default": "./script/mod.js"
+      }
+    }
+  },
+  "scripts": {
+    "test": "node test_runner.js"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "picocolors": "^1.0.0",
+    "consolemock": "^1.1.0",
+    "@deno/shim-deno": "~0.18.0"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/_dnt.shims.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dntGlobalThis = exports.WritableStream = void 0;
+const web_1 = require("node:stream/web");
+var web_2 = require("node:stream/web");
+Object.defineProperty(exports, "WritableStream", { enumerable: true, get: function () { return web_2.WritableStream; } });
+const dntGlobals = {
+    WritableStream: web_1.WritableStream,
+};
+exports.dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+function createMergeProxy(baseObj, extObj) {
+    return new Proxy(baseObj, {
+        get(_target, prop, _receiver) {
+            if (prop in extObj) {
+                return extObj[prop];
+            }
+            else {
+                return baseObj[prop];
+            }
+        },
+        set(_target, prop, value) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            baseObj[prop] = value;
+            return true;
+        },
+        deleteProperty(_target, prop) {
+            let success = false;
+            if (prop in extObj) {
+                delete extObj[prop];
+                success = true;
+            }
+            if (prop in baseObj) {
+                delete baseObj[prop];
+                success = true;
+            }
+            return success;
+        },
+        ownKeys(_target) {
+            const baseKeys = Reflect.ownKeys(baseObj);
+            const extKeys = Reflect.ownKeys(extObj);
+            const extKeysSet = new Set(extKeys);
+            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+        },
+        defineProperty(_target, prop, desc) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            Reflect.defineProperty(baseObj, prop, desc);
+            return true;
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop in extObj) {
+                return Reflect.getOwnPropertyDescriptor(extObj, prop);
+            }
+            else {
+                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+            }
+        },
+        has(_target, prop) {
+            return prop in extObj || prop in baseObj;
+        },
+    });
+}

package/script/config.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = exports.reset = exports.configure = void 0;
+const filter_js_1 = require("./filter.js");
+const logger_js_1 = require("./logger.js");
+const sink_js_1 = require("./sink.js");
+let configured = false;
+/**
+ * Configure the loggers with the specified configuration.
+ *
+ * @example
+ * ```typescript
+ * configure({
+ *   sinks: {
+ *     console: getConsoleSink(),
+ *   },
+ *   filters: {
+ *     slow: (log) =>
+ *       "duration" in log.properties &&
+ *       log.properties.duration as number > 1000,
+ *   },
+ *   loggers: [
+ *     {
+ *       category: "my-app",
+ *       sinks: ["console"],
+ *       level: "info",
+ *     },
+ *     {
+ *       category: ["my-app", "sql"],
+ *       filters: ["slow"],
+ *       level: "debug",
+ *     },
+ *     {
+ *       category: "logtape",
+ *       sinks: ["console"],
+ *       level: "error",
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @param config The configuration.
+ */
+function configure(config) {
+    if (configured && !config.reset) {
+        throw new ConfigError("Already configured; if you want to reset, turn on the reset flag.");
+    }
+    configured = true;
+    logger_js_1.LoggerImpl.getLogger([]).resetDescendants();
+    let metaConfigured = false;
+    for (const cfg of config.loggers) {
+        if (cfg.category.length === 0 ||
+            (cfg.category.length === 1 && cfg.category[0] === "logtape") ||
+            (cfg.category.length === 2 &&
+                cfg.category[0] === "logtape" &&
+                cfg.category[1] === "meta")) {
+            metaConfigured = true;
+        }
+        const logger = logger_js_1.LoggerImpl.getLogger(cfg.category);
+        for (const sinkId of cfg.sinks ?? []) {
+            const sink = config.sinks[sinkId];
+            if (!sink) {
+                reset();
+                throw new ConfigError(`Sink not found: ${sinkId}.`);
+            }
+            logger.sinks.push(sink);
+        }
+        if (cfg.level !== undefined)
+            logger.filters.push((0, filter_js_1.toFilter)(cfg.level));
+        for (const filterId of cfg.filters ?? []) {
+            const filter = config.filters[filterId];
+            if (filter === undefined) {
+                reset();
+                throw new ConfigError(`Filter not found: ${filterId}.`);
+            }
+            logger.filters.push((0, filter_js_1.toFilter)(filter));
+        }
+    }
+    const meta = logger_js_1.LoggerImpl.getLogger(["logtape", "meta"]);
+    if (!metaConfigured) {
+        meta.sinks.push((0, sink_js_1.getConsoleSink)());
+    }
+    meta.info("LogTape loggers are configured.  Note that LogTape itself uses the meta " +
+        "logger, which has category {metaLoggerCategory}.  The meta logger " +
+        "purposes to log internal errors such as sink exceptions.  If you " +
+        "are seeing this message, the meta logger is somehow configured.  " +
+        "It's recommended to configure the meta logger with a separate sink " +
+        "so that you can easily notice if logging itself fails or is " +
+        "misconfigured.  To turn off this message, configure the meta logger " +
+        "with higher log levels than {dismissLevel}.", { metaLoggerCategory: ["logtape", "meta"], dismissLevel: "info" });
+}
+exports.configure = configure;
+/**
+ * Reset the configuration.  Mostly for testing purposes.
+ */
+function reset() {
+    logger_js_1.LoggerImpl.getLogger([]).resetDescendants();
+    configured = false;
+}
+exports.reset = reset;
+/**
+ * A configuration error.
+ */
+class ConfigError extends Error {
+    /**
+     * Constructs a new configuration error.
+     * @param message The error message.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "ConfigureError";
+    }
+}
+exports.ConfigError = ConfigError;

package/script/filter.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLevelFilter = exports.toFilter = void 0;
+/**
+ * Converts a {@link FilterLike} value to an actual {@link Filter}.
+ *
+ * @param filter The filter-like value to convert.
+ * @returns The actual filter.
+ */
+function toFilter(filter) {
+    if (typeof filter === "function")
+        return filter;
+    return getLevelFilter(filter);
+}
+exports.toFilter = toFilter;
+/**
+ * Returns a filter that accepts log records with the specified level.
+ *
+ * @param level The level to filter by.  If `null`, the filter will reject all
+ *              records.
+ * @returns The filter.
+ */
+function getLevelFilter(level) {
+    if (level == null)
+        return () => false;
+    if (level === "fatal") {
+        return (record) => record.level === "fatal";
+    }
+    else if (level === "error") {
+        return (record) => record.level === "fatal" || record.level === "error";
+    }
+    else if (level === "warning") {
+        return (record) => record.level === "fatal" ||
+            record.level === "error" ||
+            record.level === "warning";
+    }
+    else if (level === "info") {
+        return (record) => record.level === "fatal" ||
+            record.level === "error" ||
+            record.level === "warning" ||
+            record.level === "info";
+    }
+    else if (level === "debug")
+        return () => true;
+    throw new TypeError(`Invalid log level: ${level}.`);
+}
+exports.getLevelFilter = getLevelFilter;