@logtape/logtape 0.1.0-dev.9

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2024 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+<!-- deno-fmt-ignore-file -->
+
+LogTape
+=======
+
+[![GitHub Actions][GitHub Actions badge]][GitHub Actions]
+[![Codecov][Codecov badge]][Codecov]
+
+LogTape is a simple logging library for Deno/Node.js/Bun/browsers.  It is
+designed to be used for both applications and libraries.
+
+Currently, LogTape provides only few sinks, but you can easily add your own
+sinks.
+
+[GitHub Actions]: https://github.com/dahlia/logtape/actions/workflows/main.yaml
+[GitHub Actions badge]: https://github.com/dahlia/logtape/actions/workflows/main.yaml/badge.svg
+[Codecov]: https://codecov.io/gh/dahlia/logtape
+[Codecov badge]: https://codecov.io/gh/dahlia/logtape/graph/badge.svg?token=yOejfcuX7r

package/esm/_dnt.shims.js

@@ -0,0 +1,61 @@
+import { WritableStream } from "node:stream/web";
+export { WritableStream } from "node:stream/web";
+const dntGlobals = {
+    WritableStream,
+};
+export const 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/esm/config.js

@@ -0,0 +1,108 @@
+import { toFilter } from "./filter.js";
+import { LoggerImpl } from "./logger.js";
+import { getConsoleSink } from "./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.
+ */
+export function configure(config) {
+    if (configured && !config.reset) {
+        throw new ConfigError("Already configured; if you want to reset, turn on the reset flag.");
+    }
+    configured = true;
+    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 = 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(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(toFilter(filter));
+        }
+    }
+    const meta = LoggerImpl.getLogger(["logtape", "meta"]);
+    if (!metaConfigured) {
+        meta.sinks.push(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" });
+}
+/**
+ * Reset the configuration.  Mostly for testing purposes.
+ */
+export function reset() {
+    LoggerImpl.getLogger([]).resetDescendants();
+    configured = false;
+}
+/**
+ * A configuration error.
+ */
+export class ConfigError extends Error {
+    /**
+     * Constructs a new configuration error.
+     * @param message The error message.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "ConfigureError";
+    }
+}

package/esm/filter.js

@@ -0,0 +1,42 @@
+/**
+ * Converts a {@link FilterLike} value to an actual {@link Filter}.
+ *
+ * @param filter The filter-like value to convert.
+ * @returns The actual filter.
+ */
+export function toFilter(filter) {
+    if (typeof filter === "function")
+        return filter;
+    return getLevelFilter(filter);
+}
+/**
+ * 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.
+ */
+export 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}.`);
+}

package/esm/formatter.js

@@ -0,0 +1,85 @@
+/**
+ * The severity level abbreviations.
+ */
+const levelAbbreviations = {
+    "debug": "DBG",
+    "info": "INF",
+    "warning": "WRN",
+    "error": "ERR",
+    "fatal": "FTL",
+};
+/**
+ * A platform-specific inspect function.  In Deno, this is {@link Deno.inspect},
+ * and in Node.js/Bun it is {@link util.inspect}.  If neither is available, it
+ * falls back to {@link JSON.stringify}.
+ *
+ * @param value The value to inspect.
+ * @returns The string representation of the value.
+ */
+const inspect = eval(`(
+  "Deno" in globalThis && "inspect" in globalThis.Deno &&
+    typeof globalThis.Deno.inspect === "function"
+    ? globalThis.Deno.inspect
+    : "util" in globalThis && "inspect" in globalThis.util &&
+        globalThis.util.inspect === "function"
+    ? globalThis.util.inspect
+    : JSON.stringify
+)`);
+/**
+ * The default text formatter.  This formatter formats log records as follows:
+ *
+ * ```
+ * 2023-11-14 22:13:20.000 +00:00 [INF] Hello, world!
+ * ```
+ *
+ * @param record The log record to format.
+ * @returns The formatted log record.
+ */
+export function defaultTextFormatter(record) {
+    const ts = new Date(record.timestamp);
+    let msg = "";
+    for (let i = 0; i < record.message.length; i++) {
+        if (i % 2 === 0)
+            msg += record.message[i];
+        else
+            msg += inspect(record.message[i]);
+    }
+    return `${ts.toISOString().replace("T", " ").replace("Z", " +00:00")} [${levelAbbreviations[record.level]}] ${msg}\n`;
+}
+/**
+ * The styles for the log level in the console.
+ */
+const logLevelStyles = {
+    "debug": "background-color: gray; color: white;",
+    "info": "background-color: white; color: black;",
+    "warning": "background-color: orange;",
+    "error": "background-color: red;",
+    "fatal": "background-color: maroon;",
+};
+/**
+ * The default console formatter.
+ *
+ * @param record The log record to format.
+ * @returns The formatted log record, as an array of arguments for
+ *          {@link console.log}.
+ */
+export function defaultConsoleFormatter(record) {
+    let msg = "";
+    const values = [];
+    for (let i = 0; i < record.message.length; i++) {
+        if (i % 2 === 0)
+            msg += record.message[i];
+        else {
+            msg += "%o";
+            values.push(record.message[i]);
+        }
+    }
+    return [
+        `%c${record.level.toUpperCase()}%c %c${record.category.join("\xb7")} %c${msg}`,
+        logLevelStyles[record.level],
+        "background-color: default;",
+        "color: gray;",
+        "color: default;",
+        ...values,
+    ];
+}

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}.`);
+    };
+}