@imqueue/async-logger 3.0.1 → 3.2.0

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.
  */
-import { Logger } from './src';
-export * from './src';
+/**
+ * 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

@@ -1,19 +1,3 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
 /*!
  * I'm Queue Software Project
  * Copyright (C) 2025  imqueue.com <support@imqueue.com>
@@ -35,8 +19,55 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * purchase a proprietary commercial license. Please contact us at
  * <support@imqueue.com> to get commercial licensing options.
  */
-const src_1 = require("./src");
-__exportStar(require("./src"), exports);
-// noinspection JSUnusedGlobalSymbols
-exports.default = new src_1.Logger();
+/**
+ * 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.0.1",
+  "version": "3.2.0",
   "description": "Configurable async logger over winston for @imqueue services",
   "keywords": [
     "logger",
@@ -34,11 +34,10 @@
   "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": {
-    "@imqueue/core": "^3.1.1",
     "winston": "^3.19.0",
     "winston-transport": "^4.9.0"
   },
@@ -49,5 +48,16 @@
     "typescript": "^7.0.2"
   },
   "main": "index.js",
-  "types": "index.d.ts"
+  "types": "index.d.ts",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  }
 }

package/signatures/version1/cla.json

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

package/src/Logger.d.ts

@@ -19,75 +19,140 @@
  * purchase a proprietary commercial license. Please contact us at
  * <support@imqueue.com> to get commercial licensing options.
  */
-import { ILogger, JsonObject } from '@imqueue/core';
-import { TransportOptions } from './TransportOptions';
+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;
 }