API Reference

This document provides a detailed API reference for the Zario logging library, covering its core components, interfaces, and classes.

Core Logger

Logger Class

The central class for creating and managing loggers.

• constructor(options?: LoggerOptions): Creates a new Logger instance.
• debug(message: string, metadata?: Record<string, any>): void: Logs a debug message.
• info(message: string, metadata?: Record<string, any>): void: Logs an informational message.
• warn(message: string, metadata?: Record<string, any>): void: Logs a warning message.
• error(message: string, metadata?: Record<string, any>): void: Logs an error message.
• silent(message: string, metadata?: Record<string, any>): void: Logs a silent message (typically not output).
• boring(message: string, metadata?: Record<string, any>): void: Logs a boring message.
• logWithLevel(level: LogLevel, message: string, metadata?: Record<string, any>): void: Logs a message with a specified (potentially custom) log level.
• setLevel(level: LogLevel): void: Sets the minimum log level for this logger.
• setFormat(format: "text" | "json"): void: Dynamically changes the output format to text or JSON.
• setAsyncMode(asyncMode: boolean): void: Enables or disables asynchronous logging mode.
• addTransport(transport: Transport): void: Adds a new transport to the logger.
• getTimestampSetting(): boolean: Returns the current timestamp setting.
• static get global(): Logger: Provides access to a globally shared Logger instance.
• createChild(options?: LoggerOptions): Logger: Creates a new child logger that inherits settings from its parent.
• startTimer(name: string): Timer: Starts a timer, logging the duration when end() is called.
• addFilter(filter: Filter): void: Adds a filter to the logger to control log emission.
• removeFilter(filter: Filter): boolean: Removes an existing filter from the logger.
• addAggregator(aggregator: LogAggregator): void: Adds a log aggregator to process logs in batches or over time.
• removeAggregator(aggregator: LogAggregator): boolean: Removes an existing log aggregator.
• addEnricher(enricher: LogEnricher): void: Adds a log enricher to modify log data before processing.
• flushAggregators(): Promise<void>: Flushes any pending logs in all attached aggregators.

LogLevel Type

Represents the severity level of a log message.

Transports

Transports are responsible for outputting log data to various destinations.

Transport Interface

The base interface for all transports.

• write(data: LogData, formatter: Formatter): void: Synchronously writes formatted log data.
• writeAsync?(data: LogData, formatter: Formatter): Promise<void>: Asynchronously writes formatted log data.

ConsoleTransport Class

Outputs log messages to the console.

• constructor(options?: ConsoleTransportOptions): Creates a new ConsoleTransport instance.
• write(data: LogData, formatter: Formatter): void: Writes log data to console.log, console.warn, or console.error based on level.
• writeAsync(data: LogData, formatter: Formatter): Promise<void>: Asynchronously writes log data to the console.

FileTransport Class

Writes log messages to a file, with optional rotation and compression.

• constructor(options: FileTransportOptions): Creates a new FileTransport instance.
• write(data: LogData, formatter: Formatter): void: Synchronously appends log data to the file, rotating if maxSize is exceeded.
• writeAsync(data: LogData, formatter: Formatter): Promise<void>: Asynchronously appends log data to the file, rotating if maxSize is exceeded.
• destroy(): Promise<void>: Cleans up resources, flushing any pending batch logs.

HttpTransport Class

Sends log messages to a remote HTTP endpoint.

• constructor(options: HttpTransportOptions): Creates a new HttpTransport instance.
• write(data: LogData, formatter: Formatter): void: Synchronously sends log data via an HTTP request.
• writeAsync(data: LogData, formatter: Formatter): Promise<void>: Asynchronously sends log data via an HTTP request, with retry logic.

FilterableTransport Class

A transport wrapper that applies filters before delegating to an underlying transport.

• constructor(transport: Transport, filters: Filter[]): Creates a new FilterableTransport instance.
• write(data: LogData, formatter: Formatter): void: Writes log data only if all applied filters pass.
• writeAsync(data: LogData, formatter: Formatter): Promise<void>: Asynchronously writes log data only if all applied filters pass.

Filters

Filters allow for selective emission of log messages based on criteria.

Filter Interface

The base interface for all filters.

• shouldEmit(logData: LogData): boolean: Returns true if the log should be emitted, false otherwise.

CompositeFilter Class

Combines multiple filters using an "AND" logic (all filters must pass).

• constructor(filters: Filter[]): Creates a new CompositeFilter with an array of filters.
• shouldEmit(logData: LogData): boolean: Returns true if all internal filters return true.

OrFilter Class

Combines multiple filters using an "OR" logic (at least one filter must pass).

• constructor(filters: Filter[]): Creates a new OrFilter with an array of filters.
• shouldEmit(logData: LogData): boolean: Returns true if any internal filter returns true.

NotFilter Class

Negates the result of another filter.

• constructor(filter: Filter): Creates a new NotFilter with a single filter to negate.
• shouldEmit(logData: LogData): boolean: Returns true if the wrapped filter returns false.

PredicateFilter Class

Filters logs based on a custom predicate function.

• constructor(predicate: FilterPredicate): Creates a new PredicateFilter with a custom function.
• shouldEmit(logData: LogData): boolean: Executes the provided predicate function against LogData.

LevelFilter Class

Filters logs based on a list of allowed log levels.

• constructor(allowedLevels: LogLevel[]): Creates a new LevelFilter with an array of allowed LogLevels.
• shouldEmit(logData: LogData): boolean: Returns true if the log's level is in the allowed list.

PrefixFilter Class

Filters logs based on a list of allowed prefixes.

• constructor(allowedPrefixes: string[]): Creates a new PrefixFilter with an array of allowed prefixes.
• shouldEmit(logData: LogData): boolean: Returns true if the log's prefix is in the allowed list.

MetadataFilter Class

Filters logs based on the presence and value of specified metadata fields.

• constructor(requiredMetadata: { [key: string]: any }): Creates a new MetadataFilter with required metadata key-value pairs.
• shouldEmit(logData: LogData): boolean: Returns true if all requiredMetadata fields match the log's metadata.

FieldFilter Class

Filters logs based on a specific field and its expected value within the log's metadata.

• constructor(fieldName: string, expectedValue: any): Creates a new FieldFilter for a specific metadata field.
• shouldEmit(logData: LogData): boolean: Returns true if the specified metadata field's value matches expectedValue.

Aggregation

Aggregators collect log messages before processing them, often for batching or timed submission.

LogAggregator Interface

The base interface for all log aggregators.

• aggregate(logData: LogData, formatter: Formatter): void: Processes a single log record for aggregation.
• flush(): Promise<void> | void: Flushes any pending aggregated logs.

BatchAggregator Class

Aggregates logs in memory and flushes them when a maxSize (number of logs) is reached.

• constructor(maxSize: number, flushCallback: (logs: { logData: LogData; formatter: Formatter }[]) => Promise<void> | void): Creates a new BatchAggregator.
• aggregate(logData: LogData, formatter: Formatter): void: Adds a log to the internal queue. Flushes if maxSize is met.
• flush(): Promise<void> | void: Forces a flush of all currently aggregated logs.

TimeBasedAggregator Class

Aggregates logs based on a specified time interval.

• constructor(flushInterval: number, flushCallback: (logs: { logData: LogData; formatter: Formatter }[]) => Promise<void> | void): Creates a new TimeBasedAggregator.
• aggregate(logData: LogData, formatter: Formatter): void: Adds a log to the internal queue and starts a timer if not already running.
• flush(): Promise<void> | void: Forces a flush of all currently aggregated logs and resets the timer.
• stop(): void: Stops the aggregator and cancels any pending timer without flushing.

CompositeAggregator Class

Combines multiple aggregators, allowing a single log to be sent to several different aggregation strategies.

• constructor(aggregators: LogAggregator[]): Creates a new CompositeAggregator with an array of aggregators.
• aggregate(logData: LogData, formatter: Formatter): void: Passes the log data to all contained aggregators.
• flush(): Promise<void> | void: Flushes all contained aggregators.

Structured Logging Extensions

Tools for enriching log data with additional context.

LogEnricher Interface

A function signature for enriching log data.

• (logData: LogData): LogData: A function that takes LogData and returns modified LogData.

MetadataEnricher Class

Provides static methods to create common LogEnricher functions.

• static addStaticFields(staticFields: { [key: string]: any }): LogEnricher: Creates an enricher that adds fixed metadata fields.
• static addDynamicFields(dynamicFields: () => { [key: string]: any }): LogEnricher: Creates an enricher that adds dynamically computed metadata fields.
• static addContext(staticFields: { [key: string]: any }): LogEnricher: Alias for addStaticFields.
• static addProcessInfo(): LogEnricher: Creates an enricher that adds current process information (PID, hostname, Node.js version).
• static addEnvironmentInfo(): LogEnricher: Creates an enricher that adds environment information (NODE_ENV, platform, architecture).

LogEnrichmentPipeline Class

Applies a series of LogEnricher functions to a log record in sequence.

• constructor(enrichers?: LogEnricher[]): Creates a new pipeline with an optional initial set of enrichers.
• add(enricher: LogEnricher): LogEnrichmentPipeline: Adds an enricher to the end of the pipeline.
• process(logData: LogData): LogData: Runs the given logData through all enrichers in the pipeline.
• getEnrichers(): LogEnricher[]: Returns a copy of the enrichers in the pipeline.

Utilities

Timer Class

A utility for measuring the duration of an operation and logging the result.

• constructor(name: string, logFn: (message: string) => void): Creates and starts a new timer. logFn is called with the duration message.
• end(): void: Stops the timer and calls the logFn with the calculated duration. Is idempotent.

Key Types and Interfaces

LoggerOptions Interface

Configuration options for the Logger class.

TransportConfig Type

A union type representing either a LegacyTransportOptions object or a direct Transport instance.

LogData Interface

The structure of a raw log record before formatting.

CustomLogLevelConfig Interface

Defines a custom log level's name, color, and priority.

FormatterOptions Interface

Configuration options for log message formatting.