drimion 0.1.0

package/dist/kernel/types/entity.types.ts

@@ -0,0 +1,60 @@
+import type { UID } from "./uid.types";
+
+/**
+ * @description
+ * Represents the static side (constructor + factory contract) of an `Aggregate` subclass.
+ *
+ * Mirrors `EntityConstructor` but scoped to `Aggregate` subclasses, enabling the same
+ * polymorphic `this`-typed factory pattern used by `Entity.create()` and `Entity.init()`.
+ *
+ * @template Props The shape of the aggregate's user-defined domain properties.
+ * @template T The concrete `Aggregate` subclass type.
+ */
+export type AggregateConstructor<Props extends object, T> = {
+	isValidProps(props: Props): boolean;
+	readonly name: string;
+	prototype: T;
+};
+
+/**
+ * @description
+ * Represents the static side (constructor + factory contract) of an `Entity` subclass.
+ *
+ * Used by `Entity.create()` and `Entity.init()` to enable the polymorphic
+ * `this`-typed factory pattern — calling `User.create(props)` infers `T = User`
+ * automatically without requiring subclasses to override the factory.
+ *
+ * @template Props The shape of the entity's user-defined domain properties.
+ * @template T The concrete `Entity` subclass type.
+ */
+export type EntityConstructor<Props extends object, T> = {
+	isValidProps(props: Props): boolean;
+	readonly name: string;
+	prototype: T;
+};
+
+/**
+ * @description
+ * Merges user-defined `Props` with the implicit Entity lifecycle fields.
+ */
+export type EntityProps<T extends object> = T & {
+	id?: string | number | UID<string>;
+	createdAt?: Date;
+	updatedAt?: Date;
+};
+
+/**
+ * @description
+ * Represents the base constraint for an entity's user-defined properties.
+ * Must be a plain object (no primitives, arrays, or class instances).
+ */
+export type IEntityProps = object;
+
+/**
+ * @description
+ * Configuration options for getter and setter behavior on an entity instance.
+ */
+export interface IEntitySettings {
+	disableGetters?: boolean;
+	disableSetters?: boolean;
+}

package/dist/kernel/types/event.types.ts

@@ -0,0 +1,129 @@
+/**
+ * @description
+ * Represents a domain event — an immutable record of something that happened
+ * within an aggregate boundary.
+ *
+ * Domain events are plain data. They carry no behaviour, no handlers, and no
+ * knowledge of how they will be consumed. The `type` field is the only
+ * required identifier; every other field provides tracing context.
+ *
+ * Naming convention: past-tense, `aggregate:fact` format.
+ * @example `'order:placed'`, `'user:registered'`, `'pokemon:caught'`
+ *
+ * @template TPayload The shape of the event-specific data.
+ */
+export interface DomainEvent<TPayload = unknown> {
+	/**
+	 * @description
+	 * The event type identifier. Use past-tense, colon-separated format:
+	 * `'<aggregate>:<fact>'` — e.g. `'order:placed'`, `'user:email-changed'`.
+	 */
+	readonly type: string;
+
+	/**
+	 * @description
+	 * The string value of the aggregate's `id` at the time the event was emitted.
+	 */
+	readonly aggregateId?: string;
+
+	/**
+	 * @description
+	 * The class name of the aggregate that emitted this event.
+	 * Useful for logging, filtering, and debugging across aggregate boundaries.
+	 *
+	 * @example `'Order'`, `'User'`, `'Pokemon'`
+	 */
+	readonly aggregateName?: string;
+
+	/**
+	 * @description
+	 * The timestamp at which this event was created inside the aggregate.
+	 * Reflects domain time, not infrastructure time.
+	 */
+	readonly occurredAt?: Date;
+
+	/**
+	 * @description
+	 * Event-specific data. Keep this flat and serializable — avoid class
+	 * instances, functions, or circular references so the event can be safely
+	 * transmitted across process boundaries.
+	 */
+	readonly payload?: TPayload;
+}
+
+/**
+ * @description
+ * Represents a generic browser / server event payload wrapper.
+ * Used internally by `BrowserEventManager` and `ServerEventManager`.
+ *
+ * @internal
+ */
+export type DomainEventPayload = { detail?: unknown[] };
+
+/**
+ * @description
+ * Stores a registered event name and its associated callback.
+ * Used internally by the built-in event managers.
+ *
+ * @internal
+ */
+export interface EventEntry {
+	eventName: string;
+	callback: (event: DomainEventPayload) => void | Promise<void>;
+}
+
+/**
+ * @description
+ * Subscriber callback type — receives a fully-typed `DomainEvent` and may
+ * return a `Promise` for async side effects.
+ */
+export type EventSubscriber<TPayload = unknown> = (
+	event: DomainEvent<TPayload>,
+) => void | Promise<void>;
+
+/**
+ * @description
+ * Contract for an application-level event bus.
+ *
+ * Implement this interface to integrate any pub-sub mechanism — an in-process
+ * `EventEmitter`, a Redis Streams adapter, BullMQ, NATS, or any other
+ * transport — with the domain event system produced by `Aggregate.pullEvents()`.
+ *
+ * The library ships with a `EventBus` implementation that works
+ * out-of-the-box in both Node.js and browser environments. Swap it for your
+ * own at the application layer without touching any domain code.
+ *
+ * @example
+ * ```typescript
+ * class RedisEventBus implements IEventBus {
+ *     async publish(event: DomainEvent): Promise<void> {
+ *         await redis.xadd(event.type, '*', 'data', JSON.stringify(event));
+ *     }
+ *     async publishAll(events: ReadonlyArray<DomainEvent>): Promise<void> {
+ *         for (const event of events) await this.publish(event);
+ *     }
+ * }
+ * ```
+ */
+export interface IEventBus {
+	/**
+	 * @description Publishes a single domain event.
+	 */
+	publish(event: DomainEvent): Promise<void>;
+
+	/**
+	 * @description
+	 * Publishes all domain events in the provided array.
+	 * Implementations should preserve order.
+	 */
+	publishAll(events: ReadonlyArray<DomainEvent>): Promise<void>;
+}
+
+/**
+ * @description
+ * Internal registry entry stored per event type.
+ */
+export interface SubscriberEntry {
+	type: string;
+	subscriber: EventSubscriber;
+}

package/dist/kernel/types/index.ts

@@ -0,0 +1,26 @@
+export type {
+	Adapter,
+	IAdapter,
+} from "./adapter.types";
+
+export type { ICommand, IQuery, IUseCase } from "./command.types";
+export type { IEntityProps, IEntitySettings } from "./entity.types";
+export type { IIterator, IIteratorConfig } from "./iterator.types";
+export type {
+	IResult,
+	IResultExecuteFn,
+	IResultHook,
+	IResultObject,
+	IResultOption,
+} from "./result.types";
+
+export type { UID } from "./uid.types";
+export type {
+	AnyObject,
+	BuiltIns,
+	CalcOpt,
+	Primitive,
+	ReadonlyDeep,
+} from "./utils.types";
+
+export type { IValueObjectSettings } from "./value-object.types";

package/dist/kernel/types/iterator.types.ts

@@ -0,0 +1,39 @@
+/**
+ * @description
+ * Defines the operations supported by an iterator for managing sequential traversal of items.
+ *
+ * @template T The type of items in the iterator.
+ */
+export interface IIterator<T> {
+	addToEnd(data: T): IIterator<T>;
+	add(data: T): IIterator<T>;
+	addToStart(data: T): IIterator<T>;
+	clear(): IIterator<T>;
+	clone(): IIterator<T>;
+	first(): T;
+	hasNext(): boolean;
+	hasPrev(): boolean;
+	isEmpty(): boolean;
+	last(): T;
+	next(): T;
+	prev(): T;
+	removeFirst(): IIterator<T>;
+	removeItem(item: T): void;
+	removeLast(): IIterator<T>;
+	toArray(): Array<T>;
+	toFirst(): IIterator<T>;
+	toLast(): IIterator<T>;
+	total(): number;
+}
+
+/**
+ * @description
+ * Configuration options for creating an iterator.
+ *
+ * @template T The type of items in the iterator.
+ */
+export interface IIteratorConfig<T> {
+	initialData?: Array<T>;
+	restartOnFinish?: boolean;
+	returnCurrentOnReversion?: boolean;
+}

package/dist/kernel/types/result.types.ts

@@ -0,0 +1,122 @@
+import type { ICommand } from "./command.types";
+import type { AnyObject } from "./utils.types";
+
+/**
+ * @description
+ * Represents the result of an operation, encapsulating its state, value, error, and metadata.
+ *
+ * @template T The type of the result's value.
+ * @template D The type of the result's error (default: string).
+ * @template M The type of the result's metadata (default: empty object).
+ */
+export interface IResult<T, D = string, M = AnyObject> {
+	/**
+	 * @description
+	 * Retrieves the error of the result. Returns null if the result represents success.
+	 *
+	 * @returns The result's error or null.
+	 */
+	error(): D;
+	/**
+	 * @description
+	 * Executes a command based on the result's state (success or failure).
+	 *
+	 * @template X The input type for the command.
+	 * @template Y The output type of the command.
+	 * @param command The command to execute.
+	 * @returns An object containing hooks for further execution.
+	 */
+	execute: <X, Y>(command: ICommand<X, Y>) => IResultExecuteFn<X, Y>;
+	/**
+	 * @description
+	 * Checks if the result represents a failure.
+	 *
+	 * @returns True if the result is a failure, false otherwise.
+	 */
+	isError(): boolean;
+	/**
+	 * @description
+	 * Checks if the result contains a null value.
+	 *
+	 * @returns True if the value is null, false otherwise.
+	 */
+	isNull(): boolean;
+	/**
+	 * @description
+	 * Checks if the result represents success.
+	 *
+	 * @returns True if the result is a success, false otherwise.
+	 */
+	isSuccess(): boolean;
+	/**
+	 * @description
+	 * Retrieves the metadata associated with the result.
+	 *
+	 * @returns The result's metadata.
+	 */
+	metaData(): M;
+	/**
+	 * @description
+	 * Converts the result into an object representing its current state.
+	 *
+	 * @returns An object containing the result's value, error, and metadata.
+	 */
+	toObject(): IResultObject<T, D, M>;
+	/**
+	 * @description
+	 * Retrieves the value of the result. Returns null if the result represents a failure.
+	 *
+	 * @returns The result's value or null.
+	 */
+	value(): T;
+}
+
+/**
+ * @description
+ * Represents the possible states of a result: success (`success`) or failure (`error`).
+ */
+export type IResultOption = "error" | "success";
+
+/**
+ * @description
+ * Hook for handling specific result states during execution.
+ *
+ * @template Y The type of the hook's output.
+ */
+export interface IResultHook<Y> {
+	/**
+	 * @description
+	 * Executes a function based on the result state.
+	 *
+	 * @param option The result state to handle (`success` or `error`).
+	 * @returns The result of the function execution, if applicable.
+	 */
+	on(option: IResultOption): Promise<IResult<Y, string>> | undefined;
+}
+
+/**
+ * @description
+ * Extends `IResultHook` with support for data input.
+ *
+ * @template X The input type for the hook.
+ * @template Y The output type for the hook.
+ */
+export interface IResultExecuteFn<X, Y> extends IResultHook<Y> {
+	withData(data: X): IResultHook<Y>;
+}
+
+/**
+ * @description
+ * Represents the state of a result, including its value, error, and metadata.
+ *
+ * @template T The type of the result's value.
+ * @template D The type of the result's error.
+ * @template M The type of the result's metadata.
+ */
+export interface IResultObject<T, D, M> {
+	data: T | null;
+	error: D | null;
+	isError: boolean;
+	isSuccess: boolean;
+	metaData: M;
+}

package/dist/kernel/types/uid.types.ts

@@ -0,0 +1,18 @@
+/**
+ * @description
+ * Represents a unique identifier (UID) with methods for manipulation and comparison.
+ *
+ * @template T The type of the UID's value (default: string).
+ */
+export interface UID<T = string> {
+	clone(): UID<T>;
+	cloneAsNew(): UID<string>;
+	createdAt(): Date;
+	deepEqual(id: UID<string>): boolean;
+	equal(id: UID<string>): boolean;
+	isEqual(id: UID<string>): boolean;
+	isNew(): boolean;
+	isShort(): boolean;
+	value(): string;
+	toShort(): UID<string>;
+}

package/dist/kernel/types/utils.types.ts

@@ -0,0 +1,120 @@
+/**
+ * @description
+ * Represents an unknown object.
+ */
+export type AnyObject = Record<string, unknown>;
+
+/**
+ * @description
+ * Built-in types that are excluded from recursive transformations.
+ */
+export type BuiltIns = Primitive | Date | RegExp;
+
+/**
+ * @description
+ * Options for calculations, such as specifying precision.
+ */
+export type CalcOpt = { fractionDigits: number };
+
+/**
+ * @description
+ * Utility type to determine if a function type has multiple call signatures.
+ *
+ * Used to differentiate simple functions from overloaded functions.
+ *
+ * @template T The function type to analyze.
+ */
+type HasMultipleCallSignatures<
+	T extends (...arguments_: unknown[]) => unknown,
+> = T extends {
+	(...arguments_: infer A): unknown;
+	(...arguments_: infer B): unknown;
+}
+	? B extends A
+		? A extends B
+			? false // Single call signature.
+			: true // Multiple call signatures.
+		: true
+	: false;
+
+/**
+ * @description
+ * Primitive types that are not recursively transformed.
+ */
+export type Primitive =
+	| null
+	| undefined
+	| string
+	| number
+	| boolean
+	| symbol
+	| bigint;
+
+/**
+ * @description
+ * A utility type to recursively make all properties of a type `T` deeply readonly.
+ *
+ * Handles built-in types, objects, arrays, tuples, sets, and maps.
+ * Special cases include skipping class constructors and functions.
+ *
+ * @template T The type to be made deeply readonly.
+ */
+export type ReadonlyDeep<T> = T extends BuiltIns
+	? T // Built-in types remain unchanged.
+	: T extends new (
+				...arguments_: unknown[]
+			) => unknown
+		? T // Skip class constructors to preserve mutability.
+		: T extends (...arguments_: unknown[]) => unknown
+			? AnyObject extends ReadonlyObjectDeep<T>
+				? T // Skip plain functions with no call signatures.
+				: HasMultipleCallSignatures<T> extends true
+					? T // Preserve functions with multiple call signatures.
+					: ((...arguments_: Parameters<T>) => ReturnType<T>) &
+							ReadonlyObjectDeep<T>
+			: T extends Readonly<ReadonlyMap<infer KeyType, infer ValueType>>
+				? ReadonlyMapDeep<KeyType, ValueType> // Recursively make map keys and values readonly.
+				: T extends Readonly<ReadonlySet<infer ItemType>>
+					? ReadonlySetDeep<ItemType> // Recursively make set items readonly.
+					: T extends readonly [] | readonly [...never[]]
+						? readonly [] // Handle empty or unspecific tuples as empty arrays.
+						: T extends readonly [infer U, ...infer V]
+							? readonly [ReadonlyDeep<U>, ...ReadonlyDeep<V>] // Handle tuples with specific types.
+							: T extends readonly [...infer U, infer V]
+								? readonly [...ReadonlyDeep<U>, ReadonlyDeep<V>] // Handle generic tuples.
+								: T extends ReadonlyArray<infer ItemType>
+									? ReadonlyArray<ReadonlyDeep<ItemType>> // Recursively make array items readonly.
+									: T extends object
+										? ReadonlyObjectDeep<T> // Recursively make object properties readonly.
+										: unknown; // For unknown types, no transformation is applied.
+
+/**
+ * @description
+ * Makes all key-value pairs of a `ReadonlyMap` deeply readonly.
+ *
+ * @template KeyType Type of the keys in the map.
+ * @template ValueType Type of the values in the map.
+ */
+type ReadonlyMapDeep<KeyType, ValueType> = {} & Readonly<
+	ReadonlyMap<ReadonlyDeep<KeyType>, ReadonlyDeep<ValueType>>
+>;
+
+/**
+ * @description
+ * Makes all properties of an object type deeply readonly.
+ *
+ * @template ObjectType The type of the object to be made deeply readonly.
+ */
+type ReadonlyObjectDeep<ObjectType extends object> = {
+	readonly [KeyType in keyof ObjectType]: ReadonlyDeep<ObjectType[KeyType]>;
+};
+
+/**
+ * @description
+ * Makes all elements of a `ReadonlySet` deeply readonly.
+ *
+ * @template ItemType Type of the items in the set.
+ */
+type ReadonlySetDeep<ItemType> = {} & Readonly<
+	ReadonlySet<ReadonlyDeep<ItemType>>
+>;

package/dist/kernel/types/value-object.types.ts

@@ -0,0 +1,20 @@
+/**
+ * @description
+ * Represents the static side (constructor + factory contract) of a `ValueObject` subclass.
+ *
+ * @template Props The shape of the value object's properties.
+ * @template T The concrete `ValueObject` subclass type.
+ */
+export type ValueObjectConstructor<Props, T> = {
+	isValidProps(props: Props): boolean;
+	readonly name: string;
+	prototype: T;
+};
+
+/**
+ * @description
+ * Configuration for value object settings.
+ */
+export interface IValueObjectSettings {
+	disableGetters?: boolean;
+}

package/dist/kernel/utils/date.utils.ts

@@ -0,0 +1,111 @@
+/** Supported time units for operations like incrementing or decrementing time. */
+export type Unit = "minute" | "hour" | "day" | "week" | "month" | "year";
+
+/** Milliseconds in common time units. */
+export const ONE_MINUTE = 60000;
+export const ONE_HOUR = ONE_MINUTE * 60;
+export const ONE_DAY = ONE_HOUR * 24;
+export const ONE_WEEK = ONE_DAY * 7;
+export const ONE_MONTH = ONE_DAY * 30;
+export const ONE_YEAR = ONE_DAY * 365;
+
+/**
+ * @description Decreases a given date by a specified amount of time based on the unit provided.
+ *
+ * @param date The starting date from which the time will be decremented.
+ * @param value The number of units to decrement. If not a valid number, the original timestamp is returned.
+ * @param unit The unit of time to decrement. Possible values are:
+ * - `'day'`: Decrement by days.
+ * - `'hour'`: Decrement by hours.
+ * - `'minute'`: Decrement by minutes.
+ * - `'month'`: Decrement by months.
+ * - `'week'`: Decrement by weeks.
+ * - `'year'`: Decrement by years.
+ *
+ * @returns The decremented timestamp as a number. If the input date is invalid, the current timestamp is returned.
+ *
+ * @example
+ * ```typescript
+ * const now = new Date();
+ * const decrementedTime = DecrementTime(now, 2, 'day'); // Subtracts 2 days from the current date.
+ * console.log(new Date(decrementedTime)); // Logs the decremented date.
+ * ```
+ */
+export const DecrementTime = (
+	date: Date,
+	value: number,
+	unit: Unit,
+): number => {
+	if (!(date instanceof Date)) return Date.now();
+
+	const time = date.getTime();
+	if (typeof value !== "number") return time;
+
+	switch (unit) {
+		case "day":
+			return time - ONE_DAY * value;
+		case "hour":
+			return time - ONE_HOUR * value;
+		case "minute":
+			return time - ONE_MINUTE * value;
+		case "month":
+			return time - ONE_MONTH * value;
+		case "week":
+			return time - ONE_WEEK * value;
+		case "year":
+			return time - ONE_YEAR * value;
+		default:
+			return time;
+	}
+};
+
+/**
+ * @description
+ * Increments a given date by a specified amount of time based on the unit provided.
+ *
+ * @param date The starting date to increment.
+ * @param value The number of units to increment. If not a valid number, the original timestamp is returned.
+ * @param unit The unit of time to increment. Possible values are:
+ * - `'day'`: Increment by days.
+ * - `'hour'`: Increment by hours.
+ * - `'minute'`: Increment by minutes.
+ * - `'month'`: Increment by months.
+ * - `'week'`: Increment by weeks.
+ * - `'year'`: Increment by years.
+ *
+ * @returns The incremented timestamp as a number. If the input date is invalid, the current timestamp is returned.
+ *
+ * @example
+ * ```typescript
+ * const now = new Date();
+ * const incrementedTime = IncrementTime(now, 3, 'day'); // Adds 3 days to the current date.
+ * console.log(new Date(incrementedTime)); // Logs the incremented date.
+ * ```
+ */
+export const IncrementTime = (
+	date: Date,
+	value: number,
+	unit: Unit,
+): number => {
+	if (!(date instanceof Date)) return Date.now();
+
+	const time = date.getTime();
+	if (typeof value !== "number") return time;
+
+	switch (unit) {
+		case "day":
+			return ONE_DAY * value + time;
+		case "hour":
+			return ONE_HOUR * value + time;
+		case "minute":
+			return ONE_MINUTE * value + time;
+		case "month":
+			return ONE_MONTH * value + time;
+		case "week":
+			return ONE_WEEK * value + time;
+		case "year":
+			return ONE_YEAR * value + time;
+		default:
+			return time;
+	}
+};

package/dist/kernel/utils/index.ts

@@ -0,0 +1,32 @@
+export {
+	DecrementTime,
+	IncrementTime,
+	ONE_DAY,
+	ONE_HOUR,
+	ONE_MINUTE,
+	ONE_MONTH,
+	ONE_WEEK,
+	ONE_YEAR,
+} from "./date.utils";
+
+export {
+	Divide,
+	EnsureNumber,
+	Float,
+	IsNaN,
+	Multiply,
+	Subtract,
+	Sum,
+	ToDecimal,
+	ToLong,
+	ToPrecision,
+} from "./number.utils";
+
+export { DeepFreeze, StableStringify } from "./object.utils";
+
+export {
+	RemoveChars,
+	RemoveSpaces,
+	ReplaceChars,
+	Stringify,
+} from "./string.utils";