@woltz/rich-domain 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 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.2.1](https://github.com/tarcisioandrade/rich-domain/compare/v1.2.0...v1.2.1) (2025-11-29)
+
+
+### Features
+
+* 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
+
+* 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
+
+* 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)
 
 

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

package/dist/base-entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-entity.d.ts","sourceRoot":"","sources":["../src/base-entity.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;AAE1B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,CAAC;AACjC,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,WAAW,EAGX,gBAAgB,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAYpD,8BAAsB,UAAU,CAAC,CAAC,SAAS,SAAS;IAClD,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,WAAW,CAAC,CAAsB;IAC1C,OAAO,CAAC,YAAY,CAAC,CAAoB;IACzC,OAAO,CAAC,YAAY,CAAsB;IAG1C,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpD,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAEnC,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,EAAE,CAAA;KAAE;IAsD9C,OAAO,CAAC,aAAa;IA4BrB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,qBAAqB;IAuE7B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAwDtB,IAAI,EAAE,IAAI,EAAE,CAEX;IAEM,KAAK,IAAI,OAAO;IAIvB;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,MAAM,GAAG,OAAO;IAuBnD,IAAW,KAAK,IAAI,CAAC,CAEpB;IAED;;OAEG;IACH,IAAI,mBAAmB,IAAI,OAAO,CAEjC;IAED;;OAEG;IACH,IAAI,gBAAgB,IAAI,eAAe,GAAG,SAAS,CAElD;IAED,SAAS,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,IAAI;IAS9C,UAAU,IAAI,YAAY,EAAE;IAI5B,YAAY,IAAI,IAAI;IAIpB;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAItC,WAAW,CAAC,GAAG,EAAE,cAAc;IAI5C;;OAEG;IACH,oBAAoB,IAAI,YAAY,EAAE;IAItC;;OAEG;IACH,WAAW,IAAI,IAAI;IAInB;;OAEG;IACH,oBAAoB,IAAI,OAAO;IAI/B,MAAM,IAAI,cAAc,CAAC,CAAC,CAAC;IAI3B,OAAO,CAAC,UAAU;CAgBnB"}
+{"version":3,"file":"base-entity.d.ts","sourceRoot":"","sources":["../src/base-entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,CAAC;AACjC,OAAO,EACL,SAAS,EACT,YAAY,EACZ,cAAc,EACd,WAAW,EAGX,gBAAgB,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAUvD,8BAAsB,UAAU,CAAC,CAAC,SAAS,SAAS;IAClD,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,WAAW,CAAC,CAAsB;IAC1C,OAAO,CAAC,YAAY,CAAC,CAAoB;IACzC,OAAO,CAAC,YAAY,CAAsB;IAG1C,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpD,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAEnC,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,EAAE,CAAA;KAAE;IA6D9C,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,cAAc;IAgBtB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAqF7B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAkDtB,IAAI,EAAE,IAAI,EAAE,CAEX;IAEM,KAAK,IAAI,OAAO;IAIvB;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,MAAM,GAAG,OAAO;IAwBnD,IAAW,KAAK,IAAI,CAAC,CAEpB;IAED;;OAEG;IACH,IAAI,mBAAmB,IAAI,OAAO,CAEjC;IAED;;OAEG;IACH,IAAI,gBAAgB,IAAI,eAAe,GAAG,SAAS,CAElD;IAMD;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,gBAAgB,CAAC,UAAU,CAAC;IAI5E;;OAEG;IACH,UAAU,IAAI,YAAY,EAAE;IAI5B;;;OAGG;IACH,WAAW,IAAI,IAAI;IASnB;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAInD;;OAEG;IACU,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D;;OAEG;IACH,oBAAoB,IAAI,YAAY,EAAE;IAItC;;OAEG;IACH,WAAW,IAAI,IAAI;IAInB;;OAEG;IACH,oBAAoB,IAAI,OAAO;IAQ/B,MAAM,IAAI,cAAc,CAAC,CAAC,CAAC;IAI3B,OAAO,CAAC,UAAU;CAgBnB"}