@matter/general 0.13.0-alpha.0-20250322-f085fa576 → 0.13.0-alpha.0-20250324-d7b7d9731

package/src/log/Logger.ts

@@ -10,97 +10,264 @@ import { ImplementationError, NotImplementedError } from "../MatterError.js";
 import { Time } from "../time/Time.js";
 import { Bytes } from "../util/Bytes.js";
 import { Diagnostic } from "./Diagnostic.js";
+import { LogDestination, LogDestinations } from "./LogDestination.js";
 import { LogFormat } from "./LogFormat.js";
 import { LogLevel } from "./LogLevel.js";
 
 /**
- * Log messages to the console.  This is the default logging mechanism.
- */
-export function consoleLogger(level: LogLevel, formattedLog: string, _facility?: string) {
-    const console = (<any>consoleLogger).console;
-    switch (level) {
-        case LogLevel.DEBUG:
-            console.debug(formattedLog);
-            break;
-        case LogLevel.INFO:
-            console.info(formattedLog);
-            break;
-        case LogLevel.NOTICE:
-            console.info(formattedLog);
-            break;
-        case LogLevel.WARN:
-            console.warn(formattedLog);
-            break;
-        case LogLevel.ERROR:
-            console.error(formattedLog);
-            break;
-        case LogLevel.FATAL:
-            console.error(formattedLog);
-            break;
-    }
-}
-
-const globalConsole = console;
-export namespace consoleLogger {
-    /**
-     * The target for consoleLogger.
-     */
-    // eslint-disable-next-line prefer-const
-    export let console = globalConsole;
-}
-
-/**
- * Create a log formatter for a given format.
- */
-function logFormatterFor(formatName: string): LoggerDefinition["logFormatter"] {
-    const format = LogFormat(formatName);
-
-    return (now, level, facility, prefix, ...values) =>
-        format(Diagnostic.message({ now, level, facility, prefix, values }));
-}
-
-/**
- * Definition of one registered Logger.
- */
-type LoggerDefinition = {
-    logIdentifier: string;
-    logFormatter: (now: Date, level: LogLevel, facility: string, prefix: string, ...values: any[]) => string;
-    log: (level: LogLevel, formattedLog: string, facility?: string) => void;
-    defaultLogLevel: LogLevel;
-    logLevels: { [facility: string]: LogLevel };
-    context?: Diagnostic.Context;
-};
-
-/**
- * Logger that can be used to emit traces.
- *
- * The class supports adding multiple loggers for different targets. A default logger (identifier "default") is added on
- * startup which logs to "console".
+ * matter.js logging API
  *
  * Usage:
  *
- *   const facility = Logger.get("loggerName");
- *   facility.debug("My debug message", "my extra value to log");
+ *   const logger = Logger.get("loggerName");
+ *   logger.debug("My debug message", "my extra value to log");
  *
- * The configuration of the default logger can be adjusted by using the static properties of the Logger class:
+ * matter.js writes logs to each {@link LogDestination} in {@link Logger.destinations}.  By default a single destination
+ * named "default" writes to the JS console.
  *
- *   - Logger.defaultLogLevel sets the default log level for all the facility
- *   - Logger.logLevels = { loggerName: Level.DEBUG } can set the level for the specific loggers
- *   - Logger.format = Format.ANSI enables colorization via ANSI escape sequences in default formatter
+ * You may adjust log verbosity and format by modifying the properties on destinations.  For example:
  *
- * For additional loggers, use Logger.addLogger() to add a new logger with a specific identifier. Afterwards the
- * configuration of these can be adjusted using static methods with the identifier as first parameter:
- *
- *   - Logger.setFormatForLogger("loggerName", Format.ANSI)
- *   - Logger.setLogLevelsForLogger("loggerName", { loggerName: Level.DEBUG })
- *   - Logger.setDefaultLoglevelForLogger("loggerName", Level.DEBUG)
+ *   `Logger.format = LogFormat.PLAIN` sets all destinations to write plaintext
+ *   `Logger.destinations.default.format = LogFormat.format.ansi` sets one destination to write ANSI
+ *   `Logger.level = LogLevel.NOTICE` sets "notice" as the minimum level for all destinations
+ *   `Logger.destinations.default.level = LogLevel.NOTICE` sets "notice" as level for one destination
  */
 export class Logger {
-    static logger: Array<LoggerDefinition>;
+    /**
+     * Log destinations.
+     *
+     * By default there is a single destination named "default".  You can create new destinations using
+     * {@link LogDestination}.  Add or remove destinations by modifying this object.
+     *
+     * Throws an error if you access a destination that doesn't exist.
+     */
+    static destinations = LogDestinations();
+
+    /**
+     * The number of indents to print with messages.
+     */
     static nestingLevel: number;
+
     readonly #name: string;
 
-    /** Add additional logger to the list of loggers including the default configuration. */
+    /**
+     * Create a new logger for a facility.
+     *
+     * @param name the name of the facility
+     * @returns a new facility
+     */
+    static get(name: string) {
+        return new Logger(name);
+    }
+
+    /**
+     * Get the default log level.
+     */
+    static get level() {
+        return LogDestination.defaults.level;
+    }
+
+    /**
+     * Set log level as name or number for all destinations.
+     */
+    static set level(level: LogLevel | string) {
+        level = LogLevel(level);
+
+        LogDestination.defaults.level = level;
+
+        for (const name in this.destinations) {
+            this.destinations[name].level = level;
+        }
+    }
+
+    /**
+     * Get the default facility levels.
+     */
+    static get facilityLevels() {
+        return LogDestination.defaults.facilityLevels;
+    }
+
+    /**
+     * Set log level as name or number for facilities in all destinations.
+     *
+     * Existing levels that are not named in {@link levels} will remain unchanged.
+     */
+    static set facilityLevels(levels: Record<string, LogLevel | string>) {
+        for (const name in levels) {
+            levels[name] = LogLevel(levels[name]);
+        }
+
+        Object.assign(LogDestination.defaults.facilityLevels, levels);
+
+        for (const name in this.destinations) {
+            Object.assign(this.destinations[name].facilityLevels, levels);
+        }
+    }
+
+    /**
+     * Get the default format name.
+     */
+    static get format(): string {
+        return LogDestination.defaults.format.name;
+    }
+
+    /**
+     * Set the format for all destinations.
+     */
+    static set format(format: string | LogFormat.Formatter) {
+        format = LogFormat(format);
+
+        LogDestination.defaults.format = format;
+
+        for (const name in this.destinations) {
+            this.destinations[name].format = format;
+        }
+    }
+
+    /**
+     * Mask a string with a given character. If unmaskedLength is provided then these number of characters will be
+     * shown unmasked.
+     *
+     * @param str String to mask
+     * @param maskChar character to mask with
+     * @param unmaskedLength number of characters to show unmasked in the beginning
+     */
+    static maskString(str: string, maskChar = "*", unmaskedLength?: number) {
+        return str.substring(0, unmaskedLength ?? 0) + str.substring(unmaskedLength ?? 0).replace(/./g, maskChar);
+    }
+
+    /**
+     * Perform operations in a nested logging context.  Messages will be
+     * indented while the context executes.
+     */
+    static nest<T>(context: () => T): T {
+        this.nestingLevel++;
+        try {
+            return context();
+        } finally {
+            this.nestingLevel--;
+        }
+    }
+
+    /**
+     * Async version of nest().
+     */
+    static async nestAsync(context: () => Promise<any>) {
+        this.nestingLevel++;
+        try {
+            return await context();
+        } finally {
+            this.nestingLevel--;
+        }
+    }
+
+    /**
+     * Unhandled error reporter.
+     *
+     * Some environments do not report full error details such as {@link Error#cause} and {@link AggregateError#errors}.
+     *
+     * To ensure these details are always recorded somewhere, unhandled errors may be reported here.
+     *
+     * To disable this behavior replace this function.
+     */
+    static reportUnhandledError(error: Error) {
+        try {
+            Logger.get("Logger").fatal("Unhandled error detected:", error);
+        } catch (e) {
+            // We do not want to cause yet another error so if logging fails for any reason it goes unreported
+        }
+    }
+
+    constructor(name: string) {
+        this.#name = name;
+    }
+
+    debug(...values: unknown[]) {
+        this.#log(LogLevel.DEBUG, values);
+    }
+
+    info(...values: unknown[]) {
+        this.#log(LogLevel.INFO, values);
+    }
+
+    notice(...values: unknown[]) {
+        this.#log(LogLevel.NOTICE, values);
+    }
+
+    warn(...values: unknown[]) {
+        this.#log(LogLevel.WARN, values);
+    }
+
+    error(...values: unknown[]) {
+        this.#log(LogLevel.ERROR, values);
+    }
+
+    fatal(...values: unknown[]) {
+        this.#log(LogLevel.FATAL, values);
+    }
+
+    log(level: LogLevel, ...values: unknown[]) {
+        this.#log(level, values);
+    }
+
+    #log(level: LogLevel, values: unknown[]) {
+        for (const name in Logger.destinations) {
+            const dest = Logger.destinations[name];
+
+            if (level < (dest.facilityLevels?.[this.#name] ?? dest.level)) {
+                return;
+            }
+
+            if (!dest.context) {
+                dest.context = Diagnostic.Context();
+            }
+
+            dest.context.run(() =>
+                dest.add(
+                    Diagnostic.message({
+                        now: Time.now(),
+                        facility: this.#name,
+                        level,
+                        prefix: nestingPrefix(),
+                        values,
+                    }),
+                ),
+            );
+        }
+    }
+
+    //
+    // DEPRECATED API SURFACE FOLLOWS
+    //
+
+    /**
+     * Stringify a value (BigInt aware) as JSON.
+     *
+     * @param data the value to stringify
+     * @returns the stringified value
+     *
+     * @deprecated use {@link Diagnostic.json}
+     */
+    static toJSON(data: any) {
+        return JSON.stringify(data, (_, value) => {
+            if (typeof value === "bigint") {
+                return value.toString();
+            }
+            if (value instanceof Uint8Array) {
+                return Bytes.toHex(value);
+            }
+            if (value === undefined) {
+                return "undefined";
+            }
+            return value;
+        });
+    }
+
+    /**
+     * Add additional logger to the list of loggers including the default configuration.
+     *
+     * @deprecated use {@link destinations}
+     */
     public static addLogger(
         identifier: string,
         logger: (level: LogLevel, formattedLog: string) => void,
@@ -110,87 +277,70 @@ export class Logger {
             logFormat?: string;
         },
     ) {
-        if (Logger.logger.some(logger => logger.logIdentifier === identifier)) {
-            throw new NotImplementedError(`Logger "${identifier}" already exists`);
+        if (identifier in this.destinations) {
+            throw new ImplementationError(`Logger "${identifier}" already exists`);
         }
-        Logger.logger.push({
-            logIdentifier: identifier,
-            logFormatter: logFormatterFor(options?.logFormat ?? LogFormat.PLAIN),
-            log: logger,
-            defaultLogLevel: options?.defaultLogLevel ?? LogLevel.DEBUG,
-            logLevels: options?.logLevels ?? {},
-        });
+        const dest = LogDestination({ name: identifier });
+        const legacy = adaptDestinationToLegacy(dest);
+        legacy.log = logger;
+        if (options?.defaultLogLevel !== undefined) {
+            legacy.defaultLogLevel = options.defaultLogLevel;
+        }
+        if (options?.logLevels !== undefined) {
+            legacy.logLevels = options.logLevels;
+        }
+        if (options?.logFormat !== undefined) {
+            legacy.logFormatter = logFormatterFor(options.logFormat);
+        }
+        this.destinations[identifier] = dest;
     }
 
+    /**
+     * @deprecated use {@link destinations}
+     */
     public static removeLogger(identifier: string) {
-        const index = Logger.logger.findIndex(logger => logger.logIdentifier === identifier);
-        if (index === -1) {
+        if (!(identifier in this.destinations)) {
             throw new NotImplementedError(`Logger "${identifier}" does not exist`);
         }
-        Logger.logger.splice(index, 1);
+        delete this.destinations[identifier];
     }
 
     /**
      * Check if a logger with the matching identifier exists.
      * @param identifier The identifier of the logger
+     *
+     * @deprecated use {@link destinations}
      */
     public static hasLoggerForIdentifier(identifier: string) {
-        return Logger.logger.some(logger => logger.logIdentifier === identifier);
+        return identifier in this.destinations;
     }
 
     /**
      * Get the logger with the matching identifier.
      * @param identifier The identifier of the logger
+     *
+     * @deprecated use {@link destinations}
      */
     public static getLoggerForIdentifier(identifier: string) {
-        const logger = Logger.logger.find(logger => logger.logIdentifier === identifier);
-        if (logger === undefined) {
+        const dest = this.destinations[identifier];
+        if (dest === undefined) {
             throw new NotImplementedError(`Unknown logger "${identifier}"`);
         }
-        return logger;
+        return adaptDestinationToLegacy(dest);
     }
 
     /**
-     * Set log level using configuration-style level name for the default logger.
+     * @deprecated use {@link destinations}
      */
-    static set level(level: number | string) {
-        if (level === undefined) {
-            level = LogLevel.DEBUG;
-        }
-
-        let levelNum;
-        if (typeof level === "string") {
-            if (level.match(/^\d+$/)) {
-                levelNum = Number.parseInt(level);
-            } else {
-                levelNum = (LogLevel as unknown as Record<string, number | undefined>)[level.toUpperCase()];
-                if (levelNum === undefined) {
-                    throw new ImplementationError(`Unsupported log level "${level}"`);
-                }
-            }
-        } else {
-            levelNum = level;
-        }
-
-        if (LogLevel[levelNum] === undefined) {
-            throw new ImplementationError(`Unsupported log level "${level}"`);
-        }
-
-        Logger.defaultLogLevel = levelNum;
-    }
-
-    /**
-     * Set logFormatter using configuration-style format name.
-     *
-     * @param format the name of the formatter (see Format enum)
-     */
-    static set format(format: string) {
-        Logger.setLogFormatterForLogger("default", logFormatterFor(format));
+    public static getLoggerforIdentifier(identifier: string) {
+        return this.getLoggerForIdentifier(identifier);
     }
 
     /**
      * Set facility loglevels for the default logger.
      * @param levels The levels to set
+     *
+     * @deprecated use {@link destinations}
      */
     public static set logLevels(levels: { [facility: string]: LogLevel }) {
         Logger.setLogLevelsForLogger("default", levels);
@@ -198,6 +348,8 @@ export class Logger {
 
     /**
      * Get facility loglevels for the default logger.
+     *
+     * @deprecated use {@link Logger.facilityLevels}
      */
     public static get logLevels() {
         return Logger.getLoggerForIdentifier("default").logLevels;
@@ -207,6 +359,8 @@ export class Logger {
      * Set default loglevel for the default logger.
      *
      * @param level The level to set
+     *
+     * @deprecated use {@link Logger.level}
      */
     public static set defaultLogLevel(level: LogLevel) {
         Logger.setDefaultLoglevelForLogger("default", level);
@@ -214,6 +368,8 @@ export class Logger {
 
     /**
      * Get default loglevel for the default logger.
+     *
+     * @deprecated use {@link destinations}
      */
     public static get defaultLogLevel() {
         return Logger.getLoggerForIdentifier("default").defaultLogLevel;
@@ -223,6 +379,8 @@ export class Logger {
      * Set the log function for the default logger.
      *
      * @param log The log function to set
+     *
+     * @deprecated use {@link destinations}
      */
     public static set log(log: (level: LogLevel, formattedLog: string, facility?: string) => void) {
         Logger.setLogger("default", log);
@@ -230,6 +388,8 @@ export class Logger {
 
     /**
      * Get the log function for the default logger.
+     *
+     * @deprecated use {@link destinations}
      */
     public static get log() {
         return Logger.getLoggerForIdentifier("default").log;
@@ -239,6 +399,8 @@ export class Logger {
      * Set the log formatter for the default logger.
      *
      * @param logFormatter
+     *
+     * @deprecated use {@link destinations}
      */
     public static set logFormatter(
         logFormatter: (now: Date, level: LogLevel, facility: string, nestingPrefix: string, values: any[]) => string,
@@ -248,6 +410,8 @@ export class Logger {
 
     /**
      * Get the log formatter for the default logger.
+     *
+     * @deprecated use {@link destinations}
      */
     public static get logFormatter() {
         return Logger.getLoggerForIdentifier("default").logFormatter;
@@ -258,14 +422,11 @@ export class Logger {
      *
      * @param identifier The identifier of the logger
      * @param format the name of the formatter (see Format enum)
+     *
+     * @deprecated use {@link destinations}
      */
     public static setFormatForLogger(identifier: string, format: string) {
-        const logger = Logger.logger.find(logger => logger.logIdentifier === identifier);
-        if (logger) {
-            logger.logFormatter = logFormatterFor(format);
-        } else {
-            throw new NotImplementedError(`Unknown logger "${identifier}"`);
-        }
+        this.getLoggerForIdentifier(identifier).logFormatter = logFormatterFor(format);
     }
 
     /**
@@ -273,14 +434,11 @@ export class Logger {
      *
      * @param identifier The identifier of the logger
      * @param level The level to set
+     *
+     * @deprecated use {@link destinations}
      */
     public static setDefaultLoglevelForLogger(identifier: string, level: LogLevel) {
-        const logger = Logger.logger.find(logger => logger.logIdentifier === identifier);
-        if (logger) {
-            logger.defaultLogLevel = level;
-        } else {
-            throw new NotImplementedError(`Unknown logger "${identifier}"`);
-        }
+        this.getLoggerForIdentifier(identifier).defaultLogLevel = level;
     }
 
     /**
@@ -288,14 +446,11 @@ export class Logger {
      *
      * @param identifier The identifier of the logger
      * @param levels The levels to set
+     *
+     * @deprecated use {@link destinations}
      */
     public static setLogLevelsForLogger(identifier: string, levels: { [facility: string]: LogLevel }) {
-        const logger = Logger.logger.find(logger => logger.logIdentifier === identifier);
-        if (logger) {
-            logger.logLevels = levels;
-        } else {
-            throw new NotImplementedError(`Unknown logger "${identifier}"`);
-        }
+        this.getLoggerForIdentifier(identifier).logLevels = levels;
     }
 
     /**
@@ -303,17 +458,14 @@ export class Logger {
      *
      * @param identifier The identifier of the logger
      * @param log The log function to set
+     *
+     * @deprecated use {@link destinations}
      */
     public static setLogger(
         identifier: string,
         log: (level: LogLevel, formattedLog: string, facility?: string) => void,
     ) {
-        const logger = Logger.logger.find(logger => logger.logIdentifier === identifier);
-        if (logger) {
-            logger.log = log;
-        } else {
-            throw new NotImplementedError(`Unknown logger "${identifier}"`);
-        }
+        this.getLoggerForIdentifier(identifier).log = log;
     }
 
     /**
@@ -321,168 +473,14 @@ export class Logger {
      *
      * @param identifier The identifier of the logger
      * @param logFormatter The log formatter to set
+     *
+     * @deprecated use {@link destinations}
      */
     static setLogFormatterForLogger(
         identifier: string,
         logFormatter: (now: Date, level: LogLevel, facility: string, nestingPrefix: string, values: any[]) => string,
     ) {
-        const logger = Logger.logger.find(logger => logger.logIdentifier === identifier);
-        if (logger) {
-            logger.logFormatter = logFormatter;
-        } else {
-            throw new NotImplementedError(`Unknown logger "${identifier}"`);
-        }
-    }
-
-    /**
-     * Create a new facility.
-     *
-     * @param name the name of the facility
-     * @returns a new facility
-     */
-    static get(name: string) {
-        return new Logger(name);
-    }
-
-    /**
-     * Stringify a value (BigInt aware) as JSON.
-     *
-     * @param data the value to stringify
-     * @returns the stringified value
-     */
-    static toJSON(data: any) {
-        return JSON.stringify(data, (_, value) => {
-            if (typeof value === "bigint") {
-                return value.toString();
-            }
-            if (value instanceof Uint8Array) {
-                return Bytes.toHex(value);
-            }
-            if (value === undefined) {
-                return "undefined";
-            }
-            return value;
-        });
-    }
-
-    /**
-     * Mask a string with a given character. If unmaskedLength is provided then these number of characters will be
-     * shown unmasked.
-     *
-     * @param str String to mask
-     * @param maskChar character to mask with
-     * @param unmaskedLength number of characters to show unmasked in the beginning
-     */
-    static maskString(str: string, maskChar = "*", unmaskedLength?: number) {
-        return str.substring(0, unmaskedLength ?? 0) + str.substring(unmaskedLength ?? 0).replace(/./g, maskChar);
-    }
-
-    /**
-     * Perform operations in a nested logging context.  Messages will be
-     * indented while the context executes.
-     */
-    static nest<T>(context: () => T): T {
-        this.nestingLevel++;
-        try {
-            return context();
-        } finally {
-            this.nestingLevel--;
-        }
-    }
-
-    /**
-     * Async version of nest().
-     */
-    static async nestAsync(context: () => Promise<any>) {
-        this.nestingLevel++;
-        try {
-            return await context();
-        } finally {
-            this.nestingLevel--;
-        }
-    }
-
-    /**
-     * Unhandled error reporter.
-     *
-     * Some environments do not report full error details such as {@link Error#cause} and {@link AggregateError#errors}.
-     *
-     * To ensure these details are always recorded somewhere, unhandled errors may be reported here.
-     *
-     * To disable this behavior replace this function.
-     */
-    static reportUnhandledError(error: Error) {
-        try {
-            Logger.get("Logger").fatal("Unhandled error detected:", error);
-        } catch (e) {
-            // We do not want to cause yet another error so if logging fails for any reason it goes unreported
-        }
-    }
-
-    /**
-     * Invoke logic and return any log messages produced.
-     */
-    static capture(fn: () => void, fromLogger = "default") {
-        if (!Logger) {
-            throw new Error("No logger loaded, cannot capture logs");
-        }
-        const logger = Logger.getLoggerForIdentifier(fromLogger);
-        const actualLogSettings = {
-            logFormatter: logger.logFormatter,
-            log: logger.log,
-            defaultLogLevel: logger.defaultLogLevel,
-            logLevels: { ...logger.logLevels },
-        };
-
-        try {
-            Logger.setFormatForLogger(fromLogger, LogFormat.PLAIN);
-            const captured = new Array<{ level: LogLevel; message: string }>();
-            Logger.setLogger(fromLogger, (level, message) =>
-                captured.push({
-                    level,
-                    message: message.replace(/\d{4}-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d/, "xxxx-xx-xx xx:xx:xx.xxx"),
-                }),
-            );
-            fn();
-            return captured;
-        } finally {
-            Logger.setLogFormatterForLogger(fromLogger, actualLogSettings.logFormatter);
-            Logger.setDefaultLoglevelForLogger(fromLogger, actualLogSettings.defaultLogLevel);
-            Logger.setLogLevelsForLogger(fromLogger, actualLogSettings.logLevels);
-            Logger.setLogger(fromLogger, actualLogSettings.log);
-        }
-    }
-
-    constructor(name: string) {
-        this.#name = name;
-    }
-
-    debug = (...values: any[]) => this.#log(LogLevel.DEBUG, values);
-    info = (...values: any[]) => this.#log(LogLevel.INFO, values);
-    notice = (...values: any[]) => this.#log(LogLevel.NOTICE, values);
-    warn = (...values: any[]) => this.#log(LogLevel.WARN, values);
-    error = (...values: any[]) => this.#log(LogLevel.ERROR, values);
-    fatal = (...values: any[]) => this.#log(LogLevel.FATAL, values);
-    log = (level: LogLevel, ...values: any[]) => this.#log(level, values);
-
-    #log(level: LogLevel, values: any[]) {
-        for (const logger of Logger.logger) {
-            if (level < (logger.logLevels[this.#name] ?? logger.defaultLogLevel)) {
-                return;
-            }
-
-            if (!logger.context) {
-                logger.context = Diagnostic.Context();
-            }
-
-            logger.context.run(() =>
-                logger.log(
-                    level,
-                    logger.logFormatter(Time.now(), level, this.#name, nestingPrefix(), values),
-                    this.#name,
-                ),
-            );
-        }
+        this.getLoggerForIdentifier(identifier).logFormatter = logFormatter;
     }
 }
 
@@ -494,13 +492,7 @@ function nestingPrefix() {
 }
 
 Boot.init(() => {
-    Logger.logger = new Array<LoggerDefinition>({
-        logIdentifier: "default",
-        logFormatter: LogFormat.plain,
-        log: consoleLogger,
-        defaultLogLevel: LogLevel.DEBUG,
-        logLevels: {},
-    });
+    Logger.destinations = LogDestinations();
     Logger.nestingLevel = 0;
 
     // Hook for testing frameworks
@@ -510,3 +502,76 @@ Boot.init(() => {
 });
 
 CancelablePromise.logger = Logger.get("CancelablePromise");
+
+/**
+ * Create a log formatter for a given format.
+ *
+ * @deprecated
+ */
+function logFormatterFor(formatName: string): LoggerDefinition["logFormatter"] {
+    const format = LogFormat(formatName);
+
+    return (now, level, facility, prefix, ...values) =>
+        format(Diagnostic.message({ now, level, facility, prefix, values }));
+}
+
+/**
+ * Definition of one registered Logger.
+ *
+ * @deprecated
+ */
+type LoggerDefinition = {
+    logIdentifier: string;
+    logFormatter: (now: Date, level: LogLevel, facility: string, prefix: string, values: any[]) => string;
+    log: (level: LogLevel, formattedLog: string, facility?: string) => void;
+    defaultLogLevel: LogLevel;
+    logLevels: { [facility: string]: LogLevel };
+    context?: Diagnostic.Context;
+};
+
+/**
+ * @deprecated
+ */
+function adaptDestinationToLegacy(destination: LogDestination): LoggerDefinition {
+    return {
+        get logIdentifier() {
+            return destination.name;
+        },
+
+        get logFormatter() {
+            return (now: Date, level: LogLevel, facility: string, prefix: string, values: any[]) =>
+                destination.format(Diagnostic.message({ now, level, facility, prefix, values }));
+        },
+
+        set logFormatter(logFormatter: LoggerDefinition["logFormatter"]) {
+            destination.format = (message: Diagnostic.Message) =>
+                logFormatter(message.now, message.level, message.facility, message.prefix, message.values);
+        },
+
+        get log() {
+            return (level: LogLevel, formattedLog: string, facility?: string) =>
+                destination.write(formattedLog, Diagnostic.message({ level, facility }));
+        },
+
+        set log(log: LoggerDefinition["log"]) {
+            destination.write = (text: string, message: Diagnostic.Message) =>
+                log(message.level, text, message.facility);
+        },
+
+        get defaultLogLevel() {
+            return destination.level;
+        },
+
+        set defaultLogLevel(level: LogLevel) {
+            destination.level = level;
+        },
+
+        get logLevels() {
+            return destination.facilityLevels;
+        },
+
+        set logLevels(levels: Record<string, LogLevel>) {
+            destination.facilityLevels = levels;
+        },
+    };
+}