feat: adding strictreturn flag

[nicholasgriffintn]

This PR introduces a new flag, strictReturn, which enforces explicit return values from message handlers in order to prevent ambiguous acknowledgment behavior. When enabled, the consumer requires each handler (handleMessage or handleMessageBatch) to explicitly return one of the following:

• A Message (or array of Messages) → acknowledge and delete the message(s)
• undefined → leave the message(s) on the queue (nack)

Returning null or omitting a return (i.e., void) is no longer permitted under strictReturn.

Motivation

Historically, handlers could return void or null, which SQS Consumer treated as “do nothing.”
This behavior often led to accidental message retention, especially when developers forgot to return a value.

The strictReturn flag:

• Makes handler intent explicit
• Prevents silent failures caused by missing return statements
• Paves the way for strictReturn to become the default behavior in a future major release

This aligns with ongoing deprecation of void/null returns (see #598

Behavior

Return value	strictReturn: false (default)	strictReturn: true
Message	✅ Acknowledge	✅ Acknowledge
undefined	✅ Leave on queue	✅ Leave on queue
null	⚠️ Logs deprecation warning	❌ Throws error

[github-actions]

LCOV of commit d883f0a during Comment PR Coverage #166

Summary coverage rate:
  lines......: 97.1% (1023 of 1054 lines)
  functions..: 97.3% (36 of 37 functions)
  branches...: no data found

Files changed coverage rate:
                   |Lines       |Functions  |Branches    
  Filename         |Rate     Num|Rate    Num|Rate     Num
  =======================================================
  src/consumer.ts  | 3.0%    702| 0.0%    21|    -      0

[Copilot]

Pull Request Overview

This PR introduces a new strictReturn flag that enforces explicit return values from message handlers to prevent ambiguous acknowledgment behavior and accidental message retention.

• Adds strictReturn option to ConsumerOptions interface with default value of false
• Implements error throwing when strictReturn is enabled and handlers return null
• Updates deprecation warning messages to specifically mention null instead of void

Reviewed Changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

File	Description
src/types.ts	Adds strictReturn boolean option to ConsumerOptions interface
src/consumer.ts	Implements strictReturn logic with error throwing and updates deprecation messages
test/tests/consumer.test.ts	Updates test descriptions and adds comprehensive test coverage for strictReturn behavior
README.md	Documents the new strictReturn flag behavior

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}