@logtape/file 0.9.0-dev.1

package/script/_dnt.shims.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dntGlobalThis = void 0;
+const dntGlobals = {};
+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/file/filesink.base.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBaseFileSink = getBaseFileSink;
+exports.getBaseRotatingFileSink = getBaseRotatingFileSink;
+const mod_js_1 = require("../logtape/mod.js");
+/**
+ * Get a platform-independent file sink.
+ *
+ * @typeParam TFile The type of the file descriptor.
+ * @param path A path to the file to write to.
+ * @param options The options for the sink and the file driver.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+function getBaseFileSink(path, options) {
+    const formatter = options.formatter ?? mod_js_1.defaultTextFormatter;
+    const encoder = options.encoder ?? new TextEncoder();
+    const fd = options.openSync(path);
+    const sink = (record) => {
+        options.writeSync(fd, encoder.encode(formatter(record)));
+        options.flushSync(fd);
+    };
+    sink[Symbol.dispose] = () => options.closeSync(fd);
+    return sink;
+}
+/**
+ * Get a platform-independent rotating file sink.
+ *
+ * This sink writes log records to a file, and rotates the file when it reaches
+ * the `maxSize`.  The rotated files are named with the original file name
+ * followed by a dot and a number, starting from 1.  The number is incremented
+ * for each rotation, and the maximum number of files to keep is `maxFiles`.
+ *
+ * @param path A path to the file to write to.
+ * @param options The options for the sink and the file driver.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+function getBaseRotatingFileSink(path, options) {
+    const formatter = options.formatter ?? mod_js_1.defaultTextFormatter;
+    const encoder = options.encoder ?? new TextEncoder();
+    const maxSize = options.maxSize ?? 1024 * 1024;
+    const maxFiles = options.maxFiles ?? 5;
+    let offset = 0;
+    try {
+        const stat = options.statSync(path);
+        offset = stat.size;
+    }
+    catch {
+        // Continue as the offset is already 0.
+    }
+    let fd = options.openSync(path);
+    function shouldRollover(bytes) {
+        return offset + bytes.length > maxSize;
+    }
+    function performRollover() {
+        options.closeSync(fd);
+        for (let i = maxFiles - 1; i > 0; i--) {
+            const oldPath = `${path}.${i}`;
+            const newPath = `${path}.${i + 1}`;
+            try {
+                options.renameSync(oldPath, newPath);
+            }
+            catch (_) {
+                // Continue if the file does not exist.
+            }
+        }
+        options.renameSync(path, `${path}.1`);
+        offset = 0;
+        fd = options.openSync(path);
+    }
+    const sink = (record) => {
+        const bytes = encoder.encode(formatter(record));
+        if (shouldRollover(bytes))
+            performRollover();
+        options.writeSync(fd, bytes);
+        options.flushSync(fd);
+        offset += bytes.length;
+    };
+    sink[Symbol.dispose] = () => options.closeSync(fd);
+    return sink;
+}

package/script/file/filesink.node.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeDriver = void 0;
+exports.getFileSink = getFileSink;
+exports.getRotatingFileSink = getRotatingFileSink;
+const node_fs_1 = __importDefault(require("node:fs"));
+const filesink_base_js_1 = require("./filesink.base.js");
+/**
+ * A Node.js-specific file sink driver.
+ */
+exports.nodeDriver = {
+    openSync(path) {
+        return node_fs_1.default.openSync(path, "a");
+    },
+    writeSync: node_fs_1.default.writeSync,
+    flushSync: node_fs_1.default.fsyncSync,
+    closeSync: node_fs_1.default.closeSync,
+    statSync: node_fs_1.default.statSync,
+    renameSync: node_fs_1.default.renameSync,
+};
+/**
+ * Get a file sink.
+ *
+ * Note that this function is unavailable in the browser.
+ *
+ * @param path A path to the file to write to.
+ * @param options The options for the sink.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+function getFileSink(path, options = {}) {
+    return (0, filesink_base_js_1.getBaseFileSink)(path, { ...options, ...exports.nodeDriver });
+}
+/**
+ * Get a rotating file sink.
+ *
+ * This sink writes log records to a file, and rotates the file when it reaches
+ * the `maxSize`.  The rotated files are named with the original file name
+ * followed by a dot and a number, starting from 1.  The number is incremented
+ * for each rotation, and the maximum number of files to keep is `maxFiles`.
+ *
+ * Note that this function is unavailable in the browser.
+ *
+ * @param path A path to the file to write to.
+ * @param options The options for the sink and the file driver.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+function getRotatingFileSink(path, options = {}) {
+    return (0, filesink_base_js_1.getBaseRotatingFileSink)(path, { ...options, ...exports.nodeDriver });
+}
+// cSpell: ignore filesink

package/script/file/mod.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRotatingFileSink = exports.getFileSink = void 0;
+var filesink_node_js_1 = require("./filesink.node.js");
+Object.defineProperty(exports, "getFileSink", { enumerable: true, get: function () { return filesink_node_js_1.getFileSink; } });
+Object.defineProperty(exports, "getRotatingFileSink", { enumerable: true, get: function () { return filesink_node_js_1.getRotatingFileSink; } });

package/script/logtape/config.js

@@ -0,0 +1,321 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = void 0;
+exports.configure = configure;
+exports.configureSync = configureSync;
+exports.getConfig = getConfig;
+exports.reset = reset;
+exports.resetSync = resetSync;
+exports.dispose = dispose;
+exports.disposeSync = disposeSync;
+const dntShim = __importStar(require("../_dnt.shims.js"));
+const filter_js_1 = require("./filter.js");
+const logger_js_1 = require("./logger.js");
+const sink_js_1 = require("./sink.js");
+/**
+ * The current configuration, if any.  Otherwise, `null`.
+ */
+let currentConfig = null;
+/**
+ * Strong references to the loggers.
+ * This is to prevent the loggers from being garbage collected so that their
+ * sinks and filters are not removed.
+ */
+const strongRefs = new Set();
+/**
+ * Disposables to dispose when resetting the configuration.
+ */
+const disposables = new Set();
+/**
+ * Async disposables to dispose when resetting the configuration.
+ */
+const asyncDisposables = new Set();
+/**
+ * Check if a config is for the meta logger.
+ */
+function isLoggerConfigMeta(cfg) {
+    return cfg.category.length === 0 ||
+        (cfg.category.length === 1 && cfg.category[0] === "logtape") ||
+        (cfg.category.length === 2 &&
+            cfg.category[0] === "logtape" &&
+            cfg.category[1] === "meta");
+}
+/**
+ * Configure the loggers with the specified configuration.
+ *
+ * Note that if the given sinks or filters are disposable, they will be
+ * disposed when the configuration is reset, or when the process exits.
+ *
+ * @example
+ * ```typescript
+ * await 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.
+ */
+async function configure(config) {
+    if (currentConfig != null && !config.reset) {
+        throw new ConfigError("Already configured; if you want to reset, turn on the reset flag.");
+    }
+    await reset();
+    try {
+        configureInternal(config, true);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            await reset();
+        throw e;
+    }
+}
+/**
+ * Configure sync loggers with the specified configuration.
+ *
+ * Note that if the given sinks or filters are disposable, they will be
+ * disposed when the configuration is reset, or when the process exits.
+ *
+ * Also note that passing async sinks or filters will throw. If
+ * necessary use {@link resetSync} or {@link disposeSync}.
+ *
+ * @example
+ * ```typescript
+ * configureSync({
+ *   sinks: {
+ *     console: getConsoleSink(),
+ *   },
+ *   loggers: [
+ *     {
+ *       category: "my-app",
+ *       sinks: ["console"],
+ *       level: "info",
+ *     },
+ *     {
+ *       category: "logtape",
+ *       sinks: ["console"],
+ *       level: "error",
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @param config The configuration.
+ * @since 0.9.0
+ */
+function configureSync(config) {
+    if (currentConfig != null && !config.reset) {
+        throw new ConfigError("Already configured; if you want to reset, turn on the reset flag.");
+    }
+    if (asyncDisposables.size > 0) {
+        throw new ConfigError("Previously configured async disposables are still active. " +
+            "Use configure() instead or explicitly dispose them using dispose().");
+    }
+    resetSync();
+    try {
+        configureInternal(config, false);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            resetSync();
+        throw e;
+    }
+}
+function configureInternal(config, allowAsync) {
+    currentConfig = config;
+    let metaConfigured = false;
+    let levelUsed = false;
+    for (const cfg of config.loggers) {
+        if (isLoggerConfigMeta(cfg)) {
+            metaConfigured = true;
+        }
+        const logger = logger_js_1.LoggerImpl.getLogger(cfg.category);
+        for (const sinkId of cfg.sinks ?? []) {
+            const sink = config.sinks[sinkId];
+            if (!sink) {
+                throw new ConfigError(`Sink not found: ${sinkId}.`);
+            }
+            logger.sinks.push(sink);
+        }
+        logger.parentSinks = cfg.parentSinks ?? "inherit";
+        if (cfg.lowestLevel !== undefined) {
+            logger.lowestLevel = cfg.lowestLevel;
+        }
+        if (cfg.level !== undefined) {
+            levelUsed = true;
+            logger.filters.push((0, filter_js_1.toFilter)(cfg.level));
+        }
+        for (const filterId of cfg.filters ?? []) {
+            const filter = config.filters?.[filterId];
+            if (filter === undefined) {
+                throw new ConfigError(`Filter not found: ${filterId}.`);
+            }
+            logger.filters.push((0, filter_js_1.toFilter)(filter));
+        }
+        strongRefs.add(logger);
+    }
+    logger_js_1.LoggerImpl.getLogger().contextLocalStorage = config.contextLocalStorage;
+    for (const sink of Object.values(config.sinks)) {
+        if (Symbol.asyncDispose in sink) {
+            if (allowAsync)
+                asyncDisposables.add(sink);
+            else {
+                throw new ConfigError("Async disposables cannot be used with configureSync().");
+            }
+        }
+        if (Symbol.dispose in sink)
+            disposables.add(sink);
+    }
+    for (const filter of Object.values(config.filters ?? {})) {
+        if (filter == null || typeof filter === "string")
+            continue;
+        if (Symbol.asyncDispose in filter) {
+            if (allowAsync)
+                asyncDisposables.add(filter);
+            else {
+                throw new ConfigError("Async disposables cannot be used with configureSync().");
+            }
+        }
+        if (Symbol.dispose in filter)
+            disposables.add(filter);
+    }
+    if ("process" in dntShim.dntGlobalThis && !("Deno" in dntShim.dntGlobalThis)) {
+        // @ts-ignore: It's fine to use process in Node
+        // deno-lint-ignore no-process-global
+        process.on("exit", allowAsync ? dispose : disposeSync);
+    }
+    else {
+        // @ts-ignore: It's fine to addEventListener() on the browser/Deno
+        addEventListener("unload", allowAsync ? dispose : disposeSync);
+    }
+    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 automatically 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}.  See also " +
+        "<https://logtape.org/manual/categories#meta-logger>.", { metaLoggerCategory: ["logtape", "meta"], dismissLevel: "info" });
+    if (levelUsed) {
+        meta.warn("The level option is deprecated in favor of lowestLevel option.  " +
+            "Please update your configuration.  See also " +
+            "<https://logtape.org/manual/levels#configuring-severity-levels>.");
+    }
+}
+/**
+ * Get the current configuration, if any.  Otherwise, `null`.
+ * @returns The current configuration, if any.  Otherwise, `null`.
+ */
+function getConfig() {
+    return currentConfig;
+}
+/**
+ * Reset the configuration.  Mostly for testing purposes.
+ */
+async function reset() {
+    await dispose();
+    resetInternal();
+}
+/**
+ * Reset the configuration.  Mostly for testing purposes. Will not clear async
+ * sinks, only use with sync sinks. Use {@link reset} if you have async sinks.
+ * @since 0.9.0
+ */
+function resetSync() {
+    disposeSync();
+    resetInternal();
+}
+function resetInternal() {
+    const rootLogger = logger_js_1.LoggerImpl.getLogger([]);
+    rootLogger.resetDescendants();
+    delete rootLogger.contextLocalStorage;
+    strongRefs.clear();
+    currentConfig = null;
+}
+/**
+ * Dispose of the disposables.
+ */
+async function dispose() {
+    disposeSync();
+    const promises = [];
+    for (const disposable of asyncDisposables) {
+        promises.push(disposable[Symbol.asyncDispose]());
+        asyncDisposables.delete(disposable);
+    }
+    await Promise.all(promises);
+}
+/**
+ * Dispose of the sync disposables. Async disposables will be untouched,
+ * use {@link dispose} if you have async sinks.
+ * @since 0.9.0
+ */
+function disposeSync() {
+    for (const disposable of disposables)
+        disposable[Symbol.dispose]();
+    disposables.clear();
+}
+/**
+ * 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/logtape/context.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withContext = withContext;
+const logger_js_1 = require("./logger.js");
+/**
+ * Runs a callback with the given implicit context.  Every single log record
+ * in the callback will have the given context.
+ *
+ * If no `contextLocalStorage` is configured, this function does nothing and
+ * just returns the return value of the callback.  It also logs a warning to
+ * the `["logtape", "meta"]` logger in this case.
+ * @param context The context to inject.
+ * @param callback The callback to run.
+ * @returns The return value of the callback.
+ * @since 0.7.0
+ */
+function withContext(context, callback) {
+    const rootLogger = logger_js_1.LoggerImpl.getLogger();
+    if (rootLogger.contextLocalStorage == null) {
+        logger_js_1.LoggerImpl.getLogger(["logtape", "meta"]).warn("Context-local storage is not configured.  " +
+            "Specify contextLocalStorage option in the configure() function.");
+        return callback();
+    }
+    const parentContext = rootLogger.contextLocalStorage.getStore() ?? {};
+    return rootLogger.contextLocalStorage.run({ ...parentContext, ...context }, callback);
+}

package/script/logtape/filter.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toFilter = toFilter;
+exports.getLevelFilter = getLevelFilter;
+/**
+ * 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);
+}
+/**
+ * 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}.`);
+}