@kronos-ts/messaging 0.1.0

package/src/index.ts

@@ -0,0 +1,356 @@
+// Messages
+export {
+  type Message,
+  type CommandMessage,
+  type CommandResultMessage,
+  type EventMessage,
+  type QueryMessage,
+} from "./message.js"
+
+// Descriptors
+export {
+  type CommandDescriptor,
+  type EventDescriptor,
+  type QueryDescriptor,
+  type MessageDescriptor,
+  command,
+  event,
+  query,
+} from "./descriptor.js"
+
+// Event criteria
+export {
+  type TagCriteria,
+  type TypeRestrictedCriteria,
+  type EitherCriteria,
+  type AnyTagCriteria,
+  type RestrictableEventCriteria,
+  EventCriteria,
+  tags,
+  anyTag,
+  either,
+} from "./event-criteria.js"
+
+// Lifecycle phases (Plan 03-04: relocated from processing-context.ts)
+export {
+  Phase,
+  type PhaseValue,
+  // Module-level lifecycle accessors (CTX-03 / D-30)
+  on as onPhase,
+  onPrepareCommit,
+  onCommit,
+  onAfterCommit,
+  onError,
+  whenComplete,
+  NoActiveUnitOfWork,
+  WrongUoWPhase,
+} from "./processing-state.js"
+
+// Unit of Work runners (Plan 03-04: replaces UnitOfWorkFactory shape)
+export {
+  type UoWRunner,
+  runInUoW,
+  runInNewUoW,
+} from "./unit-of-work.js"
+
+// Handler registration
+// Note: Handler context wrapper types deleted (Plan 04-02 / D-41).
+// Helper function types deleted.
+// Consumers import load/append from @kronos-ts/eventsourcing and send/dispatch/emitUpdate from here directly.
+export {
+  type EventHandlerRegistration,
+  type EvolverRegistration,
+  type QueryHandlerRegistration,
+  on,
+  onEvent,
+} from "./handler.js"
+
+// Command handlers
+export {
+  type CommandHandlerDefinition,
+  commandHandler,
+} from "./command-handler.js"
+
+// Event handlers
+export {
+  type EventHandlerDefinition,
+  eventHandler,
+} from "./event-handler.js"
+
+// Query handlers
+export {
+  type QueryHandlerDefinition,
+  queryHandler,
+} from "./query-handler.js"
+
+// Interceptors
+export {
+  type DispatchInterceptor,
+  type HandlerInterceptor,
+} from "./interceptor.js"
+
+// Routing strategies
+export {
+  type RoutingStrategy,
+  metadataRoutingStrategy,
+  payloadFieldRoutingStrategy,
+} from "./routing-strategy.js"
+
+// Handler enhancers
+export {
+  type HandlerEnhancerDefinition,
+  type HandlerMetadata,
+  multiHandlerEnhancerDefinition,
+} from "./handler-enhancer.js"
+
+// Correlation data
+export {
+  type CorrelationDataProvider,
+  CORRELATION_DATA_KEY,
+  getActiveCorrelationData,
+  messageOriginProvider,
+  simpleCorrelationDataProvider,
+  correlationDataHandlerInterceptor,
+  correlationDataDispatchInterceptor,
+} from "./correlation-data.js"
+
+// Bus interfaces
+export { type CommandBus } from "./command-bus.js"
+export { type QueryBus } from "./query-bus.js"
+
+// Bus implementations
+export { createSimpleCommandBus } from "./simple-command-bus.js"
+export { createSimpleQueryBus } from "./simple-query-bus.js"
+
+// Intercepting bus decorators
+export { createInterceptingCommandBus } from "./intercepting-command-bus.js"
+export { createInterceptingQueryBus } from "./intercepting-query-bus.js"
+
+// Tracing bus decorators
+export { createTracingCommandBus } from "./tracing-command-bus.js"
+
+// Gateways
+export {
+  type CommandGateway,
+  type QueryGateway,
+  createCommandGateway,
+  createQueryGateway,
+} from "./gateway.js"
+
+// Subscription queries
+export {
+  type SubscriptionQueryResult,
+  type UpdateHandler,
+  createUpdateHandler,
+  runAfterCommitOrImmediately,
+} from "./subscription-query.js"
+
+// Event sink (publish-only)
+export { type EventSink } from "./event-sink.js"
+
+// Event bus (publish + subscribe)
+export {
+  type SubscribableEventSource,
+  type EventBus,
+  createSimpleEventBus,
+} from "./event-bus.js"
+
+// Intercepting event bus decorator
+export { createInterceptingEventBus } from "./intercepting-event-bus.js"
+
+// Event gateway
+export {
+  type EventGateway,
+  createEventGateway,
+} from "./event-gateway.js"
+
+// Event processor common interface
+export { type EventProcessor } from "./event-processor.js"
+
+// Event source (for processors)
+export {
+  type SequencedEvent,
+  type StreamableEventSource,
+  type StreamingCondition,
+  type MessageStream,
+  createMessageStream,
+  emptyMessageStream,
+  failedMessageStream,
+} from "./event-source.js"
+
+// Event processor
+export {
+  type TrackingEventProcessor,
+  type TrackingEventProcessorOptions,
+  type EventProcessingErrorHandler,
+  loggingErrorHandler,
+  propagatingErrorHandler,
+  createTrackingEventProcessor,
+} from "./tracking-event-processor.js"
+
+// Segments
+export {
+  type Segment,
+  ROOT_SEGMENT,
+  segment,
+  segmentMatches,
+  splitSegment,
+  mergeSegments,
+  isMergeable,
+  segmentCount,
+  hashOf,
+  createSegments,
+} from "./segment.js"
+
+// Token store
+export {
+  type TokenStore,
+  UnableToClaimTokenError,
+  createInMemoryTokenStore,
+} from "./token-store.js"
+
+// Tracking tokens
+export {
+  type TrackingToken,
+  type GlobalSequenceToken,
+  type ReplayToken,
+  globalSequenceToken,
+  FIRST_TOKEN,
+  LATEST_TOKEN,
+  replayToken,
+  isReplayToken,
+  isGlobalSequenceToken,
+  advanceToken,
+  isReplaying,
+  unwrapToken,
+  wasProcessedBeforeReset,
+} from "./tracking-token.js"
+
+// Replay detection (ProcessingContext helper)
+export {
+  isReplay,
+  REPLAY_STATE_KEY,
+} from "./replay-token.js"
+
+// Transaction management
+export {
+  type TransactionManager,
+  noTransactionManager,
+  getActiveTransaction,
+  transactionalUnitOfWorkFactory,
+  TRANSACTION_KEY,
+} from "./transaction.js"
+
+// Retrying command bus
+export {
+  type RetryPolicy,
+  exponentialBackoffRetryPolicy,
+  createRetryingCommandBus,
+} from "./retrying-command-bus.js"
+
+// Module-level handler helpers (Plan 04-01 / HDL-02 / D-42)
+export { send, COMMAND_BUS_KEY } from "./send.js"
+export { emitUpdate, QUERY_BUS_KEY } from "./emit-update.js"
+
+// Modules — Plan 08-03a (D-82): function-style helpers replace Module-shape factories
+export {
+  registerCommandHandlersNatively,
+  createCommandInvocation,
+  type MinimalConfiguration,
+} from "./command-handling-module.js"
+export { registerQueryHandlersNatively } from "./query-handling-module.js"
+
+// Subscribing event processor
+export {
+  type SubscribingEventProcessor,
+  type SubscribingEventProcessorOptions,
+  createSubscribingEventProcessor,
+} from "./subscribing-event-processor.js"
+
+// Streaming event processor
+export {
+  type StreamingEventProcessor,
+  type StreamingEventProcessorOptions,
+  type EventProcessorStatus,
+  createStreamingEventProcessor,
+} from "./streaming-event-processor.js"
+
+// Dead letter queue
+export {
+  type DeadLetter,
+  type EnqueueDecision,
+  type EnqueuePolicy,
+  type SequencedDeadLetterQueue,
+  alwaysEnqueuePolicy,
+  createDeadLetter,
+  createInMemoryDeadLetterQueue,
+  DeadLetterQueueOverflowError,
+} from "./dead-letter-queue.js"
+
+// Dead-lettering event delivery
+export {
+  type DeadLetteringOptions,
+  createDeadLetteringDelivery,
+} from "./dead-lettering-handler.js"
+
+// Upcasting
+export {
+  type IntermediateEventRepresentation,
+  type EventUpcaster,
+  singleEventUpcaster,
+  upcasterChain,
+  upcastingSerializer,
+} from "./upcaster.js"
+
+// Serialization
+export {
+  type SchemaRegistry,
+  jsonSerializer,
+  zodValidatingSerializer,
+  createEventSchemaRegistry,
+  createCommandSchemaRegistry,
+  createQuerySchemaRegistry,
+} from "./serializer.js"
+
+// Message monitors
+export {
+  type MessageMonitor,
+  type MonitorCallback,
+  noOpMessageMonitor,
+  multiMessageMonitor,
+} from "./message-monitor.js"
+
+export {
+  type MessageMonitorRegistry,
+  createMessageMonitorRegistry,
+} from "./message-monitor-registry.js"
+
+// Tracing (core abstractions)
+export {
+  type Span,
+  type SpanFactory,
+  type SpanAttributesProvider,
+  noOpSpanFactory,
+} from "./span-factory.js"
+
+export {
+  tracingHandlerEnhancerDefinition,
+} from "./tracing-handler-enhancer.js"
+
+// Processor configuration (legacy)
+export { type ProcessorConfiguration } from "./processor-configuration.js"
+
+// Event processor builders
+export {
+  type EventProcessorModule,
+  type TrackingProcessorModule,
+  type SubscribingProcessorModule,
+  TrackingProcessorBuilder,
+  SubscribingProcessorBuilder,
+  trackingProcessor,
+  subscribingProcessor,
+} from "./event-processor-builder.js"
+
+// Namespace factory
+export { withNamespace } from "./with-namespace.js"
+

package/src/intercepting-command-bus.ts

@@ -0,0 +1,73 @@
+import type { CommandBus } from "./command-bus.js"
+import type { CommandMessage } from "./message.js"
+import type { DispatchInterceptor, HandlerInterceptor } from "./interceptor.js"
+
+/**
+ * A command bus decorator that adds dispatch and handler interceptor chains
+ * to any {@link CommandBus} implementation.
+ *
+ * {@link createSimpleCommandBus} handles dispatch + subscribe only;
+ * this decorator layers interceptor support on top.
+ */
+export function createInterceptingCommandBus(
+  delegate: CommandBus,
+): CommandBus & {
+  /** Register a dispatch interceptor. Returns an unsubscribe function. */
+  registerDispatchInterceptor(interceptor: DispatchInterceptor<CommandMessage>): () => void
+  /** Register a handler interceptor. Returns an unsubscribe function. */
+  registerHandlerInterceptor(interceptor: HandlerInterceptor): () => void
+} {
+  const dispatchInterceptors: Array<DispatchInterceptor<CommandMessage>> = []
+  const handlerInterceptors: Array<HandlerInterceptor> = []
+
+  return {
+    async dispatch(message: CommandMessage): Promise<unknown> {
+      // Run dispatch interceptors (can transform or reject)
+      let interceptedMessage = message
+      for (const interceptor of dispatchInterceptors) {
+        interceptedMessage = await interceptor(interceptedMessage)
+      }
+
+      return delegate.dispatch(interceptedMessage)
+    },
+
+    subscribe(
+      commandName: string,
+      handler: (message: CommandMessage) => Promise<unknown>,
+    ) {
+      // Wrap the handler with handler interceptors
+      const wrappedHandler = (message: CommandMessage) => {
+        if (handlerInterceptors.length === 0) {
+          return handler(message)
+        }
+
+        let chain = () => handler(message)
+        for (let i = handlerInterceptors.length - 1; i >= 0; i--) {
+          const interceptor = handlerInterceptors[i]!
+          const next = chain
+          chain = () => interceptor(message, next)
+        }
+
+        return chain()
+      }
+
+      delegate.subscribe(commandName, wrappedHandler)
+    },
+
+    registerDispatchInterceptor(interceptor) {
+      dispatchInterceptors.push(interceptor)
+      return () => {
+        const idx = dispatchInterceptors.indexOf(interceptor)
+        if (idx >= 0) dispatchInterceptors.splice(idx, 1)
+      }
+    },
+
+    registerHandlerInterceptor(interceptor) {
+      handlerInterceptors.push(interceptor)
+      return () => {
+        const idx = handlerInterceptors.indexOf(interceptor)
+        if (idx >= 0) handlerInterceptors.splice(idx, 1)
+      }
+    },
+  }
+}

package/src/intercepting-event-bus.ts

@@ -0,0 +1,29 @@
+import type { EventBus } from "./event-bus.js"
+import type { EventMessage } from "./message.js"
+import type { DispatchInterceptor } from "./interceptor.js"
+
+/**
+ * Wraps an EventBus with dispatch interceptors for event publishing.
+ */
+export function createInterceptingEventBus(
+  delegate: EventBus,
+  dispatchInterceptors: ReadonlyArray<DispatchInterceptor<EventMessage>>,
+): EventBus {
+  return {
+    async publish(events) {
+      const intercepted: EventMessage[] = []
+      for (const event of events) {
+        let msg = event
+        for (const interceptor of dispatchInterceptors) {
+          msg = await interceptor(msg) as EventMessage
+        }
+        intercepted.push(msg)
+      }
+      await delegate.publish(intercepted)
+    },
+
+    subscribe(handler) {
+      return delegate.subscribe(handler)
+    },
+  }
+}

package/src/intercepting-query-bus.ts

@@ -0,0 +1,104 @@
+import type { QueryBus } from "./query-bus.js"
+import type { QueryMessage } from "./message.js"
+import type { SubscriptionQueryResult } from "./subscription-query.js"
+import type { DispatchInterceptor, HandlerInterceptor } from "./interceptor.js"
+
+/**
+ * A query bus decorator that adds dispatch and handler interceptor chains
+ * to any {@link QueryBus} implementation.
+ *
+ * {@link createSimpleQueryBus} handles dispatch + subscribe only;
+ * this decorator layers interceptor support on top.
+ */
+export function createInterceptingQueryBus(
+  delegate: QueryBus,
+): QueryBus & {
+  /** Register a dispatch interceptor. Returns an unsubscribe function. */
+  registerDispatchInterceptor(interceptor: DispatchInterceptor<QueryMessage>): () => void
+  /** Register a handler interceptor. Returns an unsubscribe function. */
+  registerHandlerInterceptor(interceptor: HandlerInterceptor): () => void
+} {
+  const dispatchInterceptors: Array<DispatchInterceptor<QueryMessage>> = []
+  const handlerInterceptors: Array<HandlerInterceptor> = []
+
+  return {
+    async query(message: QueryMessage): Promise<unknown> {
+      let interceptedMessage = message
+      for (const interceptor of dispatchInterceptors) {
+        interceptedMessage = await interceptor(interceptedMessage)
+      }
+
+      return delegate.query(interceptedMessage)
+    },
+
+    subscribe(
+      queryName: string,
+      handler: (message: QueryMessage) => Promise<unknown>,
+    ) {
+      // Wrap the handler with handler interceptors
+      const wrappedHandler = (message: QueryMessage) => {
+        if (handlerInterceptors.length === 0) {
+          return handler(message)
+        }
+
+        let chain = () => handler(message)
+        for (let i = handlerInterceptors.length - 1; i >= 0; i--) {
+          const interceptor = handlerInterceptors[i]!
+          const next = chain
+          chain = () => interceptor(message, next)
+        }
+
+        return chain()
+      }
+
+      delegate.subscribe(queryName, wrappedHandler)
+    },
+
+    subscriptionQuery(message: QueryMessage, bufferSize?: number): SubscriptionQueryResult {
+      return delegate.subscriptionQuery(message, bufferSize)
+    },
+
+    subscribeToUpdates(message: QueryMessage, bufferSize?: number): AsyncIterable<unknown> & { close(): void } {
+      return delegate.subscribeToUpdates(message, bufferSize)
+    },
+
+    emitUpdate(
+      queryName: string,
+      filter: (queryPayload: unknown) => boolean,
+      update: unknown,
+    ): Promise<void> {
+      return delegate.emitUpdate(queryName, filter, update)
+    },
+
+    completeSubscription(
+      queryName: string,
+      filter?: (queryPayload: unknown) => boolean,
+    ): Promise<void> {
+      return delegate.completeSubscription(queryName, filter)
+    },
+
+    completeSubscriptionExceptionally(
+      queryName: string,
+      error: Error,
+      filter?: (queryPayload: unknown) => boolean,
+    ): Promise<void> {
+      return delegate.completeSubscriptionExceptionally(queryName, error, filter)
+    },
+
+    registerDispatchInterceptor(interceptor) {
+      dispatchInterceptors.push(interceptor)
+      return () => {
+        const idx = dispatchInterceptors.indexOf(interceptor)
+        if (idx >= 0) dispatchInterceptors.splice(idx, 1)
+      }
+    },
+
+    registerHandlerInterceptor(interceptor) {
+      handlerInterceptors.push(interceptor)
+      return () => {
+        const idx = handlerInterceptors.indexOf(interceptor)
+        if (idx >= 0) handlerInterceptors.splice(idx, 1)
+      }
+    },
+  }
+}

package/src/interceptor.ts

@@ -0,0 +1,48 @@
+import type { Metadata } from "@kronos-ts/common"
+import type { Message } from "./message.js"
+
+/**
+ * Intercepts a message before it reaches any handler.
+ * Can transform, enrich, or reject messages.
+ *
+ * Dispatch interceptors run in order — each receives the (possibly transformed)
+ * message from the previous interceptor.
+ *
+ * To reject a message, throw an error.
+ * To transform, return a new message.
+ * To pass through, return the message unchanged.
+ *
+ * UoW-scoped state (correlation data, tracing context, etc.) is read directly
+ * from ALS via module-level accessors (`getResource` / `setResource`) — no
+ * `ProcessingContext` parameter is threaded.
+ *
+ * **Known limitation:** Dispatch interceptors use a simple transform-or-throw
+ * approach. They do not receive a `proceed()` function that can be skipped to
+ * return an alternative result.
+ * A dispatch interceptor cannot halt the chain and return an alternative result
+ * — it can only transform the message or throw to reject it. This covers ~95%
+ * of use cases. Full chain semantics (with `proceed()`) would require the
+ * dispatch interceptor to also control the result type, which is a much larger
+ * refactor. If you need to conditionally prevent dispatch, throw a typed error
+ * and handle it at the call site.
+ */
+export interface DispatchInterceptor<M extends Message = Message> {
+  (message: M): M | Promise<M>
+}
+
+/**
+ * Intercepts a handler invocation. Wraps the actual handler call,
+ * enabling before/after logic (transactions, tracing, metrics, etc.)
+ *
+ * UoW-scoped state is read/written via module-level ALS
+ * accessors (`getResource` / `setResource`) — no `ProcessingContext`
+ * parameter is threaded.
+ *
+ * The `next` function calls the next interceptor in the chain, or the
+ * actual handler if this is the last interceptor.
+ *
+ * To skip handling entirely, don't call `next()` and return a result directly.
+ */
+export interface HandlerInterceptor<R = unknown> {
+  (message: Message, next: () => Promise<R>): Promise<R>
+}

package/src/message-monitor-registry.ts

@@ -0,0 +1,64 @@
+import type { Message, CommandMessage, EventMessage, QueryMessage } from "./message.js"
+import type { MessageMonitor } from "./message-monitor.js"
+import { multiMessageMonitor, noOpMessageMonitor } from "./message-monitor.js"
+
+/**
+ * Registry for message monitors. Collects monitors per message type
+ * and provides combined monitors for each type.
+ *
+ */
+export interface MessageMonitorRegistry {
+  /** Register a monitor for all message types. */
+  registerMonitor(monitor: MessageMonitor<Message>): void
+  /** Register a monitor for command messages. */
+  registerCommandMonitor(monitor: MessageMonitor<CommandMessage>): void
+  /** Register a monitor for event messages. */
+  registerEventMonitor(monitor: MessageMonitor<EventMessage>): void
+  /** Register a monitor for query messages. */
+  registerQueryMonitor(monitor: MessageMonitor<QueryMessage>): void
+
+  /** Get the combined monitor for command messages. */
+  commandMonitor(): MessageMonitor<CommandMessage>
+  /** Get the combined monitor for event messages. */
+  eventMonitor(): MessageMonitor<EventMessage>
+  /** Get the combined monitor for query messages. */
+  queryMonitor(): MessageMonitor<QueryMessage>
+}
+
+/**
+ * Creates a default message monitor registry.
+ */
+export function createMessageMonitorRegistry(): MessageMonitorRegistry {
+  const genericMonitors: MessageMonitor<Message>[] = []
+  const commandMonitors: MessageMonitor<CommandMessage>[] = []
+  const eventMonitors: MessageMonitor<EventMessage>[] = []
+  const queryMonitors: MessageMonitor<QueryMessage>[] = []
+
+  return {
+    registerMonitor(monitor) {
+      genericMonitors.push(monitor)
+    },
+    registerCommandMonitor(monitor) {
+      commandMonitors.push(monitor)
+    },
+    registerEventMonitor(monitor) {
+      eventMonitors.push(monitor)
+    },
+    registerQueryMonitor(monitor) {
+      queryMonitors.push(monitor)
+    },
+
+    commandMonitor() {
+      const all = [...genericMonitors, ...commandMonitors] as MessageMonitor<CommandMessage>[]
+      return all.length > 0 ? multiMessageMonitor(all) : noOpMessageMonitor()
+    },
+    eventMonitor() {
+      const all = [...genericMonitors, ...eventMonitors] as MessageMonitor<EventMessage>[]
+      return all.length > 0 ? multiMessageMonitor(all) : noOpMessageMonitor()
+    },
+    queryMonitor() {
+      const all = [...genericMonitors, ...queryMonitors] as MessageMonitor<QueryMessage>[]
+      return all.length > 0 ? multiMessageMonitor(all) : noOpMessageMonitor()
+    },
+  }
+}