Merge pull request 'docs: Add Development, CI, and Maintenance sections to README' (#8) from update-readme-dev-guide into main

The  action is a GitHub Marketplace action
that doesn't exist on self-hosted Gitea instances. Replace it with
the standard curl-based Bun installation method and add ~/.bun/bin
to GITHUB_PATH.

.gitea/workflows/validate.yml

@@ -0,0 +1,20 @@
+name: Validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: bun
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run tests
+        run: bun test

.gitignore

@@ -1,3 +1,5 @@
 node_modules/
 dist/
 *.sw?
+.lvimrc
+jdbernard-logging-*.tgz

README.md

@@ -0,0 +1,220 @@
+# Overview
+
+`@jdbernard/logging` implements a simple but powerful logging system for
+JavaScript applications based on the idea of heirarchical loggers. It heavily
+inspired by the usage patterns of [log4j][], [logback][], and similar tools in other
+ecosystems.
+
+## Getting Started
+
+Install the package from npm:
+```bash
+npm install @jdbernard/logging
+```
+
+Then, in your application, you can use the logging system like so:
+
+```typescript
+import { logService, ConsoleAppender, LogLevel } from '@jdbernard/logging';
+
+logService.ROOT_LOGGER.appenders.push(new ConsoleAppender(LogLevel.INFO));
+const logger = logService.getLogger('example');
+
+logger.info('Starting application');
+```
+
+## Loggers and Appenders
+
+The logging system is composed of two main components: loggers and appenders.
+Loggers are used to create log events, which are then passed to the appenders
+associated with the logger and it's parent. An appender is a function that
+takes a log event and writes it to some destination, such as the console, a
+file, or a network socket. Appenders also have a logging level threshold, which
+determines which log events are acted upon by the appender.
+
+Loggers are hierarchical, with the hierarchy defined by the logger name. When a
+log message is generated on a *Logger*, it is sent to any appenders associated
+with that logger, and then triggered on the parent logger, being sent to any of
+the parent logger's appenders, and so on up the hierarchy. Similarly, when a
+logging event is generated, it is filtered by the effective logging level of
+the logger. If there is no threshold set on the logger, the effective logging
+level is inherited from the parent logger. This pattern is explained in detail
+in the [logback documentation][effective logging level] and applies in the same
+manner to this library.
+
+Together, the cascading effective logging threshold and the upward propogation
+of log events to parent appenders allows for simple yet fine-grained control
+over the logging output of an application.
+
+## Layouts
+
+One difference from other logging libraries is the absense of layouts. Layouts
+are used in many logging libraries to format the log message before it is
+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 *msg* field can be either a string
+or an object, allowing for the addition of arbitrary fields to be added to the
+log event.
+
+The concept of Layouts still has a place, but it has been moved to be an
+implementation detail of the appenders. *ConsoleAppender* accepts a
+*LogMessageFormatter* function allowing for formatting of the resulting
+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 `msg`
+field if it is an object. *ConsoleAppender* will write the log message as a
+JSON object, promoting fields in the `msg` object to top-level fields in
+the output. For example:
+
+```typescript
+import { logService, ConsoleAppender } from '@jdbernard/logging';
+
+logService.ROOT_LOGGER.appenders.push(new ConsoleAppender('TRACE'));
+const logger = logService.getLogger('example');
+
+function someBusinessLogic() {
+  logger.debug({ method: 'someBusinessLogic', msg: 'Doing some business logic', foo: 'bar' });
+}
+
+logger.info('Starting application');
+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","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
+"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 msg object (and will be ignored if they are). So, for
+example:
+
+```typescript
+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","msg":"Example of ignored fields"}
+```
+
+This flattening behavior is implemented in the `flattenMessage` function
+exported from the `@jdbernard/logging/log-message.ts` module and is available
+for use in custom appender implemetations.
+
+As a final note, the *ConsoleAppender* has some special behavior for the ERROR
+level and *stacktrace* field when running in a web browser to take advantage of
+the console's built-in. See the documentation for the *ConsoleAppender* for
+more information.
+
+## Worked Example
+
+To illustrate the usage of the logging system and the purpose of the
+fine-grained control described above, consider the following TypeScript
+example:
+
+```typescript
+// main.ts -- Entry point of the application
+// A console appender is attached to the root logger to log all events at or
+// above the INFO level.
+logService.ROOT_LOGGER.appenders.push(new ConsoleAppender(LogLevel.INFO));
+
+// An API appender is attached to the root logger to forward all ERROR events
+// to a server-side error log collector.
+logServive.ROOT_LOGGER.appenders.push(new ApiAppender(
+  'https://api.example.com/error-logs',
+  appStore.user.sessionToken,
+  LogLevel.ERROR));
+
+const appLog = logService.getLogger('app');
+appLog.info('Starting application');
+
+// api.ts -- API implementaiton
+const apiLog = logService.getLogger('app/api');
+
+// http-client.ts -- HTTP client implementation
+const httpLog = logService.getLogger('app/api/http-client');
+```
+
+Because different parts of the application use namespaced loggers, we can
+dynamically adjust the logging level of different parts of the application
+without changing the code. For example, to increase the logging level of the
+HTTP client to DEBUG, we can add the following line to the `main.ts` file:
+
+```typescript
+logService.getLogger('app/api/http-client').setLevel(LogLevel.DEBUG);
+```
+
+Additionally, if, for some reason, we only wanted to forward the ERROR events
+from the API namespace to the server-side error log collector, we could attach
+the *ApiAppender* to the `app/api` logger instead of the root logger. This
+would allow us to log all events from both the API and HTTP client loggers to
+the API log collector, but ignore the rest of the application regardless of the
+logging level.
+
+## Development
+
+Set up the project locally:
+
+```bash
+bun install
+```
+
+Build the TypeScript sources:
+
+```bash
+bunx tsc
+```
+
+Run the test suite:
+
+```bash
+bun test
+```
+
+Run tests with coverage:
+
+```bash
+bun test --coverage
+```
+
+Before opening a pull request, make sure the project builds and all tests pass:
+
+```bash
+bunx tsc && bun test
+```
+
+## CI
+
+The repository uses Gitea Actions for continuous integration. The `Validate` workflow runs on every push and pull request to `main` and performs the following steps:
+
+1. Checks out the repository.
+2. Installs dependencies with `bun install`.
+3. Runs the test suite with `bun test`.
+
+## Release / Maintenance
+
+Releases are created from the `main` branch. The high-level maintainer workflow is:
+
+1. Update `version` in `package.json` following semantic versioning.
+2. Ensure the build succeeds and all tests pass locally (`bunx tsc && bun test`).
+3. Commit the version bump.
+4. Create an annotated Git tag in the `x.y.z` format (for example, `2.4.1`).
+5. Push the commit and the tag to the remote repository.
+6. Verify that CI passes on the tag.
+7. Publish the package to npm (e.g. `npm publish`).
+
+Tags must use the `x.y.z` format (three numeric components, no leading `v`). This convention is used consistently for releases in this project.
+
+[log4j]: https://logging.apache.org/log4j/2.x/
+[logback]: https://logback.qos.ch/
+[effective logging level]: https://logback.qos.ch/manual/architecture.html#effectiveLevel

eslint.config.mjs

@@ -0,0 +1,68 @@
+import importPlugin from 'eslint-plugin-import'
+import tsParser from '@typescript-eslint/parser'
+import eslintJs from '@eslint/js'
+import eslintTs from 'typescript-eslint'
+
+const tsFiles = ['src/**/*.ts']
+
+const customTypescriptConfig = {
+  files: tsFiles,
+  plugins: {
+    import: importPlugin,
+    'import/parsers': tsParser,
+  },
+  languageOptions: {
+    parser: tsParser,
+    parserOptions: {
+      project: './tsconfig.json',
+    },
+  },
+  settings: {
+    'import/parsers': {
+      '@typescript-eslint/parser': ['.ts'],
+    },
+  },
+  rules: {
+    'linebreak-style': ['error', 'unix'],
+    quotes: ['error', 'single', { avoidEscape: true }],
+    semi: ['error', 'never'],
+    '@typescript-eslint/no-unused-vars': ['error', {
+      'args': 'all',
+      'argsIgnorePattern': '^_',
+      'caughtErrorsIgnorePattern': '^_',
+      'destructuredArrayIgnorePattern': '^_',
+      'varsIgnorePattern': '^_',
+    }],
+  },
+}
+
+const recommendedTypeScriptConfigs = [
+  ...eslintTs.configs.recommended.map((config) => ({
+    ...config,
+    files: tsFiles,
+  })),
+  ...eslintTs.configs.stylistic.map((config) => ({
+    ...config,
+    files: tsFiles,
+  })),
+]
+
+export default [
+  {
+    ignores: [
+      'docs/*',
+      'build/*',
+      'lib/*',
+      'dist/*',
+    ],
+  }, // global ignores
+  eslintJs.configs.recommended,
+  ...recommendedTypeScriptConfigs,
+  customTypescriptConfig,
+  {
+    rules: {
+      quotes: ['error', 'single', { avoidEscape: true }],
+      semi: ['error', 'never'],
+    },
+  },
+]

mise.toml

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

package-lock.json

@@ -1,29 +0,0 @@
-{
-  "name": "@jdbernard/logging",
-  "version": "1.1.5",
-  "lockfileVersion": 3,
-  "requires": true,
-  "packages": {
-    "": {
-      "name": "@jdbernard/logging",
-      "version": "1.1.4",
-      "license": "GPL-3.0",
-      "devDependencies": {
-        "typescript": "^5.0.4"
-      }
-    },
-    "node_modules/typescript": {
-      "version": "5.0.4",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.0.4.tgz",
-      "integrity": "sha512-cW9T5W9xY37cc+jfEnaUvX91foxtHkza3Nw3wkoF4sSlKn0MONdkdEndig/qPBWXNkmplh3NzayQzCiHM4/hqw==",
-      "dev": true,
-      "bin": {
-        "tsc": "bin/tsc",
-        "tsserver": "bin/tsserver"
-      },
-      "engines": {
-        "node": ">=12.20"
-      }
-    }
-  }
-}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdbernard/logging",
-  "version": "1.1.5",
+  "version": "2.3.3",
   "description": "Simple Javascript logging service.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,9 +8,10 @@
     "/dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "bunx tsc",
     "prepare": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "bun test",
+    "test:coverage": "bun test --coverage"
   },
   "repository": {
     "type": "git",
@@ -23,6 +24,9 @@
   "author": "Jonathan Bernard",
   "license": "GPL-3.0",
   "devDependencies": {
-    "typescript": "^5.0.4"
+    "@typescript-eslint/parser": "^8.19.0",
+    "eslint-plugin-import": "^2.31.0",
+    "typescript": "^5.0.4",
+    "typescript-eslint": "^8.19.0"
   }
 }

src/api-log-appender.ts

@@ -1,48 +1,30 @@
-import { LogMessage, LogLevel } from './log-message';
-import LogAppender from './log-appender';
+import { LogMessage, LogLevel, flattenMessage, FlattenedLogMessage } from './log-message'
+import { LogAppender } from './log-appender'
 
-interface ApiMessage {
-  level: string;
-  message: string;
-  scope: string;
-  stacktrace: string;
-  timestamp: string;
-}
 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: ApiMessage[] = [];
-  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({
-      level: LogLevel[msg.level],
-      message:
-        typeof msg.message === 'string'
-          ? msg.message
-          : JSON.stringify(msg.message),
-      scope: msg.scope,
-      stacktrace: msg.stacktrace,
-      timestamp: msg.timestamp.toISOString()
-    });
+    this.msgBuffer.push(flattenMessage(msg))
   }
 
   private doPost() {
@@ -55,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

@@ -1,55 +1,83 @@
-/*tslint:disable:no-console*/
-import { LogMessage, LogLevel } from './log-message';
-import LogAppender from './log-appender';
+import {
+  flattenMessage,
+  LogLevel,
+  LogMessage,
+  LogMessageFormatter,
+} from './log-message'
+import { LogAppender } from './log-appender'
 
+/**
+ * A log appender that writes log messages to the console. The behavior of the
+ * log appender can be configured with a threshold level and a message
+ * formatter.
+ *
+ * When the message formatter returns a string value, that value is logged to
+ * the console as-is. When the message formatter returns an object, a summary
+ * string is logged to the console, followed by the object itself. This allows
+ * logs to be easily read in the console, while still providing the structured
+ * data for inspection in the browser's developer tools.
+ */
 export class ConsoleLogAppender implements LogAppender {
-  public threshold = LogLevel.ALL;
+  public threshold: LogLevel
+  public formatter: LogMessageFormatter
 
-  constructor(threshold?: LogLevel) {
-    if (threshold) {
-      this.threshold = threshold;
-    }
+  constructor(threshold?: LogLevel, formatter?: LogMessageFormatter) {
+    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:
-        logMethod = console.log;
-        break;
       case LogLevel.TRACE:
-        logMethod = console.log;
-        break;
-      case LogLevel.DEBUG:
-        logMethod = console.debug;
-        break;
       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
       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
     }
 
-    if (msg.error) {
-      logMethod(`[${msg.scope}]:`, msg.message, msg.error);
-    } else if (msg.stacktrace) {
-      logMethod(`[${msg.scope}]:`, msg.message, msg.stacktrace);
+    const fmtMsg = this.formatter(msg)
+
+    if (typeof fmtMsg === 'string') {
+      if (msg.err || msg.stacktrace) {
+        logMethod(fmtMsg, msg.err ?? msg.stacktrace)
       } else {
-      logMethod(`[${msg.scope}]:`, msg.message);
+        logMethod(fmtMsg)
+      }
+    } else {
+      const { msg: innerMsg, _err, _stacktrace, ...rest } = fmtMsg
+      const summary = `${LogLevel[msg.level]} -- ${msg.scope}: ${
+        innerMsg ?? fmtMsg.method
+      }\n`
+
+      if (msg.err || msg.stacktrace) {
+        logMethod(summary, msg.err ?? msg.stacktrace, rest)
+      } else {
+        logMethod(summary, rest)
+      }
     }
   }
 }
 
-export default ConsoleLogAppender;
+export default ConsoleLogAppender

src/index.ts

@@ -1,6 +1,7 @@
-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 './buffer-log-appender'
+export * from './logger'

src/log-appender.ts

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

src/log-message.ts

@@ -1,3 +1,5 @@
+import { omit } from './util'
+
 export enum LogLevel {
   ALL = 0,
   TRACE,
@@ -6,24 +8,82 @@ export enum LogLevel {
   INFO,
   WARN,
   ERROR,
-  FATAL
+  FATAL,
 }
 
-export function parseLogLevel(str: string, defaultLevel = LogLevel.INFO): LogLevel {
-  if (Object.prototype.hasOwnProperty.call(LogLevel, str)) {
-    return LogLevel[<any>str] as unknown as LogLevel;
+export function parseLogLevel(
+  str: string,
+  defaultLevel = LogLevel.INFO,
+): LogLevel {
+  if (str in LogLevel) {
+    return LogLevel[str as keyof typeof LogLevel] as LogLevel
   } else {
-    return defaultLevel;
+    return defaultLevel
   }
 }
 
 export interface LogMessage {
   scope: string;
   level: LogLevel;
-  message: string | object;
-  stacktrace: string;
-  error?: Error;
-  timestamp: Date;
+  msg: string | Record<string, unknown>;
+  stacktrace?: string;
+  err?: Error;
+  ts: Date;
 }
 
-export default LogMessage;
+export type FlattenedLogMessage = Record<string, unknown>;
+
+/**
+ * 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', ts: 'today', level: LogLevel.WARN });
+ * ```
+ *
+ * Will result in a structured log message after flattening like:
+ * ```json
+ * {"scope":"example","level":"INFO","foo":"bar","baz":"qux","ts":"2020-01-01T00:00:00.000Z"}
+ * ```
+ */
+export function flattenMessage(logMsg: LogMessage): FlattenedLogMessage {
+  if (typeof logMsg.msg === 'string') {
+    return { ...logMsg, level: LogLevel[logMsg.level] }
+  } else {
+    const { msg, ...rest } = logMsg
+    return {
+      ...omit(msg, [
+        'scope',
+        'level',
+        'stacktrace',
+        'err',
+        'ts',
+      ]),
+      ...rest,
+      level: LogLevel[logMsg.level],
+    }
+  }
+}
+export type LogMessageFormatter = (
+  msg: LogMessage,
+) => string | FlattenedLogMessage;
+
+export function structuredLogMessageFormatter(msg: LogMessage): string {
+  return JSON.stringify(flattenMessage(msg))
+}
+
+export function simpleTextLogMessageFormatter(msg: LogMessage): string {
+  return `[${msg.scope}] - ${msg.level}: ${msg.msg}`
+}
+
+export default LogMessage

src/log-service.ts

@@ -1,48 +1,82 @@
-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
+ * the service context for a set of loggers. Typically there is only one
+ * LogService instance per application, the one exported as default from this
+ * module.
+ */
 export class LogService {
-  private loggers: { [key: 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
-    );
+      LogLevel.ALL,
+    )
   }
 
+  /**
+   * Get a logger by name. If the logger does not exist, it will be created.
+   * Loggers are hierarchical, with the heirarchy defined by the logger name.
+   * When creating a new logger, the parent logger is determined by the longest
+   * existing logger name that is a prefix of the new logger name. For example,
+   * if a logger with the name "foo" already exists, any subsequent loggers
+   * with the names "foo.bar", "foo/bar", "foolish.choice", etc. will be
+   * created as children of the "foo" logger.
+   *
+   * As another example, given the following invocations:
+   *
+   * ```typescript
+   * logService.getLogger('foo');
+   * logService.getLogger('foo.bar');
+   * logService.getLogger('foo.bar.baz');
+   * logService.getLogger('foo.qux');
+   * ```
+   *
+   * will result in the following logging hierarchy:
+   *
+   *     foo
+   *     ├─foo.bar
+   *     │ └─foo.bar.baz
+   *     └─foo.qux
+   *
+   * See the Logger class for details on how loggers are used and the
+   * implications of the logger hierarchy.
+   */
   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,108 +1,144 @@
-import { LogMessage, LogLevel } from './log-message';
-import LogAppender from './log-appender';
+import { LogLevel, LogMessage } from './log-message'
+import { LogAppender } from './log-appender'
 
-export type DeferredMsg = () => string | object;
-export type MessageType = string | DeferredMsg | object;
+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'
+}
+
+/**
+ * Logger class for logging messages.
+ *
+ * Loggers are used to log messages at different levels. The levels are, in
+ * order of increasing severity: TRACE, DEBUG, LOG, INFO, WARN, ERROR, FATAL.
+ * Log messages can be logged at a specific level by calling the corresponding
+ * method on the logger instance. For example, to log a message at the INFO
+ * level, call the *info* method on the logger.
+ *
+ * Loggers have a threshold level, which is the minimum level of log message
+ * that will be logged by the logger. Log messages with a level below the
+ * threshold will be ignored. The threshold level can be set when creating a
+ * logger, or by calling the *setThreshold* method on an existing logger. If a
+ * threshold is not set, the logger will use the threshold of its parent
+ * logger.
+ *
+ * Loggers are hierarchical, with the hierarchy defined by the logger name.
+ * The heirarchy is tracked by the children: child loggers have a link to their
+ * parents, while parent loggers do not have a list of their children.
+ *
+ * When a log message is logged by a logger, it is sent to all of the appenders
+ * attached to the logger and to the parent logger. Appenders can be attached
+ * to any Logger instance, but, because of this upwards propogation, appenders
+ * are usually attached to the root logger, which is an ancestor of all loggers
+ * created by the same LogService instance.
+ *
+ * Loggers are typically created and managed by a LogService instance.  The
+ * *LogService#getLogger* method is used to get a logger by name, creating it
+ * if necessary. When creating a new logger, the parent logger is determined by
+ * the longest existing logger name that is a prefix of the new logger name.
+ * For more details, see *LogService#getLogger*.
+ */
 export class Logger {
-  public appenders: LogAppender[] = [];
+  public appenders: LogAppender[] = []
 
   public constructor(
     public readonly name: string,
     private parentLogger?: Logger,
-    public threshold?: LogLevel
+    public threshold?: LogLevel,
   ) {}
 
   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,
-    stacktrace?: string
+    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 == null ? '' : stacktrace;
-    } else if ((message as DeferredMsg).call !== undefined) {
-      logMsg.message = (message as DeferredMsg)();
-      logMsg.stacktrace = stacktrace == null ? '' : stacktrace;
-    } else if (message instanceof Error) {
-      const error = message as Error;
-      logMsg.error = error;
-      logMsg.message = `${error.name}: ${error.message}`;
-      logMsg.stacktrace = error.stack == null ? '' : error.stack;
+    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);
-    });
+    this.appenders.forEach((app) => {
+      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

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

test/api-log-appender.test.ts

@@ -0,0 +1,71 @@
+import { describe, test, expect } from "bun:test";
+import { ApiLogAppender, LogLevel, LogMessage, FlattenedLogMessage } from "../src";
+
+function makeMsg(overrides: Partial<LogMessage> = {}): LogMessage {
+  return {
+    scope: "test-scope",
+    level: LogLevel.INFO,
+    msg: "test message",
+    stacktrace: "",
+    ts: new Date(),
+    ...overrides,
+  };
+}
+
+describe("ApiLogAppender", () => {
+  test("defaults threshold to ALL", () => {
+    const appender = new ApiLogAppender("https://example.com/logs");
+    expect(appender.threshold).toBe(LogLevel.ALL);
+  });
+
+  test("respects explicit threshold", () => {
+    const appender = new ApiLogAppender("https://example.com/logs", undefined, LogLevel.WARN);
+    expect(appender.threshold).toBe(LogLevel.WARN);
+  });
+
+  test("stores authToken when provided", () => {
+    const appender = new ApiLogAppender("https://example.com/logs", "token-abc");
+    expect(appender.authToken).toBe("token-abc");
+  });
+
+  test("has sensible default batch and timing settings", () => {
+    const appender = new ApiLogAppender("https://example.com/logs");
+
+    expect(appender.batchSize).toBe(10);
+    expect(appender.minimumTimePassedInSec).toBe(60);
+    expect(appender.maximumTimePassedInSec).toBe(120);
+  });
+
+  test("threshold of ALL (0) does not cause falsy check to drop messages", () => {
+    const appender = new ApiLogAppender("https://example.com/logs", undefined, LogLevel.ALL);
+
+    // appendMessage pushes to the internal msgBuffer — we can't easily
+    // inspect it, but we can verify it doesn't throw and that the threshold
+    // check with ALL (0) doesn't drop messages due to falsy comparison.
+    appender.appendMessage(makeMsg({ level: LogLevel.ALL }));
+    appender.appendMessage(makeMsg({ level: LogLevel.INFO }));
+
+    // No assertions on internal buffer (private), but verify no errors thrown.
+    // If the falsy bug existed, these messages would be silently dropped.
+    expect(true).toBe(true);
+  });
+
+  test("respects threshold when set above ALL", () => {
+    const appender = new ApiLogAppender("https://example.com/logs", undefined, LogLevel.WARN);
+
+    // These should not throw, just silently drop
+    appender.appendMessage(makeMsg({ level: LogLevel.ALL }));
+    appender.appendMessage(makeMsg({ level: LogLevel.INFO }));
+
+    // WARN and above would be queued (but we can't easily inspect)
+    appender.appendMessage(makeMsg({ level: LogLevel.WARN }));
+    appender.appendMessage(makeMsg({ level: LogLevel.ERROR }));
+
+    expect(true).toBe(true);
+  });
+
+  test("stores apiEndpoint", () => {
+    const appender = new ApiLogAppender("https://logs.example.com/v1/ingest");
+    expect(appender.apiEndpoint).toBe("https://logs.example.com/v1/ingest");
+  });
+});

test/buffer-log-appender.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "bun:test";
+import { BufferLogAppender, LogLevel, LogMessage } from "../src";
+
+function makeMsg(overrides: Partial<LogMessage> = {}): LogMessage {
+  return {
+    scope: "test-scope",
+    level: LogLevel.INFO,
+    msg: "test message",
+    stacktrace: "",
+    ts: new Date(),
+    ...overrides,
+  };
+}
+
+describe("BufferLogAppender", () => {
+  test("defaults to empty buffer and ALL threshold", () => {
+    const appender = new BufferLogAppender();
+
+    expect(appender.buffer).toEqual([]);
+    expect(appender.threshold).toBe(LogLevel.ALL);
+  });
+
+  test("accepts initial buffer", () => {
+    const existing: LogMessage[] = [makeMsg({ msg: "pre-existing" })];
+    const appender = new BufferLogAppender(existing);
+
+    expect(appender.buffer.length).toBe(1);
+    expect(appender.buffer[0].msg).toBe("pre-existing");
+  });
+
+  test("appends messages to buffer", () => {
+    const appender = new BufferLogAppender();
+
+    appender.appendMessage(makeMsg({ msg: "first" }));
+    appender.appendMessage(makeMsg({ msg: "second" }));
+
+    expect(appender.buffer.length).toBe(2);
+    expect(appender.buffer[0].msg).toBe("first");
+    expect(appender.buffer[1].msg).toBe("second");
+  });
+
+  test("respects threshold", () => {
+    const appender = new BufferLogAppender(undefined, LogLevel.WARN);
+
+    appender.appendMessage(makeMsg({ level: LogLevel.INFO, msg: "dropped" }));
+    appender.appendMessage(makeMsg({ level: LogLevel.WARN, msg: "kept" }));
+    appender.appendMessage(makeMsg({ level: LogLevel.ERROR, msg: "also kept" }));
+
+    expect(appender.buffer.length).toBe(2);
+    expect(appender.buffer[0].msg).toBe("kept");
+    expect(appender.buffer[1].msg).toBe("also kept");
+  });
+
+  test("threshold of ALL (0) does not cause falsy check to drop messages", () => {
+    const appender = new BufferLogAppender(undefined, LogLevel.ALL);
+
+    appender.appendMessage(makeMsg({ level: LogLevel.ALL, msg: "level all" }));
+    appender.appendMessage(makeMsg({ level: LogLevel.INFO, msg: "level info" }));
+
+    // Both should be kept — ALL (0) should not be treated as falsy
+    expect(appender.buffer.length).toBe(2);
+    expect(appender.buffer[0].msg).toBe("level all");
+    expect(appender.buffer[1].msg).toBe("level info");
+  });
+
+  test("clearBuffer empties the buffer", () => {
+    const appender = new BufferLogAppender();
+    appender.appendMessage(makeMsg({ msg: "to clear" }));
+    expect(appender.buffer.length).toBe(1);
+
+    appender.clearBuffer();
+    expect(appender.buffer.length).toBe(0);
+  });
+});

test/console-log-appender.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, expect } from "bun:test";
+import { ConsoleLogAppender, LogLevel, LogMessage } from "../src";
+
+function makeMsg(overrides: Partial<LogMessage> = {}): LogMessage {
+  return {
+    scope: "test-scope",
+    level: LogLevel.INFO,
+    msg: "test message",
+    stacktrace: "",
+    ts: new Date(),
+    ...overrides,
+  };
+}
+
+describe("ConsoleLogAppender", () => {
+  test("defaults threshold to ALL and formatter to flattenMessage", () => {
+    const appender = new ConsoleLogAppender();
+
+    expect(appender.threshold).toBe(LogLevel.ALL);
+    expect(appender.formatter).toBeDefined();
+  });
+
+  test("accepts custom threshold and formatter", () => {
+    const fmt = () => "custom";
+    const appender = new ConsoleLogAppender(LogLevel.ERROR, fmt);
+
+    expect(appender.threshold).toBe(LogLevel.ERROR);
+    expect(appender.formatter).toBe(fmt);
+  });
+
+  test("threshold of ALL (0) does not cause falsy guard to block messages", () => {
+    // ALL (0) is falsy in JS. The guard `if (this.threshold && msg.level < this.threshold)`
+    // evaluates `0 && ...` = 0 (falsy), so the if-block is NOT entered and
+    // messages proceed. This is correct behavior by accident — ALL means log everything.
+    const appender = new ConsoleLogAppender(LogLevel.ALL);
+
+    // Calling appendMessage should not throw for any level when threshold is ALL.
+    // We can't easily spy on console in Bun, but we can verify no errors are thrown.
+    for (const level of [
+      LogLevel.ALL,
+      LogLevel.TRACE,
+      LogLevel.DEBUG,
+      LogLevel.INFO,
+      LogLevel.WARN,
+      LogLevel.ERROR,
+      LogLevel.FATAL,
+    ]) {
+      expect(() => appender.appendMessage(makeMsg({ level }))).not.toThrow();
+    }
+  });
+
+  test("respects threshold by dropping messages below it", () => {
+    // We verify threshold works by checking the formatter is called (or not).
+    // When threshold is WARN, messages with INFO should not invoke the formatter.
+    let formatterCalls = 0;
+    const appender = new ConsoleLogAppender(LogLevel.WARN, () => {
+      formatterCalls++;
+      return "logs";
+    });
+
+    // This should be dropped before formatter is called
+    appender.appendMessage(makeMsg({ level: LogLevel.INFO }));
+    expect(formatterCalls).toBe(0);
+
+    // This should pass through
+    appender.appendMessage(makeMsg({ level: LogLevel.WARN }));
+    expect(formatterCalls).toBe(1);
+
+    // And higher levels too
+    appender.appendMessage(makeMsg({ level: LogLevel.ERROR }));
+    expect(formatterCalls).toBe(2);
+  });
+
+  test("does not throw for any valid log level", () => {
+    const appender = new ConsoleLogAppender();
+
+    for (const level of [
+      LogLevel.ALL,
+      LogLevel.TRACE,
+      LogLevel.DEBUG,
+      LogLevel.LOG,
+      LogLevel.INFO,
+      LogLevel.WARN,
+      LogLevel.ERROR,
+      LogLevel.FATAL,
+    ]) {
+      expect(() => appender.appendMessage(makeMsg({ level }))).not.toThrow();
+    }
+  });
+
+  test("handles string message with error/stacktrace", () => {
+    const appender = new ConsoleLogAppender();
+    const err = new Error("test error");
+
+    // Should not throw
+    expect(() =>
+      appender.appendMessage(makeMsg({ err, stacktrace: "trace" }))
+    ).not.toThrow();
+  });
+
+  test("handles object message formatter output", () => {
+    // The formatter can return an object (flattenMessage does),
+    // appendMessage should construct a summary and log it.
+    const appender = new ConsoleLogAppender(LogLevel.ALL, (msg) => ({
+      msg: "inner",
+      extra: 42,
+      level: LogLevel[msg.level],
+      scope: msg.scope,
+      stacktrace: "",
+      ts: msg.ts,
+    }));
+
+    expect(() => appender.appendMessage(makeMsg())).not.toThrow();
+  });
+});

test/log-message.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect } from "bun:test";
+import { parseLogLevel, LogLevel, flattenMessage, LogMessage } from "../src";
+
+describe("parseLogLevel", () => {
+  test("parses known level strings case-sensitively", () => {
+    expect(parseLogLevel("ALL")).toBe(LogLevel.ALL);
+    expect(parseLogLevel("TRACE")).toBe(LogLevel.TRACE);
+    expect(parseLogLevel("DEBUG")).toBe(LogLevel.DEBUG);
+    expect(parseLogLevel("INFO")).toBe(LogLevel.INFO);
+    expect(parseLogLevel("WARN")).toBe(LogLevel.WARN);
+    expect(parseLogLevel("ERROR")).toBe(LogLevel.ERROR);
+    expect(parseLogLevel("FATAL")).toBe(LogLevel.FATAL);
+  });
+
+  test("returns default level for unknown strings", () => {
+    expect(parseLogLevel("BOGUS")).toBe(LogLevel.INFO);
+    expect(parseLogLevel("")).toBe(LogLevel.INFO);
+  });
+
+  test("accepts custom default level", () => {
+    expect(parseLogLevel("BOGUS", LogLevel.WARN)).toBe(LogLevel.WARN);
+  });
+});
+
+describe("flattenMessage", () => {
+  test("string message includes all fields", () => {
+    const msg: LogMessage = {
+      scope: "my-scope",
+      level: LogLevel.WARN,
+      msg: "a warning",
+      ts: new Date("2024-01-01T00:00:00Z"),
+      stacktrace: "",
+    };
+
+    const flat = flattenMessage(msg);
+
+    expect(flat.scope).toBe("my-scope");
+    expect(flat.level).toBe("WARN");
+    expect(flat.msg).toBe("a warning");
+  });
+
+  test("object message promotes fields, drops reserved keys", () => {
+    const msg: LogMessage = {
+      scope: "my-scope",
+      level: LogLevel.INFO,
+      msg: { foo: "bar", baz: 42, scope: "should-be-dropped" },
+      ts: new Date("2024-01-01T00:00:00Z"),
+      stacktrace: "",
+    };
+
+    const flat = flattenMessage(msg);
+
+    expect(flat.foo).toBe("bar");
+    expect(flat.baz).toBe(42);
+    // Reserved key from the object message should be dropped
+    expect(flat.scope).toBe("my-scope");
+    expect(flat.level).toBe("INFO");
+  });
+
+  test("level is serialized as string name", () => {
+    const msg: LogMessage = {
+      scope: "test",
+      level: LogLevel.ERROR,
+      msg: "error msg",
+      ts: new Date(),
+      stacktrace: "",
+    };
+
+    const flat = flattenMessage(msg);
+    expect(flat.level).toBe("ERROR");
+  });
+});

test/log-service.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect } from "bun:test";
+import { LogService, LogLevel } from "../src";
+
+describe("LogService", () => {
+  test("creates a root logger on construction", () => {
+    const svc = new LogService();
+
+    expect(svc.ROOT_LOGGER).toBeDefined();
+    expect(svc.ROOT_LOGGER.name).toBe("ROOT");
+  });
+
+  test("root logger defaults to ALL threshold", () => {
+    const svc = new LogService();
+
+    expect(svc.ROOT_LOGGER.threshold).toBe(LogLevel.ALL);
+  });
+
+  test("getLogger returns the same instance for the same name", () => {
+    const svc = new LogService();
+
+    const a = svc.getLogger("foo");
+    const b = svc.getLogger("foo");
+
+    expect(a).toBe(b);
+  });
+
+  test("getLogger creates hierarchical loggers", () => {
+    const svc = new LogService();
+
+    const foo = svc.getLogger("foo");
+    const fooBar = svc.getLogger("foo.bar");
+    const fooBarBaz = svc.getLogger("foo.bar.baz");
+
+    // foo.bar should be a child of foo
+    // We can verify by checking threshold propagation
+    foo.appenders = [{
+      threshold: LogLevel.ALL,
+      messages: [] as any[],
+      appendMessage(m: any) { this.messages!.push(m); },
+    }];
+
+    fooBar.info("propagate");
+
+    // The foo appender should receive the message from fooBar
+    expect(foo.appenders[0].messages.length).toBe(1);
+  });
+
+  test("getLogger allows setting threshold", () => {
+    const svc = new LogService();
+
+    const logger = svc.getLogger("with-threshold", LogLevel.ERROR);
+    expect(logger.threshold).toBe(LogLevel.ERROR);
+  });
+});

test/logger.test.ts

@@ -0,0 +1,104 @@
+import { describe, test, expect } from "bun:test";
+import { Logger, LogLevel, LogMessage } from "../src";
+
+describe("Logger", () => {
+  test("uses parent threshold when no threshold is set", () => {
+    const parent = new Logger("parent", undefined, LogLevel.WARN);
+    const child = new Logger("child", parent);
+
+    // Should not log below WARN (from parent)
+    const appender = { threshold: LogLevel.ALL, messages: [] as LogMessage[], appendMessage(msg: LogMessage) { this.messages.push(msg); } };
+    child.appenders = [appender];
+
+    child.info("should be dropped");
+    child.warn("should be logged");
+
+    expect(appender.messages.length).toBe(1);
+    expect(appender.messages[0].msg).toBe("should be logged");
+  });
+
+  test("overrides parent threshold when own threshold is set", () => {
+    const parent = new Logger("parent", undefined, LogLevel.WARN);
+    const child = new Logger("child", parent, LogLevel.ERROR);
+
+    const appender = { threshold: LogLevel.ALL, messages: [] as LogMessage[], appendMessage(msg: LogMessage) { this.messages.push(msg); } };
+    child.appenders = [appender];
+
+    child.warn("should be dropped");
+    child.error("should be logged");
+
+    expect(appender.messages.length).toBe(1);
+    expect(appender.messages[0].msg).toBe("should be logged");
+  });
+
+  test("propagates messages to parent appenders", () => {
+    const parent = new Logger("parent", undefined, LogLevel.ALL);
+    const parentAppender = { threshold: LogLevel.ALL, messages: [] as LogMessage[], appendMessage(msg: LogMessage) { this.messages.push(msg); } };
+    parent.appenders = [parentAppender];
+
+    const child = new Logger("child", parent);
+    const childAppender = { threshold: LogLevel.ALL, messages: [] as LogMessage[], appendMessage(msg: LogMessage) { this.messages.push(msg); } };
+    child.appenders = [childAppender];
+
+    child.info("hello");
+
+    expect(childAppender.messages.length).toBe(1);
+    expect(parentAppender.messages.length).toBe(1);
+  });
+
+  test("threshold of ALL (0) is not treated as falsy", () => {
+    // This is the threshold bug: `this.threshold &&` treats 0 (LogLevel.ALL) as falsy.
+    // When threshold is explicitly set to LogLevel.ALL (0), messages at ALL level
+    // should still pass through.
+    const logger = new Logger("test", undefined, LogLevel.ALL);
+    const appender = { threshold: LogLevel.ALL, messages: [] as LogMessage[], appendMessage(msg: LogMessage) { this.messages.push(msg); } };
+    logger.appenders = [appender];
+
+    logger.info("should be logged at ALL threshold");
+
+    expect(appender.messages.length).toBe(1);
+    expect(appender.messages[0].msg).toBe("should be logged at ALL threshold");
+  });
+
+  test("handles deferred messages", () => {
+    const logger = new Logger("test", undefined, LogLevel.ALL);
+    const appender = { threshold: LogLevel.ALL, messages: [] as LogMessage[], appendMessage(msg: LogMessage) { this.messages.push(msg); } };
+    logger.appenders = [appender];
+
+    logger.info(() => "deferred result");
+
+    expect(appender.messages.length).toBe(1);
+    expect(appender.messages[0].msg).toBe("deferred result");
+  });
+
+  test("handles Error objects", () => {
+    const logger = new Logger("test", undefined, LogLevel.ALL);
+    const appender = { threshold: LogLevel.ALL, messages: [] as LogMessage[], appendMessage(msg: LogMessage) { this.messages.push(msg); } };
+    logger.appenders = [appender];
+
+    const err = new Error("boom");
+    logger.error(err);
+
+    expect(appender.messages.length).toBe(1);
+    expect(appender.messages[0].msg).toBe("Error: boom");
+    expect(appender.messages[0].err).toBe(err);
+  });
+
+  test("log methods exist for all levels", () => {
+    const logger = new Logger("test", undefined, LogLevel.ALL);
+    const appender = { threshold: LogLevel.ALL, messages: [] as LogMessage[], appendMessage(msg: LogMessage) { this.messages.push(msg); } };
+    logger.appenders = [appender];
+
+    logger.trace("trace msg");
+    logger.debug("debug msg");
+    logger.log("log msg");
+    logger.info("info msg");
+    logger.warn("warn msg");
+    logger.error("error msg");
+    logger.fatal("fatal msg");
+
+    expect(appender.messages.length).toBe(7);
+    expect(appender.messages[0].level).toBe(LogLevel.TRACE);
+    expect(appender.messages[6].level).toBe(LogLevel.FATAL);
+  });
+});

tsconfig.json

@@ -1,7 +1,7 @@
 {
   "compilerOptions": {
     "module": "commonjs",
-    "target": "es6",
+    "target": "es2016",
     "declaration": true,
     "outDir": "./dist",
     "strict": true,