drimion 0.1.0

package/dist/kernel/core/id.ts

@@ -0,0 +1,207 @@
+import { UUID } from "../libs/crypto";
+import validator from "../libs/validator";
+import type { UID } from "../types/uid.types";
+
+/**
+ * @description
+ * Represents a unique identifier for Entities or Aggregates, providing methods
+ * to generate and manipulate ID values, including the ability to create new IDs, convert them
+ * to a shorter format, clone them, and check for equality.
+ */
+export class ID implements UID<string | number> {
+	protected readonly __kind = "ID" as const;
+
+	readonly #maxSize: number = 16;
+	private _isNew: boolean;
+	private _value: string;
+	#createdAt: Date;
+
+	private constructor(id?: string | number) {
+		this.#createdAt = new Date();
+
+		if (typeof id === "undefined") {
+			const uuid = UUID();
+			this._value = uuid;
+			this._isNew = true;
+			return;
+		}
+
+		if (!validator.isString(id) && !validator.isNumber(id)) {
+			throw new TypeError("ID must be a string or number");
+		}
+
+		this._value = String(id);
+		this._isNew = false;
+	}
+
+	/**
+	 * @description
+	 * Creates a new `ID` instance. If no `id` value is provided, a new
+	 * UUID is generated. If an `id` is provided, that value is used directly.
+	 *
+	 * @param id Optional value to initialize the ID with. If not provided, a new UUID is created.
+	 * @returns A `UID` instance.
+	 */
+	public static create(id?: string | number): UID<string> {
+		return new ID(id) as unknown as UID<string>;
+	}
+
+	/**
+	 * @description
+	 * Creates a clone of the current `UID` instance with the same value
+	 * and properties, but without marking it as new.
+	 *
+	 * @returns A cloned `UID` instance identical to the current one.
+	 */
+	public clone(): UID<string | number> {
+		return new ID(this._value) as unknown as UID<string | number>;
+	}
+
+	/**
+	 * @description
+	 * Creates a new `UID` instance cloned from the current one, but marks
+	 * the new clone as a new ID.
+	 *
+	 * @returns A cloned `UID` instance that is considered new.
+	 */
+	public cloneAsNew(): UID<string> {
+		const newUUID = new ID(this._value);
+		newUUID.setAsNew();
+		return newUUID;
+	}
+
+	/**
+	 * @description
+	 * Retrieves the creation date of this `ID` instance.
+	 *
+	 * @returns The `Date` object representing when this ID was created or last modified.
+	 */
+	public createdAt(): Date {
+		return this.#createdAt;
+	}
+
+	/**
+	 * @description
+	 * Performs a deep comparison by serializing both IDs and checking if
+	 * the JSON representation is identical.
+	 *
+	 * @param id Another `UID` to compare to.
+	 * @returns `true` if both IDs are deeply equal; otherwise `false`.
+	 */
+	public deepEqual(id: UID<unknown>): boolean {
+		const A = JSON.stringify(this);
+		const B = JSON.stringify(id);
+		return A === B;
+	}
+
+	/**
+	 * @description
+	 * Compares the current ID against another `UID` instance by value.
+	 *
+	 * @param id Another `UID` to compare to.
+	 * @returns `true` if both IDs share the same value type and string value, otherwise `false`.
+	 */
+	public equal(id: UID<unknown>): boolean {
+		return (
+			typeof this._value === typeof id?.value() &&
+			(this._value as unknown) === id?.value()
+		);
+	}
+
+	/**
+	 * @description
+	 * Alias for `equal`. Compares the current ID against another `UID` instance by value.
+	 *
+	 * @param id Another `UID` to compare to.
+	 * @returns `true` if both IDs share the same value, otherwise `false`.
+	 */
+	public isEqual(id: UID<unknown>): boolean {
+		return this.equal(id);
+	}
+
+	/**
+	 * @description
+	 * Indicates whether this `ID` instance was created as a new,
+	 * previously uninitialized ID (no value passed to `create()`), or if it was
+	 * initialized from a provided value.
+	 *
+	 * @returns `true` if the ID is new; otherwise, `false`.
+	 */
+	public isNew(): boolean {
+		return this._isNew;
+	}
+
+	/**
+	 * @description
+	 * Checks if the current ID is short (16 bytes).
+	 *
+	 * @returns `true` if the ID is 16 bytes long, `false` otherwise.
+	 */
+	public isShort(): boolean {
+		return this._value.length === this.#maxSize;
+	}
+
+	/**
+	 * @description
+	 * Marks the current ID as new.
+	 */
+	private setAsNew(): void {
+		this._isNew = true;
+	}
+
+	/**
+	 * @description
+	 * Creates a new short (16-byte) ID. If no `id` value is provided,
+	 * a new UUID is generated and then shortened.
+	 *
+	 * @param id An optional string or number to use as the base value.
+	 * @returns A `UID` instance with a short, 16-byte value.
+	 */
+	public static short(id?: string | number): UID<string> {
+		const _id = new ID(id);
+		if (typeof id === "undefined") _id.setAsNew();
+		_id.toShort();
+		return _id;
+	}
+
+	/**
+	 * @description
+	 * Convert the current ID value into a shortened, 16-byte version.
+	 *
+	 * If the current ID value is shorter than 16 bytes, a UUID is prepended to ensure
+	 * sufficient length.
+	 *
+	 * @returns An updated `ID` instance with a short, 16-byte value.
+	 */
+	public toShort(): UID<string> {
+		let short = "";
+		let longValue = this._value;
+
+		if (longValue.length < this.#maxSize) {
+			longValue = UUID() + longValue;
+		}
+
+		longValue = longValue.toUpperCase().replace(/-/g, "");
+		const chars = longValue.split("");
+
+		while (short.length < this.#maxSize) {
+			const lastChar = chars.pop();
+			short = lastChar + short;
+		}
+		this.#createdAt = new Date();
+		this._value = short;
+		return this as unknown as UID<string>;
+	}
+
+	/**
+	 * @description
+	 * Retrieves the current ID value.
+	 *
+	 * @returns The ID value as a string.
+	 */
+	public value(): string {
+		return this._value;
+	}
+}
+
+export const Id = ID.create;

package/dist/kernel/core/index.ts

@@ -0,0 +1,5 @@
+export { Aggregate } from "./aggregate";
+export { Entity } from "./entity";
+export { ID, Id } from "./id";
+export { BaseRepository } from "./repository";
+export { ValueObject } from "./value-object";

package/dist/kernel/core/repository.ts

@@ -0,0 +1,81 @@
+import type { Entity } from "../core/entity";
+import type { IEntityProps } from "../types/entity.types";
+import type { IResult } from "../types/result.types";
+import type { UID } from "../types/uid.types";
+
+/**
+ * @description
+ * Abstract base class defining the standard contract for a domain repository.
+ *
+ * A repository abstracts the persistence layer, allowing domain code to remain
+ * ignorant of storage details. Each aggregate root should have its own repository
+ * implementation.
+ *
+ * Only the methods defined here are guaranteed by the contract. Implementations
+ * may expose additional query methods specific to their aggregate.
+ *
+ * @template T The entity or aggregate type managed by this repository.
+ * @template ID The type of the entity's identifier. Defaults to `string`.
+ *
+ * @example
+ * ```typescript
+ * class UserRepository extends BaseRepository<User> {
+ *     async findById(id: string): Promise<IResult<User, string>> {
+ *         const row = await db.users.findOne({ id });
+ *         if (!row) return Result.error('User not found');
+ *         return User.create(row);
+ *     }
+ *
+ *     async save(user: User): Promise<IResult<void, string>> {
+ *         await db.users.upsert(user.toObject());
+ *         return Result.success();
+ *     }
+ *
+ *     async delete(id: string): Promise<IResult<void, string>> {
+ *         await db.users.delete({ id });
+ *         return Result.success();
+ *     }
+ *
+ *     async exists(id: string): Promise<boolean> {
+ *         return db.users.exists({ id });
+ *     }
+ * }
+ * ```
+ */
+export abstract class BaseRepository<T extends Entity<IEntityProps>, ID = UID> {
+	/**
+	 * @description
+	 * Finds an entity by its unique identifier.
+	 *
+	 * @param id The entity's unique identifier.
+	 * @returns A `Result` containing the entity if found, or an error if not.
+	 */
+	abstract findById(id: ID): Promise<IResult<T, string>>;
+
+	/**
+	 * @description
+	 * Persists an entity — either inserting or updating as appropriate.
+	 *
+	 * @param entity The entity instance to save.
+	 * @returns A `Result` indicating success or failure.
+	 */
+	abstract save(entity: T): Promise<IResult<void, string>>;
+
+	/**
+	 * @description
+	 * Removes an entity by its unique identifier.
+	 *
+	 * @param id The unique identifier of the entity to delete.
+	 * @returns A `Result` indicating success or failure.
+	 */
+	abstract delete(id: ID): Promise<IResult<void, string>>;
+
+	/**
+	 * @description
+	 * Checks whether an entity with the given identifier exists in the store.
+	 *
+	 * @param id The unique identifier to check.
+	 * @returns `true` if the entity exists; `false` otherwise.
+	 */
+	abstract exists(id: ID): Promise<boolean>;
+}

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

@@ -0,0 +1,309 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: TS cannot model private constructors with generic static factories. */
+/** biome-ignore-all lint/complexity/noThisInStatic: Required for polymorphic `this` in base factory (DDD pattern). */
+
+import { AutoMapper } from "../helpers/auto-mapper";
+import { DomainError } from "../helpers/domain-error";
+import { GettersAndSetters } from "../helpers/getters-setters";
+import { Result } from "../libs/result";
+import type { Adapter, IAdapter } from "../types/adapter.types";
+import type { IResult } from "../types/result.types";
+import type { UID } from "../types/uid.types";
+import type { AnyObject } from "../types/utils.types";
+import type {
+	IValueObjectSettings,
+	ValueObjectConstructor,
+} from "../types/value-object.types";
+import { DeepFreeze, StableStringify } from "../utils/object.utils";
+
+/**
+ * @description
+ * Represents a domain object characterized entirely by its properties rather than
+ * a unique identifier. Two value objects with identical properties are considered equal.
+ *
+ * Value objects are immutable by design — mutations return new instances rather than
+ * modifying the existing one. They encapsulate domain validation logic, ensuring that
+ * only valid states can be represented.
+ *
+ * Extend this class to define your own value objects with custom business rules:
+ * - Override `isValidProps()` to define what constitutes a valid state.
+ * - Override `validation()` (inherited) to enforce per-key invariants on `set().to()`.
+ * - Use `create()` as the sole public factory — keep constructors `private`.
+ * - Use `init()` when you need a throwing factory (e.g., in seeding or tests).
+ *
+ * @template Props The shape of the value object's properties.
+ *
+ * @example
+ * ```typescript
+ * interface MoneyProps { amount: number }
+ *
+ * class Money extends ValueObject<MoneyProps> {
+ *     private constructor(props: MoneyProps) { super(props); }
+ *
+ *     public static isValidProps({ amount }: MoneyProps): boolean {
+ *         return amount >= 0;
+ *     }
+ *
+ *     public static create(amount: number): IResult<Money> {
+ *         if (!this.isValidProps({ amount })) return Result.error('Amount must be positive');
+ *         return Result.success(new Money({ amount }));
+ *     }
+ * }
+ * ```
+ */
+export abstract class ValueObject<Props> extends GettersAndSetters<Props> {
+	/**
+	 * @description
+	 * Marker used internally by `Validator` to identify this instance as a `ValueObject`
+	 * without requiring a direct `instanceof` check (avoiding circular imports).
+	 *
+	 * @internal
+	 */
+	protected readonly __kind = "ValueObject" as const;
+	private readonly autoMapper: AutoMapper;
+
+	/**
+	 * @description
+	 * Initializes a new `ValueObject` instance with the provided props and optional config.
+	 *
+	 * @param props The properties that define this value object's state.
+	 * @param config Optional settings to disable getters or setters.
+	 */
+	constructor(props: Props, config?: IValueObjectSettings) {
+		super(props, "ValueObject", { ...config, disableSetters: true });
+		this.autoMapper = new AutoMapper();
+	}
+
+	/**
+	 * @description
+	 * Creates a deep clone of this value object, optionally overriding some properties.
+	 *
+	 * For object-based props, a shallow merge is performed before cloning — the result
+	 * is always a new instance of the same subclass, not the base `ValueObject`.
+	 *
+	 * @param props Optional partial properties to override in the cloned instance.
+	 * @returns A new instance of the same `ValueObject` subclass with the merged props.
+	 *
+	 * @example
+	 * ```typescript
+	 * const discounted = price.clone({ amount: price.get('amount') * 0.9 });
+	 * ```
+	 */
+	public clone(props?: Props extends object ? Partial<Props> : never): this {
+		const proto = Reflect.getPrototypeOf(this);
+		const ctor = proto?.constructor ?? this.constructor;
+		if (
+			typeof this.props === "object" &&
+			!(this.props instanceof Date) &&
+			!Array.isArray(this.props)
+		) {
+			const merged = props ? { ...this.props, ...props } : { ...this.props };
+			return Reflect.construct(ctor, [merged, this.config]);
+		}
+		return Reflect.construct(ctor, [this.props, this.config]);
+	}
+
+	/**
+	 * @description
+	 * Determines structural equality between this value object and another of the same type.
+	 *
+	 * Equality is determined by value, not reference. The comparison strategy varies by prop type:
+	 * - Strings, booleans, numbers, bigints — compared by value.
+	 * - Dates — compared by timestamp.
+	 * - Arrays and functions — compared by JSON serialization.
+	 * - IDs — compared by `.value()`.
+	 * - Symbols — compared by `.description`.
+	 * - Objects — compared by JSON serialization, excluding `createdAt` and `updatedAt`.
+	 *
+	 * @param other The value object to compare against.
+	 * @returns `true` if both value objects are structurally equal; `false` otherwise.
+	 */
+	public isEqual(other: this): boolean {
+		if (!other || other.__kind !== this.__kind) return false;
+		const props = this.props;
+		const otherProps = other?.props;
+
+		const omitTimestamps = (obj: AnyObject): string => {
+			if (!obj) return "";
+			const { createdAt: _c, updatedAt: _u, ...rest } = obj;
+			return StableStringify(rest);
+		};
+
+		if (this.validator.isArray(props) || this.validator.isFunction(props)) {
+			return StableStringify(props) === StableStringify(otherProps);
+		}
+
+		if (this.validator.isBoolean(props)) return props === otherProps;
+
+		if (this.validator.isDate(props)) {
+			return (props as Date).getTime() === (otherProps as Date)?.getTime();
+		}
+
+		if (this.validator.isID(props)) {
+			return (props as UID).value() === (otherProps as UID)?.value();
+		}
+
+		if (this.validator.isNull(props) || this.validator.isUndefined(props)) {
+			return props === otherProps;
+		}
+
+		if (this.validator.isNumber(props) || typeof props === "bigint") {
+			return this.validator
+				.number(props as number)
+				.isEqualTo(otherProps as number);
+		}
+
+		if (this.validator.isString(props)) {
+			return this.validator
+				.string(props as string)
+				.isEqual(otherProps as string);
+		}
+
+		if (this.validator.isSymbol(props)) {
+			return (
+				(props as symbol).description === (otherProps as symbol)?.description
+			);
+		}
+
+		return (
+			omitTimestamps(props as AnyObject) ===
+			omitTimestamps(otherProps as AnyObject)
+		);
+	}
+
+	/**
+	 * @description
+	 * Serializes this value object into a plain, deeply frozen object.
+	 *
+	 * If an `adapter` is provided, the adapter's transformation is applied instead
+	 * of the default `AutoMapper` serialization:
+	 * - `Adapter` (with `adaptOne`) — synchronous transformation.
+	 * - `IAdapter` (with `build`) — Result-wrapped transformation, value is unwrapped.
+	 *
+	 * The default output is a deeply frozen `unknown` — cast to your expected shape
+	 * at the call site if needed.
+	 *
+	 * @param adapter Optional adapter to transform the output into a custom shape.
+	 * @returns A deeply frozen serialized representation of this value object.
+	 *
+	 * @example
+	 * ```typescript
+	 * const plain = money.toObject();
+	 * // { amount: 100 }
+	 *
+	 * const dto = money.toObject(new MoneyDtoAdapter());
+	 * ```
+	 */
+	public toObject<T = Props>(
+		adapter?: Adapter<this, T> | IAdapter<this, T>,
+	): Readonly<T> {
+		if (
+			adapter &&
+			typeof (adapter as Adapter<this, T>).adaptOne === "function"
+		) {
+			return (adapter as Adapter<this, T>).adaptOne(this);
+		}
+		if (adapter && typeof (adapter as IAdapter<this, T>).build === "function") {
+			return (adapter as IAdapter<this, T>).build(this).value();
+		}
+
+		const mapped = this.autoMapper.valueObjectToObj(this);
+		if (typeof mapped === "object" && mapped !== null) {
+			return DeepFreeze(mapped) as Readonly<T>;
+		}
+
+		return mapped as Readonly<T>;
+	}
+
+	/**
+	 * @description
+	 * Creates a new `ValueObject` instance wrapped in a `Result`.
+	 *
+	 * Returns `Result.error()` if `isValidProps()` returns `false`.
+	 * Subclasses should override both this method and `isValidProps()` to enforce
+	 * domain-specific construction rules.
+	 *
+	 * @param props The properties to validate and construct the value object with.
+	 * @returns A `Result` containing the new instance on success, or an error on failure.
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = Money.create(100);
+	 * if (result.isSuccess()) {
+	 *     const money = result.value();
+	 * }
+	 * ```
+	 */
+	public static create<Props, T extends ValueObject<Props>>(
+		this: ValueObjectConstructor<Props, T>,
+		props: Props,
+	): IResult<T> {
+		if (!this.isValidProps(props)) {
+			return Result.error(
+				`Invalid props for ${this.name}: failed domain validation.`,
+			);
+		}
+
+		const instance = new (this as any)(props);
+		return Result.success(instance);
+	}
+
+	/**
+	 * @description
+	 * Initializes a new `ValueObject` instance directly, throwing a `DomainError` if
+	 * the provided props are invalid.
+	 *
+	 * Prefer `create()` for production code. Use `init()` in tests, seeders, or contexts
+	 * where you can guarantee the props are valid and prefer exceptions over `Result`.
+	 *
+	 * @param props The properties to validate and construct the value object with.
+	 * @returns A new instance of this value object subclass.
+	 * @throws {DomainError} If `isValidProps()` returns `false`.
+	 */
+	public static init<Props, T extends ValueObject<Props>>(
+		this: ValueObjectConstructor<Props, T>,
+		props: Props,
+	): T {
+		if (!this.isValidProps(props)) {
+			throw new DomainError(`Init: invalid props.`, { context: this.name });
+		}
+
+		const instance = new (this as any)(props);
+		return instance;
+	}
+
+	/**
+	 * @description
+	 * Alias for `isValidProps()`. Provided for consistency with the `Entity` API.
+	 * Subclasses should override `isValidProps()` rather than this method.
+	 *
+	 * @param value The value to validate.
+	 * @returns `true` if valid; `false` otherwise.
+	 */
+	public static isValid(value: unknown): boolean {
+		return this.isValidProps(value);
+	}
+
+	/**
+	 * @description
+	 * Validates the provided props before constructing a new instance.
+	 *
+	 * The base implementation accepts anything that is not `null` or `undefined`.
+	 * Override this in your subclass to enforce domain-specific rules.
+	 *
+	 * @param props The props to validate.
+	 * @returns `true` if the props represent a valid state; `false` otherwise.
+	 *
+	 * @example
+	 * ```typescript
+	 * public static isValidProps({ amount }: MoneyProps): boolean {
+	 *     return amount >= 0;
+	 * }
+	 * ```
+	 */
+	public static isValidProps(props: unknown): boolean {
+		return (
+			!ValueObject.validator.isUndefined(props) &&
+			!ValueObject.validator.isNull(props)
+		);
+	}
+}