@warlock.js/herald 5.30.0 → 5.32.0

package/skills/consume-message/SKILL.md

@@ -17,9 +17,9 @@ herald()
   .subscribe(async (message, ctx) => {
     try {
       await sendWelcomeEmail(message.payload.email);
-      await ctx.ack();          // success — message removed from queue
+      await ctx.ack(); // success — message removed from queue
     } catch (error) {
-      await ctx.nack(true);     // failure — requeue for redelivery
+      await ctx.nack(true); // failure — requeue for redelivery
     }
   });
 ```
@@ -30,7 +30,7 @@ herald()
 - Handler **throws** → herald **auto-nacks** (requeue, or DLQ/reject once retries are exhausted — see below).
 - Handler calls `ctx.ack()` / `ctx.nack()` / `ctx.reject()` / `ctx.retry()` → herald respects that and does nothing further.
 
-So the `try/catch` above is optional — letting the error throw produces the same auto-nack. Call `ctx` methods explicitly only when you want a *non-default* outcome (reject without requeue, route to DLQ, delayed retry). The one mode that loses messages is `autoAck: true`, where the broker acks on delivery before your handler runs.
+So the `try/catch` above is optional — letting the error throw produces the same auto-nack. Call `ctx` methods explicitly only when you want a _non-default_ outcome (reject without requeue, route to DLQ, delayed retry). The one mode that loses messages is `autoAck: true`, where the broker acks on delivery before your handler runs.
 
 ## Message context — flow control
 
@@ -44,23 +44,23 @@ ctx.reply(payload);     // for request-response pattern (see request-and-respond
 
 Pick by intent:
 
-| Intent | Use |
-| --- | --- |
-| Processed cleanly | `ctx.ack()` |
-| Transient failure, try again | `ctx.nack(true)` or `ctx.retry(5000)` |
-| Permanent failure, send to DLQ | `ctx.nack(false)` or `ctx.reject()` |
-| Validation failure (bad message) | `ctx.reject()` — don't requeue |
+| Intent                           | Use                                   |
+| -------------------------------- | ------------------------------------- |
+| Processed cleanly                | `ctx.ack()`                           |
+| Transient failure, try again     | `ctx.nack(true)` or `ctx.retry(5000)` |
+| Permanent failure, send to DLQ   | `ctx.nack(false)` or `ctx.reject()`   |
+| Validation failure (bad message) | `ctx.reject()` — don't requeue        |
 
 ## Subscribe options
 
 ```ts
 await channel.subscribe(handler, {
-  group: "email-workers",      // consumer group / tag — multiple consumers share work
-  prefetch: 10,                 // concurrency — how many in-flight messages this consumer holds
-  autoAck: false,               // default; keep it false in production
-  exclusive: false,             // single consumer only on this channel?
+  group: "email-workers", // consumer group / tag — multiple consumers share work
+  prefetch: 10, // concurrency — how many in-flight messages this consumer holds
+  autoAck: false, // default; keep it false in production
+  exclusive: false, // single consumer only on this channel?
   retry: {
-    maxRetries: 3,              // redelivery ceiling on handler throw (delay not auto-applied — see below)
+    maxRetries: 3, // redelivery ceiling on handler throw (delay not auto-applied — see below)
     delay: 1000,
   },
   deadLetter: {
@@ -101,10 +101,12 @@ The DLQ always forwards the full original payload plus the message metadata, so
 Messages that exhausted retries land in `user.created.failed`. Subscribe to it separately for alerting / manual inspection:
 
 ```ts
-herald().channel("user.created.failed").subscribe(async (message, ctx) => {
-  await alerts.notify(`Failed: ${JSON.stringify(message.payload)}`);
-  await ctx.ack();
-});
+herald()
+  .channel("user.created.failed")
+  .subscribe(async (message, ctx) => {
+    await alerts.notify(`Failed: ${JSON.stringify(message.payload)}`);
+    await ctx.ack();
+  });
 ```
 
 ## Decorator-style consumers — `@Consumable` + `EventConsumer`
@@ -115,7 +117,7 @@ For class-based consumers that pair with the `EventMessage` (the `publish-messag
 import { Consumable, EventConsumer } from "@warlock.js/herald";
 import type { ConsumedEventMessage } from "@warlock.js/herald";
 
-@Consumable()  // or @Consumable({ broker: "analytics" }) to target a non-default broker
+@Consumable() // or @Consumable({ broker: "analytics" }) to target a non-default broker
 export class UserCreatedConsumer extends EventConsumer<{ id: number; email: string }> {
   public static eventName = "user.created";
 
@@ -167,7 +169,7 @@ export class UserCreatedConsumer extends EventConsumer {
 import { defineConsumer } from "@warlock.js/herald";
 
 export const userCreatedConsumer = defineConsumer<{ id: number; email: string }>("user.created", {
-  schema: userCreatedSchema,                 // optional seal validation
+  schema: userCreatedSchema, // optional seal validation
   handle: async (payload, event) => {
     await sendWelcomeEmail(payload.email);
   },
@@ -183,11 +185,11 @@ export const userCreatedConsumer = defineConsumer<{ id: number; email: string }>
 ```ts
 const subscription = await channel.subscribe(handler);
 
-subscription.id;            // the consumer id (string)
-subscription.isActive();    // boolean
+subscription.id; // the consumer id (string)
+subscription.isActive(); // boolean
 
-await subscription.unsubscribe();   // cancel the consumer on the broker
-await subscription.pause();          // also cancels the consumer (RabbitMQ has no native pause)
+await subscription.unsubscribe(); // cancel the consumer on the broker
+await subscription.pause(); // also cancels the consumer (RabbitMQ has no native pause)
 ```
 
 On the RabbitMQ driver, `pause()` and `unsubscribe()` both cancel the consumer; `resume()` is **not supported and throws** — create a fresh subscription to start consuming again. You can also cancel by id from the channel: `await channel.unsubscribeById(consumerId)`, or drop every consumer on the channel with `await channel.stopConsuming()`.
@@ -198,10 +200,10 @@ The channel exposes queue-management helpers beyond pub/sub:
 
 ```ts
 const { messageCount, consumerCount } = await channel.stats(); // queue depth + live consumers
-const purged = await channel.purge();    // drop all pending messages, returns the count
-const ok = await channel.exists();        // does the queue exist on the broker?
-await channel.assert();                   // create the queue with its options (idempotent)
-await channel.delete();                   // remove the queue entirely
+const purged = await channel.purge(); // drop all pending messages, returns the count
+const ok = await channel.exists(); // does the queue exist on the broker?
+await channel.assert(); // create the queue with its options (idempotent)
+await channel.delete(); // remove the queue entirely
 ```
 
 `assert()` runs lazily on the first `publish` / `subscribe`, so you rarely call it directly — reach for it only to pre-create a queue before any traffic.

package/skills/herald-basics/SKILL.md

@@ -73,20 +73,20 @@ await connectToBroker({
   host: process.env.ANALYTICS_HOST,
 });
 
-herald().channel("emails").publish({ /* ... */ });           // → notifications
-herald("analytics").channel("events").publish({ /* ... */ }); // → analytics
+herald().channel("emails").publish({/* ... */}); // → notifications
+herald("analytics").channel("events").publish({/* ... */}); // → analytics
 ```
 
 `connectToBroker` defaults `isDefault` to `true`, and the registry promotes the most-recently-registered default. So when you register more than one broker, mark the secondaries `isDefault: false` — otherwise the last one wins and `herald()` returns the wrong broker.
 
 ## Pick a skill
 
-| If the task is about… | Load |
-| --- | --- |
-| Publishing messages — single + batch + publish options (priority, ttl, delay, persistent, headers) | the `publish-message` topic |
-| Subscribing to messages — handler signature, message context (ack/nack/retry), prefetch, retry policy, dead-letter | the `consume-message` topic |
-| Request/response (RPC) — `channel.request(...)` + `channel.respond(...)` for synchronous-style calls over a message bus | the `request-and-respond` topic |
-| Schema-validated channels — `.channel(name, { schema })` with `@warlock.js/seal` | See the `seal-basics` topic of the `warlock-js-seal` skill + skills below |
+| If the task is about…                                                                                                   | Load                                                                      |
+| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Publishing messages — single + batch + publish options (priority, ttl, delay, persistent, headers)                      | the `publish-message` topic                                               |
+| Subscribing to messages — handler signature, message context (ack/nack/retry), prefetch, retry policy, dead-letter      | the `consume-message` topic                                               |
+| Request/response (RPC) — `channel.request(...)` + `channel.respond(...)` for synchronous-style calls over a message bus | the `request-and-respond` topic                                           |
+| Schema-validated channels — `.channel(name, { schema })` with `@warlock.js/seal`                                        | See the `seal-basics` topic of the `warlock-js-seal` skill + skills below |
 
 ## Things NOT to do
 

package/skills/index.md

@@ -1,17 +1,20 @@
 ---
-description: "Message bus over RabbitMQ (Kafka planned): publish, subscribe, and request-response between services. Exports `connectToBroker`, `herald`, `heraldChannel`, `Broker`, `defineEvent`, `defineConsumer`, `EventMessage`, `EventConsumer`, `Consumable`, `brokerRegistry`. Use for: \"publish an event to RabbitMQ\", \"subscribe to a channel\", \"ack or nack a message\", \"request and reply over the bus\", \"cross-service messaging\". Not this package: durable retried background jobs on Redis → @warlock.js/queue; cron/recurring work → @warlock.js/scheduler."
+description: 'Message bus over RabbitMQ (Kafka planned): publish, subscribe, and request-response between services. Exports `connectToBroker`, `herald`, `heraldChannel`, `Broker`, `defineEvent`, `defineConsumer`, `EventMessage`, `EventConsumer`, `Consumable`, `brokerRegistry`. Use for: "publish an event to RabbitMQ", "subscribe to a channel", "ack or nack a message", "request and reply over the bus", "cross-service messaging". Not this package: durable retried background jobs on Redis → @warlock.js/queue; cron/recurring work → @warlock.js/scheduler.'
 ---
+
 # @warlock.js/herald
 
 Herald is the broker-agnostic message bus. `connectToBroker(config)` boots a broker once; `herald()` returns it (`herald("name")` for a named one); `.channel(name)` is the queue/topic you publish into and subscribe from. Channels are typed with generics and can validate with a seal schema. Server-only.
 
 ## The 80% path
+
 1. Orient with `herald-basics.md` (the map and foundations).
 2. Connect at startup, then publish: `publish-message.md`.
 3. Consume with `subscribe` handlers or consumer classes: `consume-message.md`.
 4. Need a reply? `request-and-respond.md`.
 
 ## Conventions and pitfalls
+
 - Call `connectToBroker` once before any publish or subscribe.
 - Smart auto-ack is the default: a clean return acks, a throw nacks with requeue. `autoAck: true` loses messages on a crash; avoid it.
 - Use `ctx.reject()` / `ctx.retry(ms)` only for a non-default outcome.

package/skills/publish-message/SKILL.md

@@ -27,8 +27,8 @@ type UserPayload = { userId: number; email: string };
 
 const channel = herald().channel<UserPayload>("user.created");
 
-await channel.publish({ userId: 1, email: "test@example.com" });   // ✅ typed
-await channel.publish({ userId: "1" } as never);                    // ❌ compile error
+await channel.publish({ userId: 1, email: "test@example.com" }); // ✅ typed
+await channel.publish({ userId: "1" } as never); // ❌ compile error
 ```
 
 Share the payload type between producer and consumer via a common `types/` file.
@@ -45,7 +45,7 @@ const userSchema = v.object({
 
 const channel = herald().channel("user.created", { schema: userSchema });
 
-await channel.publish({ userId: 1, email: "invalid" });   // Throws — fails .email()
+await channel.publish({ userId: 1, email: "invalid" }); // Throws — fails .email()
 ```
 
 The schema runs `validate()` before the message hits the broker. Invalid payloads never leave the producer. See the `seal-basics` topic of the `warlock-js-seal` skill.
@@ -54,10 +54,10 @@ The schema runs `validate()` before the message hits the broker. Invalid payload
 
 ```ts
 await channel.publish(payload, {
-  priority: 5,           // 0-9, higher = served first
-  expiration: 60_000,    // ms — message expires if not consumed (RabbitMQ uses `expiration`, not `ttl`)
-  delay: 5_000,          // ms — delayed delivery (requires RabbitMQ delay plugin)
-  persistent: true,      // survive broker restart (default true)
+  priority: 5, // 0-9, higher = served first
+  expiration: 60_000, // ms — message expires if not consumed (RabbitMQ uses `expiration`, not `ttl`)
+  delay: 5_000, // ms — delayed delivery (requires RabbitMQ delay plugin)
+  persistent: true, // survive broker restart (default true)
   correlationId: "uuid", // for tracking across services
   headers: {
     tenantId: "42",
@@ -71,14 +71,17 @@ The headers field is free-form — consumers read `message.metadata.headers?.ten
 ## Batch publishing
 
 ```ts
-await channel.publishBatch([
-  { userId: 1, email: "a@example.com" },
-  { userId: 2, email: "b@example.com" },
-  { userId: 3, email: "c@example.com" },
-], {
-  // Options apply to every message in the batch
-  persistent: true,
-});
+await channel.publishBatch(
+  [
+    { userId: 1, email: "a@example.com" },
+    { userId: 2, email: "b@example.com" },
+    { userId: 3, email: "c@example.com" },
+  ],
+  {
+    // Options apply to every message in the batch
+    persistent: true,
+  },
+);
 ```
 
 Under the hood `publishBatch` iterates and calls `.publish()` per message — there's no AMQP-level batching today. It's an ergonomic shape for "emit these N items" (bulk import, fanout to many recipients), not a throughput optimization. The same `options` apply to every message.
@@ -128,7 +131,7 @@ export default {
 ```ts
 // The use case opts in — channel name defaults to the use case name.
 export const createUserUseCase = useCase({
-  name: "users.create",      // → publishes to channel "users.create"
+  name: "users.create", // → publishes to channel "users.create"
   schema: createUserSchema,
   handler: async (data) => User.create(data),
   broadcast: true,

package/skills/request-and-respond/SKILL.md

@@ -36,12 +36,12 @@ The promise rejects if no reply arrives within `timeout` ms. Pick a sane number
 
 ## When to use it vs HTTP
 
-| Use HTTP | Use request/respond |
-| --- | --- |
+| Use HTTP                        | Use request/respond                         |
+| ------------------------------- | ------------------------------------------- |
 | Stateless, fast, idempotent ops | Slow / queued ops where the caller can wait |
-| Public API surface | Internal service-to-service |
-| Frontend consumption | Backend orchestration |
-| Synchronous user-facing flow | Async-but-needs-result patterns |
+| Public API surface              | Internal service-to-service                 |
+| Frontend consumption            | Backend orchestration                       |
+| Synchronous user-facing flow    | Async-but-needs-result patterns             |
 
 The bus adds queue persistence and retry. HTTP is faster for sub-100ms ops; the bus shines when the operation has variable duration or needs a queue's backpressure.