@imqueue/async-logger 3.1.0 → 3.2.1

package/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to @imqueue
+
+Thanks for your interest in improving @imqueue! Contributions of all kinds are
+welcome — bug fixes, features, tests, and documentation.
+
+## Contribution terms — please read first
+
+@imqueue is **dual-licensed**: it is free to everyone under **GPL-3.0**, and it is
+also offered under **commercial licenses** for closed-source use. To make that
+sustainable, contributions are accepted under the
+**[@imqueue Contribution Terms](./CONTRIBUTION-TERMS.md)**.
+
+**By opening a pull request — or otherwise contributing — you agree to those
+terms.** In short:
+
+- You **keep the copyright** in your contribution.
+- Your contribution stays available to everyone under **GPL-3.0**.
+- You grant the project owner the right to **also license your contribution
+  commercially**, royalty-free — you will not receive a fee for it.
+
+**If you do not agree, please do not contribute.** Read the full text in
+[CONTRIBUTION-TERMS.md](./CONTRIBUTION-TERMS.md).
+
+## How to contribute
+
+1. **Open an issue first** for anything non-trivial, so we can agree on the
+   approach before you invest time.
+2. **Fork** the repository and create a topic branch from `master`
+   (e.g. `fix/redis-reconnect` or `feat/lock-timeout`).
+3. **Make your change**, following the existing code style. Keep pull requests
+   focused — one logical change per PR.
+4. **Add or update tests** so the change is covered, and make sure the full suite
+   passes locally:
+   ```bash
+   npm ci
+   npm test
+   ```
+5. **Write clear commit messages** and a descriptive PR title and summary.
+6. **Open the pull request** against `master` and fill in the PR template,
+   including the contribution-terms checkbox.
+
+## Guidelines
+
+- Match the existing TypeScript style and formatting already used in the file you
+  are editing.
+- Keep public API changes documented (doc-blocks / README as appropriate).
+- Be respectful and constructive in reviews and discussions.
+
+## Reporting security issues
+
+Please **do not** open a public issue for security vulnerabilities. Report them
+privately to the maintainers (see the repository's security policy or contact
+address) so they can be addressed responsibly.
+
+---
+
+Questions about the terms or a larger/corporate contribution? Reach out before you
+start and we'll help.

package/CONTRIBUTION-TERMS.md

@@ -0,0 +1,79 @@
+# @imqueue Contribution Terms (v1.0)
+
+These terms apply to every contribution to any repository of the **@imqueue**
+project — the packages published under the `@imqueue` npm scope and any repository
+in the imqueue GitHub organisation.
+
+**By submitting a contribution — opening a pull request, pushing a commit, sending
+a patch, or otherwise offering work for inclusion — you accept these terms in
+full. If you do not agree with them, do not contribute.**
+
+In these terms, **"Owner"** means Mykhailo Stadnyk, together with his successors,
+assigns and any entity he controls (including VaryLogic s.r.o.), and
+**"Contribution"** means any work of authorship — code, documentation or other
+material — you submit to an @imqueue repository.
+
+## 1. What you grant
+
+You grant the Owner a **perpetual, worldwide, irrevocable, royalty-free,
+non-exclusive, transferable and sublicensable** license to use, reproduce,
+modify, adapt, publish, distribute and otherwise exploit your Contribution and
+derivative works of it, **and to license and sub-license it under any terms the
+Owner chooses — including commercial and proprietary (closed-source) licenses,
+without any obligation to release source code.**
+
+In plain terms: the Owner may include your Contribution in @imqueue and **sell
+commercial licenses that cover it**, alongside the open-source edition.
+
+## 2. No royalties, fees or compensation
+
+The rights above are granted **free of charge**. You **waive** any right to
+royalties, license fees, revenue share or any other compensation arising from the
+Owner's use or licensing of your Contribution, including its commercial licensing,
+and you agree not to seek any such payment now or in the future.
+
+## 3. You keep your copyright
+
+You **retain ownership** of the copyright in your Contribution and may use it
+elsewhere for your own purposes. You are granting the Owner the rights in Section
+1 — you are not required to transfer ownership. Your Contribution also remains
+available to the public under the repository's open-source license (GPL-3.0).
+
+## 4. Patent license
+
+You grant the Owner and all downstream recipients a perpetual, worldwide,
+royalty-free, irrevocable (except as stated) patent license to make, use, sell,
+offer to sell, import and transfer your Contribution, limited to the patent claims
+you can license that are necessarily infringed by your Contribution alone or in
+combination with the project. If you start patent litigation alleging the project
+or your Contribution infringes your patents, the patent license you received
+terminates.
+
+## 5. Your promises
+
+You confirm that: (a) the Contribution is your own original work, or you have the
+right to submit it and to grant these rights; (b) if your employer has any rights
+in your work, you have their permission to contribute, or they have waived those
+rights; and (c) you have identified any third-party material in your Contribution
+and its license.
+
+## 6. Moral rights
+
+To the maximum extent permitted by applicable law, you waive, or agree not to
+exercise, any moral rights in your Contribution in a way that would prevent the
+Owner from exercising the rights in Section 1. (Certain moral rights are
+inalienable under Slovak/EU law; nothing here purports to transfer those.)
+
+## 7. No obligation; "as is"
+
+The Owner is under no obligation to use your Contribution. It is provided **"as
+is"**, without warranty of any kind.
+
+## 8. Governing law
+
+These terms are governed by the laws of the Slovak Republic, without regard to its
+conflict-of-laws rules.
+
+---
+
+**If you do not agree to all of the above, do not contribute to @imqueue.**

package/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you believe you have found a security vulnerability in this `@imqueue` project (or
+any `@imqueue/*` package), please report it **privately** — do not open a public
+issue, pull request, or discussion for it.
+
+Two private channels:
+
+- **GitHub** — use *Security → Report a vulnerability* on this repository to open a
+  private advisory (preferred; it keeps the report and the fix coordinated in one
+  place).
+- **Email** — <support@imqueue.com> with the details below.
+
+Please include:
+
+- the affected package or repository and version(s);
+- a description of the issue and its impact;
+- steps to reproduce, or a proof of concept, where possible.
+
+## What to expect
+
+- We aim to acknowledge a report within a few business days.
+- We'll confirm the issue, keep you updated on progress, and coordinate a fix and a
+  disclosure timeline with you.
+- Once a fix is released we'll credit the reporter in the advisory unless you prefer
+  to remain anonymous.
+
+## Supported versions
+
+Security fixes land on the latest published release line of each `@imqueue/*`
+package on npm. Please make sure you can reproduce an issue against the current
+release before reporting.
+
+## Scope
+
+The `@imqueue` framework is open source under GPL-3.0. This policy covers the code
+in the `@imqueue/*` packages and the project repositories. Vulnerabilities in
+third-party dependencies should be reported to those projects, though we're glad to
+help coordinate an upgrade.

package/index.d.ts

@@ -19,7 +19,55 @@
  * purchase a proprietary commercial license. Please contact us at
  * <support@imqueue.com> to get commercial licensing options.
  */
+/**
+ * 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 {@link 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.
+ *
+ * @packageDocumentation
+ */
 import { Logger } from './src/index.js';
 export * from './src/index.js';
+/**
+ * A {@link Logger} configured from the environment, constructed at import time.
+ *
+ * @remarks
+ * Shared by every module that imports it, which is normally what you want — one
+ * set of transports per process. Construct {@link Logger} directly instead when
+ * you need different metadata or transports for a particular subsystem.
+ *
+ * Because it is built at import time, `LOGGER_TRANSPORTS` and `LOGGER_METADATA`
+ * must already be set when this module is first imported; changing them later has
+ * no effect on this instance.
+ */
 declare const _default: Logger;
 export default _default;

package/index.js

@@ -19,7 +19,55 @@
  * purchase a proprietary commercial license. Please contact us at
  * <support@imqueue.com> to get commercial licensing options.
  */
+/**
+ * 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 {@link 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.
+ *
+ * @packageDocumentation
+ */
 import { Logger } from './src/index.js';
 export * from './src/index.js';
+/**
+ * A {@link Logger} configured from the environment, constructed at import time.
+ *
+ * @remarks
+ * Shared by every module that imports it, which is normally what you want — one
+ * set of transports per process. Construct {@link Logger} directly instead when
+ * you need different metadata or transports for a particular subsystem.
+ *
+ * Because it is built at import time, `LOGGER_TRANSPORTS` and `LOGGER_METADATA`
+ * must already be set when this module is first imported; changing them later has
+ * no effect on this instance.
+ */
 export default new Logger();
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imqueue/async-logger",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Configurable async logger over winston for @imqueue services",
   "keywords": [
     "logger",
@@ -34,7 +34,7 @@
   "bugs": {
     "url": "https://github.com/imqueue/async-logger/issues"
   },
-  "homepage": "https://github.com/imqueue/async-logger",
+  "homepage": "https://imqueue.org/",
   "author": "imqueue.com <support@imqueue.com> (https://imqueue.com)",
   "license": "GPL-3.0-only",
   "dependencies": {

package/signatures/version1/cla.json

@@ -0,0 +1,3 @@
+{
+   "signedContributors": []
+}

package/src/Logger.d.ts

@@ -21,73 +21,138 @@
  */
 import { type ILogger, type JsonObject } from './types.js';
 import { type TransportOptions } from './TransportOptions.js';
+/**
+ * Explicit configuration for a {@link Logger}, replacing what it would otherwise
+ * read from the environment.
+ *
+ * @remarks
+ * Both fields are read independently: pass only `metadata` and the transports
+ * still come from `LOGGER_TRANSPORTS`, and vice versa. Passing an empty
+ * `transports` array is not the same as omitting it — an empty array means
+ * "console only", while omitting it falls back to the environment.
+ */
 export interface AsyncLoggerOptions {
+    /**
+     * Transports to log through. Each entry is created and attached at
+     * construction time; entries with `enabled: false` are skipped.
+     */
     transports: TransportOptions[];
+    /**
+     * Fields attached to every record sent to a transport, such as a source or
+     * environment tag. Does not affect console output.
+     */
     metadata: JsonObject;
 }
 /**
- * Class Logger
+ * Logger that writes to the console without blocking the caller and forwards the
+ * same records to any configured winston transports.
+ *
+ * @remarks
+ * Implements {@link ILogger}, so it drops into anything in `@imqueue` that accepts
+ * a logger — `IMQClient`, `IMQService`, `RedisCache` — replacing the default
+ * synchronous console.
+ *
+ * Console output is scheduled with `setTimeout` rather than written inline. That
+ * is the point of the package: a service logging heavily does not pay for it on
+ * the request path. It also means ordering against synchronous code is not
+ * guaranteed, and output queued at the moment of `process.exit()` is lost.
+ *
+ * Transports are optional. Constructed with none — the default when
+ * `LOGGER_TRANSPORTS` is unset — this behaves as an async console logger and
+ * never touches winston.
+ *
+ * @example
+ * ```typescript
+ * import { Logger } from '@imqueue/async-logger';
+ *
+ * // configured from LOGGER_TRANSPORTS / LOGGER_METADATA
+ * const logger = new Logger();
+ *
+ * // or explicitly, e.g. to tag one subsystem differently
+ * const audit = new Logger({
+ *     transports: [{ type: 'file', options: { filename: 'audit.log' }, enabled: true }],
+ *     metadata: { subsystem: 'audit' },
+ * });
+ *
+ * audit.info('user %s signed in', userId);
+ * ```
  */
 export declare class Logger implements ILogger {
     /**
-     * Asynchronous console async-logger
-     *
-     * @type {ILogger}
+     * Console bound through `setTimeout`, so every write is deferred to a later
+     * tick instead of blocking the caller.
      */
     private static readonly console;
     /**
-     * @description
-     * Configuring options of async-logger
+     * Builds the winston options every transport shares: JSON formatting, the
+     * given (or environment-derived) default metadata, and `exitOnError: false`
+     * so a transport failure never takes the process down.
      *
-     * @returns {LoggerOptions}
+     * @param metadata - fields to attach to every record; falls back to
+     *                   `LOGGER_METADATA` when omitted
+     * @returns winston logger options
      */
     private static getLoggerOptions;
     /**
-     * Winston based async-logger having different logging transports
-     *
-     * @type {WinstonLogger}
+     * The winston logger the transports are attached to. Left undefined when no
+     * enabled transport was configured, which is how console-only mode is
+     * represented — every method checks it before forwarding.
      */
     private readonly logger?;
     /**
-     * Logger Ctor
-     *
-     * @constructor
-     * @param {AsyncLoggerOptions} options
+     * @param options - explicit transports and metadata. Omit either half and it
+     *                  is read from `LOGGER_TRANSPORTS` / `LOGGER_METADATA`; omit
+     *                  the argument entirely and both are.
+     * @throws TypeError if the environment config is not valid JSON, or names a
+     *         transport type other than `file` or `http`
      */
     constructor(options?: AsyncLoggerOptions);
     /**
-     * Logs given arguments to configured async-logger destinations and to stdout
-     * with log level = LOG
+     * Logs to the console and to every configured transport.
      *
-     * @param {...*[]} args
+     * @remarks
+     * Reaches transports at winston's `info` level — there is no distinct `log`
+     * level — so records from here and from {@link Logger.info} are
+     * indistinguishable once shipped. They differ only in the console method
+     * used. Pick by the destination you care about.
+     *
+     * @param args - `console.log`-style arguments; the first may be a format
+     *               string with `%s`/`%d`/`%j` placeholders for the rest
      */
     log(...args: any[]): void;
     /**
-     * Logs given arguments to configured async-logger destinations and to stdout
-     * with log level = INFO
+     * Logs at INFO level — routine progress worth keeping.
      *
-     * @param {...*[]} args
+     * @param args - `console.info`-style arguments; the first may be a format
+     *               string with `%s`/`%d`/`%j` placeholders for the rest
      */
     info(...args: any[]): void;
     /**
-     * Logs given arguments to configured async-logger destinations and to stderr
-     * with log level = WARN
+     * Logs at WARN level — something recovered from, but worth seeing.
      *
-     * @param {...*[]} args
+     * @param args - `console.warn`-style arguments; the first may be a format
+     *               string with `%s`/`%d`/`%j` placeholders for the rest
      */
     warn(...args: any[]): void;
     /**
-     * Logs given arguments to configured async-logger destinations and to stderr
-     * with log level = ERROR
+     * Logs at ERROR level.
+     *
+     * @remarks
+     * Pass an `Error` and it is formatted like the console would — including the
+     * stack. Passing `error.stack` explicitly is the usual choice when the record
+     * has to stay one line for a log shipper.
      *
-     * @param {...*[]} args
+     * @param args - `console.error`-style arguments; the first may be a format
+     *               string with `%s`/`%d`/`%j` placeholders for the rest
      */
     error(...args: any[]): void;
     /**
-     * Configuring transports of async-logger
+     * Creates and attaches each enabled transport from the given config.
      *
-     * @param {TransportOptions[]} config - configuration for transports from
-     *                             environment variables
+     * @param config - transport definitions, from {@link AsyncLoggerOptions} or
+     *                 parsed out of `LOGGER_TRANSPORTS`
+     * @throws TypeError if `config` is not an array, or an enabled entry names a
+     *         transport type other than `file` or `http`
      */
     private setupLogger;
 }

package/src/Logger.js

@@ -24,13 +24,43 @@ import { createLogger, format, Logger as WinstonLogger, } from 'winston';
 import { buildMessage, defaultMetadata, getTransport, transportsConfig, } from './helpers/index.js';
 import {} from './TransportOptions.js';
 /**
- * Class Logger
+ * Logger that writes to the console without blocking the caller and forwards the
+ * same records to any configured winston transports.
+ *
+ * @remarks
+ * Implements {@link ILogger}, so it drops into anything in `@imqueue` that accepts
+ * a logger — `IMQClient`, `IMQService`, `RedisCache` — replacing the default
+ * synchronous console.
+ *
+ * Console output is scheduled with `setTimeout` rather than written inline. That
+ * is the point of the package: a service logging heavily does not pay for it on
+ * the request path. It also means ordering against synchronous code is not
+ * guaranteed, and output queued at the moment of `process.exit()` is lost.
+ *
+ * Transports are optional. Constructed with none — the default when
+ * `LOGGER_TRANSPORTS` is unset — this behaves as an async console logger and
+ * never touches winston.
+ *
+ * @example
+ * ```typescript
+ * import { Logger } from '@imqueue/async-logger';
+ *
+ * // configured from LOGGER_TRANSPORTS / LOGGER_METADATA
+ * const logger = new Logger();
+ *
+ * // or explicitly, e.g. to tag one subsystem differently
+ * const audit = new Logger({
+ *     transports: [{ type: 'file', options: { filename: 'audit.log' }, enabled: true }],
+ *     metadata: { subsystem: 'audit' },
+ * });
+ *
+ * audit.info('user %s signed in', userId);
+ * ```
  */
 export class Logger {
     /**
-     * Asynchronous console async-logger
-     *
-     * @type {ILogger}
+     * Console bound through `setTimeout`, so every write is deferred to a later
+     * tick instead of blocking the caller.
      */
     static console = {
         // oxlint-disable-next-line no-console -- forwarding is the API here
@@ -40,10 +70,13 @@ export class Logger {
         error: (...args) => setTimeout(() => console.error(...args)),
     };
     /**
-     * @description
-     * Configuring options of async-logger
+     * Builds the winston options every transport shares: JSON formatting, the
+     * given (or environment-derived) default metadata, and `exitOnError: false`
+     * so a transport failure never takes the process down.
      *
-     * @returns {LoggerOptions}
+     * @param metadata - fields to attach to every record; falls back to
+     *                   `LOGGER_METADATA` when omitted
+     * @returns winston logger options
      */
     static getLoggerOptions(metadata) {
         return {
@@ -53,16 +86,17 @@ export class Logger {
         };
     }
     /**
-     * Winston based async-logger having different logging transports
-     *
-     * @type {WinstonLogger}
+     * The winston logger the transports are attached to. Left undefined when no
+     * enabled transport was configured, which is how console-only mode is
+     * represented — every method checks it before forwarding.
      */
     logger;
     /**
-     * Logger Ctor
-     *
-     * @constructor
-     * @param {AsyncLoggerOptions} options
+     * @param options - explicit transports and metadata. Omit either half and it
+     *                  is read from `LOGGER_TRANSPORTS` / `LOGGER_METADATA`; omit
+     *                  the argument entirely and both are.
+     * @throws TypeError if the environment config is not valid JSON, or names a
+     *         transport type other than `file` or `http`
      */
     constructor(options) {
         const opts = Logger.getLoggerOptions((options || {}).metadata);
@@ -73,10 +107,16 @@ export class Logger {
         }
     }
     /**
-     * Logs given arguments to configured async-logger destinations and to stdout
-     * with log level = LOG
+     * Logs to the console and to every configured transport.
      *
-     * @param {...*[]} args
+     * @remarks
+     * Reaches transports at winston's `info` level — there is no distinct `log`
+     * level — so records from here and from {@link Logger.info} are
+     * indistinguishable once shipped. They differ only in the console method
+     * used. Pick by the destination you care about.
+     *
+     * @param args - `console.log`-style arguments; the first may be a format
+     *               string with `%s`/`%d`/`%j` placeholders for the rest
      */
     log(...args) {
         Logger.console.log(...args);
@@ -85,10 +125,10 @@ export class Logger {
         }
     }
     /**
-     * Logs given arguments to configured async-logger destinations and to stdout
-     * with log level = INFO
+     * Logs at INFO level — routine progress worth keeping.
      *
-     * @param {...*[]} args
+     * @param args - `console.info`-style arguments; the first may be a format
+     *               string with `%s`/`%d`/`%j` placeholders for the rest
      */
     info(...args) {
         Logger.console.info(...args);
@@ -97,10 +137,10 @@ export class Logger {
         }
     }
     /**
-     * Logs given arguments to configured async-logger destinations and to stderr
-     * with log level = WARN
+     * Logs at WARN level — something recovered from, but worth seeing.
      *
-     * @param {...*[]} args
+     * @param args - `console.warn`-style arguments; the first may be a format
+     *               string with `%s`/`%d`/`%j` placeholders for the rest
      */
     warn(...args) {
         Logger.console.warn(...args);
@@ -109,10 +149,15 @@ export class Logger {
         }
     }
     /**
-     * Logs given arguments to configured async-logger destinations and to stderr
-     * with log level = ERROR
+     * Logs at ERROR level.
+     *
+     * @remarks
+     * Pass an `Error` and it is formatted like the console would — including the
+     * stack. Passing `error.stack` explicitly is the usual choice when the record
+     * has to stay one line for a log shipper.
      *
-     * @param {...*[]} args
+     * @param args - `console.error`-style arguments; the first may be a format
+     *               string with `%s`/`%d`/`%j` placeholders for the rest
      */
     error(...args) {
         Logger.console.error(...args);
@@ -121,10 +166,12 @@ export class Logger {
         }
     }
     /**
-     * Configuring transports of async-logger
+     * Creates and attaches each enabled transport from the given config.
      *
-     * @param {TransportOptions[]} config - configuration for transports from
-     *                             environment variables
+     * @param config - transport definitions, from {@link AsyncLoggerOptions} or
+     *                 parsed out of `LOGGER_TRANSPORTS`
+     * @throws TypeError if `config` is not an array, or an enabled entry names a
+     *         transport type other than `file` or `http`
      */
     setupLogger(config) {
         if (!config || !Array.isArray(config)) {
@@ -135,6 +182,13 @@ export class Logger {
                 continue;
             }
             const transport = getTransport(options.type, options.options);
+            // getTransport() yields nothing for a type it does not know. Report
+            // the offending type here: winston would otherwise reject the null
+            // with "Invalid transport, must be an object with a log method",
+            // which names neither the type nor the config it came from.
+            if (!transport) {
+                throw new TypeError(`Logger: unknown transport type "${options.type}", expected "file" or "http"!`);
+            }
             // the constructor always creates the winston logger before
             // calling setupLogger(), the optional chaining only satisfies
             // strict property-initialization analysis

package/src/TransportOptions.d.ts

@@ -21,10 +21,44 @@
  */
 import { type LoggerOptions } from 'winston';
 /**
- * Interface IConfig
+ * One transport declaration — the shape of each element in the
+ * `LOGGER_TRANSPORTS` JSON array.
+ *
+ * @example
+ * ```json
+ * {
+ *     "type": "http",
+ *     "options": {
+ *         "ssl": true,
+ *         "port": 443,
+ *         "host": "http-intake.logs.datadoghq.com",
+ *         "path": "/v1/input/<API_KEY>"
+ *     },
+ *     "enabled": true
+ * }
+ * ```
  */
 export interface TransportOptions {
+    /**
+     * Which transport to create: `'file'` or `'http'`. Any other value is
+     * rejected at construction time.
+     */
     type: string;
+    /**
+     * Options handed to the winston transport constructor — `filename` for
+     * `file`, `host`/`port`/`path`/`ssl` for `http`.
+     *
+     * @remarks
+     * Typed as winston's `LoggerOptions` for historical reasons, which is wider
+     * than what is actually accepted here. Treat it as `FileTransportOptions` or
+     * `HttpTransportOptions` according to `type`; the declared type will not
+     * catch a mismatch for you.
+     */
     options: LoggerOptions;
+    /**
+     * Whether to attach this transport. A `false` entry is skipped entirely, so
+     * a transport can be left in the config and switched off per environment
+     * rather than deleted.
+     */
     enabled: boolean;
 }

package/src/helpers/env.d.ts

@@ -22,23 +22,46 @@
 import { type JsonObject } from '../types.js';
 import { type TransportOptions } from '../TransportOptions.js';
 /**
- * Retrieve package name and version from package.json of running service
+ * Reads the running service's own name and version, used to expand the `%name`
+ * and `%version` placeholders in the logger environment variables.
  *
- * @returns {name: string, value: string} - return package name and version
+ * @remarks
+ * Resolved from `package.json` in the process's CURRENT WORKING DIRECTORY, not
+ * from this package's location. A service started from a different directory
+ * therefore reports whatever it finds there, and one started somewhere with no
+ * `package.json` falls back to `{ name: 'logger', version: '' }` rather than
+ * failing.
+ *
+ * @returns the service name and version, or the fallback pair
  */
 export declare function pkg(): {
     name: string;
     version: string;
 };
 /**
- * Used for retrieve transport config from environment variables
+ * Parses the transport declarations out of `LOGGER_TRANSPORTS`, expanding
+ * `%name` and `%version` first.
+ *
+ * @remarks
+ * An unset variable yields an empty array, which the {@link Logger} treats as
+ * console-only rather than as an error — the normal local-development case.
+ * Malformed JSON, by contrast, throws: a config typo should fail loudly at
+ * start-up rather than silently drop a production log destination.
  *
- * @returns {TransportOptions[]}
+ * @returns the declared transports, or an empty array when unset
+ * @throws TypeError if the variable is set but not parseable as JSON
  */
 export declare function transportsConfig(): TransportOptions[];
 /**
- * Returns default metadata, configured by environment variables
+ * Parses the default record metadata out of `LOGGER_METADATA`, expanding `%name`
+ * and `%version` first.
+ *
+ * @remarks
+ * These fields are attached to every record sent to a transport — a source tag,
+ * an environment name, a hostname — and are what makes records from several
+ * services distinguishable at the collector. Console output is unaffected.
  *
- * @returns {JsonObject}
+ * @returns the parsed metadata, or an empty object when unset
+ * @throws TypeError if the variable is set but not parseable as JSON
  */
 export declare function defaultMetadata(): JsonObject;

package/src/helpers/env.js

@@ -26,9 +26,17 @@ import {} from '../TransportOptions.js';
 const RX_NAME = /%name/g;
 const RX_VERSION = /%version/g;
 /**
- * Retrieve package name and version from package.json of running service
+ * Reads the running service's own name and version, used to expand the `%name`
+ * and `%version` placeholders in the logger environment variables.
  *
- * @returns {name: string, value: string} - return package name and version
+ * @remarks
+ * Resolved from `package.json` in the process's CURRENT WORKING DIRECTORY, not
+ * from this package's location. A service started from a different directory
+ * therefore reports whatever it finds there, and one started somewhere with no
+ * `package.json` falls back to `{ name: 'logger', version: '' }` rather than
+ * failing.
+ *
+ * @returns the service name and version, or the fallback pair
  */
 export function pkg() {
     const pkgPath = resolve(process.cwd(), 'package.json');
@@ -38,9 +46,17 @@ export function pkg() {
     return { name, version };
 }
 /**
- * Used for retrieve transport config from environment variables
+ * Parses the transport declarations out of `LOGGER_TRANSPORTS`, expanding
+ * `%name` and `%version` first.
+ *
+ * @remarks
+ * An unset variable yields an empty array, which the {@link Logger} treats as
+ * console-only rather than as an error — the normal local-development case.
+ * Malformed JSON, by contrast, throws: a config typo should fail loudly at
+ * start-up rather than silently drop a production log destination.
  *
- * @returns {TransportOptions[]}
+ * @returns the declared transports, or an empty array when unset
+ * @throws TypeError if the variable is set but not parseable as JSON
  */
 export function transportsConfig() {
     const { name, version } = pkg();
@@ -54,9 +70,16 @@ export function transportsConfig() {
     }
 }
 /**
- * Returns default metadata, configured by environment variables
+ * Parses the default record metadata out of `LOGGER_METADATA`, expanding `%name`
+ * and `%version` first.
+ *
+ * @remarks
+ * These fields are attached to every record sent to a transport — a source tag,
+ * an environment name, a hostname — and are what makes records from several
+ * services distinguishable at the collector. Console output is unaffected.
  *
- * @returns {JsonObject}
+ * @returns the parsed metadata, or an empty object when unset
+ * @throws TypeError if the variable is set but not parseable as JSON
  */
 export function defaultMetadata() {
     const { name, version } = pkg();

package/src/helpers/message.d.ts

@@ -1,7 +1,13 @@
 /**
- * Format message like console log
+ * 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.
  *
- * @param {...*[]} args
- * @returns {string}
+ * @remarks
+ * MUTATES the array it is given — the first element is shifted off to serve as
+ * the format string. Pass a copy if you need the original afterwards.
+ *
+ * @param args - the logging arguments, first one treated as the format string
+ * @returns the formatted message
  */
 export declare function buildMessage(args: any[]): string;

package/src/helpers/message.js

@@ -21,10 +21,16 @@
  */
 import { format } from 'util';
 /**
- * Format message like console log
+ * 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.
  *
- * @param {...*[]} args
- * @returns {string}
+ * @remarks
+ * MUTATES the array it is given — the first element is shifted off to serve as
+ * the format string. Pass a copy if you need the original afterwards.
+ *
+ * @param args - the logging arguments, first one treated as the format string
+ * @returns the formatted message
  */
 export function buildMessage(args) {
     return format(args.shift(), ...args);

package/src/helpers/transport.d.ts

@@ -1,11 +1,16 @@
 import type Transport from 'winston-transport';
 import type { FileTransportOptions, HttpTransportOptions } from 'winston/lib/winston/transports/index.js';
 /**
- * Used for get configured transport by type
+ * Constructs a winston transport of the named type.
  *
- * @param {string} type - transport type
- * @param {FileTransportOptions | HttpTransportOptions} options -
- *   options for configure transport
- * @returns {Transport}
+ * @remarks
+ * Only `'file'` and `'http'` are supported. Anything else returns nothing —
+ * despite the declared return type, which is a `Transport` cast rather than a
+ * guarantee. {@link Logger} checks for that and reports the offending type; a
+ * direct caller must check too.
+ *
+ * @param type - `'file'` or `'http'`
+ * @param options - options for the winston transport constructor
+ * @returns the transport, or nothing if the type is not recognised
  */
 export declare function getTransport(type: string, options: FileTransportOptions | HttpTransportOptions): Transport;

package/src/helpers/transport.js

@@ -21,12 +21,17 @@
  */
 import { transports } from 'winston';
 /**
- * Used for get configured transport by type
+ * Constructs a winston transport of the named type.
  *
- * @param {string} type - transport type
- * @param {FileTransportOptions | HttpTransportOptions} options -
- *   options for configure transport
- * @returns {Transport}
+ * @remarks
+ * Only `'file'` and `'http'` are supported. Anything else returns nothing —
+ * despite the declared return type, which is a `Transport` cast rather than a
+ * guarantee. {@link Logger} checks for that and reports the offending type; a
+ * direct caller must check too.
+ *
+ * @param type - `'file'` or `'http'`
+ * @param options - options for the winston transport constructor
+ * @returns the transport, or nothing if the type is not recognised
  */
 export function getTransport(type, options) {
     let transportInstance = null;

package/src/types.d.ts

@@ -26,46 +26,40 @@
  * assignment-compatible with code written against the core interfaces.
  */
 /**
- * Represents any JSON-serializable value
+ * Any value that survives `JSON.stringify` unchanged.
+ *
+ * @remarks
+ * A structural copy of the type in `@imqueue/core`, declared here so the logger
+ * needs no runtime dependency on the queue library. The shapes match exactly, so
+ * values remain assignable in both directions.
  */
 export type AnyJson = boolean | number | string | null | undefined | JsonArray | JsonObject;
 /**
- * Represents JSON serializable object
+ * A JSON object — string keys, {@link AnyJson} values. This is the type of the
+ * logger's default metadata.
  */
 export interface JsonObject {
     [key: string]: AnyJson;
 }
-/**
- * Represents JSON-serializable array
- */
+/** A JSON array — any number of {@link AnyJson} values. */
 export interface JsonArray extends Array<AnyJson> {
 }
 /**
- * Logger interface
+ * The logger contract shared across `@imqueue` — the four console methods, and
+ * nothing else.
+ *
+ * @remarks
+ * Deliberately console-shaped, so `console` itself satisfies it and any
+ * `@imqueue` component taking a logger accepts either that or a {@link Logger}
+ * with no adapter. Implement it to route the framework's own output elsewhere.
  */
 export interface ILogger {
-    /**
-     * Log level function
-     *
-     * @param {...unknown[]} args
-     */
+    /** Logs at the default level. */
     log(...args: unknown[]): void;
-    /**
-     * Info level function
-     *
-     * @param {...unknown[]} args
-     */
+    /** Logs at INFO level. */
     info(...args: unknown[]): void;
-    /**
-     * Warning level function
-     *
-     * @param {...unknown[]} args
-     */
+    /** Logs at WARN level. */
     warn(...args: unknown[]): void;
-    /**
-     * Error level function
-     *
-     * @param {...unknown[]} args
-     */
+    /** Logs at ERROR level. */
     error(...args: unknown[]): void;
 }