@kronos-ts/messaging 0.1.0

package/src/event-source.ts

@@ -0,0 +1,301 @@
+import type { EventMessage } from "./message.js"
+import type { EventCriteria } from "./event-criteria.js"
+import type { TrackingToken } from "./tracking-token.js"
+
+/**
+ * An event with its global sequence position.
+ */
+export interface SequencedEvent {
+  readonly sequence: bigint
+  readonly event: EventMessage
+}
+
+/**
+ * Condition for opening a streaming event source.
+ * Defines the starting position and optional event criteria filter.
+ */
+export interface StreamingCondition {
+  /** Position to start streaming from. */
+  readonly position: bigint
+  /** Optional criteria to filter events. When omitted, all events are delivered. */
+  readonly criteria?: EventCriteria
+}
+
+/**
+ * A push-based message stream. Events are buffered internally and
+ * pulled via {@link next}. The stream notifies when events become
+ * available via {@link setCallback}.
+ */
+export interface MessageStream<M> {
+  /** Pull the next available item (non-blocking). */
+  next(): M | undefined
+  /** Peek at the next item without consuming it. */
+  peek(): M | undefined
+  /** Check if there are items ready to be pulled. */
+  hasNextAvailable(): boolean
+  /** Whether the stream has been completed. */
+  isCompleted(): boolean
+  /** The error that caused the stream to fail, if any. */
+  error(): Error | undefined
+  /** Register a callback for when items become available. */
+  setCallback(callback: () => void): void
+  /** Close the stream and release resources. */
+  close(): void
+  /** Transform each item. */
+  map<R>(mapper: (item: M) => R): MessageStream<R>
+  /** Filter items by predicate. */
+  filter(predicate: (item: M) => boolean): MessageStream<M>
+  /** Recover from stream errors by providing a continuation stream. */
+  onErrorContinue(recovery: (error: Error) => MessageStream<M>): MessageStream<M>
+  /** Reduce all items to a single value. Resolves when the stream completes. */
+  reduce<R>(identity: R, accumulator: (acc: R, item: M) => R): Promise<R>
+  /** Concatenate another stream after this one completes. */
+  concatWith(other: MessageStream<M>): MessageStream<M>
+}
+
+/**
+ * Creates a MessageStream that wraps a source with transformation support.
+ * Used by event store implementations to provide stream instances.
+ */
+export function createMessageStream<M>(source: {
+  next(): M | undefined
+  peek(): M | undefined
+  hasNextAvailable(): boolean
+  isCompleted(): boolean
+  error(): Error | undefined
+  setCallback(callback: () => void): void
+  close(): void
+}): MessageStream<M> {
+  const stream: MessageStream<M> = {
+    ...source,
+    map<R>(mapper: (item: M) => R): MessageStream<R> {
+      return createMappedStream(stream, mapper)
+    },
+    filter(predicate: (item: M) => boolean): MessageStream<M> {
+      return createFilteredStream(stream, predicate)
+    },
+    onErrorContinue(recovery: (error: Error) => MessageStream<M>): MessageStream<M> {
+      return createErrorRecoveryStream(stream, recovery)
+    },
+    reduce<R>(identity: R, accumulator: (acc: R, item: M) => R): Promise<R> {
+      return reduceStream(stream, identity, accumulator)
+    },
+    concatWith(other: MessageStream<M>): MessageStream<M> {
+      return createConcatStream(stream, other)
+    },
+  }
+  return stream
+}
+
+/**
+ * Creates a completed empty MessageStream.
+ */
+export function emptyMessageStream<M>(): MessageStream<M> {
+  return createMessageStream<M>({
+    next: () => undefined,
+    peek: () => undefined,
+    hasNextAvailable: () => false,
+    isCompleted: () => true,
+    error: () => undefined,
+    setCallback: () => {},
+    close: () => {},
+  })
+}
+
+/**
+ * Creates a MessageStream that immediately fails with the given error.
+ */
+export function failedMessageStream<M>(error: Error): MessageStream<M> {
+  return createMessageStream<M>({
+    next: () => undefined,
+    peek: () => undefined,
+    hasNextAvailable: () => false,
+    isCompleted: () => true,
+    error: () => error,
+    setCallback: () => {},
+    close: () => {},
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Stream transformations
+// ---------------------------------------------------------------------------
+
+function createMappedStream<M, R>(source: MessageStream<M>, mapper: (item: M) => R): MessageStream<R> {
+  return createMessageStream<R>({
+    next() {
+      const item = source.next()
+      return item !== undefined ? mapper(item) : undefined
+    },
+    peek() {
+      const item = source.peek()
+      return item !== undefined ? mapper(item) : undefined
+    },
+    hasNextAvailable: () => source.hasNextAvailable(),
+    isCompleted: () => source.isCompleted(),
+    error: () => source.error(),
+    setCallback: (cb) => source.setCallback(cb),
+    close: () => source.close(),
+  })
+}
+
+function createFilteredStream<M>(source: MessageStream<M>, predicate: (item: M) => boolean): MessageStream<M> {
+  let buffered: M | undefined
+
+  function advance(): M | undefined {
+    while (true) {
+      const item = source.next()
+      if (item === undefined) return undefined
+      if (predicate(item)) return item
+    }
+  }
+
+  return createMessageStream<M>({
+    next() {
+      if (buffered !== undefined) {
+        const item = buffered
+        buffered = undefined
+        return item
+      }
+      return advance()
+    },
+    peek() {
+      if (buffered !== undefined) return buffered
+      buffered = advance()
+      return buffered
+    },
+    hasNextAvailable() {
+      if (buffered !== undefined) return true
+      buffered = advance()
+      return buffered !== undefined
+    },
+    isCompleted: () => source.isCompleted() && buffered === undefined,
+    error: () => source.error(),
+    setCallback: (cb) => source.setCallback(cb),
+    close: () => source.close(),
+  })
+}
+
+function createErrorRecoveryStream<M>(
+  source: MessageStream<M>,
+  recovery: (error: Error) => MessageStream<M>,
+): MessageStream<M> {
+  let current: MessageStream<M> = source
+  let recovered = false
+
+  function checkRecovery(): void {
+    if (!recovered && current.error()) {
+      current = recovery(current.error()!)
+      recovered = true
+    }
+  }
+
+  return createMessageStream<M>({
+    next() { checkRecovery(); return current.next() },
+    peek() { checkRecovery(); return current.peek() },
+    hasNextAvailable() { checkRecovery(); return current.hasNextAvailable() },
+    isCompleted() { checkRecovery(); return current.isCompleted() },
+    error() { return recovered ? current.error() : undefined },
+    setCallback(cb) { current.setCallback(cb) },
+    close() { current.close() },
+  })
+}
+
+function createConcatStream<M>(first: MessageStream<M>, second: MessageStream<M>): MessageStream<M> {
+  let usingFirst = true
+
+  function current(): MessageStream<M> {
+    if (usingFirst && first.isCompleted() && !first.hasNextAvailable()) {
+      usingFirst = false
+    }
+    return usingFirst ? first : second
+  }
+
+  return createMessageStream<M>({
+    next() { return current().next() },
+    peek() { return current().peek() },
+    hasNextAvailable() { return current().hasNextAvailable() },
+    isCompleted() { return current().isCompleted() },
+    error() { return current().error() },
+    setCallback(cb) {
+      if (usingFirst) {
+        first.setCallback(() => {
+          if (first.isCompleted() && !first.hasNextAvailable()) {
+            usingFirst = false
+            second.setCallback(cb)
+            cb()
+          } else {
+            cb()
+          }
+        })
+      } else {
+        second.setCallback(cb)
+      }
+    },
+    close() { first.close(); second.close() },
+  })
+}
+
+async function reduceStream<M, R>(
+  stream: MessageStream<M>,
+  identity: R,
+  accumulator: (acc: R, item: M) => R,
+): Promise<R> {
+  let result = identity
+  return new Promise<R>((resolve, reject) => {
+    function drain() {
+      while (true) {
+        const item = stream.next()
+        if (item !== undefined) {
+          result = accumulator(result, item)
+          continue
+        }
+        if (stream.error()) {
+          reject(stream.error())
+          return
+        }
+        if (stream.isCompleted()) {
+          resolve(result)
+          return
+        }
+        // Wait for more items
+        stream.setCallback(drain)
+        return
+      }
+    }
+    drain()
+  })
+}
+
+// ---------------------------------------------------------------------------
+// StreamableEventSource
+// ---------------------------------------------------------------------------
+
+/**
+ * A source of events that can be opened as an infinite stream.
+ */
+export interface StreamableEventSource {
+  /**
+   * Open an infinite event stream starting from the given condition.
+   */
+  open(condition: StreamingCondition): MessageStream<SequencedEvent>
+
+  /**
+   * Get the token representing the beginning of the event stream.
+   * A processor starting from this token will read all events.
+   */
+  firstToken(): Promise<TrackingToken>
+
+  /**
+   * Get the token representing the current tail of the event stream.
+   * A processor starting from this token will only see new events.
+   */
+  latestToken(): Promise<TrackingToken>
+
+  /**
+   * Get the current head position — the sequence of the next event
+   * to be appended. Convenience method equivalent to
+   * {@code (await latestToken()).position()}.
+   */
+  getHeadPosition(): Promise<bigint>
+}

package/src/gateway.ts

@@ -0,0 +1,144 @@
+import {
+  generateIdentifier,
+  emptyMetadata,
+  type Metadata,
+} from "@kronos-ts/common"
+import type { CommandBus } from "./command-bus.js"
+import type { QueryBus } from "./query-bus.js"
+import type { CommandDescriptor, QueryDescriptor } from "./descriptor.js"
+import type { SubscriptionQueryResult } from "./subscription-query.js"
+import { runInNewUoW, type UoWRunner } from "./unit-of-work.js"
+import type { z } from "zod"
+
+/**
+ * Infers the result type from a descriptor's `result` schema.
+ * If no result schema, returns `unknown`.
+ */
+type InferResult<R extends z.ZodType | undefined> =
+  R extends z.ZodType ? z.infer<R> : unknown
+
+/**
+ * User-facing command gateway. Wraps payloads into proper command messages
+ * and delegates to the command bus.
+ *
+ * When the command descriptor has a `result` schema, the return type is inferred:
+ * ```typescript
+ * const CreateCourse = command({
+ *   name: qn("university", "CreateCourse"),
+ *   payload: z.object({ courseId: z.string() }),
+ *   result: z.object({ id: z.string() }),
+ * })
+ *
+ * const result = await gateway.send(CreateCourse, { courseId: "cs-101" })
+ * //    ^ { id: string } — inferred from descriptor
+ * ```
+ */
+export interface CommandGateway {
+  send<P extends z.ZodType, R extends z.ZodType | undefined = undefined>(
+    descriptor: CommandDescriptor<P, R>,
+    payload: z.infer<P>,
+    metadata?: Metadata,
+  ): Promise<InferResult<R>>
+}
+
+/**
+ * User-facing query gateway. Wraps payloads into proper query messages
+ * and delegates to the query bus.
+ *
+ * When the query descriptor has a `result` schema, the return type is inferred:
+ * ```typescript
+ * const GetCourse = query({
+ *   name: qn("university", "GetCourseView"),
+ *   payload: z.object({ courseId: z.string() }),
+ *   result: z.object({ courseId: z.string(), name: z.string() }),
+ * })
+ *
+ * const course = await gateway.query(GetCourse, { courseId: "cs-101" })
+ * //    ^ { courseId: string, name: string } — inferred from descriptor
+ * ```
+ */
+export interface QueryGateway {
+  query<P extends z.ZodType, R extends z.ZodType | undefined = undefined>(
+    descriptor: QueryDescriptor<P, R>,
+    payload: z.infer<P>,
+    metadata?: Metadata,
+  ): Promise<InferResult<R>>
+
+  subscriptionQuery<P extends z.ZodType, R extends z.ZodType | undefined = undefined>(
+    descriptor: QueryDescriptor<P, R>,
+    payload: z.infer<P>,
+    metadata?: Metadata,
+  ): SubscriptionQueryResult
+}
+
+/**
+ * Creates a command gateway backed by a command bus.
+ *
+ * Plan 03-04 (CTX-04 / D-34): the optional `unitOfWorkRunner` lets the
+ * configurer inject a transactional wrapper (`transactionalUnitOfWorkFactory`)
+ * around the dispatch boundary. Defaults to `runInNewUoW` — preserves the
+ * Plan 03-01 contract that every gateway call starts a fresh UoW.
+ */
+export function createCommandGateway(
+  bus: CommandBus,
+  unitOfWorkRunner: UoWRunner = runInNewUoW,
+): CommandGateway {
+  return {
+    async send(descriptor, payload, metadata) {
+      const resolvedMetadata = metadata ?? emptyMetadata()
+      // Plan 03-01 (D-32) / Plan 03-03 (CTX-01): gateways always start a new
+      // UoW. The bus.dispatch call below will detect the ALS state we just
+      // established (via runInUoW in simple-command-bus) and reuse it — so
+      // this is the single UoW boundary for the dispatch chain. No
+      // ProcessingContext parameter is threaded.
+      return unitOfWorkRunner(resolvedMetadata, () =>
+        bus.dispatch({
+          identifier: generateIdentifier(),
+          name: descriptor.name,
+          payload,
+          metadata: resolvedMetadata,
+          timestamp: Date.now(),
+        }) as Promise<any>,
+      ) as any
+    },
+  }
+}
+
+/**
+ * Creates a query gateway backed by a query bus.
+ *
+ * See `createCommandGateway` for the `unitOfWorkRunner` injection contract.
+ */
+export function createQueryGateway(
+  bus: QueryBus,
+  unitOfWorkRunner: UoWRunner = runInNewUoW,
+): QueryGateway {
+  return {
+    async query(descriptor, payload, metadata) {
+      const resolvedMetadata = metadata ?? emptyMetadata()
+      // Plan 03-01 (D-32) / Plan 03-03 (CTX-01): gateway always starts a new
+      // UoW; bus.query auto-nests via runInUoW in simple-query-bus.
+      // subscriptionQuery below stays as-is — its initialResult goes through
+      // bus.query, which handles its own UoW.
+      return unitOfWorkRunner(resolvedMetadata, () =>
+        bus.query({
+          identifier: generateIdentifier(),
+          name: descriptor.name,
+          payload,
+          metadata: resolvedMetadata,
+          timestamp: Date.now(),
+        }) as Promise<any>,
+      ) as any
+    },
+
+    subscriptionQuery(descriptor, payload, metadata) {
+      return bus.subscriptionQuery({
+        identifier: generateIdentifier(),
+        name: descriptor.name,
+        payload,
+        metadata: metadata ?? emptyMetadata(),
+        timestamp: Date.now(),
+      })
+    },
+  }
+}

package/src/handler-enhancer.ts

@@ -0,0 +1,70 @@
+/**
+ * Metadata about a handler being enhanced. Allows enhancers to
+ * selectively wrap based on handler type, message name, etc.
+ */
+export interface HandlerMetadata {
+  /** The type of message this handler processes. */
+  readonly messageType: "command" | "event" | "query"
+  /** The qualified name of the message (e.g., "university.courses.CreateCourse"). */
+  readonly messageName: string
+  /** The name of the handler group or module (e.g., "course-commands"). */
+  readonly handlerGroup: string
+}
+
+/**
+ * Wraps message handler functions at registration time to add cross-cutting
+ * concerns. Different from interceptors — interceptors wrap dispatch,
+ * enhancers wrap the handler itself.
+ *
+ * Applied once at handler discovery/registration time, not per-invocation.
+ * This makes enhancers ideal for:
+ * - Tracing spans per-handler
+ * - Security checks
+ * - Timeout enforcement
+ * - Caching
+ *
+ * @example
+ * ```ts
+ * const timingEnhancer: HandlerEnhancerDefinition = {
+ *   wrapHandler(handler, metadata) {
+ *     return async (...args) => {
+ *       const start = performance.now()
+ *       try {
+ *         return await handler(...args)
+ *       } finally {
+ *         console.log(`${metadata.messageName} took ${performance.now() - start}ms`)
+ *       }
+ *     }
+ *   },
+ * }
+ * ```
+ */
+export interface HandlerEnhancerDefinition {
+  /**
+   * Wrap a handler function. Return the original handler to skip enhancement.
+   * The returned function must have the same signature as the input.
+   */
+  wrapHandler<T extends (...args: any[]) => any>(
+    handler: T,
+    metadata: HandlerMetadata,
+  ): T
+}
+
+/**
+ * Combines multiple handler enhancer definitions into a single one.
+ * Enhancers are applied in order — the first enhancer wraps outermost.
+ */
+export function multiHandlerEnhancerDefinition(
+  enhancers: ReadonlyArray<HandlerEnhancerDefinition>,
+): HandlerEnhancerDefinition {
+  return {
+    wrapHandler<T extends (...args: any[]) => any>(handler: T, metadata: HandlerMetadata): T {
+      let wrapped = handler
+      // Apply in reverse order so first enhancer is outermost
+      for (let i = enhancers.length - 1; i >= 0; i--) {
+        wrapped = enhancers[i]!.wrapHandler(wrapped, metadata)
+      }
+      return wrapped
+    },
+  }
+}

package/src/handler.ts

@@ -0,0 +1,133 @@
+import type { z } from "zod"
+import type { Metadata } from "@kronos-ts/common"
+import type {
+  CommandDescriptor,
+  EventDescriptor,
+  QueryDescriptor,
+} from "./descriptor.js"
+
+// ---------------------------------------------------------------------------
+// Handler context shapes — DELETED (Plan 04-02, D-41)
+// CommandHandlerContext / EventHandlerContext / QueryHandlerContext removed.
+// LoadFunction / AppendFunction / SendFunction / EmitUpdateFunction removed.
+// Consumers import load/append from @kronos-ts/eventsourcing and
+// send/dispatch/emitUpdate from @kronos-ts/messaging directly.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Registration types
+// ---------------------------------------------------------------------------
+
+/** A paired event descriptor + handler function, used in handler arrays. */
+export interface EventHandlerRegistration<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
+}
+
+/**
+ * A paired event descriptor + evolver function, used in entity evolve arrays.
+ *
+ * Evolvers can be sync or async. Async evolvers don't block the event loop
+ * during state reconstruction.
+ */
+export interface EvolverRegistration<
+  S = unknown,
+  P extends z.ZodType = z.ZodType,
+> {
+  readonly kind: "evolver"
+  readonly descriptor: EventDescriptor<P>
+  readonly evolve: (state: S, event: z.infer<P>, id: unknown) => S | Promise<S>
+}
+
+/** A paired query descriptor + handler function, with result type on the handler. */
+export interface QueryHandlerRegistration<
+  Q extends z.ZodType = z.ZodType,
+  R = unknown,
+> {
+  readonly kind: "query-handler"
+  readonly descriptor: QueryDescriptor<Q>
+  readonly handler: (
+    query: z.infer<Q>,
+    metadata: Metadata,
+  ) => Promise<R> | R
+}
+
+// ---------------------------------------------------------------------------
+// on() — universal registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Universal registration function.
+ * Pairs a descriptor with its handler for use in handler/evolve arrays.
+ *
+ * Usage:
+ * - Event handlers:  `on(CourseCreated, async (event, ctx) => { ... })`
+ * - Query handlers:  `on(GetCourse, async (query, ctx) => { return { ... } })`
+ * - Evolvers:        `on(CourseCreated, (state, event) => ({ ...state, name: event.name }))`
+ *
+ * The overload is resolved by the descriptor kind and how many arguments
+ * the callback declares. Evolvers receive `(state, event)` or `(state, event, id)`,
+ * while event handlers receive `(event, context)`.
+ *
+ * In practice the distinction is enforced by the array type:
+ * - `evolve: [on(...)]` expects `EvolverRegistration`
+ * - `handlers: [on(...)]` expects `EventHandlerRegistration`
+ */
+
+// Overload: evolver (event descriptor + state evolve function)
+export function on<S, P extends z.ZodType>(
+  descriptor: EventDescriptor<P>,
+  evolve: (state: S, event: z.infer<P>, id: unknown) => S | Promise<S>,
+): EvolverRegistration<S, P>
+
+// Overload: event handler (event descriptor + handler function)
+export function on<P extends z.ZodType>(
+  descriptor: EventDescriptor<P>,
+  handler: (event: z.infer<P>, metadata: Metadata) => Promise<void> | void,
+): EventHandlerRegistration<P>
+
+// Overload: query handler
+export function on<Q extends z.ZodType, R>(
+  descriptor: QueryDescriptor<Q>,
+  handler: (
+    query: z.infer<Q>,
+    metadata: Metadata,
+  ) => Promise<R> | R,
+): QueryHandlerRegistration<Q, R>
+
+export function on(
+  descriptor: EventDescriptor | QueryDescriptor,
+  handler: (...args: any[]) => any,
+): EventHandlerRegistration | EvolverRegistration | QueryHandlerRegistration {
+  if (descriptor.kind === "event") {
+    // For event descriptors, the same `on()` call is used for both event handlers
+    // and evolvers. We return an object that satisfies both interfaces — the
+    // consumer's array type (evolve: EvolverRegistration[] vs handlers: EventHandlerRegistration[])
+    // enforces correct usage at compile time.
+    return {
+      kind: "event-handler" as any,
+      descriptor: descriptor as EventDescriptor,
+      handler,
+      evolve: handler,
+    }
+  }
+  return {
+    kind: "query-handler",
+    descriptor: descriptor as QueryDescriptor,
+    handler,
+  }
+}
+
+/**
+ * @deprecated Use `on()` instead. `onEvent` is kept for backward compatibility.
+ */
+export function onEvent<S, P extends z.ZodType>(
+  descriptor: EventDescriptor<P>,
+  evolve: (state: S, event: z.infer<P>, id: unknown) => S | Promise<S>,
+): EvolverRegistration<S, P> {
+  return { kind: "evolver", descriptor, evolve }
+}