@kronos-ts/messaging 0.1.1 → 0.3.0

package/src/interceptor.ts

@@ -1,4 +1,3 @@
-import type { Metadata } from "@kronos-ts/common"
 import type { Message } from "./message.js"
 
 /**
@@ -38,11 +37,29 @@ export interface DispatchInterceptor<M extends Message = Message> {
  * accessors (`getResource` / `setResource`) — no `ProcessingContext`
  * parameter is threaded.
  *
+ * The first argument is the full message object. Prefer keeping it as
+ * `message` when transforming or inspecting broad message details:
+ *
+ * ```
+ * app.handlerInterceptor(async (message, next) => {
+ *   const { payload, metadata, timestamp } = message
+ *   return next({
+ *     ...message,
+ *     metadata: { ...metadata, tenantId: "tenant-1" },
+ *   })
+ * })
+ * ```
+ *
  * The `next` function calls the next interceptor in the chain, or the
- * actual handler if this is the last interceptor.
+ * actual handler if this is the last interceptor. Call `next()` to proceed
+ * with the current message, or `next(replacementMessage)` to proceed with a
+ * transformed message.
  *
  * 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>
+export interface HandlerInterceptor<
+  M extends Message = Message,
+  R = unknown,
+> {
+  (message: M, next: (message?: M) => Promise<R>): Promise<R>
 }

package/src/message.ts

@@ -35,6 +35,11 @@ export interface EventMessage<P = unknown> extends Message<P> {
   readonly tags: ReadonlyArray<{ readonly key: string; readonly value: string }>
 }
 
+export interface SequencedEventMessage<P = unknown> extends EventMessage<P> {
+  /** Stream position when the source has one; absent for push-only delivery. */
+  readonly sequence?: bigint
+}
+
 /**
  * A query message — dispatched to handler(s) that can answer it.
  */

package/src/query-bus.ts

@@ -1,5 +1,6 @@
 import type { QueryMessage } from "./message.js"
 import type { SubscriptionQueryResult } from "./subscription-query.js"
+import type { SubscriptionFilter } from "./subscription-filter.js"
 
 /**
  * The query bus — low-level infrastructure for dispatching query messages.
@@ -43,10 +44,14 @@ export interface QueryBus {
    * Emit an update to all active subscription queries matching the filter.
    * When called within an active UnitOfWork (detected via ALS), the update is
    * deferred to AFTER_COMMIT.
+   *
+   * The filter can be either a function (local-only when a distributed bus is
+   * in use) or a structured `payloadEquals` predicate (crosses transports).
+   * See {@link SubscriptionFilter}.
    */
   emitUpdate(
     queryName: string,
-    filter: (queryPayload: unknown) => boolean,
+    filter: SubscriptionFilter,
     update: unknown,
   ): Promise<void>
 
@@ -55,7 +60,7 @@ export interface QueryBus {
    */
   completeSubscription(
     queryName: string,
-    filter?: (queryPayload: unknown) => boolean,
+    filter?: SubscriptionFilter,
   ): Promise<void>
 
   /**
@@ -64,6 +69,6 @@ export interface QueryBus {
   completeSubscriptionExceptionally(
     queryName: string,
     error: Error,
-    filter?: (queryPayload: unknown) => boolean,
+    filter?: SubscriptionFilter,
   ): Promise<void>
 }

package/src/query-handler.ts

@@ -1,6 +1,6 @@
 import type { z } from "zod"
-import type { Metadata } from "@kronos-ts/common"
 import type { QueryDescriptor } from "./descriptor.js"
+import type { QueryMessage } from "./message.js"
 
 // ---------------------------------------------------------------------------
 // Singular factory — mirrors commandHandler / eventHandler.
@@ -23,15 +23,15 @@ export interface QueryHandlerDefinition<
 > {
   readonly kind: "query-handler"
   readonly descriptor: QueryDescriptor<Q, z.ZodType | undefined>
-  readonly handler: (query: z.infer<Q>, metadata: Metadata) => Promise<R> | R
+  readonly handler: (message: QueryMessage<z.infer<Q>>) => Promise<R> | R
 }
 
 /**
  * Defines a singular query handler.
  *
  * ```
- * const getCourseView = queryHandler(GetCourseView, async (q, metadata) => {
- *   const view = courseViews.get(q.courseId)
+ * const getCourseView = queryHandler(GetCourseView, async ({ payload, metadata }) => {
+ *   const view = courseViews.get(payload.courseId)
  *   if (!view) throw new Error("not found")
  *   return view
  * })
@@ -43,7 +43,7 @@ export interface QueryHandlerDefinition<
  */
 export function queryHandler<Q extends z.ZodType, R>(
   descriptor: QueryDescriptor<Q, z.ZodType | undefined>,
-  handler: (query: z.infer<Q>, metadata: Metadata) => Promise<R> | R,
+  handler: (message: QueryMessage<z.infer<Q>>) => Promise<R> | R,
 ): QueryHandlerDefinition<Q, R> {
   return { kind: "query-handler", descriptor, handler }
 }

package/src/query-handling-module.ts

@@ -31,7 +31,7 @@ export function registerQueryHandlersNatively(
   for (const reg of handlers) {
     const queryName = qualifiedNameToString(reg.descriptor.name)
     let invocation = async (message: QueryMessage) =>
-      reg.handler(message.payload, message.metadata)
+      reg.handler(message)
     if (deps.handlerEnhancer) {
       invocation = deps.handlerEnhancer.wrapHandler(invocation, {
         messageType: "query",

package/src/simple-command-bus.ts

@@ -1,6 +1,6 @@
 import type { CommandBus } from "./command-bus.js"
 import type { CommandMessage } from "./message.js"
-import { runInNewUoW } from "./unit-of-work.js"
+import { runInNewUoW, type UoWRunner } from "./unit-of-work.js"
 import { qualifiedNameToString } from "@kronos-ts/common"
 
 /**
@@ -16,14 +16,20 @@ import { qualifiedNameToString } from "@kronos-ts/common"
  * by sharing a transaction. DCB read-set / append-condition merging
  * happens only WITHIN a single handler's UnitOfWork.
  *
- * Transactional wiring composes at the runner level via
- * `transactionalUnitOfWorkFactory(runInNewUoW, txManager)` and is consumed
- * by extensions / processors directly, not by the bus.
+ * The handler runs through `unitOfWorkRunner` — by default `runInNewUoW`, but
+ * the configurer injects the resolved `unitOfWorkFactory` slot (e.g. a
+ * transactional runner from a storage extension) so the per-command UoW
+ * carries whatever transaction that backend provides. This mirrors the
+ * distributed command buses (kronosdb / axon-server), which already run
+ * handlers through the configured runner. The runner is always built on
+ * `runInNewUoW`, so a command — primary OR nested via `send()` — still gets
+ * its own fresh UoW (and its own independent transaction); composition does
+ * not change AF5 isolation, only whether that fresh UoW has a transaction.
  *
  * Interceptor support is provided by wrapping with
  * {@link createInterceptingCommandBus}.
  */
-export function createSimpleCommandBus(): CommandBus {
+export function createSimpleCommandBus(unitOfWorkRunner: UoWRunner = runInNewUoW): CommandBus {
   const handlers = new Map<string, (message: CommandMessage) => Promise<unknown>>()
 
   return {
@@ -34,12 +40,12 @@ export function createSimpleCommandBus(): CommandBus {
         throw new Error(`No handler registered for command "${key}"`)
       }
 
-      // AF5 parity: every command gets its own fresh UnitOfWork, even when
-      // dispatched from inside another handler. Dispatch interceptors have
-      // already run in the caller's context (the intercepting bus wraps
-      // this one), so correlation data is carried on `message.metadata`
-      // before we cross into the new UoW.
-      return runInNewUoW(message.metadata, () => handler(message))
+      // AF5 parity: every command gets its own fresh UnitOfWork (the runner is
+      // built on runInNewUoW), even when dispatched from inside another
+      // handler. Dispatch interceptors have already run in the caller's context
+      // (the intercepting bus wraps this one), so correlation data is carried
+      // on `message.metadata` before we cross into the new UoW.
+      return unitOfWorkRunner(message.metadata, () => handler(message))
     },
 
     subscribe(

package/src/simple-query-bus.ts

@@ -2,6 +2,8 @@ import type { QueryBus } from "./query-bus.js"
 import type { QueryMessage } from "./message.js"
 import type { SubscriptionQueryResult, UpdateHandler } from "./subscription-query.js"
 import { createUpdateHandler, runAfterCommitOrImmediately } from "./subscription-query.js"
+import type { SubscriptionFilter } from "./subscription-filter.js"
+import { applySubscriptionFilter } from "./subscription-filter.js"
 import { runInUoW } from "./unit-of-work.js"
 import { qualifiedNameToString } from "@kronos-ts/common"
 
@@ -95,7 +97,7 @@ export function createSimpleQueryBus(): QueryBus {
 
     async emitUpdate(
       queryName: string,
-      filter: (queryPayload: unknown) => boolean,
+      filter: SubscriptionFilter,
       update: unknown,
     ): Promise<void> {
       runAfterCommitOrImmediately(() => {
@@ -107,7 +109,7 @@ export function createSimpleQueryBus(): QueryBus {
 
           const handlerQueryName = qualifiedNameToString(handler.query.name)
           if (handlerQueryName !== queryName) continue
-          if (!filter(handler.query.payload)) continue
+          if (!applySubscriptionFilter(filter, handler.query.payload)) continue
 
           const accepted = handler.offer(update)
           if (!accepted) {
@@ -122,13 +124,13 @@ export function createSimpleQueryBus(): QueryBus {
 
     async completeSubscription(
       queryName: string,
-      filter?: (queryPayload: unknown) => boolean,
+      filter?: SubscriptionFilter,
     ): Promise<void> {
       runAfterCommitOrImmediately(() => {
         for (const [id, handler] of subscriptions) {
           const handlerQueryName = qualifiedNameToString(handler.query.name)
           if (handlerQueryName !== queryName) continue
-          if (filter && !filter(handler.query.payload)) continue
+          if (filter && !applySubscriptionFilter(filter, handler.query.payload)) continue
 
           handler.complete()
           subscriptions.delete(id)
@@ -139,13 +141,13 @@ export function createSimpleQueryBus(): QueryBus {
     async completeSubscriptionExceptionally(
       queryName: string,
       error: Error,
-      filter?: (queryPayload: unknown) => boolean,
+      filter?: SubscriptionFilter,
     ): Promise<void> {
       runAfterCommitOrImmediately(() => {
         for (const [id, handler] of subscriptions) {
           const handlerQueryName = qualifiedNameToString(handler.query.name)
           if (handlerQueryName !== queryName) continue
-          if (filter && !filter(handler.query.payload)) continue
+          if (filter && !applySubscriptionFilter(filter, handler.query.payload)) continue
 
           handler.completeExceptionally(error)
           subscriptions.delete(id)

package/src/streaming-event-processor.ts

@@ -249,7 +249,7 @@ export function createStreamingEventProcessor(
 
     for (const reg of handlers) {
       try {
-        await reg.handler(event.payload, event.metadata)
+        await reg.handler({ ...event, sequence: sequencedEvent.sequence })
       } catch (err) {
         await errorHandler.handleError(err, eventName, sequencedEvent.sequence)
       }

package/src/subscribing-event-processor.ts

@@ -135,7 +135,7 @@ export function createSubscribingEventProcessor(
 
     for (const reg of handlers) {
       try {
-        await reg.handler(event.payload, event.metadata)
+        await reg.handler(event)
       } catch (err) {
         // SubscribingEventProcessor doesn't have position tracking,
         // so pass -1n as position indicator

package/src/subscription-filter.ts

@@ -0,0 +1,85 @@
+/**
+ * A predicate over a query payload, used by `emitUpdate` to decide which
+ * subscribers should receive an update.
+ *
+ * Two forms are supported:
+ *
+ * 1. **Function** — `(payload) => boolean`. Easy to write but cannot cross a
+ *    network boundary because functions are not serializable. Use for
+ *    in-process / single-segment query buses.
+ *
+ * 2. **Structured `payloadEquals`** — `{ payloadEquals: Partial<P> }`. Every
+ *    key in the partial must deep-equal the same key in the subscriber's
+ *    query payload. Serializable, so it ships across distributed query bus
+ *    transports (e.g. RabbitMQ broadcasts).
+ *
+ * Both forms work locally; only the structured form crosses processes when a
+ * distributed query bus is in use.
+ */
+export type SubscriptionFilter<P = unknown> =
+  | ((payload: P) => boolean)
+  | { readonly payloadEquals: Partial<P> }
+
+/**
+ * Helper that builds a structured filter from a partial payload.
+ *
+ * ```ts
+ * emitUpdate(GetCourseView, payloadEquals({ courseId: e.courseId }), view)
+ * ```
+ *
+ * Prefer this over a function filter when you want updates to fan out across
+ * a distributed query bus.
+ */
+export function payloadEquals<P>(partial: Partial<P>): { payloadEquals: Partial<P> } {
+  return { payloadEquals: partial }
+}
+
+/** Evaluate a {@link SubscriptionFilter} against a payload. */
+export function applySubscriptionFilter<P>(filter: SubscriptionFilter<P>, payload: P): boolean {
+  if (typeof filter === "function") return filter(payload)
+  return matchesPayloadEquals(payload, filter.payloadEquals)
+}
+
+/** Extract the structured form, if any, for serialization across a transport. */
+export function extractStructuredFilter<P>(
+  filter: SubscriptionFilter<P> | undefined,
+): { payloadEquals: Partial<P> } | undefined {
+  if (!filter) return undefined
+  if (typeof filter === "function") return undefined
+  return filter
+}
+
+/** Deep equality on the keys defined in `expected`. */
+export function matchesPayloadEquals<P>(payload: P, expected: Partial<P>): boolean {
+  if (payload === null || typeof payload !== "object") {
+    return Object.keys(expected).length === 0
+  }
+  for (const key of Object.keys(expected) as Array<keyof P>) {
+    if (!deepEqual((payload as P)[key], expected[key])) return false
+  }
+  return true
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (a === null || b === null) return false
+  if (typeof a !== typeof b) return false
+  if (typeof a !== "object") return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false
+    }
+    return true
+  }
+  const ao = a as Record<string, unknown>
+  const bo = b as Record<string, unknown>
+  const aKeys = Object.keys(ao)
+  const bKeys = Object.keys(bo)
+  if (aKeys.length !== bKeys.length) return false
+  for (const key of aKeys) {
+    if (!deepEqual(ao[key], bo[key])) return false
+  }
+  return true
+}

package/src/tracking-event-processor.ts

@@ -268,7 +268,7 @@ export function createTrackingEventProcessor(
 
     for (const reg of handlers) {
       try {
-        await reg.handler(event.payload, event.metadata)
+        await reg.handler({ ...event, sequence: sequencedEvent.sequence })
       } catch (err) {
         await errorHandler.handleError(err, eventName, sequencedEvent.sequence)
       }

package/src/transaction.ts

@@ -8,6 +8,18 @@ import {
 } from "./processing-state.js"
 import type { UoWRunner } from "./unit-of-work.js"
 
+/**
+ * Resource key holding a deferred-begin factory installed by
+ * {@link lazyTransactionalUnitOfWorkFactory}. The factory begins the tx on
+ * first call, registers commit/rollback hooks on the UoW, caches the
+ * resulting tx in {@link TRANSACTION_KEY}, and returns it. Subsequent calls
+ * return the cached tx without a re-begin.
+ *
+ * NOT exported from the package barrel — components reach the lazily-begun
+ * tx through {@link getOrBeginActiveTransaction}.
+ */
+const LAZY_TX_FACTORY_KEY: ResourceKey<() => Promise<unknown>> = resourceKey("lazyTxFactory")
+
 /**
  * Manages transaction lifecycle. Users provide an implementation
  * for their specific database/ORM.
@@ -96,3 +108,75 @@ export function transactionalUnitOfWorkFactory<T>(
     })
   }
 }
+
+/**
+ * Lazy variant of {@link transactionalUnitOfWorkFactory}.
+ *
+ * Unlike the eager factory, no transaction is begun on UoW entry. Instead,
+ * a factory is installed in the UoW that opens the tx on the first call to
+ * {@link getOrBeginActiveTransaction}. Pure-read UoWs that never request a
+ * tx pay zero begin/commit cost and never claim a connection from the pool.
+ *
+ * On first request: the tx is begun, stored in {@link TRANSACTION_KEY},
+ * and commit/rollback hooks are registered. Subsequent requests within
+ * the same UoW return the cached tx — there is exactly one tx per UoW.
+ *
+ * Components that may write to the underlying store (event stores,
+ * schedulers, ORM integrations) reach the tx via
+ * {@link getOrBeginActiveTransaction}; read-only paths use
+ * {@link getActiveTransaction} so they observe an existing tx but do not
+ * provoke one to open.
+ */
+export function lazyTransactionalUnitOfWorkFactory<T>(
+  delegate: UoWRunner,
+  txManager: TransactionManager<T>,
+): UoWRunner {
+  return async (metadata, action) => {
+    return delegate(metadata, async () => {
+      let tx: T | undefined
+      let committed = false
+
+      const factory = async (): Promise<T> => {
+        if (tx !== undefined) return tx
+        tx = await txManager.begin()
+        setResource(TRANSACTION_KEY, tx)
+        on(Phase.COMMIT, async () => {
+          if (tx === undefined) return
+          await txManager.commit(tx)
+          committed = true
+        })
+        onError(async () => {
+          if (tx === undefined || committed) return
+          await txManager.rollback(tx)
+        })
+        return tx
+      }
+
+      setResource(LAZY_TX_FACTORY_KEY, factory as () => Promise<unknown>)
+      return action()
+    })
+  }
+}
+
+/**
+ * Return the active UoW transaction, opening it if a lazy factory is
+ * installed and no tx has been begun yet. Returns the cached tx on
+ * subsequent calls within the same UoW.
+ *
+ * Returns `undefined` when no UoW is active OR when an active UoW has
+ * neither an existing tx nor a lazy factory installed (e.g., the app
+ * doesn't compose a TransactionManager). Callers that need a tx must
+ * decide what to do with `undefined` — typically fall back to opening
+ * an ad-hoc tx on their own driver.
+ */
+export async function getOrBeginActiveTransaction<T = unknown>(): Promise<T | undefined> {
+  const state = processingStateStorage.getStore()
+  if (!state) return undefined
+  const existing = state.resources.get(TRANSACTION_KEY.symbol) as T | undefined
+  if (existing !== undefined) return existing
+  const factory = state.resources.get(LAZY_TX_FACTORY_KEY.symbol) as
+    | (() => Promise<T>)
+    | undefined
+  if (factory === undefined) return undefined
+  return await factory()
+}