@itwin/core-bentley 4.0.0-dev.8 → 4.0.0-dev.81

package/lib/esm/Logger.js

@@ -1,254 +1,254 @@
-/*---------------------------------------------------------------------------------------------
-* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
-* See LICENSE.md in the project root for license terms and full copyright notice.
-*--------------------------------------------------------------------------------------------*/
-/** @packageDocumentation
- * @module Logging
- */
-import { BentleyError, IModelStatus } from "./BentleyError";
-import { BentleyLoggerCategory } from "./BentleyLoggerCategory";
-/** Use to categorize logging messages by severity.
- * @public
- */
-export var LogLevel;
-(function (LogLevel) {
-    /** Tracing and debugging - low level */
-    LogLevel[LogLevel["Trace"] = 0] = "Trace";
-    /** Information - mid level */
-    LogLevel[LogLevel["Info"] = 1] = "Info";
-    /** Warnings - high level */
-    LogLevel[LogLevel["Warning"] = 2] = "Warning";
-    /** Errors - highest level */
-    LogLevel[LogLevel["Error"] = 3] = "Error";
-    /** Higher than any real logging level. This is used to turn a category off. */
-    LogLevel[LogLevel["None"] = 4] = "None";
-})(LogLevel || (LogLevel = {}));
-/** Logger allows libraries and apps to report potentially useful information about operations, and it allows apps and users to control
- * how or if the logged information is displayed or collected. See [Learning about Logging]($docs/learning/common/Logging.md).
- * @public
- */
-export class Logger {
-    /** Initialize the logger streams. Should be called at application initialization time. */
-    static initialize(logError, logWarning, logInfo, logTrace) {
-        Logger._logError = logError;
-        Logger._logWarning = logWarning;
-        Logger._logInfo = logInfo;
-        Logger._logTrace = logTrace;
-        Logger.turnOffLevelDefault();
-        Logger.turnOffCategories();
-    }
-    /** Initialize the logger to output to the console. */
-    static initializeToConsole() {
-        const logConsole = (level) => (category, message, metaData) => console.log(`${level} | ${category} | ${message} ${Logger.stringifyMetaData(metaData)}`); // eslint-disable-line no-console
-        Logger.initialize(logConsole("Error"), logConsole("Warning"), logConsole("Info"), logConsole("Trace"));
-    }
-    /** merge the supplied metadata with all static metadata into one object */
-    static getMetaData(metaData) {
-        const metaObj = {};
-        for (const meta of Logger.staticMetaData) {
-            const val = BentleyError.getMetaData(meta[1]);
-            if (val)
-                Object.assign(metaObj, val);
-        }
-        Object.assign(metaObj, BentleyError.getMetaData(metaData)); // do this last so user supplied values take precedence
-        return metaObj;
-    }
-    /** stringify the metadata for a log message by merging the supplied metadata with all static metadata into one object that is then `JSON.stringify`ed. */
-    static stringifyMetaData(metaData) {
-        const metaObj = this.getMetaData(metaData);
-        return Object.keys(metaObj).length > 0 ? JSON.stringify(metaObj) : "";
-    }
-    /** Set the least severe level at which messages should be displayed by default. Call setLevel to override this default setting for specific categories. */
-    static setLevelDefault(minLevel) {
-        var _a;
-        this._minLevel = minLevel;
-        (_a = this.logLevelChangedFn) === null || _a === void 0 ? void 0 : _a.call(this);
-    }
-    /** Set the minimum logging level for the specified category. The minimum level is least severe level at which messages in the
-     * specified category should be displayed.
-     */
-    static setLevel(category, minLevel) {
-        var _a;
-        Logger._categoryFilter.set(category, minLevel);
-        (_a = this.logLevelChangedFn) === null || _a === void 0 ? void 0 : _a.call(this);
-    }
-    /** Interpret a string as the name of a LogLevel */
-    static parseLogLevel(str) {
-        switch (str.toUpperCase()) {
-            case "EXCEPTION": return LogLevel.Error;
-            case "FATAL": return LogLevel.Error;
-            case "ERROR": return LogLevel.Error;
-            case "WARNING": return LogLevel.Warning;
-            case "INFO": return LogLevel.Info;
-            case "TRACE": return LogLevel.Trace;
-            case "DEBUG": return LogLevel.Trace;
-        }
-        return LogLevel.None;
-    }
-    /** Set the log level for multiple categories at once. Also see [[validateProps]] */
-    static configureLevels(cfg) {
-        Logger.validateProps(cfg);
-        if (cfg.defaultLevel !== undefined) {
-            this.setLevelDefault(Logger.parseLogLevel(cfg.defaultLevel));
-        }
-        if (cfg.categoryLevels !== undefined) {
-            for (const cl of cfg.categoryLevels) {
-                this.setLevel(cl.category, Logger.parseLogLevel(cl.logLevel));
-            }
-        }
-    }
-    static isLogLevel(v) {
-        return LogLevel.hasOwnProperty(v);
-    }
-    /** Check that the specified object is a valid LoggerLevelsConfig. This is useful when reading a config from a .json file. */
-    static validateProps(config) {
-        const validProps = ["defaultLevel", "categoryLevels"];
-        for (const prop of Object.keys(config)) {
-            if (!validProps.includes(prop))
-                throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig - unrecognized property: ${prop}`);
-            if (prop === "defaultLevel") {
-                if (!Logger.isLogLevel(config.defaultLevel))
-                    throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig.defaultLevel must be a LogLevel. Invalid value: ${JSON.stringify(config.defaultLevel)}`);
-            }
-            else if (prop === "categoryLevels") {
-                const value = config[prop];
-                if (!Array.isArray(value))
-                    throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig.categoryLevels must be an array. Invalid value: ${JSON.stringify(value)}`);
-                for (const item of config[prop]) {
-                    if (!item.hasOwnProperty("category") || !item.hasOwnProperty("logLevel"))
-                        throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig.categoryLevels - each item must be a LoggerCategoryAndLevel {category: logLevel:}. Invalid value: ${JSON.stringify(item)}`);
-                    if (!Logger.isLogLevel(item.logLevel))
-                        throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig.categoryLevels - each item's logLevel property must be a LogLevel. Invalid value: ${JSON.stringify(item.logLevel)}`);
-                }
-            }
-        }
-    }
-    /** Get the minimum logging level for the specified category. */
-    static getLevel(category) {
-        // Prefer the level set for this category specifically
-        const minLevelForThisCategory = Logger._categoryFilter.get(category);
-        if (minLevelForThisCategory !== undefined)
-            return minLevelForThisCategory;
-        // Fall back on the level set for the parent of this category.
-        const parent = category.lastIndexOf(".");
-        if (parent !== -1)
-            return Logger.getLevel(category.slice(0, parent));
-        // Fall back on the default level.
-        return Logger._minLevel;
-    }
-    /** Turns off the least severe level at which messages should be displayed by default.
-     * This turns off logging for all messages for which no category minimum level is defined.
-     */
-    static turnOffLevelDefault() {
-        Logger._minLevel = undefined;
-    }
-    /** Turns off all category level filters previously defined with [[Logger.setLevel]].
-     */
-    static turnOffCategories() {
-        Logger._categoryFilter.clear();
-    }
-    /** Check if messages in the specified category should be displayed at this level of severity. */
-    static isEnabled(category, level) {
-        const minLevel = Logger.getLevel(category);
-        return (minLevel !== undefined) && (level >= minLevel);
-    }
-    /** Log the specified message to the **error** stream.
-     * @param category  The category of the message.
-     * @param message  The message.
-     * @param metaData  Optional data for the message
-     */
-    static logError(category, message, metaData) {
-        if (Logger._logError && Logger.isEnabled(category, LogLevel.Error))
-            Logger._logError(category, message, metaData);
-    }
-    static getExceptionMessage(err) {
-        const stack = Logger.logExceptionCallstacks ? `\n${BentleyError.getErrorStack(err)}` : "";
-        return BentleyError.getErrorMessage(err) + stack;
-    }
-    /** Log the specified exception. The special "ExceptionType" property will be added as metadata,
-     * in addition to any other metadata that may be supplied by the caller, unless the
-     * metadata supplied by the caller already includes this property.
-     * @param category  The category of the message.
-     * @param err  The exception object.
-     * @param log The logger output function to use - defaults to Logger.logError
-     * @param metaData  Optional data for the message
-     */
-    static logException(category, err, log = Logger.logError) {
-        log(category, Logger.getExceptionMessage(err), () => {
-            return { ...BentleyError.getErrorMetadata(err), exceptionType: err.constructor.name };
-        });
-    }
-    /** Log the specified message to the **warning** stream.
-     * @param category  The category of the message.
-     * @param message  The message.
-     * @param metaData  Optional data for the message
-     */
-    static logWarning(category, message, metaData) {
-        if (Logger._logWarning && Logger.isEnabled(category, LogLevel.Warning))
-            Logger._logWarning(category, message, metaData);
-    }
-    /** Log the specified message to the **info** stream.
-     * @param category  The category of the message.
-     * @param message  The message.
-     * @param metaData  Optional data for the message
-     */
-    static logInfo(category, message, metaData) {
-        if (Logger._logInfo && Logger.isEnabled(category, LogLevel.Info))
-            Logger._logInfo(category, message, metaData);
-    }
-    /** Log the specified message to the **trace** stream.
-     * @param category  The category of the message.
-     * @param message  The message.
-     * @param metaData  Optional data for the message
-     */
-    static logTrace(category, message, metaData) {
-        if (Logger._logTrace && Logger.isEnabled(category, LogLevel.Trace))
-            Logger._logTrace(category, message, metaData);
-    }
-}
-Logger._categoryFilter = new Map(); // do not change the name of this member, it is referenced directly from node addon
-Logger._minLevel = undefined; // do not change the name of this member, it is referenced directly from node addon
-/** Should the call stack be included when an exception is logged?  */
-Logger.logExceptionCallstacks = false;
-/** All static metadata is combined with per-call metadata and stringified in every log message.
- * Static metadata can either be an object or a function that returns an object.
- * Use a key to identify entries in the map so the can be removed individually.
- * @internal */
-Logger.staticMetaData = new Map();
-/** Simple performance diagnostics utility.
- * It measures the time from construction to disposal. On disposal it logs the routine name along with
- * the duration in milliseconds.
- * It also logs the routine name at construction time so that nested calls can be disambiguated.
- *
- * The timings are logged using the log category **Performance** and log severity [[LogLevel.INFO]].
- * Enable those, if you want to capture timings.
- * @public
- */
-export class PerfLogger {
-    constructor(operation, metaData) {
-        this._operation = operation;
-        this._metaData = metaData;
-        if (!Logger.isEnabled(BentleyLoggerCategory.Performance, PerfLogger._severity)) {
-            this._startTimeStamp = 0;
-            return;
-        }
-        Logger.logInfo(BentleyLoggerCategory.Performance, `${this._operation},START`, this._metaData);
-        this._startTimeStamp = new Date().getTime(); // take timestamp
-    }
-    logMessage() {
-        const endTimeStamp = new Date().getTime();
-        if (!Logger.isEnabled(BentleyLoggerCategory.Performance, PerfLogger._severity))
-            return;
-        Logger.logInfo(BentleyLoggerCategory.Performance, `${this._operation},END`, () => {
-            const mdata = this._metaData ? BentleyError.getMetaData(this._metaData) : {};
-            return {
-                ...mdata, TimeElapsed: endTimeStamp - this._startTimeStamp, // eslint-disable-line @typescript-eslint/naming-convention
-            };
-        });
-    }
-    dispose() {
-        this.logMessage();
-    }
-}
-PerfLogger._severity = LogLevel.Info;
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Logging
+ */
+import { BentleyError, IModelStatus } from "./BentleyError";
+import { BentleyLoggerCategory } from "./BentleyLoggerCategory";
+/** Use to categorize logging messages by severity.
+ * @public
+ */
+export var LogLevel;
+(function (LogLevel) {
+    /** Tracing and debugging - low level */
+    LogLevel[LogLevel["Trace"] = 0] = "Trace";
+    /** Information - mid level */
+    LogLevel[LogLevel["Info"] = 1] = "Info";
+    /** Warnings - high level */
+    LogLevel[LogLevel["Warning"] = 2] = "Warning";
+    /** Errors - highest level */
+    LogLevel[LogLevel["Error"] = 3] = "Error";
+    /** Higher than any real logging level. This is used to turn a category off. */
+    LogLevel[LogLevel["None"] = 4] = "None";
+})(LogLevel || (LogLevel = {}));
+/** Logger allows libraries and apps to report potentially useful information about operations, and it allows apps and users to control
+ * how or if the logged information is displayed or collected. See [Learning about Logging]($docs/learning/common/Logging.md).
+ * @public
+ */
+class Logger {
+    /** Initialize the logger streams. Should be called at application initialization time. */
+    static initialize(logError, logWarning, logInfo, logTrace) {
+        Logger._logError = logError;
+        Logger._logWarning = logWarning;
+        Logger._logInfo = logInfo;
+        Logger._logTrace = logTrace;
+        Logger.turnOffLevelDefault();
+        Logger.turnOffCategories();
+    }
+    /** Initialize the logger to output to the console. */
+    static initializeToConsole() {
+        const logConsole = (level) => (category, message, metaData) => console.log(`${level} | ${category} | ${message} ${Logger.stringifyMetaData(metaData)}`); // eslint-disable-line no-console
+        Logger.initialize(logConsole("Error"), logConsole("Warning"), logConsole("Info"), logConsole("Trace"));
+    }
+    /** merge the supplied metadata with all static metadata into one object */
+    static getMetaData(metaData) {
+        const metaObj = {};
+        for (const meta of Logger.staticMetaData) {
+            const val = BentleyError.getMetaData(meta[1]);
+            if (val)
+                Object.assign(metaObj, val);
+        }
+        Object.assign(metaObj, BentleyError.getMetaData(metaData)); // do this last so user supplied values take precedence
+        return metaObj;
+    }
+    /** stringify the metadata for a log message by merging the supplied metadata with all static metadata into one object that is then `JSON.stringify`ed. */
+    static stringifyMetaData(metaData) {
+        const metaObj = this.getMetaData(metaData);
+        return Object.keys(metaObj).length > 0 ? JSON.stringify(metaObj) : "";
+    }
+    /** Set the least severe level at which messages should be displayed by default. Call setLevel to override this default setting for specific categories. */
+    static setLevelDefault(minLevel) {
+        this._minLevel = minLevel;
+        this.logLevelChangedFn?.();
+    }
+    /** Set the minimum logging level for the specified category. The minimum level is least severe level at which messages in the
+     * specified category should be displayed.
+     */
+    static setLevel(category, minLevel) {
+        Logger._categoryFilter.set(category, minLevel);
+        this.logLevelChangedFn?.();
+    }
+    /** Interpret a string as the name of a LogLevel */
+    static parseLogLevel(str) {
+        switch (str.toUpperCase()) {
+            case "EXCEPTION": return LogLevel.Error;
+            case "FATAL": return LogLevel.Error;
+            case "ERROR": return LogLevel.Error;
+            case "WARNING": return LogLevel.Warning;
+            case "INFO": return LogLevel.Info;
+            case "TRACE": return LogLevel.Trace;
+            case "DEBUG": return LogLevel.Trace;
+        }
+        return LogLevel.None;
+    }
+    /** Set the log level for multiple categories at once. Also see [[validateProps]] */
+    static configureLevels(cfg) {
+        Logger.validateProps(cfg);
+        if (cfg.defaultLevel !== undefined) {
+            this.setLevelDefault(Logger.parseLogLevel(cfg.defaultLevel));
+        }
+        if (cfg.categoryLevels !== undefined) {
+            for (const cl of cfg.categoryLevels) {
+                this.setLevel(cl.category, Logger.parseLogLevel(cl.logLevel));
+            }
+        }
+    }
+    static isLogLevel(v) {
+        return LogLevel.hasOwnProperty(v);
+    }
+    /** Check that the specified object is a valid LoggerLevelsConfig. This is useful when reading a config from a .json file. */
+    static validateProps(config) {
+        const validProps = ["defaultLevel", "categoryLevels"];
+        for (const prop of Object.keys(config)) {
+            if (!validProps.includes(prop))
+                throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig - unrecognized property: ${prop}`);
+            if (prop === "defaultLevel") {
+                if (!Logger.isLogLevel(config.defaultLevel))
+                    throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig.defaultLevel must be a LogLevel. Invalid value: ${JSON.stringify(config.defaultLevel)}`);
+            }
+            else if (prop === "categoryLevels") {
+                const value = config[prop];
+                if (!Array.isArray(value))
+                    throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig.categoryLevels must be an array. Invalid value: ${JSON.stringify(value)}`);
+                for (const item of config[prop]) {
+                    if (!item.hasOwnProperty("category") || !item.hasOwnProperty("logLevel"))
+                        throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig.categoryLevels - each item must be a LoggerCategoryAndLevel {category: logLevel:}. Invalid value: ${JSON.stringify(item)}`);
+                    if (!Logger.isLogLevel(item.logLevel))
+                        throw new BentleyError(IModelStatus.BadArg, `LoggerLevelsConfig.categoryLevels - each item's logLevel property must be a LogLevel. Invalid value: ${JSON.stringify(item.logLevel)}`);
+                }
+            }
+        }
+    }
+    /** Get the minimum logging level for the specified category. */
+    static getLevel(category) {
+        // Prefer the level set for this category specifically
+        const minLevelForThisCategory = Logger._categoryFilter.get(category);
+        if (minLevelForThisCategory !== undefined)
+            return minLevelForThisCategory;
+        // Fall back on the level set for the parent of this category.
+        const parent = category.lastIndexOf(".");
+        if (parent !== -1)
+            return Logger.getLevel(category.slice(0, parent));
+        // Fall back on the default level.
+        return Logger._minLevel;
+    }
+    /** Turns off the least severe level at which messages should be displayed by default.
+     * This turns off logging for all messages for which no category minimum level is defined.
+     */
+    static turnOffLevelDefault() {
+        Logger._minLevel = undefined;
+    }
+    /** Turns off all category level filters previously defined with [[Logger.setLevel]].
+     */
+    static turnOffCategories() {
+        Logger._categoryFilter.clear();
+    }
+    /** Check if messages in the specified category should be displayed at this level of severity. */
+    static isEnabled(category, level) {
+        const minLevel = Logger.getLevel(category);
+        return (minLevel !== undefined) && (level >= minLevel);
+    }
+    /** Log the specified message to the **error** stream.
+     * @param category  The category of the message.
+     * @param message  The message.
+     * @param metaData  Optional data for the message
+     */
+    static logError(category, message, metaData) {
+        if (Logger._logError && Logger.isEnabled(category, LogLevel.Error))
+            Logger._logError(category, message, metaData);
+    }
+    static getExceptionMessage(err) {
+        const stack = Logger.logExceptionCallstacks ? `\n${BentleyError.getErrorStack(err)}` : "";
+        return BentleyError.getErrorMessage(err) + stack;
+    }
+    /** Log the specified exception. The special "ExceptionType" property will be added as metadata,
+     * in addition to any other metadata that may be supplied by the caller, unless the
+     * metadata supplied by the caller already includes this property.
+     * @param category  The category of the message.
+     * @param err  The exception object.
+     * @param log The logger output function to use - defaults to Logger.logError
+     * @param metaData  Optional data for the message
+     */
+    static logException(category, err, log = Logger.logError) {
+        log(category, Logger.getExceptionMessage(err), () => {
+            return { ...BentleyError.getErrorMetadata(err), exceptionType: err.constructor.name };
+        });
+    }
+    /** Log the specified message to the **warning** stream.
+     * @param category  The category of the message.
+     * @param message  The message.
+     * @param metaData  Optional data for the message
+     */
+    static logWarning(category, message, metaData) {
+        if (Logger._logWarning && Logger.isEnabled(category, LogLevel.Warning))
+            Logger._logWarning(category, message, metaData);
+    }
+    /** Log the specified message to the **info** stream.
+     * @param category  The category of the message.
+     * @param message  The message.
+     * @param metaData  Optional data for the message
+     */
+    static logInfo(category, message, metaData) {
+        if (Logger._logInfo && Logger.isEnabled(category, LogLevel.Info))
+            Logger._logInfo(category, message, metaData);
+    }
+    /** Log the specified message to the **trace** stream.
+     * @param category  The category of the message.
+     * @param message  The message.
+     * @param metaData  Optional data for the message
+     */
+    static logTrace(category, message, metaData) {
+        if (Logger._logTrace && Logger.isEnabled(category, LogLevel.Trace))
+            Logger._logTrace(category, message, metaData);
+    }
+}
+Logger._categoryFilter = new Map(); // do not change the name of this member, it is referenced directly from node addon
+Logger._minLevel = undefined; // do not change the name of this member, it is referenced directly from node addon
+/** Should the call stack be included when an exception is logged?  */
+Logger.logExceptionCallstacks = false;
+/** All static metadata is combined with per-call metadata and stringified in every log message.
+ * Static metadata can either be an object or a function that returns an object.
+ * Use a key to identify entries in the map so the can be removed individually.
+ * @internal */
+Logger.staticMetaData = new Map();
+export { Logger };
+/** Simple performance diagnostics utility.
+ * It measures the time from construction to disposal. On disposal it logs the routine name along with
+ * the duration in milliseconds.
+ * It also logs the routine name at construction time so that nested calls can be disambiguated.
+ *
+ * The timings are logged using the log category **Performance** and log severity [[LogLevel.INFO]].
+ * Enable those, if you want to capture timings.
+ * @public
+ */
+class PerfLogger {
+    constructor(operation, metaData) {
+        this._operation = operation;
+        this._metaData = metaData;
+        if (!Logger.isEnabled(BentleyLoggerCategory.Performance, PerfLogger._severity)) {
+            this._startTimeStamp = 0;
+            return;
+        }
+        Logger.logInfo(BentleyLoggerCategory.Performance, `${this._operation},START`, this._metaData);
+        this._startTimeStamp = new Date().getTime(); // take timestamp
+    }
+    logMessage() {
+        const endTimeStamp = new Date().getTime();
+        if (!Logger.isEnabled(BentleyLoggerCategory.Performance, PerfLogger._severity))
+            return;
+        Logger.logInfo(BentleyLoggerCategory.Performance, `${this._operation},END`, () => {
+            const mdata = this._metaData ? BentleyError.getMetaData(this._metaData) : {};
+            return {
+                ...mdata, TimeElapsed: endTimeStamp - this._startTimeStamp, // eslint-disable-line @typescript-eslint/naming-convention
+            };
+        });
+    }
+    dispose() {
+        this.logMessage();
+    }
+}
+PerfLogger._severity = LogLevel.Info;
+export { PerfLogger };
 //# sourceMappingURL=Logger.js.map