bump version for v2.4.0.

Sometimes it is useful to capture log messages in a way that is easy for
the running program to introspect or manually handle.
*BufferLogAppender* captures the logs in a simple array.

Be careful, there is no default flush/clear mechanism that runs
automatically. Users of BufferLogAppender should take care to
render/handle log messages and periodically call `clearBuffer` on the
*BufferLogAppender* instance to avoid the buffer array growing without
limit.

README.md

@@ -54,7 +54,7 @@ written to the appender. This requires the assumption of all logs being written
 to a text-based destination, which is not always the case for us.
 
 In this library, all logs are internally stored as structured data, defined by
-the *LogMessage* interface. Notably, the *message* field can be either a string
+the *LogMessage* interface. Notably, the *msg* field can be either a string
 or an object, allowing for the addition of arbitrary fields to be added to the
 log event.
 
@@ -65,9 +65,9 @@ messages written to the console. the *ApiAppender* would be an example of an
 appender for which layout would be irrelevant.
 
 Finally, notice that all of the appenders provided by this library
-automatically persist log messages as structured data, flattening the `message`
+automatically persist log messages as structured data, flattening the `msg`
 field if it is an object. *ConsoleAppender* will write the log message as a
-JSON object, promoting fields in the `message` object to top-level fields in
+JSON object, promoting fields in the `msg` object to top-level fields in
 the output. For example:
 
 ```typescript
@@ -87,24 +87,24 @@ someBusinessLogic();
 results in the following two events logged as output to the console:
 
 ```json
-{"timestamp":"2021-09-01T00:00:00.000Z","level":"INFO","scope":"example","message":"Starting application"}
+{"timestamp":"2021-09-01T00:00:00.000Z","level":"INFO","scope":"example","msg":"Starting application"}
 {"timestamp":"2021-09-01T00:00:00.000Z","level":"DEBUG","scope":"example","msg":"Doing some business logic","method":"someBusinessLogic","foo":"bar"}
 ```
 
 Note that the field name in the structured data for string messages is
-"message". In the case of an object message, the fields are used as provided.
+"msg". In the case of an object message, the fields are used as provided.
 Fields defined on the *LogMessage* interface are reserved and should not be
-used as keys in the message object (and will be ignored if they are). So, for
+used as keys in the msg object (and will be ignored if they are). So, for
 example:
 
 ```typescript
-logger.debug({ level: 'WARN', message: 'Example of ignored fields', timestamp: 'today' });
+logger.debug({ level: 'WARN', msg: 'Example of ignored fields', timestamp: 'today' });
 
 results in the following event logged as output to the console (note the
 ignored `level` and `timestamp` fields from the object):
 
 ```json
-{"timestamp":"2021-09-01T00:00:00.000Z","level":"DEBUG","scope":"example","message":"Example of ignored fields"}
+{"timestamp":"2021-09-01T00:00:00.000Z","level":"DEBUG","scope":"example","msg":"Example of ignored fields"}
 ```
 
 This flattening behavior is implemented in the `flattenMessage` function

mise.toml

@@ -0,0 +1,3 @@
+[tools]
+node = "latest"
+deno = "none"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdbernard/logging",
-  "version": "2.0.0",
+  "version": "2.4.0",
   "description": "Simple Javascript logging service.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,7 +8,7 @@
     "/dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "bunx tsc",
     "prepare": "npm run build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },

src/api-log-appender.ts

@@ -1,32 +1,30 @@
-import { LogMessage, LogLevel, flattenMessage, FlattenedLogMessage } from './log-message';
-import { LogAppender } from './log-appender';
+import { LogMessage, LogLevel, flattenMessage, FlattenedLogMessage } from './log-message'
+import { LogAppender } from './log-appender'
 
 export class ApiLogAppender implements LogAppender {
-  public batchSize = 10;
-  public minimumTimePassedInSec = 60;
-  public maximumTimePassedInSec = 120;
-  public threshold = LogLevel.ALL;
+  public batchSize = 10
+  public minimumTimePassedInSec = 60
+  public maximumTimePassedInSec = 120
+  public threshold: LogLevel
 
-  private msgBuffer: FlattenedLogMessage[] = [];
-  private lastSent = 0;
+  private msgBuffer: FlattenedLogMessage[] = []
+  private lastSent = 0
 
   constructor(
     public readonly apiEndpoint: string,
     public authToken?: string,
     threshold?: LogLevel
   ) {
-    setTimeout(this.checkPost, 1000);
-    if (threshold) {
-      this.threshold = threshold;
-    }
+    setTimeout(this.checkPost, 1000)
+    this.threshold = threshold ?? LogLevel.ALL
   }
 
   public appendMessage(msg: LogMessage): void {
     if (this.threshold && msg.level < this.threshold) {
-      return;
+      return
     }
 
-    this.msgBuffer.push(flattenMessage(msg));
+    this.msgBuffer.push(flattenMessage(msg))
   }
 
   private doPost() {
@@ -39,29 +37,29 @@ export class ApiLogAppender implements LogAppender {
           'Content-Type': 'application/json',
           Authorization: `Bearer ${this.authToken}`
         }
-      });
+      })
 
-      this.lastSent = Date.now();
-      this.msgBuffer = [];
+      this.lastSent = Date.now()
+      this.msgBuffer = []
     }
   }
 
   private checkPost = () => {
-    const now = Date.now();
-    const min = this.lastSent + this.minimumTimePassedInSec * 1000;
-    const max = this.lastSent + this.maximumTimePassedInSec * 1000;
+    const now = Date.now()
+    const min = this.lastSent + this.minimumTimePassedInSec * 1000
+    const max = this.lastSent + this.maximumTimePassedInSec * 1000
 
     if (
       (this.msgBuffer.length >= this.batchSize && min < now) ||
       (this.msgBuffer.length > 0 && max < now)
     ) {
-      this.doPost();
+      this.doPost()
     }
     setTimeout(
       this.checkPost,
       Math.max(10000, this.minimumTimePassedInSec * 1000)
-    );
-  };
+    )
+  }
 }
 
-export default ApiLogAppender;
+export default ApiLogAppender

src/buffer-log-appender.ts

@@ -0,0 +1,21 @@
+import type { LogAppender } from './log-appender'
+import { LogLevel, type LogMessage } from './log-message'
+
+export class BufferLogAppender implements LogAppender {
+  public threshold: LogLevel
+  public buffer: LogMessage[]
+
+  constructor(buffer?: LogMessage[], threshold?: LogLevel) {
+    this.buffer = buffer ?? []
+    this.threshold = threshold ?? LogLevel.ALL
+  }
+
+  public appendMessage(msg: LogMessage): void {
+    if (this.threshold && msg.level < this.threshold) return
+    else this.buffer.push(msg)
+  }
+
+  public clearBuffer(): void {
+    this.buffer.length = 0
+  }
+}

src/console-log-appender.ts

@@ -3,8 +3,8 @@ import {
   LogLevel,
   LogMessage,
   LogMessageFormatter,
-} from "./log-message";
-import { LogAppender } from "./log-appender";
+} from './log-message'
+import { LogAppender } from './log-appender'
 
 /**
  * A log appender that writes log messages to the console. The behavior of the
@@ -18,66 +18,66 @@ import { LogAppender } from "./log-appender";
  * data for inspection in the browser's developer tools.
  */
 export class ConsoleLogAppender implements LogAppender {
-  public threshold = LogLevel.ALL;
-  public formatter: LogMessageFormatter = flattenMessage;
+  public threshold: LogLevel
+  public formatter: LogMessageFormatter
 
   constructor(threshold?: LogLevel, formatter?: LogMessageFormatter) {
-    if (threshold) {
-      this.threshold = threshold;
-    }
-    if (formatter) {
-      this.formatter = formatter;
-    }
+    this.threshold = threshold ?? LogLevel.ALL
+    this.formatter = formatter ?? flattenMessage
   }
 
   public appendMessage(msg: LogMessage): void {
     if (this.threshold && msg.level < this.threshold) {
-      return;
+      return
     }
 
-    let logMethod = console.log;
+    let logMethod = console.log
     switch (msg.level) {
       case LogLevel.ALL:
       case LogLevel.TRACE:
       case LogLevel.LOG:
-        logMethod = console.log;
-        break;
+        // console.trace generates and prints a stack trace attached to the
+        // logged message. This is not really what we want for TRACE level
+        // messages as it just makes things more verbose needlessly, so these
+        // all log to console.log
+        logMethod = console.log
+        break
       case LogLevel.DEBUG:
-        logMethod = console.debug;
-        break;
+        logMethod = console.debug
+        break
       case LogLevel.INFO:
-        logMethod = console.info;
-        break;
+        logMethod = console.info
+        break
       case LogLevel.WARN:
-        logMethod = console.warn;
-        break;
+        logMethod = console.warn
+        break
       case LogLevel.ERROR:
       case LogLevel.FATAL:
-        logMethod = console.trace;
-        break;
+        logMethod = console.error
+        break
     }
 
-    const fmtMsg = this.formatter(msg);
+    const fmtMsg = this.formatter(msg)
 
-    if (typeof fmtMsg === "string") {
-      if (msg.error || msg.stacktrace) {
-        logMethod(fmtMsg, msg.error ?? msg.stacktrace);
+    if (typeof fmtMsg === 'string') {
+      if (msg.err || msg.stacktrace) {
+        logMethod(fmtMsg, msg.err ?? msg.stacktrace)
       } else {
-        logMethod(fmtMsg);
+        logMethod(fmtMsg)
       }
     } else {
-      const { message, _error, _stacktrace, ...rest } = fmtMsg;
+      const { msg: innerMsg, _err, _stacktrace, ...rest } = fmtMsg
       const summary = `${LogLevel[msg.level]} -- ${msg.scope}: ${
-        message ?? fmtMsg.method
-      }\n`;
+        innerMsg ?? fmtMsg.method
+      }\n`
 
-      if (msg.error || msg.stacktrace) {
-        logMethod(summary, msg.error ?? msg.stacktrace, rest);
+      if (msg.err || msg.stacktrace) {
+        logMethod(summary, msg.err ?? msg.stacktrace, rest)
       } else {
-        logMethod(summary, rest);
+        logMethod(summary, rest)
       }
     }
   }
 }
 
-export default ConsoleLogAppender;
+export default ConsoleLogAppender

src/index.ts

@@ -1,6 +1,6 @@
-export * from './log-message';
-export * from './log-appender';
-export * from './log-service';
-export * from './console-log-appender';
-export * from './api-log-appender';
-export * from './logger';
+export * from './log-message'
+export * from './log-appender'
+export * from './log-service'
+export * from './console-log-appender'
+export * from './api-log-appender'
+export * from './logger'

src/log-appender.ts

@@ -1,8 +1,8 @@
-import { LogLevel, LogMessage } from './log-message';
+import { LogLevel, LogMessage } from './log-message'
 
 export interface LogAppender {
   threshold: LogLevel;
   appendMessage(message: LogMessage): void;
 }
 
-export default LogAppender;
+export default LogAppender

src/log-message.ts

@@ -16,69 +16,74 @@ export function parseLogLevel(
   defaultLevel = LogLevel.INFO,
 ): LogLevel {
   if (str in LogLevel) {
-    return LogLevel[str as keyof typeof LogLevel] as LogLevel;
+    return LogLevel[str as keyof typeof LogLevel] as LogLevel
   } else {
-    return defaultLevel;
+    return defaultLevel
   }
 }
 
 export interface LogMessage {
   scope: string;
   level: LogLevel;
-  message: string | Record<string, unknown>;
+  msg: string | Record<string, unknown>;
   stacktrace?: string;
-  error?: Error;
-  timestamp: Date;
+  err?: Error;
+  ts: Date;
 }
 
 export type FlattenedLogMessage = Record<string, unknown>;
 
 /**
- * Flatten a log message to a plain object. The *message* field can be either a
- * string or an object. In the case of an object message, the LogMessage should
- * be flattened before being emitted by an appender, promoting the object's
- * fields to the top level of the message. Fields defined on the *LogMessage*
- * interface are reserved and should not be used as keys in the message object
- * (and will be ignored if they are).
+ * Flatten a log message to a plain object in preparation for emission to an
+ * appender.
+ *
+ * In general, the *message* field can be either a string or an object. In the
+ * case of an object message, the LogMessage should be flattened before being
+ * emitted by an appender, promoting the object's fields to the top level of
+ * the message. Fields defined on the *LogMessage* interface are reserved and
+ * should not be used as keys in the message object (and will be ignored if
+ * they are).
  *
  * So, for example:
  *
  * ```typescript
  * const logger = logService.getLogger('example');
- * logger.info({ foo: 'bar', baz: 'qux', timestamp: 'today', level: LogLevel.WARN });
+ * logger.info({ foo: 'bar', baz: 'qux', ts: 'today', level: LogLevel.WARN });
  * ```
  *
- * Should result after flattening in a structured log message like:
+ * Will result in a structured log message after flattening like:
  * ```json
- * {"scope":"example","level":"INFO","foo":"bar","baz":"qux","timestamp":"2020-01-01T00:00:00.000Z"}
+ * {"scope":"example","level":"INFO","foo":"bar","baz":"qux","ts":"2020-01-01T00:00:00.000Z"}
  * ```
  */
-export function flattenMessage(msg: LogMessage): FlattenedLogMessage {
-  if (typeof msg.message === 'string') {
-    return { ...msg, level: LogLevel[msg.level] };
+export function flattenMessage(logMsg: LogMessage): FlattenedLogMessage {
+  if (typeof logMsg.msg === 'string') {
+    return { ...logMsg, level: LogLevel[logMsg.level] }
   } else {
-    const { message, ...rest } = msg;
+    const { msg, ...rest } = logMsg
     return {
-      ...omit(message, [
+      ...omit(msg, [
         'scope',
         'level',
         'stacktrace',
-        'error',
-        'timestamp',
+        'err',
+        'ts',
       ]),
       ...rest,
-      level: LogLevel[msg.level],
-    };
+      level: LogLevel[logMsg.level],
     }
   }
-export type LogMessageFormatter = (msg: LogMessage) => string | FlattenedLogMessage;
+}
+export type LogMessageFormatter = (
+  msg: LogMessage,
+) => string | FlattenedLogMessage;
 
 export function structuredLogMessageFormatter(msg: LogMessage): string {
-  return JSON.stringify(flattenMessage(msg));
+  return JSON.stringify(flattenMessage(msg))
 }
 
 export function simpleTextLogMessageFormatter(msg: LogMessage): string {
-  return `[${msg.scope}] - ${msg.level}: ${msg.message}`;
+  return `[${msg.scope}] - ${msg.level}: ${msg.msg}`
 }
 
-export default LogMessage;
+export default LogMessage

src/log-service.ts

@@ -1,7 +1,7 @@
-import { LogLevel } from './log-message';
-import { Logger } from './logger';
+import { LogLevel } from './log-message'
+import { Logger } from './logger'
 
-const ROOT_LOGGER_NAME = 'ROOT';
+const ROOT_LOGGER_NAME = 'ROOT'
 
 /**
  * Service for managing loggers. A LogService instance defines
@@ -10,19 +10,19 @@ const ROOT_LOGGER_NAME = 'ROOT';
  * module.
  */
 export class LogService {
-  private loggers: Record<string, Logger>;
+  private loggers: Record<string, Logger>
 
   public get ROOT_LOGGER() {
-    return this.loggers[ROOT_LOGGER_NAME];
+    return this.loggers[ROOT_LOGGER_NAME]
   }
 
   public constructor() {
-    this.loggers = {};
+    this.loggers = {}
     this.loggers[ROOT_LOGGER_NAME] = new Logger(
       ROOT_LOGGER_NAME,
       undefined,
       LogLevel.ALL,
-    );
+    )
   }
 
   /**
@@ -55,28 +55,28 @@ export class LogService {
    */
   public getLogger(name: string, threshold?: LogLevel): Logger {
     if (this.loggers[name]) {
-      return this.loggers[name];
+      return this.loggers[name]
     }
 
-    let parentLogger: Logger;
+    let parentLogger: Logger
 
     const parentLoggerName = Object.keys(this.loggers)
       .filter((n: string) => name.startsWith(n))
       .reduce(
         (acc: string, cur: string) => (acc.length > cur.length ? acc : cur),
         '',
-      );
+      )
 
     if (parentLoggerName) {
-      parentLogger = this.loggers[parentLoggerName];
+      parentLogger = this.loggers[parentLoggerName]
     } else {
-      parentLogger = this.ROOT_LOGGER;
+      parentLogger = this.ROOT_LOGGER
     }
 
-    this.loggers[name] = parentLogger.createChildLogger(name, threshold);
-    return this.loggers[name];
+    this.loggers[name] = parentLogger.createChildLogger(name, threshold)
+    return this.loggers[name]
   }
 }
 
-export const logService = new LogService();
-export default logService;
+export const logService = new LogService()
+export default logService

src/logger.ts

@@ -1,11 +1,11 @@
-import { LogLevel, LogMessage } from './log-message';
-import { LogAppender } from './log-appender';
+import { LogLevel, LogMessage } from './log-message'
+import { LogAppender } from './log-appender'
 
 export type DeferredMsg = () => string | Record<string, unknown>;
 export type MessageType = string | DeferredMsg | Record<string, unknown>;
 
 export function isDeferredMsg(msg: MessageType): msg is DeferredMsg {
-  return typeof msg === 'function';
+  return typeof msg === 'function'
 }
 
 /**
@@ -41,7 +41,7 @@ export function isDeferredMsg(msg: MessageType): msg is DeferredMsg {
  * For more details, see *LogService#getLogger*.
  */
 export class Logger {
-  public appenders: LogAppender[] = [];
+  public appenders: LogAppender[] = []
 
   public constructor(
     public readonly name: string,
@@ -50,95 +50,95 @@ export class Logger {
   ) {}
 
   public createChildLogger(name: string, threshold?: LogLevel): Logger {
-    return new Logger(name, this, threshold);
+    return new Logger(name, this, threshold)
   }
 
   public doLog(
     level: LogLevel,
-    message: Error | MessageType,
+    msg: Error | MessageType,
     stacktrace?: string,
   ): void {
     if (level < this.getEffectiveThreshold()) {
-      return;
+      return
     }
 
     const logMsg: LogMessage = {
       scope: this.name,
       level,
-      message: '',
+      msg: '',
       stacktrace: '',
-      timestamp: new Date(),
-    };
+      ts: new Date(),
+    }
 
-    if (message === undefined || message === null) {
-      logMsg.message = message;
-      logMsg.stacktrace = stacktrace ?? '';
-    } else if (message instanceof Error) {
-      const error = message as Error;
-      logMsg.error = error;
-      logMsg.message = `${error.name}: ${error.message}`;
-      logMsg.stacktrace = stacktrace ?? error.stack ?? '';
-    } else if (isDeferredMsg(message)) {
-      logMsg.message = message();
-      logMsg.stacktrace = stacktrace == null ? '' : stacktrace;
+    if (msg === undefined || msg === null) {
+      logMsg.msg = msg
+      logMsg.stacktrace = stacktrace ?? ''
+    } else if (msg instanceof Error) {
+      const err = msg as Error
+      logMsg.err = err
+      logMsg.msg = `${err.name}: ${err.message}`
+      logMsg.stacktrace = stacktrace ?? err.stack ?? ''
+    } else if (isDeferredMsg(msg)) {
+      logMsg.msg = msg()
+      logMsg.stacktrace = stacktrace == null ? '' : stacktrace
     } else {
       // string | object
-      logMsg.message = message;
-      logMsg.stacktrace = stacktrace == null ? '' : stacktrace;
+      logMsg.msg = msg
+      logMsg.stacktrace = stacktrace == null ? '' : stacktrace
     }
 
-    this.sendToAppenders(logMsg);
+    this.sendToAppenders(logMsg)
   }
 
-  public trace(message: Error | MessageType, stacktrace?: string): void {
-    this.doLog(LogLevel.TRACE, message, stacktrace);
+  public trace(msg: Error | MessageType, stacktrace?: string): void {
+    this.doLog(LogLevel.TRACE, msg, stacktrace)
   }
 
-  public debug(message: Error | MessageType, stacktrace?: string): void {
-    this.doLog(LogLevel.DEBUG, message, stacktrace);
+  public debug(msg: Error | MessageType, stacktrace?: string): void {
+    this.doLog(LogLevel.DEBUG, msg, stacktrace)
   }
 
-  public log(message: MessageType, stacktrace?: string): void {
-    this.doLog(LogLevel.LOG, message, stacktrace);
+  public log(msg: MessageType, stacktrace?: string): void {
+    this.doLog(LogLevel.LOG, msg, stacktrace)
   }
 
-  public info(message: MessageType, stacktrace?: string): void {
-    this.doLog(LogLevel.INFO, message, stacktrace);
+  public info(msg: MessageType, stacktrace?: string): void {
+    this.doLog(LogLevel.INFO, msg, stacktrace)
   }
 
-  public warn(message: MessageType, stacktrace?: string): void {
-    this.doLog(LogLevel.WARN, message, stacktrace);
+  public warn(msg: MessageType, stacktrace?: string): void {
+    this.doLog(LogLevel.WARN, msg, stacktrace)
   }
 
-  public error(message: Error | MessageType, stacktrace?: string): void {
-    this.doLog(LogLevel.ERROR, message, stacktrace);
+  public error(msg: Error | MessageType, stacktrace?: string): void {
+    this.doLog(LogLevel.ERROR, msg, stacktrace)
   }
 
-  public fatal(message: Error | MessageType, stacktrace?: string): void {
-    this.doLog(LogLevel.FATAL, message, stacktrace);
+  public fatal(msg: Error | MessageType, stacktrace?: string): void {
+    this.doLog(LogLevel.FATAL, msg, stacktrace)
   }
 
   protected sendToAppenders(logMsg: LogMessage) {
     this.appenders.forEach((app) => {
-      app.appendMessage(logMsg);
-    });
+      app.appendMessage(logMsg)
+    })
 
     if (this.parentLogger) {
-      this.parentLogger.sendToAppenders(logMsg);
+      this.parentLogger.sendToAppenders(logMsg)
     }
   }
 
   protected getEffectiveThreshold(): LogLevel {
     if (this.threshold) {
-      return this.threshold;
+      return this.threshold
     }
     if (this.parentLogger) {
-      return this.parentLogger.getEffectiveThreshold();
+      return this.parentLogger.getEffectiveThreshold()
     }
 
     // should never happen (root logger should always have a threshold
-    return LogLevel.ALL;
+    return LogLevel.ALL
   }
 }
 
-export default Logger;
+export default Logger

src/util.ts

@@ -2,11 +2,11 @@ export function omit(
   obj: Record<string, unknown>,
   keys: string[],
 ): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
+  const result: Record<string, unknown> = {}
   for (const key in obj) {
     if (!keys.includes(key)) {
-      result[key] = obj[key];
+      result[key] = obj[key]
     }
   }
-  return result;
+  return result
 }