@kronos-ts/messaging 0.1.0

package/src/event-criteria.ts

@@ -0,0 +1,141 @@
+import type { Tag, QualifiedName } from "@kronos-ts/common"
+import { qualifiedNameToString, tagsFromRecord } from "@kronos-ts/common"
+import type { EventDescriptor } from "./descriptor.js"
+
+/**
+ * Criteria for selecting events from the event store.
+ * Used for both sourcing conditions (which events to load) and
+ * append conditions (which events define the consistency boundary).
+ *
+ * Criteria are composable via `or()` and restrictable via `ofTypes()`.
+ */
+export type EventCriteria =
+  | TagCriteria
+  | TypeRestrictedCriteria
+  | EitherCriteria
+  | AnyTagCriteria
+
+export interface TagCriteria {
+  readonly kind: "tags"
+  readonly tags: ReadonlyArray<Tag>
+}
+
+export interface TypeRestrictedCriteria {
+  readonly kind: "type-restricted"
+  readonly inner: TagCriteria | AnyTagCriteria
+  readonly types: ReadonlyArray<string>
+}
+
+export interface EitherCriteria {
+  readonly kind: "either"
+  readonly criteria: ReadonlyArray<EventCriteria>
+}
+
+export interface AnyTagCriteria {
+  readonly kind: "any-tag"
+}
+
+/**
+ * A tag or any-tag criteria that allows further restriction by event types.
+ */
+export type RestrictableEventCriteria = (TagCriteria | AnyTagCriteria) & {
+  /**
+   * Restrict matched events to the given types.
+   * Accepts event descriptors or qualified name strings.
+   */
+  ofTypes(...types: Array<EventDescriptor<any> | QualifiedName | string>): EventCriteria
+}
+
+function resolveTypeName(t: EventDescriptor<any> | QualifiedName | string): string {
+  if (typeof t === "string") return t
+  if ("kind" in t && t.kind === "event") return qualifiedNameToString(t.name)
+  if ("namespace" in t && "name" in t) return qualifiedNameToString(t as QualifiedName)
+  return String(t)
+}
+
+function makeRestrictable(criteria: TagCriteria | AnyTagCriteria): RestrictableEventCriteria {
+  return Object.assign(criteria, {
+    ofTypes(...types: Array<EventDescriptor<any> | QualifiedName | string>): EventCriteria {
+      return {
+        kind: "type-restricted" as const,
+        inner: criteria,
+        types: types.map(resolveTypeName),
+      }
+    },
+  })
+}
+
+export const EventCriteria = {
+  /**
+   * Match events having all the specified tags.
+   *
+   * Accepts individual Tag objects or a record of key-value pairs:
+   * ```typescript
+   * EventCriteria.havingTags({ courseId: id.courseId })
+   * EventCriteria.havingTags(tag("courseId", id.courseId))
+   * ```
+   */
+  havingTags(...args: Tag[] | [Record<string, string>]): RestrictableEventCriteria {
+    if (args.length === 1 && typeof args[0] === "object" && !("key" in args[0])) {
+      return makeRestrictable({ kind: "tags", tags: tagsFromRecord(args[0] as Record<string, string>) })
+    }
+    return makeRestrictable({ kind: "tags", tags: args as Tag[] })
+  },
+
+  /**
+   * Match events having any tag (i.e., all tagged events).
+   */
+  havingAnyTag(): RestrictableEventCriteria {
+    return makeRestrictable({ kind: "any-tag" })
+  },
+
+  /**
+   * Match events matching any of the given criteria (logical OR).
+   */
+  either(...criteria: EventCriteria[]): EventCriteria {
+    return { kind: "either", criteria }
+  },
+} as const
+
+// ---------------------------------------------------------------------------
+// Standalone shorthand functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Match events having all the specified tags.
+ *
+ * Shorthand for `EventCriteria.havingTags()`. Supports `.ofTypes()` chaining.
+ *
+ * ```typescript
+ * tags({ courseId: id.courseId })
+ * tags({ courseId: id.courseId }).ofTypes(CourseCreated, CourseCapacityChanged)
+ * ```
+ */
+export function tags(...args: Tag[] | [Record<string, string>]): RestrictableEventCriteria {
+  return EventCriteria.havingTags(...args)
+}
+
+/**
+ * Match events having any tag.
+ *
+ * Shorthand for `EventCriteria.havingAnyTag()`. Supports `.ofTypes()` chaining.
+ */
+export function anyTag(): RestrictableEventCriteria {
+  return EventCriteria.havingAnyTag()
+}
+
+/**
+ * Match events matching any of the given criteria (logical OR).
+ *
+ * Shorthand for `EventCriteria.either()`.
+ *
+ * ```typescript
+ * either(
+ *   tags({ courseId: id.courseId }),
+ *   tags({ studentId: id.studentId }).ofTypes(StudentSubscribed),
+ * )
+ * ```
+ */
+export function either(...criteria: EventCriteria[]): EventCriteria {
+  return EventCriteria.either(...criteria)
+}

package/src/event-gateway.ts

@@ -0,0 +1,42 @@
+import type { EventSink } from "./event-sink.js"
+import type { EventMessage } from "./message.js"
+import type { EventDescriptor } from "./descriptor.js"
+import { generateIdentifier } from "@kronos-ts/common"
+import type { z } from "zod"
+
+/**
+ * User-facing gateway for publishing events directly (without going through
+ * command handlers).
+ *
+ */
+export interface EventGateway {
+  /**
+   * Publish a single event described by its descriptor.
+   */
+  publish<P extends z.ZodType>(
+    descriptor: EventDescriptor<P>,
+    payload: z.infer<P>,
+    metadata?: Record<string, unknown>,
+  ): Promise<void>
+}
+
+/**
+ * Creates an event gateway backed by an event sink.
+ */
+export function createEventGateway(eventSink: EventSink): EventGateway {
+  return {
+    async publish(descriptor, payload, metadata = {}) {
+      const tags = descriptor.tags ? descriptor.tags(payload) : []
+      const event: EventMessage = {
+        identifier: generateIdentifier(),
+        name: descriptor.name,
+        version: descriptor.version,
+        payload,
+        metadata,
+        timestamp: Date.now(),
+        tags,
+      }
+      await eventSink.publish([event])
+    },
+  }
+}

package/src/event-handler.ts

@@ -0,0 +1,44 @@
+import type { z } from "zod"
+import type { Metadata } from "@kronos-ts/common"
+import type { EventDescriptor } from "./descriptor.js"
+
+// ---------------------------------------------------------------------------
+// Singular factory — mirrors commandHandler / queryHandler.
+// The processor builder consumes these via `.eventHandlers(...handlers)` varargs.
+// ---------------------------------------------------------------------------
+
+/**
+ * A registered singular event handler — pairs an event descriptor with its handler
+ * function. Mirrors {@link import("./command-handler.js").CommandHandlerDefinition}
+ * structurally so all three handler shapes (command / event / query) share the same
+ * pattern.
+ */
+export interface EventHandlerDefinition<P extends z.ZodType = z.ZodType> {
+  readonly kind: "event-handler"
+  readonly descriptor: EventDescriptor<P>
+  readonly handler: (
+    event: z.infer<P>,
+    metadata: Metadata,
+  ) => Promise<void> | void
+}
+
+/**
+ * Defines a singular event handler.
+ *
+ * ```
+ * const onCourseCreated = eventHandler(CourseCreated, async (event, metadata) => {
+ *   await db.courses.insert({ id: event.courseId, name: event.name })
+ * })
+ * ```
+ *
+ * Use with `trackingProcessor(...).eventHandlers(onCreated, onCapChanged).build()` or
+ * `subscribingProcessor(...).eventHandlers(...).build()`. Symmetric to
+ * {@link import("./command-handler.js").commandHandler} and
+ * {@link import("./query-handler.js").queryHandler}.
+ */
+export function eventHandler<P extends z.ZodType>(
+  descriptor: EventDescriptor<P>,
+  handler: (event: z.infer<P>, metadata: Metadata) => Promise<void> | void,
+): EventHandlerDefinition<P> {
+  return { kind: "event-handler", descriptor, handler }
+}

package/src/event-processor-builder.ts

@@ -0,0 +1,246 @@
+import type { EventHandlerDefinition } from "./event-handler.js"
+import type { TokenStore } from "./token-store.js"
+import type { UoWRunner } from "./unit-of-work.js"
+import type { EventProcessingErrorHandler } from "./tracking-event-processor.js"
+import type { SequencedDeadLetterQueue } from "./dead-letter-queue.js"
+
+/**
+ * Base configuration shared by all event processor types.
+ *
+ * Plan 11-02: option types carry a flat `eventHandlers: EventHandlerDefinition[]`
+ * array. The processor (not the handler bundle) owns reset semantics — see
+ * `TrackingProcessorModule.onReset`.
+ */
+interface EventProcessorBase {
+  readonly name: string
+  readonly eventHandlers: ReadonlyArray<EventHandlerDefinition>
+}
+
+/**
+ * Configuration for a tracking event processor (polling-based, with token store).
+ */
+export interface TrackingProcessorModule extends EventProcessorBase {
+  readonly kind: "tracking"
+  readonly batchSize?: number
+  readonly pollingIntervalMs?: number
+  readonly tokenStore?: TokenStore
+  readonly unitOfWorkRunner?: UoWRunner
+  readonly errorHandler?: EventProcessingErrorHandler
+  readonly deadLetterQueue?: SequencedDeadLetterQueue
+  /** Number of segments created on first startup. Default 16 (Axon Framework parity). Always set by builder.build(). */
+  readonly initialSegmentCount: number
+  readonly claimExtensionThresholdMs?: number
+  readonly tokenClaimIntervalMs?: number
+  /** Reset callback invoked when the processor is reset. Reset is processor-level (clear token + replay), and the callback that wipes view state belongs alongside it. */
+  readonly onReset?: () => Promise<void> | void
+}
+
+/**
+ * Configuration for a subscribing event processor (push-based, no tracking).
+ *
+ * Subscribing processors do not support reset — see `supportsReset()` on the
+ * runtime instance — so there is no `onReset` field here.
+ */
+export interface SubscribingProcessorModule extends EventProcessorBase {
+  readonly kind: "subscribing"
+  readonly unitOfWorkRunner?: UoWRunner
+  readonly errorHandler?: EventProcessingErrorHandler
+}
+
+export type EventProcessorModule = TrackingProcessorModule | SubscribingProcessorModule
+
+// ---------------------------------------------------------------------------
+// Tracking processor builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Builder for a tracking event processor.
+ *
+ * Tracking processors poll the event store for new events, maintain
+ * position via a token store, and support replay/reset.
+ *
+ * ```typescript
+ * const onCreated = eventHandler(CourseCreated, async (e) => { ... })
+ * const onCapChanged = eventHandler(CourseCapacityChanged, async (e) => { ... })
+ *
+ * trackingProcessor("course-projection")
+ *   .eventHandlers(onCreated, onCapChanged)
+ *   .onReset(async () => courseViews.clear())
+ *   .batchSize(50)
+ *   .build()
+ * ```
+ *
+ * NOTE: Pooled streaming processor support is deferred to a follow-up
+ * research phase exploring how that model should fit Node/Bun runtime
+ * semantics, where worker threads are not reservable the same way as JVM
+ * threads.
+ */
+export function trackingProcessor(name: string): TrackingProcessorBuilder {
+  return new TrackingProcessorBuilder(name)
+}
+
+export class TrackingProcessorBuilder {
+  private readonly _name: string
+  private readonly _eventHandlers: EventHandlerDefinition[] = []
+  private _onReset?: () => Promise<void> | void
+  private _batchSize?: number
+  private _pollingIntervalMs?: number
+  private _tokenStore?: TokenStore
+  private _unitOfWorkRunner?: UoWRunner
+  private _errorHandler?: EventProcessingErrorHandler
+  private _deadLetterQueue?: SequencedDeadLetterQueue
+  private _initialSegmentCount?: number
+  private _claimExtensionThresholdMs?: number
+  private _tokenClaimIntervalMs?: number
+
+  constructor(name: string) {
+    this._name = name
+  }
+
+  /** Register one or more singular event handlers on this processor. */
+  eventHandlers(...handlers: EventHandlerDefinition[]): this {
+    this._eventHandlers.push(...handlers)
+    return this
+  }
+
+  /** Register a callback fired when the processor is reset (clears view state for replay). */
+  onReset(fn: () => Promise<void> | void): this {
+    this._onReset = fn
+    return this
+  }
+
+  /** Events per batch/transaction. Default: 100. */
+  batchSize(size: number): this {
+    this._batchSize = size
+    return this
+  }
+
+  /** Polling interval in ms. Default: 500. */
+  pollingIntervalMs(ms: number): this {
+    this._pollingIntervalMs = ms
+    return this
+  }
+
+  /** Override the token store for this processor. */
+  tokenStore(store: TokenStore): this {
+    this._tokenStore = store
+    return this
+  }
+
+  /**
+   * Override the UnitOfWork runner for this processor. Compose with
+   * `transactionalUnitOfWorkFactory(runInUoW, txManager)` to attach
+   * transactional semantics.
+   */
+  unitOfWorkRunner(runner: UoWRunner): this {
+    this._unitOfWorkRunner = runner
+    return this
+  }
+
+  /** Override the error handler for this processor. */
+  errorHandler(handler: EventProcessingErrorHandler): this {
+    this._errorHandler = handler
+    return this
+  }
+
+  /** Set a dead letter queue for this processor. */
+  deadLetterQueue(queue: SequencedDeadLetterQueue): this {
+    this._deadLetterQueue = queue
+    return this
+  }
+
+  /** Number of segments to create on first startup. Default: 16 (Axon Framework parity). */
+  initialSegmentCount(count: number): this {
+    this._initialSegmentCount = count
+    return this
+  }
+
+  /** @internal Build the processor configuration. */
+  build(): TrackingProcessorModule {
+    return {
+      kind: "tracking",
+      name: this._name,
+      eventHandlers: this._eventHandlers,
+      batchSize: this._batchSize,
+      pollingIntervalMs: this._pollingIntervalMs,
+      tokenStore: this._tokenStore,
+      unitOfWorkRunner: this._unitOfWorkRunner,
+      errorHandler: this._errorHandler,
+      deadLetterQueue: this._deadLetterQueue,
+      initialSegmentCount: this._initialSegmentCount ?? 16,
+      claimExtensionThresholdMs: this._claimExtensionThresholdMs,
+      tokenClaimIntervalMs: this._tokenClaimIntervalMs,
+      onReset: this._onReset,
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Subscribing processor builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Builder for a subscribing event processor.
+ *
+ * Subscribing processors receive events pushed from the event source
+ * as they are appended. No token store, no position tracking, no replay.
+ *
+ * ```typescript
+ * const onNotification = eventHandler(NotificationRaised, async (e) => { ... })
+ *
+ * subscribingProcessor("notifications")
+ *   .eventHandlers(onNotification)
+ *   .build()
+ * ```
+ *
+ * Subscribing processors do NOT support reset (`supportsReset() === false`),
+ * so there is no `.onReset(fn)` builder method here — that lives on
+ * `TrackingProcessorBuilder` only.
+ */
+export function subscribingProcessor(name: string): SubscribingProcessorBuilder {
+  return new SubscribingProcessorBuilder(name)
+}
+
+export class SubscribingProcessorBuilder {
+  private readonly _name: string
+  private readonly _eventHandlers: EventHandlerDefinition[] = []
+  private _unitOfWorkRunner?: UoWRunner
+  private _errorHandler?: EventProcessingErrorHandler
+
+  constructor(name: string) {
+    this._name = name
+  }
+
+  /** Register one or more singular event handlers on this processor. */
+  eventHandlers(...handlers: EventHandlerDefinition[]): this {
+    this._eventHandlers.push(...handlers)
+    return this
+  }
+
+  /**
+   * Override the UnitOfWork runner for this processor. Compose with
+   * `transactionalUnitOfWorkFactory(runInUoW, txManager)` to attach
+   * transactional semantics.
+   */
+  unitOfWorkRunner(runner: UoWRunner): this {
+    this._unitOfWorkRunner = runner
+    return this
+  }
+
+  /** Override the error handler for this processor. */
+  errorHandler(handler: EventProcessingErrorHandler): this {
+    this._errorHandler = handler
+    return this
+  }
+
+  /** @internal Build the processor configuration. */
+  build(): SubscribingProcessorModule {
+    return {
+      kind: "subscribing",
+      name: this._name,
+      eventHandlers: this._eventHandlers,
+      unitOfWorkRunner: this._unitOfWorkRunner,
+      errorHandler: this._errorHandler,
+    }
+  }
+}

package/src/event-processor.ts

@@ -0,0 +1,9 @@
+/**
+ * Common interface for all event processors.
+ */
+export interface EventProcessor {
+  readonly name: string
+  readonly running: boolean
+  start(): Promise<void>
+  stop(): void
+}

package/src/event-sink.ts

@@ -0,0 +1,23 @@
+import type { EventMessage } from "./message.js"
+
+/**
+ * Publish-only abstraction for event publication.
+ *
+ * This is the messaging-level contract for publishing events. The EventGateway
+ * and command handlers use this to emit events without needing to know about
+ * event storage.
+ *
+ * Implementations include:
+ * - The EventStore (which persists AND publishes)
+ * - A simple EventBus (which only distributes to subscribers)
+ *
+ */
+export interface EventSink {
+  /**
+   * Publish events. The events are distributed to any subscribed handlers.
+   *
+   * In an event sourcing context, this also persists the events to the
+   * underlying storage engine.
+   */
+  publish(events: ReadonlyArray<EventMessage>): Promise<void>
+}