@shirudo/ddd-kit 3.0.0-rc.5 → 3.0.0-rc.7

package/dist/chunks/ports.js

@@ -703,6 +703,37 @@ function shadowMutators(obj, typeName, methods) {
 	}
 	return true;
 }
+const VALUE_OBJECT_CLASS = Symbol.for("@shirudo/ddd-kit/value-object-class/v1");
+function recordValueObjectClass(instance, valueObjectClass) {
+	Object.defineProperty(instance, VALUE_OBJECT_CLASS, {
+		value: valueObjectClass,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+}
+function isValueObjectInstance(value) {
+	if (value === null || typeof value !== "object") return false;
+	const record = Reflect.getOwnPropertyDescriptor(value, VALUE_OBJECT_CLASS);
+	if (record === void 0 || typeof record.value !== "function" || record.enumerable !== false || record.writable !== false || record.configurable !== false) return false;
+	const props = Reflect.getOwnPropertyDescriptor(value, "props");
+	return props !== void 0 && isSealedProps(props.value);
+}
+function isSealedProps(props) {
+	if (typeof props !== "object" || props === null) return false;
+	return Object.isFrozen(props) || builtInTagWithoutInvokingAccessors(props) === "[object RegExp]";
+}
+function looksLikeValueObject(instance) {
+	if (Object.hasOwn(instance, VALUE_OBJECT_CLASS)) return true;
+	const props = Reflect.getOwnPropertyDescriptor(instance, "props");
+	return props !== void 0 && isSealedProps(props.value);
+}
+function openValueObjectKeys(instance) {
+	return Reflect.ownKeys(instance).filter((key) => key !== "props" && key !== VALUE_OBJECT_CLASS);
+}
+function rejectValueObjectAsInput(input, entry) {
+	if (isValueObjectInstance(input)) throw new TypeError(`${entry} does not accept a value object as its input: nest the value object under a key, or pass its props`);
+}
 /**
 * Deep freezes an object and all its nested properties recursively, then
 * returns it. Iterates both string-keyed and symbol-keyed own properties
@@ -809,11 +840,12 @@ function freezeDeep(obj, walk) {
 * `deepEqual` DOES consider symbol keys) and shared references / cycles
 * keep their identity across Map boundaries. Function values throw,
 * preserving `vo()`'s documented data-not-behaviour gate. Built-ins without
-* immutable value semantics throw a descriptive `TypeError`. Custom class
-* instances and subclasses of built-ins are rejected because cloning them
-* without invoking their
-* constructor can silently lose private or non-enumerable state. Map keys
-* and Set members must be primitive because their equality is
+* immutable value semantics throw a descriptive `TypeError`. A kit
+* `ValueObject` instance is admitted by reference (see
+* `VALUE_OBJECT_CLASS`). Every other custom class instance and every
+* subclass of a built-in is rejected because cloning it without invoking
+* its constructor can silently lose private or non-enumerable state. Map
+* keys and Set members must be primitive because their equality is
 * identity-based and object identity cannot survive defensive cloning.
 * Accessor properties are rejected without invoking them. Admitted atomic
 * built-ins (Date, RegExp and primitive wrappers) delegate to
@@ -828,7 +860,7 @@ function cloneForVo(value, visited) {
 	if (ArrayBuffer.isView(obj)) throwUnsupportedValueSemantics(builtInTagWithoutInvokingAccessors(obj) ?? "[object ArrayBuffer view]");
 	if (visited.has(obj)) return visited.get(obj);
 	if (Array.isArray(obj)) {
-		if (!hasIntrinsicPrototypeChain(obj, "Array")) throwUnsupportedClassInstance();
+		if (!hasIntrinsicPrototypeChain(obj, "Array")) throwUnsupportedClassInstance(obj);
 		const clone = new Array(obj.length);
 		visited.set(obj, clone);
 		for (const key of Reflect.ownKeys(obj)) {
@@ -844,7 +876,7 @@ function cloneForVo(value, visited) {
 	}
 	const tag = builtInTagWithoutInvokingAccessors(obj);
 	if (tag !== void 0) {
-		if (!hasIntrinsicPrototypeChain(obj)) throwUnsupportedClassInstance();
+		if (!hasIntrinsicPrototypeChain(obj)) throwUnsupportedClassInstance(obj);
 		if (tag === "[object Map]") {
 			const clone = /* @__PURE__ */ new Map();
 			visited.set(obj, clone);
@@ -874,7 +906,14 @@ function cloneForVo(value, visited) {
 		return builtInClone;
 	}
 	const prototype = Object.getPrototypeOf(obj);
-	if (prototype !== null && (!isIntrinsicConstructorPrototype(prototype, "Object") || Object.getPrototypeOf(prototype) !== null)) throwUnsupportedClassInstance();
+	if (prototype !== null && (!isIntrinsicConstructorPrototype(prototype, "Object") || Object.getPrototypeOf(prototype) !== null)) {
+		if (isValueObjectInstance(obj)) {
+			const openKeys = openValueObjectKeys(obj);
+			if (openKeys.length > 0) throwOpenValueObjectFields(openKeys);
+			return obj;
+		}
+		throwUnsupportedClassInstance(obj);
+	}
 	const clone = Object.create(prototype === null ? null : Object.prototype);
 	visited.set(obj, clone);
 	for (const key of Reflect.ownKeys(obj)) {
@@ -891,8 +930,12 @@ function cloneForVo(value, visited) {
 	}
 	return clone;
 }
-function throwUnsupportedClassInstance() {
-	throw new TypeError("vo() cannot clone custom class instances: Value Objects are plain data");
+function throwUnsupportedClassInstance(instance) {
+	const valueObjectHint = looksLikeValueObject(instance) ? ". A value object is recognized only when a copy of this kit version built it and its props are frozen" : "";
+	throw new TypeError(`vo() cannot clone custom class instances: Value Objects are plain data${valueObjectHint}`);
+}
+function throwOpenValueObjectFields(keys) {
+	throw new TypeError(`vo() cannot nest a value object with own fields outside props (${keys.map(String).join(", ")}): keep the state of a value object in props`);
 }
 function throwUnsupportedAccessorProperty() {
 	throw new TypeError("vo() cannot clone accessor properties: Value Objects are plain data");
@@ -910,9 +953,12 @@ function isPrimitiveValue(value) {
 * The input is first deep-cloned, then the clone is frozen, so calling
 * `vo(input)` never freezes the caller's own object graph as a
 * side-effect. Mutating the input afterwards does not bleed into the VO.
-* Symbol-keyed properties are preserved (matching `voEquals`); function
-* values and custom class instances are rejected (Value Objects are plain
-* data, not behaviour-bearing object graphs). Inputs must be trusted and
+* Symbol-keyed properties are preserved (matching `voEquals`). A kit
+* `ValueObject` instance nested in the input is kept by reference and
+* frozen in place; it must keep all of its state in `props`. A value
+* object as the input itself is rejected.
+* Function values and every other custom class instance are rejected
+* (Value Objects are plain data, not behaviour-bearing object graphs). Inputs must be trusted and
 * Proxy-free: ECMAScript provides no portable way to identify a transparent
 * Proxy without potentially executing its traps, so `vo()` is not a sandbox
 * for hostile in-process objects. Built-ins that cannot provide immutable,
@@ -927,6 +973,7 @@ function isPrimitiveValue(value) {
 * ```
 */
 function vo(t) {
+	rejectValueObjectAsInput(t, "vo()");
 	return deepFreeze(cloneForVo(t, /* @__PURE__ */ new WeakMap()));
 }
 /**
@@ -967,6 +1014,11 @@ function voEquals(a, b) {
 * Useful for comparing value objects that contain metadata or optional fields
 * that should not affect equality comparison.
 *
+* The walk enters a nested `ValueObject` instance like any other object,
+* so inside it the path continues with `props`; `ignoreKeys: ["props"]`
+* empties every nested value object. The key under which the kit records
+* the class of the instance is never ignored.
+*
 * @param a - First value object
 * @param b - Second value object
 * @param options - Options specifying which keys to ignore during comparison
@@ -1000,7 +1052,15 @@ function voEquals(a, b) {
 * ```
 */
 function voEqualsExcept(a, b, options) {
-	return deepEqualExcept(a, b, options);
+	return deepEqualExcept(a, b, keepValueObjectClass(options));
+}
+function keepValueObjectClass(options) {
+	const { ignoreKeys, ignoreKeyPredicate } = options;
+	return {
+		...options,
+		ignoreKeys: ignoreKeys?.filter((key) => key !== VALUE_OBJECT_CLASS),
+		ignoreKeyPredicate: ignoreKeyPredicate && ((key, path) => key !== VALUE_OBJECT_CLASS && ignoreKeyPredicate(key, path))
+	};
 }
 /**
 * Creates a value object with optional validation.
@@ -1049,7 +1109,11 @@ function describeValue(value) {
 }
 /**
 * Abstract base class for creating Value Objects.
-* Value Objects are immutable and defined by their properties.
+* Value Objects are immutable and defined by their properties. A value
+* object can hold other value objects in its props. Every instance
+* records its class under an own symbol key, so `equals` compares a
+* nested value object by class and props and does not call its `equals`
+* method.
 *
 * @template T - The shape of the value object's properties
 */
@@ -1076,8 +1140,10 @@ var ValueObject = class {
 	* ```
 	*/
 	constructor(props) {
+		rejectValueObjectAsInput(props, "new ValueObject()");
 		this.validate(props);
 		this.props = deepFreeze(cloneForVo(props, /* @__PURE__ */ new WeakMap()));
+		recordValueObjectClass(this, this.constructor);
 	}
 	/**
 	* Optional validation hook that can be overridden by subclasses.
@@ -1621,5 +1687,5 @@ function isDispatchTrackingOutbox(outbox) {
 }
 
 //#endregion
-export { isWeakMap as A, voWithValidation as C, findPropertyDescriptor as D, deepEqual as E, isBuiltInObject as O, voEqualsExcept as S, deepOmit as T, stampCooperativeBrand as _, createDomainEvent as a, vo as b, createUncommittedDomainEvent as c, isUncommittedDomainEvent as d, mergeMetadata as f, hasCooperativeBrand as g, SnapshotTimeValidationError as h, copyMetadata as i, isIntrinsicConstructorPrototype as k, defaultDomainEventFactory as l, DomainEventValidationError as m, adoptRecordedDomainEvent as n, createDomainEventFactory as o, recordDomainEvent as p, adoptUncommittedDomainEvent as r, createDomainEventFromFacts as s, isDispatchTrackingOutbox as t, isRecordedDomainEvent as u, ValueObject as v, deepEqualExcept as w, voEquals as x, deepFreeze as y };
+export { isBuiltInObject as A, voWithValidation as C, builtInTagWithoutInvokingAccessors as D, deepEqual as E, isWeakMap as M, findPropertyDescriptor as O, voEqualsExcept as S, deepOmit as T, stampCooperativeBrand as _, createDomainEvent as a, vo as b, createUncommittedDomainEvent as c, isUncommittedDomainEvent as d, mergeMetadata as f, hasCooperativeBrand as g, SnapshotTimeValidationError as h, copyMetadata as i, isIntrinsicConstructorPrototype as j, hasIntrinsicPrototypeChain as k, defaultDomainEventFactory as l, DomainEventValidationError as m, adoptRecordedDomainEvent as n, createDomainEventFactory as o, recordDomainEvent as p, adoptUncommittedDomainEvent as r, createDomainEventFromFacts as s, isDispatchTrackingOutbox as t, isRecordedDomainEvent as u, ValueObject as v, deepEqualExcept as w, voEquals as x, deepFreeze as y };
 //# sourceMappingURL=ports.js.map