@warlock.js/herald 5.19.1 → 5.21.0

package/skills/publish-message/SKILL.md

@@ -1,172 +1,172 @@
----
-name: publish-message
-description: "Publish messages in @warlock.js/herald; use when you need to publish message."
----
-
-# Publish messages
-
-Push messages into a channel. The consumer side picks them up via [`@warlock.js/herald/consume-message/SKILL.md`](@warlock.js/herald/consume-message/SKILL.md).
-
-## Single publish
-
-```ts
-import { herald } from "@warlock.js/herald";
-
-await herald().channel("user.created").publish({
-  userId: 1,
-  email: "ada@example.com",
-});
-```
-
-Returns when the broker has accepted the message (not when a consumer has handled it — that's `.request()` territory).
-
-## Typed channels
-
-```ts
-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
-```
-
-Share the payload type between producer and consumer via a common `types/` file.
-
-## Schema-validated publish
-
-```ts
-import { v } from "@warlock.js/seal";
-
-const userSchema = v.object({
-  userId: v.int(),
-  email: v.string().email(),
-});
-
-const channel = herald().channel("user.created", { schema: userSchema });
-
-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 [`@warlock.js/seal/seal-basics/SKILL.md`](@warlock.js/seal/seal-basics/SKILL.md).
-
-## Publish options
-
-```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)
-  correlationId: "uuid", // for tracking across services
-  headers: {
-    tenantId: "42",
-    source: "billing-service",
-  },
-});
-```
-
-The headers field is free-form — consumers read `message.metadata.headers?.tenantId` to route or filter (headers live under `message.metadata`, alongside `messageId`, `correlationId`, `timestamp`, and `retryCount`).
-
-## 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,
-});
-```
-
-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.
-
-## Publish + transaction (outbox pattern)
-
-Don't publish inside a database transaction — if the transaction rolls back but the publish already happened, you've emitted an event for a state that never persisted.
-
-The outbox pattern: write to an `outbox` table inside the transaction, dispatch from the outbox via a worker after commit:
-
-```ts
-await transaction(async () => {
-  await Order.create(orderData);
-  await Outbox.create({
-    channel: "order.created",
-    payload: { orderId: order.id, ... },
-    status: "pending",
-  });
-});
-
-// In a separate worker:
-const pending = await Outbox.where("status", "pending").get();
-for (const row of pending) {
-  await herald().channel(row.get("channel")).publish(row.get("payload"));
-  await row.merge({ status: "sent", sent_at: new Date() }).save();
-}
-```
-
-Full recipe at `domains/cascade/docs/recipes/outbox-pattern.md`.
-
-## Broadcasting use-case results
-
-`@warlock.js/herald` ships `heraldBroadcast()` — a channel adapter that lets a `@warlock.js/core` `useCase()` publish its result to the bus automatically on success. Register it once in the use-cases config; each use case opts in with `broadcast: true`.
-
-```ts title="src/config/use-cases.ts"
-import { type UseCaseConfigurations } from "@warlock.js/core";
-import { heraldBroadcast } from "@warlock.js/herald";
-
-export default {
-  broadcast: {
-    enabled: true,
-    channels: [heraldBroadcast({ broker: "default" })], // omit broker for the default
-  },
-} satisfies UseCaseConfigurations;
-```
-
-```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"
-  schema: createUserSchema,
-  handler: async (data) => User.create(data),
-  broadcast: true,
-});
-```
-
-The adapter publishes the broadcast envelope's `payload` to `channel(event.event)`. It's structurally typed, so herald keeps no dependency on core. See [`@warlock.js/core/write-use-case/SKILL.md`](@warlock.js/core/write-use-case/SKILL.md) for the `broadcast` option (payload projection, custom event name, payload-safety rules).
-
-## Event classes (`EventMessage`) — the typed event layer
-
-Raw `channel(name).publish(payload)` is the low-level path. For domain events that travel between modules, herald ships a higher-level pair: define the event once as a class, publish instances of it, and consume them with an [`EventConsumer`](@warlock.js/herald/consume-message/SKILL.md). The channel name comes from the event's `eventName` — no string to keep in sync across producer and consumer.
-
-```ts
-import { defineEvent, publishEvent } from "@warlock.js/herald";
-
-// `defineEvent<IncomingData, OutgoingData>` — `toJSON` projects the wire payload.
-const UserCreatedEvent = defineEvent<User, { id: number; email: string }>("user.created", {
-  toJSON: (user) => ({ id: user.id, email: user.email }),
-  // schema?: an @warlock.js/seal ObjectValidator (held on the instance; the consumer side validates)
-});
-
-// `publishEvent` serializes the instance and publishes to channel "user.created" on the default broker.
-await publishEvent(new UserCreatedEvent(user));
-```
-
-`publishEvent(event)` is shorthand for `herald().publish(event)` — it calls `event.serialize()` and sends an **envelope**: `{ payload, metadata, messageId, eventName, version, occurredAt }`. That nesting is why an `EventConsumer` reads `envelope.payload`, not the raw body — pair this only with the consumer side, not a bare `.subscribe()`.
-
-Set an optional `version` on the event (instance field) to drive the consumer's `minVersion` / `maxVersion` acceptance gate. The class form (`class X extends EventMessage`) is equivalent — override `toJSON()` and set `eventName`, `version`, `schema` as fields.
-
-## Things NOT to do
-
-- Don't publish inside a transaction. Use the outbox pattern.
-- Don't pass non-JSON-serializable values (functions, `BigInt`, class instances with methods). Serialization happens at the broker boundary; functions go silent, BigInt throws.
-- Don't `expiration: 0` — set a real expiry or omit. `0` means "expire immediately."
-- Don't omit `persistent: true` for messages where loss matters. Default is `true` in this lib, but worth being explicit when the message represents money / customer state.
-- Don't put secrets in headers. Headers travel in plaintext (encrypted only by TLS in transit, not at rest in the broker).
-
-## See also
-
-- [`@warlock.js/herald/consume-message/SKILL.md`](@warlock.js/herald/consume-message/SKILL.md) — the receiving side
-- [`@warlock.js/herald/request-and-respond/SKILL.md`](@warlock.js/herald/request-and-respond/SKILL.md) — when you need a reply
+---
+name: publish-message
+description: 'Publish messages to a channel — .publish(payload, options?) for single, .publishBatch([...], options?) for batch, with priority / ttl / delay / persistent / correlationId / headers options. Optional schema validation via .channel(name, {schema}). Triggers: `publish`, `publishBatch`, `channel`, `priority`, `ttl`, `delay`, `persistent`, `correlationId`, `headers`, `schema`; "publish a message", "emit an event after a domain change", "fan out a notification", "schedule delayed work", "batch publish"; typical import `import { herald } from "@warlock.js/herald"`. Skip: setup — `@warlock.js/herald/herald-basics/SKILL.md`; consuming — `@warlock.js/herald/consume-message/SKILL.md`; RPC — `@warlock.js/herald/request-and-respond/SKILL.md`; competing libs `amqplib`, `kafkajs`, `bullmq`; NestJS `ClientProxy.emit`.'
+---
+
+# Publish messages
+
+Push messages into a channel. The consumer side picks them up via [`@warlock.js/herald/consume-message/SKILL.md`](@warlock.js/herald/consume-message/SKILL.md).
+
+## Single publish
+
+```ts
+import { herald } from "@warlock.js/herald";
+
+await herald().channel("user.created").publish({
+  userId: 1,
+  email: "ada@example.com",
+});
+```
+
+Returns when the broker has accepted the message (not when a consumer has handled it — that's `.request()` territory).
+
+## Typed channels
+
+```ts
+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
+```
+
+Share the payload type between producer and consumer via a common `types/` file.
+
+## Schema-validated publish
+
+```ts
+import { v } from "@warlock.js/seal";
+
+const userSchema = v.object({
+  userId: v.int(),
+  email: v.string().email(),
+});
+
+const channel = herald().channel("user.created", { schema: userSchema });
+
+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 [`@warlock.js/seal/seal-basics/SKILL.md`](@warlock.js/seal/seal-basics/SKILL.md).
+
+## Publish options
+
+```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)
+  correlationId: "uuid", // for tracking across services
+  headers: {
+    tenantId: "42",
+    source: "billing-service",
+  },
+});
+```
+
+The headers field is free-form — consumers read `message.metadata.headers?.tenantId` to route or filter (headers live under `message.metadata`, alongside `messageId`, `correlationId`, `timestamp`, and `retryCount`).
+
+## 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,
+});
+```
+
+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.
+
+## Publish + transaction (outbox pattern)
+
+Don't publish inside a database transaction — if the transaction rolls back but the publish already happened, you've emitted an event for a state that never persisted.
+
+The outbox pattern: write to an `outbox` table inside the transaction, dispatch from the outbox via a worker after commit:
+
+```ts
+await transaction(async () => {
+  await Order.create(orderData);
+  await Outbox.create({
+    channel: "order.created",
+    payload: { orderId: order.id, ... },
+    status: "pending",
+  });
+});
+
+// In a separate worker:
+const pending = await Outbox.where("status", "pending").get();
+for (const row of pending) {
+  await herald().channel(row.get("channel")).publish(row.get("payload"));
+  await row.merge({ status: "sent", sent_at: new Date() }).save();
+}
+```
+
+Full recipe at `domains/cascade/docs/recipes/outbox-pattern.md`.
+
+## Broadcasting use-case results
+
+`@warlock.js/herald` ships `heraldBroadcast()` — a channel adapter that lets a `@warlock.js/core` `useCase()` publish its result to the bus automatically on success. Register it once in the use-cases config; each use case opts in with `broadcast: true`.
+
+```ts title="src/config/use-cases.ts"
+import { type UseCaseConfigurations } from "@warlock.js/core";
+import { heraldBroadcast } from "@warlock.js/herald";
+
+export default {
+  broadcast: {
+    enabled: true,
+    channels: [heraldBroadcast({ broker: "default" })], // omit broker for the default
+  },
+} satisfies UseCaseConfigurations;
+```
+
+```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"
+  schema: createUserSchema,
+  handler: async (data) => User.create(data),
+  broadcast: true,
+});
+```
+
+The adapter publishes the broadcast envelope's `payload` to `channel(event.event)`. It's structurally typed, so herald keeps no dependency on core. See [`@warlock.js/core/write-use-case/SKILL.md`](@warlock.js/core/write-use-case/SKILL.md) for the `broadcast` option (payload projection, custom event name, payload-safety rules).
+
+## Event classes (`EventMessage`) — the typed event layer
+
+Raw `channel(name).publish(payload)` is the low-level path. For domain events that travel between modules, herald ships a higher-level pair: define the event once as a class, publish instances of it, and consume them with an [`EventConsumer`](@warlock.js/herald/consume-message/SKILL.md). The channel name comes from the event's `eventName` — no string to keep in sync across producer and consumer.
+
+```ts
+import { defineEvent, publishEvent } from "@warlock.js/herald";
+
+// `defineEvent<IncomingData, OutgoingData>` — `toJSON` projects the wire payload.
+const UserCreatedEvent = defineEvent<User, { id: number; email: string }>("user.created", {
+  toJSON: (user) => ({ id: user.id, email: user.email }),
+  // schema?: an @warlock.js/seal ObjectValidator (held on the instance; the consumer side validates)
+});
+
+// `publishEvent` serializes the instance and publishes to channel "user.created" on the default broker.
+await publishEvent(new UserCreatedEvent(user));
+```
+
+`publishEvent(event)` is shorthand for `herald().publish(event)` — it calls `event.serialize()` and sends an **envelope**: `{ payload, metadata, messageId, eventName, version, occurredAt }`. That nesting is why an `EventConsumer` reads `envelope.payload`, not the raw body — pair this only with the consumer side, not a bare `.subscribe()`.
+
+Set an optional `version` on the event (instance field) to drive the consumer's `minVersion` / `maxVersion` acceptance gate. The class form (`class X extends EventMessage`) is equivalent — override `toJSON()` and set `eventName`, `version`, `schema` as fields.
+
+## Things NOT to do
+
+- Don't publish inside a transaction. Use the outbox pattern.
+- Don't pass non-JSON-serializable values (functions, `BigInt`, class instances with methods). Serialization happens at the broker boundary; functions go silent, BigInt throws.
+- Don't `expiration: 0` — set a real expiry or omit. `0` means "expire immediately."
+- Don't omit `persistent: true` for messages where loss matters. Default is `true` in this lib, but worth being explicit when the message represents money / customer state.
+- Don't put secrets in headers. Headers travel in plaintext (encrypted only by TLS in transit, not at rest in the broker).
+
+## See also
+
+- [`@warlock.js/herald/consume-message/SKILL.md`](@warlock.js/herald/consume-message/SKILL.md) — the receiving side
+- [`@warlock.js/herald/request-and-respond/SKILL.md`](@warlock.js/herald/request-and-respond/SKILL.md) — when you need a reply

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

@@ -1,74 +1,74 @@
----
-name: request-and-respond
-description: "Request-response over the bus in @warlock.js/herald; use when you need to request and respond."
----
-
-# Request-response over the bus
-
-Most messaging is fire-and-forget. When you need a reply, use the request/respond pair — a reply-queue + correlation-id pattern under the hood, surfaced as a typed promise.
-
-## Shape
-
-```ts
-// Caller (client)
-const response = await herald()
-  .channel<RequestPayload>("compute.tax")
-  .request<TaxResponse>({ amount: 1000, country: "US" }, { timeout: 30_000 });
-
-// Responder (server)
-herald()
-  .channel<RequestPayload>("compute.tax")
-  .respond(async (message, ctx) => {
-    const tax = await computeTax(message.payload);
-    return { tax, currency: "USD" }; // ← the return value IS the reply
-  });
-```
-
-`request` returns a promise that resolves with the responder's return value. `respond` registers a handler and **automatically replies with whatever the handler returns** (then acks) — so just `return` the response; you don't call `ctx.reply()` yourself inside a `respond` handler. (`ctx.reply` is the lower-level primitive used when you wire a plain `.subscribe()` as a responder by hand.)
-
-## Timeout
-
-```ts
-await channel.request(payload, { timeout: 30_000 });
-```
-
-The promise rejects if no reply arrives within `timeout` ms. Pick a sane number — too short rejects mid-work; too long lets a hung responder block the caller.
-
-## When to use it vs HTTP
-
-| 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 |
-
-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.
-
-## When NOT to use it
-
-- "I need a result in under 50ms" — too much overhead on the bus.
-- "The responder might be down for hours" — request will time out repeatedly; consider `publish` + write the result somewhere the caller polls.
-- "Many callers, the response is the same for all" — cache the result and use `publish` for invalidation.
-
-## Multiple responders
-
-`respond(handler)` takes no options — there's no `group` knob here. If multiple consumers `respond()` to the same channel, they all sit on the same queue, so RabbitMQ round-robins between them: **one responder handles each request, and the caller gets exactly one reply.** That's the "share work across responders" pattern — a synchronous worker pool. Make every responder functionally identical, since the caller has no say in which one answers.
-
-For "multiple replies expected" patterns, use a regular `subscribe` + a request id, then the caller listens on a result channel.
-
-## Correlation across replies
-
-Each `request()` generates its own correlation ID and an exclusive reply queue under the hood. The reply carries the same ID; the client matches it to the awaiting promise and resolves. You don't manage correlation IDs manually — and you shouldn't pass your own `correlationId` on a `request()`, since herald overwrites it with the one it uses to match the reply. To thread your own trace id (e.g. a transaction id for logs) through to the responder, put it in `headers` instead — the responder reads it from `message.metadata.headers`.
-
-## Things NOT to do
-
-- Don't use request/respond for high-throughput, low-latency ops. The reply-queue round-trip adds at least one broker hop. HTTP is the right tool.
-- Don't return huge payloads from `respond`. Reply messages travel through the broker; a multi-MB response is a load on the bus and on memory. For big results, write to S3 / cache and reply with a reference.
-- Don't forget to `respond` in long-lived consumers. If the responder crashes, every caller's request will time out — they don't know why.
-- Don't set timeout to `Infinity`. A stuck request becomes a leaked promise — set a real timeout and handle the rejection.
-
-## See also
-
-- [`@warlock.js/herald/publish-message/SKILL.md`](@warlock.js/herald/publish-message/SKILL.md) — fire-and-forget pattern
-- [`@warlock.js/herald/consume-message/SKILL.md`](@warlock.js/herald/consume-message/SKILL.md) — subscribe + ctx flow control (including `ctx.reply`)
+---
+name: request-and-respond
+description: 'Synchronous-style RPC over the message bus — channel.request<R>(payload, {timeout}) waits for a reply, channel.respond(handler) registers the responder, ctx.reply(response) sends the answer. Triggers: `channel.request`, `channel.respond`, `ctx.reply`, `timeout`, `correlationId`, `headers.correlationId`; "RPC over message bus", "request-response across services", "wait for a reply", "internal service-to-service call instead of HTTP"; typical import `import { herald } from "@warlock.js/herald"`. Skip: setup — `@warlock.js/herald/herald-basics/SKILL.md`; fire-and-forget — `@warlock.js/herald/publish-message/SKILL.md`; consumer ctx flow — `@warlock.js/herald/consume-message/SKILL.md`; competing libs `amqplib` RPC, `nats` request/reply; NestJS `ClientProxy.send`; gRPC; HTTP.'
+---
+
+# Request-response over the bus
+
+Most messaging is fire-and-forget. When you need a reply, use the request/respond pair — a reply-queue + correlation-id pattern under the hood, surfaced as a typed promise.
+
+## Shape
+
+```ts
+// Caller (client)
+const response = await herald()
+  .channel<RequestPayload>("compute.tax")
+  .request<TaxResponse>({ amount: 1000, country: "US" }, { timeout: 30_000 });
+
+// Responder (server)
+herald()
+  .channel<RequestPayload>("compute.tax")
+  .respond(async (message, ctx) => {
+    const tax = await computeTax(message.payload);
+    return { tax, currency: "USD" }; // ← the return value IS the reply
+  });
+```
+
+`request` returns a promise that resolves with the responder's return value. `respond` registers a handler and **automatically replies with whatever the handler returns** (then acks) — so just `return` the response; you don't call `ctx.reply()` yourself inside a `respond` handler. (`ctx.reply` is the lower-level primitive used when you wire a plain `.subscribe()` as a responder by hand.)
+
+## Timeout
+
+```ts
+await channel.request(payload, { timeout: 30_000 });
+```
+
+The promise rejects if no reply arrives within `timeout` ms. Pick a sane number — too short rejects mid-work; too long lets a hung responder block the caller.
+
+## When to use it vs HTTP
+
+| 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 |
+
+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.
+
+## When NOT to use it
+
+- "I need a result in under 50ms" — too much overhead on the bus.
+- "The responder might be down for hours" — request will time out repeatedly; consider `publish` + write the result somewhere the caller polls.
+- "Many callers, the response is the same for all" — cache the result and use `publish` for invalidation.
+
+## Multiple responders
+
+`respond(handler)` takes no options — there's no `group` knob here. If multiple consumers `respond()` to the same channel, they all sit on the same queue, so RabbitMQ round-robins between them: **one responder handles each request, and the caller gets exactly one reply.** That's the "share work across responders" pattern — a synchronous worker pool. Make every responder functionally identical, since the caller has no say in which one answers.
+
+For "multiple replies expected" patterns, use a regular `subscribe` + a request id, then the caller listens on a result channel.
+
+## Correlation across replies
+
+Each `request()` generates its own correlation ID and an exclusive reply queue under the hood. The reply carries the same ID; the client matches it to the awaiting promise and resolves. You don't manage correlation IDs manually — and you shouldn't pass your own `correlationId` on a `request()`, since herald overwrites it with the one it uses to match the reply. To thread your own trace id (e.g. a transaction id for logs) through to the responder, put it in `headers` instead — the responder reads it from `message.metadata.headers`.
+
+## Things NOT to do
+
+- Don't use request/respond for high-throughput, low-latency ops. The reply-queue round-trip adds at least one broker hop. HTTP is the right tool.
+- Don't return huge payloads from `respond`. Reply messages travel through the broker; a multi-MB response is a load on the bus and on memory. For big results, write to S3 / cache and reply with a reference.
+- Don't forget to `respond` in long-lived consumers. If the responder crashes, every caller's request will time out — they don't know why.
+- Don't set timeout to `Infinity`. A stuck request becomes a leaked promise — set a real timeout and handle the rejection.
+
+## See also
+
+- [`@warlock.js/herald/publish-message/SKILL.md`](@warlock.js/herald/publish-message/SKILL.md) — fire-and-forget pattern
+- [`@warlock.js/herald/consume-message/SKILL.md`](@warlock.js/herald/consume-message/SKILL.md) — subscribe + ctx flow control (including `ctx.reply`)