@fgv/ts-utils 5.0.0-22 → 5.0.0-24

package/lib/packlets/logging/logger.d.ts

@@ -0,0 +1,183 @@
+import { MessageLogLevel, Success } from '../base';
+/**
+ * The level of logging to be used.
+ * @public
+ */
+export type ReporterLogLevel = 'all' | 'detail' | 'info' | 'warning' | 'error' | 'silent';
+/**
+ * Compares two log levels.
+ * @param message - The first log level.
+ * @param reporter - The second log level.
+ * @returns `true` if the message should be logged, `false` if it should be suppressed.
+ * @public
+ */
+export declare function shouldLog(message: MessageLogLevel, reporter: ReporterLogLevel): boolean;
+/**
+ * Generic Result-aware logger interface with multiple levels of logging.
+ * @public
+ */
+export interface ILogger {
+    /**
+     * The level of logging to be used.
+     */
+    readonly logLevel: ReporterLogLevel;
+    /**
+     * Logs a message at the given level.
+     * @param level - The level of the message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * Logs a detail message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * Logs an info message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * Logs a warning message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * Logs an error message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+}
+/**
+ * Abstract base class which implements {@link Logging.ILogger | ILogger}.
+ * @public
+ */
+export declare abstract class LoggerBase implements ILogger {
+    /**
+     * {@inheritDoc Logging.ILogger.logLevel}
+     */
+    logLevel: ReporterLogLevel;
+    protected constructor(logLevel?: ReporterLogLevel);
+    /**
+     * {@inheritDoc Logging.ILogger.detail}
+     */
+    detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * {@inheritDoc Logging.ILogger.info}
+     */
+    info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * {@inheritDoc Logging.ILogger.warn}
+     */
+    warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * {@inheritDoc Logging.ILogger.error}
+     */
+    error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * {@inheritDoc Logging.ILogger.log}
+     */
+    log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * Formats a message and parameters into a string.
+     * @param message - The message to format.
+     * @param parameters - The parameters to format.
+     * @returns The formatted message.
+     * @public
+     */
+    protected _format(message?: unknown, ...parameters: unknown[]): string;
+    /**
+     * Inner method called for suppressed log messages.
+     */
+    protected _suppressLog(__level: MessageLogLevel, __message?: unknown, ...__parameters: unknown[]): Success<undefined>;
+    protected abstract _log(message: string, level: MessageLogLevel): Success<string | undefined>;
+}
+/**
+ * An in-memory logger that stores logged and suppressed messages.
+ * @public
+ */
+export declare class InMemoryLogger extends LoggerBase {
+    /**
+     * The messages that have been logged.
+     */
+    protected _logged: string[];
+    /**
+     * The messages that have been suppressed.
+     */
+    protected _suppressed: string[];
+    /**
+     * Creates a new in-memory logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel?: ReporterLogLevel);
+    /**
+     * The messages that have been logged.
+     */
+    get logged(): string[];
+    /**
+     * The messages that have been suppressed.
+     */
+    get suppressed(): string[];
+    /**
+     * Clears the logged and suppressed messages.
+     */
+    clear(): void;
+    /**
+     * {@inheritDoc Logging.LoggerBase._log}
+     */
+    protected _log(message: string, __level: MessageLogLevel): Success<string | undefined>;
+    /**
+     * {@inheritDoc Logging.LoggerBase._suppressLog}
+     * @param level - The level of the message.
+     * @param message - The message to suppress.
+     * @param parameters - The parameters to suppress.
+     * @returns `Success` with `undefined` if the message is suppressed.
+     */
+    protected _suppressLog(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<undefined>;
+}
+/**
+ * A console logger that outputs messages to the console.
+ * @public
+ */
+export declare class ConsoleLogger extends LoggerBase {
+    /**
+     * Creates a new console logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel?: ReporterLogLevel);
+    /**
+     * {@inheritDoc Logging.LoggerBase._log}
+     */
+    protected _log(message: string, level: MessageLogLevel): Success<string | undefined>;
+}
+/**
+ * A no-op {@link Logging.LoggerBase | LoggerBase} that does not log anything.
+ * @public
+ */
+export declare class NoOpLogger extends LoggerBase {
+    /**
+     * Creates a new no-op logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel?: ReporterLogLevel);
+    /**
+     * {@inheritDoc Logging.LoggerBase._log}
+     */
+    protected _log(message: string, __level: MessageLogLevel): Success<string | undefined>;
+}
+//# sourceMappingURL=logger.d.ts.map

package/lib/packlets/logging/logger.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoOpLogger = exports.ConsoleLogger = exports.InMemoryLogger = exports.LoggerBase = void 0;
+exports.shouldLog = shouldLog;
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * 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.
+ */
+const base_1 = require("../base");
+/**
+ * Compares two log levels.
+ * @param message - The first log level.
+ * @param reporter - The second log level.
+ * @returns `true` if the message should be logged, `false` if it should be suppressed.
+ * @public
+ */
+function shouldLog(message, reporter) {
+    if (reporter === 'all') {
+        return true; // 'all' logs everything, including 'quiet'
+    }
+    if (reporter === 'silent') {
+        return false; // 'silent' suppresses everything
+    }
+    if (message === 'quiet') {
+        return false; // 'quiet' messages only show when reporter is 'all'
+    }
+    switch (reporter) {
+        case 'error':
+            return message === 'error';
+        case 'warning':
+            return message === 'warning' || message === 'error';
+        case 'info':
+            return message !== 'detail';
+    }
+    return true;
+}
+/**
+ * Abstract base class which implements {@link Logging.ILogger | ILogger}.
+ * @public
+ */
+class LoggerBase {
+    constructor(logLevel) {
+        /**
+         * {@inheritDoc Logging.ILogger.logLevel}
+         */
+        this.logLevel = 'info';
+        this.logLevel = logLevel !== null && logLevel !== void 0 ? logLevel : 'info';
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.detail}
+     */
+    detail(message, ...parameters) {
+        return this.log('detail', message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.info}
+     */
+    info(message, ...parameters) {
+        return this.log('info', message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.warn}
+     */
+    warn(message, ...parameters) {
+        return this.log('warning', message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.error}
+     */
+    error(message, ...parameters) {
+        return this.log('error', message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.log}
+     */
+    log(level, message, ...parameters) {
+        if (shouldLog(level, this.logLevel)) {
+            const formatted = this._format(message, ...parameters);
+            return this._log(formatted, level);
+        }
+        return this._suppressLog(level, message, ...parameters);
+    }
+    /**
+     * Formats a message and parameters into a string.
+     * @param message - The message to format.
+     * @param parameters - The parameters to format.
+     * @returns The formatted message.
+     * @public
+     */
+    _format(message, ...parameters) {
+        const raw = [message, ...parameters];
+        const filtered = raw.filter((m) => m !== undefined);
+        const strings = filtered.map((m) => m.toString());
+        const joined = strings.join('');
+        return joined;
+    }
+    /**
+     * Inner method called for suppressed log messages.
+     */
+    _suppressLog(__level, __message, ...__parameters) {
+        return (0, base_1.succeed)(undefined);
+    }
+}
+exports.LoggerBase = LoggerBase;
+/**
+ * An in-memory logger that stores logged and suppressed messages.
+ * @public
+ */
+class InMemoryLogger extends LoggerBase {
+    /**
+     * Creates a new in-memory logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel) {
+        super(logLevel);
+        /**
+         * The messages that have been logged.
+         */
+        this._logged = [];
+        /**
+         * The messages that have been suppressed.
+         */
+        this._suppressed = [];
+    }
+    /**
+     * The messages that have been logged.
+     */
+    get logged() {
+        return this._logged;
+    }
+    /**
+     * The messages that have been suppressed.
+     */
+    get suppressed() {
+        return this._suppressed;
+    }
+    /**
+     * Clears the logged and suppressed messages.
+     */
+    clear() {
+        this._logged = [];
+        this._suppressed = [];
+    }
+    /**
+     * {@inheritDoc Logging.LoggerBase._log}
+     */
+    _log(message, __level) {
+        this._logged.push(message);
+        return (0, base_1.succeed)(message);
+    }
+    /**
+     * {@inheritDoc Logging.LoggerBase._suppressLog}
+     * @param level - The level of the message.
+     * @param message - The message to suppress.
+     * @param parameters - The parameters to suppress.
+     * @returns `Success` with `undefined` if the message is suppressed.
+     */
+    _suppressLog(level, message, ...parameters) {
+        const formatted = this._format(message, ...parameters);
+        this._suppressed.push(formatted);
+        return (0, base_1.succeed)(undefined);
+    }
+}
+exports.InMemoryLogger = InMemoryLogger;
+/**
+ * A console logger that outputs messages to the console.
+ * @public
+ */
+class ConsoleLogger extends LoggerBase {
+    /**
+     * Creates a new console logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel) {
+        super(logLevel);
+    }
+    /**
+     * {@inheritDoc Logging.LoggerBase._log}
+     */
+    _log(message, level) {
+        switch (level) {
+            case 'error':
+                console.error(message);
+                break;
+            case 'warning':
+                console.warn(message);
+                break;
+            case 'info':
+                console.info(message);
+                break;
+            default:
+                console.log(message);
+                break;
+        }
+        return (0, base_1.succeed)(message);
+    }
+}
+exports.ConsoleLogger = ConsoleLogger;
+/**
+ * A no-op {@link Logging.LoggerBase | LoggerBase} that does not log anything.
+ * @public
+ */
+class NoOpLogger extends LoggerBase {
+    /**
+     * Creates a new no-op logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel) {
+        super(logLevel);
+    }
+    /**
+     * {@inheritDoc Logging.LoggerBase._log}
+     */
+    _log(message, __level) {
+        // no-op
+        return (0, base_1.succeed)(message);
+    }
+}
+exports.NoOpLogger = NoOpLogger;
+//# sourceMappingURL=logger.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-utils",
-  "version": "5.0.0-22",
+  "version": "5.0.0-24",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-utils.d.ts",
@@ -35,14 +35,14 @@
     "rimraf": "^5.0.7",
     "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.8.3",
+    "typescript": "5.8.3",
     "eslint-plugin-n": "^16.6.2",
     "jest-snapshot": "~29.7.0",
-    "@rushstack/heft": "~0.74.2",
-    "@rushstack/heft-node-rig": "~2.9.3",
-    "@rushstack/eslint-config": "~4.4.0",
+    "@rushstack/heft": "0.74.3",
+    "@rushstack/heft-node-rig": "2.9.4",
+    "@rushstack/eslint-config": "4.4.0",
     "@types/heft-jest": "1.0.6",
-    "@rushstack/heft-jest-plugin": "~0.16.11",
+    "@rushstack/heft-jest-plugin": "0.16.12",
     "eslint-plugin-tsdoc": "~0.4.0"
   },
   "scripts": {

package/.vscode/launch.json

@@ -1,16 +0,0 @@
-{
-  // Use IntelliSense to learn about possible attributes.
-  // Hover to view descriptions of existing attributes.
-  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "type": "node",
-      "request": "launch",
-      "name": "Launch Program",
-      "skipFiles": ["<node_internals>/**"],
-      "program": "${workspaceFolder}/lib/index.js",
-      "outFiles": ["${workspaceFolder}/**/*.js"]
-    }
-  ]
-}

package/.vscode/settings.json

@@ -1,36 +0,0 @@
-{
-  "typescript.tsdk": "node_modules\\typescript\\lib",
-  "search.exclude": {
-    "**/boneyard": true
-  },
-  "files.exclude": {
-    "**/boneyard/**/*.ts": true
-  },
-  "cSpell.words": [
-    "badp",
-    "convalidate",
-    "Convalidator",
-    "dflt",
-    "Eulers",
-    "fixlint",
-    "flintstone",
-    "furst",
-    "jetson",
-    "luxon",
-    "nums",
-    "oopsy",
-    "packlets",
-    "papaparse",
-    "prefixp",
-    "TCONV",
-    "TDEST",
-    "TELEM",
-    "TINDEX",
-    "TITEM",
-    "TKEY",
-    "TSRC",
-    "TTOELEM",
-    "Unvalidated",
-    "xyzzy"
-  ]
-}