drimion 0.1.0

package/dist/kernel/events/browser-event-manager.ts

@@ -0,0 +1,241 @@
+import type { DomainEventPayload, EventEntry } from "../types/event.types";
+import { BaseEventManager } from "./event-manager";
+import { ValidateEventName } from "./event-utils";
+
+/**
+ * @description
+ * Duck-typed interface for the browser `window` object.
+ *
+ * Using a structural type instead of `Window & typeof globalThis` keeps this
+ * module free of DOM lib dependencies, making the library usable in projects
+ * that do not include `"lib": ["DOM"]` in their tsconfig.
+ */
+export interface WindowLike {
+	dispatchEvent(event: Event): boolean;
+	addEventListener(
+		type: string,
+		listener: (event: Event) => void,
+		options?: boolean | AddEventListenerOptions,
+	): void;
+	removeEventListener(
+		type: string,
+		listener: (event: Event) => void,
+		options?: boolean | EventListenerOptions,
+	): void;
+	sessionStorage: {
+		getItem(key: string): string | null;
+		setItem(key: string, value: string): void;
+		removeItem(key: string): void;
+	};
+	CustomEvent: new <T>(
+		type: string,
+		eventInitDict?: { bubbles?: boolean; detail?: T },
+	) => Event;
+}
+
+/**
+ * @description
+ * Browser-side singleton event manager backed by the native `window` CustomEvent API.
+ *
+ * Manages application-level event subscriptions and dispatches for browser environments.
+ * Subscriptions are persisted in `sessionStorage` so their existence can be detected
+ * across re-renders. Listeners are automatically cleaned up on page unload.
+ *
+ * Supports wildcard event dispatch using `*` as a glob-style pattern.
+ *
+ * Use `EventContext.resolve()` to obtain this instance rather than constructing it directly.
+ * For most use cases, prefer `EventBus` — use this only when you need to tap into
+ * the native browser CustomEvent system.
+ *
+ * @example
+ * ```typescript
+ * const manager = BrowserEventManager.instance(window);
+ *
+ * manager.subscribe('order:placed', (event) => {
+ *     console.log(event.detail);
+ * });
+ *
+ * manager.dispatchEvent('order:placed', { orderId: '123' });
+ * ```
+ */
+export class BrowserEventManager extends BaseEventManager {
+	private static _instance: BrowserEventManager;
+	private readonly entries: EventEntry[] = [];
+	private readonly storagePrefix = "browser:event:";
+	private initialized = false;
+
+	private constructor(private readonly win: WindowLike) {
+		super();
+		if (typeof win === "undefined" || win === null) {
+			throw new Error("BrowserEventManager requires a valid window object.");
+		}
+	}
+
+	/**
+	 * @description
+	 * Returns the singleton `BrowserEventManager` instance, creating it if necessary.
+	 *
+	 * @param win The browser `window` object (or any `WindowLike` implementation).
+	 * @returns The singleton `BrowserEventManager`.
+	 * @throws {Error} If called outside a browser environment.
+	 */
+	public static instance(win: WindowLike): BrowserEventManager {
+		if (!BrowserEventManager._instance) {
+			BrowserEventManager._instance = new BrowserEventManager(win);
+		}
+		return BrowserEventManager._instance;
+	}
+
+	/**
+	 * @description
+	 * Checks whether an event with the given name is currently registered.
+	 *
+	 * Checks both the internal entry list and `sessionStorage` for persistence
+	 * across re-renders.
+	 *
+	 * @param eventName The event name to check.
+	 * @returns `true` if the event is registered.
+	 */
+	public exists(eventName: string): boolean {
+		const inStorage = !!this.win.sessionStorage.getItem(
+			this.storagePrefix + eventName,
+		);
+		const inEntries = this.entries.some((e) => e.eventName === eventName);
+		return inStorage || inEntries;
+	}
+
+	/**
+	 * @description
+	 * Dispatches a custom event by name, forwarding optional arguments as the `detail` payload.
+	 *
+	 * Supports wildcard patterns — if `eventName` contains `*`, all registered events
+	 * whose names match the resulting regex are dispatched.
+	 *
+	 * @param eventName The event name or wildcard pattern to dispatch.
+	 * @param args Additional arguments forwarded as `detail` to handlers.
+	 */
+	public dispatchEvent(eventName: string, ...args: unknown[]): void {
+		ValidateEventName(eventName);
+
+		if (eventName.includes("*")) {
+			const regex = new RegExp(eventName.replace("*", ".*"));
+			for (const entry of this.entries) {
+				if (regex.test(entry.eventName)) {
+					this.win.dispatchEvent(
+						new this.win.CustomEvent(entry.eventName, {
+							bubbles: true,
+							detail: args,
+						}),
+					);
+				}
+			}
+			return;
+		}
+
+		this.win.dispatchEvent(
+			new this.win.CustomEvent(eventName, {
+				bubbles: true,
+				detail: args,
+			}),
+		);
+	}
+
+	/**
+	 * @description
+	 * Removes a registered event, cleaning up its listener and `sessionStorage` entry.
+	 *
+	 * @param eventName The name of the event to remove.
+	 * @returns `true` if the event was found and removed; `false` otherwise.
+	 */
+	public removeEvent(eventName: string): boolean {
+		// this.win.sessionStorage.removeItem(this.storagePrefix + eventName);
+		// const entry = this.entries.find((e) => e.eventName === eventName);
+		// if (!entry) return false;
+		// this.entries.splice(this.entries.indexOf(entry), 1);
+		// // Cast through unknown — the callback is structurally compatible at runtime
+		// // (CustomEvent extends Event), but TypeScript cannot verify this statically.
+		// this.win.removeEventListener(
+		// 	eventName,
+		// 	entry.callback as unknown as (event: Event) => void,
+		// );
+		// return true;
+		const matching = this.entries.filter((e) => e.eventName === eventName);
+
+		if (matching.length === 0) return false;
+
+		// Remove from entries
+		this.entries.splice(
+			0,
+			this.entries.length,
+			...this.entries.filter((e) => e.eventName !== eventName),
+		);
+
+		// Remove all listeners
+		for (const entry of matching) {
+			this.win.removeEventListener(
+				eventName,
+				entry.callback as unknown as (event: Event) => void,
+			);
+		}
+
+		// Remove storage
+		this.win.sessionStorage.removeItem(this.storagePrefix + eventName);
+
+		return true;
+	}
+
+	/**
+	 * @description
+	 * Subscribes a callback to the specified event name using the native `window` event system.
+	 *
+	 * Persists the subscription in `sessionStorage` and registers a `beforeunload`
+	 * cleanup listener. If the event is already registered, this call is a no-op.
+	 *
+	 * Event names must follow the `context:EventName` format.
+	 *
+	 * @param eventName The event name to subscribe to.
+	 * @param fn The callback to invoke when the event is dispatched.
+	 *
+	 * @throws {DomainError} If the event name does not follow the required format.
+	 */
+	public subscribe(
+		eventName: string,
+		fn: (event: DomainEventPayload) => void | Promise<void>,
+	): void {
+		ValidateEventName(eventName);
+
+		this.entries.push({ eventName, callback: fn });
+		this.win.sessionStorage.setItem(
+			this.storagePrefix + eventName,
+			Date.now().toString(),
+		);
+		this.win.addEventListener(
+			eventName,
+			fn as unknown as (event: Event) => void,
+		);
+		if (!this.initialized) {
+			this.win.addEventListener("beforeunload", () => {
+				for (const entry of this.entries) {
+					this.win.sessionStorage.removeItem(
+						this.storagePrefix + entry.eventName,
+					);
+				}
+			});
+
+			this.initialized = true;
+		}
+	}
+
+	/**
+	 * @description
+	 * Resets the cached event manager instance.
+	 *
+	 * Intended for use in tests where environment switching or clean state
+	 * between test cases is required. Not recommended in production code.
+	 *
+	 * @internal
+	 */
+	public static __reset(): void {
+		BrowserEventManager._instance = undefined as unknown as BrowserEventManager;
+	}
+}

package/dist/kernel/events/domain-event.ts

@@ -0,0 +1,76 @@
+import type { DomainEvent } from "../types/event.types";
+
+/**
+ * @description
+ * Abstract base class for defining strongly-typed domain events.
+ *
+ * Extend this class when you want an OOP-style event definition with a fixed
+ * `type` string baked into the class. The `aggregateId`, `aggregateName`, and
+ * `occurredAt` fields are set automatically by `Aggregate.emit()` — subclasses
+ * only need to declare the `payload` shape.
+ *
+ * Using this base class is **optional**. `Aggregate.emit()` accepts any object
+ * conforming to `DomainEvent<TPayload>` — a plain object literal works equally
+ * well. Prefer this class when you want a reusable, self-describing event type
+ * that can be imported and checked with `instanceof`.
+ *
+ * @template TPayload The shape of the event-specific data.
+ *
+ * @example
+ * ```typescript
+ * // Define the event
+ * interface OrderPlacedPayload { total: number; customerId: string }
+ *
+ * class OrderPlacedEvent extends BaseDomainEvent<OrderPlacedPayload> {
+ *     static readonly type = 'order:placed' as const;
+ *
+ *     constructor(aggregateId: string, payload: OrderPlacedPayload) {
+ *         super(OrderPlacedEvent.type, aggregateId, 'Order', payload);
+ *     }
+ * }
+ *
+ * // Inside an Aggregate subclass
+ * class Order extends Aggregate<OrderProps> {
+ *     public place(): void {
+ *         this.change('status', 'placed');
+ *         this.emit(new OrderPlacedEvent(this.id.value(), {
+ *             total: this.get('total'),
+ *             customerId: this.get('customerId'),
+ *         }));
+ *     }
+ * }
+ *
+ * // Application layer
+ * order.place();
+ * await repo.save(order);
+ * await eventBus.publishAll(order.pullEvents());
+ * ```
+ */
+export abstract class BaseDomainEvent<TPayload = unknown>
+	implements DomainEvent<TPayload>
+{
+	readonly type: string;
+	readonly aggregateId: string;
+	readonly aggregateName: string;
+	readonly occurredAt: Date;
+	readonly payload: TPayload;
+
+	/**
+	 * @param type          The event type identifier, e.g. `'order:placed'`.
+	 * @param aggregateId   The `id.value()` of the aggregate that emitted this event.
+	 * @param aggregateName The class name of the aggregate, e.g. `'Order'`.
+	 * @param payload       Event-specific data. Keep flat and serializable.
+	 */
+	constructor(
+		type: string,
+		aggregateId: string,
+		aggregateName: string,
+		payload: TPayload,
+	) {
+		this.type = type;
+		this.aggregateId = aggregateId;
+		this.aggregateName = aggregateName;
+		this.occurredAt = new Date();
+		this.payload = payload;
+	}
+}

package/dist/kernel/events/event-bus.ts

@@ -0,0 +1,158 @@
+import type {
+	DomainEvent,
+	EventSubscriber,
+	IEventBus,
+	SubscriberEntry,
+} from "../types/event.types";
+
+/**
+ * @description
+ * A simple, in-process event bus that ships with the library as a zero-config
+ * default. Suitable for monolithic applications, unit tests, and any context
+ * where events do not need to cross process or network boundaries.
+ *
+ * `EventBus` implements `IEventBus` so it can be swapped for any external
+ * transport (Redis, NATS, BullMQ, etc.) without touching domain code.
+ *
+ * Subscribers are registered per `type` string and invoked in registration
+ * order. Each subscriber runs independently — a failure in one does not
+ * prevent the others from running.
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Register subscribers (application layer)
+ * bus.subscribe('order:placed', async (event) => {
+ *     await sendConfirmationEmail(event.payload.customerId);
+ * });
+ *
+ * // Publish after repository.save() (application layer)
+ * await repo.save(order);
+ * await bus.publishAll(order.pullEvents());
+ * ```
+ */
+export class EventBus implements IEventBus {
+	private readonly entries: SubscriberEntry[] = [];
+
+	/**
+	 * @description
+	 * Registers a subscriber for a specific event type.
+	 *
+	 * Multiple subscribers for the same `type` are all invoked when that event
+	 * is published. Subscribing the same function twice for the same type will
+	 * register it twice — callers are responsible for deduplication if needed.
+	 *
+	 * @param type       The event type to listen for, e.g. `'order:placed'`.
+	 * @param subscriber The callback to invoke when a matching event is published.
+	 */
+	public subscribe<TPayload = unknown>(
+		type: string,
+		subscriber: EventSubscriber<TPayload>,
+	): void {
+		this.entries.push({
+			type,
+			subscriber: subscriber as EventSubscriber,
+		});
+	}
+
+	/**
+	 * @description
+	 * Removes all subscribers for a given event type.
+	 *
+	 * @param type The event type whose subscribers should be removed.
+	 * @returns The number of subscribers that were removed.
+	 */
+	public unsubscribe(type: string): number {
+		const before = this.entries.length;
+		const remaining = this.entries.filter((e) => e.type !== type);
+		this.entries.splice(0, this.entries.length, ...remaining);
+		return before - this.entries.length;
+	}
+
+	/**
+	 * @description
+	 * Publishes a single domain event, invoking all matching subscribers in
+	 * registration order.
+	 *
+	 * Subscriber errors are caught and re-thrown after all subscribers have
+	 * had a chance to run, collected as an `AggregateError`.
+	 *
+	 * @param event The domain event to publish.
+	 * @throws {AggregateError} If one or more subscribers throw.
+	 */
+	public async publish(event: DomainEvent): Promise<void> {
+		const matching = this.entries.filter((e) => e.type === event.type);
+		const errors: unknown[] = [];
+
+		for (const entry of matching) {
+			try {
+				await entry.subscriber(event);
+			} catch (err) {
+				errors.push(err);
+			}
+		}
+
+		if (errors.length > 0) {
+			throw new AggregateError(
+				errors,
+				`EventBus: ${errors.length} subscriber(s) failed for event "${event.type}".`,
+			);
+		}
+	}
+
+	/**
+	 * @description
+	 * Publishes all domain events in the provided array, in order.
+	 * Each event is published independently — a failure in one event's
+	 * subscribers does not prevent subsequent events from being published.
+	 *
+	 * Errors from all events are collected and thrown together as an
+	 * `AggregateError` after all events have been processed.
+	 *
+	 * @param events The array of domain events to publish.
+	 * @throws {AggregateError} If any subscriber across any event throws.
+	 */
+	public async publishAll(events: ReadonlyArray<DomainEvent>): Promise<void> {
+		const errors: unknown[] = [];
+
+		for (const event of events) {
+			try {
+				await this.publish(event);
+			} catch (err) {
+				// AggregateError from publish() — unwrap its inner errors
+				if (err instanceof AggregateError) {
+					errors.push(...err.errors);
+				} else {
+					errors.push(err);
+				}
+			}
+		}
+
+		if (errors.length > 0) {
+			throw new AggregateError(
+				errors,
+				`EventBus: ${errors.length} error(s) occurred while publishing ${events.length} event(s).`,
+			);
+		}
+	}
+
+	/**
+	 * @description
+	 * Returns the number of subscribers currently registered for a given type.
+	 * Useful for testing and diagnostics.
+	 *
+	 * @param type The event type to count subscribers for.
+	 */
+	public subscriberCount(type: string): number {
+		return this.entries.filter((e) => e.type === type).length;
+	}
+
+	/**
+	 * @description
+	 * Removes all registered subscribers. Useful for test teardown.
+	 */
+	public clear(): void {
+		this.entries.splice(0, this.entries.length);
+	}
+}

package/dist/kernel/events/event-context.ts

@@ -0,0 +1,95 @@
+import { BrowserEventManager } from "./browser-event-manager";
+import type { BaseEventManager } from "./event-manager";
+import { ServerEventManager } from "./server-event-manager";
+
+/**
+ * @description
+ * Internal cache for the resolved event manager instance.
+ */
+let managerCache: BaseEventManager | null = null;
+
+/**
+ * @description
+ * Provides a platform-aware mechanism for resolving the appropriate built-in
+ * event manager at runtime.
+ *
+ * `EventContext` detects whether the current environment is Node.js or a browser,
+ * then initialises and returns the corresponding singleton `BaseEventManager`:
+ * - Node.js / Bun / Deno → `ServerEventManager`
+ * - Browser              → `BrowserEventManager`
+ *
+ * Detection uses `process.versions?.node` rather than just `process` to avoid
+ * false positives in bundled browser environments (Webpack/Vite) where `process`
+ * may be polyfilled.
+ *
+ * @remarks
+ * `EventContext` is an **optional, convenience utility** for the built-in event
+ * managers. Application code that uses `EventBus` or a custom `IEventBus`
+ * implementation does not need this at all — it exists only to simplify access
+ * to `BrowserEventManager` / `ServerEventManager` when you choose to use them.
+ *
+ * @example
+ * ```typescript
+ * // Resolve the platform-appropriate manager once at startup
+ * const manager = EventContext.resolve();
+ * manager.subscribe('order:placed', handler);
+ *
+ * // After aggregate mutations and repository.save():
+ * for (const event of order.pullEvents()) {
+ *     manager.dispatchEvent(event.type, event);
+ * }
+ * ```
+ */
+export const EventContext = {
+	/**
+	 * @description
+	 * Resolves and returns the platform-appropriate `BaseEventManager` singleton.
+	 *
+	 * Detection order:
+	 * 1. Node.js / Bun — detected via `process.versions?.node`
+	 * 2. Browser       — detected via `globalThis.window`
+	 *
+	 * The resolved instance is cached after first resolution. Call `reset()`
+	 * in tests if you need a clean state between environment switches.
+	 *
+	 * @returns The resolved `BaseEventManager` instance.
+	 * @throws {Error} If the runtime environment cannot be determined.
+	 */
+	resolve(): BaseEventManager {
+		if (managerCache) return managerCache;
+
+		if (
+			typeof process !== "undefined" &&
+			process.versions?.node !== undefined
+		) {
+			managerCache = ServerEventManager.instance();
+			return managerCache;
+		}
+
+		if (
+			typeof globalThis !== "undefined" &&
+			typeof globalThis.window !== "undefined"
+		) {
+			managerCache = BrowserEventManager.instance(
+				globalThis.window as Window & typeof globalThis,
+			);
+			return managerCache;
+		}
+
+		throw new Error(
+			"EventContext: unable to determine the runtime environment. " +
+				"Neither a Node.js-compatible runtime nor a browser window was detected.",
+		);
+	},
+
+	/**
+	 * @description
+	 * Resets the cached event manager instance.
+	 *
+	 * Intended for use in tests where environment switching or clean state
+	 * between test cases is required. Not recommended in production code.
+	 */
+	__reset(): void {
+		managerCache = null;
+	},
+};

package/dist/kernel/events/event-manager.ts

@@ -0,0 +1,20 @@
+import type { DomainEventPayload } from "../types/event.types";
+
+/**
+ * @description
+ * Abstract base class for the built-in event manager implementations
+ * (`BrowserEventManager`, `ServerEventManager`).
+ *
+ * Application code that depends only on `IEventBus` does not need this class.
+ * It is exposed for library consumers who want to extend or replace the
+ * built-in transport layer.
+ */
+export abstract class BaseEventManager {
+	abstract subscribe(
+		eventName: string,
+		fn: (event: DomainEventPayload) => void | Promise<void>,
+	): void;
+	abstract exists(eventName: string): boolean;
+	abstract removeEvent(eventName: string): boolean;
+	abstract dispatchEvent(eventName: string, ...args: unknown[]): void;
+}

package/dist/kernel/events/event-utils.ts

@@ -0,0 +1,19 @@
+import { DomainError } from "../helpers";
+
+/**
+ * @description
+ * Validates that an event name follows the required `context:EventName` format.
+ *
+ * @param eventName The event name to validate.
+ * @throws {DomainError} If the event name does not contain a colon separator.
+ */
+export const ValidateEventName = (eventName: string): void => {
+	if (!eventName.includes(":")) {
+		throw new DomainError(
+			`Invalid event name "${eventName}". ` +
+				'Event names must follow the pattern "context:EventName" ' +
+				'(e.g., "order:placed", "user:registered").',
+			{ context: "DomainEvent" },
+		);
+	}
+};

package/dist/kernel/events/index.ts

@@ -0,0 +1,7 @@
+export { BrowserEventManager, type WindowLike } from "./browser-event-manager";
+export { BaseDomainEvent } from "./domain-event";
+export { EventBus } from "./event-bus";
+export { EventContext } from "./event-context";
+export { BaseEventManager } from "./event-manager";
+export { ValidateEventName } from "./event-utils";
+export { ServerEventManager } from "./server-event-manager";