@warlock.js/herald 5.29.0 → 5.31.0

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.