@woltz/rich-domain 1.2.0 → 1.2.2

package/dist/types/utils.d.ts

@@ -6,7 +6,6 @@ export type DeepJsonResult<T> = {
         toJson(): infer V;
     } ? V[] : U extends Id ? string[] : U[] : T[K];
 };
-export type DeepKeyOf<T, K extends keyof T = keyof T> = K extends string ? T[K] extends Primitive ? K : T[K] extends object ? `${K}` | `${K}.${DeepKeyOf<T[K]>}` : never : never;
 export type Primitive = string | number | boolean | Date | null | undefined;
 export type UnwrapArray<T> = T extends Array<infer U> ? U : never;
 export type IsArray<T> = T extends Array<any> ? true : false;

package/dist/types/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/types/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAE3B,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;KAC7B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,GAC3B,MAAM,GACN,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,MAAM,IAAI,MAAM,CAAC,CAAA;KAAE,GAClC,CAAC,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAC3B,CAAC,SAAS;QAAE,MAAM,IAAI,MAAM,CAAC,CAAA;KAAE,GAC7B,CAAC,EAAE,GACH,CAAC,SAAS,EAAE,GACZ,MAAM,EAAE,GACR,CAAC,EAAE,GACL,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,MAAM,GACpE,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,GACpB,CAAC,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACnB,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAClC,KAAK,GACP,KAAK,CAAC;AAEV,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;AAE5E,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAClE,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAC7D,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,GAAG,KAAK,GAAG,CAAC,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/types/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAE3B,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;KAC7B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,GAC3B,MAAM,GACN,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,MAAM,IAAI,MAAM,CAAC,CAAA;KAAE,GAClC,CAAC,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAC3B,CAAC,SAAS;QAAE,MAAM,IAAI,MAAM,CAAC,CAAA;KAAE,GAC7B,CAAC,EAAE,GACH,CAAC,SAAS,EAAE,GACZ,MAAM,EAAE,GACR,CAAC,EAAE,GACL,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;AAC5E,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAClE,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAC7D,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,GAAG,KAAK,GAAG,CAAC,CAAC"}

package/dist/utils/criteria-operator-validation.d.ts

@@ -1,4 +1,5 @@
 import { FilterOperator } from "../types";
+export declare function sanitizeFieldValue(value: unknown, operator: FilterOperator): unknown;
 export declare function isValidOperatorForType(value: unknown, operator: FilterOperator): boolean;
 export declare function getValidOperatorsForType(value: unknown): FilterOperator[];
 export declare function isOperator(value: string): value is FilterOperator;

package/dist/utils/criteria-operator-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"criteria-operator-validation.d.ts","sourceRoot":"","sources":["../../src/utils/criteria-operator-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,cAAc,EAGf,MAAM,UAAU,CAAC;AAElB,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,cAAc,GACvB,OAAO,CAyFT;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,EAAE,CA8DzE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAEjE"}
+{"version":3,"file":"criteria-operator-validation.d.ts","sourceRoot":"","sources":["../../src/utils/criteria-operator-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,cAAc,EAGf,MAAM,UAAU,CAAC;AAIlB,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,cAAc,GACvB,OAAO,CAsCT;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,cAAc,GACvB,OAAO,CAkFT;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,EAAE,CA8DzE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAEjE"}

package/dist/utils/criteria-operator-validation.js

@@ -1,20 +1,47 @@
 import { FILTER_OPERATORS, } from "../types";
-export function isValidOperatorForType(value, operator) {
-    // Handle null/undefined
+const FORCE_STRING_OPERATORS = new Set(["contains", "startsWith", "endsWith"]);
+export function sanitizeFieldValue(value, operator) {
     if (value === null || value === undefined) {
-        return ["isNull", "isNotNull", "equals", "notEquals"].includes(operator);
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeFieldValue(item, operator));
+    }
+    if (value instanceof Date) {
+        return value;
+    }
+    const stringValue = String(value).trim();
+    if (stringValue === "") {
+        return "";
+    }
+    if (operator && FORCE_STRING_OPERATORS.has(operator)) {
+        return stringValue;
+    }
+    if (stringValue === "true" || stringValue === "false") {
+        return stringValue === "true";
     }
-    // Special case: between operator with array [min, max]
-    if (operator === "between" && Array.isArray(value) && value.length === 2) {
-        // Validate based on the type of the first element
-        const elementType = typeof value[0];
-        if (elementType === "number" || value[0] instanceof Date) {
+    const numberValue = Number(stringValue);
+    if (!Number.isNaN(numberValue)) {
+        return numberValue;
+    }
+    const dateObj = new Date(stringValue);
+    if (!Number.isNaN(dateObj.getTime())) {
+        return dateObj;
+    }
+    return stringValue;
+}
+export function isValidOperatorForType(value, operator) {
+    const sanitizedValue = sanitizeFieldValue(value, operator);
+    if (operator === "between" &&
+        Array.isArray(sanitizedValue) &&
+        sanitizedValue.length === 2) {
+        const elementType = typeof sanitizedValue[0];
+        if (elementType === "number" || sanitizedValue[0] instanceof Date) {
             return true;
         }
         return false;
     }
-    const valueType = typeof value;
-    // String operators
+    const valueType = typeof sanitizedValue;
     if (valueType === "string") {
         const validOps = [
             "equals",
@@ -29,7 +56,6 @@ export function isValidOperatorForType(value, operator) {
         ];
         return validOps.includes(operator);
     }
-    // Number operators
     if (valueType === "number") {
         const validOps = [
             "equals",
@@ -46,7 +72,6 @@ export function isValidOperatorForType(value, operator) {
         ];
         return validOps.includes(operator);
     }
-    // Boolean operators
     if (valueType === "boolean") {
         const validOps = [
             "equals",
@@ -56,8 +81,7 @@ export function isValidOperatorForType(value, operator) {
         ];
         return validOps.includes(operator);
     }
-    // Date operators
-    if (value instanceof Date) {
+    if (sanitizedValue instanceof Date) {
         const validOps = [
             "equals",
             "notEquals",
@@ -73,12 +97,10 @@ export function isValidOperatorForType(value, operator) {
         ];
         return validOps.includes(operator);
     }
-    // Array operators
-    if (Array.isArray(value)) {
+    if (Array.isArray(sanitizedValue)) {
         const validOps = ["in", "notIn", "isNull", "isNotNull"];
         return validOps.includes(operator);
     }
-    // For unknown types, allow all operators
     return true;
 }
 export function getValidOperatorsForType(value) {

package/dist/utils/criteria-operator-validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"criteria-operator-validation.js","sourceRoot":"","sources":["../../src/utils/criteria-operator-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,gBAAgB,GAIjB,MAAM,UAAU,CAAC;AAElB,MAAM,UAAU,sBAAsB,CACpC,KAAc,EACd,QAAwB;IAExB,wBAAwB;IACxB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC3E,CAAC;IAED,uDAAuD;IACvD,IAAI,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzE,kDAAkD;QAClD,MAAM,WAAW,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,YAAY,IAAI,EAAE,CAAC;YACzD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;IAE/B,mBAAmB;IACnB,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAsB;YAClC,QAAQ;YACR,WAAW;YACX,UAAU;YACV,YAAY;YACZ,UAAU;YACV,IAAI;YACJ,OAAO;YACP,QAAQ;YACR,WAAW;SACZ,CAAC;QACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAA2B,CAAC,CAAC;IACxD,CAAC;IAED,mBAAmB;IACnB,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAsB;YAClC,QAAQ;YACR,WAAW;YACX,aAAa;YACb,oBAAoB;YACpB,UAAU;YACV,iBAAiB;YACjB,IAAI;YACJ,OAAO;YACP,SAAS;YACT,QAAQ;YACR,WAAW;SACZ,CAAC;QACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAA2B,CAAC,CAAC;IACxD,CAAC;IAED,oBAAoB;IACpB,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAuB;YACnC,QAAQ;YACR,WAAW;YACX,QAAQ;YACR,WAAW;SACZ,CAAC;QACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAA4B,CAAC,CAAC;IACzD,CAAC;IAED,iBAAiB;IACjB,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAoB;YAChC,QAAQ;YACR,WAAW;YACX,aAAa;YACb,oBAAoB;YACpB,UAAU;YACV,iBAAiB;YACjB,IAAI;YACJ,OAAO;YACP,SAAS;YACT,QAAQ;YACR,WAAW;SACZ,CAAC;QACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAAyB,CAAC,CAAC;IACtD,CAAC;IAED,kBAAkB;IAClB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC1E,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAA0B,CAAC,CAAC;IACvD,CAAC;IAED,yCAAyC;IACzC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;IAE/B,IAAI,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAC1D,OAAO;YACL,QAAQ;YACR,WAAW;YACX,UAAU;YACV,YAAY;YACZ,UAAU;YACV,IAAI;YACJ,OAAO;YACP,QAAQ;YACR,WAAW;SACZ,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO;YACL,QAAQ;YACR,WAAW;YACX,aAAa;YACb,oBAAoB;YACpB,UAAU;YACV,iBAAiB;YACjB,IAAI;YACJ,OAAO;YACP,SAAS;YACT,QAAQ;YACR,WAAW;SACZ,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,OAAO;YACL,QAAQ;YACR,WAAW;YACX,aAAa;YACb,oBAAoB;YACpB,UAAU;YACV,iBAAiB;YACjB,IAAI;YACJ,OAAO;YACP,SAAS;YACT,QAAQ;YACR,WAAW;SACZ,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,CAAC,GAAG,gBAAgB,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,gBAAgB,CAAC,QAAQ,CAAC,KAAuB,CAAC,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"criteria-operator-validation.js","sourceRoot":"","sources":["../../src/utils/criteria-operator-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,gBAAgB,GAIjB,MAAM,UAAU,CAAC;AAElB,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC;AAE/E,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,QAAwB;IAExB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,QAAQ,IAAI,sBAAsB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,WAAW,KAAK,MAAM,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;QACtD,OAAO,WAAW,KAAK,MAAM,CAAC;IAChC,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,KAAc,EACd,QAAwB;IAExB,MAAM,cAAc,GAAG,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE3D,IACE,QAAQ,KAAK,SAAS;QACtB,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC;QAC7B,cAAc,CAAC,MAAM,KAAK,CAAC,EAC3B,CAAC;QACD,MAAM,WAAW,GAAG,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC;QAC7C,IAAI,WAAW,KAAK,QAAQ,IAAI,cAAc,CAAC,CAAC,CAAC,YAAY,IAAI,EAAE,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,cAAc,CAAC;IAExC,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAsB;YAClC,QAAQ;YACR,WAAW;YACX,UAAU;YACV,YAAY;YACZ,UAAU;YACV,IAAI;YACJ,OAAO;YACP,QAAQ;YACR,WAAW;SACZ,CAAC;QACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAA2B,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAsB;YAClC,QAAQ;YACR,WAAW;YACX,aAAa;YACb,oBAAoB;YACpB,UAAU;YACV,iBAAiB;YACjB,IAAI;YACJ,OAAO;YACP,SAAS;YACT,QAAQ;YACR,WAAW;SACZ,CAAC;QACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAA2B,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAuB;YACnC,QAAQ;YACR,WAAW;YACX,QAAQ;YACR,WAAW;SACZ,CAAC;QACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAA4B,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,cAAc,YAAY,IAAI,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAoB;YAChC,QAAQ;YACR,WAAW;YACX,aAAa;YACb,oBAAoB;YACpB,UAAU;YACV,iBAAiB;YACjB,IAAI;YACJ,OAAO;YACP,SAAS;YACT,QAAQ;YACR,WAAW;SACZ,CAAC;QACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAAyB,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC1E,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAA0B,CAAC,CAAC;IACvD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;IAE/B,IAAI,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAC1D,OAAO;YACL,QAAQ;YACR,WAAW;YACX,UAAU;YACV,YAAY;YACZ,UAAU;YACV,IAAI;YACJ,OAAO;YACP,QAAQ;YACR,WAAW;SACZ,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO;YACL,QAAQ;YACR,WAAW;YACX,aAAa;YACb,oBAAoB;YACpB,UAAU;YACV,iBAAiB;YACjB,IAAI;YACJ,OAAO;YACP,SAAS;YACT,QAAQ;YACR,WAAW;SACZ,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,OAAO;YACL,QAAQ;YACR,WAAW;YACX,aAAa;YACb,oBAAoB;YACpB,UAAU;YACV,iBAAiB;YACjB,IAAI;YACJ,OAAO;YACP,SAAS;YACT,QAAQ;YACR,WAAW;SACZ,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,CAAC,GAAG,gBAAgB,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,gBAAgB,CAAC,QAAQ,CAAC,KAAuB,CAAC,CAAC;AAC5D,CAAC"}

package/dist/validation-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation-error.d.ts","sourceRoot":"","sources":["../src/validation-error.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1C,SAAgB,mBAAmB,QAAQ;gBAE/B,MAAM,EAAE,eAAe,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM;IAavD;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe;IAalE;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE;IAIjD;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIvC;;OAEG;IACH,MAAM,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,EAAE,CAAA;KAAE;CAOvE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,OAAO,EAAE,MAAM,GACd,eAAe,CAKjB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,OAAO,EAAE,MAAM,GACd,KAAK,CAEP"}
+{"version":3,"file":"validation-error.d.ts","sourceRoot":"","sources":["../src/validation-error.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1C,SAAgB,mBAAmB,QAAQ;gBAE/B,MAAM,EAAE,eAAe,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM;IAYvD;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe;IAYlE;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE;IAIjD;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIvC;;OAEG;IACH,MAAM,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,EAAE,CAAA;KAAE;CAOvE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,OAAO,EAAE,MAAM,GACd,eAAe,CAKjB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,OAAO,EAAE,MAAM,GACd,KAAK,CAEP"}

package/dist/validation-error.js

@@ -1,14 +1,10 @@
-// ============================================================================
-// Validation Error - Domain Validation Errors
-// ============================================================================
 export class ValidationError extends Error {
     constructor(issues, message) {
         const errorMessage = message || `Validation failed: ${issues.map(i => i.message).join(', ')}`;
         super(errorMessage);
-        this.__isValidationError = true; // Brand for identification
+        this.__isValidationError = true;
         this.name = 'ValidationError';
         this.issues = issues;
-        // Maintain proper stack trace
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, ValidationError);
         }
@@ -20,7 +16,6 @@ export class ValidationError extends Error {
         if (error instanceof ValidationError) {
             return true;
         }
-        // Check by duck typing for cross-module compatibility
         return (error instanceof Error &&
             error.name === 'ValidationError' &&
             'issues' in error &&

package/dist/validation-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation-error.js","sourceRoot":"","sources":["../src/validation-error.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8CAA8C;AAC9C,+EAA+E;AAO/E,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAIxC,YAAY,MAAyB,EAAE,OAAgB;QACrD,MAAM,YAAY,GAChB,OAAO,IAAI,sBAAsB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3E,KAAK,CAAC,YAAY,CAAC,CAAC;QALN,wBAAmB,GAAG,IAAI,CAAC,CAAC,2BAA2B;QAMrE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,8BAA8B;QAC9B,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAc;QACrC,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,sDAAsD;QACtD,OAAO,CACL,KAAK,YAAY,KAAK;YACtB,KAAK,CAAC,IAAI,KAAK,iBAAiB;YAChC,QAAQ,IAAI,KAAK;YACjB,KAAK,CAAC,OAAO,CAAE,KAAa,CAAC,MAAM,CAAC,CACrC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,IAAY;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,IAAY;QAC3B,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAuB,EACvB,OAAe;IAEf,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;QAClD,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAuB,EACvB,OAAe;IAEf,MAAM,IAAI,eAAe,CAAC,CAAC,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC"}
+{"version":3,"file":"validation-error.js","sourceRoot":"","sources":["../src/validation-error.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAIxC,YAAY,MAAyB,EAAE,OAAgB;QACrD,MAAM,YAAY,GAChB,OAAO,IAAI,sBAAsB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3E,KAAK,CAAC,YAAY,CAAC,CAAC;QALN,wBAAmB,GAAG,IAAI,CAAC;QAMzC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAc;QACrC,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CACL,KAAK,YAAY,KAAK;YACtB,KAAK,CAAC,IAAI,KAAK,iBAAiB;YAChC,QAAQ,IAAI,KAAK;YACjB,KAAK,CAAC,OAAO,CAAE,KAAa,CAAC,MAAM,CAAC,CACrC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,IAAY;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,IAAY;QAC3B,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAuB,EACvB,OAAe;IAEf,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;QAClD,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAuB,EACvB,OAAe;IAEf,MAAM,IAAI,eAAe,CAAC,CAAC,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC"}

package/dist/value-object.d.ts

@@ -1,6 +1,10 @@
 import { ValidationError } from "./validation-error";
 import { IDomainEvent } from ".";
 import { VOHooks, EntityValidation } from "./types";
+/**
+ * Identity key type for a Value Object. Can be a single key or an array of keys (composite key).
+ */
+export type IdentityKeyDefinition<T> = (keyof T)[] | keyof T;
 export declare abstract class ValueObject<T> {
     protected readonly props: T;
     private validationConfig;
@@ -9,38 +13,83 @@ export declare abstract class ValueObject<T> {
     private domainEvents;
     protected static validation?: EntityValidation<any>;
     protected static hooks?: VOHooks<any, any>;
+    /**
+     * Identity key for identification in collections.
+     * Used by ChangeTracker to track changes in arrays of Value Objects.
+     *
+     * @example
+     * ```typescript
+     * // Simple key
+     * class TagReference extends ValueObject<{ tagId: string }> {
+     *   static readonly identityKey = 'tagId';
+     * }
+     *
+     * // Composite key
+     * class Like extends ValueObject<{ postId: string; userId: string }> {
+     *   static readonly identityKey = ['postId', 'userId'];
+     * }
+     * ```
+     */
+    protected static identityKey?: IdentityKeyDefinition<any>;
     constructor(props: T);
     private validateProps;
     private extractPathKey;
     /**
-     * Check if value object has validation errors (when throwOnError is false)
+     * Returns true if the value object has validation errors (when throwOnError is false).
      */
     get hasValidationErrors(): boolean;
     /**
-     * Get validation errors (when throwOnError is false)
+     * Returns the validation errors (when throwOnError is false).
      */
     get validationErrors(): ValidationError | undefined;
+    /**
+     * Compare this ValueObject with another for equality based on their properties.
+     */
     equals(other: ValueObject<T>): boolean;
     /**
-     * Add a domain event to this value object
+     * Returns the identity key for this Value Object.
+     * Used for identification in collections when identityKey is set.
+     *
+     * @returns String with the identity key or null if not defined
+     *
+     * @example
+     * ```typescript
+     * const like = new Like({ postId: 'p1', userId: 'u1' });
+     * like.getIdentityKey(); // 'p1:u1'
+     *
+     * const tag = new TagReference({ tagId: 'tag-123' });
+     * tag.getIdentityKey(); // 'tag-123'
+     * ```
+     */
+    getIdentityKey(): string | null;
+    /**
+     * Returns true if this Value Object has an identity key defined.
+     */
+    hasIdentityKey(): boolean;
+    /**
+     * Returns the identity key definition (if any).
+     */
+    static getIdentityKeyDefinition<P>(): IdentityKeyDefinition<P> | undefined;
+    /**
+     * Adds a domain event to this value object.
      */
     protected addDomainEvent(event: IDomainEvent): void;
     /**
-     * Get all uncommitted domain events
+     * Returns all uncommitted domain events.
      */
     getUncommittedEvents(): IDomainEvent[];
     /**
-     * Clear all domain events (call after publishing)
+     * Clears all domain events (call after publishing).
      */
     clearEvents(): void;
     /**
-     * Check if value object has uncommitted events
+     * Returns true if the value object has uncommitted events.
      */
     hasUncommittedEvents(): boolean;
     toJson(): T;
     /**
-     * Create a new ValueObject with updated properties
-     * Since ValueObjects are immutable, this returns a new instance
+     * Creates a new ValueObject with updated properties.
+     * ValueObjects are immutable, so this returns a new instance.
      */
     protected clone(updates: Partial<T>): this;
 }

package/dist/value-object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-object.d.ts","sourceRoot":"","sources":["../src/value-object.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,CAAC;AACjC,OAAO,EACL,OAAO,EAGP,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAYjB,8BAAsB,WAAW,CAAC,CAAC;IACjC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAG,CAAC,CAAC;IAC7B,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,WAAW,CAAC,CAAkB;IACtC,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,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAE/B,KAAK,EAAE,CAAC;IA2CpB,OAAO,CAAC,aAAa;IA4BrB,OAAO,CAAC,cAAc;IAmBtB;;OAEG;IACH,IAAI,mBAAmB,IAAI,OAAO,CAEjC;IAED;;OAEG;IACH,IAAI,gBAAgB,IAAI,eAAe,GAAG,SAAS,CAElD;IAED,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO;IAKtC;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAInD;;OAEG;IACH,oBAAoB,IAAI,YAAY,EAAE;IAItC;;OAEG;IACH,WAAW,IAAI,IAAI;IAInB;;OAEG;IACH,oBAAoB,IAAI,OAAO;IAI/B,MAAM,IAAI,CAAC;IAIX;;;OAGG;IACH,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;CAI3C"}
+{"version":3,"file":"value-object.d.ts","sourceRoot":"","sources":["../src/value-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,CAAC;AACjC,OAAO,EACL,OAAO,EAGP,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAWjB;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;AAE7D,8BAAsB,WAAW,CAAC,CAAC;IACjC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAG,CAAC,CAAC;IAC7B,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,WAAW,CAAC,CAAkB;IACtC,OAAO,CAAC,YAAY,CAAC,CAAoB;IACzC,OAAO,CAAC,YAAY,CAAsB;IAE1C,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpD,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAE3C;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,qBAAqB,CAAC,GAAG,CAAC,CAAC;gBAE9C,KAAK,EAAE,CAAC;IAqCpB,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,cAAc;IAgBtB;;OAEG;IACH,IAAI,mBAAmB,IAAI,OAAO,CAEjC;IAED;;OAEG;IACH,IAAI,gBAAgB,IAAI,eAAe,GAAG,SAAS,CAElD;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO;IAKtC;;;;;;;;;;;;;;OAcG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAiB/B;;OAEG;IACH,cAAc,IAAI,OAAO;IAOzB;;OAEG;IACH,MAAM,CAAC,wBAAwB,CAAC,CAAC,KAAK,qBAAqB,CAAC,CAAC,CAAC,GAAG,SAAS;IAI1E;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAInD;;OAEG;IACH,oBAAoB,IAAI,YAAY,EAAE;IAItC;;OAEG;IACH,WAAW,IAAI,IAAI;IAInB;;OAEG;IACH,oBAAoB,IAAI,OAAO;IAI/B,MAAM,IAAI,CAAC;IAIX;;;OAGG;IACH,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;CAI3C"}

package/dist/value-object.js

@@ -1,17 +1,12 @@
-// ============================================================================
-// Value Object - Immutable Domain Objects
-// ============================================================================
 import { ValidationError } from "./validation-error";
 import { DEFAULT_VALIDATION_CONFIG } from "./constants";
 import { DomainError } from "./exceptions";
-// Helper to get static properties from constructor
 function getStaticProperty(instance, propertyName) {
     return instance.constructor[propertyName];
 }
 export class ValueObject {
     constructor(props) {
         this.domainEvents = [];
-        // Get static configuration from subclass
         const validation = getStaticProperty(this, "validation");
         const hooks = getStaticProperty(this, "hooks");
         this.domainHooks = hooks;
@@ -23,19 +18,14 @@ export class ValueObject {
             ...validation?.config,
         };
         let finalProps = { ...props };
-        // Validate schema on creation
         if (this.domainSchema && this.validationConfig.onCreate) {
             this.validateProps(finalProps);
         }
-        // Set props (not frozen yet) so rules can access them
         this.props = finalProps;
-        // Execute rules (custom validations) - after props is set but before freezing
         if (hooks?.rules) {
             hooks.rules(this);
         }
-        // Now freeze the props for immutability
         Object.freeze(this.props);
-        // Hook onCreate
         if (hooks?.onCreate) {
             hooks.onCreate(this);
         }
@@ -55,7 +45,6 @@ export class ValueObject {
             if (this.validationConfig.throwOnError) {
                 throw validationError;
             }
-            // If not throwing, store error for later retrieval
             this._validationError = validationError;
         }
     }
@@ -63,57 +52,95 @@ export class ValueObject {
         if (pathSegment === null || pathSegment === undefined) {
             return "";
         }
-        // Handle PropertyKey (string | number | symbol)
         if (typeof pathSegment === "string" || typeof pathSegment === "number") {
             return String(pathSegment);
         }
         if (typeof pathSegment === "symbol") {
             return pathSegment.toString();
         }
-        // Handle object with 'key' property (Zod's PathSegment)
         if (typeof pathSegment === "object" && "key" in pathSegment) {
             return String(pathSegment.key);
         }
-        // Fallback
         return String(pathSegment);
     }
     /**
-     * Check if value object has validation errors (when throwOnError is false)
+     * Returns true if the value object has validation errors (when throwOnError is false).
      */
     get hasValidationErrors() {
         return !!this._validationError;
     }
     /**
-     * Get validation errors (when throwOnError is false)
+     * Returns the validation errors (when throwOnError is false).
      */
     get validationErrors() {
         return this._validationError;
     }
+    /**
+     * Compare this ValueObject with another for equality based on their properties.
+     */
     equals(other) {
         if (!other || !(other instanceof ValueObject))
             return false;
         return JSON.stringify(this.props) === JSON.stringify(other.props);
     }
     /**
-     * Add a domain event to this value object
+     * Returns the identity key for this Value Object.
+     * Used for identification in collections when identityKey is set.
+     *
+     * @returns String with the identity key or null if not defined
+     *
+     * @example
+     * ```typescript
+     * const like = new Like({ postId: 'p1', userId: 'u1' });
+     * like.getIdentityKey(); // 'p1:u1'
+     *
+     * const tag = new TagReference({ tagId: 'tag-123' });
+     * tag.getIdentityKey(); // 'tag-123'
+     * ```
+     */
+    getIdentityKey() {
+        const keyDef = getStaticProperty(this, "identityKey");
+        if (!keyDef) {
+            return null;
+        }
+        if (Array.isArray(keyDef)) {
+            return keyDef.map((k) => String(this.props[k])).join(":");
+        }
+        return String(this.props[keyDef]);
+    }
+    /**
+     * Returns true if this Value Object has an identity key defined.
+     */
+    hasIdentityKey() {
+        return (getStaticProperty(this, "identityKey") !==
+            undefined);
+    }
+    /**
+     * Returns the identity key definition (if any).
+     */
+    static getIdentityKeyDefinition() {
+        return this.identityKey;
+    }
+    /**
+     * Adds a domain event to this value object.
      */
     addDomainEvent(event) {
         this.domainEvents.push(event);
     }
     /**
-     * Get all uncommitted domain events
+     * Returns all uncommitted domain events.
      */
     getUncommittedEvents() {
         return [...this.domainEvents];
     }
     /**
-     * Clear all domain events (call after publishing)
+     * Clears all domain events (call after publishing).
      */
     clearEvents() {
         this.domainEvents = [];
     }
     /**
-     * Check if value object has uncommitted events
+     * Returns true if the value object has uncommitted events.
      */
     hasUncommittedEvents() {
         return this.domainEvents.length > 0;
@@ -122,8 +149,8 @@ export class ValueObject {
         return { ...this.props };
     }
     /**
-     * Create a new ValueObject with updated properties
-     * Since ValueObjects are immutable, this returns a new instance
+     * Creates a new ValueObject with updated properties.
+     * ValueObjects are immutable, so this returns a new instance.
      */
     clone(updates) {
         const Constructor = this.constructor;

package/dist/value-object.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@woltz/rich-domain",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Rich Domain Library with Standard Schema validation support",
   "homepage": "https://github.com/tarcisioandrade/rich-domain",
   "type": "module",
@@ -41,6 +41,7 @@
     "typescript"
   ],
   "devDependencies": {
+    "@faker-js/faker": "^9.9.0",
     "zod": "^3.24.0"
   },
   "peerDependencies": {