Adze Logging Library

The LevelSelector type is used throughout the library (in Configuration.activeLevel, Configuration.filters, GlobalStore.addListener, and GlobalStore.tools.filterByLevel) to allow flexible selection of one or more log levels.

Supported formats for LevelSelector include:

• *: Selects all log levels.
• string: A single level name (e.g., 'info').
• number: A single level value.
• string[] or number[]: An array of specific levels.
• [string, '-', string] or [number, '-', number]: A range of levels (e.g., ['alert', '-', 'warn']).

import adze, { setup } from 'adze';

const store = setup();

// Add a listener that selects ALL log levels.
store.addListener('*', (log: Log) => {
  /* Do something */
});

// Add a listener that selects a single log level by name.
store.addListener('info', (log: Log) => {
  /* Do something with info logs */
});

// Add a listener that selects both alert and error log levels by name.
store.addListener(['alert', 'error'], (log: Log) => {
  /* Do something with the alert and error logs */
});

// Or select a range of values by their name.
store.addListener(['alert', '-', 'warn'], (log: Log) => {
  /* Do something with the alert, error, and warn logs */
});

// Alternatively, select alert and error logs by their level values.
store.addListener([0, 1], (log: Log) => {
  /* Do something with the alert and error logs */
});

// Or select a range of logs by their level values.
store.addListener([0, '-', 3], (log: Log) => {
  /* Do something with the alert, error, warn, and info logs */
});

Filters allow you to control which logs are rendered to the console or server based on their level, label, or namespace.

Each filter uses a FilterConfig which requires a type and a set of values:

• type: 'include': Only logs matching the values will be rendered.
• type: 'exclude': Logs matching the values will be suppressed.

If both include and exclude are specified, include takes precedence.

Note: When filtering by level, you can use the LevelSelector type to specify single levels, arrays of levels, or ranges (e.g., ['alert', '-', 'warn']).

import adze, { setup } from 'adze';

setup({
  filters: {
    namespaces: {
      type: 'include',
      values: ['foo'],
    },
  },
});

adze.ns('foo').success('I should print.');
adze.ns('foo', 'bar').success('I should print.');
adze.ns('bar').fail('I should not print.');
adze.fail('I should not print because I do not have a namespace.');

An Adze log follows a specific lifecycle of construction, termination, and storage. Understanding this flow is essential for working with middleware, log listeners, and the global store.

1. Construction & Modification: You start a log using the Adze class. You can chain an indefinite number of modifier methods together. Each time a static modifier method is called, a new instance of Adze is returned, allowing for continuous chaining.
2. Termination: To finalize a log, you call a terminator method. Unlike modifiers, a terminator method does not return a new Adze instance; it ends the chain. At this point, the log properties are evaluated, and the log message is generated and printed.
3. Middleware Execution: During the termination process, Adze triggers lifecycle hooks on any registered middleware instances. This allows plugins to intercept, manipulate, or capture log data before it is finalized.
4. Storage: Once terminated, the log instance is stored in the Global Store (provided that caching is enabled in your configuration). This allows you to later filter and recall historical logs using global store tools.

If built-in formatters do not meet your needs, you can create a third-party formatter by extending the Formatter class.

The Formatter class handles environment detection (browser vs. server) and timestamp formatting logic. To implement a complete formatter, you must override both formatBrowser and formatServer.

Implementation Details

• formatBrowser(data: ModifierData, timestamp: string, args: unknown[]): unknown[]: Called in browser environments. It should return an array of formatted arguments in the same order they were provided.
• formatServer(data: ModifierData, timestamp: string, args: unknown[]): unknown[]: Called in backend environments. It should return an array of formatted arguments in the same order they were provided.
• timestampFormatter getter: Returns the most relevant timestamp formatter based on a hierarchy:
  1. The Formatter class definition (highest priority).
  2. The UserConfiguration override.
  3. The default ISO-8601 formatter (lowest priority).

import { Configuration, Formatter, type LevelConfiguration, type ModifierData } from 'adze';

class HelloFormatter extends Formatter {
  constructor(cfg: Configuration, level: LevelConfiguration) {
    super(cfg, level);
  }

  protected formatBrowser(data: ModifierData, timestamp: string, args: unknown[]): unknown[] {
    // Example: prepend 'Hello' to browser logs
    return ['Hello', ...args];
  }

  protected formatServer(data: ModifierData, timestamp: string, args: unknown[]): unknown[] {
    // Example: prepend 'Hello' to server logs
    return ['Hello', ...args];
  }
}