release: v2.0.5 - accept task-level postDelay/startDelay, keep…

[cldmv-bot]

HoldMyTask v2.0.5 Changelog

Release Date: October 2026
Release Type: Patch
Branch: release/2.0.5

---

Overview

v2.0.5 fixes three long-standing problems in how the queue reads its options and reports failures. The documented task-level postDelay / startDelay options now actually work (the old delay / start names become deprecated aliases), a callback-style task failure no longer crashes the process when no error listener is attached, and a priorities key that is not an integer is now reported instead of being dropped silently. The README was rewritten to the CLDMV layout and every example now uses the current API.

Runtime behavior changes in a few observable ways, all described below: code that still passes delay or start to enqueue() now receives a deprecation warning event, a task-level completion delay is now enforced even when the task's priority has no postDelay of its own, a callback-style task failure is no longer thrown as an unhandled error event, and a non-integer priority key now produces an invalid-priority warning. No option was removed and no exported signature changed.

---

🐛 Bug Fixes

Task-level postDelay / startDelay are honored; delay / start are deprecated aliases (#55)

enqueue() only read the task-level delay and start options, although its JSDoc already pointed at postDelay. Passing the documented name gave no delay at all. enqueue() now treats postDelay and startDelay as the current task-level names, matching the names already used in priorities, coalescing.defaults and coalescing.keys. delay and start still work and map onto the new names; when both forms are given, the current name wins. postDelay: -1 bypasses an active delay period exactly as delay: -1 did, and the caller's options object is never mutated. getPriorityConfig() and getCoalescingConfig() accept both names in their taskOptions argument.

New warning: each deprecated task-level alias now emits a warning event of type "deprecation" (with deprecated and replacement fields), in the same shape the priority and coalescing levels already used. The warning fires once per alias per queue instance, not once per task, so a hot enqueue path does not flood listeners. No warning is emitted when the replacement name is also present.

Scheduler fix: the delay gate between tasks used to require the completed task's priority to have a positive postDelay. A task-level completion delay on a priority without one was recorded but never enforced, which was true of the old delay name as well. The gate now relies on the computed next-available time alone, so a task-level postDelay (or delay) takes effect regardless of the priority's configuration. Code that relied on a task-level delay being ignored in that situation will now see the delay applied. Closes #51.

Callback-style task failures no longer require an error listener (#56)

When a callback-style task failed, timed out, was aborted or expired, the queue emitted error. HoldMyTask is an EventEmitter, so with no error listener that emit threw: the process crashed (an unhandled rejection for failures, an uncaught exception from the scheduler for expiry), and for failures the task's callback never ran. Task-failure error events are now emitted only when at least one error listener is attached. The failure always reaches the task's callback with the documented payload ({ type: "error", error }, { type: "timeout", message }, { type: "canceled", message: "Task was aborted" }, or the expiry error).

Listeners that are attached see the same events as before. The difference is for queues without one: a callback task failure is no longer thrown. An error thrown by the callback itself is still emitted unconditionally, so a bug inside a callback is not silently swallowed, and the error events for invalid enqueue() arguments and rejected configurePriority() / configureCoalescingKey() input are unchanged. Promise-style tasks are unchanged and report failures only through the rejected promise. Closes #53.

Non-integer priority keys are reported instead of dropped silently (#57)

The constructor ran priorities (and the deprecated delays) keys through parseInt and discarded anything that came back NaN, so a config such as priorities: { high: { postDelay: 100 } } did nothing, and a key such as "2.5" was truncated without notice. Any non-integer key now emits a warning event of type "invalid-priority" with message, option ("priorities" or "delays"), key and priority fields. A key that cannot be read as a number is still ignored (priority: null); a fractional key keeps its historical meaning, the truncated priority, but is reported. Integer keys, including negative ones, are unaffected. The constructor still never throws for configuration, so a config that constructed fine on v2.0.4 still constructs fine. Closes #54.

---

🧪 Tests

• New suites: TaskLevelDelayNames (#55), CallbackErrorWithoutListener (#56) and PriorityKeyValidation (#57).
• PostDelayAfterAwait (#59) adds deterministic fake-timer coverage for postDelay when the next task is enqueued after awaiting the previous one: promise API after await, promise API in the resolving microtask, and callback API enqueuing from the completion callback, in both smart-scheduling and polling modes. All cases pass on the current code; the report in #52 could not be reproduced, and the issue is closed with these tests as regression coverage.

📚 Documentation

• The README was restructured to the CLDMV layout and every example was updated from deprecated option names to the current API (#50). It now documents the task-level postDelay / startDelay options, the optional error listener for callback-style tasks, both warning event types (deprecation and invalid-priority), and a table of every deprecated option with its replacement.
• The JSDoc and generated types/ declarations for enqueue() list postDelay and startDelay, with delay and start marked deprecated.
• NEW: docs/changelog/v2/v2.0.5.md — this changelog.

🔧 Dependencies

Both are dev dependencies and affect only the npm run fix:headers script, which extends @cldmv/configs/fix-headers.json. Only package.json and the lockfile changed; no file headers were restamped and the published package is unaffected.

• @cldmv/fix-headers ^2.1.1 → ^2.2.0, in two steps. 2.1.4 (#61) no longer writes a JavaScript comment into JSON or Markdown files, processes every repeated --input, and never walks dependency folders such as node_modules. 2.2.0 (#62) makes @Last modified by follow edits to a file's content only, so a run that merely rewrites a header keeps the recorded editor.
• @cldmv/configs ^1.2.0 → ^1.2.4 (#62). The shared fix-headers config now sets forceAuthorUpdate and forceLastModifiedAuthorUpdate to false, so @Author keeps the file's creator and @Last modified by changes only with real content edits. The 1.2.1 and 1.2.2 releases of that package only changed its own CI.

---

Upgrade notes

No breaking API changes — drop-in for v2.0.4, with these behavior differences to check:

• Replace task-level delay with postDelay and start with startDelay in enqueue() calls. The old names keep working, but each emits one deprecation warning per queue instance.
• A task-level postDelay (or delay) is now enforced even when the task's priority has no postDelay. If a queue depended on that delay being ignored, remove it from the task options.
• A callback-style task failure is no longer thrown when no error listener is attached; handle failures in the task callback, or attach an error listener if the queue-level event is wanted.
• Check priorities / delays configs for non-integer keys. They behave as before, but now emit an invalid-priority warning.

👥 Contributors

• @Shinrai

---

Metric	Coverage
Statements	80.7%
Branches	75.2%
Functions	72.7%
Lines	81.8%

Avg: 77.6% · 9e5a70b · Node lts/*

Co-authored-by: Shinrai Shinrai@users.noreply.github.com

[cldmv-bot]

🔒 Dependency Review

• ✅ 0 vulnerable package(s)
• ✅ 0 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ✅ 0 package(s) with unknown licenses
• ✅ 0 denied package(s)
• ✅ 0 package(s) with OpenSSF Scorecard score < 3

Full job summary

[cldmv-bot]

⚠️ Bundle size increased

File	Raw	Δ Raw	Gzipped	Δ Gzipped
dist/hold-my-task.mjs	98.7 kB	+4.6 kB (+4.9%) ⚠️	20.8 kB	+1.4 kB
dist/utils.mjs	3.3 kB	—	1.2 kB	—
index.cjs	1.6 kB	—	813 B	—
index.mjs	2.4 kB	—	937 B	—
types/index.d.mts	1.7 kB	—	564 B	—
types/index.d.mts.map	834 B	—	299 B	—
Total	108.5 kB	+4.6 kB	24.5 kB	+1.4 kB

_{📊 Generated by bundle-size. Brotli sizes also measured but omitted from the table for brevity.}