drimion 0.1.0

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

@@ -0,0 +1,169 @@
+import { EventEmitter } from "node:events";
+import type { DomainEventPayload, EventEntry } from "../types/event.types";
+import { BaseEventManager } from "./event-manager";
+import { ValidateEventName } from "./event-utils";
+
+/**
+ * @description
+ * Server-side singleton event manager backed by Node.js `EventEmitter`.
+ *
+ * Manages application-level event subscriptions and dispatches for server
+ * environments (Node.js, Bun, Deno). 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 direct access to the `EventEmitter` transport.
+ *
+ * @example
+ * ```typescript
+ * const manager = ServerEventManager.instance();
+ *
+ * manager.subscribe('order:placed', (event) => {
+ *     console.log(event.detail);
+ * });
+ *
+ * manager.dispatchEvent('order:placed', { orderId: '123' });
+ * ```
+ */
+export class ServerEventManager extends BaseEventManager {
+	private static _instance: ServerEventManager;
+	private readonly emitter: EventEmitter;
+	private readonly entries: EventEntry[] = [];
+
+	private constructor() {
+		super();
+		// Use `process.versions?.node` instead of just `process` to avoid false
+		// positives in bundled browser environments where `process` may be polyfilled
+		// by Webpack / Vite but `process.versions.node` is never set.
+		if (
+			typeof process === "undefined" ||
+			process.versions?.node === undefined ||
+			typeof EventEmitter === "undefined"
+		) {
+			throw new Error(
+				"ServerEventManager is not supported in this environment.",
+			);
+		}
+		this.emitter = new EventEmitter({ captureRejections: true });
+	}
+
+	/**
+	 * @description
+	 * Returns the singleton `ServerEventManager` instance, creating it if necessary.
+	 *
+	 * @returns The singleton `ServerEventManager`.
+	 * @throws {Error} If called outside a Node.js-compatible environment.
+	 */
+	public static instance(): ServerEventManager {
+		if (!ServerEventManager._instance) {
+			ServerEventManager._instance = new ServerEventManager();
+		}
+		return ServerEventManager._instance;
+	}
+
+	/**
+	 * @description
+	 * Checks whether an event with the given name is currently registered.
+	 *
+	 * @param eventName The event name to check.
+	 * @returns `true` if at least one listener exists for this event name.
+	 */
+	public exists(eventName: string): boolean {
+		return (
+			this.emitter.listenerCount(eventName) > 0 ||
+			this.entries.some((e) => e.eventName === eventName)
+		);
+	}
+
+	/**
+	 * @description
+	 * Dispatches an 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.emitter.emit(entry.eventName, { detail: args });
+				}
+			}
+			return;
+		}
+
+		this.emitter.emit(eventName, { detail: args });
+	}
+
+	/**
+	 * @description
+	 * Removes a registered event and its associated listener.
+	 *
+	 * @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 {
+		// const entry = this.entries.find((e) => e.eventName === eventName);
+		// if (!entry) return false;
+		// this.entries.splice(this.entries.indexOf(entry), 1);
+		// this.emitter.removeListener(eventName, entry.callback);
+		// return true;
+
+		const matching = this.entries.filter((e) => e.eventName === eventName);
+
+		if (matching.length === 0) return false;
+		this.entries.splice(
+			0,
+			this.entries.length,
+			...this.entries.filter((e) => e.eventName !== eventName),
+		);
+
+		for (const entry of matching) {
+			this.emitter.removeListener(eventName, entry.callback);
+		}
+
+		return true;
+	}
+
+	/**
+	 * @description
+	 * Subscribes a callback to the specified event name.
+	 *
+	 * If an event with the same name 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.emitter.addListener(eventName, fn);
+	}
+
+	/**
+	 * @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 {
+		ServerEventManager._instance = undefined as unknown as ServerEventManager;
+	}
+}

package/dist/kernel/helpers/auto-mapper.ts

@@ -0,0 +1,222 @@
+import validator, { type Validator } from "../libs/validator";
+import type { AnyObject } from "../types/utils.types";
+
+/**
+ * @description
+ * Defines the shape of data used for mapping an entity's properties.
+ */
+export interface EntityAutoMapperPayload {
+	id: string;
+	createdAt: Date;
+	updatedAt: Date;
+}
+
+/**
+ * @description
+ * The `AutoMapper` class is responsible for transforming domain resources (entities, value objects)
+ * into plain objects or primitive values. It provides methods to recursively process nested value objects, IDs,
+ * entities, and arrays, ensuring all complex data structures are serialized into a consistent object format.
+ */
+export class AutoMapper {
+	private validator: Validator = validator;
+
+	/**
+	 * @description
+	 * Transforms an entity into a plain object, including its associated meta properties
+	 * (`id`, `createdAt`, `updatedAt`).
+	 *
+	 * This method:
+	 * - Resolves IDs to their primitive value forms.
+	 * - Recursively converts nested entities, aggregates, and value objects to plain objects.
+	 * - Preserves arrays and transforms their elements as needed.
+	 *
+	 * @param entity The entity instance to be transformed into a plain object.
+	 * @returns A plain object representing the entity, including its metadata and serialized properties.
+	 */
+	public entityToObj(entity: unknown): unknown {
+		if (this.validator.isID(entity)) {
+			return (entity as { value(): string }).value();
+		}
+
+		if (this.validator.isSymbol(entity)) {
+			return (entity as symbol).description;
+		}
+
+		if (
+			this.validator.isBoolean(entity) ||
+			this.validator.isNumber(entity) ||
+			this.validator.isString(entity) ||
+			this.validator.isDate(entity) ||
+			entity === null
+		) {
+			return entity;
+		}
+
+		if (this.validator.isValueObject(entity)) {
+			return this.valueObjectToObj(entity);
+		}
+
+		if (this.validator.isArray(entity)) {
+			return (entity as unknown[]).map((item) => this.valueObjectToObj(item));
+		}
+
+		if (this.validator.isObject(entity)) {
+			const result: AnyObject = {};
+			for (const key of Object.keys(entity as object)) {
+				result[key] = this.entityToObj((entity as AnyObject)[key]);
+			}
+			return result;
+		}
+
+		if (this.validator.isEntity(entity) || this.validator.isAggregate(entity)) {
+			return this.serializeEntity(entity);
+		}
+
+		return entity;
+	}
+
+	/**
+	 * @description
+	 * Serializes an entity or aggregate into a plain object, extracting its identity
+	 * metadata (`id`, `createdAt`, `updatedAt`) and recursively converting all nested
+	 * properties into their primitive or serialized equivalents.
+	 *
+	 * This method is called internally by `entityToObj` when the target is confirmed
+	 * to be an entity or aggregate (identified via `__kind` marker).
+	 *
+	 * @param entity The entity or aggregate instance to serialize. Expected to have
+	 * a `props` object and an `id` field exposing a `.value()` method.
+	 * @returns A plain object representation of the entity, including all metadata
+	 * and recursively serialized properties.
+	 */
+	private serializeEntity(entity: unknown): unknown {
+		const e = entity as AnyObject;
+		const props = (e.props ?? {}) as AnyObject;
+		const id = (e.id as { value(): string } | undefined)?.value();
+
+		const result: AnyObject & Partial<EntityAutoMapperPayload> = {
+			id,
+			createdAt: props.createdAt as Date | undefined,
+			updatedAt: props.updatedAt as Date | undefined,
+		};
+
+		for (const key of Object.keys(props)) {
+			if (key === "createdAt" || key === "updatedAt") continue;
+
+			const val = props[key];
+
+			if (this.validator.isID(val)) {
+				result[key] = (val as { value(): string }).value();
+			} else if (this.validator.isArray(val)) {
+				result[key] = (val as unknown[]).map((item) => this.entityToObj(item));
+			} else if (this.validator.isEntity(val)) {
+				result[key] = this.entityToObj(val);
+			} else if (this.validator.isSymbol(val)) {
+				result[key] = (val as symbol).description;
+			} else {
+				result[key] = this.valueObjectToObj(val);
+			}
+		}
+
+		return result;
+	}
+
+	/**
+	 * @description
+	 * Converts a value object into a plain object or a primitive value.
+	 *
+	 * This method handles multiple scenarios, including:
+	 * - Null values
+	 * - Symbol values
+	 * - ID values
+	 * - Simple data types (strings, numbers, booleans, dates, objects)
+	 * - Nested value objects
+	 * - Arrays containing complex data
+	 *
+	 * @param valueObject An instance representing a value object to be transformed.
+	 * @returns A plain object, primitive value, or serialized structure derived from the given value object.
+	 */
+	public valueObjectToObj(valueObject: unknown): unknown {
+		if (valueObject === null) return null;
+		if (typeof valueObject === "undefined") return undefined;
+
+		if (this.validator.isSymbol(valueObject)) {
+			return (valueObject as symbol).description;
+		}
+
+		if (this.validator.isID(valueObject)) {
+			return (valueObject as { value(): string }).value();
+		}
+
+		if (
+			this.validator.isBoolean(valueObject) ||
+			this.validator.isNumber(valueObject) ||
+			this.validator.isString(valueObject) ||
+			this.validator.isDate(valueObject)
+		) {
+			return valueObject;
+		}
+
+		if (this.validator.isArray(valueObject)) {
+			return (valueObject as unknown[]).map((item) =>
+				this.valueObjectToObj(item),
+			);
+		}
+
+		if (this.validator.isObject(valueObject)) {
+			const result: AnyObject = {};
+			for (const key of Object.keys(valueObject as object)) {
+				result[key] = this.entityToObj((valueObject as AnyObject)[key]);
+			}
+			return result;
+		}
+
+		// treat as VO with props
+		const vo = valueObject as AnyObject;
+		const voProps = vo.props;
+
+		if (
+			this.validator.isBoolean(voProps) ||
+			this.validator.isNumber(voProps) ||
+			this.validator.isString(voProps) ||
+			this.validator.isDate(voProps)
+		) {
+			return voProps;
+		}
+
+		if (this.validator.isSymbol(voProps)) {
+			return (voProps as symbol).description;
+		}
+
+		if (this.validator.isArray(voProps)) {
+			return (voProps as unknown[]).map((item) => this.valueObjectToObj(item));
+		}
+
+		if (this.validator.isObject(voProps)) {
+			const props = voProps as AnyObject;
+			const result: AnyObject = {};
+
+			for (const key of Object.keys(props)) {
+				const val = props[key];
+
+				if (this.validator.isValueObject(val)) {
+					result[key] = this.valueObjectToObj(val);
+				} else if (this.validator.isID(val)) {
+					result[key] = (val as { value(): string }).value();
+				} else if (this.validator.isSymbol(val)) {
+					result[key] = (val as symbol).description;
+				} else if (this.validator.isArray(val)) {
+					result[key] = (val as unknown[]).map((item) =>
+						this.valueObjectToObj(item),
+					);
+				} else {
+					result[key] = val;
+				}
+			}
+
+			return result;
+		}
+
+		return this.entityToObj(voProps);
+	}
+}

package/dist/kernel/helpers/domain-classes.ts

@@ -0,0 +1,162 @@
+import { Iterator } from "../libs/iterator";
+import { Result } from "../libs/result";
+import type { IIterator } from "../types/iterator.types";
+import type { IResult } from "../types/result.types";
+
+/**
+ * @description
+ * Represents the result of a `DomainClasseses.createMany()` operation.
+ *
+ * Contains both an iterator over each individual creation result and a combined
+ * result that reflects the overall success or failure of the batch operation.
+ */
+export interface CreateManyResult {
+	/**
+	 * @description
+	 * An iterator over each individual `Result` produced during the batch creation.
+	 * Use `data.next()` to access results in the same order as the input entries.
+	 */
+	data: IIterator<IResult<unknown, unknown, unknown>>;
+
+	/**
+	 * @description
+	 * A combined `Result` representing the overall outcome.
+	 * Will be a failure if any single entry failed to be created.
+	 */
+	result: IResult<unknown, unknown, unknown>;
+}
+
+/**
+ * @description
+ * Represents a pairing of a domain class and the props needed to construct an instance of it.
+ * Used internally by the `DomainClasses` fluent builder.
+ */
+interface DomainClassesEntry {
+	class: {
+		create: (props: unknown) => IResult<unknown, unknown, unknown>;
+		name: string;
+	};
+	props: unknown;
+}
+
+/**
+ * @description
+ * Fluent builder for creating multiple domain instances in a single batch operation.
+ *
+ * Chain `.prepare()` calls to register domain classes and their props,
+ * then call `.create()` to execute all instantiations at once.
+ *
+ * The combined `result` reflects the overall success or failure of the batch —
+ * it fails if any single entry fails. Individual results are accessible via the
+ * returned `data` iterator in the same order as the `.prepare()` calls.
+ *
+ * @example
+ * ```typescript
+ * const { result, data } = DomainClasses
+ *     .prepare(Age, { value: 21 })
+ *     .prepare(Name, { value: 'Alice' })
+ *     .create();
+ *
+ * if (result.isSuccess()) {
+ *     const age = data.next().value() as Age;
+ *     const name = data.next().value() as Name;
+ * }
+ * ```
+ */
+export class DomainClasses {
+	private readonly entries: DomainClassesEntry[] = [];
+
+	private constructor() {}
+
+	/**
+	 * @description
+	 * Registers a domain class and its construction props for batch instantiation.
+	 *
+	 * Returns the same `DomainClasses` builder instance to allow chaining.
+	 *
+	 * @param domainClasses The domain class with a static `create` method.
+	 * @param props The props to pass to the class's `create` method.
+	 * @returns The current `DomainClasses` builder instance.
+	 *
+	 * @example
+	 * ```typescript
+	 * DomainClasses.prepare(Money, { amount: 100 })
+	 * ```
+	 */
+	public prepare<Props>(
+		domainClasses: DomainClassesEntry["class"],
+		props: Props,
+	): this {
+		this.entries.push({ class: domainClasses, props });
+		return this;
+	}
+
+	/**
+	 * @description
+	 * Executes the batch creation of all registered domain class entries.
+	 *
+	 * Iterates over each registered entry and calls its class's static `create` method.
+	 * If an entry's class does not expose a `create` method, a failure `Result` is
+	 * recorded for that entry.
+	 *
+	 * @returns A `CreateManyResult` containing:
+	 * - `result`: A combined `IResult` — fails if any entry failed.
+	 * - `data`: An `IIterator` over each individual `IResult`, in registration order.
+	 *
+	 * @example
+	 * ```typescript
+	 * const { result, data } = DomainClasses
+	 *     .prepare(Age, { value: 21 })
+	 *     .prepare(Name, { value: 'Alice' })
+	 *     .create();
+	 * ```
+	 */
+	public create(): CreateManyResult {
+		const results: IResult<unknown, unknown, unknown>[] = [];
+
+		for (const entry of this.entries) {
+			if (typeof entry.class?.create !== "function") {
+				results.push(
+					Result.error(
+						`No static 'create' method found in class ${entry.class?.name}.`,
+					),
+				);
+				continue;
+			}
+			results.push(entry.class.create(entry.props));
+		}
+
+		const iterator = Iterator.create({
+			initialData: results,
+			returnCurrentOnReversion: true,
+		});
+
+		return {
+			data: iterator,
+			result: Result.combine(results),
+		};
+	}
+
+	/**
+	 * @description
+	 * Entry point for the `DomainClasses` fluent builder.
+	 *
+	 * Equivalent to `new DomainClasses().prepare(domainClasses, props)` — starts a new
+	 * builder chain with the first class-props pair already registered.
+	 *
+	 * @param domainClasses The domain class with a static `create` method.
+	 * @param props The props to pass to the class's `create` method.
+	 * @returns A new `DomainClasses` builder instance with the first entry registered.
+	 *
+	 * @example
+	 * ```typescript
+	 * DomainClasses.prepare(Age, { value: 21 }).prepare(Name, { value: 'Alice' }).create()
+	 * ```
+	 */
+	public static prepare<Props>(
+		domainClasses: DomainClassesEntry["class"],
+		props: Props,
+	): DomainClasses {
+		return new DomainClasses().prepare(domainClasses, props);
+	}
+}

package/dist/kernel/helpers/domain-error.ts

@@ -0,0 +1,52 @@
+/**
+ * @description
+ * Represents a domain-level error thrown when a business rule or invariant is violated.
+ *
+ * Unlike generic `Error`, `DomainError` carries structured context about where and why
+ * the violation occurred, making it easier to handle, log, and surface meaningful
+ * feedback to callers.
+ *
+ * Use `DomainError` whenever a domain operation fails due to an invariant violation —
+ * for example, when `set().to()` receives an invalid value, or when a required domain
+ * rule is not satisfied.
+ *
+ * @example
+ * ```typescript
+ * throw new DomainError('Amount must be positive', {
+ *     field: 'amount',
+ *     context: 'Money',
+ * });
+ * ```
+ */
+export class DomainError extends Error {
+	public readonly field?: string;
+	public readonly context?: string;
+
+	/**
+	 * @description
+	 * Creates a new `DomainError` instance.
+	 *
+	 * @param message A human-readable description of the violation.
+	 * @param options Optional structured context about the violation.
+	 * @param options.field The property or field name that caused the error.
+	 * @param options.context The domain class or context name where the error originated.
+	 */
+	constructor(
+		message: string,
+		options?: { field?: string; context?: string; cause?: unknown },
+	) {
+		const formattedMessage = options?.context
+			? `[${options.context}] ${message}`
+			: message;
+
+		super(formattedMessage, { cause: options?.cause });
+		this.name = "DomainError";
+		this.field = options?.field;
+		this.context = options?.context;
+
+		// Maintains proper stack trace in V8 environments (Node.js, Bun, Chrome)
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, DomainError);
+		}
+	}
+}