@cqrs-ddd/core 0.2.0

package/dist/domain/models/root.entity.d.ts

@@ -0,0 +1,208 @@
+import type { MutationPatch } from '../decorators/apply-mutation.decorator';
+import { RootEntitySnapshot } from '../interfaces/root-entity-snapshot.interface';
+import { AggregateRoot } from './aggregate-root';
+/**
+ * Abstract base entity for DDD domain aggregates and entities.
+ *
+ * Inherits from {@link AggregateRoot} to manage domain events
+ * internally:
+ * - **Domain Event Recording**: Call `this.apply(new SomeEvent(this))` to buffer uncommitted events.
+ * - **UUID v7 Identity**: Automatically generates time-ordered UUID v7 identifiers for new instances.
+ * - **Lifecycle Timestamps**: Enforces invariant-checked `createdAt` and `updatedAt` tracking.
+ * - **Accessor-Driven Persistence**: `id`, `createdAt` and `updatedAt` have public getters and
+ *   private setters. An ORM hydrates through the setters (MikroORM: `accessor: true`); application code
+ *   cannot assign them and changes state through factories and domain methods.
+ * - **Optimistic Concurrency Control**: Tracks integer aggregate versioning (`_version`, {@link getExpectedVersion}),
+ *   incremented automatically on mutations to prevent concurrent lost updates.
+ * - **Polymorphic Rehydration**: Static `RootEntity.from()` transparently handles instances, plain snapshots,
+ *   or nullish database results while enforcing strict aggregate type safety (throws `TypeError` on incompatible aggregates).
+ * - **Mutation Tracking**: Automatically updates `updatedAt`, increments `_version` on `@ApplyMutation()`-decorated methods,
+ *   and triggers the `afterUpdate()` lifecycle hook.
+ *
+ * @example Defining a domain aggregate
+ * ```typescript
+ * interface UserSnapshot extends Partial<RootEntitySnapshot> {
+ *   readonly username: string;
+ *   readonly email: string;
+ *   readonly version?: number;
+ * }
+ *
+ * export class User extends RootEntity<UserSnapshot> {
+ *   @Mutable<string>()
+ *   private _username: string;
+ *   readonly email: string;
+ *
+ *   private constructor(snapshot: UserSnapshot) {
+ *     super(snapshot);
+ *     this._username = snapshot.username!;
+ *     this.email = snapshot.email!;
+ *   }
+ *
+ *   static create(username: string, email: string): User {
+ *     const user = new User({ username, email });
+ *     user.apply(new UserCreatedEvent(user));
+ *     return user;
+ *   }
+ *
+ *   static fromJSON(snapshot: UserSnapshot): User {
+ *     return new User(snapshot);
+ *   }
+ *
+ *   @ApplyMutation<User>({ event: (user) => new UserRenamedEvent(user) })
+ *   rename(newUsername: string): this {
+ *     this.applyPatch({ username: newUsername });
+ *     return this;
+ *   }
+ *
+ *   toJSON(): RootEntitySnapshot & UserSnapshot {
+ *     return this.freezeState({
+ *       id: this.id,
+ *       username: this._username,
+ *       email: this.email,
+ *       createdAt: this.createdAt,
+ *       updatedAt: this.updatedAt,
+ *       version: this._version,
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class RootEntity<TSnapshot extends Partial<RootEntitySnapshot> = RootEntitySnapshot> extends AggregateRoot implements RootEntitySnapshot {
+    private _id;
+    private _createdAt;
+    private _updatedAt;
+    protected _version: number;
+    protected _persistedVersion: number;
+    constructor(snapshot?: Partial<RootEntitySnapshot>);
+    protected static normalizeId(id?: string): string;
+    protected static normalizeDate(value?: Date | string): Date;
+    /**
+     * Rehydrates or returns an already-hydrated entity instance.
+     *
+     * If `candidate` is already an instance of the target entity class, it is returned as-is.
+     * If `candidate` is an instance of an incompatible `RootEntity`, a `TypeError` is thrown.
+     * Otherwise, if `candidate` is a snapshot object, it is rehydrated via the class's `fromJSON()` factory.
+     */
+    static from<T extends RootEntity<TSnapshot>, TSnapshot extends Partial<RootEntitySnapshot>>(this: {
+        fromJSON(snapshot: TSnapshot): T;
+    } | (abstract new (...args: unknown[]) => T), candidate: T | TSnapshot | null | undefined): T | null;
+    get id(): string;
+    /**
+     * For ORM hydration only (MikroORM: `accessor: true`). Private, so application code
+     * cannot assign it and changes state through domain methods and factories.
+     */
+    private set id(value);
+    get createdAt(): Date;
+    /**
+     * For ORM hydration only (MikroORM: `accessor: true`). Private, so application code
+     * cannot assign it and changes state through domain methods and factories.
+     */
+    private set createdAt(value);
+    get updatedAt(): Date;
+    /**
+     * For ORM hydration only (MikroORM: `accessor: true`). Private, so application code
+     * cannot assign it and changes state through domain methods and factories.
+     */
+    private set updatedAt(value);
+    /**
+     * The current in-memory version: 1 for a new entity, advanced by each
+     * `@ApplyMutation()` method. Persistence writes store it; the version a write
+     * expects to find in storage is {@link getExpectedVersion}.
+     *
+     * @example
+     * ```typescript
+     * const user = User.create('ada', 'ada@example.com'); // user.version === 1
+     * user.rename('ada.l');                                // user.version === 2
+     * user.getExpectedVersion();                           // still 1 until persisted
+     * ```
+     */
+    get version(): number;
+    /**
+     * For ORM hydration only (MikroORM: `accessor: true`). Private, so application code
+     * cannot assign it and changes state through domain methods and factories.
+     * A loaded version is also the persisted baseline; a value that is not a
+     * positive integer is ignored.
+     */
+    private set version(value);
+    /**
+     * Returns the expected persistence version baseline (`_persistedVersion`).
+     *
+     * This baseline represents the last confirmed durable version successfully written
+     * to persistent storage. Persistence adapters use this value in version predicates
+     * (e.g. `WHERE id = ? AND version = expectedVersion`) to detect concurrent updates.
+     *
+     * @returns The positive integer version expected in persistent storage.
+     *
+     * @example
+     * ```typescript
+     * const expected = user.getExpectedVersion(); // e.g. 1
+     * await em.nativeUpdate(User, { id: user.id, version: expected }, { ...data, version: user.version });
+     * ```
+     */
+    getExpectedVersion(): number;
+    /**
+     * Acknowledges that a version has been successfully persisted to durable storage.
+     * Advances the expected version baseline (`_persistedVersion`) to match the version
+     * actually written (by default `this._version`), without recording a domain event
+     * or advancing the in-memory version.
+     *
+     * This method is owned by persistence repositories and is typically invoked
+     * automatically by the `@AcknowledgePersisted` method decorator upon successful
+     * write resolution. Application code must never call this method directly; state
+     * mutations belong in domain methods.
+     *
+     * @param version Optional specific version that was persisted. If omitted,
+     *                `this._version` is used. Must be a positive integer (> 0).
+     * @throws {Error} If `version` is provided but is not a positive integer.
+     *
+     * @example Manual invocation in a custom persistence repository
+     * ```typescript
+     * async save(user: User): Promise<UserSnapshot> {
+     *   const snapshot = user.toJSON();
+     *   await this.db.update(user.id, snapshot);
+     *   user.acknowledgePersisted(); // advances _persistedVersion to user.version
+     *   return snapshot;
+     * }
+     * ```
+     *
+     * @example Declarative invocation via `@AcknowledgePersisted` (recommended)
+     * ```typescript
+     * @AcknowledgePersisted<[User]>({ entity: ([user]) => user })
+     * async save(user: User): Promise<UserSnapshot> {
+     *   // Decorator captures user.version before execution and calls
+     *   // user.acknowledgePersisted() when the returned promise resolves.
+     *   return snapshot;
+     * }
+     * ```
+     */
+    acknowledgePersisted(version?: number): void;
+    /**
+     * Applies a patch to fields registered with `@Mutable()`, ignoring undefined values.
+     * Validates all keys and normalizes all values before writing any field.
+     * Does not advance version/timestamps or record events; use inside a decorated mutation.
+     *
+     * @param patch - Public field names and proposed values; keys must be registered with `@Mutable()`.
+     * @throws {UnknownMutableFieldError} When a defined patch key is not registered.
+     * @throws Propagates field normalization errors without applying the patch.
+     *
+     * @example Inside a User aggregate with a mutable username field
+     * ```ts
+     * @ApplyMutation<User>({ event: (user) => new UserUpdatedEvent(user) })
+     * update(username: string): this {
+     *   this.applyPatch<User>({ username });
+     *   return this;
+     * }
+     * ```
+     */
+    protected applyPatch<TEntity extends object>(patch: MutationPatch<TEntity>): void;
+    protected onUpdate(): void;
+    protected freezeState<S extends object>(state: S): Readonly<S>;
+    /**
+     * Post-mutation lifecycle hook, invoked after the version and `updatedAt`
+     * advance and before the mutation's event is recorded. The default does
+     * nothing; override it only when the aggregate has post-mutation work.
+     */
+    protected afterUpdate(): void;
+    abstract toJSON(): RootEntitySnapshot & TSnapshot;
+}
+//# sourceMappingURL=root.entity.d.ts.map

package/dist/domain/models/root.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.entity.d.ts","sourceRoot":"","sources":["../../../domain/models/root.entity.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAG5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,8BAAsB,UAAU,CAC5B,SAAS,SAAS,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAEpE,SAAQ,aACR,YAAW,kBAAkB;IAE7B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,UAAU,CAAO;IACzB,OAAO,CAAC,UAAU,CAAO;IACzB,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBAExB,QAAQ,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC;IAwClD,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAOjD,SAAS,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI;IAgB3D;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CACT,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC,EAC/B,SAAS,SAAS,OAAO,CAAC,kBAAkB,CAAC,EAE7C,IAAI,EACA;QAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,CAAC,CAAA;KAAE,GACpC,CAAC,QAAQ,MACP,GAAG,IAAI,EAAE,OAAO,EAAE,KACf,CAAC,CAAC,EACX,SAAS,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,GAC1C,CAAC,GAAG,IAAI;IA4BX,IAAI,EAAE,IAAI,MAAM,CAEf;IAED;;;OAGG;IACH,OAAO,KAAK,EAAE,QAEb;IAED,IAAI,SAAS,IAAI,IAAI,CAEpB;IAED;;;OAGG;IACH,OAAO,KAAK,SAAS,QAEpB;IAED,IAAI,SAAS,IAAI,IAAI,CAEpB;IAED;;;OAGG;IACH,OAAO,KAAK,SAAS,QAEpB;IAED;;;;;;;;;;;OAWG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;;OAKG;IACH,OAAO,KAAK,OAAO,QAKlB;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,oBAAoB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAc5C;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,UAAU,CAAC,OAAO,SAAS,MAAM,EACzC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAC5B,IAAI;IAwCP,SAAS,CAAC,QAAQ,IAAI,IAAI;IAM1B,SAAS,CAAC,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAI9D;;;;OAIG;IACH,SAAS,CAAC,WAAW,IAAI,IAAI;IAE7B,QAAQ,CAAC,MAAM,IAAI,kBAAkB,GAAG,SAAS;CAClD"}

package/dist/domain/models/root.entity.js

@@ -0,0 +1,350 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RootEntity = void 0;
+const uuidv7_1 = require("@cqrs-ddd/uuidv7");
+const mutable_decorator_1 = require("../decorators/mutable.decorator");
+const unknown_mutable_field_error_1 = require("../exceptions/unknown-mutable-field.error");
+const aggregate_root_1 = require("./aggregate-root");
+/**
+ * Abstract base entity for DDD domain aggregates and entities.
+ *
+ * Inherits from {@link AggregateRoot} to manage domain events
+ * internally:
+ * - **Domain Event Recording**: Call `this.apply(new SomeEvent(this))` to buffer uncommitted events.
+ * - **UUID v7 Identity**: Automatically generates time-ordered UUID v7 identifiers for new instances.
+ * - **Lifecycle Timestamps**: Enforces invariant-checked `createdAt` and `updatedAt` tracking.
+ * - **Accessor-Driven Persistence**: `id`, `createdAt` and `updatedAt` have public getters and
+ *   private setters. An ORM hydrates through the setters (MikroORM: `accessor: true`); application code
+ *   cannot assign them and changes state through factories and domain methods.
+ * - **Optimistic Concurrency Control**: Tracks integer aggregate versioning (`_version`, {@link getExpectedVersion}),
+ *   incremented automatically on mutations to prevent concurrent lost updates.
+ * - **Polymorphic Rehydration**: Static `RootEntity.from()` transparently handles instances, plain snapshots,
+ *   or nullish database results while enforcing strict aggregate type safety (throws `TypeError` on incompatible aggregates).
+ * - **Mutation Tracking**: Automatically updates `updatedAt`, increments `_version` on `@ApplyMutation()`-decorated methods,
+ *   and triggers the `afterUpdate()` lifecycle hook.
+ *
+ * @example Defining a domain aggregate
+ * ```typescript
+ * interface UserSnapshot extends Partial<RootEntitySnapshot> {
+ *   readonly username: string;
+ *   readonly email: string;
+ *   readonly version?: number;
+ * }
+ *
+ * export class User extends RootEntity<UserSnapshot> {
+ *   @Mutable<string>()
+ *   private _username: string;
+ *   readonly email: string;
+ *
+ *   private constructor(snapshot: UserSnapshot) {
+ *     super(snapshot);
+ *     this._username = snapshot.username!;
+ *     this.email = snapshot.email!;
+ *   }
+ *
+ *   static create(username: string, email: string): User {
+ *     const user = new User({ username, email });
+ *     user.apply(new UserCreatedEvent(user));
+ *     return user;
+ *   }
+ *
+ *   static fromJSON(snapshot: UserSnapshot): User {
+ *     return new User(snapshot);
+ *   }
+ *
+ *   @ApplyMutation<User>({ event: (user) => new UserRenamedEvent(user) })
+ *   rename(newUsername: string): this {
+ *     this.applyPatch({ username: newUsername });
+ *     return this;
+ *   }
+ *
+ *   toJSON(): RootEntitySnapshot & UserSnapshot {
+ *     return this.freezeState({
+ *       id: this.id,
+ *       username: this._username,
+ *       email: this.email,
+ *       createdAt: this.createdAt,
+ *       updatedAt: this.updatedAt,
+ *       version: this._version,
+ *     });
+ *   }
+ * }
+ * ```
+ */
+class RootEntity extends aggregate_root_1.AggregateRoot {
+    _id;
+    _createdAt;
+    _updatedAt;
+    _version;
+    _persistedVersion;
+    constructor(snapshot) {
+        super();
+        const id = snapshot?.id;
+        const createdAt = snapshot?.createdAt;
+        const updatedAt = snapshot?.updatedAt;
+        const version = snapshot?.version;
+        this._version =
+            typeof version === 'number' && Number.isInteger(version) && version > 0
+                ? version
+                : 1;
+        this._persistedVersion = this._version;
+        if (id !== undefined &&
+            createdAt !== undefined &&
+            updatedAt !== undefined) {
+            this._id = RootEntity.normalizeId(id);
+            this._createdAt = RootEntity.normalizeDate(createdAt);
+            this._updatedAt = RootEntity.normalizeDate(updatedAt);
+            return;
+        }
+        if (id !== undefined ||
+            createdAt !== undefined ||
+            updatedAt !== undefined) {
+            throw new Error('id, createdAt, and updatedAt must be provided together when rehydrating an entity.');
+        }
+        const now = new Date();
+        this._id = (0, uuidv7_1.uuidv7)();
+        this._createdAt = now;
+        this._updatedAt = now;
+    }
+    static normalizeId(id) {
+        if (typeof id !== 'string' || !(0, uuidv7_1.isUuidV7)(id)) {
+            throw new Error('id must be a valid UUID v7.');
+        }
+        return id.trim();
+    }
+    static normalizeDate(value) {
+        if (value === undefined || value === null) {
+            throw new Error('Date is empty.');
+        }
+        if (typeof value === 'string' && value.trim().length === 0) {
+            throw new Error('Date is empty.');
+        }
+        const parsed = new Date(value);
+        if (Number.isNaN(parsed.getTime()) || parsed.getUTCFullYear() <= 1) {
+            throw new Error('Date must be a valid non-empty date.');
+        }
+        return parsed;
+    }
+    /**
+     * Rehydrates or returns an already-hydrated entity instance.
+     *
+     * If `candidate` is already an instance of the target entity class, it is returned as-is.
+     * If `candidate` is an instance of an incompatible `RootEntity`, a `TypeError` is thrown.
+     * Otherwise, if `candidate` is a snapshot object, it is rehydrated via the class's `fromJSON()` factory.
+     */
+    static from(candidate) {
+        if (candidate === null || candidate === undefined) {
+            return null;
+        }
+        // biome-ignore lint/complexity/noThisInStatic: Polymorphic static rehydration
+        const targetClass = this;
+        if (typeof targetClass === 'function') {
+            if (candidate instanceof targetClass) {
+                return candidate;
+            }
+            if (candidate instanceof RootEntity) {
+                const expectedName = targetClass.name || 'TargetEntity';
+                const actualName = candidate.constructor?.name || 'RootEntity';
+                throw new TypeError(`Cannot rehydrate entity: expected instance of ${expectedName}, received incompatible aggregate ${actualName}.`);
+            }
+        }
+        else if (candidate instanceof RootEntity) {
+            return candidate;
+        }
+        // biome-ignore lint/complexity/noThisInStatic: Polymorphic static rehydration
+        const ctor = this;
+        if (typeof ctor.fromJSON === 'function') {
+            return ctor.fromJSON(candidate);
+        }
+        throw new Error('Cannot rehydrate entity: missing fromJSON factory.');
+    }
+    get id() {
+        return this._id;
+    }
+    /**
+     * For ORM hydration only (MikroORM: `accessor: true`). Private, so application code
+     * cannot assign it and changes state through domain methods and factories.
+     */
+    set id(value) {
+        this._id = RootEntity.normalizeId(value);
+    }
+    get createdAt() {
+        return new Date(this._createdAt);
+    }
+    /**
+     * For ORM hydration only (MikroORM: `accessor: true`). Private, so application code
+     * cannot assign it and changes state through domain methods and factories.
+     */
+    set createdAt(value) {
+        this._createdAt = RootEntity.normalizeDate(value);
+    }
+    get updatedAt() {
+        return new Date(this._updatedAt);
+    }
+    /**
+     * For ORM hydration only (MikroORM: `accessor: true`). Private, so application code
+     * cannot assign it and changes state through domain methods and factories.
+     */
+    set updatedAt(value) {
+        this._updatedAt = RootEntity.normalizeDate(value);
+    }
+    /**
+     * The current in-memory version: 1 for a new entity, advanced by each
+     * `@ApplyMutation()` method. Persistence writes store it; the version a write
+     * expects to find in storage is {@link getExpectedVersion}.
+     *
+     * @example
+     * ```typescript
+     * const user = User.create('ada', 'ada@example.com'); // user.version === 1
+     * user.rename('ada.l');                                // user.version === 2
+     * user.getExpectedVersion();                           // still 1 until persisted
+     * ```
+     */
+    get version() {
+        return this._version;
+    }
+    /**
+     * For ORM hydration only (MikroORM: `accessor: true`). Private, so application code
+     * cannot assign it and changes state through domain methods and factories.
+     * A loaded version is also the persisted baseline; a value that is not a
+     * positive integer is ignored.
+     */
+    set version(value) {
+        if (typeof value === 'number' && Number.isInteger(value) && value > 0) {
+            this._version = value;
+            this._persistedVersion = value;
+        }
+    }
+    /**
+     * Returns the expected persistence version baseline (`_persistedVersion`).
+     *
+     * This baseline represents the last confirmed durable version successfully written
+     * to persistent storage. Persistence adapters use this value in version predicates
+     * (e.g. `WHERE id = ? AND version = expectedVersion`) to detect concurrent updates.
+     *
+     * @returns The positive integer version expected in persistent storage.
+     *
+     * @example
+     * ```typescript
+     * const expected = user.getExpectedVersion(); // e.g. 1
+     * await em.nativeUpdate(User, { id: user.id, version: expected }, { ...data, version: user.version });
+     * ```
+     */
+    getExpectedVersion() {
+        return this._persistedVersion;
+    }
+    /**
+     * Acknowledges that a version has been successfully persisted to durable storage.
+     * Advances the expected version baseline (`_persistedVersion`) to match the version
+     * actually written (by default `this._version`), without recording a domain event
+     * or advancing the in-memory version.
+     *
+     * This method is owned by persistence repositories and is typically invoked
+     * automatically by the `@AcknowledgePersisted` method decorator upon successful
+     * write resolution. Application code must never call this method directly; state
+     * mutations belong in domain methods.
+     *
+     * @param version Optional specific version that was persisted. If omitted,
+     *                `this._version` is used. Must be a positive integer (> 0).
+     * @throws {Error} If `version` is provided but is not a positive integer.
+     *
+     * @example Manual invocation in a custom persistence repository
+     * ```typescript
+     * async save(user: User): Promise<UserSnapshot> {
+     *   const snapshot = user.toJSON();
+     *   await this.db.update(user.id, snapshot);
+     *   user.acknowledgePersisted(); // advances _persistedVersion to user.version
+     *   return snapshot;
+     * }
+     * ```
+     *
+     * @example Declarative invocation via `@AcknowledgePersisted` (recommended)
+     * ```typescript
+     * @AcknowledgePersisted<[User]>({ entity: ([user]) => user })
+     * async save(user: User): Promise<UserSnapshot> {
+     *   // Decorator captures user.version before execution and calls
+     *   // user.acknowledgePersisted() when the returned promise resolves.
+     *   return snapshot;
+     * }
+     * ```
+     */
+    acknowledgePersisted(version) {
+        if (typeof version === 'number') {
+            if (!Number.isInteger(version) || version <= 0) {
+                throw new Error('Persisted version must be a positive integer.');
+            }
+            this._persistedVersion = version;
+            if (this._version < version) {
+                this._version = version;
+            }
+            return;
+        }
+        this._persistedVersion = this._version;
+    }
+    /**
+     * Applies a patch to fields registered with `@Mutable()`, ignoring undefined values.
+     * Validates all keys and normalizes all values before writing any field.
+     * Does not advance version/timestamps or record events; use inside a decorated mutation.
+     *
+     * @param patch - Public field names and proposed values; keys must be registered with `@Mutable()`.
+     * @throws {UnknownMutableFieldError} When a defined patch key is not registered.
+     * @throws Propagates field normalization errors without applying the patch.
+     *
+     * @example Inside a User aggregate with a mutable username field
+     * ```ts
+     * @ApplyMutation<User>({ event: (user) => new UserUpdatedEvent(user) })
+     * update(username: string): this {
+     *   this.applyPatch<User>({ username });
+     *   return this;
+     * }
+     * ```
+     */
+    applyPatch(patch) {
+        if (patch === undefined || patch === null) {
+            return;
+        }
+        if (typeof patch !== 'object') {
+            throw new TypeError('applyPatch() requires a field patch object, or nothing.');
+        }
+        const fields = (0, mutable_decorator_1.getMutableFields)(this);
+        const writes = [];
+        // Phase 1: validate all keys and normalize values before any state changes
+        for (const [key, value] of Object.entries(patch)) {
+            if (value === undefined) {
+                continue;
+            }
+            const field = fields.get(key);
+            if (!field) {
+                throw new unknown_mutable_field_error_1.UnknownMutableFieldError(this.constructor.name, key, [
+                    ...fields.keys(),
+                ]);
+            }
+            const normalizedValue = field.normalize ? field.normalize(value) : value;
+            writes.push({
+                propertyKey: field.propertyKey,
+                value: normalizedValue,
+            });
+        }
+        // Phase 2: apply normalized writes to backing properties
+        for (const { propertyKey, value } of writes) {
+            this[propertyKey] = value;
+        }
+    }
+    onUpdate() {
+        this._version += 1;
+        this._updatedAt = new Date();
+        this.afterUpdate();
+    }
+    freezeState(state) {
+        return Object.freeze(state);
+    }
+    /**
+     * Post-mutation lifecycle hook, invoked after the version and `updatedAt`
+     * advance and before the mutation's event is recorded. The default does
+     * nothing; override it only when the aggregate has post-mutation work.
+     */
+    afterUpdate() { }
+}
+exports.RootEntity = RootEntity;
+//# sourceMappingURL=root.entity.js.map

package/dist/domain/models/root.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.entity.js","sourceRoot":"","sources":["../../../domain/models/root.entity.ts"],"names":[],"mappings":"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"}

package/dist/domain/rules/number.rule.d.ts

@@ -0,0 +1,81 @@
+import type { ValueViolationError } from './value-violation';
+/** Options of {@link numberRule}. */
+export interface NumberRuleOptions {
+    /** Field name reported in the violation and in the default message. */
+    readonly field: string;
+    /**
+     * `false` accepts `null` and `undefined`, and normalizes them to `null`.
+     * Defaults to `true`: they are a `required` violation.
+     */
+    readonly required?: boolean;
+    /**
+     * `true` accepts safe integers only (`Number.isSafeInteger`), so the value
+     * survives a round trip through JSON and a `bigint` column.
+     */
+    readonly integer?: boolean;
+    /** Smallest accepted value, inclusive. */
+    readonly min?: number;
+    /** Largest accepted value, inclusive. */
+    readonly max?: number;
+    /**
+     * Builds the error thrown for a violation. Defaults to
+     * `InvalidValueException`.
+     */
+    readonly error?: ValueViolationError;
+}
+/** What {@link NumberRule.parse} returns: `number | null` when not required. */
+export type NumberRuleValue<TOptions extends NumberRuleOptions> = TOptions extends {
+    readonly required: true;
+} ? number : TOptions extends {
+    readonly required: boolean;
+} ? number | null : number;
+/** A number rule: its options, frozen, and the parser that enforces them. */
+export type NumberRule<TOptions extends NumberRuleOptions = NumberRuleOptions> = Readonly<TOptions> & {
+    /**
+     * Returns the value unchanged, or `null` for a missing value the rule
+     * does not require. A standalone function: pass it without binding.
+     *
+     * @throws The `error` option's result, by default `InvalidValueException`.
+     */
+    readonly parse: (value: unknown) => NumberRuleValue<TOptions>;
+};
+/**
+ * Defines the rule for one number field of an aggregate: declared once, used
+ * by the aggregate to parse the value, and read by other layers (such as a
+ * request schema) for its limits.
+ *
+ * `parse(value)` checks, in this order:
+ * 1. `null` or `undefined`: `null`, or a `required` violation;
+ * 2. not a number: a `type` violation (a numeric string is not converted);
+ * 3. `NaN` or an infinity: a `finite` violation;
+ * 4. with `integer`, not a safe integer: an `integer` violation;
+ * 5. `min`, then `max`.
+ *
+ * @param options - The field name, its constraints and its error.
+ * @returns The frozen rule.
+ * @throws TypeError when an option is invalid: an empty `field`, a bound that
+ *   is not a finite number, or `min` above `max`.
+ *
+ * @example
+ * ```ts
+ * export class Order extends RootEntity<OrderSnapshot> {
+ *   static readonly rules = {
+ *     quantity: numberRule({
+ *       field: 'quantity',
+ *       integer: true,
+ *       min: 1,
+ *       max: 100,
+ *       error: (violation) => new InvalidQuantityException(violation),
+ *     }),
+ *   } as const;
+ *
+ *   @Mutable<number>({ normalize: (value) => Order.rules.quantity.parse(value) })
+ *   private _quantity: number;
+ * }
+ *
+ * Order.rules.quantity.parse(0);
+ * // throws InvalidQuantityException: "quantity must be at least 1."
+ * ```
+ */
+export declare function numberRule<const TOptions extends NumberRuleOptions>(options: TOptions): NumberRule<TOptions>;
+//# sourceMappingURL=number.rule.d.ts.map

package/dist/domain/rules/number.rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.rule.d.ts","sourceRoot":"","sources":["../../../domain/rules/number.rule.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;CACtC;AAED,gFAAgF;AAChF,MAAM,MAAM,eAAe,CAAC,QAAQ,SAAS,iBAAiB,IAC5D,QAAQ,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,GACxC,MAAM,GACN,QAAQ,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC7C,MAAM,GAAG,IAAI,GACb,MAAM,CAAC;AAEf,6EAA6E;AAC7E,MAAM,MAAM,UAAU,CAAC,QAAQ,SAAS,iBAAiB,GAAG,iBAAiB,IAC3E,QAAQ,CAAC,QAAQ,CAAC,GAAG;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,eAAe,CAAC,QAAQ,CAAC,CAAC;CAC/D,CAAC;AAQJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,UAAU,CAAC,KAAK,CAAC,QAAQ,SAAS,iBAAiB,EACjE,OAAO,EAAE,QAAQ,GAChB,UAAU,CAAC,QAAQ,CAAC,CAkCtB"}