hexok 2.2.3 → 2.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hexok",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "description": "TypeScript primitives for hexagonal software: Schema, Entity, UseCase, Port, Adapter, Mapper, Event, EventCatalog, EventHandler, and Errors.",
   "type": "module",
   "license": "MIT",

package/skills/hexok/SKILL.md

@@ -31,6 +31,7 @@ Read the reference before writing that concept. Each file is the supporting docu
 | UseCase | [references/use-case.md](references/use-case.md) | Application. One caller action. `UseCase.context` is in that file. |
 | Port | [references/port.md](references/port.md) | Application. The contract a use case or handler calls. |
 | EventHandler | [references/event-handler.md](references/event-handler.md) | Application. Work that follows one event. |
+| Integration events | [references/integration-events.md](references/integration-events.md) | Contract between applications. Read it when another application that deploys on its own publishes or consumes the event. From `@hexok/integration-events`. |
 | Adapter | [references/adapter.md](references/adapter.md) | Interface adapter. The current implementation of one port. |
 | Mapper | [references/mapper.md](references/mapper.md) | Interface adapter. Read it when the stored document is not the domain props. |
 
@@ -72,6 +73,8 @@ When that work exists and the event does not, define the event and register it o
 
 When the story has no consequence beyond its own write, this step is `none`. Do not add an event so the step looks complete.
 
+When the consequence runs in another application that deploys on its own, the event is an integration event, not a domain event. Read [references/integration-events.md](references/integration-events.md).
+
 ### 3.c. Event handlers
 
 When step 3.b named a side effect, implement the handler if it does not exist. The handler takes its own ports on a `deps` object in the constructor. `handle` receives the event. Emailing subscribers loads addresses through a subscriber port and sends mail through a mail port. Read [references/event-handler.md](references/event-handler.md).

package/skills/hexok/references/integration-events.md

@@ -0,0 +1,85 @@
+# Integration events
+
+An integration event is a fact one application publishes for other applications that deploy on their own, such as a second product or a service another team owns. It comes from `@hexok/integration-events`, not from `hexok`. Read the package README for the full guarantees.
+
+A domain event stays inside one application and changes with it. An integration event is a contract. Do not publish a domain event to another application. Map it to an integration event at the edge.
+
+Use an integration event only when a consumer deploys apart from the producer. Two processes of one application, such as an API and its worker, share a catalog and use `Event` and `EventCatalog`.
+
+## Contract
+
+The producer owns the contract file. It imports `@hexok/integration-events`, a schema library, and nothing else from the producer. Consumers import it from a package the producer publishes, a shared workspace, or a copy.
+
+```ts
+import { Contract, Message } from '@hexok/integration-events';
+
+export class PostPublished extends Message('post.published', 1, z.object({
+  postId: z.string(),
+  title: z.string(),
+})) {}
+
+export class Blog extends Contract('blog', {
+  posts: [PostPublished],
+}) {}
+```
+
+`Message(type, version, schema)` is an `Event` with a `version`. `Contract(name, topics)` maps each key to its messages. The queue topic is `<name>.<key>`, here `blog.posts`.
+
+Contract schemas describe JSON. `Date`, `bigint`, `Map`, and `Set` do not survive the queue. Use strings and numbers, such as an ISO string for a time. `publish` validates the JSON form of the payload and sends that form, so keys the schema would strip are still sent. A payload that is not JSON or fails its schema throws `VALIDATION` before anything is sent.
+
+## Producer
+
+The use case depends on a port. The adapter wraps `IntegrationPublisher`.
+
+```ts
+abstract class BlogIntegrationEvents extends Port('BlogIntegrationEvents') {
+  abstract publish(event: ContractEvent<typeof Blog>): Promise<string>;
+}
+
+class QueueBlogIntegrationEvents extends Adapter(BlogIntegrationEvents) {
+  readonly #publisher: IntegrationPublisher<typeof Blog>;
+
+  constructor(private readonly deps: { readonly queue: Queue }) {
+    super();
+    this.#publisher = new IntegrationPublisher(Blog, deps);
+  }
+
+  override publish(event: ContractEvent<typeof Blog>): Promise<string> {
+    return this.#publisher.publish(event);
+  }
+}
+```
+
+The use case publishes after its save succeeds, as it does a domain event. When the application already publishes a domain event, an event handler can map it to the integration event and publish that.
+
+## Consumer
+
+Each handler is an `EventHandler` for one message. The worker entry subscribes them.
+
+```ts
+class ProjectPost extends EventHandler('project-post', PostPublished) {
+  constructor(private readonly deps: { readonly posts: PostProjection }) {
+    super();
+  }
+
+  async handle(event: PostPublished, meta?: IntegrationMeta): Promise<void> {
+    await this.deps.posts.upsert(event.payload, meta?.id);
+  }
+}
+
+const blog = new IntegrationSubscriber(Blog, { queue, service: 'search', logger, quarantine });
+await blog.subscribe({ maxDeliveries: 10, handlers: [new ProjectPost({ posts })] });
+```
+
+`service` names the consuming application. Each handler gets the consumer group `<service>:<handler token>`. Give each handler its own token. Delivery is at least once. Make `handle` idempotent with `meta.id`.
+
+## Versions
+
+- An additive change keeps the version. Consumer schemas accept unknown fields.
+- A breaking change is a new `Message` of the same type and the next version, with `downgrade: { to, map }` to the previous one. Add it to the same topic. One `publish` of the newest version sends every version in the topic.
+- `publish` accepts only the newest version.
+- Retire an old version after every consumer moves. Remove it from the topic and remove the downgrade that targets it. Until a consumer moves, its handler for the retired version receives nothing and logs nothing, and the new contract makes its `subscribe` throw.
+
+## What the application owns
+
+Retention, backfill for a new consumer, order between redeliveries, the outbox, and topic permissions in the broker. Every handler reads every entry on its topic, so keep topics narrow, such as one per aggregate.