async-logger package

Non-blocking logger for @imqueue services: writes to the console without holding up the caller, and ships the same records to file or HTTP transports configured entirely from the environment.

The default export is a ready-to-use Logger already configured from LOGGER_TRANSPORTS and LOGGER_METADATA, so the common case needs no construction and no wiring:

import logger from '@imqueue/async-logger';

logger.info('service started on port %s', port);

Remarks

Console writes are deferred with setTimeout, which is what keeps a burst of logging from blocking the event loop — and the reason for the package name. Two consequences follow: log output can appear after code that ran later, and a process that exits immediately after logging may lose the tail. Call it a tick before exiting if the last lines matter.

Transports are declared as JSON in LOGGER_TRANSPORTS. The placeholders %name and %version are substituted from the running service's own package.json, so one config can be shared across services:

export LOGGER_TRANSPORTS='[{"type":"http","options":{"ssl":true,"port":443,"host":"http-intake.logs.datadoghq.com","path":"/v1/input/<API_KEY>"},"enabled":true}]'
export LOGGER_METADATA='{"ddsource":"%name %version","ddtags":"env: dev"}'

With no transports configured the logger still works — console only. That is the intended local-development mode, not a misconfiguration.

Classes

Class	Description
Logger	Logger that writes to the console without blocking the caller and forwards the same records to any configured winston transports.

Functions

Function	Description
buildMessage(args)	Renders `console.log`-style arguments into the single string a transport record needs, applying `util.format` so `%s`/`%d`/`%j` placeholders and object inspection behave exactly as they do on the console.
defaultMetadata()	Parses the default record metadata out of `LOGGER_METADATA`, expanding `%name` and `%version` first.
getTransport(type, options)	Constructs a winston transport of the named type.
pkg()	Reads the running service's own name and version, used to expand the `%name` and `%version` placeholders in the logger environment variables.
transportsConfig()	Parses the transport declarations out of `LOGGER_TRANSPORTS`, expanding `%name` and `%version` first.

Interfaces

Interface	Description
AsyncLoggerOptions	Explicit configuration for a Logger, replacing what it would otherwise read from the environment.
ILogger	The logger contract shared across `@imqueue` — the four console methods, and nothing else.
JsonArray	A JSON array — any number of AnyJson values.
JsonObject	A JSON object — string keys, AnyJson values. This is the type of the logger's default metadata.
TransportOptions	One transport declaration — the shape of each element in the `LOGGER_TRANSPORTS` JSON array.

Variables

Variable	Description
_default	A Logger configured from the environment, constructed at import time.

Type Aliases

Type Alias	Description
AnyJson	Any value that survives `JSON.stringify` unchanged.

Read this page as plain markdown — no HTML, no navigation. For pasting into an LLM, or for an agent to fetch.