drimion 0.1.0

package/dist/kernel/helpers/getters-setters.ts

@@ -0,0 +1,385 @@
+import { ID } from "../core/id";
+import utils, { type Utils } from "../libs/utils";
+import validator, { type Validator } from "../libs/validator";
+import type { UID } from "../types/uid.types";
+import type { AnyObject } from "../types/utils.types";
+import { DomainError } from "./domain-error";
+
+/**
+ * @description
+ * Discriminator indicating which domain primitive this instance belongs to.
+ * Used internally to apply different mutation behaviors for `ValueObject` vs `Entity`.
+ */
+export type ParentKind = "ValueObject" | "Entity";
+
+/**
+ * @description
+ * Configuration options for enabling or disabling getter and setter access
+ * on a domain object instance.
+ *
+ * Disabling getters or setters can be useful when enforcing strict encapsulation
+ * or building read-only / write-only domain primitives.
+ */
+export interface GettersSettersConfig {
+	/**
+	 * @description
+	 * When `true`, calling `get()` on this instance will throw a `DomainError`.
+	 * @default false
+	 */
+	disableGetters?: boolean;
+
+	/**
+	 * @description
+	 * When `true`, calling `set().to()` or `change()` on this instance will throw a `DomainError`.
+	 * @default false
+	 */
+	disableSetters?: boolean;
+}
+
+/**
+ * @description
+ * Base class providing typed getter, setter, and validation infrastructure
+ * for all domain primitives (`ValueObject` and `Entity`).
+ *
+ * `GettersAndSetters` is not intended to be instantiated directly. It is extended
+ * by `ValueObject` and `Entity`, which pass their `parentKind` to enable
+ * kind-specific behavior (e.g., auto-updating `updatedAt` on Entity mutations).
+ *
+ * Subclasses may override `validation()` to enforce per-key domain invariants
+ * that are checked automatically on every `set().to()` or `change()` call.
+ *
+ * @template Props The shape of the domain object's properties.
+ *
+ * @example
+ * ```typescript
+ * class Age extends ValueObject<{ value: number }> {
+ *     validation<Key extends keyof { value: number }>(
+ *         value: { value: number }[Key],
+ *         key: Key,
+ *     ): boolean {
+ *         if (key === 'value') return (value as number) > 0;
+ *         return true;
+ *     }
+ * }
+ * ```
+ */
+export abstract class GettersAndSetters<Props> {
+	protected static readonly util: Utils = utils;
+	protected static readonly validator: Validator = validator;
+	protected readonly util: Utils = utils;
+	protected readonly validator: Validator = validator;
+	protected parentKind: ParentKind = "ValueObject";
+	protected config: GettersSettersConfig = {
+		disableGetters: false,
+		disableSetters: false,
+	};
+
+	constructor(
+		protected props: Props,
+		parentKind: ParentKind,
+		config?: GettersSettersConfig,
+	) {
+		this.parentKind = parentKind;
+		this.config.disableGetters = !!config?.disableGetters;
+		this.config.disableSetters = !!config?.disableSetters;
+	}
+
+	/**
+	 * @description
+	 * Handles the special case of assigning a new identity (`id`) to an Entity.
+	 *
+	 * Accepts a string, number, or existing `UID` instance. In all cases, the
+	 * internal `_id` field and `props.id` are updated in sync, and `updatedAt`
+	 * is refreshed to reflect the mutation.
+	 *
+	 * This method is only called when `key === 'id'` and `parentKind === 'Entity'`.
+	 *
+	 * @param value The new identity value — a string, number, or `UID` instance.
+	 */
+	private applyEntityId<Key extends keyof Props>(value: Props[Key]): void {
+		const self = this as unknown as AnyObject;
+
+		if (this.validator.isString(value) || this.validator.isNumber(value)) {
+			const newId = ID.create(value as string | number);
+			self._id = newId;
+			(this.props as AnyObject).id = newId.value();
+			this.touchUpdatedAt();
+			return;
+		}
+
+		if (this.validator.isID(value)) {
+			self._id = value;
+			(this.props as AnyObject).id = (value as unknown as UID).value();
+			this.touchUpdatedAt();
+		}
+	}
+
+	/**
+	 * @description
+	 * Applies a validated value to the specified property key.
+	 *
+	 * Delegates to `applyEntityId()` when the key is `'id'` and the parent
+	 * is an `Entity`. Otherwise, directly assigns the value and, for entities,
+	 * updates the `updatedAt` timestamp via `touchUpdatedAt()`.
+	 *
+	 * @param key The property key to assign to.
+	 * @param value The validated value to apply.
+	 */
+	private applyValue<Key extends keyof Props>(
+		key: Key,
+		value: Props[Key],
+	): void {
+		if (key === "id" && this.parentKind === "Entity") {
+			this.applyEntityId(value);
+			return;
+		}
+
+		(this.props as AnyObject)[key as string] = value;
+
+		if (this.parentKind === "Entity") {
+			this.touchUpdatedAt();
+		}
+	}
+
+	/**
+	 * @description
+	 * Asserts that setters are currently enabled on this instance.
+	 * Throws a `DomainError` if `disableSetters` is `true` in the config.
+	 *
+	 * @param key The property key being targeted, used to build the error message.
+	 * @throws {DomainError} If setters are disabled.
+	 */
+	private assertSettersEnabled<Key extends keyof Props>(key: Key): void {
+		if (this.config.disableSetters) {
+			const name = Reflect.getPrototypeOf(this)?.constructor.name;
+			throw new DomainError(`Set: setters are disabled for "${String(key)}".`, {
+				context: name,
+				field: String(key),
+			});
+		}
+	}
+
+	/**
+	 * @description
+	 * Runs validation for a property assignment, applying both the external
+	 * validation function (if provided) and the instance's `validation()` hook.
+	 *
+	 * External validation is checked first. If it returns `false`, a `DomainError`
+	 * is thrown immediately without calling `validation()`.
+	 *
+	 * @param key The property key being validated.
+	 * @param value The value being assigned.
+	 * @param externalValidation An optional caller-provided validation function.
+	 * @throws {DomainError} If either validation step fails.
+	 */
+	private assertValid<Key extends keyof Props>(
+		key: Key,
+		value: Props[Key],
+		externalValidation?: (value: Props[Key]) => boolean,
+	): void {
+		const name = Reflect.getPrototypeOf(this)?.constructor.name;
+
+		if (
+			typeof externalValidation === "function" &&
+			!externalValidation(value)
+		) {
+			throw new DomainError(`Set: validation failed for "${String(key)}".`, {
+				context: name,
+				field: String(key),
+			});
+		}
+
+		if (!this.validation(value, key)) {
+			throw new DomainError(`Set: invariant violated for "${String(key)}".`, {
+				context: name,
+				field: String(key),
+			});
+		}
+	}
+
+	/**
+	 * @description
+	 * Direct setter — validates then assigns a value to the specified property key.
+	 * Equivalent to `set(key).to(value, validation)` but without the fluent chain.
+	 * Throws a `DomainError` if setters are disabled or validation fails.
+	 *
+	 * @param key The property key to change.
+	 * @param value The new value.
+	 * @param validation Optional validation function.
+	 * @returns `true` if successfully changed.
+	 *
+	 * @throws {DomainError} If setters are disabled or validation fails.
+	 *
+	 * @example
+	 * ```typescript
+	 * entity.change('age', 25, (age) => age > 0);
+	 * ```
+	 */
+	public change<Key extends keyof Props>(
+		key: Key,
+		value: Props[Key],
+		validation?: (value: Props[Key]) => boolean,
+	): boolean {
+		this.assertSettersEnabled(key);
+		this.assertValid(key, value, validation);
+		this.applyValue(key, value);
+		return true;
+	}
+
+	/**
+	 * @description
+	 * Retrieves the value of a specified property key.
+	 * Throws a `DomainError` if getters are disabled on this instance.
+	 *
+	 * For primitive props (string, number, boolean), use the key `'value'`
+	 * to retrieve the raw value directly.
+	 *
+	 * @param key The property key to retrieve.
+	 * @returns The readonly value of the specified key.
+	 *
+	 * @throws {DomainError} If getters are disabled.
+	 *
+	 * @example
+	 * ```typescript
+	 * const age = person.get('age'); // 30
+	 * const raw = stringVo.get('value'); // 'hello'
+	 * ```
+	 */
+	public get<Key extends keyof Props>(key: Key): Readonly<Props[Key]>;
+	public get(
+		key: "value",
+	): Readonly<"value" extends keyof Props ? Props["value"] : Props>;
+	/** biome-ignore lint/suspicious/noExplicitAny: TS cannot correlate overload branches with runtime narrowing. */
+	public get(key: any): any {
+		if (this.config.disableGetters) {
+			const name = Reflect.getPrototypeOf(this)?.constructor.name;
+			throw new DomainError(`Get: getters are disabled for "${String(key)}".`, {
+				context: name,
+				field: String(key),
+			});
+		}
+
+		if (key === "value") {
+			if (
+				this.props &&
+				typeof this.props === "object" &&
+				"value" in (this.props as AnyObject)
+			) {
+				return (this.props as AnyObject).value;
+			}
+
+			if (
+				this.validator.isBoolean(this.props) ||
+				this.validator.isNumber(this.props) ||
+				this.validator.isString(this.props) ||
+				this.validator.isDate(this.props)
+			) {
+				return this.props;
+			}
+
+			if (this.validator.isSymbol(this.props)) {
+				return (this.props as symbol).description;
+			}
+
+			if (this.validator.isID(this.props)) {
+				return (this.props as UID).value();
+			}
+
+			if (this.validator.isArray(this.props)) {
+				return this.props;
+			}
+		}
+
+		const obj = this.props as AnyObject;
+
+		if (!(key in obj)) {
+			const name = Reflect.getPrototypeOf(this)?.constructor.name;
+			throw new DomainError(`Get: key "${String(key)}" does not exist.`, {
+				context: name,
+				field: String(key),
+			});
+		}
+
+		return obj[key] ?? null;
+	}
+
+	/**
+	 * @description
+	 * Returns the raw properties of the domain instance as a frozen, read-only object.
+	 *
+	 * @returns A frozen copy of the internal props.
+	 */
+	public getRaw(): Readonly<Props> {
+		return Object.freeze(this.props);
+	}
+
+	/**
+	 * @description
+	 * Fluent setter — validates then assigns a value to the specified property key.
+	 * Throws a `DomainError` if setters are disabled or validation fails.
+	 *
+	 * @param key The property key to set.
+	 * @returns An object with a `to` method to complete the assignment.
+	 *
+	 * @example
+	 * ```typescript
+	 * entity.set('age').to(30, (age) => age > 0);
+	 * ```
+	 */
+	public set<Key extends keyof Props>(
+		key: Key,
+	): {
+		to: (
+			value: Props[Key],
+			validation?: (value: Props[Key]) => boolean,
+		) => boolean;
+	} {
+		return {
+			to: (
+				value: Props[Key],
+				validation?: (value: Props[Key]) => boolean,
+			): boolean => {
+				this.assertSettersEnabled(key);
+				this.assertValid(key, value, validation);
+				this.applyValue(key, value);
+				return true;
+			},
+		};
+	}
+
+	/**
+	 * @description
+	 * Updates the `updatedAt` field on `props` to the current timestamp.
+	 *
+	 * Called automatically after any successful mutation on an `Entity` instance
+	 * to reflect that the domain object's state has changed.
+	 */
+	private touchUpdatedAt(): void {
+		(this.props as AnyObject).updatedAt = new Date();
+	}
+
+	/**
+	 * @description
+	 * Hook for subclasses to define per-key validation rules.
+	 * Called automatically by `set().to()` and `change()` before applying a value.
+	 * Override this in your domain class to enforce invariants.
+	 *
+	 * @param _value The value to validate.
+	 * @param _key The property key being validated.
+	 * @returns `true` if the value is valid; `false` otherwise.
+	 *
+	 * @example
+	 * ```typescript
+	 * validation<Key extends keyof Props>(value: Props[Key], key: Key): boolean {
+	 *     if (key === 'age') return (value as number) > 0;
+	 *     return true;
+	 * }
+	 * ```
+	 */
+	public validation<Key extends keyof Props>(
+		_value: Props[Key],
+		_key: Key,
+	): boolean {
+		return true;
+	}
+}

package/dist/kernel/helpers/index.ts

@@ -0,0 +1,7 @@
+export type { EntityAutoMapperPayload } from "./auto-mapper";
+export { AutoMapper } from "./auto-mapper";
+export type { CreateManyResult } from "./domain-classes";
+export { DomainClasses } from "./domain-classes";
+export { DomainError } from "./domain-error";
+export type { GettersSettersConfig, ParentKind } from "./getters-setters";
+export { GettersAndSetters } from "./getters-setters";

package/dist/kernel/index.ts

@@ -0,0 +1,73 @@
+// ── Core domain primitives ─────────────────────────────────────────────────
+export { Aggregate } from "./core/aggregate";
+export { Entity } from "./core/entity";
+export { ID, Id } from "./core/id";
+export { BaseRepository } from "./core/repository";
+export { ValueObject } from "./core/value-object";
+// ── Event system ───────────────────────────────────────────────────────────
+export type { WindowLike } from "./events/browser-event-manager";
+export { BrowserEventManager } from "./events/browser-event-manager";
+export { BaseDomainEvent } from "./events/domain-event";
+export { EventBus } from "./events/event-bus";
+export { EventContext } from "./events/event-context";
+export { BaseEventManager } from "./events/event-manager";
+export { ValidateEventName } from "./events/event-utils";
+export { ServerEventManager } from "./events/server-event-manager";
+// ── Helpers ────────────────────────────────────────────────────────────────
+export type { EntityAutoMapperPayload } from "./helpers/auto-mapper";
+export { AutoMapper } from "./helpers/auto-mapper";
+export type { CreateManyResult } from "./helpers/domain-classes";
+export { DomainClasses } from "./helpers/domain-classes";
+export { DomainError } from "./helpers/domain-error";
+export type {
+	GettersSettersConfig,
+	ParentKind,
+} from "./helpers/getters-setters";
+export { GettersAndSetters } from "./helpers/getters-setters";
+
+// ── Libs ───────────────────────────────────────────────────────────────────
+export { Iterator } from "./libs/iterator";
+export { Result } from "./libs/result";
+export { Utils } from "./libs/utils";
+export { Validator } from "./libs/validator";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+export type { Adapter, IAdapter } from "./types/adapter.types";
+export type { ICommand, IQuery, IUseCase } from "./types/command.types";
+export type {
+	AggregateConstructor,
+	EntityConstructor,
+	EntityProps,
+	IEntityProps,
+	IEntitySettings,
+} from "./types/entity.types";
+export type {
+	DomainEvent,
+	DomainEventPayload,
+	EventEntry,
+	IEventBus,
+} from "./types/event.types";
+export type { IIterator, IIteratorConfig } from "./types/iterator.types";
+export type {
+	IResult,
+	IResultExecuteFn,
+	IResultHook,
+	IResultObject,
+	IResultOption,
+} from "./types/result.types";
+export type { UID } from "./types/uid.types";
+export type {
+	AnyObject,
+	BuiltIns,
+	CalcOpt,
+	Primitive,
+	ReadonlyDeep,
+} from "./types/utils.types";
+export type {
+	IValueObjectSettings,
+	ValueObjectConstructor,
+} from "./types/value-object.types";
+
+// ── Utils ──────────────────────────────────────────────────────────────────
+export { DeepFreeze, StableStringify } from "./utils/object.utils";
+export { InvalidPropsType } from "./utils/type.utils";

package/dist/kernel/libs/crypto.ts

@@ -0,0 +1,33 @@
+import * as crypto from "node:crypto";
+
+const customCrypto = {
+	randomUUID: (): string => {
+		const hexChars = "0123456789abcdef";
+		let uuid = "";
+		for (let i = 0; i < 36; i++) {
+			if (i === 8 || i === 13 || i === 18 || i === 23) {
+				uuid += "-";
+			} else if (i === 14) {
+				uuid += "4";
+			} else if (i === 19) {
+				uuid += hexChars.charAt(Math.floor(Math.random() * 4) + 8);
+			} else {
+				uuid += hexChars.charAt(Math.floor(Math.random() * 16));
+			}
+		}
+		return uuid;
+	},
+};
+
+// Node.js
+if (typeof process !== "undefined" && crypto?.randomUUID) {
+	customCrypto.randomUUID = crypto.randomUUID;
+}
+// Browser
+else if (typeof globalThis !== "undefined" && globalThis.crypto?.randomUUID) {
+	customCrypto.randomUUID = globalThis.crypto.randomUUID.bind(
+		globalThis.crypto,
+	);
+}
+
+export const UUID = customCrypto.randomUUID;

package/dist/kernel/libs/index.ts

@@ -0,0 +1,5 @@
+export { UUID } from "./crypto";
+export { Iterator } from "./iterator";
+export { Result } from "./result";
+export { Utils } from "./utils";
+export { Validator } from "./validator";