@kronos-ts/messaging 0.1.1 → 0.3.0

package/src/command-handling-module.ts

@@ -122,7 +122,7 @@ export function createCommandInvocation(
           )
 
           const finalCriteria = handler.appendCondition
-            ? handler.appendCondition(message.payload, combinedCriteria)
+            ? handler.appendCondition(message, combinedCriteria)
             : combinedCriteria
 
           appendCondition = {
@@ -135,7 +135,7 @@ export function createCommandInvocation(
       })
     }
 
-    return handler.handler(message.payload, message.metadata)
+    return handler.handler(message)
   }
 }
 

package/src/dead-lettering-handler.ts

@@ -74,7 +74,7 @@ export function createDeadLetteringDelivery(options: DeadLetteringOptions) {
       // Try to deliver to all handlers
       for (const reg of handlers) {
         try {
-          await reg.handler(event.payload, event.metadata)
+          await reg.handler({ ...event, sequence: sequencedEvent.sequence })
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err))
           const letter = createDeadLetter(event, error, seqId, {

package/src/emit-update.ts

@@ -3,12 +3,13 @@ import { resourceKey, qualifiedNameToString, type ResourceKey } from "@kronos-ts
 import { requireInvocationPhase } from "./processing-state.js"
 import type { QueryBus } from "./query-bus.js"
 import type { QueryDescriptor } from "./descriptor.js"
+import type { SubscriptionFilter } from "./subscription-filter.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,
+    filter: SubscriptionFilter<z.infer<Q>>,
     update: unknown,
   ): void
 }
@@ -31,5 +32,5 @@ export const emitUpdate: EmitUpdateFunction = (queryDescriptor, filter, update)
   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)
+  bus.emitUpdate(queryName, filter as SubscriptionFilter, update)
 }

package/src/event-handler.ts

@@ -1,6 +1,6 @@
 import type { z } from "zod"
-import type { Metadata } from "@kronos-ts/common"
 import type { EventDescriptor } from "./descriptor.js"
+import type { SequencedEventMessage } from "./message.js"
 
 // ---------------------------------------------------------------------------
 // Singular factory — mirrors commandHandler / queryHandler.
@@ -16,18 +16,15 @@ import type { EventDescriptor } from "./descriptor.js"
 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
+  readonly handler: (message: SequencedEventMessage<z.infer<P>>) => 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 })
+ * const onCourseCreated = eventHandler(CourseCreated, async ({ payload, metadata, timestamp }) => {
+ *   await db.courses.insert({ id: payload.courseId, name: payload.name, createdAt: timestamp })
  * })
  * ```
  *
@@ -38,7 +35,7 @@ export interface EventHandlerDefinition<P extends z.ZodType = z.ZodType> {
  */
 export function eventHandler<P extends z.ZodType>(
   descriptor: EventDescriptor<P>,
-  handler: (event: z.infer<P>, metadata: Metadata) => Promise<void> | void,
+  handler: (message: SequencedEventMessage<z.infer<P>>) => Promise<void> | void,
 ): EventHandlerDefinition<P> {
   return { kind: "event-handler", descriptor, handler }
 }

package/src/event-processor-builder.ts

@@ -60,8 +60,8 @@ export type EventProcessorModule = TrackingProcessorModule | SubscribingProcesso
  * position via a token store, and support replay/reset.
  *
  * ```typescript
- * const onCreated = eventHandler(CourseCreated, async (e) => { ... })
- * const onCapChanged = eventHandler(CourseCapacityChanged, async (e) => { ... })
+ * const onCreated = eventHandler(CourseCreated, async ({ payload: e }) => { ... })
+ * const onCapChanged = eventHandler(CourseCapacityChanged, async ({ payload: e }) => { ... })
  *
  * trackingProcessor("course-projection")
  *   .eventHandlers(onCreated, onCapChanged)
@@ -186,7 +186,7 @@ export class TrackingProcessorBuilder {
  * as they are appended. No token store, no position tracking, no replay.
  *
  * ```typescript
- * const onNotification = eventHandler(NotificationRaised, async (e) => { ... })
+ * const onNotification = eventHandler(NotificationRaised, async ({ payload: e }) => { ... })
  *
  * subscribingProcessor("notifications")
  *   .eventHandlers(onNotification)

package/src/event-scheduler.ts

@@ -0,0 +1,96 @@
+/**
+ * EventScheduler — schedule an event to be appended to the event store at
+ * a future time, with the option to cancel before the fire-time.
+ *
+ * # Semantics
+ *
+ * - `schedule(event, at)` MUST be called from inside a UnitOfWork (i.e.,
+ *   from a command/event/query handler, or any code that opened a UoW
+ *   via `runInNewUoW`). The scheduled record participates in the active
+ *   UoW transaction: if the UoW rolls back, the schedule is not persisted;
+ *   if the UoW commits, the schedule is durably stored.
+ *
+ * - Once the schedule is committed, the implementation guarantees that the
+ *   event WILL be appended to the event store at or after `at`, unless
+ *   {@link EventScheduler.cancel} is called and succeeds before the
+ *   fire-time. "At or after" because workers poll on an interval — fire
+ *   times are not real-time deadlines.
+ *
+ * - `cancel(token)` returns a {@link CancelResult} discriminated union so
+ *   callers can branch on three distinct outcomes: the schedule was
+ *   cancelled before firing, the event had already been appended (too
+ *   late), or no such schedule exists (already-cancelled, never-existed,
+ *   or token from a different deployment).
+ *
+ * - Cancel is also UoW-aware: when called inside a UoW, it participates
+ *   in the active tx so a handler that cancels and then throws does NOT
+ *   leave the schedule cancelled. When called outside any UoW (rare —
+ *   typically an ops/admin path), it commits standalone.
+ *
+ * # Calling from handlers
+ *
+ * Implementations resolve themselves from the active UoW's resources
+ * (similar to {@link send} and {@link emitUpdate}), so handler code uses
+ * the scheduler the framework configured for it. The interface itself
+ * is transport-agnostic — postgres and in-memory implementations live
+ * in their respective packages.
+ *
+ * # NOT what this is
+ *
+ * - This is NOT a command scheduler. AF5 schedules events, not commands;
+ *   if you want a command to run later, schedule an event and run an
+ *   automation processor that turns the event into a command on receipt.
+ * - This is NOT a cron / recurring scheduler. Each `schedule()` produces
+ *   a single one-shot fire.
+ */
+
+import type { EventMessage } from "./message.js"
+
+/**
+ * Opaque handle returned by {@link EventScheduler.schedule}. Pass back to
+ * {@link EventScheduler.cancel} to attempt cancellation. Tokens are
+ * implementation-specific (postgres uses the row PK; in-memory uses a
+ * UUID) but always carry a stable `id`.
+ */
+export interface ScheduleToken {
+  readonly id: string
+}
+
+/**
+ * Outcome of {@link EventScheduler.cancel}.
+ *
+ * - `cancelled`        — the schedule existed in `pending` state and was
+ *                        successfully marked `cancelled`. Event will NOT
+ *                        be appended.
+ * - `already-appended` — a worker already fired this schedule; the event
+ *                        is in the event store. Caller decides whether
+ *                        compensation is needed.
+ * - `not-found`        — no row matches the token. Could mean: already
+ *                        cancelled, never existed, or wrong store. Caller
+ *                        usually treats this as a no-op.
+ */
+export type CancelResult =
+  | { readonly kind: "cancelled" }
+  | { readonly kind: "already-appended" }
+  | { readonly kind: "not-found" }
+
+export interface EventScheduler {
+  /**
+   * Schedule {@link event} for append at {@link at}. Must be called inside
+   * a UoW; throws otherwise. The schedule participates in the active UoW
+   * tx and is only durable once the UoW commits.
+   *
+   * `at` is the wall-clock fire-time. Past dates are valid — they cause
+   * the worker to fire the schedule on its next poll.
+   */
+  schedule(event: EventMessage, at: Date): Promise<ScheduleToken>
+
+  /**
+   * Attempt to cancel a pending schedule. See {@link CancelResult} for
+   * the three possible outcomes.
+   *
+   * Safe to call from inside a UoW (joins the active tx) or outside
+   * (commits standalone).
+   */
+  cancel(token: ScheduleToken): Promise<CancelResult>
+}

package/src/gateway.ts

@@ -74,32 +74,24 @@ export interface QueryGateway {
 /**
  * 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.
+ * AF5-aligned (CLAUDE.md command model): the gateway is a thin message-builder
+ * and does NOT establish a UnitOfWork. The command bus owns the single
+ * per-command UoW (and, via the configured `unitOfWorkFactory`, its
+ * transaction) — see `createSimpleCommandBus`. Dispatch interceptors run on
+ * the message before it crosses into that UoW; the dispatch-side hook channel
+ * is ALS, not a threaded ProcessingContext.
  */
-export function createCommandGateway(
-  bus: CommandBus,
-  unitOfWorkRunner: UoWRunner = runInNewUoW,
-): CommandGateway {
+export function createCommandGateway(bus: CommandBus): 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
+      return bus.dispatch({
+        identifier: generateIdentifier(),
+        name: descriptor.name,
+        payload,
+        metadata: resolvedMetadata,
+        timestamp: Date.now(),
+      }) as any
     },
   }
 }

package/src/handler.ts

@@ -1,10 +1,10 @@
 import type { z } from "zod"
-import type { Metadata } from "@kronos-ts/common"
 import type {
   CommandDescriptor,
   EventDescriptor,
   QueryDescriptor,
 } from "./descriptor.js"
+import type { EventMessage, QueryMessage, SequencedEventMessage } from "./message.js"
 
 // ---------------------------------------------------------------------------
 // Handler context shapes — DELETED (Plan 04-02, D-41)
@@ -22,10 +22,7 @@ import type {
 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
+  readonly handler: (message: SequencedEventMessage<z.infer<P>>) => Promise<void> | void
 }
 
 /**
@@ -40,7 +37,7 @@ export interface EvolverRegistration<
 > {
   readonly kind: "evolver"
   readonly descriptor: EventDescriptor<P>
-  readonly evolve: (state: S, event: z.infer<P>, id: unknown) => S | Promise<S>
+  readonly evolve: (state: S, message: EventMessage<z.infer<P>>) => S | Promise<S>
 }
 
 /** A paired query descriptor + handler function, with result type on the handler. */
@@ -50,10 +47,7 @@ export interface QueryHandlerRegistration<
 > {
   readonly kind: "query-handler"
   readonly descriptor: QueryDescriptor<Q>
-  readonly handler: (
-    query: z.infer<Q>,
-    metadata: Metadata,
-  ) => Promise<R> | R
+  readonly handler: (message: QueryMessage<z.infer<Q>>) => Promise<R> | R
 }
 
 // ---------------------------------------------------------------------------
@@ -65,13 +59,13 @@ export interface QueryHandlerRegistration<
  * 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 }))`
+ * - Event handlers:  `on(CourseCreated, async ({ payload, metadata }) => { ... })`
+ * - Query handlers:  `on(GetCourse, async ({ payload, metadata }) => { return { ... } })`
+ * - Evolvers:        `on(CourseCreated, (state, { payload }) => ({ ...state, name: payload.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)`.
+ * the callback declares. Event and query handlers receive the full typed message.
+ * Evolvers receive the current state plus the full typed event message.
  *
  * In practice the distinction is enforced by the array type:
  * - `evolve: [on(...)]` expects `EvolverRegistration`
@@ -81,22 +75,19 @@ export interface QueryHandlerRegistration<
 // 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>,
+  evolve: (state: S, message: EventMessage<z.infer<P>>) => 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,
+  handler: (message: SequencedEventMessage<z.infer<P>>) => 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,
+  handler: (message: QueryMessage<z.infer<Q>>) => Promise<R> | R,
 ): QueryHandlerRegistration<Q, R>
 
 export function on(
@@ -127,7 +118,7 @@ export function on(
  */
 export function onEvent<S, P extends z.ZodType>(
   descriptor: EventDescriptor<P>,
-  evolve: (state: S, event: z.infer<P>, id: unknown) => S | Promise<S>,
+  evolve: (state: S, message: EventMessage<z.infer<P>>) => S | Promise<S>,
 ): EvolverRegistration<S, P> {
   return { kind: "evolver", descriptor, evolve }
 }

package/src/in-memory-event-scheduler.ts

@@ -0,0 +1,150 @@
+/**
+ * In-memory {@link EventScheduler} — intended for tests only.
+ *
+ * Backed by a `Map<scheduleId, record>` and `setTimeout`. Publishes fired
+ * events through a supplied {@link EventSink} (typically the in-memory
+ * event bus or a test spy).
+ *
+ * # UoW semantics (best-effort, test-grade)
+ *
+ * - `schedule()` must be called inside a UoW (INVOCATION phase). The
+ *   record is staged immediately so cancel() inside the SAME UoW sees it,
+ *   but the `setTimeout` arming is deferred to AFTER_COMMIT — so if the
+ *   UoW rolls back the schedule never fires. `onError` cleans the staged
+ *   record so callers see `not-found` on the rolled-back token.
+ *
+ * - `cancel()` may be called inside or outside a UoW. State change is
+ *   applied immediately for caller-visibility; this means a UoW that
+ *   cancels and then rolls back does NOT restore the schedule. This
+ *   differs from the postgres implementation (which is true
+ *   transactional) and is acceptable for the in-memory's test-only
+ *   remit. Document this when writing tests that depend on cancel
+ *   rollback semantics — use the postgres scheduler for that.
+ *
+ * # NOT production
+ *
+ * No persistence, no recovery on restart, no at-least-once. A test-only
+ * spy with a real-enough surface to exercise framework wiring.
+ */
+
+import type { EventMessage } from "./message.js"
+import type { EventSink } from "./event-sink.js"
+import type { EventScheduler, ScheduleToken, CancelResult } from "./event-scheduler.js"
+import {
+  requireInvocationPhase,
+  onAfterCommit,
+  onError,
+  processingStateStorage,
+} from "./processing-state.js"
+import { generateIdentifier } from "@kronos-ts/common"
+
+type RecordStatus = "pending" | "appended" | "cancelled"
+
+interface ScheduleRecord {
+  status: RecordStatus
+  event: EventMessage
+  fireAt: number
+  timer?: ReturnType<typeof setTimeout>
+}
+
+export interface InMemoryEventSchedulerOptions {
+  readonly eventSink: EventSink
+  /** Override `Date.now` for deterministic tests. Defaults to `Date.now`. */
+  readonly now?: () => number
+}
+
+export interface InMemoryEventScheduler extends EventScheduler {
+  /**
+   * Cancel any armed timers and drop all internal state. Tests call this
+   * in `afterEach` to ensure schedulers from one test do not fire into
+   * another. Not part of the public {@link EventScheduler} contract.
+   */
+  stop(): Promise<void>
+}
+
+export function createInMemoryEventScheduler(
+  options: InMemoryEventSchedulerOptions,
+): InMemoryEventScheduler {
+  const { eventSink } = options
+  const now = options.now ?? Date.now
+  const records = new Map<string, ScheduleRecord>()
+
+  function armTimer(id: string, record: ScheduleRecord): void {
+    const delay = Math.max(0, record.fireAt - now())
+    record.timer = setTimeout(() => {
+      const rec = records.get(id)
+      if (!rec || rec.status !== "pending") return
+      rec.status = "appended"
+      rec.timer = undefined
+      eventSink.publish([rec.event]).catch((err) => {
+        // Test-only: surface but do not crash the process. Real
+        // implementations need an at-least-once retry; not modelled here.
+        console.warn("inMemoryEventScheduler: publish failed:", err)
+      })
+    }, delay)
+  }
+
+  return {
+    async schedule(event: EventMessage, at: Date): Promise<ScheduleToken> {
+      requireInvocationPhase()
+
+      const id = generateIdentifier()
+      const record: ScheduleRecord = {
+        status: "pending",
+        event,
+        fireAt: at.getTime(),
+      }
+      records.set(id, record)
+
+      onAfterCommit(() => {
+        const rec = records.get(id)
+        if (!rec || rec.status !== "pending") return
+        armTimer(id, rec)
+      })
+
+      onError(() => {
+        // Roll back the staged record so post-rollback cancel() sees
+        // `not-found` rather than `cancelled`.
+        const rec = records.get(id)
+        if (rec && rec.status === "pending") records.delete(id)
+      })
+
+      return { id }
+    },
+
+    async cancel(token: ScheduleToken): Promise<CancelResult> {
+      const rec = records.get(token.id)
+      if (!rec) return { kind: "not-found" }
+      if (rec.status === "appended") return { kind: "already-appended" }
+      if (rec.status === "cancelled") return { kind: "not-found" }
+
+      rec.status = "cancelled"
+      if (rec.timer !== undefined) {
+        clearTimeout(rec.timer)
+        rec.timer = undefined
+      }
+
+      // Best-effort UoW participation: if we're inside a UoW that later
+      // errors, revert the cancel so the schedule's pending state
+      // re-materialises. The original timer (if it was armed) has already
+      // been cleared — the AFTER_COMMIT re-arm cycle is not re-driven
+      // here, which means a cancel + rollback inside a post-commit window
+      // would not re-fire. Acceptable for the in-memory's test-only remit.
+      if (processingStateStorage.getStore() !== undefined) {
+        onError(() => {
+          const r = records.get(token.id)
+          if (r && r.status === "cancelled") r.status = "pending"
+        })
+      }
+
+      return { kind: "cancelled" }
+    },
+
+    async stop(): Promise<void> {
+      for (const rec of records.values()) {
+        if (rec.timer !== undefined) clearTimeout(rec.timer)
+      }
+      records.clear()
+    },
+  }
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export {
   type CommandMessage,
   type CommandResultMessage,
   type EventMessage,
+  type SequencedEventMessage,
   type QueryMessage,
 } from "./message.js"
 
@@ -145,6 +146,14 @@ export {
   runAfterCommitOrImmediately,
 } from "./subscription-query.js"
 
+export {
+  type SubscriptionFilter,
+  payloadEquals,
+  applySubscriptionFilter,
+  extractStructuredFilter,
+  matchesPayloadEquals,
+} from "./subscription-filter.js"
+
 // Event sink (publish-only)
 export { type EventSink } from "./event-sink.js"
 
@@ -237,7 +246,9 @@ export {
   type TransactionManager,
   noTransactionManager,
   getActiveTransaction,
+  getOrBeginActiveTransaction,
   transactionalUnitOfWorkFactory,
+  lazyTransactionalUnitOfWorkFactory,
   TRANSACTION_KEY,
 } from "./transaction.js"
 
@@ -252,6 +263,18 @@ export {
 export { send, COMMAND_BUS_KEY } from "./send.js"
 export { emitUpdate, QUERY_BUS_KEY } from "./emit-update.js"
 
+// Event scheduling
+export {
+  type EventScheduler,
+  type ScheduleToken,
+  type CancelResult,
+} from "./event-scheduler.js"
+export {
+  type InMemoryEventScheduler,
+  type InMemoryEventSchedulerOptions,
+  createInMemoryEventScheduler,
+} from "./in-memory-event-scheduler.js"
+
 // Modules — Plan 08-03a (D-82): function-style helpers replace Module-shape factories
 export {
   registerCommandHandlersNatively,
@@ -353,4 +376,3 @@ export {
 
 // Namespace factory
 export { withNamespace } from "./with-namespace.js"
-

package/src/intercepting-command-bus.ts

@@ -15,10 +15,10 @@ export function createInterceptingCommandBus(
   /** 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
+  registerHandlerInterceptor(interceptor: HandlerInterceptor<CommandMessage>): () => void
 } {
   const dispatchInterceptors: Array<DispatchInterceptor<CommandMessage>> = []
-  const handlerInterceptors: Array<HandlerInterceptor> = []
+  const handlerInterceptors: Array<HandlerInterceptor<CommandMessage>> = []
 
   return {
     async dispatch(message: CommandMessage): Promise<unknown> {
@@ -35,20 +35,21 @@ export function createInterceptingCommandBus(
       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)
+        let chain = (currentMessage: CommandMessage) => handler(currentMessage)
         for (let i = handlerInterceptors.length - 1; i >= 0; i--) {
           const interceptor = handlerInterceptors[i]!
           const next = chain
-          chain = () => interceptor(message, next)
+          chain = (currentMessage: CommandMessage) =>
+            interceptor(currentMessage, (replacementMessage) =>
+              next(replacementMessage ?? currentMessage))
         }
 
-        return chain()
+        return chain(message)
       }
 
       delegate.subscribe(commandName, wrappedHandler)

package/src/intercepting-query-bus.ts

@@ -1,6 +1,7 @@
 import type { QueryBus } from "./query-bus.js"
 import type { QueryMessage } from "./message.js"
 import type { SubscriptionQueryResult } from "./subscription-query.js"
+import type { SubscriptionFilter } from "./subscription-filter.js"
 import type { DispatchInterceptor, HandlerInterceptor } from "./interceptor.js"
 
 /**
@@ -16,10 +17,10 @@ export function createInterceptingQueryBus(
   /** 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
+  registerHandlerInterceptor(interceptor: HandlerInterceptor<QueryMessage>): () => void
 } {
   const dispatchInterceptors: Array<DispatchInterceptor<QueryMessage>> = []
-  const handlerInterceptors: Array<HandlerInterceptor> = []
+  const handlerInterceptors: Array<HandlerInterceptor<QueryMessage>> = []
 
   return {
     async query(message: QueryMessage): Promise<unknown> {
@@ -35,20 +36,21 @@ export function createInterceptingQueryBus(
       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)
+        let chain = (currentMessage: QueryMessage) => handler(currentMessage)
         for (let i = handlerInterceptors.length - 1; i >= 0; i--) {
           const interceptor = handlerInterceptors[i]!
           const next = chain
-          chain = () => interceptor(message, next)
+          chain = (currentMessage: QueryMessage) =>
+            interceptor(currentMessage, (replacementMessage) =>
+              next(replacementMessage ?? currentMessage))
         }
 
-        return chain()
+        return chain(message)
       }
 
       delegate.subscribe(queryName, wrappedHandler)
@@ -64,7 +66,7 @@ export function createInterceptingQueryBus(
 
     emitUpdate(
       queryName: string,
-      filter: (queryPayload: unknown) => boolean,
+      filter: SubscriptionFilter,
       update: unknown,
     ): Promise<void> {
       return delegate.emitUpdate(queryName, filter, update)
@@ -72,7 +74,7 @@ export function createInterceptingQueryBus(
 
     completeSubscription(
       queryName: string,
-      filter?: (queryPayload: unknown) => boolean,
+      filter?: SubscriptionFilter,
     ): Promise<void> {
       return delegate.completeSubscription(queryName, filter)
     },
@@ -80,7 +82,7 @@ export function createInterceptingQueryBus(
     completeSubscriptionExceptionally(
       queryName: string,
       error: Error,
-      filter?: (queryPayload: unknown) => boolean,
+      filter?: SubscriptionFilter,
     ): Promise<void> {
       return delegate.completeSubscriptionExceptionally(queryName, error, filter)
     },