@kronos-ts/messaging 0.1.0

package/dist/emit-update.js

@@ -0,0 +1,23 @@
+import { resourceKey, qualifiedNameToString } from "@kronos-ts/common";
+import { requireInvocationPhase } from "./processing-state.js";
+/**
+ * Resource key for the query bus component.
+ * Written by handling modules + processors at handler-invocation entry (D-44).
+ */
+export const QUERY_BUS_KEY = resourceKey("queryBus");
+/**
+ * Plan 04-01 (HDL-02 / D-42): module-level emitUpdate.
+ *
+ * Throws NoActiveUnitOfWork outside a UoW; throws WrongUoWPhase outside
+ * INVOCATION phase (D-43 mutator guard). Emits a subscription query update
+ * through the active query bus.
+ */
+export const emitUpdate = (queryDescriptor, filter, update) => {
+    const state = requireInvocationPhase(); // D-43 mutator guard
+    const bus = state.resources.get(QUERY_BUS_KEY.symbol);
+    if (!bus)
+        throw new Error("No query bus configured");
+    const queryName = qualifiedNameToString(queryDescriptor.name);
+    bus.emitUpdate(queryName, filter, update);
+};
+//# sourceMappingURL=emit-update.js.map

package/dist/emit-update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-update.js","sourceRoot":"","sources":["../src/emit-update.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAoB,MAAM,mBAAmB,CAAA;AACxF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAa9D;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAA0B,WAAW,CAAC,UAAU,CAAC,CAAA;AAE3E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAuB,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;IAChF,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAA,CAAC,qBAAqB;IAC5D,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAyB,CAAA;IAC7E,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAA;IACpD,MAAM,SAAS,GAAG,qBAAqB,CAAC,eAAe,CAAC,IAAI,CAAC,CAAA;IAC7D,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,MAAiC,EAAE,MAAM,CAAC,CAAA;AACtE,CAAC,CAAA"}

package/dist/event-bus.d.ts

@@ -0,0 +1,29 @@
+import type { EventMessage } from "./message.js";
+import type { EventSink } from "./event-sink.js";
+/**
+ * Subscribable source of events — push-based delivery.
+ */
+export interface SubscribableEventSource {
+    /**
+     * Subscribe to events as they are published.
+     * Returns an unsubscribe function.
+     *
+     * @param handler Called with each batch of events as they are appended.
+     */
+    subscribe(handler: (events: ReadonlyArray<EventMessage>) => Promise<void>): () => void;
+}
+/**
+ * The event bus — combines event publication (EventSink) with
+ * push-based subscription (SubscribableEventSource).
+ *
+ * In event sourcing setups, the EventStore serves as the EventBus.
+ * In non-event-sourcing setups, SimpleEventBus provides in-memory distribution.
+ */
+export interface EventBus extends SubscribableEventSource, EventSink {
+}
+/**
+ * In-memory event bus for non-event-sourcing scenarios.
+ * Publishes events directly to all subscribers.
+ */
+export declare function createSimpleEventBus(): EventBus;
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAA;CACvF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAS,SAAQ,uBAAuB,EAAE,SAAS;CAAG;AAEvE;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,QAAQ,CAe/C"}

package/dist/event-bus.js

@@ -0,0 +1,22 @@
+/**
+ * In-memory event bus for non-event-sourcing scenarios.
+ * Publishes events directly to all subscribers.
+ */
+export function createSimpleEventBus() {
+    const subscribers = new Set();
+    return {
+        async publish(events) {
+            for (const subscriber of subscribers) {
+                try {
+                    await subscriber(events);
+                }
+                catch { /* ignore subscriber errors */ }
+            }
+        },
+        subscribe(handler) {
+            subscribers.add(handler);
+            return () => { subscribers.delete(handler); };
+        },
+    };
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,WAAW,GAAG,IAAI,GAAG,EAA0D,CAAA;IAErF,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,MAAM;YAClB,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;gBACrC,IAAI,CAAC;oBAAC,MAAM,UAAU,CAAC,MAAM,CAAC,CAAA;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,8BAA8B,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;QAED,SAAS,CAAC,OAAO;YACf,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YACxB,OAAO,GAAG,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA,CAAC,CAAC,CAAA;QAC9C,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/event-criteria.d.ts

@@ -0,0 +1,87 @@
+import type { Tag, QualifiedName } from "@kronos-ts/common";
+import type { EventDescriptor } from "./descriptor.js";
+/**
+ * Criteria for selecting events from the event store.
+ * Used for both sourcing conditions (which events to load) and
+ * append conditions (which events define the consistency boundary).
+ *
+ * Criteria are composable via `or()` and restrictable via `ofTypes()`.
+ */
+export type EventCriteria = TagCriteria | TypeRestrictedCriteria | EitherCriteria | AnyTagCriteria;
+export interface TagCriteria {
+    readonly kind: "tags";
+    readonly tags: ReadonlyArray<Tag>;
+}
+export interface TypeRestrictedCriteria {
+    readonly kind: "type-restricted";
+    readonly inner: TagCriteria | AnyTagCriteria;
+    readonly types: ReadonlyArray<string>;
+}
+export interface EitherCriteria {
+    readonly kind: "either";
+    readonly criteria: ReadonlyArray<EventCriteria>;
+}
+export interface AnyTagCriteria {
+    readonly kind: "any-tag";
+}
+/**
+ * A tag or any-tag criteria that allows further restriction by event types.
+ */
+export type RestrictableEventCriteria = (TagCriteria | AnyTagCriteria) & {
+    /**
+     * Restrict matched events to the given types.
+     * Accepts event descriptors or qualified name strings.
+     */
+    ofTypes(...types: Array<EventDescriptor<any> | QualifiedName | string>): EventCriteria;
+};
+export declare const EventCriteria: {
+    /**
+     * Match events having all the specified tags.
+     *
+     * Accepts individual Tag objects or a record of key-value pairs:
+     * ```typescript
+     * EventCriteria.havingTags({ courseId: id.courseId })
+     * EventCriteria.havingTags(tag("courseId", id.courseId))
+     * ```
+     */
+    readonly havingTags: (...args: Tag[] | [Record<string, string>]) => RestrictableEventCriteria;
+    /**
+     * Match events having any tag (i.e., all tagged events).
+     */
+    readonly havingAnyTag: () => RestrictableEventCriteria;
+    /**
+     * Match events matching any of the given criteria (logical OR).
+     */
+    readonly either: (...criteria: EventCriteria[]) => EventCriteria;
+};
+/**
+ * Match events having all the specified tags.
+ *
+ * Shorthand for `EventCriteria.havingTags()`. Supports `.ofTypes()` chaining.
+ *
+ * ```typescript
+ * tags({ courseId: id.courseId })
+ * tags({ courseId: id.courseId }).ofTypes(CourseCreated, CourseCapacityChanged)
+ * ```
+ */
+export declare function tags(...args: Tag[] | [Record<string, string>]): RestrictableEventCriteria;
+/**
+ * Match events having any tag.
+ *
+ * Shorthand for `EventCriteria.havingAnyTag()`. Supports `.ofTypes()` chaining.
+ */
+export declare function anyTag(): RestrictableEventCriteria;
+/**
+ * Match events matching any of the given criteria (logical OR).
+ *
+ * Shorthand for `EventCriteria.either()`.
+ *
+ * ```typescript
+ * either(
+ *   tags({ courseId: id.courseId }),
+ *   tags({ studentId: id.studentId }).ofTypes(StudentSubscribed),
+ * )
+ * ```
+ */
+export declare function either(...criteria: EventCriteria[]): EventCriteria;
+//# sourceMappingURL=event-criteria.d.ts.map

package/dist/event-criteria.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-criteria.d.ts","sourceRoot":"","sources":["../src/event-criteria.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,sBAAsB,GACtB,cAAc,GACd,cAAc,CAAA;AAElB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,CAAA;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,cAAc,CAAA;IAC5C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CAChD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,WAAW,GAAG,cAAc,CAAC,GAAG;IACvE;;;OAGG;IACH,OAAO,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,aAAa,GAAG,MAAM,CAAC,GAAG,aAAa,CAAA;CACvF,CAAA;AAqBD,eAAO,MAAM,aAAa;IACxB;;;;;;;;OAQG;mCACiB,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAG,yBAAyB;IAOhF;;OAEG;iCACa,yBAAyB;IAIzC;;OAEG;mCACiB,aAAa,EAAE,KAAG,aAAa;CAG3C,CAAA;AAMV;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,yBAAyB,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,yBAAyB,CAElD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,GAAG,QAAQ,EAAE,aAAa,EAAE,GAAG,aAAa,CAElE"}

package/dist/event-criteria.js

@@ -0,0 +1,90 @@
+import { qualifiedNameToString, tagsFromRecord } from "@kronos-ts/common";
+function resolveTypeName(t) {
+    if (typeof t === "string")
+        return t;
+    if ("kind" in t && t.kind === "event")
+        return qualifiedNameToString(t.name);
+    if ("namespace" in t && "name" in t)
+        return qualifiedNameToString(t);
+    return String(t);
+}
+function makeRestrictable(criteria) {
+    return Object.assign(criteria, {
+        ofTypes(...types) {
+            return {
+                kind: "type-restricted",
+                inner: criteria,
+                types: types.map(resolveTypeName),
+            };
+        },
+    });
+}
+export const EventCriteria = {
+    /**
+     * Match events having all the specified tags.
+     *
+     * Accepts individual Tag objects or a record of key-value pairs:
+     * ```typescript
+     * EventCriteria.havingTags({ courseId: id.courseId })
+     * EventCriteria.havingTags(tag("courseId", id.courseId))
+     * ```
+     */
+    havingTags(...args) {
+        if (args.length === 1 && typeof args[0] === "object" && !("key" in args[0])) {
+            return makeRestrictable({ kind: "tags", tags: tagsFromRecord(args[0]) });
+        }
+        return makeRestrictable({ kind: "tags", tags: args });
+    },
+    /**
+     * Match events having any tag (i.e., all tagged events).
+     */
+    havingAnyTag() {
+        return makeRestrictable({ kind: "any-tag" });
+    },
+    /**
+     * Match events matching any of the given criteria (logical OR).
+     */
+    either(...criteria) {
+        return { kind: "either", criteria };
+    },
+};
+// ---------------------------------------------------------------------------
+// Standalone shorthand functions
+// ---------------------------------------------------------------------------
+/**
+ * Match events having all the specified tags.
+ *
+ * Shorthand for `EventCriteria.havingTags()`. Supports `.ofTypes()` chaining.
+ *
+ * ```typescript
+ * tags({ courseId: id.courseId })
+ * tags({ courseId: id.courseId }).ofTypes(CourseCreated, CourseCapacityChanged)
+ * ```
+ */
+export function tags(...args) {
+    return EventCriteria.havingTags(...args);
+}
+/**
+ * Match events having any tag.
+ *
+ * Shorthand for `EventCriteria.havingAnyTag()`. Supports `.ofTypes()` chaining.
+ */
+export function anyTag() {
+    return EventCriteria.havingAnyTag();
+}
+/**
+ * Match events matching any of the given criteria (logical OR).
+ *
+ * Shorthand for `EventCriteria.either()`.
+ *
+ * ```typescript
+ * either(
+ *   tags({ courseId: id.courseId }),
+ *   tags({ studentId: id.studentId }).ofTypes(StudentSubscribed),
+ * )
+ * ```
+ */
+export function either(...criteria) {
+    return EventCriteria.either(...criteria);
+}
+//# sourceMappingURL=event-criteria.js.map

package/dist/event-criteria.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-criteria.js","sourceRoot":"","sources":["../src/event-criteria.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AA+CzE,SAAS,eAAe,CAAC,CAAgD;IACvE,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAA;IACnC,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IAC3E,IAAI,WAAW,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,qBAAqB,CAAC,CAAkB,CAAC,CAAA;IACrF,OAAO,MAAM,CAAC,CAAC,CAAC,CAAA;AAClB,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAsC;IAC9D,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE;QAC7B,OAAO,CAAC,GAAG,KAA2D;YACpE,OAAO;gBACL,IAAI,EAAE,iBAA0B;gBAChC,KAAK,EAAE,QAAQ;gBACf,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC;aAClC,CAAA;QACH,CAAC;KACF,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B;;;;;;;;OAQG;IACH,UAAU,CAAC,GAAG,IAAsC;QAClD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,OAAO,gBAAgB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAA2B,CAAC,EAAE,CAAC,CAAA;QACpG,CAAC;QACD,OAAO,gBAAgB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAa,EAAE,CAAC,CAAA;IAChE,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,gBAAgB,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAA;IAC9C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,GAAG,QAAyB;QACjC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAA;IACrC,CAAC;CACO,CAAA;AAEV,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,IAAI,CAAC,GAAG,IAAsC;IAC5D,OAAO,aAAa,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAA;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM;IACpB,OAAO,aAAa,CAAC,YAAY,EAAE,CAAA;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CAAC,GAAG,QAAyB;IACjD,OAAO,aAAa,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAA;AAC1C,CAAC"}

package/dist/event-gateway.d.ts

@@ -0,0 +1,19 @@
+import type { EventSink } from "./event-sink.js";
+import type { EventDescriptor } from "./descriptor.js";
+import type { z } from "zod";
+/**
+ * User-facing gateway for publishing events directly (without going through
+ * command handlers).
+ *
+ */
+export interface EventGateway {
+    /**
+     * Publish a single event described by its descriptor.
+     */
+    publish<P extends z.ZodType>(descriptor: EventDescriptor<P>, payload: z.infer<P>, metadata?: Record<string, unknown>): Promise<void>;
+}
+/**
+ * Creates an event gateway backed by an event sink.
+ */
+export declare function createEventGateway(eventSink: EventSink): EventGateway;
+//# sourceMappingURL=event-gateway.d.ts.map

package/dist/event-gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-gateway.d.ts","sourceRoot":"","sources":["../src/event-gateway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EACzB,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,EAC9B,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAAA;CACjB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,YAAY,CAgBrE"}

package/dist/event-gateway.js

@@ -0,0 +1,22 @@
+import { generateIdentifier } from "@kronos-ts/common";
+/**
+ * Creates an event gateway backed by an event sink.
+ */
+export function createEventGateway(eventSink) {
+    return {
+        async publish(descriptor, payload, metadata = {}) {
+            const tags = descriptor.tags ? descriptor.tags(payload) : [];
+            const event = {
+                identifier: generateIdentifier(),
+                name: descriptor.name,
+                version: descriptor.version,
+                payload,
+                metadata,
+                timestamp: Date.now(),
+                tags,
+            };
+            await eventSink.publish([event]);
+        },
+    };
+}
+//# sourceMappingURL=event-gateway.js.map

package/dist/event-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-gateway.js","sourceRoot":"","sources":["../src/event-gateway.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAmBtD;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAoB;IACrD,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,GAAG,EAAE;YAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;YAC5D,MAAM,KAAK,GAAiB;gBAC1B,UAAU,EAAE,kBAAkB,EAAE;gBAChC,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,OAAO,EAAE,UAAU,CAAC,OAAO;gBAC3B,OAAO;gBACP,QAAQ;gBACR,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,IAAI;aACL,CAAA;YACD,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QAClC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/event-handler.d.ts

@@ -0,0 +1,30 @@
+import type { z } from "zod";
+import type { Metadata } from "@kronos-ts/common";
+import type { EventDescriptor } from "./descriptor.js";
+/**
+ * A registered singular event handler — pairs an event descriptor with its handler
+ * function. Mirrors {@link import("./command-handler.js").CommandHandlerDefinition}
+ * structurally so all three handler shapes (command / event / query) share the same
+ * pattern.
+ */
+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;
+}
+/**
+ * Defines a singular event handler.
+ *
+ * ```
+ * const onCourseCreated = eventHandler(CourseCreated, async (event, metadata) => {
+ *   await db.courses.insert({ id: event.courseId, name: event.name })
+ * })
+ * ```
+ *
+ * Use with `trackingProcessor(...).eventHandlers(onCreated, onCapChanged).build()` or
+ * `subscribingProcessor(...).eventHandlers(...).build()`. Symmetric to
+ * {@link import("./command-handler.js").commandHandler} and
+ * {@link import("./query-handler.js").queryHandler}.
+ */
+export declare function eventHandler<P extends z.ZodType>(descriptor: EventDescriptor<P>, handler: (event: z.infer<P>, metadata: Metadata) => Promise<void> | void): EventHandlerDefinition<P>;
+//# sourceMappingURL=event-handler.d.ts.map

package/dist/event-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-handler.d.ts","sourceRoot":"","sources":["../src/event-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAOtD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IACrE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,CAChB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EACjB,QAAQ,EAAE,QAAQ,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC9C,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,EAC9B,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACvE,sBAAsB,CAAC,CAAC,CAAC,CAE3B"}

package/dist/event-handler.js

@@ -0,0 +1,18 @@
+/**
+ * Defines a singular event handler.
+ *
+ * ```
+ * const onCourseCreated = eventHandler(CourseCreated, async (event, metadata) => {
+ *   await db.courses.insert({ id: event.courseId, name: event.name })
+ * })
+ * ```
+ *
+ * Use with `trackingProcessor(...).eventHandlers(onCreated, onCapChanged).build()` or
+ * `subscribingProcessor(...).eventHandlers(...).build()`. Symmetric to
+ * {@link import("./command-handler.js").commandHandler} and
+ * {@link import("./query-handler.js").queryHandler}.
+ */
+export function eventHandler(descriptor, handler) {
+    return { kind: "event-handler", descriptor, handler };
+}
+//# sourceMappingURL=event-handler.js.map

package/dist/event-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-handler.js","sourceRoot":"","sources":["../src/event-handler.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAC1B,UAA8B,EAC9B,OAAwE;IAExE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,UAAU,EAAE,OAAO,EAAE,CAAA;AACvD,CAAC"}

package/dist/event-processor-builder.d.ts

@@ -0,0 +1,148 @@
+import type { EventHandlerDefinition } from "./event-handler.js";
+import type { TokenStore } from "./token-store.js";
+import type { UoWRunner } from "./unit-of-work.js";
+import type { EventProcessingErrorHandler } from "./tracking-event-processor.js";
+import type { SequencedDeadLetterQueue } from "./dead-letter-queue.js";
+/**
+ * Base configuration shared by all event processor types.
+ *
+ * Plan 11-02: option types carry a flat `eventHandlers: EventHandlerDefinition[]`
+ * array. The processor (not the handler bundle) owns reset semantics — see
+ * `TrackingProcessorModule.onReset`.
+ */
+interface EventProcessorBase {
+    readonly name: string;
+    readonly eventHandlers: ReadonlyArray<EventHandlerDefinition>;
+}
+/**
+ * Configuration for a tracking event processor (polling-based, with token store).
+ */
+export interface TrackingProcessorModule extends EventProcessorBase {
+    readonly kind: "tracking";
+    readonly batchSize?: number;
+    readonly pollingIntervalMs?: number;
+    readonly tokenStore?: TokenStore;
+    readonly unitOfWorkRunner?: UoWRunner;
+    readonly errorHandler?: EventProcessingErrorHandler;
+    readonly deadLetterQueue?: SequencedDeadLetterQueue;
+    /** Number of segments created on first startup. Default 16 (Axon Framework parity). Always set by builder.build(). */
+    readonly initialSegmentCount: number;
+    readonly claimExtensionThresholdMs?: number;
+    readonly tokenClaimIntervalMs?: number;
+    /** Reset callback invoked when the processor is reset. Reset is processor-level (clear token + replay), and the callback that wipes view state belongs alongside it. */
+    readonly onReset?: () => Promise<void> | void;
+}
+/**
+ * Configuration for a subscribing event processor (push-based, no tracking).
+ *
+ * Subscribing processors do not support reset — see `supportsReset()` on the
+ * runtime instance — so there is no `onReset` field here.
+ */
+export interface SubscribingProcessorModule extends EventProcessorBase {
+    readonly kind: "subscribing";
+    readonly unitOfWorkRunner?: UoWRunner;
+    readonly errorHandler?: EventProcessingErrorHandler;
+}
+export type EventProcessorModule = TrackingProcessorModule | SubscribingProcessorModule;
+/**
+ * Builder for a tracking event processor.
+ *
+ * Tracking processors poll the event store for new events, maintain
+ * position via a token store, and support replay/reset.
+ *
+ * ```typescript
+ * const onCreated = eventHandler(CourseCreated, async (e) => { ... })
+ * const onCapChanged = eventHandler(CourseCapacityChanged, async (e) => { ... })
+ *
+ * trackingProcessor("course-projection")
+ *   .eventHandlers(onCreated, onCapChanged)
+ *   .onReset(async () => courseViews.clear())
+ *   .batchSize(50)
+ *   .build()
+ * ```
+ *
+ * NOTE: Pooled streaming processor support is deferred to a follow-up
+ * research phase exploring how that model should fit Node/Bun runtime
+ * semantics, where worker threads are not reservable the same way as JVM
+ * threads.
+ */
+export declare function trackingProcessor(name: string): TrackingProcessorBuilder;
+export declare class TrackingProcessorBuilder {
+    private readonly _name;
+    private readonly _eventHandlers;
+    private _onReset?;
+    private _batchSize?;
+    private _pollingIntervalMs?;
+    private _tokenStore?;
+    private _unitOfWorkRunner?;
+    private _errorHandler?;
+    private _deadLetterQueue?;
+    private _initialSegmentCount?;
+    private _claimExtensionThresholdMs?;
+    private _tokenClaimIntervalMs?;
+    constructor(name: string);
+    /** Register one or more singular event handlers on this processor. */
+    eventHandlers(...handlers: EventHandlerDefinition[]): this;
+    /** Register a callback fired when the processor is reset (clears view state for replay). */
+    onReset(fn: () => Promise<void> | void): this;
+    /** Events per batch/transaction. Default: 100. */
+    batchSize(size: number): this;
+    /** Polling interval in ms. Default: 500. */
+    pollingIntervalMs(ms: number): this;
+    /** Override the token store for this processor. */
+    tokenStore(store: TokenStore): this;
+    /**
+     * Override the UnitOfWork runner for this processor. Compose with
+     * `transactionalUnitOfWorkFactory(runInUoW, txManager)` to attach
+     * transactional semantics.
+     */
+    unitOfWorkRunner(runner: UoWRunner): this;
+    /** Override the error handler for this processor. */
+    errorHandler(handler: EventProcessingErrorHandler): this;
+    /** Set a dead letter queue for this processor. */
+    deadLetterQueue(queue: SequencedDeadLetterQueue): this;
+    /** Number of segments to create on first startup. Default: 16 (Axon Framework parity). */
+    initialSegmentCount(count: number): this;
+    /** @internal Build the processor configuration. */
+    build(): TrackingProcessorModule;
+}
+/**
+ * Builder for a subscribing event processor.
+ *
+ * Subscribing processors receive events pushed from the event source
+ * as they are appended. No token store, no position tracking, no replay.
+ *
+ * ```typescript
+ * const onNotification = eventHandler(NotificationRaised, async (e) => { ... })
+ *
+ * subscribingProcessor("notifications")
+ *   .eventHandlers(onNotification)
+ *   .build()
+ * ```
+ *
+ * Subscribing processors do NOT support reset (`supportsReset() === false`),
+ * so there is no `.onReset(fn)` builder method here — that lives on
+ * `TrackingProcessorBuilder` only.
+ */
+export declare function subscribingProcessor(name: string): SubscribingProcessorBuilder;
+export declare class SubscribingProcessorBuilder {
+    private readonly _name;
+    private readonly _eventHandlers;
+    private _unitOfWorkRunner?;
+    private _errorHandler?;
+    constructor(name: string);
+    /** Register one or more singular event handlers on this processor. */
+    eventHandlers(...handlers: EventHandlerDefinition[]): this;
+    /**
+     * Override the UnitOfWork runner for this processor. Compose with
+     * `transactionalUnitOfWorkFactory(runInUoW, txManager)` to attach
+     * transactional semantics.
+     */
+    unitOfWorkRunner(runner: UoWRunner): this;
+    /** Override the error handler for this processor. */
+    errorHandler(handler: EventProcessingErrorHandler): this;
+    /** @internal Build the processor configuration. */
+    build(): SubscribingProcessorModule;
+}
+export {};
+//# sourceMappingURL=event-processor-builder.d.ts.map

package/dist/event-processor-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-processor-builder.d.ts","sourceRoot":"","sources":["../src/event-processor-builder.ts"],"names":[],"mappings":"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"}