@kronos-ts/messaging 0.1.0

package/src/unit-of-work.ts

@@ -0,0 +1,138 @@
+import { emptyMetadata, type Metadata } from "@kronos-ts/common"
+import {
+  processingStateStorage,
+  createInitialProcessingState,
+  Phase,
+  type PhaseValue,
+} from "./processing-state.js"
+
+/**
+ * Runner type: the canonical "enter a UnitOfWork" shape.
+ *
+ * Plan 03-04 (CTX-04 / D-34): replaces the old `UnitOfWorkFactory` shape.
+ * Extensions (kronosdb, axon-server) and transactional wrappers compose
+ * runners — `transactionalUnitOfWorkFactory` accepts a delegate runner
+ * and returns a new runner that begins/commits/rolls-back a transaction
+ * around the inner action.
+ */
+export type UoWRunner = <R>(
+  metadata: Metadata | undefined,
+  action: () => Promise<R>,
+) => Promise<R>
+
+/**
+ * Run `action` inside a NEW UnitOfWork. Always creates a fresh UoW even
+ * if one is already active on the ALS stack.
+ *
+ * Used by gateways (D-32): `commandGateway.send`, `queryGateway.query`,
+ * and any external entry point. This keeps gateway calls isolated from
+ * an injected dispatcher that reuses the active UoW.
+ */
+export function runInNewUoW<R>(
+  metadata: Metadata | undefined,
+  action: () => Promise<R>,
+): Promise<R> {
+  const resolvedMetadata = metadata ?? emptyMetadata()
+  const state = createInitialProcessingState(resolvedMetadata)
+  return processingStateStorage.run(state, () => drivePhases(state, action))
+}
+
+/**
+ * Run `action` inside a UnitOfWork. ALS-aware:
+ *
+ * - If `processingStateStorage` already has an active state (we are
+ *   nested inside a parent UoW), this REUSES the parent's state and
+ *   calls `action` directly — no new `processingStateStorage.run`, no
+ *   new phase lifecycle. This is CTX-02: nested dispatch threads through
+ *   the same UoW so transactionality spans handler-internal bus calls.
+ *
+ * - If no state is active, behaves identically to `runInNewUoW` —
+ *   creates a fresh UoW and drives the full phase lifecycle.
+ *
+ * Used by `queryBus.query` so handler-internal queries auto-nest, while
+ * a primary query (no active UoW) starts a new one.
+ *
+ * NOTE: `commandBus.dispatch` deliberately does NOT use this — for AF5
+ * parity every command gets its own fresh UnitOfWork via `runInNewUoW`,
+ * nested or not. See `createSimpleCommandBus`.
+ */
+export function runInUoW<R>(
+  metadata: Metadata | undefined,
+  action: () => Promise<R>,
+): Promise<R> {
+  if (processingStateStorage.getStore() !== undefined) return action()
+  return runInNewUoW(metadata, action)
+}
+
+// ── private: the lifecycle-driving loop ───────────────────────────────
+//
+// Plan 03-04 (D-34): the phase-driving loop previously lived inside
+// `createUnitOfWork` + `ManagedProcessingContext.executePhases`. Inlined
+// here because the ProcessingContext abstraction is gone — the runner is
+// now the only entry point.
+//
+// Re-sort semantics from the old `executePhases` (default-processing-context.ts
+// lines 168-199): handlers registered during a phase's own execution at
+// EARLIER phase values are silently dropped (the phase is already past).
+// `runPhase` drains its own bucket repeatedly so handlers registered for
+// the SAME phase during execution are picked up before moving on. After
+// a phase finishes, the outer loop re-reads `phaseActions.keys()` so any
+// new LATER phase entries are picked up in order.
+
+type State = ReturnType<typeof createInitialProcessingState>
+
+async function drivePhases<R>(state: State, action: () => Promise<R>): Promise<R> {
+  state.status = "started"
+  try {
+    await runPhase(state, Phase.PRE_INVOCATION)
+
+    state.currentPhase = Phase.INVOCATION
+    let actions = state.phaseActions.get(Phase.INVOCATION)
+    while (actions && actions.length > 0) {
+      const bucket = actions
+      state.phaseActions.set(Phase.INVOCATION, [])
+      for (const a of bucket) await a()
+      actions = state.phaseActions.get(Phase.INVOCATION)
+    }
+    const result = await action()
+
+    await runPhase(state, Phase.POST_INVOCATION)
+    await runPhase(state, Phase.PREPARE_COMMIT)
+    await runPhase(state, Phase.COMMIT)
+    await runPhase(state, Phase.AFTER_COMMIT)
+
+    state.status = "completed"
+    for (const h of state.completeHandlers) {
+      try {
+        h()
+      } catch (e) {
+        console.warn("UnitOfWork: completion handler threw an exception:", e)
+      }
+    }
+    return result
+  } catch (error) {
+    state.status = "error"
+    const failedPhase = state.currentPhase ?? undefined
+    for (const h of state.errorHandlers) {
+      try {
+        await h(error, failedPhase)
+      } catch (e) {
+        console.warn("UnitOfWork: error handler threw an exception:", e)
+      }
+    }
+    throw error
+  }
+}
+
+async function runPhase(state: State, phase: PhaseValue): Promise<void> {
+  state.currentPhase = phase
+  // Late registration: actions registered during a phase's own execution
+  // fire next loop iteration (still within the same phase).
+  let actions = state.phaseActions.get(phase)
+  while (actions && actions.length > 0) {
+    const bucket = actions
+    state.phaseActions.set(phase, [])
+    for (const a of bucket) await a()
+    actions = state.phaseActions.get(phase)
+  }
+}

package/src/upcaster.ts

@@ -0,0 +1,174 @@
+import type { Serializer, SerializedObject } from "@kronos-ts/common"
+
+/**
+ * An intermediate representation of an event during the upcasting pipeline.
+ *
+ * After deserialization from bytes (JSON.parse) but before Zod validation,
+ * the event passes through the upcaster chain as an IntermediateEventRepresentation.
+ * Each upcaster can transform the payload, type name, revision, and metadata.
+ */
+export interface IntermediateEventRepresentation {
+  /** The deserialized payload (raw JSON, not yet Zod-validated). */
+  readonly payload: unknown
+  /** The qualified type name (e.g., "university.CourseCreated"). */
+  readonly typeName: string
+  /** The schema revision (e.g., "1.0"). */
+  readonly revision: string
+  /** Event metadata. */
+  readonly metadata: Record<string, unknown>
+}
+
+/**
+ * An event upcaster transforms events from one schema version to another.
+ *
+ * Upcasters run after JSON deserialization but before Zod validation,
+ * so the payload is raw parsed JSON. The upcaster can add fields, rename
+ * fields, change the type name, bump the revision, etc.
+ *
+ * An upcaster can return:
+ * - A single representation (one-to-one transform)
+ * - An array of representations (one-to-many, e.g., splitting events)
+ * - An empty array (filtering out an event)
+ */
+export interface EventUpcaster {
+  /** Whether this upcaster can handle the given type + revision. */
+  canUpcast(typeName: string, revision: string): boolean
+
+  /**
+   * Transform the intermediate representation.
+   * Return the upcasted representation(s).
+   */
+  upcast(event: IntermediateEventRepresentation): IntermediateEventRepresentation | IntermediateEventRepresentation[]
+}
+
+/**
+ * Convenience function for the common case: a single event type
+ * being transformed from one revision to the next.
+ *
+ * ```typescript
+ * const upcaster = singleEventUpcaster({
+ *   typeName: "university.CourseCreated",
+ *   fromRevision: "1.0",
+ *   toRevision: "2.0",
+ *   upcast: (payload: any) => ({
+ *     ...payload,
+ *     capacity: payload.capacity ?? 30,  // added in v2
+ *   }),
+ * })
+ * ```
+ */
+export function singleEventUpcaster(options: {
+  typeName: string
+  fromRevision: string
+  toRevision: string
+  upcast: (payload: unknown) => unknown
+  upcastMetadata?: (metadata: Record<string, unknown>) => Record<string, unknown>
+}): EventUpcaster {
+  return {
+    canUpcast(typeName, revision) {
+      return typeName === options.typeName && revision === options.fromRevision
+    },
+
+    upcast(event) {
+      return {
+        payload: options.upcast(event.payload),
+        typeName: options.typeName,
+        revision: options.toRevision,
+        metadata: options.upcastMetadata
+          ? options.upcastMetadata(event.metadata)
+          : event.metadata,
+      }
+    },
+  }
+}
+
+/**
+ * Chains multiple upcasters into a single upcaster.
+ * Upcasters are applied in order. Each upcaster's output becomes
+ * the next upcaster's input. Handles one-to-many expansion.
+ *
+ * ```typescript
+ * const chain = upcasterChain(
+ *   courseCreatedV1ToV2,
+ *   courseCreatedV2ToV3,
+ * )
+ * ```
+ */
+export function upcasterChain(...upcasters: EventUpcaster[]): EventUpcaster {
+  return {
+    canUpcast(typeName, revision) {
+      return upcasters.some((u) => u.canUpcast(typeName, revision))
+    },
+
+    upcast(event) {
+      let representations: IntermediateEventRepresentation[] = [event]
+
+      for (const upcaster of upcasters) {
+        const next: IntermediateEventRepresentation[] = []
+        for (const rep of representations) {
+          if (upcaster.canUpcast(rep.typeName, rep.revision)) {
+            const result = upcaster.upcast(rep)
+            if (Array.isArray(result)) {
+              next.push(...result)
+            } else {
+              next.push(result)
+            }
+          } else {
+            next.push(rep)
+          }
+        }
+        representations = next
+      }
+
+      return representations.length === 1 ? representations[0]! : representations
+    },
+  }
+}
+
+/**
+ * Creates an upcasting serializer decorator.
+ *
+ * On deserialization, the raw payload is first deserialized by the delegate,
+ * then passed through the upcaster chain before being returned. The type name
+ * and revision from the SerializedObject drive upcaster selection.
+ *
+ * ```typescript
+ * const serializer = upcastingSerializer(
+ *   jsonSerializer(),
+ *   upcasterChain(v1ToV2, v2ToV3),
+ * )
+ * ```
+ */
+export function upcastingSerializer(
+  delegate: Serializer,
+  upcaster: EventUpcaster,
+): Serializer {
+  return {
+    serialize(value, type, revision) {
+      return delegate.serialize(value, type, revision)
+    },
+
+    deserialize<T>(data: SerializedObject): T {
+      const raw = delegate.deserialize<unknown>(data)
+
+      if (!upcaster.canUpcast(data.type, data.revision)) {
+        return raw as T
+      }
+
+      const representation: IntermediateEventRepresentation = {
+        payload: raw,
+        typeName: data.type,
+        revision: data.revision,
+        metadata: {},
+      }
+
+      const result = upcaster.upcast(representation)
+      const upcasted = Array.isArray(result) ? result[0]! : result
+      return upcasted.payload as T
+    },
+
+    canConvert(type) {
+      return delegate.canConvert(type)
+    },
+  }
+}

package/src/with-namespace.ts

@@ -0,0 +1,75 @@
+import { qn, type Tag } from "@kronos-ts/common"
+import {
+  command as createCommand,
+  event as createEvent,
+  query as createQuery,
+} from "./descriptor.js"
+import type { z } from "zod"
+
+/**
+ * Creates a namespace-scoped factory for message descriptors.
+ * Reduces repetition when defining many messages in the same bounded context.
+ *
+ * ```typescript
+ * const ns = withNamespace("university.courses")
+ *
+ * const CreateCourse = ns.command("CreateCourse", {
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ * })
+ *
+ * const CourseCreated = ns.event("CourseCreated", {
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ *   tags: (p) => [tag("courseId", p.courseId)],
+ * })
+ *
+ * const GetCourse = ns.query("GetCourse", {
+ *   payload: z.object({ courseId: z.string() }),
+ * })
+ * ```
+ */
+export function withNamespace(namespace: string) {
+  function command<P extends z.ZodType>(name: string, def: {
+    payload: P
+    version?: string
+    routingKey?: string
+  }): ReturnType<typeof createCommand<P>>
+  function command<P extends z.ZodType, R extends z.ZodType>(name: string, def: {
+    payload: P
+    result: R
+    version?: string
+    routingKey?: string
+  }): ReturnType<typeof createCommand<P, R>>
+  function command(name: string, def: { payload: z.ZodType }) {
+    return createCommand({ name: qn(namespace, name), ...def } as never)
+  }
+
+  function query<P extends z.ZodType>(name: string, def: {
+    payload: P
+    version?: string
+  }): ReturnType<typeof createQuery<P>>
+  function query<P extends z.ZodType, R extends z.ZodType>(name: string, def: {
+    payload: P
+    result: R
+    version?: string
+  }): ReturnType<typeof createQuery<P, R>>
+  function query(name: string, def: { payload: z.ZodType }) {
+    return createQuery({ name: qn(namespace, name), ...def } as never)
+  }
+
+  return {
+    /** Create a command descriptor in this namespace. */
+    command,
+
+    /** Create an event descriptor in this namespace. */
+    event<P extends z.ZodType>(name: string, def: {
+      payload: P
+      version?: string
+      tags?: (payload: z.infer<P>) => Tag[]
+    }) {
+      return createEvent({ name: qn(namespace, name), ...def })
+    },
+
+    /** Create a query descriptor in this namespace. */
+    query,
+  }
+}