fix!: improve hooks type safety with generic HookSignatureMap

[fgiova]

Replace manual hook return types and addHook overloads with a single HookSignatureMap type that maps each hook name to its args and return type. Both Hooks.runHook and Hooks.addHook are now generic, providing full type inference at call sites.

Also fix several inaccuracies in README: wrong option names, incorrect return types, non-existent onHandle hook, and wrong destroySigner default.

BREAKING-CHANGE: Drop support to Node.js 20.x

[Copilot]

Pull request overview

This PR introduces type-safe hook signatures through a generic HookSignatureMap type system, replacing manual hook return type definitions and overloads with a single centralized type mapping. It also corrects several documentation inaccuracies in the README, updates the codebase to drop Node.js 20 support (breaking change), refactors the polling mechanism from recursive calls to a while loop with exponential backoff error handling, and improves timeout cleanup and error message handling.

Changes:

• Introduced generic HookSignatureMap for type-safe hook signatures with full type inference
• Refactored polling from recursive calls to while loop with exponential backoff for error recovery
• Fixed README documentation errors (option names, return types, removed non-existent onHandle hook, corrected destroySigner default)
• Dropped Node.js 20.x support, requiring Node.js 22.14.0+ or 24.10.0+

Reviewed changes

Copilot reviewed 12 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/hooks.ts	Added HookSignatureMap type for centralized hook signature definitions and updated addHook/runHook to use generics
src/index.ts	Updated to use new generic hook types, refactored pollMessages to use while loop with exponential backoff, improved timeout cleanup
src/errors.ts	Removed coverage ignore comment for TimeoutError fallback message
test/test/hooks.ts	Added tests for TimeoutError message handling, void return hooks (onStart/onStop), and onSQSError error propagation
test/test/queue-hooks.ts	Added integration tests for onStart, onStop, and onSuccess hooks
test/test/index.ts	Added tests for isRunning getter, deleteMessage false option, and serial handler errors
test/test/error.ts	Changed onHandlerError hook return from boolean to void
test/scripts/runners/localstack.js	Added testcontainers reaper session label for proper container cleanup
README.md	Corrected option names (extendVisibilityTimeout, executionTimeout), return types (boolean instead of Message), removed non-existent onHandle hook, corrected destroySigner default
package.json	Updated Node.js version requirement, upgraded dependencies (@fgiova/mini-sqs-client, @fgiova/aws-signature, dev dependencies)
.nvmrc	Updated from v20 to v22
.github/workflows/node.js.yml	Removed Node 20 from matrix, updated actions versions, added granular permissions, removed NPM_TOKEN
.gitignore	Added .plans/ directory

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.