@kronos-ts/messaging 0.1.0

package/src/dead-letter-queue.ts

@@ -0,0 +1,330 @@
+import type { EventMessage } from "./message.js"
+
+/**
+ * A dead letter — an event that failed processing and was parked
+ * for later retry or manual intervention.
+ */
+export interface DeadLetter {
+  /** The original event message that failed. */
+  readonly message: EventMessage
+  /** The error that caused the failure. */
+  readonly cause: Error
+  /** When this letter was first enqueued. */
+  readonly enqueuedAt: number
+  /** When this letter was last touched (enqueued or requeued). */
+  readonly lastTouched: number
+  /** Additional diagnostics metadata about the failure. */
+  readonly diagnostics: Record<string, unknown>
+  /** The sequence identifier this letter belongs to. */
+  readonly sequenceIdentifier: string
+}
+
+/**
+ * Decision on whether to enqueue a failed event as a dead letter.
+ */
+export interface EnqueueDecision {
+  /** Whether to enqueue the failed event. */
+  readonly shouldEnqueue: boolean
+  /** Optional updated cause (may differ from original). */
+  readonly cause?: Error
+  /** Additional diagnostics to attach. */
+  readonly diagnostics?: Record<string, unknown>
+}
+
+/**
+ * Policy that determines whether a failed event should be dead-lettered.
+ */
+export interface EnqueuePolicy {
+  /**
+   * Decide whether to enqueue a failed event.
+   * @param letter The dead letter candidate
+   * @param cause The error that caused the failure
+   */
+  decide(letter: DeadLetter, cause: Error): EnqueueDecision
+}
+
+/**
+ * Default policy: always enqueue with the original cause.
+ */
+export function alwaysEnqueuePolicy(): EnqueuePolicy {
+  return {
+    decide() {
+      return { shouldEnqueue: true }
+    },
+  }
+}
+
+/**
+ * A sequenced dead letter queue that maintains ordering within sequences.
+ *
+ * Events in the same sequence (identified by `sequenceIdentifier`) are
+ * ordered by insertion. When a sequence has dead letters, subsequent
+ * events in that sequence are also dead-lettered to preserve ordering.
+ *
+ * Typical sequence identifier: aggregate ID or correlation ID.
+ *
+ * Database-backed implementations participate in the active UnitOfWork via
+ * the ALS-managed transaction (read through `getActiveTransaction()` /
+ * `getResource(TRANSACTION_KEY)`); no `ProcessingContext` parameter is
+ * threaded through the public surface.
+ */
+export interface SequencedDeadLetterQueue {
+  /**
+   * Enqueue a dead letter into the given sequence.
+   */
+  enqueue(letter: DeadLetter): Promise<void>
+
+  /**
+   * Enqueue a dead letter only if the sequence already has dead letters.
+   * Used to block subsequent events in a failed sequence.
+   * The supplier is only called if the sequence exists (avoids creating
+   * unnecessary objects).
+   * Returns true if the letter was enqueued (sequence existed).
+   */
+  enqueueIfPresent(sequenceIdentifier: string, letterSupplier: () => DeadLetter): Promise<boolean>
+
+  /**
+   * Remove a dead letter from the queue (successfully reprocessed).
+   */
+  evict(sequenceIdentifier: string, letter: DeadLetter): Promise<void>
+
+  /**
+   * Re-insert a dead letter at the front of its sequence with updated properties.
+   */
+  requeue(
+    letter: DeadLetter,
+    update?: Partial<Pick<DeadLetter, "cause" | "diagnostics">>,
+  ): Promise<void>
+
+  /**
+   * Check if a sequence has any dead letters.
+   */
+  contains(sequenceIdentifier: string): Promise<boolean>
+
+  /**
+   * Get all dead letters in a sequence, in insertion order.
+   */
+  deadLetterSequence(sequenceIdentifier: string): Promise<DeadLetter[]>
+
+  /**
+   * Get all sequence identifiers that have dead letters.
+   */
+  sequenceIdentifiers(): Promise<string[]>
+
+  /**
+   * Process the oldest dead letter sequence matching the filter.
+   * For each letter in the sequence:
+   * - If processingTask returns `{ shouldEnqueue: false }`: letter is evicted, continue
+   * - If processingTask returns `{ shouldEnqueue: true }`: letter is requeued, stop
+   *
+   * Returns true if a sequence was processed.
+   */
+  process(
+    sequenceFilter: (sequenceId: string) => boolean,
+    processingTask: (letter: DeadLetter) => Promise<EnqueueDecision>,
+  ): Promise<boolean>
+
+  /** Total number of dead letters across all sequences. */
+  size(): number
+
+  /** Number of sequences with dead letters. */
+  amountOfSequences(): number
+
+  /** Clear all dead letters. */
+  clear(): Promise<void>
+
+  /**
+   * Check if the queue is full for the given sequence.
+   * Returns true if max sequences or max sequence size is reached.
+   */
+  isFull(sequenceIdentifier: string): boolean
+}
+
+/**
+ * Creates an in-memory dead letter queue.
+ *
+ * @param options.maxSequences Maximum number of sequences (default: 1024)
+ * @param options.maxSequenceSize Maximum letters per sequence (default: 1024)
+ */
+export function createInMemoryDeadLetterQueue(options?: {
+  maxSequences?: number
+  maxSequenceSize?: number
+}): SequencedDeadLetterQueue {
+  const maxSequences = options?.maxSequences ?? 1024
+  const maxSequenceSize = options?.maxSequenceSize ?? 1024
+
+  const sequences = new Map<string, DeadLetter[]>()
+  const processing = new Set<string>()
+
+  return {
+    async enqueue(letter) {
+      const seq = sequences.get(letter.sequenceIdentifier)
+      if (seq) {
+        if (seq.length >= maxSequenceSize) {
+          throw new DeadLetterQueueOverflowError(
+            `sequence "${letter.sequenceIdentifier}" has reached max size ${maxSequenceSize}`,
+          )
+        }
+        seq.push(letter)
+      } else {
+        if (sequences.size >= maxSequences) {
+          throw new DeadLetterQueueOverflowError(
+            `max sequences ${maxSequences} reached`,
+          )
+        }
+        sequences.set(letter.sequenceIdentifier, [letter])
+      }
+    },
+
+    async enqueueIfPresent(sequenceIdentifier, letterSupplier) {
+      const seq = sequences.get(sequenceIdentifier)
+      if (!seq) return false
+      if (seq.length >= maxSequenceSize) {
+        throw new DeadLetterQueueOverflowError(
+          `sequence "${sequenceIdentifier}" has reached max size ${maxSequenceSize}`,
+        )
+      }
+      seq.push(letterSupplier())
+      return true
+    },
+
+    async evict(sequenceIdentifier, letter) {
+      const seq = sequences.get(sequenceIdentifier)
+      if (!seq) return
+      const idx = seq.indexOf(letter)
+      if (idx >= 0) seq.splice(idx, 1)
+      if (seq.length === 0) sequences.delete(sequenceIdentifier)
+    },
+
+    async requeue(letter, update?) {
+      const seq = sequences.get(letter.sequenceIdentifier)
+      if (!seq) return
+
+      const updated: DeadLetter = {
+        ...letter,
+        lastTouched: Date.now(),
+        cause: update?.cause ?? letter.cause,
+        diagnostics: update?.diagnostics
+          ? { ...letter.diagnostics, ...update.diagnostics }
+          : letter.diagnostics,
+      }
+
+      const idx = seq.indexOf(letter)
+      if (idx >= 0) seq.splice(idx, 1)
+      seq.unshift(updated)
+    },
+
+    async contains(sequenceIdentifier) {
+      const seq = sequences.get(sequenceIdentifier)
+      return seq !== undefined && seq.length > 0
+    },
+
+    async deadLetterSequence(sequenceIdentifier) {
+      return sequences.get(sequenceIdentifier) ?? []
+    },
+
+    async sequenceIdentifiers() {
+      return [...sequences.keys()]
+    },
+
+    async process(sequenceFilter, processingTask) {
+      // Find oldest untaken sequence matching filter
+      let oldestId: string | undefined
+      let oldestTime = Infinity
+
+      for (const [id, letters] of sequences) {
+        if (processing.has(id)) continue
+        if (letters.length === 0) continue
+        if (!sequenceFilter(id)) continue
+
+        const firstTouched = letters[0]!.lastTouched
+        if (firstTouched < oldestTime) {
+          oldestTime = firstTouched
+          oldestId = id
+        }
+      }
+
+      if (!oldestId) return false
+
+      processing.add(oldestId)
+      try {
+        const letters = sequences.get(oldestId)
+        if (!letters) return false
+
+        // Process letters in order — take a snapshot of current letters
+        const snapshot = [...letters]
+        for (const letter of snapshot) {
+          const decision = await processingTask(letter)
+          if (decision.shouldEnqueue) {
+            // Requeue and stop — sequence is still blocked
+            await this.requeue(letter, {
+              cause: decision.cause,
+              diagnostics: decision.diagnostics,
+            })
+            return true
+          }
+          // Evict — successfully reprocessed
+          await this.evict(oldestId!, letter)
+        }
+        return true
+      } finally {
+        processing.delete(oldestId)
+      }
+    },
+
+    size() {
+      let total = 0
+      for (const letters of sequences.values()) {
+        total += letters.length
+      }
+      return total
+    },
+
+    amountOfSequences() {
+      return sequences.size
+    },
+
+    async clear() {
+      sequences.clear()
+      processing.clear()
+    },
+
+    isFull(sequenceIdentifier) {
+      const seq = sequences.get(sequenceIdentifier)
+      if (seq) {
+        return seq.length >= maxSequenceSize
+      }
+      return sequences.size >= maxSequences
+    },
+  }
+}
+
+/**
+ * Thrown when the dead letter queue is full.
+ */
+export class DeadLetterQueueOverflowError extends Error {
+  constructor(message: string) {
+    super(`Dead letter queue overflow: ${message}`)
+    this.name = "DeadLetterQueueOverflowError"
+  }
+}
+
+/**
+ * Creates a DeadLetter from a failed event.
+ */
+export function createDeadLetter(
+  message: EventMessage,
+  cause: Error,
+  sequenceIdentifier: string,
+  diagnostics?: Record<string, unknown>,
+): DeadLetter {
+  const now = Date.now()
+  return {
+    message,
+    cause,
+    enqueuedAt: now,
+    lastTouched: now,
+    diagnostics: diagnostics ?? {},
+    sequenceIdentifier,
+  }
+}

package/src/dead-lettering-handler.ts

@@ -0,0 +1,109 @@
+import { qualifiedNameToString } from "@kronos-ts/common"
+import type { EventMessage } from "./message.js"
+import type { EventHandlerRegistration } from "./handler.js"
+import type { SequencedEvent } from "./event-source.js"
+import {
+  type SequencedDeadLetterQueue,
+  type EnqueuePolicy,
+  alwaysEnqueuePolicy,
+  createDeadLetter,
+} from "./dead-letter-queue.js"
+
+/**
+ * Options for dead-lettering event handler wrapper.
+ */
+export interface DeadLetteringOptions {
+  /** The dead letter queue to use. */
+  queue: SequencedDeadLetterQueue
+  /** Policy deciding whether to dead-letter a failed event. Default: always. */
+  policy?: EnqueuePolicy
+  /**
+   * Extract a sequence identifier from an event. Events in the same
+   * sequence are ordered — if one fails, subsequent ones are blocked.
+   * Default: uses the first tag value or event name.
+   */
+  sequenceIdentifier?: (event: EventMessage) => string
+}
+
+/**
+ * Wraps event delivery with dead-letter support.
+ *
+ * When a handler fails:
+ * 1. Creates a DeadLetter and consults the EnqueuePolicy
+ * 2. If policy says enqueue: adds to DLQ, continues with next event
+ * 3. If policy says don't enqueue: error is swallowed
+ *
+ * When processing an event whose sequence already has dead letters:
+ * - The event is automatically dead-lettered (sequence is blocked)
+ * - This preserves ordering within the sequence
+ */
+export function createDeadLetteringDelivery(options: DeadLetteringOptions) {
+  const {
+    queue,
+    policy = alwaysEnqueuePolicy(),
+    sequenceIdentifier = defaultSequenceIdentifier,
+  } = options
+
+  return {
+    /**
+     * Deliver an event to handlers, with dead-letter support.
+     *
+     * The DLQ participates in any active transaction via ALS — both the
+     * caller and the DLQ implementation read transactional state from the
+     * UnitOfWork ALS store, no explicit ProcessingContext is threaded.
+     */
+    async deliver(
+      sequencedEvent: SequencedEvent,
+      handlers: Array<EventHandlerRegistration<any>>,
+    ): Promise<void> {
+      const event = sequencedEvent.event
+      const seqId = sequenceIdentifier(event)
+
+      // If this sequence already has dead letters, block this event too
+      const blocked = await queue.enqueueIfPresent(
+        seqId,
+        () => createDeadLetter(
+          event,
+          new Error("Blocked: previous event in sequence failed"),
+          seqId,
+          { blocked: true, position: Number(sequencedEvent.sequence) },
+        ),
+      )
+      if (blocked) return
+
+      // Try to deliver to all handlers
+      for (const reg of handlers) {
+        try {
+          await reg.handler(event.payload, event.metadata)
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err))
+          const letter = createDeadLetter(event, error, seqId, {
+            position: Number(sequencedEvent.sequence),
+            handlerName: qualifiedNameToString(reg.descriptor.name),
+          })
+
+          const decision = policy.decide(letter, error)
+          if (decision.shouldEnqueue) {
+            await queue.enqueue({
+              ...letter,
+              cause: decision.cause ?? letter.cause,
+              diagnostics: decision.diagnostics
+                ? { ...letter.diagnostics, ...decision.diagnostics }
+                : letter.diagnostics,
+            })
+          }
+          // Error is consumed by DLQ — don't propagate
+          return
+        }
+      }
+    },
+  }
+}
+
+function defaultSequenceIdentifier(event: EventMessage): string {
+  // Use first tag value if available, otherwise event name
+  if (event.tags && event.tags.length > 0) {
+    return event.tags[0]!.value
+  }
+  return qualifiedNameToString(event.name)
+}

package/src/descriptor.ts

@@ -0,0 +1,176 @@
+import type { z } from "zod"
+import type { QualifiedName, Tag } from "@kronos-ts/common"
+import { tagsFromRecord } from "@kronos-ts/common"
+
+/**
+ * Describes a command message type — its name, payload schema,
+ * and optional result schema for typed gateway returns.
+ */
+export interface CommandDescriptor<
+  P extends z.ZodType = z.ZodType,
+  R extends z.ZodType | undefined = undefined,
+> {
+  readonly kind: "command"
+  readonly name: QualifiedName
+  /** Version of the command. Default: "1.0". */
+  readonly version: string
+  readonly payload: P
+  /** Optional result schema — enables typed return from `commandGateway.send()`. */
+  readonly result?: R
+  /**
+   * The payload field that contains the routing key for distributed command routing.
+   *
+   * Used by the command gateway to extract the routing key before dispatch.
+   * Commands with the same routing key are routed to the same handler instance.
+   */
+  readonly routingKey?: string
+}
+
+/**
+ * Describes an event message type — its name, payload schema, and tag derivation.
+ * Tags define how events are indexed for criteria-based sourcing.
+ */
+export interface EventDescriptor<P extends z.ZodType = z.ZodType> {
+  readonly kind: "event"
+  readonly name: QualifiedName
+  readonly version: string
+  readonly payload: P
+  readonly tags?: (payload: z.infer<P>) => Tag[]
+}
+
+/**
+ * Describes a query message type — its name, payload schema,
+ * and optional result schema for typed gateway returns.
+ */
+export interface QueryDescriptor<
+  P extends z.ZodType = z.ZodType,
+  R extends z.ZodType | undefined = undefined,
+> {
+  readonly kind: "query"
+  readonly name: QualifiedName
+  /** Version of the query. Default: "1.0". */
+  readonly version: string
+  readonly payload: P
+  /** Optional result schema — enables typed return from `queryGateway.query()`. */
+  readonly result?: R
+}
+
+/** Any message descriptor. */
+export type MessageDescriptor =
+  | CommandDescriptor
+  | EventDescriptor
+  | QueryDescriptor
+
+/**
+ * Creates a command descriptor.
+ *
+ * Without result schema (void command):
+ * ```
+ * const CreateCourse = command({
+ *   name: qn("university", "CreateCourse"),
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ *   routingKey: "courseId",
+ * })
+ * ```
+ *
+ * With result schema (typed return):
+ * ```
+ * const CreateCourse = command({
+ *   name: qn("university", "CreateCourse"),
+ *   payload: z.object({ courseId: z.string() }),
+ *   result: z.object({ courseId: z.string() }),
+ *   routingKey: "courseId",
+ * })
+ * // commandGateway.send(CreateCourse, { courseId: "cs-101" }) → Promise<{ courseId: string }>
+ * ```
+ */
+export function command<P extends z.ZodType>(def: {
+  name: QualifiedName
+  version?: string
+  payload: P
+  routingKey?: string
+}): CommandDescriptor<P, undefined>
+
+export function command<P extends z.ZodType, R extends z.ZodType>(def: {
+  name: QualifiedName
+  version?: string
+  payload: P
+  result: R
+  routingKey?: string
+}): CommandDescriptor<P, R>
+
+export function command(def: any): CommandDescriptor {
+  return { kind: "command" as const, version: def.version ?? "1.0", ...def }
+}
+
+/**
+ * Creates an event descriptor.
+ *
+ * Tags can return `Tag[]` or a `Record<string, string>`:
+ * ```typescript
+ * event({
+ *   name: qn("university", "CourseCreated"),
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ *   tags: (p) => ({ courseId: p.courseId }),
+ * })
+ * ```
+ */
+export function event<P extends z.ZodType>(def: {
+  name: QualifiedName
+  version?: string
+  payload: P
+  tags?: (payload: z.infer<P>) => Tag[] | Record<string, string>
+}): EventDescriptor<P> {
+  const rawTags = def.tags
+  const tags: ((payload: z.infer<P>) => Tag[]) | undefined = rawTags
+    ? (payload: z.infer<P>): Tag[] => {
+        const result = rawTags(payload)
+        return Array.isArray(result) ? result : tagsFromRecord(result)
+      }
+    : undefined
+  return {
+    kind: "event" as const,
+    name: def.name,
+    version: def.version ?? "1.0",
+    payload: def.payload,
+    ...(tags ? { tags } : {}),
+  }
+}
+
+/**
+ * Creates a query descriptor.
+ *
+ * Without result schema:
+ * ```
+ * const GetCourse = query({
+ *   name: qn("university", "GetCourseView"),
+ *   payload: z.object({ courseId: z.string() }),
+ * })
+ * ```
+ *
+ * With result schema (typed return):
+ * ```
+ * const GetCourse = query({
+ *   name: qn("university", "GetCourseView"),
+ *   payload: z.object({ courseId: z.string() }),
+ *   result: z.object({ courseId: z.string(), name: z.string() }),
+ * })
+ * // queryGateway.query(GetCourse, { courseId: "cs-101" }) → Promise<{ courseId: string, name: string }>
+ * ```
+ */
+export function query<P extends z.ZodType>(def: {
+  name: QualifiedName
+  version?: string
+  payload: P
+}): QueryDescriptor<P, undefined>
+
+export function query<P extends z.ZodType, R extends z.ZodType>(def: {
+  name: QualifiedName
+  version?: string
+  payload: P
+  result: R
+}): QueryDescriptor<P, R>
+
+export function query(def: any): QueryDescriptor {
+  return { kind: "query" as const, version: def.version ?? "1.0", ...def }
+}

package/src/emit-update.ts

@@ -0,0 +1,35 @@
+import type { z } from "zod"
+import { resourceKey, qualifiedNameToString, type ResourceKey } from "@kronos-ts/common"
+import { requireInvocationPhase } from "./processing-state.js"
+import type { QueryBus } from "./query-bus.js"
+import type { QueryDescriptor } from "./descriptor.js"
+
+/** Emit a subscription-query update from within the current processing context. */
+export interface EmitUpdateFunction {
+  <Q extends z.ZodType>(
+    query: QueryDescriptor<Q>,
+    filter: (query: z.infer<Q>) => boolean,
+    update: unknown,
+  ): void
+}
+
+/**
+ * Resource key for the query bus component.
+ * Written by handling modules + processors at handler-invocation entry (D-44).
+ */
+export const QUERY_BUS_KEY: ResourceKey<QueryBus> = resourceKey("queryBus")
+
+/**
+ * Plan 04-01 (HDL-02 / D-42): module-level emitUpdate.
+ *
+ * Throws NoActiveUnitOfWork outside a UoW; throws WrongUoWPhase outside
+ * INVOCATION phase (D-43 mutator guard). Emits a subscription query update
+ * through the active query bus.
+ */
+export const emitUpdate: EmitUpdateFunction = (queryDescriptor, filter, update) => {
+  const state = requireInvocationPhase() // D-43 mutator guard
+  const bus = state.resources.get(QUERY_BUS_KEY.symbol) as QueryBus | undefined
+  if (!bus) throw new Error("No query bus configured")
+  const queryName = qualifiedNameToString(queryDescriptor.name)
+  bus.emitUpdate(queryName, filter as (q: unknown) => boolean, update)
+}

package/src/event-bus.ts

@@ -0,0 +1,45 @@
+import type { EventMessage } from "./message.js"
+import type { EventSink } from "./event-sink.js"
+
+/**
+ * Subscribable source of events — push-based delivery.
+ */
+export interface SubscribableEventSource {
+  /**
+   * Subscribe to events as they are published.
+   * Returns an unsubscribe function.
+   *
+   * @param handler Called with each batch of events as they are appended.
+   */
+  subscribe(handler: (events: ReadonlyArray<EventMessage>) => Promise<void>): () => void
+}
+
+/**
+ * The event bus — combines event publication (EventSink) with
+ * push-based subscription (SubscribableEventSource).
+ *
+ * In event sourcing setups, the EventStore serves as the EventBus.
+ * In non-event-sourcing setups, SimpleEventBus provides in-memory distribution.
+ */
+export interface EventBus extends SubscribableEventSource, EventSink {}
+
+/**
+ * In-memory event bus for non-event-sourcing scenarios.
+ * Publishes events directly to all subscribers.
+ */
+export function createSimpleEventBus(): EventBus {
+  const subscribers = new Set<(events: ReadonlyArray<EventMessage>) => Promise<void>>()
+
+  return {
+    async publish(events) {
+      for (const subscriber of subscribers) {
+        try { await subscriber(events) } catch { /* ignore subscriber errors */ }
+      }
+    },
+
+    subscribe(handler) {
+      subscribers.add(handler)
+      return () => { subscribers.delete(handler) }
+    },
+  }
+}