@lindorm/iris 0.1.1 → 0.2.0

package/README.md

@@ -92,6 +92,73 @@ await source.drain();
 await source.disconnect();
 ```
 
+## Table of Contents
+
+- [Messaging Patterns](#messaging-patterns)
+  - [Publisher (Fire-and-Forget)](#publisher-fire-and-forget)
+  - [Message Bus (Pub/Sub + Queues)](#message-bus-pubsub--queues)
+  - [Worker Queue (Competing Consumers)](#worker-queue-competing-consumers)
+  - [RPC (Request/Response)](#rpc-requestresponse)
+  - [Stream Processor (Pipelines)](#stream-processor-pipelines)
+- [Field Types](#field-types)
+- [Decorators](#decorators)
+  - [Class-Level Decorators](#class-level-decorators)
+    - [`@Message`](#message)
+    - [`@AbstractMessage`](#abstractmessage)
+    - [`@Namespace`](#namespace)
+    - [`@Version`](#version)
+    - [`@Topic`](#topic)
+    - [`@Broadcast`](#broadcast)
+    - [`@Persistent`](#persistent)
+    - [`@Priority`](#priority)
+    - [`@Delay`](#delay)
+    - [`@Expiry`](#expiry)
+    - [`@Encrypted`](#encrypted)
+    - [`@Compressed`](#compressed)
+    - [`@Retry`](#retry)
+    - [`@DeadLetter`](#deadletter)
+  - [Field Decorators](#field-decorators)
+    - [`@Field`](#field)
+    - [`@IdentifierField`](#identifierfield)
+    - [`@CorrelationField`](#correlationfield)
+    - [`@TimestampField`](#timestampfield)
+    - [`@MandatoryField`](#mandatoryfield)
+    - [`@PersistentField`](#persistentfield)
+  - [Field Modifiers](#field-modifiers)
+    - [`@Generated`](#generated)
+    - [`@Header`](#header)
+    - [`@Enum`](#enum)
+    - [`@Min` / `@Max`](#min--max)
+    - [`@Schema`](#schema)
+    - [`@Transform`](#transform)
+  - [Lifecycle Hook Decorators](#lifecycle-hook-decorators)
+    - [`@OnCreate`](#oncreate)
+    - [`@OnHydrate`](#onhydrate)
+    - [`@OnValidate`](#onvalidate)
+    - [`@BeforePublish` / `@AfterPublish`](#beforepublish--afterpublish)
+    - [`@BeforeConsume` / `@AfterConsume`](#beforeconsume--afterconsume)
+    - [`@OnConsumeError`](#onconsumeerror)
+- [Retry and Dead Letter](#retry-and-dead-letter)
+- [Dynamic Topics](#dynamic-topics)
+- [Encryption and Compression](#encryption-and-compression)
+- [Message Subscribers](#message-subscribers)
+- [Hook Execution Order](#hook-execution-order)
+- [Consume Envelope](#consume-envelope)
+- [Message Manipulation](#message-manipulation)
+- [Publish Options](#publish-options)
+- [Zod Validation](#zod-validation)
+- [Cloning](#cloning)
+- [Driver Configuration](#driver-configuration)
+  - [Memory](#memory)
+  - [RabbitMQ](#rabbitmq)
+  - [Kafka](#kafka)
+  - [NATS](#nats)
+  - [Redis Streams](#redis-streams)
+- [Persistence (Delay and Dead Letter Stores)](#persistence-delay-and-dead-letter-stores)
+- [Connection State](#connection-state)
+- [Testing with Mocks](#testing-with-mocks)
+- [Error Classes](#error-classes)
+
 ## Messaging Patterns
 
 ### Publisher (Fire-and-Forget)
@@ -190,141 +257,794 @@ await server.serve(async (req) => {
   return res;
 });
 
-// Client: send request
-const req = new GetPrice();
-req.sku = "WIDGET-42";
+// Client: send request
+const req = new GetPrice();
+req.sku = "WIDGET-42";
+
+const res = await client.request(req);
+console.log(`${res.price} ${res.currency}`); // 29.99 USD
+
+// With timeout
+const res2 = await client.request(req, { timeout: 5000 });
+
+// Clean up
+await client.close();
+await server.unserveAll();
+```
+
+### Stream Processor (Pipelines)
+
+Declarative stream processing with an immutable builder pattern.
+
+```typescript
+@Message()
+class RawEvent {
+  @Field("string") type!: string;
+  @Field("float") value!: number;
+}
+
+@Message()
+class AggregatedEvent {
+  @Field("float") sum!: number;
+  @Field("integer") count!: number;
+}
+
+const pipeline = source
+  .stream()
+  .from(RawEvent)
+  .filter((msg) => msg.value > 0)
+  .map((msg) => {
+    const out = new AggregatedEvent();
+    out.sum = msg.value;
+    out.count = 1;
+    return out;
+  })
+  .to(AggregatedEvent);
+
+await pipeline.start();
+// pipeline.isRunning() === true
+
+await pipeline.pause();
+await pipeline.resume();
+await pipeline.stop();
+```
+
+## Field Types
+
+The `@Field()` decorator accepts the following type identifiers:
+
+| Category       | Types                            |
+| -------------- | -------------------------------- |
+| Boolean        | `boolean`                        |
+| Integer        | `integer`, `bigint`              |
+| Floating Point | `float`                          |
+| String         | `string`, `email`, `url`, `uuid` |
+| Enum           | `enum`                           |
+| Date/Time      | `date`                           |
+| Structured     | `object`, `array`                |
+
+```typescript
+@Message()
+class FullExample {
+  @IdentifierField() id!: string;
+  @CorrelationField() correlationId!: string;
+  @TimestampField() createdAt!: Date;
+
+  @Field("string") name!: string;
+  @Field("integer") count!: number;
+  @Field("float") price!: number;
+  @Field("boolean") active!: boolean;
+  @Field("date") expiresAt!: Date;
+  @Field("uuid") referenceId!: string;
+  @Field("email") contactEmail!: string;
+  @Field("url") callbackUrl!: string;
+  @Field("array") tags!: Array<string>;
+  @Field("object") metadata!: Record<string, unknown>;
+
+  @Field("string", { nullable: true }) description!: string | null;
+  @Field("string", { optional: true }) nickname?: string;
+  @Field("integer", { default: 0 }) retryCount!: number;
+  @Field("string", { default: () => "generated" }) code!: string;
+}
+```
+
+## Decorators
+
+All decorators use the TC39 (stage 3) decorator specification. Class decorators receive `ClassDecoratorContext`, field decorators receive `ClassFieldDecoratorContext`. Metadata flows through the `Symbol.metadata` prototype chain, so abstract base class decorators are inherited by concrete subclasses.
+
+### Class-Level Decorators
+
+These decorators are applied to classes and configure message-wide behavior.
+
+#### `@Message`
+
+Marks a class as a concrete message type registered in the global message registry. Every message class must have exactly one of `@Message` or `@AbstractMessage`.
+
+```typescript
+@Message()
+class OrderPlaced {
+  /* ... */
+}
+
+@Message({ name: "order-placed" }) // custom message name
+class OrderPlaced {
+  /* ... */
+}
+```
+
+**Options:** `{ name?: string }` — Override the message name. Defaults to the class name with any trailing version suffix (`_v1`, `_V2`) stripped. Must not conflict with other registered message names.
+
+#### `@AbstractMessage`
+
+Marks a class as an abstract message base. It is **not** registered in the global message registry. Fields, hooks, and metadata are inherited by `@Message()` subclasses via the `Symbol.metadata` prototype chain.
+
+```typescript
+@AbstractMessage()
+class BaseEvent {
+  @IdentifierField() id!: string;
+  @TimestampField() createdAt!: Date;
+}
+
+@Message()
+@Namespace("orders")
+class OrderPlaced extends BaseEvent {
+  @Field("string") orderId!: string;
+}
+```
+
+Cannot be combined with `@Message` on the same class.
+
+#### `@Namespace`
+
+Places the message in a named namespace for logical grouping and routing.
+
+```typescript
+@Namespace("orders")
+@Message()
+class OrderPlaced {
+  /* ... */
+}
+```
+
+**Argument:** `string` — must be non-empty. Throws `IrisMetadataError` if empty or whitespace-only.
+
+#### `@Version`
+
+Sets the message schema version. Useful for evolving message formats while maintaining backward compatibility.
+
+```typescript
+@Version(1)
+@Message()
+class OrderPlaced {
+  /* ... */
+}
+```
+
+**Argument:** `number` — must be a positive integer (>= 1). Throws `IrisMetadataError` otherwise.
+
+#### `@Topic`
+
+Provides a dynamic topic resolution callback. Instead of using the message class name as the topic, the callback computes the topic from the message content at publish time.
+
+```typescript
+@Topic((msg: any) => `events.${msg.region}.${msg.type}`)
+@Message()
+class RegionalEvent {
+  @Field("string") region!: string;
+  @Field("string") type!: string;
+}
+```
+
+**Argument:** `(message: any) => string` — receives the message instance, returns the routing topic string.
+
+#### `@Broadcast`
+
+Marks a message for broadcast delivery. When published, the message is delivered to **all** subscribers rather than being distributed round-robin to one consumer per queue.
+
+```typescript
+@Broadcast()
+@Message()
+class SystemNotification {
+  @Field("string") text!: string;
+}
+```
+
+No arguments.
+
+#### `@Persistent`
+
+Marks a message as persistent/durable. Persistent messages survive broker restarts (where supported by the driver).
+
+```typescript
+@Persistent()
+@Message()
+class PaymentCharge {
+  @Field("string") chargeId!: string;
+}
+```
+
+No arguments.
+
+#### `@Priority`
+
+Sets the default priority for a message type. Higher priority messages are delivered before lower priority ones (where supported by the driver).
+
+```typescript
+@Priority(8)
+@Message()
+class UrgentAlert {
+  @Field("string") text!: string;
+}
+```
+
+**Argument:** `number` — integer between 0 and 10 inclusive. Throws `IrisMetadataError` if out of range or not an integer.
+
+#### `@Delay`
+
+Sets a default delivery delay. The message is held for the specified duration before being delivered to consumers.
+
+```typescript
+@Delay(5000) // 5 seconds
+@Message()
+class ScheduledReminder {
+  @Field("string") text!: string;
+}
+```
+
+**Argument:** `number` — non-negative integer in milliseconds. Throws `IrisMetadataError` if negative or not an integer.
+
+Can be overridden per-publish via `PublishOptions.delay`.
+
+#### `@Expiry`
+
+Sets a default message TTL (time-to-live). Messages that are not consumed within this window are discarded.
+
+```typescript
+@Expiry(60000) // 1 minute
+@Message()
+class TemporaryOffer {
+  @Field("float") discount!: number;
+}
+```
+
+**Argument:** `number` — non-negative integer in milliseconds. Throws `IrisMetadataError` if negative or not an integer.
+
+Can be overridden per-publish via `PublishOptions.expiry`.
+
+#### `@Encrypted`
+
+Enables payload encryption via `@lindorm/amphora`. The entire message payload is encrypted before publishing and decrypted on consume. Requires an `IAmphora` instance configured on `IrisSource`.
+
+```typescript
+@Encrypted() // encrypt with any available key
+@Message()
+class SensitivePayload {
+  @Field("string") ssn!: string;
+}
+
+@Encrypted({ purpose: "pii" }) // filter keys by purpose
+@Message()
+class MedicalRecord {
+  @Field("json") data!: Record<string, unknown>;
+}
+```
+
+**Argument:** `AmphoraPredicate` (optional, defaults to `{}`) — a predicate object to filter which encryption key to use from the key store. Supports fields like `algorithm`, `encryption`, `purpose`, `type`, `ownerId`, and standard predicate operators (`$eq`, `$in`, `$neq`, etc.).
+
+#### `@Compressed`
+
+Enables payload compression before publishing and decompression on consume.
+
+```typescript
+@Compressed() // gzip (default)
+@Compressed("brotli") // brotli compression
+@Message()
+class LargePayload {
+  @Field("object") data!: Record<string, unknown>;
+}
+```
+
+**Argument:** `"gzip" | "deflate" | "brotli"` (optional, defaults to `"gzip"`).
+
+When combined with `@Encrypted`, compression is applied first, then encryption.
+
+#### `@Retry`
+
+Configures automatic retry behavior when a consume callback throws. Failed messages are retried with configurable backoff strategies.
+
+```typescript
+@Retry() // defaults: 3 retries, constant 1s delay
+@Message()
+class ProcessOrder {
+  @Field("string") orderId!: string;
+}
+
+@Retry({
+  maxRetries: 5,
+  strategy: "exponential",
+  delay: 1000,
+  delayMax: 30000,
+  multiplier: 2,
+  jitter: true,
+})
+@Message()
+class PaymentCharge {
+  @Field("string") chargeId!: string;
+}
+```
+
+**Options:**
+
+| Field        | Type                                          | Default      | Description                               |
+| ------------ | --------------------------------------------- | ------------ | ----------------------------------------- |
+| `maxRetries` | `number`                                      | `3`          | Maximum number of retry attempts          |
+| `strategy`   | `"constant"` \| `"linear"` \| `"exponential"` | `"constant"` | Backoff strategy                          |
+| `delay`      | `number`                                      | `1000`       | Initial delay in milliseconds             |
+| `delayMax`   | `number`                                      | `30000`      | Maximum delay cap in milliseconds         |
+| `multiplier` | `number`                                      | `2`          | Multiplier for exponential backoff        |
+| `jitter`     | `boolean`                                     | `false`      | Add randomness to prevent thundering herd |
+
+**Retry strategies:**
+
+| Strategy        | Delay pattern (base=1000, multiplier=2)     |
+| --------------- | ------------------------------------------- |
+| `"constant"`    | 1000, 1000, 1000, ...                       |
+| `"linear"`      | 1000, 2000, 3000, ...                       |
+| `"exponential"` | 1000, 2000, 4000, 8000, ... (capped at max) |
+
+#### `@DeadLetter`
+
+Routes messages that have exhausted all retry attempts to the dead letter store. Requires `@Retry` and a dead letter store configured via `IrisSource.persistence.deadLetter`.
+
+```typescript
+@Retry({ maxRetries: 3 })
+@DeadLetter()
+@Message()
+class PaymentCharge {
+  @Field("string") chargeId!: string;
+}
+```
+
+No arguments.
+
+---
+
+### Field Decorators
+
+These decorators are applied to class properties and declare message fields. Each field decorator creates a complete field definition with its type, default value, and nullability.
+
+#### `@Field`
+
+The foundational field decorator. Declares a message field with an explicit type.
+
+```typescript
+@Field("string")
+name!: string;
+
+@Field("integer")
+count!: number;
+
+@Field("float")
+price!: number;
+
+@Field("boolean")
+active!: boolean;
+
+@Field("date")
+expiresAt!: Date;
+
+@Field("uuid")
+referenceId!: string;
+
+@Field("email")
+contactEmail!: string;
+
+@Field("url")
+callbackUrl!: string;
+
+@Field("array")
+tags!: Array<string>;
+
+@Field("object")
+metadata!: Record<string, unknown>;
+```
+
+**Arguments:** `(type: MetaFieldType, options?: FieldDecoratorOptions)`.
+
+**Options:**
+
+| Field       | Type                             | Default | Description                               |
+| ----------- | -------------------------------- | ------- | ----------------------------------------- |
+| `nullable`  | `boolean`                        | `false` | Allow `null` values                       |
+| `optional`  | `boolean`                        | `false` | Field may be omitted                      |
+| `default`   | `value \| (() => value) \| null` | `null`  | Default value applied on create           |
+| `transform` | `MetaTransform \| null`          | `null`  | Inline serialisation/deserialisation pair |
+
+```typescript
+@Field("string", { nullable: true })
+description!: string | null;
+
+@Field("string", { optional: true })
+nickname?: string;
+
+@Field("integer", { default: 0 })
+retryCount!: number;
+
+@Field("string", { default: () => "generated" })
+code!: string;
+
+@Field("float", {
+  transform: {
+    to: (value: number) => Math.round(value * 100),
+    from: (raw: number) => raw / 100,
+  },
+})
+price!: number;
+```
+
+#### `@IdentifierField`
+
+Shorthand for a UUID primary identifier field. Auto-generates a UUID v4 on message creation.
+
+```typescript
+@IdentifierField()
+id!: string;
+```
+
+Equivalent to `@Field("uuid", { default: () => randomUUID() })`. Non-nullable, non-optional.
+
+No arguments.
+
+#### `@CorrelationField`
+
+Shorthand for a UUID correlation tracking field. Auto-generates a UUID v4 on message creation. Used to trace related messages across publish/consume chains.
+
+```typescript
+@CorrelationField()
+correlationId!: string;
+```
+
+Equivalent to `@Field("uuid", { default: () => randomUUID() })`. Non-nullable, non-optional.
+
+No arguments.
+
+#### `@TimestampField`
+
+Shorthand for a timestamp field. Auto-generates the current `Date` on message creation.
+
+```typescript
+@TimestampField()
+createdAt!: Date;
+```
+
+Equivalent to `@Field("date", { default: () => new Date() })`. Non-nullable, non-optional.
+
+No arguments.
+
+#### `@MandatoryField`
+
+Shorthand for a boolean flag that defaults to `false`. Commonly used for acknowledgement or processing flags.
+
+```typescript
+@MandatoryField()
+requiresApproval!: boolean;
+```
+
+Equivalent to `@Field("boolean", { default: false })`. Non-nullable, non-optional.
+
+No arguments.
+
+#### `@PersistentField`
+
+Shorthand for a boolean persistence flag that defaults to `false`. Commonly used to mark whether a message should be durably stored.
+
+```typescript
+@PersistentField()
+shouldPersist!: boolean;
+```
+
+Equivalent to `@Field("boolean", { default: false })`. Non-nullable, non-optional.
+
+No arguments.
+
+---
+
+### Field Modifiers
+
+These decorators modify the behavior of a field declared with `@Field` or one of the shorthand field decorators. Stack them on the same property. Modifier decorators must appear alongside a field decorator on the same property.
+
+#### `@Generated`
+
+Marks a field for automatic value generation on message creation.
+
+```typescript
+@Generated("uuid")                   // UUID v4
+@Field("uuid")
+traceId!: string;
+
+@Generated("date")                   // current timestamp
+@Field("date")
+processedAt!: Date;
+
+@Generated("string")                 // random string (default length)
+@Field("string")
+token!: string;
+
+@Generated("string", { length: 12 }) // random string with custom length
+@Field("string")
+shortCode!: string;
+
+@Generated("integer", { min: 1, max: 1000 })
+@Field("integer")
+sequenceNumber!: number;
+
+@Generated("float", { min: 0.0, max: 1.0 })
+@Field("float")
+weight!: number;
+```
+
+**Arguments:** `(strategy: MetaGeneratedStrategy, options?: GeneratedDecoratorOptions)`.
+
+**Strategies:**
+
+| Strategy    | Description                              |
+| ----------- | ---------------------------------------- |
+| `"uuid"`    | Generate UUID v4                         |
+| `"date"`    | Current timestamp                        |
+| `"string"`  | Random string with configurable `length` |
+| `"integer"` | Random integer in `[min, max]` range     |
+| `"float"`   | Random float in `[min, max]` range       |
+
+**Options:** `{ length?: number, min?: number, max?: number }` — all optional, all default to `null`.
+
+#### `@Header`
+
+Promotes a field value to a message header. Headers are transported as key-value metadata alongside the payload, accessible without deserialising the full message body.
+
+```typescript
+@Header()              // header name = property name ("source")
+@Field("string")
+source!: string;
+
+@Header("x-trace-id") // explicit header name
+@Field("uuid")
+traceId!: string;
+```
+
+**Argument:** `string?` — custom header name. Defaults to the property name. Throws `IrisMetadataError` if the resolved name is empty or whitespace-only.
+
+#### `@Enum`
+
+Restricts a field to a fixed set of allowed values. Pass a TypeScript enum or a plain `Record<string, string | number>`. Enforced during Zod validation.
+
+```typescript
+enum OrderStatus {
+  Pending = "pending",
+  Shipped = "shipped",
+  Delivered = "delivered",
+}
+
+@Enum(OrderStatus)
+@Field("enum")
+status!: OrderStatus;
+```
+
+**Argument:** `Record<string, string | number>` — the enum object or value map.
+
+#### `@Min` / `@Max`
+
+Set minimum/maximum bounds for numeric fields or minimum/maximum length for string fields. Enforced during Zod validation.
+
+```typescript
+@Min(0)
+@Max(100)
+@Field("integer")
+score!: number;
+
+@Min(1)
+@Max(255)
+@Field("string")
+name!: string;
+```
+
+**Argument:** `number`.
+
+#### `@Schema`
+
+Attaches a Zod schema for fine-grained field validation. The schema is evaluated during message validation.
+
+```typescript
+import { z } from "zod";
+
+@Schema(z.string().email())
+@Field("email")
+email!: string;
+
+@Schema(z.number().int().min(13).max(150))
+@Field("integer")
+age!: number;
+
+@Schema(z.string().regex(/^[A-Z]{2,3}$/))
+@Field("string")
+countryCode!: string;
+```
+
+**Argument:** `z.ZodType` — any Zod schema.
+
+#### `@Transform`
+
+Applies a bidirectional transform to a field value. `to` runs during serialisation (message -> transport), `from` runs during deserialisation (transport -> message).
+
+```typescript
+@Transform({
+  to: (value: string[]) => value.join(","),
+  from: (raw: string) => raw.split(","),
+})
+@Field("string")
+tags!: string[];
+
+@Transform<Date, number>({
+  to: (date) => date.getTime(),
+  from: (ms) => new Date(ms),
+})
+@Field("bigint")
+timestamp!: Date;
+```
+
+**Options:** `{ to: (value: TFrom) => TTo, from: (raw: TTo) => TFrom }`.
+
+This is a standalone decorator that uses a separate staging path. For inline transforms, use the `transform` option on `@Field` instead.
+
+---
+
+### Lifecycle Hook Decorators
 
-const res = await client.request(req);
-console.log(`${res.price} ${res.currency}`); // 29.99 USD
+Lifecycle hooks are **class decorators** that register callbacks at specific points in the message lifecycle. All hooks receive `(message, context?)` as arguments, where `context` is the source's context value.
 
-// With timeout
-const res2 = await client.request(req, { timeout: 5000 });
+Hooks may be async (`void | Promise<void>`) unless otherwise noted.
 
-// Clean up
-await client.close();
-await server.unserveAll();
+#### `@OnCreate`
+
+Fires when a message instance is created via `create()`. Useful for setting computed defaults or derived fields.
+
+```typescript
+@OnCreate((msg) => {
+  msg.slug = msg.name.toLowerCase().replace(/\s+/g, "-");
+})
+@Message()
+class OrderPlaced {
+  @Field("string") name!: string;
+  @Field("string") slug!: string;
+}
 ```
 
-### Stream Processor (Pipelines)
+**Argument:** `(message: M, context?: C) => void | Promise<void>`.
 
-Declarative stream processing with an immutable builder pattern.
+#### `@OnHydrate`
+
+Fires when a message is rehydrated from raw transport data, after all fields are populated but before the message is returned to the consume callback.
 
 ```typescript
+@OnHydrate((msg) => {
+  msg.displayName = `${msg.firstName} ${msg.lastName}`;
+})
 @Message()
-class RawEvent {
-  @Field("string") type!: string;
-  @Field("float") value!: number;
+class UserEvent {
+  @Field("string") firstName!: string;
+  @Field("string") lastName!: string;
+  @Field("string") displayName!: string;
 }
+```
+
+**Argument:** `(message: M, context?: C) => void | Promise<void>`.
+
+#### `@OnValidate`
 
+Fires during message validation, after the built-in Zod schema check. Throw to reject the message.
+
+```typescript
+@OnValidate((msg) => {
+  if (msg.startDate >= msg.endDate) {
+    throw new Error("startDate must be before endDate");
+  }
+})
 @Message()
-class AggregatedEvent {
-  @Field("float") sum!: number;
-  @Field("integer") count!: number;
+class BookingRequest {
+  @Field("date") startDate!: Date;
+  @Field("date") endDate!: Date;
 }
+```
 
-const pipeline = source
-  .stream()
-  .from(RawEvent)
-  .filter((msg) => msg.value > 0)
-  .map((msg) => {
-    const out = new AggregatedEvent();
-    out.sum = msg.value;
-    out.count = 1;
-    return out;
-  })
-  .to(AggregatedEvent);
+**Argument:** `(message: M, context?: C) => void | Promise<void>`.
 
-await pipeline.start();
-// pipeline.isRunning() === true
+#### `@BeforePublish` / `@AfterPublish`
 
-await pipeline.pause();
-await pipeline.resume();
-await pipeline.stop();
+Fire around publish operations. `@BeforePublish` runs before the message is handed to the transport. `@AfterPublish` runs after the transport confirms delivery.
+
+```typescript
+@BeforePublish(async (msg) => {
+  await validateExternalId(msg.externalId);
+})
+@AfterPublish(async (msg) => {
+  metrics.increment("messages.published");
+})
+@Message()
+class OrderPlaced {
+  @Field("string") externalId!: string;
+}
 ```
 
-## Message Decorators
-
-### Class-Level
-
-| Decorator            | Description                                            |
-| -------------------- | ------------------------------------------------------ |
-| `@Message(opts?)`    | Mark class as a message type                           |
-| `@AbstractMessage()` | Mark as abstract (non-concrete base)                   |
-| `@Namespace(ns)`     | Set message namespace                                  |
-| `@Version(n)`        | Set message version (positive integer)                 |
-| `@Topic(fn)`         | Dynamic topic resolution callback                      |
-| `@Broadcast()`       | Deliver to all subscribers (not just one per queue)    |
-| `@Persistent()`      | Mark message as persistent/durable                     |
-| `@Priority(n)`       | Set priority (integer 0-10)                            |
-| `@Delay(ms)`         | Default delivery delay in milliseconds                 |
-| `@Expiry(ms)`        | Message expiration in milliseconds                     |
-| `@Encrypted(pred?)`  | Enable payload encryption via `@lindorm/amphora`       |
-| `@Compressed(alg?)`  | Enable compression (`"gzip"`, `"deflate"`, `"brotli"`) |
-| `@Retry(opts?)`      | Configure retry behaviour on consume failure           |
-| `@DeadLetter()`      | Route failed messages to dead letter store             |
-
-### Field-Level
-
-| Decorator              | Description                                                                  |
-| ---------------------- | ---------------------------------------------------------------------------- |
-| `@Field(type, opts?)`  | Declare field with type and options                                          |
-| `@IdentifierField()`   | Auto-generated UUID field                                                    |
-| `@CorrelationField()`  | Auto-generated UUID for correlation tracking                                 |
-| `@TimestampField()`    | Auto-generated Date field                                                    |
-| `@MandatoryField()`    | Boolean field, defaults to `false`                                           |
-| `@PersistentField()`   | Boolean persistence flag, defaults to `false`                                |
-| `@Generated(strategy)` | Auto-generate value (`"uuid"`, `"date"`, `"string"`, `"integer"`, `"float"`) |
-| `@Header(name?)`       | Promote field to message header                                              |
-| `@Enum(values)`        | Restrict to enum values                                                      |
-| `@Min(n)`              | Minimum value constraint                                                     |
-| `@Max(n)`              | Maximum value constraint                                                     |
-| `@Schema(zodType)`     | Zod schema validation                                                        |
-| `@Transform(opts)`     | Custom serialisation/deserialisation transform                               |
-
-### Lifecycle Hooks
-
-| Decorator             | Description                                     |
-| --------------------- | ----------------------------------------------- |
-| `@OnCreate(fn)`       | Called when message instance is created         |
-| `@OnHydrate(fn)`      | Called when message is rehydrated from raw data |
-| `@OnValidate(fn)`     | Called when message is validated                |
-| `@BeforePublish(fn)`  | Called before publishing                        |
-| `@AfterPublish(fn)`   | Called after publishing                         |
-| `@BeforeConsume(fn)`  | Called before consume callback                  |
-| `@AfterConsume(fn)`   | Called after successful consume                 |
-| `@OnConsumeError(fn)` | Called when consume callback throws             |
+**Argument:** `(message: M, context?: C) => void | Promise<void>`.
 
-## Field Types
+#### `@BeforeConsume` / `@AfterConsume`
 
-The `@Field()` decorator accepts the following type identifiers:
+Fire around consume callback execution. `@BeforeConsume` runs after deserialisation but before the consume callback. `@AfterConsume` runs after the callback completes successfully.
+
+```typescript
+@BeforeConsume(async (msg, ctx) => {
+  audit.log("consuming", msg);
+})
+@AfterConsume(async (msg) => {
+  metrics.increment("messages.consumed");
+})
+@Message()
+class OrderPlaced {
+  /* ... */
+}
+```
+
+**Argument:** `(message: M, context?: C) => void | Promise<void>`.
 
-`"array"` | `"bigint"` | `"boolean"` | `"date"` | `"email"` | `"enum"` | `"float"` | `"integer"` | `"object"` | `"string"` | `"url"` | `"uuid"`
+#### `@OnConsumeError`
+
+Fires when a consume callback throws an error. Receives the error as the **first** argument, followed by the message and context.
 
 ```typescript
+@OnConsumeError(async (error, msg) => {
+  errorTracker.capture(error, { messageId: msg.id });
+})
 @Message()
-class FullExample {
+class PaymentCharge {
   @IdentifierField() id!: string;
-  @CorrelationField() correlationId!: string;
-  @TimestampField() createdAt!: Date;
+  @Field("string") chargeId!: string;
+}
+```
 
-  @Field("string") name!: string;
-  @Field("integer") count!: number;
-  @Field("float") price!: number;
-  @Field("boolean") active!: boolean;
-  @Field("date") expiresAt!: Date;
-  @Field("uuid") referenceId!: string;
-  @Field("email") contactEmail!: string;
-  @Field("url") callbackUrl!: string;
-  @Field("array") tags!: Array<string>;
-  @Field("object") metadata!: Record<string, unknown>;
+**Argument:** `(error: Error, message: M, context?: C) => void | Promise<void>`.
 
-  @Field("string", { nullable: true }) description!: string | null;
-  @Field("string", { optional: true }) nickname?: string;
-  @Field("integer", { default: 0 }) retryCount!: number;
-  @Field("string", { default: () => "generated" }) code!: string;
-}
+Note the different signature: `error` is the first parameter, unlike all other hooks where the message comes first.
+
+---
+
+### Hook Execution Order
+
+| Phase      | Hooks (in order)                                                                                        |
+| ---------- | ------------------------------------------------------------------------------------------------------- |
+| Creation   | `@OnCreate`                                                                                             |
+| Validation | `@OnValidate`                                                                                           |
+| Publish    | `@BeforePublish` -> subscriber.beforePublish -> transport -> `@AfterPublish` -> subscriber.afterPublish |
+| Consume    | `@BeforeConsume` -> subscriber.beforeConsume -> callback -> `@AfterConsume` -> subscriber.afterConsume  |
+| Hydration  | `@OnHydrate`                                                                                            |
+| Error      | `@OnConsumeError` -> subscriber.onConsumeError (replaces AfterConsume steps)                            |
+
+Full publish + consume lifecycle:
+
+```
+1. @BeforePublish hook
+2. subscriber.beforePublish
+3. (transport publishes)
+4. (transport delivers to consumer)
+5. @BeforeConsume hook
+6. subscriber.beforeConsume
+7. callback executes
+8. @AfterConsume hook
+9. subscriber.afterConsume
+10. @AfterPublish hook
+11. subscriber.afterPublish
 ```
 
+On error at step 7, steps 8-11 are replaced by `@OnConsumeError` and `subscriber.onConsumeError`.
+
 ## Retry and Dead Letter
 
 Configure automatic retry with backoff strategies and dead letter routing for permanently failed messages.
@@ -346,14 +1066,6 @@ class PaymentCharge {
 }
 ```
 
-**Retry strategies:**
-
-| Strategy        | Delay pattern (base=1000, multiplier=2)     |
-| --------------- | ------------------------------------------- |
-| `"constant"`    | 1000, 1000, 1000, ...                       |
-| `"linear"`      | 1000, 2000, 3000, ...                       |
-| `"exponential"` | 1000, 2000, 4000, 8000, ... (capped at max) |
-
 ## Dynamic Topics
 
 Route messages to different topics based on their content:
@@ -420,24 +1132,6 @@ source.addSubscriber(auditSubscriber);
 source.removeSubscriber(auditSubscriber);
 ```
 
-**Hook execution order on publish + consume:**
-
-```
-1. @BeforePublish hook
-2. subscriber.beforePublish
-3. (transport publishes)
-4. (transport delivers to consumer)
-5. @BeforeConsume hook
-6. subscriber.beforeConsume
-7. callback executes
-8. @AfterConsume hook
-9. subscriber.afterConsume
-10. @AfterPublish hook
-11. subscriber.afterPublish
-```
-
-On error at step 7, steps 8-11 are replaced by `@OnConsumeError` and `subscriber.onConsumeError`.
-
 ## Consume Envelope
 
 Every subscribe/consume callback receives the message and an envelope with routing metadata:
@@ -460,6 +1154,65 @@ await bus.subscribe({
 });
 ```
 
+## Message Manipulation
+
+Every publisher, message bus, and worker queue provides utilities for working with message instances:
+
+```typescript
+const bus = source.messageBus(OrderPlaced);
+
+// Create: new instance with auto-generated fields and defaults
+const msg = bus.create({ orderId: "abc-123", total: 59.99 });
+
+// Hydrate: reconstruct from raw data (no auto-generation)
+const hydrated = bus.hydrate({ orderId: "abc-123", total: 59.99, id: "existing-uuid" });
+
+// Copy: deep clone with a fresh identifier
+const copied = bus.copy(msg);
+// copied.orderId === msg.orderId, but copied.id !== msg.id
+
+// Validate: throws IrisValidationError if invalid
+bus.validate(msg);
+```
+
+## Publish Options
+
+Override message-level defaults per publish call:
+
+```typescript
+await bus.publish(msg, {
+  delay: 5000, // delay delivery by 5 seconds
+  priority: 8, // override @Priority
+  expiry: 60000, // override @Expiry (TTL in ms)
+  key: "partition-key", // routing/partition key
+  headers: { "x-source": "api" }, // additional headers
+});
+```
+
+## Zod Validation
+
+Use `@Schema()` with Zod for fine-grained field validation:
+
+```typescript
+import { z } from "zod";
+import { Schema, Field, Message } from "@lindorm/iris";
+
+@Message()
+class UserCreated {
+  @Schema(z.string().email())
+  @Field("email")
+  email!: string;
+
+  @Schema(z.number().int().min(13).max(150))
+  @Field("integer")
+  age!: number;
+
+  @Schema(z.string().regex(/^[A-Z]{2,3}$/))
+  @Field("string")
+  countryCode!: string;
+}
+```
+
 ## Cloning
 
 Create independent source instances that share the underlying driver connection:
@@ -697,65 +1450,6 @@ source.onConnectionStateChange((state) => {
 const healthy = await source.ping();
 ```
 
-## Message Manipulation
-
-Every publisher, message bus, and worker queue provides utilities for working with message instances:
-
-```typescript
-const bus = source.messageBus(OrderPlaced);
-
-// Create: new instance with auto-generated fields and defaults
-const msg = bus.create({ orderId: "abc-123", total: 59.99 });
-
-// Hydrate: reconstruct from raw data (no auto-generation)
-const hydrated = bus.hydrate({ orderId: "abc-123", total: 59.99, id: "existing-uuid" });
-
-// Copy: deep clone with a fresh identifier
-const copied = bus.copy(msg);
-// copied.orderId === msg.orderId, but copied.id !== msg.id
-
-// Validate: throws IrisValidationError if invalid
-bus.validate(msg);
-```
-
-## Publish Options
-
-Override message-level defaults per publish call:
-
-```typescript
-await bus.publish(msg, {
-  delay: 5000, // delay delivery by 5 seconds
-  priority: 8, // override @Priority
-  expiry: 60000, // override @Expiry (TTL in ms)
-  key: "partition-key", // routing/partition key
-  headers: { "x-source": "api" }, // additional headers
-});
-```
-
-## Zod Validation
-
-Use `@Schema()` with Zod for fine-grained field validation:
-
-```typescript
-import { z } from "zod";
-import { Schema, Field, Message } from "@lindorm/iris";
-
-@Message()
-class UserCreated {
-  @Schema(z.string().email())
-  @Field("email")
-  email!: string;
-
-  @Schema(z.number().int().min(13).max(150))
-  @Field("integer")
-  age!: number;
-
-  @Schema(z.string().regex(/^[A-Z]{2,3}$/))
-  @Field("string")
-  countryCode!: string;
-}
-```
-
 ## Testing with Mocks
 
 All mocks are available via the `@lindorm/iris/mocks` subpath: