@amqp-contract/worker 0.10.0 → 0.11.0

package/README.md

@@ -30,8 +30,9 @@ pnpm add @amqp-contract/worker
 ### Basic Usage
 
 ```typescript
-import { TypedAmqpWorker } from "@amqp-contract/worker";
+import { TypedAmqpWorker, RetryableError } from "@amqp-contract/worker";
 import type { Logger } from "@amqp-contract/core";
+import { Future } from "@swan-io/boxed";
 import { contract } from "./contract";
 
 // Optional: Create a logger implementation
@@ -46,14 +47,13 @@ const logger: Logger = {
 const worker = await TypedAmqpWorker.create({
   contract,
   handlers: {
-    processOrder: async (message) => {
-      console.log("Processing order:", message.orderId);
+    processOrder: ({ payload }) => {
+      console.log("Processing order:", payload.orderId);
 
       // Your business logic here
-      await processPayment(message);
-      await updateInventory(message);
-
-      // If an exception is thrown, the message is automatically requeued
+      return Future.fromPromise(Promise.all([processPayment(payload), updateInventory(payload)]))
+        .mapOk(() => undefined)
+        .mapError((error) => new RetryableError("Order processing failed", error));
     },
   },
   urls: ["amqp://localhost"],
@@ -72,25 +72,43 @@ For advanced features like prefetch configuration, batch processing, and **autom
 
 #### Retry with Exponential Backoff
 
-Enable automatic retry for failed messages:
+Retry is configured at the queue level in your contract definition. Add `retry` to your queue definition:
+
+```typescript
+import { defineQueue, defineExchange, defineContract } from "@amqp-contract/contract";
+
+const dlx = defineExchange("orders-dlx", "topic", { durable: true });
+
+// Configure retry at queue level
+const orderQueue = defineQueue("order-processing", {
+  deadLetter: { exchange: dlx },
+  retry: {
+    mode: "ttl-backoff",
+    maxRetries: 3, // Retry up to 3 times (default: 3)
+    initialDelayMs: 1000, // Start with 1 second delay (default: 1000)
+    maxDelayMs: 30000, // Max 30 seconds between retries (default: 30000)
+    backoffMultiplier: 2, // Double the delay each time (default: 2)
+    jitter: true, // Add randomness to prevent thundering herd (default: true)
+  },
+});
+```
+
+Then use `RetryableError` in your handlers:
 
 ```typescript
+import { TypedAmqpWorker, RetryableError } from "@amqp-contract/worker";
+import { Future } from "@swan-io/boxed";
+
 const worker = await TypedAmqpWorker.create({
   contract,
   handlers: {
-    processOrder: async (message) => {
-      // If this throws, message is automatically retried with exponential backoff
-      await processPayment(message);
-    },
+    processOrder: ({ payload }) =>
+      // If this fails with RetryableError, message is automatically retried
+      Future.fromPromise(processPayment(payload))
+        .mapOk(() => undefined)
+        .mapError((error) => new RetryableError("Payment failed", error)),
   },
   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
-  },
 });
 ```
 
@@ -102,22 +120,24 @@ You can define handlers outside of the worker creation using `defineHandler` and
 
 ## Error Handling
 
-Worker handlers use standard Promise-based async/await pattern:
+Worker handlers return `Future<Result<void, HandlerError>>` for explicit error handling:
 
 ```typescript
+import { RetryableError, NonRetryableError } from "@amqp-contract/worker";
+import { Future, Result } from "@swan-io/boxed";
+
 handlers: {
-  processOrder: async (message) => {
-    // Standard async/await - no Result wrapping needed
-    try {
-      await process(message);
-      // Message acknowledged automatically on success
-    } catch (error) {
-      // Exception automatically caught by worker
-      // With retry configured: message is retried with exponential backoff
-      // Without retry: message is immediately requeued
-      throw error;
+  processOrder: ({ payload }) => {
+    // Validation errors - non-retryable
+    if (payload.amount <= 0) {
+      return Future.value(Result.Error(new NonRetryableError("Invalid amount")));
     }
-  };
+
+    // Transient errors - retryable
+    return Future.fromPromise(process(payload))
+      .mapOk(() => undefined)
+      .mapError((error) => new RetryableError("Processing failed", error));
+  },
 }
 ```
 
@@ -127,9 +147,8 @@ 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)
-
-**Handlers don't need to use these error classes** - just throw standard exceptions. The worker handles retry automatically based on your configuration.
+- `RetryableError` - Signals that the error is transient and should be retried
+- `NonRetryableError` - Signals permanent failure, message goes to DLQ
 
 ## API