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

docs/changelog/v2/v2.0.5.md

@@ -0,0 +1,66 @@
+# 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](https://github.com/CLDMV/holdmytask/pull/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](https://github.com/CLDMV/holdmytask/issues/51).
+
+### Callback-style task failures no longer require an `error` listener ([#56](https://github.com/CLDMV/holdmytask/pull/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](https://github.com/CLDMV/holdmytask/issues/53).
+
+### Non-integer priority keys are reported instead of dropped silently ([#57](https://github.com/CLDMV/holdmytask/pull/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](https://github.com/CLDMV/holdmytask/issues/54).
+
+---
+
+## 🧪 Tests
+
+- New suites: `TaskLevelDelayNames` ([#55](https://github.com/CLDMV/holdmytask/pull/55)), `CallbackErrorWithoutListener` ([#56](https://github.com/CLDMV/holdmytask/pull/56)) and `PriorityKeyValidation` ([#57](https://github.com/CLDMV/holdmytask/pull/57)).
+- `PostDelayAfterAwait` ([#59](https://github.com/CLDMV/holdmytask/pull/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](https://github.com/CLDMV/holdmytask/issues/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](https://github.com/CLDMV/holdmytask/pull/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](./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](https://github.com/CLDMV/holdmytask/pull/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](https://github.com/CLDMV/holdmytask/pull/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](https://github.com/CLDMV/holdmytask/pull/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](./v2.0.4.md), 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.

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/holdmytask",
-	"version": "2.0.4",
+	"version": "2.0.5",
 	"description": "A tiny task queue that waits until your task is ready",
 	"main": "./index.cjs",
 	"module": "./index.mjs",
@@ -82,8 +82,8 @@
 	},
 	"type": "module",
 	"devDependencies": {
-		"@cldmv/configs": "^1.2.0",
-		"@cldmv/fix-headers": "^2.1.1",
+		"@cldmv/configs": "^1.2.4",
+		"@cldmv/fix-headers": "^2.2.0",
 		"@cldmv/vitest-runner": "^1.2.0",
 		"@eslint/css": "^2.0.0",
 		"@eslint/js": "^10.0.1",