@amqp-contract/worker 0.7.0 → 0.9.0

package/docs/index.md

@@ -8,7 +8,7 @@
 
 ### MessageValidationError
 
-Defined in: [packages/worker/src/errors.ts:35](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/errors.ts#L35)
+Defined in: [packages/worker/src/errors.ts:35](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L35)
 
 Error thrown when message validation fails
 
@@ -24,7 +24,7 @@ Error thrown when message validation fails
 new MessageValidationError(consumerName, issues): MessageValidationError;
 ```
 
-Defined in: [packages/worker/src/errors.ts:36](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/errors.ts#L36)
+Defined in: [packages/worker/src/errors.ts:36](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L36)
 
 ###### Parameters
 
@@ -48,12 +48,12 @@ WorkerError.constructor
 | Property | Modifier | Type | Description | Inherited from | Defined in |
 | ------ | ------ | ------ | ------ | ------ | ------ |
 | <a id="cause"></a> `cause?` | `public` | `unknown` | - | `WorkerError.cause` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:26 |
-| <a id="consumername"></a> `consumerName` | `readonly` | `string` | - | - | [packages/worker/src/errors.ts:37](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/errors.ts#L37) |
-| <a id="issues"></a> `issues` | `readonly` | `unknown` | - | - | [packages/worker/src/errors.ts:38](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/errors.ts#L38) |
+| <a id="consumername"></a> `consumerName` | `readonly` | `string` | - | - | [packages/worker/src/errors.ts:37](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L37) |
+| <a id="issues"></a> `issues` | `readonly` | `unknown` | - | - | [packages/worker/src/errors.ts:38](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L38) |
 | <a id="message"></a> `message` | `public` | `string` | - | `WorkerError.message` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
 | <a id="name"></a> `name` | `public` | `string` | - | `WorkerError.name` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
 | <a id="stack"></a> `stack?` | `public` | `string` | - | `WorkerError.stack` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
-| <a id="stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `WorkerError.stackTraceLimit` | node\_modules/.pnpm/@types+node@25.0.3/node\_modules/@types/node/globals.d.ts:67 |
+| <a id="stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `WorkerError.stackTraceLimit` | node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:67 |
 
 #### Methods
 
@@ -63,7 +63,7 @@ WorkerError.constructor
 static captureStackTrace(targetObject, constructorOpt?): void;
 ```
 
-Defined in: node\_modules/.pnpm/@types+node@25.0.3/node\_modules/@types/node/globals.d.ts:51
+Defined in: node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:51
 
 Creates a `.stack` property on `targetObject`, which when accessed returns
 a string representing the location in the code at which
@@ -132,7 +132,313 @@ WorkerError.captureStackTrace
 static prepareStackTrace(err, stackTraces): any;
 ```
 
-Defined in: node\_modules/.pnpm/@types+node@25.0.3/node\_modules/@types/node/globals.d.ts:55
+Defined in: node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:55
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `err` | `Error` |
+| `stackTraces` | `CallSite`[] |
+
+###### Returns
+
+`any`
+
+###### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+###### Inherited from
+
+```ts
+WorkerError.prepareStackTrace
+```
+
+***
+
+### NonRetryableError
+
+Defined in: [packages/worker/src/errors.ts:69](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L69)
+
+Non-retryable errors - permanent failures that should not be retried
+Examples: invalid data, business rule violations, permanent external failures
+
+Use this error type when retrying would not help - the message will be
+immediately sent to the dead letter queue (DLQ) if configured.
+
+#### Extends
+
+- `WorkerError`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new NonRetryableError(message, cause?): NonRetryableError;
+```
+
+Defined in: [packages/worker/src/errors.ts:70](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L70)
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `string` |
+| `cause?` | `unknown` |
+
+###### Returns
+
+[`NonRetryableError`](#nonretryableerror)
+
+###### Overrides
+
+```ts
+WorkerError.constructor
+```
+
+#### Properties
+
+| Property | Modifier | Type | Description | Inherited from | Defined in |
+| ------ | ------ | ------ | ------ | ------ | ------ |
+| <a id="cause-1"></a> `cause?` | `readonly` | `unknown` | - | `WorkerError.cause` | [packages/worker/src/errors.ts:72](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L72) |
+| <a id="message-1"></a> `message` | `public` | `string` | - | `WorkerError.message` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
+| <a id="name-1"></a> `name` | `public` | `string` | - | `WorkerError.name` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
+| <a id="stack-1"></a> `stack?` | `public` | `string` | - | `WorkerError.stack` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
+| <a id="stacktracelimit-1"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `WorkerError.stackTraceLimit` | node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:67 |
+
+#### Methods
+
+##### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Defined in: node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:51
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack;  // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+  b();
+}
+
+function b() {
+  c();
+}
+
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error;
+  Error.stackTraceLimit = 0;
+  const error = new Error();
+  Error.stackTraceLimit = stackTraceLimit;
+
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+  throw error;
+}
+
+a();
+```
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `targetObject` | `object` |
+| `constructorOpt?` | `Function` |
+
+###### Returns
+
+`void`
+
+###### Inherited from
+
+```ts
+WorkerError.captureStackTrace
+```
+
+##### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+Defined in: node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:55
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `err` | `Error` |
+| `stackTraces` | `CallSite`[] |
+
+###### Returns
+
+`any`
+
+###### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+###### Inherited from
+
+```ts
+WorkerError.prepareStackTrace
+```
+
+***
+
+### RetryableError
+
+Defined in: [packages/worker/src/errors.ts:52](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L52)
+
+Retryable errors - transient failures that may succeed on retry
+Examples: network timeouts, rate limiting, temporary service unavailability
+
+Use this error type when the operation might succeed if retried.
+The worker will apply exponential backoff and retry the message.
+
+#### Extends
+
+- `WorkerError`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new RetryableError(message, cause?): RetryableError;
+```
+
+Defined in: [packages/worker/src/errors.ts:53](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L53)
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `string` |
+| `cause?` | `unknown` |
+
+###### Returns
+
+[`RetryableError`](#retryableerror)
+
+###### Overrides
+
+```ts
+WorkerError.constructor
+```
+
+#### Properties
+
+| Property | Modifier | Type | Description | Inherited from | Defined in |
+| ------ | ------ | ------ | ------ | ------ | ------ |
+| <a id="cause-2"></a> `cause?` | `readonly` | `unknown` | - | `WorkerError.cause` | [packages/worker/src/errors.ts:55](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L55) |
+| <a id="message-2"></a> `message` | `public` | `string` | - | `WorkerError.message` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
+| <a id="name-2"></a> `name` | `public` | `string` | - | `WorkerError.name` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
+| <a id="stack-2"></a> `stack?` | `public` | `string` | - | `WorkerError.stack` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
+| <a id="stacktracelimit-2"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `WorkerError.stackTraceLimit` | node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:67 |
+
+#### Methods
+
+##### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Defined in: node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:51
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack;  // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+  b();
+}
+
+function b() {
+  c();
+}
+
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error;
+  Error.stackTraceLimit = 0;
+  const error = new Error();
+  Error.stackTraceLimit = stackTraceLimit;
+
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+  throw error;
+}
+
+a();
+```
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `targetObject` | `object` |
+| `constructorOpt?` | `Function` |
+
+###### Returns
+
+`void`
+
+###### Inherited from
+
+```ts
+WorkerError.captureStackTrace
+```
+
+##### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+Defined in: node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:55
 
 ###### Parameters
 
@@ -159,7 +465,7 @@ WorkerError.prepareStackTrace
 
 ### TechnicalError
 
-Defined in: [packages/worker/src/errors.ts:22](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/errors.ts#L22)
+Defined in: [packages/worker/src/errors.ts:22](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L22)
 
 Error for technical/runtime failures in worker operations
 This includes validation failures, parsing failures, and processing failures
@@ -176,7 +482,7 @@ This includes validation failures, parsing failures, and processing failures
 new TechnicalError(message, cause?): TechnicalError;
 ```
 
-Defined in: [packages/worker/src/errors.ts:23](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/errors.ts#L23)
+Defined in: [packages/worker/src/errors.ts:23](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L23)
 
 ###### Parameters
 
@@ -199,11 +505,11 @@ WorkerError.constructor
 
 | Property | Modifier | Type | Description | Inherited from | Defined in |
 | ------ | ------ | ------ | ------ | ------ | ------ |
-| <a id="cause-1"></a> `cause?` | `readonly` | `unknown` | - | `WorkerError.cause` | [packages/worker/src/errors.ts:25](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/errors.ts#L25) |
-| <a id="message-1"></a> `message` | `public` | `string` | - | `WorkerError.message` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
-| <a id="name-1"></a> `name` | `public` | `string` | - | `WorkerError.name` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
-| <a id="stack-1"></a> `stack?` | `public` | `string` | - | `WorkerError.stack` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
-| <a id="stacktracelimit-1"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `WorkerError.stackTraceLimit` | node\_modules/.pnpm/@types+node@25.0.3/node\_modules/@types/node/globals.d.ts:67 |
+| <a id="cause-3"></a> `cause?` | `readonly` | `unknown` | - | `WorkerError.cause` | [packages/worker/src/errors.ts:25](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L25) |
+| <a id="message-3"></a> `message` | `public` | `string` | - | `WorkerError.message` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
+| <a id="name-3"></a> `name` | `public` | `string` | - | `WorkerError.name` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
+| <a id="stack-3"></a> `stack?` | `public` | `string` | - | `WorkerError.stack` | node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
+| <a id="stacktracelimit-3"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `WorkerError.stackTraceLimit` | node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:67 |
 
 #### Methods
 
@@ -213,7 +519,7 @@ WorkerError.constructor
 static captureStackTrace(targetObject, constructorOpt?): void;
 ```
 
-Defined in: node\_modules/.pnpm/@types+node@25.0.3/node\_modules/@types/node/globals.d.ts:51
+Defined in: node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:51
 
 Creates a `.stack` property on `targetObject`, which when accessed returns
 a string representing the location in the code at which
@@ -282,7 +588,7 @@ WorkerError.captureStackTrace
 static prepareStackTrace(err, stackTraces): any;
 ```
 
-Defined in: node\_modules/.pnpm/@types+node@25.0.3/node\_modules/@types/node/globals.d.ts:55
+Defined in: node\_modules/.pnpm/@types+node@25.0.5/node\_modules/@types/node/globals.d.ts:55
 
 ###### Parameters
 
@@ -309,7 +615,7 @@ WorkerError.prepareStackTrace
 
 ### TypedAmqpWorker
 
-Defined in: [packages/worker/src/worker.ts:130](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/worker.ts#L130)
+Defined in: [packages/worker/src/worker.ts:190](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L190)
 
 Type-safe AMQP worker for consuming messages from RabbitMQ.
 
@@ -363,7 +669,7 @@ await worker.close().resultToPromise();
 close(): Future<Result<void, TechnicalError>>;
 ```
 
-Defined in: [packages/worker/src/worker.ts:244](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/worker.ts#L244)
+Defined in: [packages/worker/src/worker.ts:327](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L327)
 
 Close the AMQP channel and connection.
 
@@ -391,7 +697,7 @@ if (closeResult.isOk()) {
 static create<TContract>(options): Future<Result<TypedAmqpWorker<TContract>, TechnicalError>>;
 ```
 
-Defined in: [packages/worker/src/worker.ts:205](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/worker.ts#L205)
+Defined in: [packages/worker/src/worker.ts:283](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L283)
 
 Create a type-safe AMQP worker from a contract.
 
@@ -424,17 +730,13 @@ A Future that resolves to a Result containing the worker or an error
 ###### Example
 
 ```typescript
-const workerResult = await TypedAmqpWorker.create({
+const worker = await TypedAmqpWorker.create({
   contract: myContract,
   handlers: {
     processOrder: async (msg) => console.log('Order:', msg.orderId)
   },
   urls: ['amqp://localhost']
 }).resultToPromise();
-
-if (workerResult.isError()) {
-  console.error('Failed to create worker:', workerResult.error);
-}
 ```
 
 ## Type Aliases
@@ -445,7 +747,7 @@ if (workerResult.isError()) {
 type CreateWorkerOptions<TContract> = object;
 ```
 
-Defined in: [packages/worker/src/worker.ts:77](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/worker.ts#L77)
+Defined in: [packages/worker/src/worker.ts:124](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L124)
 
 Options for creating a type-safe AMQP worker.
 
@@ -478,7 +780,14 @@ const options: CreateWorkerOptions<typeof contract> = {
   connectionOptions: {
     heartbeatIntervalInSeconds: 30
   },
-  logger: myLogger
+  logger: myLogger,
+  retry: {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffMultiplier: 2,
+    jitter: true
+  }
 };
 ```
 
@@ -490,26 +799,302 @@ const options: CreateWorkerOptions<typeof contract> = {
 
 #### Properties
 
-| Property | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ |
-| <a id="connectionoptions"></a> `connectionOptions?` | `AmqpConnectionManagerOptions` | Optional connection configuration (heartbeat, reconnect settings, etc.) | [packages/worker/src/worker.ts:85](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/worker.ts#L85) |
-| <a id="contract"></a> `contract` | `TContract` | The AMQP contract definition specifying consumers and their message schemas | [packages/worker/src/worker.ts:79](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/worker.ts#L79) |
-| <a id="handlers"></a> `handlers` | [`WorkerInferConsumerHandlers`](#workerinferconsumerhandlers)\<`TContract`\> | Handlers for each consumer defined in the contract. Can be a function or a tuple of [handler, options] | [packages/worker/src/worker.ts:81](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/worker.ts#L81) |
-| <a id="logger"></a> `logger?` | `Logger` | Optional logger for logging message consumption and errors | [packages/worker/src/worker.ts:87](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/worker.ts#L87) |
-| <a id="urls"></a> `urls` | `ConnectionUrl`[] | AMQP broker URL(s). Multiple URLs provide failover support | [packages/worker/src/worker.ts:83](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/worker.ts#L83) |
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="connectionoptions"></a> `connectionOptions?` | `AmqpConnectionManagerOptions` | Optional connection configuration (heartbeat, reconnect settings, etc.) | [packages/worker/src/worker.ts:137](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L137) |
+| <a id="contract"></a> `contract` | `TContract` | The AMQP contract definition specifying consumers and their message schemas | [packages/worker/src/worker.ts:126](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L126) |
+| <a id="handlers"></a> `handlers` | [`WorkerInferSafeConsumerHandlers`](#workerinfersafeconsumerhandlers)\<`TContract`\> | Handlers for each consumer defined in the contract. Handlers must return `Future<Result<void, HandlerError>>` for explicit error handling. Use defineHandler() to create safe handlers, or defineUnsafeHandler() which wraps Promise-based handlers into safe handlers internally. | [packages/worker/src/worker.ts:133](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L133) |
+| <a id="logger"></a> `logger?` | `Logger` | Optional logger for logging message consumption and errors | [packages/worker/src/worker.ts:139](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L139) |
+| <a id="retry"></a> `retry?` | [`RetryOptions`](#retryoptions) | Retry configuration - when undefined, uses legacy behavior (immediate requeue) | [packages/worker/src/worker.ts:141](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L141) |
+| <a id="telemetry"></a> `telemetry?` | `TelemetryProvider` | Optional telemetry provider for tracing and metrics. If not provided, uses the default provider which attempts to load OpenTelemetry. OpenTelemetry instrumentation is automatically enabled if @opentelemetry/api is installed. | [packages/worker/src/worker.ts:147](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L147) |
+| <a id="urls"></a> `urls` | `ConnectionUrl`[] | AMQP broker URL(s). Multiple URLs provide failover support | [packages/worker/src/worker.ts:135](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L135) |
+
+***
+
+### HandlerError
+
+```ts
+type HandlerError = 
+  | RetryableError
+  | NonRetryableError;
+```
+
+Defined in: [packages/worker/src/errors.ts:83](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/errors.ts#L83)
+
+Union type representing all handler errors.
+Use this type when defining handlers that explicitly signal error outcomes.
+
+***
+
+### RetryOptions
+
+```ts
+type RetryOptions = object;
+```
+
+Defined in: [packages/worker/src/worker.ts:56](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L56)
+
+Retry configuration options for handling failed message processing.
+
+When enabled, the worker will automatically retry failed messages using
+RabbitMQ's native TTL + Dead Letter Exchange (DLX) pattern.
+
+#### Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="backoffmultiplier"></a> `backoffMultiplier?` | `number` | Exponential backoff multiplier (default: 2) | [packages/worker/src/worker.ts:64](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L64) |
+| <a id="initialdelayms"></a> `initialDelayMs?` | `number` | Initial delay in ms before first retry (default: 1000) | [packages/worker/src/worker.ts:60](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L60) |
+| <a id="jitter"></a> `jitter?` | `boolean` | Add jitter to prevent thundering herd (default: true) | [packages/worker/src/worker.ts:66](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L66) |
+| <a id="maxdelayms"></a> `maxDelayMs?` | `number` | Maximum delay in ms between retries (default: 30000) | [packages/worker/src/worker.ts:62](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L62) |
+| <a id="maxretries"></a> `maxRetries?` | `number` | Maximum retry attempts before sending to DLQ (default: 3) | [packages/worker/src/worker.ts:58](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/worker.ts#L58) |
+
+***
+
+### ~~WorkerInferConsumerBatchHandler~~
+
+```ts
+type WorkerInferConsumerBatchHandler<TContract, TName> = WorkerInferUnsafeConsumerBatchHandler<TContract, TName>;
+```
+
+Defined in: [packages/worker/src/types.ts:195](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L195)
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+#### Deprecated
+
+Use WorkerInferUnsafeConsumerBatchHandler instead
+
+***
+
+### ~~WorkerInferConsumerHandler~~
+
+```ts
+type WorkerInferConsumerHandler<TContract, TName> = WorkerInferUnsafeConsumerHandler<TContract, TName>;
+```
+
+Defined in: [packages/worker/src/types.ts:187](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L187)
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+#### Deprecated
+
+Use WorkerInferUnsafeConsumerHandler instead
+
+***
+
+### ~~WorkerInferConsumerHandlerEntry~~
+
+```ts
+type WorkerInferConsumerHandlerEntry<TContract, TName> = WorkerInferUnsafeConsumerHandlerEntry<TContract, TName>;
+```
+
+Defined in: [packages/worker/src/types.ts:203](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L203)
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+#### Deprecated
+
+Use WorkerInferUnsafeConsumerHandlerEntry instead
+
+***
+
+### ~~WorkerInferConsumerHandlers~~
+
+```ts
+type WorkerInferConsumerHandlers<TContract> = WorkerInferUnsafeConsumerHandlers<TContract>;
+```
+
+Defined in: [packages/worker/src/types.ts:211](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L211)
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+
+#### Deprecated
+
+Use WorkerInferUnsafeConsumerHandlers instead
+
+***
+
+### WorkerInferConsumerInput
+
+```ts
+type WorkerInferConsumerInput<TContract, TName> = ConsumerInferInput<InferConsumer<TContract, TName>>;
+```
+
+Defined in: [packages/worker/src/types.ts:39](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L39)
+
+Worker perspective types - for consuming messages
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+***
+
+### WorkerInferSafeConsumerBatchHandler()
+
+```ts
+type WorkerInferSafeConsumerBatchHandler<TContract, TName> = (messages) => Future<Result<void, HandlerError>>;
+```
+
+Defined in: [packages/worker/src/types.ts:80](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L80)
+
+Safe consumer handler type for batch processing.
+Returns a `Future<Result<void, HandlerError>>` for explicit error handling.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `messages` | [`WorkerInferConsumerInput`](#workerinferconsumerinput)\<`TContract`, `TName`\>[] |
+
+#### Returns
+
+`Future`\<`Result`\<`void`, [`HandlerError`](#handlererror)\>\>
+
+#### Example
+
+```typescript
+const handler: WorkerInferSafeConsumerBatchHandler<typeof contract, 'processOrders'> =
+  (messages) => Future.value(Result.Ok(undefined));
+```
+
+***
+
+### WorkerInferSafeConsumerHandler()
+
+```ts
+type WorkerInferSafeConsumerHandler<TContract, TName> = (message) => Future<Result<void, HandlerError>>;
+```
+
+Defined in: [packages/worker/src/types.ts:65](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L65)
+
+Safe consumer handler type for a specific consumer.
+Returns a `Future<Result<void, HandlerError>>` for explicit error handling.
+
+**Recommended over unsafe handlers** for better error control:
+- RetryableError: Message will be retried with exponential backoff
+- NonRetryableError: Message will be immediately sent to DLQ
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | [`WorkerInferConsumerInput`](#workerinferconsumerinput)\<`TContract`, `TName`\> |
+
+#### Returns
+
+`Future`\<`Result`\<`void`, [`HandlerError`](#handlererror)\>\>
+
+#### Example
+
+```typescript
+const handler: WorkerInferSafeConsumerHandler<typeof contract, 'processOrder'> =
+  (message) => Future.value(Result.Ok(undefined));
+```
+
+***
+
+### WorkerInferSafeConsumerHandlerEntry
+
+```ts
+type WorkerInferSafeConsumerHandlerEntry<TContract, TName> = 
+  | WorkerInferSafeConsumerHandler<TContract, TName>
+  | readonly [WorkerInferSafeConsumerHandler<TContract, TName>, {
+  batchSize?: never;
+  batchTimeout?: never;
+  prefetch?: number;
+}]
+  | readonly [WorkerInferSafeConsumerBatchHandler<TContract, TName>, {
+  batchSize: number;
+  batchTimeout?: number;
+  prefetch?: number;
+}];
+```
+
+Defined in: [packages/worker/src/types.ts:95](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L95)
+
+Safe handler entry for a consumer - either a function or a tuple of [handler, options].
+
+Three patterns are supported:
+1. Simple handler: `(message) => Future.value(Result.Ok(undefined))`
+2. Handler with prefetch: `[(message) => ..., { prefetch: 10 }]`
+3. Batch handler: `[(messages) => ..., { batchSize: 5, batchTimeout: 1000 }]`
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
+| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+***
+
+### WorkerInferSafeConsumerHandlers
+
+```ts
+type WorkerInferSafeConsumerHandlers<TContract> = { [K in InferConsumerNames<TContract>]: WorkerInferSafeConsumerHandlerEntry<TContract, K> };
+```
+
+Defined in: [packages/worker/src/types.ts:113](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L113)
+
+Safe consumer handlers for a contract.
+All handlers return `Future<Result<void, HandlerError>>` for explicit error control.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TContract` *extends* `ContractDefinition` |
 
 ***
 
-### WorkerInferConsumerBatchHandler()
+### ~~WorkerInferUnsafeConsumerBatchHandler()~~
 
 ```ts
-type WorkerInferConsumerBatchHandler<TContract, TName> = (messages) => Promise<void>;
+type WorkerInferUnsafeConsumerBatchHandler<TContract, TName> = (messages) => Promise<void>;
 ```
 
-Defined in: [packages/worker/src/types.ts:56](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/types.ts#L56)
+Defined in: [packages/worker/src/types.ts:147](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L147)
 
-Infer consumer handler type for batch processing.
-Batch handlers receive an array of messages.
+Unsafe consumer handler type for batch processing.
+Returns a `Promise<void>` - throws exceptions on error.
 
 #### Type Parameters
 
@@ -528,19 +1113,23 @@ Batch handlers receive an array of messages.
 
 `Promise`\<`void`\>
 
+#### Deprecated
+
+Prefer using safe handlers (WorkerInferSafeConsumerBatchHandler) that return
+`Future<Result<void, HandlerError>>` for better error handling.
+
 ***
 
-### WorkerInferConsumerHandler()
+### ~~WorkerInferUnsafeConsumerHandler()~~
 
 ```ts
-type WorkerInferConsumerHandler<TContract, TName> = (message) => Promise<void>;
+type WorkerInferUnsafeConsumerHandler<TContract, TName> = (message) => Promise<void>;
 ```
 
-Defined in: [packages/worker/src/types.ts:47](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/types.ts#L47)
+Defined in: [packages/worker/src/types.ts:135](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L135)
 
-Infer consumer handler type for a specific consumer.
-Handlers always receive a single message by default.
-For batch processing, use consumerOptions to configure batch behavior.
+Unsafe consumer handler type for a specific consumer.
+Returns a `Promise<void>` - throws exceptions on error.
 
 #### Type Parameters
 
@@ -559,33 +1148,37 @@ For batch processing, use consumerOptions to configure batch behavior.
 
 `Promise`\<`void`\>
 
+#### Deprecated
+
+Prefer using safe handlers (WorkerInferSafeConsumerHandler) that return
+`Future<Result<void, HandlerError>>` for better error handling.
+
+**Note:** When using unsafe handlers:
+- All thrown errors are treated as retryable by default (when retry is configured)
+- Use RetryableError or NonRetryableError to control retry behavior explicitly
+
 ***
 
-### WorkerInferConsumerHandlerEntry
+### ~~WorkerInferUnsafeConsumerHandlerEntry~~
 
 ```ts
-type WorkerInferConsumerHandlerEntry<TContract, TName> = 
-  | WorkerInferConsumerHandler<TContract, TName>
-  | readonly [WorkerInferConsumerHandler<TContract, TName>, {
+type WorkerInferUnsafeConsumerHandlerEntry<TContract, TName> = 
+  | WorkerInferUnsafeConsumerHandler<TContract, TName>
+  | readonly [WorkerInferUnsafeConsumerHandler<TContract, TName>, {
   batchSize?: never;
   batchTimeout?: never;
   prefetch?: number;
 }]
-  | readonly [WorkerInferConsumerBatchHandler<TContract, TName>, {
+  | readonly [WorkerInferUnsafeConsumerBatchHandler<TContract, TName>, {
   batchSize: number;
   batchTimeout?: number;
   prefetch?: number;
 }];
 ```
 
-Defined in: [packages/worker/src/types.ts:69](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/types.ts#L69)
+Defined in: [packages/worker/src/types.ts:157](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L157)
 
-Infer handler entry for a consumer - either a function or a tuple of [handler, options].
-
-Three patterns are supported:
-1. Simple handler: `async (message) => { ... }`
-2. Handler with prefetch: `[async (message) => { ... }, { prefetch: 10 }]`
-3. Batch handler: `[async (messages) => { ... }, { batchSize: 5, batchTimeout: 1000 }]`
+Unsafe handler entry for a consumer - either a function or a tuple of [handler, options].
 
 #### Type Parameters
 
@@ -594,43 +1187,31 @@ Three patterns are supported:
 | `TContract` *extends* `ContractDefinition` |
 | `TName` *extends* `InferConsumerNames`\<`TContract`\> |
 
-***
-
-### WorkerInferConsumerHandlers
-
-```ts
-type WorkerInferConsumerHandlers<TContract> = { [K in InferConsumerNames<TContract>]: WorkerInferConsumerHandlerEntry<TContract, K> };
-```
-
-Defined in: [packages/worker/src/types.ts:87](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/types.ts#L87)
-
-Infer all consumer handlers for a contract.
-Handlers can be either single-message handlers, batch handlers, or a tuple of [handler, options].
-
-#### Type Parameters
+#### Deprecated
 
-| Type Parameter |
-| ------ |
-| `TContract` *extends* `ContractDefinition` |
+Prefer using safe handler entries (WorkerInferSafeConsumerHandlerEntry).
 
 ***
 
-### WorkerInferConsumerInput
+### ~~WorkerInferUnsafeConsumerHandlers~~
 
 ```ts
-type WorkerInferConsumerInput<TContract, TName> = ConsumerInferInput<InferConsumer<TContract, TName>>;
+type WorkerInferUnsafeConsumerHandlers<TContract> = { [K in InferConsumerNames<TContract>]: WorkerInferUnsafeConsumerHandlerEntry<TContract, K> };
 ```
 
-Defined in: [packages/worker/src/types.ts:37](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/types.ts#L37)
+Defined in: [packages/worker/src/types.ts:176](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/types.ts#L176)
 
-Worker perspective types - for consuming messages
+Unsafe consumer handlers for a contract.
 
 #### Type Parameters
 
 | Type Parameter |
 | ------ |
 | `TContract` *extends* `ContractDefinition` |
-| `TName` *extends* `InferConsumerNames`\<`TContract`\> |
+
+#### Deprecated
+
+Prefer using safe handlers (WorkerInferSafeConsumerHandlers).
 
 ## Functions
 
@@ -642,24 +1223,21 @@ Worker perspective types - for consuming messages
 function defineHandler<TContract, TName>(
    contract, 
    consumerName, 
-handler): WorkerInferConsumerHandlerEntry<TContract, TName>;
+handler): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
 ```
 
-Defined in: [packages/worker/src/handlers.ts:70](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/handlers.ts#L70)
+Defined in: [packages/worker/src/handlers.ts:134](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/handlers.ts#L134)
 
 Define a type-safe handler for a specific consumer in a contract.
 
-This utility allows you to define handlers outside of the worker creation,
-providing better code organization and reusability.
+**Recommended:** This function creates handlers that return `Future<Result<void, HandlerError>>`,
+providing explicit error handling and better control over retry behavior.
 
 Supports three patterns:
 1. Simple handler: just the function (single message handler)
 2. Handler with prefetch: [handler, { prefetch: 10 }] (single message handler with config)
 3. Batch handler: [batchHandler, { batchSize: 5, batchTimeout: 1000 }] (REQUIRES batchSize config)
 
-**Important**: Batch handlers (handlers that accept an array of messages) MUST include
-batchSize configuration. You cannot create a batch handler without specifying batchSize.
-
 ##### Type Parameters
 
 | Type Parameter | Description |
@@ -673,49 +1251,42 @@ batchSize configuration. You cannot create a batch handler without specifying ba
 | ------ | ------ | ------ |
 | `contract` | `TContract` | The contract definition containing the consumer |
 | `consumerName` | `TName` | The name of the consumer from the contract |
-| `handler` | [`WorkerInferConsumerHandler`](#workerinferconsumerhandler)\<`TContract`, `TName`\> | The async handler function that processes messages (single or batch) |
+| `handler` | [`WorkerInferSafeConsumerHandler`](#workerinfersafeconsumerhandler)\<`TContract`, `TName`\> | The handler function that returns `Future<Result<void, HandlerError>>` |
 
 ##### Returns
 
-[`WorkerInferConsumerHandlerEntry`](#workerinferconsumerhandlerentry)\<`TContract`, `TName`\>
+[`WorkerInferSafeConsumerHandlerEntry`](#workerinfersafeconsumerhandlerentry)\<`TContract`, `TName`\>
 
 A type-safe handler that can be used with TypedAmqpWorker
 
 ##### Example
 
 ```typescript
-import { defineHandler } from '@amqp-contract/worker';
+import { defineHandler, RetryableError, NonRetryableError } from '@amqp-contract/worker';
+import { Future, Result } from '@swan-io/boxed';
 import { orderContract } from './contract';
 
-// Simple single-message handler without options
+// Simple handler with explicit error handling using mapError
 const processOrderHandler = defineHandler(
   orderContract,
   'processOrder',
-  async (message) => {
-    console.log('Processing order:', message.orderId);
-    await processPayment(message);
-  }
-);
-
-// Single-message handler with prefetch
-const processOrderWithPrefetch = defineHandler(
-  orderContract,
-  'processOrder',
-  async (message) => {
-    await processOrder(message);
-  },
-  { prefetch: 10 }
+  (message) =>
+    Future.fromPromise(processPayment(message))
+      .mapOk(() => undefined)
+      .mapError((error) => new RetryableError('Payment failed', error))
 );
 
-// Batch handler - MUST include batchSize
-const processBatchOrders = defineHandler(
+// Handler with validation (non-retryable error)
+const validateOrderHandler = defineHandler(
   orderContract,
-  'processOrders',
-  async (messages) => {
-    // messages is an array - batchSize configuration is REQUIRED
-    await db.insertMany(messages);
-  },
-  { batchSize: 5, batchTimeout: 1000 }
+  'validateOrder',
+  (message) => {
+    if (message.amount < 1) {
+      // Won't be retried - goes directly to DLQ
+      return Future.value(Result.Error(new NonRetryableError('Invalid order amount')));
+    }
+    return Future.value(Result.Ok(undefined));
+  }
 );
 ```
 
@@ -726,24 +1297,21 @@ function defineHandler<TContract, TName>(
    contract, 
    consumerName, 
    handler, 
-options): WorkerInferConsumerHandlerEntry<TContract, TName>;
+options): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
 ```
 
-Defined in: [packages/worker/src/handlers.ts:78](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/handlers.ts#L78)
+Defined in: [packages/worker/src/handlers.ts:142](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/handlers.ts#L142)
 
 Define a type-safe handler for a specific consumer in a contract.
 
-This utility allows you to define handlers outside of the worker creation,
-providing better code organization and reusability.
+**Recommended:** This function creates handlers that return `Future<Result<void, HandlerError>>`,
+providing explicit error handling and better control over retry behavior.
 
 Supports three patterns:
 1. Simple handler: just the function (single message handler)
 2. Handler with prefetch: [handler, { prefetch: 10 }] (single message handler with config)
 3. Batch handler: [batchHandler, { batchSize: 5, batchTimeout: 1000 }] (REQUIRES batchSize config)
 
-**Important**: Batch handlers (handlers that accept an array of messages) MUST include
-batchSize configuration. You cannot create a batch handler without specifying batchSize.
-
 ##### Type Parameters
 
 | Type Parameter | Description |
@@ -757,53 +1325,46 @@ batchSize configuration. You cannot create a batch handler without specifying ba
 | ------ | ------ | ------ |
 | `contract` | `TContract` | The contract definition containing the consumer |
 | `consumerName` | `TName` | The name of the consumer from the contract |
-| `handler` | [`WorkerInferConsumerHandler`](#workerinferconsumerhandler)\<`TContract`, `TName`\> | The async handler function that processes messages (single or batch) |
-| `options` | \{ `batchSize?`: `undefined`; `batchTimeout?`: `undefined`; `prefetch?`: `number`; \} | Optional consumer options (prefetch, batchSize, batchTimeout) - For single-message handlers: { prefetch?: number } is optional - For batch handlers: { batchSize: number, batchTimeout?: number } is REQUIRED |
+| `handler` | [`WorkerInferSafeConsumerHandler`](#workerinfersafeconsumerhandler)\<`TContract`, `TName`\> | The handler function that returns `Future<Result<void, HandlerError>>` |
+| `options` | \{ `batchSize?`: `undefined`; `batchTimeout?`: `undefined`; `prefetch?`: `number`; \} | Optional consumer options (prefetch, batchSize, batchTimeout) |
 | `options.batchSize?` | `undefined` | - |
 | `options.batchTimeout?` | `undefined` | - |
 | `options.prefetch?` | `number` | - |
 
 ##### Returns
 
-[`WorkerInferConsumerHandlerEntry`](#workerinferconsumerhandlerentry)\<`TContract`, `TName`\>
+[`WorkerInferSafeConsumerHandlerEntry`](#workerinfersafeconsumerhandlerentry)\<`TContract`, `TName`\>
 
 A type-safe handler that can be used with TypedAmqpWorker
 
 ##### Example
 
 ```typescript
-import { defineHandler } from '@amqp-contract/worker';
+import { defineHandler, RetryableError, NonRetryableError } from '@amqp-contract/worker';
+import { Future, Result } from '@swan-io/boxed';
 import { orderContract } from './contract';
 
-// Simple single-message handler without options
+// Simple handler with explicit error handling using mapError
 const processOrderHandler = defineHandler(
   orderContract,
   'processOrder',
-  async (message) => {
-    console.log('Processing order:', message.orderId);
-    await processPayment(message);
-  }
-);
-
-// Single-message handler with prefetch
-const processOrderWithPrefetch = defineHandler(
-  orderContract,
-  'processOrder',
-  async (message) => {
-    await processOrder(message);
-  },
-  { prefetch: 10 }
+  (message) =>
+    Future.fromPromise(processPayment(message))
+      .mapOk(() => undefined)
+      .mapError((error) => new RetryableError('Payment failed', error))
 );
 
-// Batch handler - MUST include batchSize
-const processBatchOrders = defineHandler(
+// Handler with validation (non-retryable error)
+const validateOrderHandler = defineHandler(
   orderContract,
-  'processOrders',
-  async (messages) => {
-    // messages is an array - batchSize configuration is REQUIRED
-    await db.insertMany(messages);
-  },
-  { batchSize: 5, batchTimeout: 1000 }
+  'validateOrder',
+  (message) => {
+    if (message.amount < 1) {
+      // Won't be retried - goes directly to DLQ
+      return Future.value(Result.Error(new NonRetryableError('Invalid order amount')));
+    }
+    return Future.value(Result.Ok(undefined));
+  }
 );
 ```
 
@@ -814,24 +1375,21 @@ function defineHandler<TContract, TName>(
    contract, 
    consumerName, 
    handler, 
-options): WorkerInferConsumerHandlerEntry<TContract, TName>;
+options): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
 ```
 
-Defined in: [packages/worker/src/handlers.ts:87](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/handlers.ts#L87)
+Defined in: [packages/worker/src/handlers.ts:151](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/handlers.ts#L151)
 
 Define a type-safe handler for a specific consumer in a contract.
 
-This utility allows you to define handlers outside of the worker creation,
-providing better code organization and reusability.
+**Recommended:** This function creates handlers that return `Future<Result<void, HandlerError>>`,
+providing explicit error handling and better control over retry behavior.
 
 Supports three patterns:
 1. Simple handler: just the function (single message handler)
 2. Handler with prefetch: [handler, { prefetch: 10 }] (single message handler with config)
 3. Batch handler: [batchHandler, { batchSize: 5, batchTimeout: 1000 }] (REQUIRES batchSize config)
 
-**Important**: Batch handlers (handlers that accept an array of messages) MUST include
-batchSize configuration. You cannot create a batch handler without specifying batchSize.
-
 ##### Type Parameters
 
 | Type Parameter | Description |
@@ -845,70 +1403,313 @@ batchSize configuration. You cannot create a batch handler without specifying ba
 | ------ | ------ | ------ |
 | `contract` | `TContract` | The contract definition containing the consumer |
 | `consumerName` | `TName` | The name of the consumer from the contract |
-| `handler` | [`WorkerInferConsumerBatchHandler`](#workerinferconsumerbatchhandler)\<`TContract`, `TName`\> | The async handler function that processes messages (single or batch) |
-| `options` | \{ `batchSize`: `number`; `batchTimeout?`: `number`; `prefetch?`: `number`; \} | Optional consumer options (prefetch, batchSize, batchTimeout) - For single-message handlers: { prefetch?: number } is optional - For batch handlers: { batchSize: number, batchTimeout?: number } is REQUIRED |
+| `handler` | [`WorkerInferSafeConsumerBatchHandler`](#workerinfersafeconsumerbatchhandler)\<`TContract`, `TName`\> | The handler function that returns `Future<Result<void, HandlerError>>` |
+| `options` | \{ `batchSize`: `number`; `batchTimeout?`: `number`; `prefetch?`: `number`; \} | Optional consumer options (prefetch, batchSize, batchTimeout) |
 | `options.batchSize` | `number` | - |
 | `options.batchTimeout?` | `number` | - |
 | `options.prefetch?` | `number` | - |
 
 ##### Returns
 
-[`WorkerInferConsumerHandlerEntry`](#workerinferconsumerhandlerentry)\<`TContract`, `TName`\>
+[`WorkerInferSafeConsumerHandlerEntry`](#workerinfersafeconsumerhandlerentry)\<`TContract`, `TName`\>
 
 A type-safe handler that can be used with TypedAmqpWorker
 
 ##### Example
 
 ```typescript
-import { defineHandler } from '@amqp-contract/worker';
+import { defineHandler, RetryableError, NonRetryableError } from '@amqp-contract/worker';
+import { Future, Result } from '@swan-io/boxed';
 import { orderContract } from './contract';
 
-// Simple single-message handler without options
+// Simple handler with explicit error handling using mapError
 const processOrderHandler = defineHandler(
+  orderContract,
+  'processOrder',
+  (message) =>
+    Future.fromPromise(processPayment(message))
+      .mapOk(() => undefined)
+      .mapError((error) => new RetryableError('Payment failed', error))
+);
+
+// Handler with validation (non-retryable error)
+const validateOrderHandler = defineHandler(
+  orderContract,
+  'validateOrder',
+  (message) => {
+    if (message.amount < 1) {
+      // Won't be retried - goes directly to DLQ
+      return Future.value(Result.Error(new NonRetryableError('Invalid order amount')));
+    }
+    return Future.value(Result.Ok(undefined));
+  }
+);
+```
+
+***
+
+### defineHandlers()
+
+```ts
+function defineHandlers<TContract>(contract, handlers): WorkerInferSafeConsumerHandlers<TContract>;
+```
+
+Defined in: [packages/worker/src/handlers.ts:208](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/handlers.ts#L208)
+
+Define multiple type-safe handlers for consumers in a contract.
+
+**Recommended:** This function creates handlers that return `Future<Result<void, HandlerError>>`,
+providing explicit error handling and better control over retry behavior.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TContract` *extends* `ContractDefinition` | The contract definition type |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `contract` | `TContract` | The contract definition containing the consumers |
+| `handlers` | [`WorkerInferSafeConsumerHandlers`](#workerinfersafeconsumerhandlers)\<`TContract`\> | An object with handler functions for each consumer |
+
+#### Returns
+
+[`WorkerInferSafeConsumerHandlers`](#workerinfersafeconsumerhandlers)\<`TContract`\>
+
+A type-safe handlers object that can be used with TypedAmqpWorker
+
+#### Example
+
+```typescript
+import { defineHandlers, RetryableError } from '@amqp-contract/worker';
+import { Future } from '@swan-io/boxed';
+import { orderContract } from './contract';
+
+const handlers = defineHandlers(orderContract, {
+  processOrder: (message) =>
+    Future.fromPromise(processPayment(message))
+      .mapOk(() => undefined)
+      .mapError((error) => new RetryableError('Payment failed', error)),
+  notifyOrder: (message) =>
+    Future.fromPromise(sendNotification(message))
+      .mapOk(() => undefined)
+      .mapError((error) => new RetryableError('Notification failed', error)),
+});
+```
+
+***
+
+### ~~defineUnsafeHandler()~~
+
+#### Call Signature
+
+```ts
+function defineUnsafeHandler<TContract, TName>(
+   contract, 
+   consumerName, 
+handler): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
+```
+
+Defined in: [packages/worker/src/handlers.ts:272](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/handlers.ts#L272)
+
+Define an unsafe handler for a specific consumer in a contract.
+
+##### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TContract` *extends* `ContractDefinition` | The contract definition type |
+| `TName` *extends* `string` \| `number` \| `symbol` | The consumer name from the contract |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `contract` | `TContract` | The contract definition containing the consumer |
+| `consumerName` | `TName` | The name of the consumer from the contract |
+| `handler` | `UnsafeHandler`\<`TContract`, `TName`\> | The async handler function that processes messages |
+
+##### Returns
+
+[`WorkerInferSafeConsumerHandlerEntry`](#workerinfersafeconsumerhandlerentry)\<`TContract`, `TName`\>
+
+A type-safe handler that can be used with TypedAmqpWorker
+
+##### Deprecated
+
+Use `defineHandler` instead for explicit error handling with `Future<Result>`.
+
+**Warning:** Unsafe handlers use exception-based error handling:
+- All thrown errors are treated as retryable by default
+- Harder to reason about which errors should be retried
+- May lead to unexpected retry behavior
+
+**Note:** Internally, this function wraps the Promise-based handler into a Future-based
+safe handler for consistent processing in the worker.
+
+##### Example
+
+```typescript
+import { defineUnsafeHandler } from '@amqp-contract/worker';
+
+// ⚠️ Consider using defineHandler for better error handling
+const processOrderHandler = defineUnsafeHandler(
   orderContract,
   'processOrder',
   async (message) => {
-    console.log('Processing order:', message.orderId);
+    // Throws on error - will be retried
     await processPayment(message);
   }
 );
+```
+
+#### Call Signature
+
+```ts
+function defineUnsafeHandler<TContract, TName>(
+   contract, 
+   consumerName, 
+   handler, 
+options): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
+```
+
+Defined in: [packages/worker/src/handlers.ts:280](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/handlers.ts#L280)
+
+Define an unsafe handler for a specific consumer in a contract.
+
+##### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TContract` *extends* `ContractDefinition` | The contract definition type |
+| `TName` *extends* `string` \| `number` \| `symbol` | The consumer name from the contract |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `contract` | `TContract` | The contract definition containing the consumer |
+| `consumerName` | `TName` | The name of the consumer from the contract |
+| `handler` | `UnsafeHandler`\<`TContract`, `TName`\> | The async handler function that processes messages |
+| `options` | \{ `batchSize?`: `undefined`; `batchTimeout?`: `undefined`; `prefetch?`: `number`; \} | Optional consumer options (prefetch, batchSize, batchTimeout) |
+| `options.batchSize?` | `undefined` | - |
+| `options.batchTimeout?` | `undefined` | - |
+| `options.prefetch?` | `number` | - |
+
+##### Returns
+
+[`WorkerInferSafeConsumerHandlerEntry`](#workerinfersafeconsumerhandlerentry)\<`TContract`, `TName`\>
+
+A type-safe handler that can be used with TypedAmqpWorker
 
-// Single-message handler with prefetch
-const processOrderWithPrefetch = defineHandler(
+##### Deprecated
+
+Use `defineHandler` instead for explicit error handling with `Future<Result>`.
+
+**Warning:** Unsafe handlers use exception-based error handling:
+- All thrown errors are treated as retryable by default
+- Harder to reason about which errors should be retried
+- May lead to unexpected retry behavior
+
+**Note:** Internally, this function wraps the Promise-based handler into a Future-based
+safe handler for consistent processing in the worker.
+
+##### Example
+
+```typescript
+import { defineUnsafeHandler } from '@amqp-contract/worker';
+
+// ⚠️ Consider using defineHandler for better error handling
+const processOrderHandler = defineUnsafeHandler(
   orderContract,
   'processOrder',
   async (message) => {
-    await processOrder(message);
-  },
-  { prefetch: 10 }
+    // Throws on error - will be retried
+    await processPayment(message);
+  }
 );
+```
+
+#### Call Signature
+
+```ts
+function defineUnsafeHandler<TContract, TName>(
+   contract, 
+   consumerName, 
+   handler, 
+options): WorkerInferSafeConsumerHandlerEntry<TContract, TName>;
+```
+
+Defined in: [packages/worker/src/handlers.ts:289](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/handlers.ts#L289)
+
+Define an unsafe handler for a specific consumer in a contract.
+
+##### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `TContract` *extends* `ContractDefinition` | The contract definition type |
+| `TName` *extends* `string` \| `number` \| `symbol` | The consumer name from the contract |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `contract` | `TContract` | The contract definition containing the consumer |
+| `consumerName` | `TName` | The name of the consumer from the contract |
+| `handler` | `UnsafeBatchHandler`\<`TContract`, `TName`\> | The async handler function that processes messages |
+| `options` | \{ `batchSize`: `number`; `batchTimeout?`: `number`; `prefetch?`: `number`; \} | Optional consumer options (prefetch, batchSize, batchTimeout) |
+| `options.batchSize` | `number` | - |
+| `options.batchTimeout?` | `number` | - |
+| `options.prefetch?` | `number` | - |
+
+##### Returns
+
+[`WorkerInferSafeConsumerHandlerEntry`](#workerinfersafeconsumerhandlerentry)\<`TContract`, `TName`\>
+
+A type-safe handler that can be used with TypedAmqpWorker
+
+##### Deprecated
+
+Use `defineHandler` instead for explicit error handling with `Future<Result>`.
+
+**Warning:** Unsafe handlers use exception-based error handling:
+- All thrown errors are treated as retryable by default
+- Harder to reason about which errors should be retried
+- May lead to unexpected retry behavior
+
+**Note:** Internally, this function wraps the Promise-based handler into a Future-based
+safe handler for consistent processing in the worker.
 
-// Batch handler - MUST include batchSize
-const processBatchOrders = defineHandler(
+##### Example
+
+```typescript
+import { defineUnsafeHandler } from '@amqp-contract/worker';
+
+// ⚠️ Consider using defineHandler for better error handling
+const processOrderHandler = defineUnsafeHandler(
   orderContract,
-  'processOrders',
-  async (messages) => {
-    // messages is an array - batchSize configuration is REQUIRED
-    await db.insertMany(messages);
-  },
-  { batchSize: 5, batchTimeout: 1000 }
+  'processOrder',
+  async (message) => {
+    // Throws on error - will be retried
+    await processPayment(message);
+  }
 );
 ```
 
 ***
 
-### defineHandlers()
+### ~~defineUnsafeHandlers()~~
 
 ```ts
-function defineHandlers<TContract>(contract, handlers): WorkerInferConsumerHandlers<TContract>;
+function defineUnsafeHandlers<TContract>(contract, handlers): WorkerInferSafeConsumerHandlers<TContract>;
 ```
 
-Defined in: [packages/worker/src/handlers.ts:181](https://github.com/btravers/amqp-contract/blob/382c6d2fbfc563c9f6f16cb71cb33fd4a3d41d77/packages/worker/src/handlers.ts#L181)
-
-Define multiple type-safe handlers for consumers in a contract.
+Defined in: [packages/worker/src/handlers.ts:373](https://github.com/btravers/amqp-contract/blob/f058a24938d9644a82812e57d7995cb683cfd6b5/packages/worker/src/handlers.ts#L373)
 
-This utility allows you to define all handlers at once outside of the worker creation,
-ensuring type safety and providing better code organization.
+Define multiple unsafe handlers for consumers in a contract.
 
 #### Type Parameters
 
@@ -921,55 +1722,36 @@ ensuring type safety and providing better code organization.
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
 | `contract` | `TContract` | The contract definition containing the consumers |
-| `handlers` | [`WorkerInferConsumerHandlers`](#workerinferconsumerhandlers)\<`TContract`\> | An object with async handler functions for each consumer |
+| `handlers` | `UnsafeHandlers`\<`TContract`\> | An object with async handler functions for each consumer |
 
 #### Returns
 
-[`WorkerInferConsumerHandlers`](#workerinferconsumerhandlers)\<`TContract`\>
+[`WorkerInferSafeConsumerHandlers`](#workerinfersafeconsumerhandlers)\<`TContract`\>
 
 A type-safe handlers object that can be used with TypedAmqpWorker
 
-#### Examples
+#### Deprecated
+
+Use `defineHandlers` instead for explicit error handling with `Future<Result>`.
+
+**Warning:** Unsafe handlers use exception-based error handling.
+Consider migrating to safe handlers for better error control.
+
+**Note:** Internally, this function wraps all Promise-based handlers into Future-based
+safe handlers for consistent processing in the worker.
+
+#### Example
 
 ```typescript
-import { defineHandlers } from '@amqp-contract/worker';
-import { orderContract } from './contract';
+import { defineUnsafeHandlers } from '@amqp-contract/worker';
 
-// Define all handlers at once
-const handlers = defineHandlers(orderContract, {
+// ⚠️ Consider using defineHandlers for better error handling
+const handlers = defineUnsafeHandlers(orderContract, {
   processOrder: async (message) => {
-    // message is fully typed based on the contract
-    console.log('Processing order:', message.orderId);
     await processPayment(message);
   },
   notifyOrder: async (message) => {
     await sendNotification(message);
   },
-  shipOrder: async (message) => {
-    await prepareShipment(message);
-  },
-});
-
-// Use the handlers in worker
-const worker = await TypedAmqpWorker.create({
-  contract: orderContract,
-  handlers,
-  connection: 'amqp://localhost',
-});
-```
-
-```typescript
-// Separate handler definitions for better organization
-async function handleProcessOrder(message: WorkerInferConsumerInput<typeof orderContract, 'processOrder'>) {
-  await processOrder(message);
-}
-
-async function handleNotifyOrder(message: WorkerInferConsumerInput<typeof orderContract, 'notifyOrder'>) {
-  await sendNotification(message);
-}
-
-const handlers = defineHandlers(orderContract, {
-  processOrder: handleProcessOrder,
-  notifyOrder: handleNotifyOrder,
 });
 ```