@logtape/logtape 0.1.0-dev.10

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,194 @@
+<!-- deno-fmt-ignore-file -->
+
+LogTape
+=======
+
+[![GitHub Actions][GitHub Actions badge]][GitHub Actions]
+[![Codecov][Codecov badge]][Codecov]
+
+> [!NOTE]
+> LogTape is still in the early stage of development.  The API is not stable
+> yet.  Please be careful when using it in production.
+
+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
+
+
+Installation
+------------
+
+### Deno
+
+~~~~ sh
+deno add @logtape/logtape
+~~~~
+
+### Node.js
+
+~~~~ sh
+npm add @logtape/logtape
+~~~~
+
+### Bun
+
+~~~~ sh
+bun add @logtape/logtape
+~~~~
+
+
+Quick start
+-----------
+
+Set up LogTape in the entry point of your application (if you are composing
+a library, you should not set up LogTape in the library itself; it is up to
+the application to set up LogTape):
+
+~~~~ typescript
+import { configure, getConsoleSink } from "@logtape/logtape";
+
+configure({
+  sinks: { console: getConsoleSink() },
+  filters: {},
+  loggers: [
+    { category: "my-app", level: "debug", sinks: ["console"] }
+  ]
+});
+~~~~
+
+And then you can use LogTape in your application or library:
+
+~~~~ typescript
+import { getLogger } from "@logtape/logtape";
+
+const logger = getLogger(["my-app", "my-module"]);
+
+export function myFunc(value: number): void {
+  logger.debug `Hello, ${value}!`;
+}
+~~~~
+
+
+How to log
+----------
+
+There are total 5 log levels: `debug`, `info`, `warning`, `error`, `fatal` (in
+the order of verbosity).  You can log messages with the following syntax:
+
+~~~~ typescript
+logger.debug `This is a debug message with ${value}.`;
+logger.info  `This is an info message with ${value}.`;
+logger.warn  `This is a warning message with ${value}.`;
+logger.error `This is an error message with ${value}.`;
+logger.fatal `This is a fatal message with ${value}.`;
+~~~~
+
+You can also log messages with a function call:
+
+~~~~ typescript
+logger.debug("This is a debug message with {value}.", { value });
+logger.info("This is an info message with {value}.", { value });
+logger.warn("This is a warning message with {value}.", { value });
+logger.error("This is an error message with {value}.", { value });
+logger.fatal("This is a fatal message with {value}.", { value });
+~~~~
+
+Sometimes, values to be logged are expensive to compute.  In such cases, you
+can use a function to defer the computation so that it is only computed when
+the log message is actually logged:
+
+~~~~ typescript
+logger.debug(l => l`This is a debug message with ${computeValue()}.`);
+logger.debug("Or you can use a function call: {value}.", () => {
+  return { value: computeValue() };
+});
+~~~~
+
+
+Categories
+----------
+
+LogTape uses a hierarchical category system to manage loggers.  A category is
+a list of strings.  For example, `["my-app", "my-module"]` is a category.
+
+When you log a message, it is dispatched to all loggers whose categories are
+prefixes of the category of the logger.  For example, if you log a message
+with the category `["my-app", "my-module", "my-submodule"]`, it is dispatched
+to loggers whose categories are `["my-app", "my-module"]` and `["my-app"]`.
+
+This behavior allows you to control the verbosity of log messages by setting
+the log level of loggers at different levels of the category hierarchy.
+
+
+Sinks
+-----
+
+A sink is a destination of log messages.  LogTape currently provides a few
+sinks: console and stream.  However, you can easily add your own sinks.
+The signature of a sink is:
+
+~~~~ typescript
+export type Sink = (record: LogRecord) => void;
+~~~~
+
+Here's a simple example of a sink that writes log messages to console:
+
+~~~~ typescript
+import { configure } from "@logtape/logtape";
+
+configure({
+  sinks: {
+    console(record) {
+      console.log(record.message);
+    }
+  },
+  // Omitted for brevity
+});
+~~~~
+
+Of course, you don't have to implement your own console sink because LogTape
+provides a console sink:
+
+~~~~ typescript
+import { configure, getConsoleSink } from "@logtape/logtape";
+
+configure({
+  sinks: {
+    console: getConsoleSink(),
+  },
+  // Omitted for brevity
+});
+~~~~
+
+Another built-in sink is a stream sink.  It writes log messages to
+a [`WritableStream`].  Here's an example of a stream sink that writes log
+messages to the standard error:
+
+~~~~ typescript
+// Deno:
+const stderrSink = getStreamSink(Deno.stderr.writable);
+~~~~
+
+~~~~ typescript
+// Node.js:
+import stream from "node:stream";
+const stderrSink = getStreamSink(stream.Writable.toWeb(process.stderr));
+~~~~
+
+> [!NOTE]
+> Here we use `WritableStream` from the Web Streams API.  If you are using
+> Node.js, you cannot directly pass `process.stderr` to `getStreamSink` because
+> `process.stderr` is not a `WritableStream` but a [`Writable`], which is a
+> Node.js stream.  You can use [`Writable.toWeb()`] method to convert a Node.js
+> stream to a `WritableStream`.
+
+[`WritableStream`]: https://developer.mozilla.org/en-US/docs/Web/API/WritableStream
+[`Writable`]: https://nodejs.org/api/stream.html#class-streamwritable
+[`Writable.toWeb()`]: https://nodejs.org/api/stream.html#streamwritabletowebstreamwritable

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,86 @@
+/**
+ * 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] category·subcategory: 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]);
+    }
+    const category = record.category.join("\xb7");
+    return `${ts.toISOString().replace("T", " ").replace("Z", " +00:00")} [${levelAbbreviations[record.level]}] ${category}: ${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,
+    ];
+}