# @imqueue/async-logger 3.2.0 · API reference

Source: https://imqueue.org/api/async-logger/latest/
Published: 2026-07-31
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/async-logger 3.2.0 — generated reference, not hand-written

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](https://imqueue.org/api/async-logger/latest/async-logger.logger/) already configured from `LOGGER_TRANSPORTS` and `LOGGER_METADATA`, so the common case needs no construction and no wiring:

```typescript
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:

```bash
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](https://imqueue.org/api/async-logger/latest/async-logger.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)](https://imqueue.org/api/async-logger/latest/async-logger.buildmessage/) | 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()](https://imqueue.org/api/async-logger/latest/async-logger.defaultmetadata/) | Parses the default record metadata out of `LOGGER_METADATA`, expanding `%name` and `%version` first. |
| [getTransport(type, options)](https://imqueue.org/api/async-logger/latest/async-logger.gettransport/) | Constructs a winston transport of the named type. |
| [pkg()](https://imqueue.org/api/async-logger/latest/async-logger.pkg/) | Reads the running service's own name and version, used to expand the `%name` and `%version` placeholders in the logger environment variables. |
| [transportsConfig()](https://imqueue.org/api/async-logger/latest/async-logger.transportsconfig/) | Parses the transport declarations out of `LOGGER_TRANSPORTS`, expanding `%name` and `%version` first. |


## Interfaces


| Interface | Description |
| --- | --- |
| [AsyncLoggerOptions](https://imqueue.org/api/async-logger/latest/async-logger.asyncloggeroptions/) | Explicit configuration for a [Logger](https://imqueue.org/api/async-logger/latest/async-logger.logger/), replacing what it would otherwise read from the environment. |
| [ILogger](https://imqueue.org/api/async-logger/latest/async-logger.ilogger/) | The logger contract shared across `@imqueue` — the four console methods, and nothing else. |
| [JsonArray](https://imqueue.org/api/async-logger/latest/async-logger.jsonarray/) | A JSON array — any number of [AnyJson](https://imqueue.org/api/async-logger/latest/async-logger.anyjson/) values. |
| [JsonObject](https://imqueue.org/api/async-logger/latest/async-logger.jsonobject/) | A JSON object — string keys, [AnyJson](https://imqueue.org/api/async-logger/latest/async-logger.anyjson/) values. This is the type of the logger's default metadata. |
| [TransportOptions](https://imqueue.org/api/async-logger/latest/async-logger.transportoptions/) | One transport declaration — the shape of each element in the `LOGGER_TRANSPORTS` JSON array. |


## Variables


| Variable | Description |
| --- | --- |
| [\_default](https://imqueue.org/api/async-logger/latest/async-logger._default/) | A [Logger](https://imqueue.org/api/async-logger/latest/async-logger.logger/) configured from the environment, constructed at import time. |


## Type Aliases


| Type Alias | Description |
| --- | --- |
| [AnyJson](https://imqueue.org/api/async-logger/latest/async-logger.anyjson/) | Any value that survives `JSON.stringify` unchanged. |