@amqp-contract/worker 0.6.0 → 0.8.0

package/README.md

@@ -20,6 +20,7 @@ pnpm add @amqp-contract/worker
 
 - ✅ **Type-safe message consumption** — Handlers are fully typed based on your contract
 - ✅ **Automatic validation** — Messages are validated before reaching your handlers
+- ✅ **Automatic retry with exponential backoff** — Built-in retry mechanism using RabbitMQ TTL+DLX pattern
 - ✅ **Prefetch configuration** — Control message flow with per-consumer prefetch settings
 - ✅ **Batch processing** — Process multiple messages at once for better throughput
 - ✅ **Automatic reconnection** — Built-in connection management with failover support
@@ -29,9 +30,9 @@ pnpm add @amqp-contract/worker
 ### Basic Usage
 
 ```typescript
-import { TypedAmqpWorker } from '@amqp-contract/worker';
-import type { Logger } from '@amqp-contract/core';
-import { contract } from './contract';
+import { TypedAmqpWorker } from "@amqp-contract/worker";
+import type { Logger } from "@amqp-contract/core";
+import { contract } from "./contract";
 
 // Optional: Create a logger implementation
 const logger: Logger = {
@@ -46,7 +47,7 @@ const worker = await TypedAmqpWorker.create({
   contract,
   handlers: {
     processOrder: async (message) => {
-      console.log('Processing order:', message.orderId);
+      console.log("Processing order:", message.orderId);
 
       // Your business logic here
       await processPayment(message);
@@ -55,7 +56,7 @@ const worker = await TypedAmqpWorker.create({
       // If an exception is thrown, the message is automatically requeued
     },
   },
-  urls: ['amqp://localhost'],
+  urls: ["amqp://localhost"],
   logger, // Optional: logs message consumption and errors
 });
 
@@ -67,7 +68,33 @@ const worker = await TypedAmqpWorker.create({
 
 ### Advanced Features
 
-For advanced features like prefetch configuration and batch processing, see the [Worker Usage Guide](https://btravers.github.io/amqp-contract/guide/worker-usage).
+For advanced features like prefetch configuration, batch processing, and **automatic retry with exponential backoff**, see the [Worker Usage Guide](https://btravers.github.io/amqp-contract/guide/worker-usage).
+
+#### Retry with Exponential Backoff
+
+Enable automatic retry for failed messages:
+
+```typescript
+const worker = await TypedAmqpWorker.create({
+  contract,
+  handlers: {
+    processOrder: async (message) => {
+      // If this throws, message is automatically retried with exponential backoff
+      await processPayment(message);
+    },
+  },
+  urls: ["amqp://localhost"],
+  retry: {
+    maxRetries: 3, // Retry up to 3 times
+    initialDelayMs: 1000, // Start with 1 second delay
+    maxDelayMs: 30000, // Max 30 seconds between retries
+    backoffMultiplier: 2, // Double the delay each time
+    jitter: true, // Add randomness to prevent thundering herd
+  },
+});
+```
+
+The retry mechanism uses RabbitMQ's native TTL and Dead Letter Exchange pattern, so it doesn't block the consumer during retry delays. See the [Error Handling and Retry](https://btravers.github.io/amqp-contract/guide/worker-usage#error-handling-and-retry) section in the guide for complete details.
 
 ## Defining Handlers Externally
 
@@ -86,21 +113,23 @@ handlers: {
       // Message acknowledged automatically on success
     } catch (error) {
       // Exception automatically caught by worker
-      // Message is requeued for retry
+      // With retry configured: message is retried with exponential backoff
+      // Without retry: message is immediately requeued
       throw error;
     }
-  }
+  };
 }
 ```
 
 **Error Types:**
 
-Worker defines error classes for internal use:
+Worker defines error classes:
 
 - `TechnicalError` - Runtime failures (parsing, processing)
 - `MessageValidationError` - Message fails schema validation
+- `RetryableError` - Optional error class for explicit retry signaling (all errors are retryable by default when retry is configured)
 
-These errors are logged but **handlers don't need to use them** - just throw standard exceptions.
+**Handlers don't need to use these error classes** - just throw standard exceptions. The worker handles retry automatically based on your configuration.
 
 ## API