@woltz/rich-domain 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -2,40 +2,106 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-## [1.1.0](https://github.com/tarcisioandrade/rich-domain/compare/v1.0.0...v1.1.0) (2025-11-22)
+### [1.2.1](https://github.com/tarcisioandrade/rich-domain/compare/v1.2.0...v1.2.1) (2025-11-29)
 
 
 ### Features
 
-* add examples in monorepo ([2cba30e](https://github.com/tarcisioandrade/rich-domain/commit/2cba30e318be2575b007c8b4f9a00e35561eec5e))
-* add react-with-react-query example ([439589e](https://github.com/tarcisioandrade/rich-domain/commit/439589e1abbc47b1b03efab3b9dde53fe8d6253c))
-* domain execeptions ([e206274](https://github.com/tarcisioandrade/rich-domain/commit/e206274d8a93c09cc91b2c0514be62cb986caaa3))
-* implement useCriteria hook ([c00441a](https://github.com/tarcisioandrade/rich-domain/commit/c00441a105391fd06ef39b8c7e3aa0907c3ff508))
+* implement custom UUID generation in crypto module ([4fc732a](https://github.com/tarcisioandrade/rich-domain/commit/4fc732a00237a9d63e320555acf4a8a14c941f13))
+* introduce TypedOrder and enhance Criteria to support nested object field paths ([9857624](https://github.com/tarcisioandrade/rich-domain/commit/9857624608eda1320ec813b165e9183f1e28a0d1))
+* new history-tracker structure ([aaea6d4](https://github.com/tarcisioandrade/rich-domain/commit/aaea6d4c8aed575f50917cba41936d1b1560ed3d))
+* update Id constructor to handle optional isNew parameter ([0aae58b](https://github.com/tarcisioandrade/rich-domain/commit/0aae58b02da69e0cb7421663335ac305ade5afa7))
 
 
 ### Bug Fixes
 
-* infinite loop when multiples order are add ([2c13dc4](https://github.com/tarcisioandrade/rich-domain/commit/2c13dc472d009bf328ad45222ea1c921f588ff9a))
-* search not working in fromArray PaginatedResult method ([b79b2aa](https://github.com/tarcisioandrade/rich-domain/commit/b79b2aa2aa17e8b98bf2c2fcb4823452db99dcc1))
+* aggregate-changes type inference ([aa62138](https://github.com/tarcisioandrade/rich-domain/commit/aa62138b31cdedb63c0e1be8a19271f4ada2e71c))
+* history tracker not tracking when nested created ([2900e20](https://github.com/tarcisioandrade/rich-domain/commit/2900e20c18da7aa0ee960c9e5d0f5e2524e3d6f3))
+* uow in persistence fastify example ([fcef611](https://github.com/tarcisioandrade/rich-domain/commit/fcef61103f160c0b1adbee9cbce821ce047189eb))
 
 
 ### Refactoring
 
-* clean exports ([3f8e16a](https://github.com/tarcisioandrade/rich-domain/commit/3f8e16a2103514ef7a2a928dff20f674d1e39506))
-* migrate eslint configuration to ES module syntax ([3ea4366](https://github.com/tarcisioandrade/rich-domain/commit/3ea43667b0857b7ae2afcbad858c16384035dc50))
-* monorepo implementation ([e0b1e68](https://github.com/tarcisioandrade/rich-domain/commit/e0b1e683d5ee95b54b79510d43dd957af49c65e2))
-* remove defaultValues from value objects ([0523479](https://github.com/tarcisioandrade/rich-domain/commit/0523479c6f272d7ea5d678638fa666e3fde71c7a))
-* streamline domain event imports and consolidate IDomainEvent interface ([573c689](https://github.com/tarcisioandrade/rich-domain/commit/573c689a762baecd9fb8791e66300f663d7a58c1))
+* change prisma example to new architecture ([92dc179](https://github.com/tarcisioandrade/rich-domain/commit/92dc1798ee5a64439d6633ab5b0cc77b42265ed6))
+* improve deepClone method for better object handling and error management ([52ae893](https://github.com/tarcisioandrade/rich-domain/commit/52ae8930d112ba018f7944f69837edea82d45309))
+* prisma example unit of work with async local storage ([ca6fc16](https://github.com/tarcisioandrade/rich-domain/commit/ca6fc1663ca251dac020939080b126f3984b0eae))
+* remove unnosed code from ancient architecture ([19a41b1](https://github.com/tarcisioandrade/rich-domain/commit/19a41b121b4adaaea5525da20b068f43cc674db8))
+* update repository methods to use 'save' consistently across use cases ([aab323b](https://github.com/tarcisioandrade/rich-domain/commit/aab323be2fff86246dc0c1a14cb7ba56bf11efa7))
+* update repository methods to use 'save' instead of 'create' and 'update' ([6766970](https://github.com/tarcisioandrade/rich-domain/commit/6766970019781215019b492963e020ef4babcd89))
+
+
+### Tests
+
+* add load test ([9bd07fb](https://github.com/tarcisioandrade/rich-domain/commit/9bd07fb019e2cc0eef3f0573af8f4dad1d8b385f))
+* new history-tracker structure ([d31ad0b](https://github.com/tarcisioandrade/rich-domain/commit/d31ad0b109bfa5e5ff62743d70dd51bb64107f10))
+
+## [1.2.0](https://github.com/tarcisioandrade/rich-domain/compare/v1.1.0...v1.2.0) (2025-11-23)
+
+
+### Features
+
+* add getFilterByField and getSortByField methods to useCriteria hook ([8db041a](https://github.com/tarcisioandrade/rich-domain/commit/8db041a8fbe359ec6fe3ff70e22ac87a6c221686))
+* add options parameter to addFilter method for enhanced filtering capabilities ([c43c164](https://github.com/tarcisioandrade/rich-domain/commit/c43c164f56831b9f0b06f2e5981ba3f540cf3378))
+* add quantifier support to Criteria class for enhanced filtering options ([322adf3](https://github.com/tarcisioandrade/rich-domain/commit/322adf36dfedcdc21ae6fc85c3577e1fb2835019))
+* criteria adapter implementation ([f387f0b](https://github.com/tarcisioandrade/rich-domain/commit/f387f0bcd601a69da74d5fff33b9d9872e049179))
+* enhance criteria operators with new types and validation functions ([8d30c14](https://github.com/tarcisioandrade/rich-domain/commit/8d30c1448e3d25c790d667b43d17546a441e710d))
+
+
+### Bug Fixes
+
+* FieldPath infer type to array methods ([844a56e](https://github.com/tarcisioandrade/rich-domain/commit/844a56ef2cdc65fac0cb228c6936808a92ffa440))
+* search filter not reset page ([c8c9d8b](https://github.com/tarcisioandrade/rich-domain/commit/c8c9d8b1fecc1ce8c568f43710c8748ad9ad1f1e))
+* types in react-with-react-query ([6eeeb74](https://github.com/tarcisioandrade/rich-domain/commit/6eeeb74715bef50d3c5dec8dcc3e37484e0f511b))
 
 
 ### Chores
 
-* add postinstall script to generate Prisma client ([ffbe310](https://github.com/tarcisioandrade/rich-domain/commit/ffbe310db4ff9e6918d4e55096b8939c1f8f4543))
-* enhance linting setup for react-rich-domain and update package.json ([ac2803b](https://github.com/tarcisioandrade/rich-domain/commit/ac2803bac0d907c0513d249fc5e14390418c7530))
-* modify check script to target specific workspace ([d39d6d8](https://github.com/tarcisioandrade/rich-domain/commit/d39d6d8ef3a04d17207a3a0e795027040b3cf707))
-* update clean script to remove node_modules in backend and rich-domain packages ([2a10cab](https://github.com/tarcisioandrade/rich-domain/commit/2a10cab193ba00e504a9a301cc00cda4b68b8573))
-* update module entry points in package.json for react-rich-domain ([03be9ac](https://github.com/tarcisioandrade/rich-domain/commit/03be9aced05160c97eb74f771b770283c07e046b))
-* update package configuration and add new dependencies ([4135393](https://github.com/tarcisioandrade/rich-domain/commit/4135393ae78b1b8e6b0c9306f0ac0872971ddb3f))
-* update package.json scripts to target specific workspace ([8f46868](https://github.com/tarcisioandrade/rich-domain/commit/8f468688017f49cae58dff5d1a9818fe64b38017))
-* update package.json with homepage and repository detail ([bfb387c](https://github.com/tarcisioandrade/rich-domain/commit/bfb387cb2076989a808f25be09337a24ed3a8ff6))
-* update test script to target specific workspace ([6783208](https://github.com/tarcisioandrade/rich-domain/commit/678320803828a43ef588c366e59bf62c2851c126))
+* add TypeScript check script and enhance ([9f6347c](https://github.com/tarcisioandrade/rich-domain/commit/9f6347c4707adebb9e03bcdc952791a9c3279038))
+* enhance useCriteria hook and update TypeScript types for better type safety ([2bbc699](https://github.com/tarcisioandrade/rich-domain/commit/2bbc699aab415a52502ad50e7fbf67bcd52ae222))
+* refactor frontend example to integrate useCriteria hook ([48dccc7](https://github.com/tarcisioandrade/rich-domain/commit/48dccc7df870024f280902c22c77dcf531702781))
+* update ESLint configurations to include tsconfigRootDir ([b019884](https://github.com/tarcisioandrade/rich-domain/commit/b01988496b91c6c9d3e6d3d89597cf9f23e54729))
+* update rich domain version in examples app ([4be8a1b](https://github.com/tarcisioandrade/rich-domain/commit/4be8a1bdd4473d8274c0ec8bec1d4ec1d70109ea))
+* update target paths in registry.json and use-criteria.json for improved file structure ([d2f9348](https://github.com/tarcisioandrade/rich-domain/commit/d2f93486158e465d8878d92f1d80e259cc62f701))
+
+
+### Refactoring
+
+* criteria adapter in fastify-with-prisma example ([8adef1e](https://github.com/tarcisioandrade/rich-domain/commit/8adef1e0c62ab94bd3665f91ca6ea29d568ea24f))
+
+## [1.1.0](https://github.com/tarcisioandrade/rich-domain/compare/v1.0.0...v1.1.0) (2025-11-22)
+
+
+### Features
+
+* add examples in monorepo ([2cba30e](https://github.com/tarcisioandrade/rich-domain/commit/2cba30e318be2575b007c8b4f9a00e35561eec5e))
+* add react-with-react-query example ([439589e](https://github.com/tarcisioandrade/rich-domain/commit/439589e1abbc47b1b03efab3b9dde53fe8d6253c))
+* domain execeptions ([e206274](https://github.com/tarcisioandrade/rich-domain/commit/e206274d8a93c09cc91b2c0514be62cb986caaa3))
+* implement useCriteria hook ([c00441a](https://github.com/tarcisioandrade/rich-domain/commit/c00441a105391fd06ef39b8c7e3aa0907c3ff508))
+
+
+### Bug Fixes
+
+* infinite loop when multiples order are add ([2c13dc4](https://github.com/tarcisioandrade/rich-domain/commit/2c13dc472d009bf328ad45222ea1c921f588ff9a))
+* search not working in fromArray PaginatedResult method ([b79b2aa](https://github.com/tarcisioandrade/rich-domain/commit/b79b2aa2aa17e8b98bf2c2fcb4823452db99dcc1))
+
+
+### Refactoring
+
+* clean exports ([3f8e16a](https://github.com/tarcisioandrade/rich-domain/commit/3f8e16a2103514ef7a2a928dff20f674d1e39506))
+* migrate eslint configuration to ES module syntax ([3ea4366](https://github.com/tarcisioandrade/rich-domain/commit/3ea43667b0857b7ae2afcbad858c16384035dc50))
+* monorepo implementation ([e0b1e68](https://github.com/tarcisioandrade/rich-domain/commit/e0b1e683d5ee95b54b79510d43dd957af49c65e2))
+* remove defaultValues from value objects ([0523479](https://github.com/tarcisioandrade/rich-domain/commit/0523479c6f272d7ea5d678638fa666e3fde71c7a))
+* streamline domain event imports and consolidate IDomainEvent interface ([573c689](https://github.com/tarcisioandrade/rich-domain/commit/573c689a762baecd9fb8791e66300f663d7a58c1))
+
+
+### Chores
+
+* add postinstall script to generate Prisma client ([ffbe310](https://github.com/tarcisioandrade/rich-domain/commit/ffbe310db4ff9e6918d4e55096b8939c1f8f4543))
+* enhance linting setup for react-rich-domain and update package.json ([ac2803b](https://github.com/tarcisioandrade/rich-domain/commit/ac2803bac0d907c0513d249fc5e14390418c7530))
+* modify check script to target specific workspace ([d39d6d8](https://github.com/tarcisioandrade/rich-domain/commit/d39d6d8ef3a04d17207a3a0e795027040b3cf707))
+* update clean script to remove node_modules in backend and rich-domain packages ([2a10cab](https://github.com/tarcisioandrade/rich-domain/commit/2a10cab193ba00e504a9a301cc00cda4b68b8573))
+* update module entry points in package.json for react-rich-domain ([03be9ac](https://github.com/tarcisioandrade/rich-domain/commit/03be9aced05160c97eb74f771b770283c07e046b))
+* update package configuration and add new dependencies ([4135393](https://github.com/tarcisioandrade/rich-domain/commit/4135393ae78b1b8e6b0c9306f0ac0872971ddb3f))
+* update package.json scripts to target specific workspace ([8f46868](https://github.com/tarcisioandrade/rich-domain/commit/8f468688017f49cae58dff5d1a9818fe64b38017))
+* update package.json with homepage and repository detail ([bfb387c](https://github.com/tarcisioandrade/rich-domain/commit/bfb387cb2076989a808f25be09337a24ed3a8ff6))
+* update test script to target specific workspace ([6783208](https://github.com/tarcisioandrade/rich-domain/commit/678320803828a43ef588c366e59bf62c2851c126))

package/dist/aggregate-changes.d.ts

@@ -0,0 +1,164 @@
+import { Operation, CreateOperation, UpdateOperation, DeleteOperation, BatchOperations } from "./types/change-tracker";
+import { EntityChanges } from "./entity-changes";
+/**
+ * Manages and organizes the changes of an Aggregate.
+ *
+ * Responsibilities:
+ * - Stores all operations (create, update, delete)
+ * - Orders operations respecting FK dependencies
+ * - Groups operations by entity for batch execution
+ * - Provides query and iteration methods
+ *
+ * @example
+ * ```typescript
+ * // Define an entity map for type-safe operations
+ * type UserEntities = {
+ *   User: User;
+ *   Post: Post;
+ *   Comment: Comment;
+ * };
+ *
+ * // Getting changes with types
+ * const changes = user.getChanges<UserEntities>();
+ *
+ * // Filtering by entity with autocompletion
+ * const postChanges = changes.for('Post'); // 'Post' autocompletes
+ * postChanges.creates.forEach(post => {
+ *   console.log(post.title); // 'post' is typed as Post
+ * });
+ * ```
+ */
+export declare class AggregateChanges<TEntityMap = Record<string, any>> {
+    private ops;
+    constructor(operations?: Operation[]);
+    /**
+     * Adds a create operation.
+     */
+    addCreate<T>(entity: string, data: T, depth: number, parentId?: string, parentEntity?: string): void;
+    /**
+     * Adds an update operation.
+     */
+    addUpdate<T>(entity: string, id: string, data: T, changedFields: Record<string, any>, depth: number): void;
+    /**
+     * Adds a delete operation.
+     */
+    addDelete<T>(entity: string, id: string, data: T, depth: number): void;
+    /**
+     * Returns all create operations, sorted by ascending depth (root → leaf).
+     */
+    creates(): CreateOperation[];
+    /**
+     * Returns all update operations.
+     */
+    updates(): UpdateOperation[];
+    /**
+     * Returns all delete operations, sorted by descending depth (leaf → root).
+     */
+    deletes(): DeleteOperation[];
+    /**
+     * Iterator that returns operations in the correct execution order:
+     * 1. Deletes (leaf → root)
+     * 2. Creates (root → leaf)
+     * 3. Updates
+     */
+    operations(): Generator<Operation>;
+    /**
+     * Returns all operations as an array in execution order.
+     */
+    toArray(): Operation[];
+    /**
+     * Converts the changes into BatchOperations for optimized execution.
+     *
+     * Groups operations by entity and sorts by depth:
+     * - Deletes: depth DESC (leaf → root)
+     * - Creates: depth ASC (root → leaf)
+     * - Updates: grouped by entity
+     *
+     * @example
+     * ```typescript
+     * const batch = changes.toBatchOperations();
+     *
+     * // Run deletes
+     * for (const del of batch.deletes) {
+     *   await tx[del.entity].deleteMany({ where: { id: { in: del.ids } } });
+     * }
+     *
+     * // Run creates
+     * for (const create of batch.creates) {
+     *   await tx[create.entity].createMany({ data: create.items });
+     * }
+     * ```
+     */
+    toBatchOperations(): BatchOperations;
+    /**
+     * Groups deletes by entity, sorted by descending depth.
+     */
+    private groupDeletes;
+    /**
+     * Groups creates by entity, sorted by ascending depth.
+     */
+    private groupCreates;
+    /**
+     * Groups updates by entity.
+     */
+    private groupUpdates;
+    /**
+     * Filters changes by entity name.
+     *
+     * @param entityName - Name of the entity (e.g., 'Post', 'Comment')
+     * @returns EntityChanges containing only the operations for this entity
+     *
+     * @example
+     * ```typescript
+     * const postChanges = changes.for('Post');
+     *
+     * if (postChanges.hasCreates()) {
+     *   postChanges.creates.forEach(post => {
+     *     console.log('New post:', post.title);
+     *   });
+     * }
+     * ```
+     */
+    for<K extends keyof TEntityMap>(entityName: K): EntityChanges<TEntityMap[K]>;
+    /**
+     * Checks if there are create operations.
+     */
+    hasCreates(): boolean;
+    /**
+     * Checks if there are update operations.
+     */
+    hasUpdates(): boolean;
+    /**
+     * Checks if there are delete operations.
+     */
+    hasDeletes(): boolean;
+    /**
+     * Checks if there are any operations.
+     */
+    hasChanges(): boolean;
+    /**
+     * Checks if there are no operations.
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns the total number of operations.
+     */
+    get count(): number;
+    /**
+     * Returns the raw operations (for debug/testing).
+     */
+    get rawOperations(): Operation[];
+    /**
+     * Lists all entities that have changes.
+     */
+    getAffectedEntities(): string[];
+    /**
+     * Clears all operations.
+     */
+    clear(): void;
+    /**
+     * Creates a copy of the changes.
+     */
+    clone(): AggregateChanges<TEntityMap>;
+}
+//# sourceMappingURL=aggregate-changes.d.ts.map

package/dist/aggregate-changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-changes.d.ts","sourceRoot":"","sources":["../src/aggregate-changes.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,eAAe,EACf,eAAe,EACf,eAAe,EACf,eAAe,EAGhB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,gBAAgB,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC5D,OAAO,CAAC,GAAG,CAAmB;gBAElB,UAAU,GAAE,SAAS,EAAO;IAIxC;;OAEG;IACH,SAAS,CAAC,CAAC,EACT,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI;IAWP;;OAEG;IACH,SAAS,CAAC,CAAC,EACT,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,CAAC,EACP,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,KAAK,EAAE,MAAM,GACZ,IAAI;IAWP;;OAEG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAUtE;;OAEG;IACH,OAAO,IAAI,eAAe,EAAE;IAM5B;;OAEG;IACH,OAAO,IAAI,eAAe,EAAE;IAI5B;;OAEG;IACH,OAAO,IAAI,eAAe,EAAE;IAM5B;;;;;OAKG;IACF,UAAU,IAAI,SAAS,CAAC,SAAS,CAAC;IAMnC;;OAEG;IACH,OAAO,IAAI,SAAS,EAAE;IAItB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,IAAI,eAAe;IAQpC;;OAEG;IACH,OAAO,CAAC,YAAY;IAgBpB;;OAEG;IACH,OAAO,CAAC,YAAY;IAsBpB;;OAEG;IACH,OAAO,CAAC,YAAY;IAoBpB;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,UAAU,EAAE,UAAU,EAAE,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAK5E;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,SAAS,EAAE,CAE/B;IAED;;OAEG;IACH,mBAAmB,IAAI,MAAM,EAAE;IAM/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,KAAK,IAAI,gBAAgB,CAAC,UAAU,CAAC;CAGtC"}

package/dist/aggregate-changes.js

@@ -0,0 +1,281 @@
+import { EntityChanges } from "./entity-changes";
+/**
+ * Manages and organizes the changes of an Aggregate.
+ *
+ * Responsibilities:
+ * - Stores all operations (create, update, delete)
+ * - Orders operations respecting FK dependencies
+ * - Groups operations by entity for batch execution
+ * - Provides query and iteration methods
+ *
+ * @example
+ * ```typescript
+ * // Define an entity map for type-safe operations
+ * type UserEntities = {
+ *   User: User;
+ *   Post: Post;
+ *   Comment: Comment;
+ * };
+ *
+ * // Getting changes with types
+ * const changes = user.getChanges<UserEntities>();
+ *
+ * // Filtering by entity with autocompletion
+ * const postChanges = changes.for('Post'); // 'Post' autocompletes
+ * postChanges.creates.forEach(post => {
+ *   console.log(post.title); // 'post' is typed as Post
+ * });
+ * ```
+ */
+export class AggregateChanges {
+    constructor(operations = []) {
+        this.ops = [];
+        this.ops = [...operations];
+    }
+    /**
+     * Adds a create operation.
+     */
+    addCreate(entity, data, depth, parentId, parentEntity) {
+        this.ops.push({
+            type: "create",
+            entity,
+            data,
+            depth,
+            parentId,
+            parentEntity,
+        });
+    }
+    /**
+     * Adds an update operation.
+     */
+    addUpdate(entity, id, data, changedFields, depth) {
+        this.ops.push({
+            type: "update",
+            entity,
+            id,
+            data,
+            changedFields,
+            depth,
+        });
+    }
+    /**
+     * Adds a delete operation.
+     */
+    addDelete(entity, id, data, depth) {
+        this.ops.push({
+            type: "delete",
+            entity,
+            id,
+            data,
+            depth,
+        });
+    }
+    /**
+     * Returns all create operations, sorted by ascending depth (root → leaf).
+     */
+    creates() {
+        return this.ops
+            .filter((op) => op.type === "create")
+            .sort((a, b) => a.depth - b.depth);
+    }
+    /**
+     * Returns all update operations.
+     */
+    updates() {
+        return this.ops.filter((op) => op.type === "update");
+    }
+    /**
+     * Returns all delete operations, sorted by descending depth (leaf → root).
+     */
+    deletes() {
+        return this.ops
+            .filter((op) => op.type === "delete")
+            .sort((a, b) => b.depth - a.depth);
+    }
+    /**
+     * Iterator that returns operations in the correct execution order:
+     * 1. Deletes (leaf → root)
+     * 2. Creates (root → leaf)
+     * 3. Updates
+     */
+    *operations() {
+        yield* this.deletes();
+        yield* this.creates();
+        yield* this.updates();
+    }
+    /**
+     * Returns all operations as an array in execution order.
+     */
+    toArray() {
+        return [...this.operations()];
+    }
+    /**
+     * Converts the changes into BatchOperations for optimized execution.
+     *
+     * Groups operations by entity and sorts by depth:
+     * - Deletes: depth DESC (leaf → root)
+     * - Creates: depth ASC (root → leaf)
+     * - Updates: grouped by entity
+     *
+     * @example
+     * ```typescript
+     * const batch = changes.toBatchOperations();
+     *
+     * // Run deletes
+     * for (const del of batch.deletes) {
+     *   await tx[del.entity].deleteMany({ where: { id: { in: del.ids } } });
+     * }
+     *
+     * // Run creates
+     * for (const create of batch.creates) {
+     *   await tx[create.entity].createMany({ data: create.items });
+     * }
+     * ```
+     */
+    toBatchOperations() {
+        return {
+            deletes: this.groupDeletes(),
+            creates: this.groupCreates(),
+            updates: this.groupUpdates(),
+        };
+    }
+    /**
+     * Groups deletes by entity, sorted by descending depth.
+     */
+    groupDeletes() {
+        const deleteOps = this.deletes();
+        const grouped = new Map();
+        for (const op of deleteOps) {
+            if (!grouped.has(op.entity)) {
+                grouped.set(op.entity, { depth: op.depth, ids: [] });
+            }
+            grouped.get(op.entity).ids.push(op.id);
+        }
+        return Array.from(grouped.entries())
+            .map(([entity, { depth, ids }]) => ({ entity, depth, ids }))
+            .sort((a, b) => b.depth - a.depth);
+    }
+    /**
+     * Groups creates by entity, sorted by ascending depth.
+     */
+    groupCreates() {
+        const createOps = this.creates();
+        const grouped = new Map();
+        for (const op of createOps) {
+            if (!grouped.has(op.entity)) {
+                grouped.set(op.entity, { depth: op.depth, items: [] });
+            }
+            grouped.get(op.entity).items.push({
+                data: op.data,
+                parentId: op.parentId,
+            });
+        }
+        return Array.from(grouped.entries())
+            .map(([entity, { depth, items }]) => ({ entity, depth, items }))
+            .sort((a, b) => a.depth - b.depth);
+    }
+    /**
+     * Groups updates by entity.
+     */
+    groupUpdates() {
+        const updateOps = this.updates();
+        const grouped = new Map();
+        for (const op of updateOps) {
+            if (!grouped.has(op.entity)) {
+                grouped.set(op.entity, []);
+            }
+            grouped.get(op.entity).push({
+                id: op.id,
+                changedFields: op.changedFields,
+            });
+        }
+        return Array.from(grouped.entries()).map(([entity, items]) => ({
+            entity,
+            items,
+        }));
+    }
+    /**
+     * Filters changes by entity name.
+     *
+     * @param entityName - Name of the entity (e.g., 'Post', 'Comment')
+     * @returns EntityChanges containing only the operations for this entity
+     *
+     * @example
+     * ```typescript
+     * const postChanges = changes.for('Post');
+     *
+     * if (postChanges.hasCreates()) {
+     *   postChanges.creates.forEach(post => {
+     *     console.log('New post:', post.title);
+     *   });
+     * }
+     * ```
+     */
+    for(entityName) {
+        const filtered = this.ops.filter((op) => op.entity === entityName);
+        return new EntityChanges(filtered);
+    }
+    /**
+     * Checks if there are create operations.
+     */
+    hasCreates() {
+        return this.ops.some((op) => op.type === "create");
+    }
+    /**
+     * Checks if there are update operations.
+     */
+    hasUpdates() {
+        return this.ops.some((op) => op.type === "update");
+    }
+    /**
+     * Checks if there are delete operations.
+     */
+    hasDeletes() {
+        return this.ops.some((op) => op.type === "delete");
+    }
+    /**
+     * Checks if there are any operations.
+     */
+    hasChanges() {
+        return this.ops.length > 0;
+    }
+    /**
+     * Checks if there are no operations.
+     */
+    isEmpty() {
+        return this.ops.length === 0;
+    }
+    /**
+     * Returns the total number of operations.
+     */
+    get count() {
+        return this.ops.length;
+    }
+    /**
+     * Returns the raw operations (for debug/testing).
+     */
+    get rawOperations() {
+        return [...this.ops];
+    }
+    /**
+     * Lists all entities that have changes.
+     */
+    getAffectedEntities() {
+        const entities = new Set();
+        this.ops.forEach((op) => entities.add(op.entity));
+        return Array.from(entities);
+    }
+    /**
+     * Clears all operations.
+     */
+    clear() {
+        this.ops = [];
+    }
+    /**
+     * Creates a copy of the changes.
+     */
+    clone() {
+        return new AggregateChanges([...this.ops]);
+    }
+}
+//# sourceMappingURL=aggregate-changes.js.map

package/dist/aggregate-changes.js.map

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

package/dist/base-entity.d.ts

@@ -1,11 +1,12 @@
 import { Id } from "./id";
 import { ValidationError } from "./validation-error";
 import { IDomainEvent } from ".";
-import { BaseProps, SubscriptionConfig, HistoryEntry, DeepJsonResult, EntityHooks, EntityValidation } from "./types";
+import { BaseProps, HistoryEntry, DeepJsonResult, EntityHooks, EntityValidation } from "./types";
 import { DomainEventBus } from "./domain-event-bus";
+import { AggregateChanges } from "./aggregate-changes";
 export declare abstract class BaseEntity<T extends BaseProps> {
     private _props;
-    private proxy;
+    private tracker;
     private proxiedProps;
     private snapshot;
     private validationConfig;
@@ -19,6 +20,10 @@ export declare abstract class BaseEntity<T extends BaseProps> {
     });
     private validateProps;
     private extractPathKey;
+    /**
+     * Setup validation that runs on every property change.
+     * Uses the HistoryTracker's onChangeValidator callback.
+     */
     private setupUpdateValidation;
     private takeSnapshot;
     private deepCloneProps;
@@ -26,10 +31,6 @@ export declare abstract class BaseEntity<T extends BaseProps> {
     isNew(): boolean;
     /**
      * Check equality with another entity by comparing IDs
-     * Entities are equal if they have the same ID, regardless of other properties
-     *
-     * @param other - Another entity or an ID to compare with
-     * @returns true if entities have the same ID
      */
     equals(other: BaseEntity<T> | Id | string): boolean;
     get props(): T;
@@ -41,13 +42,36 @@ export declare abstract class BaseEntity<T extends BaseProps> {
      * Get validation errors (when throwOnError is false)
      */
     get validationErrors(): ValidationError | undefined;
-    subscribe(config: SubscriptionConfig<T>): void;
+    /**
+     * Returns all detected changes as AggregateChanges.
+     *
+     * @example
+     * ```typescript
+     * const changes = user.getChanges();
+     * const batch = changes.toBatchOperations();
+     *
+     * for (const del of batch.deletes) { ... }
+     * for (const create of batch.creates) { ... }
+     * for (const upd of batch.updates) { ... }
+     * ```
+     */
+    getChanges<TEntityMap = Record<string, any>>(): AggregateChanges<TEntityMap>;
+    /**
+     * Returns the change history (for debugging).
+     */
     getHistory(): HistoryEntry[];
-    clearHistory(): void;
+    /**
+     * Clears history and marks entity as "clean".
+     * Call this after successfully persisting to the database.
+     */
+    markAsClean(): void;
     /**
      * Add a domain event to this entity
      */
     protected addDomainEvent(event: IDomainEvent): void;
+    /**
+     * Dispatch all events through the event bus
+     */
     dispatchAll(bus: DomainEventBus): Promise<void>;
     /**
      * Get all uncommitted domain events