@imqueue/job 2.0.6 → 3.0.1

package/.oxfmtrc.json

@@ -0,0 +1,9 @@
+{
+  "singleQuote": true,
+  "tabWidth": 4,
+  "printWidth": 80,
+  "semi": true,
+  "trailingComma": "all",
+  "arrowParens": "avoid",
+  "bracketSpacing": true
+}

package/.oxlintrc.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "categories": {
+    "correctness": "error"
+  },
+  "rules": {
+    "no-debugger": "error",
+    "no-console": ["warn", { "allow": ["warn", "error", "info"] }],
+    "no-unused-vars": "warn"
+  },
+  "ignorePatterns": [
+    "**/*.js",
+    "**/*.d.ts",
+    "docs/",
+    "coverage/",
+    ".nyc_output/",
+    ".agent-out/",
+    "node_modules/"
+  ]
+}

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,40 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you believe you have found a security vulnerability in **@imqueue/job** (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 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. Vulnerabilities in third-party dependencies should be
+reported to those projects, though we're glad to help coordinate an upgrade.

package/index.d.ts

@@ -21,7 +21,7 @@
  * purchase a proprietary commercial license. Please contact us at
  * <support@imqueue.com> to get commercial licensing options.
  */
-import { ILogger, IMessageQueue } from '@imqueue/core';
+import { type ILogger, type IMessageQueue } from '@imqueue/core';
 /**
  * Job queues options
  */
@@ -184,7 +184,7 @@ export interface AnyJobQueuePublisher<T, U> {
 export declare abstract class BaseJobQueue<T, U> implements AnyJobQueue<T> {
     protected options: JobQueueOptions;
     protected imq: IMessageQueue;
-    protected handler: JobQueuePopHandler<U>;
+    protected handler?: JobQueuePopHandler<U>;
     readonly logger: ILogger;
     protected constructor(options: JobQueueOptions);
     /**

package/index.js

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.JobQueueWorker = exports.JobQueuePublisher = exports.BaseJobQueue = void 0;
 /*!
  * Job Queue for @imqueue framework
  *
@@ -24,11 +21,15 @@ exports.JobQueueWorker = exports.JobQueuePublisher = exports.BaseJobQueue = void
  * purchase a proprietary commercial license. Please contact us at
  * <support@imqueue.com> to get commercial licensing options.
  */
-const core_1 = require("@imqueue/core");
+import IMQ, { IMQMode, } from '@imqueue/core';
 /**
  * Abstract job queue, handles base implementations of AnyJobQueue interface.
  */
-class BaseJobQueue {
+export class BaseJobQueue {
+    options;
+    imq;
+    handler;
+    logger;
     constructor(options) {
         this.options = options;
         this.logger = options.logger || console;
@@ -68,7 +69,6 @@ class BaseJobQueue {
         await this.imq.destroy();
     }
 }
-exports.BaseJobQueue = BaseJobQueue;
 /**
  * Creates and returns IMQOptions derived from a given JobQueueOptions
  *
@@ -83,10 +83,10 @@ function toIMQOptions(options, logger) {
         username: options.username,
         password: options.password,
         cleanup: false,
-        safeDelivery: typeof options.safe === 'undefined'
-            ? true : options.safe,
+        safeDelivery: typeof options.safe === 'undefined' ? true : options.safe,
         safeDeliveryTtl: typeof options.safeLockTtl === 'undefined'
-            ? 10000 : options.safeLockTtl,
+            ? 10000
+            : options.safeLockTtl,
         prefix: options.prefix || 'imq-job',
         verbose: options.verbose,
         verboseExtended: options.verboseExtended,
@@ -98,7 +98,7 @@ function toIMQOptions(options, logger) {
  * Implements simple scheduled job queue publisher. Job queue publisher is only
  * responsible for pushing queue messages.
  */
-class JobQueuePublisher extends BaseJobQueue {
+export class JobQueuePublisher extends BaseJobQueue {
     /**
      * Constructor. Instantiates new JobQueue instance.
      *
@@ -107,7 +107,7 @@ class JobQueuePublisher extends BaseJobQueue {
      */
     constructor(options) {
         super(options);
-        this.imq = core_1.default.create(options.name, toIMQOptions(options, this.logger), core_1.IMQMode.PUBLISHER);
+        this.imq = IMQ.create(options.name, toIMQOptions(options, this.logger), IMQMode.PUBLISHER);
     }
     /**
      * Pushes new job to this queue
@@ -118,17 +118,24 @@ class JobQueuePublisher extends BaseJobQueue {
      */
     push(job, options) {
         options = options || {};
-        this.imq.send(this.name, Object.assign(Object.assign({ job: job }, (options.ttl ? { expire: Date.now() + options.ttl } : {})), (options.delay ? { delay: options.delay } : {})), options.delay).catch(err => this.logger.log('[JobQueue] push error:', err));
+        this.imq
+            .send(this.name, {
+            job: job,
+            ...(options.ttl
+                ? { expire: Date.now() + options.ttl }
+                : {}),
+            ...(options.delay ? { delay: options.delay } : {}),
+        }, options.delay)
+            .catch(err => this.logger.log('[JobQueue] push error:', err));
         return this;
     }
 }
-exports.JobQueuePublisher = JobQueuePublisher;
 // noinspection JSUnusedGlobalSymbols
 /**
  * Implements simple scheduled job queue worker. Job queue worker is only
  * responsible for processing queue messages.
  */
-class JobQueueWorker extends BaseJobQueue {
+export class JobQueueWorker extends BaseJobQueue {
     /**
      * Constructor. Instantiates new JobQueue instance.
      *
@@ -137,7 +144,7 @@ class JobQueueWorker extends BaseJobQueue {
      */
     constructor(options) {
         super(options);
-        this.imq = core_1.default.create(options.name, toIMQOptions(options, this.logger), core_1.IMQMode.WORKER);
+        this.imq = IMQ.create(options.name, toIMQOptions(options, this.logger), IMQMode.WORKER);
     }
     /**
      * Sets up job handler, which is called when the job is popped from this
@@ -156,7 +163,7 @@ class JobQueueWorker extends BaseJobQueue {
             const { job, expire, delay } = message;
             let rescheduleDelay;
             try {
-                rescheduleDelay = this.handler(job);
+                rescheduleDelay = this.handler?.(job);
                 if (rescheduleDelay &&
                     typeof rescheduleDelay === 'object' &&
                     rescheduleDelay &&
@@ -179,7 +186,6 @@ class JobQueueWorker extends BaseJobQueue {
         return this;
     }
 }
-exports.JobQueueWorker = JobQueueWorker;
 // noinspection JSUnusedGlobalSymbols
 /**
  * Implements simple scheduled job queue. Job scheduling is optional. It may
@@ -188,7 +194,7 @@ exports.JobQueueWorker = JobQueueWorker;
  * the job is removed from a queue.
  * Supports graceful shutdown, if TERM or SIGINT is sent to the process.
  */
-class JobQueue extends BaseJobQueue {
+export default class JobQueue extends BaseJobQueue {
     /**
      * Constructor. Instantiates new JobQueue instance.
      *
@@ -197,7 +203,7 @@ class JobQueue extends BaseJobQueue {
      */
     constructor(options) {
         super(options);
-        this.imq = core_1.default.create(options.name, toIMQOptions(options, this.logger));
+        this.imq = IMQ.create(options.name, toIMQOptions(options, this.logger));
     }
     /**
      * Starts processing job queue. Throws if handler is not set before start.
@@ -236,5 +242,4 @@ class JobQueue extends BaseJobQueue {
         return JobQueueWorker.prototype.onPop.call(this, handler);
     }
 }
-exports.default = JobQueue;
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imqueue/job",
-  "version": "2.0.6",
+  "version": "3.0.1",
   "description": "Simple job queue",
   "keywords": [
     "message-queue",
@@ -13,17 +13,20 @@
     "json-message-queue"
   ],
   "scripts": {
-    "prepare": "./node_modules/.bin/tsc",
-    "show:test": "/usr/bin/env node -e \"import('open').then(open => open.default('file://`pwd`/coverage/index.html',{wait:false}));\"",
-    "test": "./node_modules/.bin/tsc && ./node_modules/.bin/nyc mocha && npm run show:test",
-    "clean-typedefs": "find . -name '*.d.ts' -not -wholename '*node_modules*' -not -wholename '*generator*' -type f -delete",
-    "clean-maps": "find . -name '*.js.map' -not -wholename '*node_modules*' -not -wholename '*generator*' -type f -delete",
-    "clean-js": "find . -name '*.js' -not -wholename '*node_modules*' -not -wholename '*generator*' -type f -delete",
+    "prepare": "npm run build",
+    "build": "npm run clean-compiled && tsc",
+    "lint": "oxlint",
+    "format": "oxfmt \"index.ts\" \"test/**/*.ts\"",
+    "format:check": "oxfmt --check \"index.ts\" \"test/**/*.ts\"",
+    "test": "npm run build && node --experimental-test-module-mocks --import ./test/mocks/index.js --test --test-timeout=15000 $(find test -name '*.spec.js')",
+    "test-coverage": "npm run build && node --experimental-test-module-mocks --enable-source-maps --import ./test/mocks/index.js --test --experimental-test-coverage --test-timeout=15000 $(find test -name '*.spec.js')",
+    "test-lcov": "npm run build && mkdir -p coverage && node --experimental-test-module-mocks --enable-source-maps --import ./test/mocks/index.js --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --test-timeout=15000 $(find test -name '*.spec.js'); node scripts/strip-comment-coverage.mjs coverage/lcov.info",
+    "clean-typedefs": "find . -name '*.d.ts' -not -wholename '*node_modules*' -type f -delete",
+    "clean-maps": "find . -name '*.js.map' -not -wholename '*node_modules*' -type f -delete",
+    "clean-js": "find . -name '*.js' -not -wholename '*node_modules*' -not -wholename '*scripts*' -type f -delete",
+    "clean-compiled": "npm run clean-js && npm run clean-typedefs && npm run clean-maps",
     "clean-tests": "rm -rf .nyc_output coverage",
-    "clean-doc": "rm -rf docs",
-    "clean-benchmark": "rm -rf benchmark-result",
-    "clean": "npm run clean-tests && npm run clean-typedefs && npm run clean-maps && npm run clean-js && npm run clean-doc && npm run clean-benchmark",
-    "doc": "rm -rf docs && typedoc  --excludePrivate --excludeExternals --hideGenerator --exclude \"**/+(test|node_modules|docs|coverage|benchmark|.nyc_output)/**/*\" --out ./docs . && /usr/bin/env node -e \"import('open').then(open => open.default('file://`pwd`/docs/index.html',{wait:false}))\""
+    "clean": "npm run clean-tests && npm run clean-compiled"
   },
   "repository": {
     "type": "git",
@@ -32,70 +35,32 @@
   "bugs": {
     "url": "https://github.com/imqueue/job/issues"
   },
-  "homepage": "https://imqueue.com/",
+  "homepage": "https://imqueue.org/",
   "author": "imqueue.com <support@imqueue.com> (https://imqueue.com)",
   "license": "GPL-3.0-only",
   "dependencies": {
-    "@imqueue/core": "^2.0.18"
+    "@imqueue/core": "^3.2.2"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.35.0",
-    "@types/chai": "^5.2.2",
-    "@types/mocha": "^10.0.10",
-    "@types/mock-require": "^3.0.0",
-    "@types/node": "^24.9.2",
-    "@types/sinon": "^17.0.4",
-    "@typescript-eslint/eslint-plugin": "^8.43.0",
-    "@typescript-eslint/parser": "^8.43.0",
-    "@typescript-eslint/typescript-estree": "^8.43.0",
-    "chai": "^6.0.1",
-    "eslint": "^9.35.0",
-    "globals": "^16.4.0",
-    "mocha": "^11.7.2",
-    "mocha-lcov-reporter": "^1.3.0",
-    "mock-require": "^3.0.3",
-    "npm-scripts-help": "^0.8.0",
-    "nyc": "^17.1.0",
-    "open": "^10.2.0",
-    "reflect-metadata": "^0.2.2",
-    "sinon": "^21.0.0",
-    "source-map-support": "^0.5.21",
-    "ts-node": "^10.9.2",
-    "typedoc": "^0.28.12",
-    "typescript": "^5.9.2",
-    "yargs": "^18.0.0"
+    "@types/node": "^24.9.1",
+    "oxfmt": "0.57.0",
+    "oxlint": "1.72.0",
+    "typescript": "^7.0.2"
   },
   "main": "index.js",
   "typescript": {
     "definitions": "index.d.ts"
   },
-  "mocha": {
-    "require": [
-      "ts-node/register",
-      "source-map-support/register"
-    ],
-    "recursive": true,
-    "bail": true,
-    "full-trace": true
+  "type": "module",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
   },
-  "nyc": {
-    "check-coverage": false,
-    "extension": [
-      ".ts"
-    ],
-    "exclude": [
-      "**/*.d.ts",
-      "**/test/**"
-    ],
-    "require": [
-      "ts-node/register"
-    ],
-    "reporter": [
-      "html",
-      "text",
-      "text-summary",
-      "lcovonly"
-    ]
+  "engines": {
+    "node": ">=22.12.0"
   }
 }

package/scripts/strip-comment-coverage.mjs

@@ -0,0 +1,472 @@
+/*!
+ * Coverage post-processor
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+
+/**
+ * Node's built-in coverage (`--experimental-test-coverage --enable-source-maps`)
+ * reports every non-code line of a `.ts` source as uncovered, because comment
+ * and blank lines have no source-map mappings and therefore fall outside every
+ * covered V8 byte-range. That paints the license header and each JSDoc block
+ * red in the HTML report and pushes per-file line% far below reality.
+ *
+ * Node's reporter also emits records that the (strict) genhtml LCOV 2.x tool
+ * rejects — function entries with `undefined` line numbers or synthetic,
+ * duplicated names (`<instance_members_initializer>`, and decorated methods all
+ * mis-named `has`/`get`), plus `BRDA:undefined,...` branch records. Left in,
+ * they produce a wall of warnings and a fatal "unexpected category" error.
+ *
+ * This script rewrites an lcov file in place: it drops the `DA`/`BRDA` records
+ * for lines that contain no executable code (comments and blank lines), drops
+ * all function records and malformed branch records, then recomputes the
+ * `LF`/`LH`/`BRF`/`BRH` totals. It uses the TypeScript scanner (already a dev
+ * dependency) to locate comments reliably — comment markers inside strings,
+ * template literals and regexes are not misdetected. The result renders in
+ * genhtml with accurate line + branch coverage and no warnings or errors.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+// TypeScript 7 (native port) no longer exposes the classic compiler API from
+// the package root — the lightweight scanner/AST primitives live under the
+// `typescript/unstable/ast` entry point (createSourceFile is gone entirely, so
+// import spans are located with the scanner rather than a parsed AST).
+import * as ts from 'typescript/unstable/ast';
+
+const lcovPath = process.argv[2] || 'coverage/lcov.info';
+
+if (!existsSync(lcovPath)) {
+    console.warn(`strip-comment-coverage: ${lcovPath} not found, skipping`);
+    process.exit(0);
+}
+
+/**
+ * Returns the set of 1-based line numbers in the given source that hold no
+ * executable code — i.e. blank lines and lines whose only content is a comment.
+ *
+ * @param {string} text
+ * @returns {Set<number>}
+ */
+function nonCodeLines(text) {
+    const commentChars = new Uint8Array(text.length);
+    const scanner = ts.createScanner(
+        ts.ScriptTarget.Latest,
+        /* skipTrivia */ false,
+        ts.LanguageVariant.Standard,
+    );
+
+    scanner.setText(text);
+
+    let token = scanner.scan();
+
+    while (token !== ts.SyntaxKind.EndOfFile) {
+        if (
+            token === ts.SyntaxKind.SingleLineCommentTrivia ||
+            token === ts.SyntaxKind.MultiLineCommentTrivia
+        ) {
+            const start = scanner.getTokenStart();
+            const end = scanner.getTokenEnd();
+
+            for (let i = start; i < end; i++) {
+                commentChars[i] = 1;
+            }
+        }
+
+        token = scanner.scan();
+    }
+
+    const lines = text.split('\n');
+    const result = new Set();
+    let pos = 0;
+
+    for (let ln = 0; ln < lines.length; ln++) {
+        const line = lines[ln];
+        let hasCode = false;
+
+        for (let i = 0; i < line.length; i++) {
+            const ch = line[i];
+
+            if (ch === ' ' || ch === '\t' || ch === '\r') {
+                continue;
+            }
+
+            if (!commentChars[pos + i]) {
+                hasCode = true;
+                break;
+            }
+        }
+
+        if (!hasCode) {
+            result.add(ln + 1);
+        }
+
+        pos += line.length + 1; // account for the split '\n'
+    }
+
+    return result;
+}
+
+/**
+ * Returns the set of 1-based lines occupied by top-level import statements.
+ * Imports compile to `require(...)` that runs on module load, so they are
+ * always executed, yet Node's source-mapped coverage frequently mis-reports
+ * them as uncovered (the mapping lands outside the covered byte-range). Treating
+ * them as non-coverable corrects that artifact rather than hiding real logic.
+ *
+ * @param {string} text
+ * @returns {Set<number>}
+ */
+function importLines(text) {
+    // TypeScript 7 dropped `createSourceFile`, so top-level import statements are
+    // located with the scanner: a top-level `import` keyword (depth 0, not the
+    // dynamic `import(...)` call nor `import.meta`) begins a declaration whose
+    // span reaches the terminating semicolon — both `import ... from '...'` and
+    // `import x = require('...')` end that way in this codebase.
+    const scanner = ts.createScanner(
+        ts.ScriptTarget.Latest,
+        /* skipTrivia */ true,
+        ts.LanguageVariant.Standard,
+    );
+
+    scanner.setText(text);
+
+    const lineStarts = ts.computeLineStarts(text);
+    // 0-based line holding `pos`: largest index with lineStarts[i] <= pos
+    const lineOf = pos => {
+        let lo = 0;
+        let hi = lineStarts.length - 1;
+
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+
+            if (lineStarts[mid] <= pos) {
+                lo = mid;
+            } else {
+                hi = mid - 1;
+            }
+        }
+
+        return lo;
+    };
+
+    const K = ts.SyntaxKind;
+    const result = new Set();
+    let depth = 0;
+    let token = scanner.scan();
+
+    while (token !== K.EndOfFile) {
+        if (
+            token === K.OpenBraceToken ||
+            token === K.OpenParenToken ||
+            token === K.OpenBracketToken
+        ) {
+            depth++;
+        } else if (
+            token === K.CloseBraceToken ||
+            token === K.CloseParenToken ||
+            token === K.CloseBracketToken
+        ) {
+            depth--;
+        } else if (depth === 0 && token === K.ImportKeyword) {
+            const start = scanner.getTokenStart();
+            let next = scanner.scan();
+
+            // `import(...)` dynamic call or `import.meta` — not a declaration
+            if (next === K.OpenParenToken || next === K.DotToken) {
+                token = next;
+                continue;
+            }
+
+            // consume to the terminating semicolon at bracket depth 0
+            let inner = 0;
+            let end = scanner.getTokenEnd();
+
+            while (next !== K.EndOfFile) {
+                if (next === K.OpenBraceToken || next === K.OpenParenToken) {
+                    inner++;
+                } else if (
+                    next === K.CloseBraceToken ||
+                    next === K.CloseParenToken
+                ) {
+                    inner--;
+                } else if (next === K.SemicolonToken && inner === 0) {
+                    end = scanner.getTokenEnd();
+                    break;
+                }
+
+                end = scanner.getTokenEnd();
+                next = scanner.scan();
+            }
+
+            for (let line = lineOf(start); line <= lineOf(end); line++) {
+                result.add(line + 1);
+            }
+
+            token = scanner.scan();
+            continue;
+        }
+
+        token = scanner.scan();
+    }
+
+    return result;
+}
+
+const B64 =
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const B64MAP = new Map([...B64].map((c, i) => [c, i]));
+
+/**
+ * Decodes one base64 VLQ source-map segment into its integer fields.
+ *
+ * @param {string} seg
+ * @returns {number[]}
+ */
+function decodeVLQ(seg) {
+    const out = [];
+    let shift = 0;
+    let value = 0;
+
+    for (const ch of seg) {
+        const digit = B64MAP.get(ch);
+
+        if (digit === undefined) {
+            break;
+        }
+
+        value += (digit & 31) << shift;
+
+        if (digit & 32) {
+            shift += 5;
+        } else {
+            out.push(value & 1 ? -(value >> 1) : value >> 1);
+            value = 0;
+            shift = 0;
+        }
+    }
+
+    return out;
+}
+
+/**
+ * Returns the set of 1-based source lines that produced generated JavaScript,
+ * read from the file's `.js.map`. These are exactly the coverable lines — every
+ * other line (comments, blanks, type-only declarations, interfaces) emits no
+ * code and can never be executed. Returns null when no source map is present.
+ *
+ * @param {string} sourceFile - path of the .ts source (e.g. src/RedisQueue.ts)
+ * @returns {Set<number> | null}
+ */
+function emittedLines(sourceFile) {
+    const mapPath = sourceFile.replace(/\.ts$/, '.js.map');
+
+    if (!existsSync(mapPath)) {
+        return null;
+    }
+
+    let map;
+
+    try {
+        map = JSON.parse(readFileSync(mapPath, 'utf8'));
+    } catch {
+        return null;
+    }
+
+    if (typeof map.mappings !== 'string') {
+        return null;
+    }
+
+    const lines = new Set();
+    let srcIndex = 0;
+    let srcLine = 0;
+
+    for (const group of map.mappings.split(';')) {
+        for (const seg of group.split(',')) {
+            if (!seg) {
+                continue;
+            }
+
+            const fields = decodeVLQ(seg);
+
+            // [genCol, srcIndex, srcLine, srcCol, nameIndex]; <4 fields = no
+            // source position for this segment
+            if (fields.length >= 4) {
+                srcIndex += fields[1];
+                srcLine += fields[2];
+
+                if (srcIndex === 0) {
+                    lines.add(srcLine + 1); // map lines are 0-based
+                }
+            }
+        }
+    }
+
+    return lines;
+}
+
+const coverableCache = new Map();
+
+/**
+ * Resolves how to filter a source file's line records:
+ *   - `{ mode: 'keep', set }` — keep only lines in `set` (source-map driven);
+ *   - `{ mode: 'drop', set }` — drop lines in `set` (comment-scanner fallback).
+ *
+ * @param {string} sourceFile
+ * @returns {{ mode: 'keep' | 'drop', set: Set<number> }}
+ */
+function coverableInfo(sourceFile) {
+    if (coverableCache.has(sourceFile)) {
+        return coverableCache.get(sourceFile);
+    }
+
+    const emitted = sourceFile ? emittedLines(sourceFile) : null;
+    let info;
+
+    if (emitted && existsSync(sourceFile)) {
+        // A line is coverable only if it emitted JS (has a source-map mapping)
+        // AND is not a comment/blank AND is not an import statement. The comment
+        // check is required because `removeComments: false` keeps license/JSDoc
+        // comments in the output, so they carry mappings too; the mapping check
+        // drops type-only lines (interfaces, type aliases) which emit nothing;
+        // the import check drops the mis-mapped import artifact.
+        const text = readFileSync(sourceFile, 'utf8');
+        const nonCode = nonCodeLines(text);
+        const imports = importLines(text);
+        const keep = new Set(
+            [...emitted].filter(
+                line => !nonCode.has(line) && !imports.has(line),
+            ),
+        );
+        info = { mode: 'keep', set: keep };
+    } else if (sourceFile && existsSync(sourceFile)) {
+        const text = readFileSync(sourceFile, 'utf8');
+        const skip = nonCodeLines(text);
+
+        for (const line of importLines(text)) {
+            skip.add(line);
+        }
+
+        info = { mode: 'drop', set: skip };
+    } else {
+        info = { mode: 'drop', set: new Set() };
+    }
+
+    coverableCache.set(sourceFile, info);
+
+    return info;
+}
+
+let strippedLines = 0;
+
+/**
+ * Rewrites a single lcov record so that genhtml accepts it without warnings or
+ * errors. It:
+ *   - drops DA/BRDA entries on non-code (comment/blank) lines;
+ *   - drops all function records (FN/FNDA/FNF/FNH) — Node's source-mapped
+ *     function detection is unreliable here (undefined line numbers, mis-named
+ *     and duplicated entries), which genhtml rejects, so line + branch coverage
+ *     is kept instead;
+ *   - drops malformed branch records such as `BRDA:undefined,...`;
+ *   - recomputes the LF/LH/BRF/BRH totals.
+ *
+ * @param {string[]} recordLines - record body, excluding the end_of_record line
+ * @returns {string}
+ */
+function processRecord(recordLines) {
+    const sfLine = recordLines.find(line => line.startsWith('SF:'));
+    const sourceFile = sfLine ? sfLine.slice(3).trim() : '';
+    const info = coverableInfo(sourceFile);
+
+    // true when a source line produces no executable code and must be dropped
+    const drop = n => (info.mode === 'keep' ? !info.set.has(n) : info.set.has(n));
+
+    let lf = 0;
+    let lh = 0;
+    let brf = 0;
+    let brh = 0;
+
+    const kept = recordLines.filter(line => {
+        // drop all function records — unreliable under source maps
+        if (/^(FN:|FNDA:|FNF:|FNH:)/.test(line)) {
+            return false;
+        }
+
+        const da = line.match(/^DA:(\d+),(\d+)/);
+
+        if (da) {
+            if (drop(+da[1])) {
+                strippedLines++;
+
+                return false;
+            }
+
+            lf++;
+
+            if (+da[2] > 0) {
+                lh++;
+            }
+
+            return true;
+        }
+
+        if (line.startsWith('BRDA:')) {
+            const brda = line.match(/^BRDA:(\d+),\d+,\d+,(\d+|-)$/);
+
+            // drop malformed (e.g. BRDA:undefined,...) or non-code branches
+            if (!brda || drop(+brda[1])) {
+                return false;
+            }
+
+            brf++;
+
+            if (brda[2] !== '-' && +brda[2] > 0) {
+                brh++;
+            }
+
+            return true;
+        }
+
+        // drop the old totals — they are recomputed below
+        return !/^(LF|LH|BRF|BRH):/.test(line);
+    });
+
+    return (
+        `${kept.join('\n')}\n` +
+        `LF:${lf}\nLH:${lh}\nBRF:${brf}\nBRH:${brh}\nend_of_record\n`
+    );
+}
+
+const output = [];
+let record = [];
+
+for (const line of readFileSync(lcovPath, 'utf8').split('\n')) {
+    if (line === 'end_of_record') {
+        output.push(processRecord(record));
+        record = [];
+    } else if (line !== '') {
+        record.push(line);
+    }
+}
+
+writeFileSync(lcovPath, output.join(''));
+console.info(
+    `strip-comment-coverage: removed ${strippedLines} comment/blank line ` +
+        `entries from ${lcovPath}`,
+);

package/eslint.config.mjs

@@ -1,132 +0,0 @@
-import typescriptEslint from "@typescript-eslint/eslint-plugin";
-import globals from "globals";
-import tsParser from "@typescript-eslint/parser";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import js from "@eslint/js";
-import { FlatCompat } from "@eslint/eslintrc";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const compat = new FlatCompat({
-    baseDirectory: __dirname,
-    recommendedConfig: js.configs.recommended,
-    allConfig: js.configs.all
-});
-
-export default [...compat.extends(
-    "plugin:@typescript-eslint/recommended",
-    "plugin:@typescript-eslint/recommended-requiring-type-checking",
-), {
-    plugins: {
-        "@typescript-eslint": typescriptEslint,
-    },
-
-    languageOptions: {
-        globals: {
-            ...globals.browser,
-            ...globals.node,
-        },
-
-        parser: tsParser,
-        ecmaVersion: 5,
-        sourceType: "module",
-
-        parserOptions: {
-            project: "tsconfig.json",
-        },
-    },
-
-    rules: {
-        "@typescript-eslint/adjacent-overload-signatures": "error",
-        "@typescript-eslint/array-type": "error",
-        "@typescript-eslint/class-name-casing": "off",
-        "@typescript-eslint/consistent-type-assertions": "error",
-        "@typescript-eslint/interface-name-prefix": "off",
-        "@typescript-eslint/no-unsafe-assignment": "off",
-        "@typescript-eslint/no-unsafe-member-access": "off",
-        "@typescript-eslint/explicit-module-boundary-types": "off",
-        "@typescript-eslint/no-unsafe-return": "off",
-        "@typescript-eslint/await-thenable": "off",
-        "@typescript-eslint/no-misused-promises": "off",
-        "@typescript-eslint/no-empty-function": "error",
-        "@typescript-eslint/no-empty-interface": "error",
-        "@typescript-eslint/no-explicit-any": "off",
-        "@typescript-eslint/no-misused-new": "error",
-        "@typescript-eslint/no-namespace": "error",
-        "@typescript-eslint/no-parameter-properties": "off",
-        "@typescript-eslint/no-use-before-define": "off",
-        "@typescript-eslint/no-var-requires": "off",
-        "@typescript-eslint/prefer-for-of": "error",
-        "@typescript-eslint/prefer-function-type": "error",
-        "@typescript-eslint/prefer-namespace-keyword": "error",
-        "@typescript-eslint/unbound-method": "off",
-        "@typescript-eslint/no-shadow": ["error"],
-
-        "quotes": ["error", "single", {
-            avoidEscape: true,
-        }],
-
-        "semi": "error",
-        "@typescript-eslint/triple-slash-reference": "error",
-        "@typescript-eslint/unified-signatures": "error",
-        "arrow-parens": ["off", "as-needed"],
-        camelcase: "error",
-        "comma-dangle": "off",
-        complexity: "off",
-        "constructor-super": "error",
-        "dot-notation": "error",
-        eqeqeq: ["error", "smart"],
-        "guard-for-in": "error",
-
-        "id-blacklist": [
-            "error",
-            "any",
-            "Number",
-            "number",
-            "String",
-            "string",
-            "Boolean",
-            "boolean",
-            "Undefined",
-            "undefined",
-        ],
-
-        "id-match": "error",
-        "max-classes-per-file": "off",
-
-        "max-len": ["error", {
-            code: 80,
-        }],
-
-        "new-parens": "error",
-        "no-bitwise": "off",
-        "no-caller": "error",
-        "no-cond-assign": "error",
-        "no-console": "off",
-        "no-debugger": "error",
-        "no-empty": "error",
-        "no-eval": "error",
-        "no-fallthrough": "off",
-        "no-invalid-this": "off",
-        "no-multiple-empty-lines": "off",
-        "no-new-wrappers": "error",
-        "no-shadow": "off",
-        "no-throw-literal": "error",
-        "no-trailing-spaces": "error",
-        "no-undef-init": "error",
-        "no-underscore-dangle": "error",
-        "no-unsafe-finally": "error",
-        "no-unused-expressions": "off",
-        "no-unused-labels": "error",
-        "no-var": "error",
-        "object-shorthand": "error",
-        "one-var": ["error", "never"],
-        "prefer-arrow/prefer-arrow-functions": "off",
-        "prefer-const": "error",
-        radix: "error",
-        "spaced-comment": "off",
-        "use-isnan": "error",
-        "valid-typeof": "off",
-    },
-}];