@kronos-ts/messaging 0.1.0 → 0.2.0

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/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/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()
+}