@holz/core 0.7.0-rc.2 → 0.8.0-rc.1

package/README.md

@@ -7,21 +7,32 @@
 Here is an example of how to create a logger and use it to log a message:
 
 ```typescript
-import { createLogger } from '@holz/core';
+import { createLogger, type LogLevel } from '@holz/core';
 
 const logger = createLogger((log) => {
-  console.log(`[${log.level}]`, log.message);
+  console.log(logLevelPrefix[log.level], log.message);
 });
 
+const logLevelPrefix: Record<LogLevel, string> = {
+  [level.trace]: '[trace]',
+  [level.debug]: '[debug]',
+  [level.info]: '[info]',
+  [level.warn]: '[warn]',
+  [level.error]: '[error]',
+  [level.fatal]: '[fatal]',
+};
+
 logger.info('Hello, world!');
 ```
 
-This will log a message with the info level to the console.
+This will log a message to the console.
 
 ```
 [info] Hello, world!
 ```
 
+This is a simplified example of what `@holz/console-backend` does under the hood.
+
 ## Logger Interface
 
 The `Logger` class is the core of the library. It provides a set of methods for logging messages with different levels of severity. Each method takes a message and an optional context object.
@@ -30,14 +41,18 @@ You can also use the `namespace` method to create a new logger with a specific o
 
 ## Log Levels
 
-The library provides four log levels:
+The library provides six log levels:
+
+- `level.fatal`: Something critical failed and we can't recover.
+- `level.error`: Something failed, but we can recover.
+- `level.warn`: Something is concerning, but we can keep going.
+- `level.info`: High-level progress updates.
+- `level.debug`: Low-level progress updates, such as events (usually hidden).
+- `level.trace`: Extremely verbose updates, such as function calls and branch conditions (usually hidden).
 
-- `LogLevel.Debug`: Extremely verbose progress updates (usually hidden).
-- `LogLevel.Info`: High-level progress updates.
-- `LogLevel.Warn`: Something is concerning, but we can keep going.
-- `LogLevel.Error`: Something critical failed and we can't continue.
+Backends may do different things depending on severity, such as only uploading `info` or above to a log aggregator.
 
-You can use these levels to indicate the severity of a log message. The severity levels can be configured to perform actions based on the level of severity of the log messages.
+Each level is a number. Higher numbers mean higher severity.
 
 ## Log Structure
 
@@ -46,7 +61,7 @@ Every log message processed by Holz follows a specific structure defined by the
 A `Log` object contains the following properties:
 
 - `message`: The verbatim log message. This property should not contain any interpolated data.
-- `level`: The severity of the log message, expressed as a member of the `LogLevel` enum. The available log levels are, in increasing order of severity: `Debug`, `Info`, `Warn`, `Error`.
+- `level`: The severity of the log message, expressed as a member of the `LogLevel` enum. The available log levels are, in increasing order of severity: `trace`, `debug`, `info`, `warn`, `error`, `fatal`.
 - `origin`: The source of the log message. This property is an array of strings that typically identifies the library, module, or component that generated the log message, followed by more specific information. This property can be used to filter and group log messages based on their origin.
 - `context`: A dictionary of key-value pairs that provides additional context for the log message. The values in this object must be JSON serializable. Because it's easy to accidentally include unsuitable log context, such as PII or deeply nested objects, the use of nested objects in the context is discouraged.
 
@@ -54,9 +69,9 @@ Here is an example of a log message expressed as a `Log` object:
 
 ```typescript
 {
-  message: 'Connection to database established.',
-  level: LogLevel.Info,
-  origin: ['my-app', 'database-connection'],
+  message: 'Established database connection',
+  level: level.info,
+  origin: ['my-app', 'db'],
   context: {
     host: 'localhost',
     port: 5432,
@@ -93,7 +108,7 @@ import {
 } from './custom-processors';
 
 const logger = createLogger(
-  combine([consoleBackend, fileBackend, logUploadService])
+  combine([consoleBackend, fileBackend, logUploadService]),
 );
 ```
 
@@ -105,8 +120,8 @@ The `filter` processor takes a filter function and another log processor as inpu
 import { filter } from '@holz/core';
 
 const debugLogFilter = filter(
-  (log) => log.level !== LogLevel.Debug,
-  consoleProcessor
+  (log) => log.level > level.debug,
+  consoleProcessor,
 );
 
 const logger = createLogger(debugLogFilter);

package/dist/holz-core.cjs

@@ -1 +1 @@
-"use strict";var a=Object.defineProperty;var c=(o,r,e)=>r in o?a(o,r,{enumerable:!0,configurable:!0,writable:!0,value:e}):o[r]=e;var i=(o,r,e)=>c(o,typeof r!="symbol"?r+"":r,e);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});var t=(o=>(o.Error="error",o.Warn="warn",o.Info="info",o.Debug="debug",o))(t||{});function f(o){return r=>o.forEach(e=>e(r))}function u(o,r){return e=>{o(e)&&r(e)}}class s{constructor(r,e){i(this,"debug",(r,e)=>{this.forwardLog(t.Debug,r,e)});i(this,"info",(r,e)=>{this.forwardLog(t.Info,r,e)});i(this,"warn",(r,e)=>{this.forwardLog(t.Warn,r,e)});i(this,"error",(r,e)=>{this.forwardLog(t.Error,r,e)});this.processor=r,this.owner=e;const n={configurable:!1,enumerable:!1};Object.defineProperties(this,{processor:n,debug:n,info:n,warn:n,error:n})}namespace(r){return new s(this.processor,this.owner.concat(r))}forwardLog(r,e,n={}){this.processor({message:e,level:r,origin:this.owner,context:n})}}const g=o=>new s(o,[]);exports.LogLevel=t;exports.combine=f;exports.createLogger=g;exports.filter=u;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const b=n=>r=>n.forEach(e=>e(r)),f=(n,r)=>e=>{n(e)&&r(e)},l={fatal:60,error:50,warn:40,info:30,debug:20,trace:10},i=(n,r)=>{const e=(a,c,d={})=>{n({message:c,level:a,origin:r,context:d})},o={owner:r,trace:e.bind(null,l.trace),debug:e.bind(null,l.debug),info:e.bind(null,l.info),warn:e.bind(null,l.warn),error:e.bind(null,l.error),fatal:e.bind(null,l.fatal),namespace:a=>i(n,r.concat(a)),withMiddleware:a=>i(a(n),r)},t={configurable:!1,enumerable:!1};return Object.defineProperties(o,{withMiddleware:t,namespace:t,trace:t,debug:t,info:t,warn:t,error:t,fatal:t})},g=n=>i(n,[]);exports.combine=b;exports.createLogger=g;exports.filter=f;exports.level=l;

package/dist/holz-core.d.ts

@@ -3,7 +3,7 @@
  * called in sequence. Useful for sending a single log to multiple log
  * destinations.
  */
-export declare function combine(processors: Array<LogProcessor>): LogProcessor;
+export declare const combine: (processors: Array<LogProcessor>) => LogProcessor;
 
 /**
  * Create a new logger. The processor is up to you. There are plugins for
@@ -13,24 +13,60 @@ export declare function combine(processors: Array<LogProcessor>): LogProcessor;
  */
 export declare const createLogger: (processor: LogProcessor) => Logger;
 
+/**
+ * Custom values allowed in log context. These values don't have to be JSON.
+ * The most common case is errors, which support richer error tracking in
+ * backends that support it.
+ *
+ * This is part of the public API. Backends may use declaration merging to
+ * extend the standard attributes. It's recommended to use symbols as keys for
+ * custom features, but not required.
+ */
+export declare interface CustomContext {
+    /**
+     * Error instance associated with the log message. This supports error
+     * tracking and shows prominently in visual backends like TTY output.
+     */
+    error: Error;
+}
+
 /**
  * Filter logs based on a filter function. If the function returns true, the
  * log is kept and forwarded onto the next processor, otherwise it is
  * discarded.
  */
-export declare function filter(
+export declare const filter: (
 /** Returns `true` to forward the log. */
 predicate: (log: Log) => boolean, 
 /** Where to send the log if it passes the filter. */
-processor: LogProcessor): LogProcessor;
+processor: LogProcessor) => LogProcessor;
+
+declare interface JsonContext {
+    [key: string]: JsonPrimitive | ReadonlyArray<JsonPrimitive>;
+}
 
 declare type JsonPrimitive = string | number | boolean | null | undefined;
 
+export declare const level: {
+    /** A critical failure happened and the program must exit. */
+    readonly fatal: 60;
+    /** Something failed, but we can keep going. */
+    readonly error: 50;
+    /** Cause for concern, but we can keep going. */
+    readonly warn: 40;
+    /** High-level progress updates. */
+    readonly info: 30;
+    /** Verbose update about events or control flow (usually hidden). */
+    readonly debug: 20;
+    /** Extremely detailed progress updates (usually hidden). */
+    readonly trace: 10;
+};
+
 /** A log message where variables are carried as structured data. */
 export declare interface Log {
     /** The verbatim log message. Should not contain interpolated data. */
     readonly message: string;
-    /** Log severity. */
+    /** Log severity. One of `levels.*`. */
     readonly level: LogLevel;
     /**
      * Where the log message originated. Usually starts with a library or app name,
@@ -55,35 +91,42 @@ export declare interface Log {
     readonly context: LogContext;
 }
 
-export declare type LogContext = Record<string, JsonPrimitive | ReadonlyArray<JsonPrimitive>>;
+/**
+ * A more general type expected by logging backends. Supports type narrowing,
+ * so if a known field exists, it will be used instead of the generic JSON
+ * type.
+ */
+export declare type LogContext = Partial<CustomContext> & JsonContext;
 
-export declare class Logger {
-    private processor;
+/**
+ * This is the public API which generates and sends `Log` events through the
+ * user-defined processing pipeline.
+ */
+export declare interface Logger {
     readonly owner: ReadonlyArray<string>;
-    constructor(processor: LogProcessor, owner: ReadonlyArray<string>);
     /** Extend the logger to attach a class or module name to logs. */
-    namespace(owner: string): Logger;
+    namespace: (owner: string) => Logger;
+    /**
+     * Create a new logger which runs all logs through a middleware function.
+     * Useful for adding default context, doing ad-hoc filtering, or
+     * registering plugins. Only applies to this logger and its descendants.
+     */
+    withMiddleware: (middleware: (next: LogProcessor) => LogProcessor) => Logger;
+    /** Log a verbose and frequent update. */
+    trace: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
     /** Log a frequent and verbose progress update. */
-    debug: (message: string, context?: LogContext) => void;
+    debug: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
     /** Log a high-level progress update. */
-    info: (message: string, context?: LogContext) => void;
+    info: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
     /** Log something concerning. */
-    warn: (message: string, context?: LogContext) => void;
-    /** Log a critical failure. */
-    error: (message: string, context?: LogContext) => void;
-    private forwardLog;
+    warn: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
+    /** Log a failure. */
+    error: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
+    /** Log a catastrophic failure. */
+    fatal: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
 }
 
-export declare enum LogLevel {
-    /** Something critical failed and we can't continue. */
-    Error = "error",
-    /** Something is concerning, but we can keep going. */
-    Warn = "warn",
-    /** High-level progress updates. */
-    Info = "info",
-    /** Extremely verbose progress updates (usually hidden). */
-    Debug = "debug"
-}
+export declare type LogLevel = (typeof level)[keyof typeof level];
 
 /**
  * A logger is made up of log processors. These processors take structured
@@ -92,7 +135,16 @@ export declare enum LogLevel {
  */
 export declare interface LogProcessor {
     /** Do something with a log message. */
-    (log: Log): void;
+    (log: Log): unknown;
 }
 
+/**
+ * A type narrowing constraint designed for generic constraints. Controls
+ * what fields are allowed in `log.context`, sourcing from `CustomContext`
+ * first, then falling back to any JSON value.
+ */
+declare type StrictContext<Input> = {
+    [Key in keyof Input]: Key extends keyof CustomContext ? CustomContext[Key] : JsonPrimitive | ReadonlyArray<JsonPrimitive>;
+};
+
 export { }

package/dist/holz-core.js

@@ -1,60 +1,51 @@
-var a = Object.defineProperty;
-var c = (e, r, o) => r in e ? a(e, r, { enumerable: !0, configurable: !0, writable: !0, value: o }) : e[r] = o;
-var s = (e, r, o) => c(e, typeof r != "symbol" ? r + "" : r, o);
-var t = /* @__PURE__ */ ((e) => (e.Error = "error", e.Warn = "warn", e.Info = "info", e.Debug = "debug", e))(t || {});
-function u(e) {
-  return (r) => e.forEach((o) => o(r));
-}
-function h(e, r) {
-  return (o) => {
-    e(o) && r(o);
-  };
-}
-class i {
-  constructor(r, o) {
-    /** Log a frequent and verbose progress update. */
-    s(this, "debug", (r, o) => {
-      this.forwardLog(t.Debug, r, o);
+const f = (n) => (r) => n.forEach((e) => e(r)), b = (n, r) => (e) => {
+  n(e) && r(e);
+}, l = {
+  /** A critical failure happened and the program must exit. */
+  fatal: 60,
+  /** Something failed, but we can keep going. */
+  error: 50,
+  /** Cause for concern, but we can keep going. */
+  warn: 40,
+  /** High-level progress updates. */
+  info: 30,
+  /** Verbose update about events or control flow (usually hidden). */
+  debug: 20,
+  /** Extremely detailed progress updates (usually hidden). */
+  trace: 10
+}, i = (n, r) => {
+  const e = (t, d, c = {}) => {
+    n({
+      message: d,
+      level: t,
+      origin: r,
+      context: c
     });
-    /** Log a high-level progress update. */
-    s(this, "info", (r, o) => {
-      this.forwardLog(t.Info, r, o);
-    });
-    /** Log something concerning. */
-    s(this, "warn", (r, o) => {
-      this.forwardLog(t.Warn, r, o);
-    });
-    /** Log a critical failure. */
-    s(this, "error", (r, o) => {
-      this.forwardLog(t.Error, r, o);
-    });
-    this.processor = r, this.owner = o;
-    const n = { configurable: !1, enumerable: !1 };
-    Object.defineProperties(this, {
-      processor: n,
-      debug: n,
-      info: n,
-      warn: n,
-      error: n
-    });
-  }
-  /** Extend the logger to attach a class or module name to logs. */
-  namespace(r) {
-    return new i(this.processor, this.owner.concat(r));
-  }
-  forwardLog(r, o, n = {}) {
-    this.processor({
-      message: o,
-      level: r,
-      origin: this.owner,
-      context: n
-    });
-  }
-}
-const w = (e) => new i(e, []);
+  }, o = {
+    owner: r,
+    trace: e.bind(null, l.trace),
+    debug: e.bind(null, l.debug),
+    info: e.bind(null, l.info),
+    warn: e.bind(null, l.warn),
+    error: e.bind(null, l.error),
+    fatal: e.bind(null, l.fatal),
+    namespace: (t) => i(n, r.concat(t)),
+    withMiddleware: (t) => i(t(n), r)
+  }, a = { configurable: !1, enumerable: !1 };
+  return Object.defineProperties(o, {
+    withMiddleware: a,
+    namespace: a,
+    trace: a,
+    debug: a,
+    info: a,
+    warn: a,
+    error: a,
+    fatal: a
+  });
+}, u = (n) => i(n, []);
 export {
-  t as LogLevel,
-  u as combine,
-  w as createLogger,
-  h as filter
+  f as combine,
+  u as createLogger,
+  b as filter,
+  l as level
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/core",
-  "version": "0.7.0-rc.2",
+  "version": "0.8.0-rc.1",
   "description": "A structured and composable logger",
   "type": "module",
   "repository": {
@@ -37,11 +37,11 @@
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^3.0.8",
-    "typescript": "^5.0.0",
+    "typescript": "^5.8.2",
     "vite": "^6.0.0",
     "vite-plugin-dts": "^4.5.3",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.0.8"
   },
-  "stableVersion": "0.6.0"
+  "stableVersion": "0.7.0"
 }

package/src/__tests__/logger.test.ts

@@ -1,5 +1,5 @@
 import { createLogger } from '../logger';
-import { LogLevel } from '../types';
+import { level } from '../index';
 
 describe('Logger', () => {
   it('sends structured logs to the log processor', () => {
@@ -11,25 +11,27 @@ describe('Logger', () => {
     expect(backend).toHaveBeenCalledOnce();
     expect(backend).toHaveBeenCalledWith({
       message: 'Hello world',
-      level: 'info',
+      level: level.info,
       origin: [],
       context: { audience: 'testers' },
     });
   });
 
   it.each([
-    [LogLevel.Debug, 'Look, a dead fly', { urgency: 'high' }],
-    [LogLevel.Info, 'I am not a window cleaner!', { state: 'panic' }],
-    [LogLevel.Warn, 'There are irregularities in the pension fund', {}],
-    [LogLevel.Error, 'Leadership has taken a dive', { windows: 'open' }],
-  ])('correctly processes %s log messages', (level, message, context) => {
+    ['trace' as const, 'Look, a dead fly', { urgency: 'high?' }],
+    ['debug' as const, 'Made in Britain', { condition: 'fire' }],
+    ['info' as const, 'I am not a window cleaner!', { state: 'panic' }],
+    ['warn' as const, 'There are irregularities in the pension fund', {}],
+    ['error' as const, 'Have you tried turning it off and on again?', {}],
+    ['fatal' as const, 'Leadership has taken a dive', { windows: 'open' }],
+  ])('correctly processes %s log messages', (method, message, context) => {
     const backend = vi.fn();
     const logger = createLogger(backend);
 
-    logger[level](message, context);
+    logger[method](message, context);
     expect(backend).toHaveBeenCalledWith({
       message,
-      level,
+      level: level[method],
       context,
       origin: [],
     });
@@ -60,10 +62,51 @@ describe('Logger', () => {
       expect(backend).toHaveBeenCalledOnce();
       expect(backend).toHaveBeenCalledWith({
         message: 'opening socket',
-        level: 'info',
+        level: level.info,
         origin: ['signaling', 'socket'],
         context: {},
       });
     });
   });
+
+  describe('withMiddleware', () => {
+    it('allows middleware to be added', () => {
+      const backend = vi.fn();
+      const logger = createLogger(backend).withMiddleware((next) => (log) => {
+        next({ ...log, message: 'replaced' });
+      });
+
+      logger.info('original message');
+      expect(backend).toHaveBeenCalledOnce();
+      expect(backend).toHaveBeenCalledWith({
+        message: 'replaced',
+        level: level.info,
+        origin: [],
+        context: {},
+      });
+    });
+
+    it('inherits middleware from parent loggers', () => {
+      const backend = vi.fn();
+      const logger = createLogger(backend)
+        .withMiddleware((next) => (log) => {
+          log.context.parent = true;
+          next(log);
+        })
+        .namespace('child')
+        .withMiddleware((next) => (log) => {
+          log.context.child = true;
+          next(log);
+        });
+
+      logger.info('original message');
+      expect(backend).toHaveBeenCalledOnce();
+      expect(backend).toHaveBeenCalledWith({
+        message: 'original message',
+        level: level.info,
+        origin: ['child'],
+        context: { parent: true, child: true },
+      });
+    });
+  });
 });

package/src/__tests__/operators.test.ts

@@ -1,6 +1,6 @@
 import { createLogger } from '../logger';
 import { combine, filter } from '../operators';
-import { LogLevel } from '../types';
+import { level } from '../types';
 
 describe('operators', () => {
   describe('combine', () => {
@@ -33,7 +33,7 @@ describe('operators', () => {
     it('filters out logs that do not match the predicate', () => {
       const backend = vi.fn();
       const logger = createLogger(
-        filter((log) => log.level !== LogLevel.Debug, backend),
+        filter((log) => log.level !== level.debug, backend),
       );
 
       logger.info('keep me');

package/src/index.ts

@@ -1,4 +1,11 @@
-export type { LogProcessor, LogContext, Log } from './types';
-export { LogLevel } from './types';
 export { combine, filter } from './operators';
-export { createLogger, type Logger } from './logger';
+export { createLogger } from './logger';
+export { level } from './types';
+export type {
+  LogProcessor,
+  LogContext,
+  Log,
+  CustomContext,
+  Logger,
+  LogLevel,
+} from './types';

package/src/logger.ts

@@ -1,60 +1,56 @@
-import type { LogProcessor, LogContext } from './types';
-import { LogLevel } from './types';
-
-class Logger {
-  constructor(
-    private processor: LogProcessor,
-    readonly owner: ReadonlyArray<string>,
-  ) {
-    // Non-enumerable to keep the repl clean.
-    const hidden = { configurable: false, enumerable: false };
-    Object.defineProperties(this, {
-      processor: hidden,
-      debug: hidden,
-      info: hidden,
-      warn: hidden,
-      error: hidden,
-    });
-  }
-
-  /** Extend the logger to attach a class or module name to logs. */
-  namespace(owner: string): Logger {
-    return new Logger(this.processor, this.owner.concat(owner));
-  }
-
-  /** Log a frequent and verbose progress update. */
-  debug = (message: string, context?: LogContext) => {
-    this.forwardLog(LogLevel.Debug, message, context);
-  };
-
-  /** Log a high-level progress update. */
-  info = (message: string, context?: LogContext) => {
-    this.forwardLog(LogLevel.Info, message, context);
-  };
-
-  /** Log something concerning. */
-  warn = (message: string, context?: LogContext) => {
-    this.forwardLog(LogLevel.Warn, message, context);
-  };
-
-  /** Log a critical failure. */
-  error = (message: string, context?: LogContext) => {
-    this.forwardLog(LogLevel.Error, message, context);
-  };
-
-  private forwardLog(
+import {
+  level,
+  type LogContext,
+  type LogLevel,
+  type LogProcessor,
+  type StrictContext,
+  type Logger,
+} from './types';
+
+const createNamespacedLogger = (
+  processor: LogProcessor,
+  namespace: ReadonlyArray<string>,
+): Logger => {
+  const createAndSendLog = <Context extends StrictContext<Context>>(
     level: LogLevel,
     message: string,
-    context: LogContext = {},
-  ) {
-    this.processor({
+    context: Context = {} as Context,
+  ) => {
+    processor({
       message,
       level,
-      origin: this.owner,
-      context,
+      origin: namespace,
+      context: context as LogContext,
     });
-  }
-}
+  };
+
+  const logger: Logger = {
+    owner: namespace,
+    trace: createAndSendLog.bind(null, level.trace),
+    debug: createAndSendLog.bind(null, level.debug),
+    info: createAndSendLog.bind(null, level.info),
+    warn: createAndSendLog.bind(null, level.warn),
+    error: createAndSendLog.bind(null, level.error),
+    fatal: createAndSendLog.bind(null, level.fatal),
+    namespace: (child: string) =>
+      createNamespacedLogger(processor, namespace.concat(child)),
+    withMiddleware: (middleware) =>
+      createNamespacedLogger(middleware(processor), namespace),
+  };
+
+  // Non-enumerable to keep the repl clean.
+  const hidden = { configurable: false, enumerable: false };
+  return Object.defineProperties(logger, {
+    withMiddleware: hidden,
+    namespace: hidden,
+    trace: hidden,
+    debug: hidden,
+    info: hidden,
+    warn: hidden,
+    error: hidden,
+    fatal: hidden,
+  });
+};
 
 /**
  * Create a new logger. The processor is up to you. There are plugins for
@@ -63,6 +59,4 @@ class Logger {
  * If you wish to use more than one processor, `combine(...)` them first.
  */
 export const createLogger = (processor: LogProcessor): Logger =>
-  new Logger(processor, []);
-
-export type { Logger };
+  createNamespacedLogger(processor, []);

package/src/operators.ts

@@ -5,24 +5,25 @@ import type { Log, LogProcessor } from './types';
  * called in sequence. Useful for sending a single log to multiple log
  * destinations.
  */
-export function combine(processors: Array<LogProcessor>): LogProcessor {
-  return (log: Log) => processors.forEach((processor) => processor(log));
-}
+export const combine =
+  (processors: Array<LogProcessor>): LogProcessor =>
+  (log: Log) =>
+    processors.forEach((processor) => processor(log));
 
 /**
  * Filter logs based on a filter function. If the function returns true, the
  * log is kept and forwarded onto the next processor, otherwise it is
  * discarded.
  */
-export function filter(
-  /** Returns `true` to forward the log. */
-  predicate: (log: Log) => boolean,
-  /** Where to send the log if it passes the filter. */
-  processor: LogProcessor,
-): LogProcessor {
-  return (log: Log) => {
+export const filter =
+  (
+    /** Returns `true` to forward the log. */
+    predicate: (log: Log) => boolean,
+    /** Where to send the log if it passes the filter. */
+    processor: LogProcessor,
+  ): LogProcessor =>
+  (log: Log) => {
     if (predicate(log)) {
       processor(log);
     }
   };
-}

package/src/types.ts

@@ -5,7 +5,7 @@
  */
 export interface LogProcessor {
   /** Do something with a log message. */
-  (log: Log): void;
+  (log: Log): unknown;
 }
 
 /** A log message where variables are carried as structured data. */
@@ -13,7 +13,7 @@ export interface Log {
   /** The verbatim log message. Should not contain interpolated data. */
   readonly message: string;
 
-  /** Log severity. */
+  /** Log severity. One of `levels.*`. */
   readonly level: LogLevel;
 
   /**
@@ -40,23 +40,119 @@ export interface Log {
   readonly context: LogContext;
 }
 
-export enum LogLevel {
-  /** Something critical failed and we can't continue. */
-  Error = 'error',
+export const level = {
+  /** A critical failure happened and the program must exit. */
+  fatal: 60,
 
-  /** Something is concerning, but we can keep going. */
-  Warn = 'warn',
+  /** Something failed, but we can keep going. */
+  error: 50,
+
+  /** Cause for concern, but we can keep going. */
+  warn: 40,
 
   /** High-level progress updates. */
-  Info = 'info',
+  info: 30,
 
-  /** Extremely verbose progress updates (usually hidden). */
-  Debug = 'debug',
-}
+  /** Verbose update about events or control flow (usually hidden). */
+  debug: 20,
 
-export type LogContext = Record<
-  string,
-  JsonPrimitive | ReadonlyArray<JsonPrimitive>
->;
+  /** Extremely detailed progress updates (usually hidden). */
+  trace: 10,
+} as const;
+
+export type LogLevel = (typeof level)[keyof typeof level];
 
 type JsonPrimitive = string | number | boolean | null | undefined;
+
+export interface JsonContext {
+  [key: string]: JsonPrimitive | ReadonlyArray<JsonPrimitive>;
+}
+
+/**
+ * Custom values allowed in log context. These values don't have to be JSON.
+ * The most common case is errors, which support richer error tracking in
+ * backends that support it.
+ *
+ * This is part of the public API. Backends may use declaration merging to
+ * extend the standard attributes. It's recommended to use symbols as keys for
+ * custom features, but not required.
+ */
+export interface CustomContext {
+  /**
+   * Error instance associated with the log message. This supports error
+   * tracking and shows prominently in visual backends like TTY output.
+   */
+  error: Error;
+}
+
+/**
+ * A type narrowing constraint designed for generic constraints. Controls
+ * what fields are allowed in `log.context`, sourcing from `CustomContext`
+ * first, then falling back to any JSON value.
+ */
+export type StrictContext<Input> = {
+  [Key in keyof Input]: Key extends keyof CustomContext
+    ? CustomContext[Key]
+    : JsonPrimitive | ReadonlyArray<JsonPrimitive>;
+};
+
+/**
+ * A more general type expected by logging backends. Supports type narrowing,
+ * so if a known field exists, it will be used instead of the generic JSON
+ * type.
+ */
+export type LogContext = Partial<CustomContext> & JsonContext;
+
+/**
+ * This is the public API which generates and sends `Log` events through the
+ * user-defined processing pipeline.
+ */
+export interface Logger {
+  readonly owner: ReadonlyArray<string>;
+
+  /** Extend the logger to attach a class or module name to logs. */
+  namespace: (owner: string) => Logger;
+
+  /**
+   * Create a new logger which runs all logs through a middleware function.
+   * Useful for adding default context, doing ad-hoc filtering, or
+   * registering plugins. Only applies to this logger and its descendants.
+   */
+  withMiddleware: (middleware: (next: LogProcessor) => LogProcessor) => Logger;
+
+  /** Log a verbose and frequent update. */
+  trace: <Context extends StrictContext<Context>>(
+    message: string,
+    context?: Context,
+  ) => void;
+
+  /** Log a frequent and verbose progress update. */
+  debug: <Context extends StrictContext<Context>>(
+    message: string,
+    context?: Context,
+  ) => void;
+
+  /** Log a high-level progress update. */
+  info: <Context extends StrictContext<Context>>(
+    message: string,
+    context?: Context,
+  ) => void;
+
+  /** Log something concerning. */
+  warn: <Context extends StrictContext<Context>>(
+    message: string,
+    context?: Context,
+  ) => void;
+
+  /** Log a failure. */
+  error: <Context extends StrictContext<Context>>(
+    message: string,
+    context?: Context,
+  ) => void;
+
+  /** Log a catastrophic failure. */
+  fatal: <Context extends StrictContext<Context>>(
+    message: string,
+    context?: Context,
+  ) => void;
+}