@qubit-ltd/common-decorator 3.9.1 → 3.10.0

package/README.md

@@ -127,9 +127,11 @@ class.
   - `object`: the calling object itself.
 
 This function copies the fields of the object `obj` to this object, only copying 
-fields defined in this object's class. If a field in the `obj` object is 
-`undefined` or `null`, it sets the field's value to the default value. Note that 
-`obj` can have a different prototype to this object.
+fields defined in this object's class. If a field doesn't exist in the `obj` object, 
+it sets the field's value to the default value. If a field exists in the `obj` object 
+but its value is `null` or `undefined`, the function preserves the `null` or `undefined` 
+value rather than setting it to the default value. Note that `obj` can have a different 
+prototype to this object.
 
 #### <span id="model-clone">Instance method: Class.prototype.clone()</span>
 
@@ -227,6 +229,9 @@ fields of this object. If `fields` is an array of strings, it normalizes all the
 normalizable fields whose names are specified in the array. Note that a field is 
 normalizable if and only if it is decorated by the `@Normalizable` decorator.
 
+**IMPORTANT**: If a field value is `null` or `undefined`, the normalization process will
+preserve the `null` or `undefined` value rather than replacing it with a default value.
+
 #### <span id="model-validateField">Instance method: Class.prototype.validateField(field)</span>
 
 - Parameters:

package/README.zh_CN.md

@@ -112,7 +112,8 @@ pnpm add @qubit-ltd/common-decorator
     - `object`：调用该方法的对象自身。
 
 此函数将 `obj` 对象的字段复制到当前对象中，仅复制当前对象类中定义的字段。
-如果 `obj` 中的字段为 `undefined` 或 `null`，将其值设为默认值。
+如果 `obj` 中不存在某个字段，则将当前对象对应字段设为默认值。但如果 `obj` 中某个字段存在
+且值为 `null` 或 `undefined`，函数会保留这些 `null` 或 `undefined` 值，而不是设为默认值。
 注意，`obj` 可以与当前对象有不同的原型。
 
 #### <span id="model-clone">实例方法：Class.prototype.clone()</span>
@@ -189,6 +190,9 @@ pnpm add @qubit-ltd/common-decorator
 如果 `fields` 是一个字符串数组，则规范化数组中指定名称的所有可规范化字段。
 请注意，字段只有在被 `@Normalizable` 装饰器装饰时才是可规范化的。
 
+**重要提示**：如果字段值为 `null` 或 `undefined`，规范化过程将会保留这些 `null` 或 `undefined` 值，
+而不会将其替换为默认值。
+
 #### <span id="model-validateField">实例方法：Class.prototype.validateField(field)</span>
 
 - 参数：

package/dist/common-decorator.cjs

@@ -1042,7 +1042,8 @@ function enumNormalizer(EnumClass) {
  * A default normalizer for a non-static class field.
  *
  * This normalizer does the following things:
- * - If the value is `undefined` or `null`, it returns the value itself;
+ * - If the value is `undefined` or `null`, it returns the value itself without
+ *   changing it;
  * - If the value is a string, it returns the trimmed string;
  * - If the value is a collection, it returns the same type of collection whose
  *   elements are normalized by the default normalizer;
@@ -10266,7 +10267,12 @@ function normalizeArrayField(Class, obj, field, value, options, normalizer) {
       elementTypes: options.elementTypes
     };
     obj[field] = value.map(function (v) {
-      return normalizer(v, context);
+      // for null or undefined values, keep the original value without normalization
+      if (v === null || v === undefined) {
+        return v;
+      } else {
+        return normalizer(v, context);
+      }
     });
     return true;
   }
@@ -10416,19 +10422,16 @@ function normalizeNormalField(Class, obj, field, value, options, normalizer) {
  * @param {any} value
  *     The value of the specified field of the specified object.
  * @returns {boolean}
- *     If the field value is nullish, this function normalizes the field of the
- *     specified object by setting its field value to the corresponding field
- *     value of the default instance of the specified class, and returns `true`;
+ *     If the field value is nullish, this function returns `true` and preserves
+ *     the nullish value (null or undefined) in the object's field;
  *     otherwise, this function does nothing and returns `false`.
  * @author Haixing Hu
  * @private
  */
 function normalizeNullishField(Class, obj, field, value) {
   if (value === undefined || value === null) {
-    // For field values that are `undefined` or `null`, the normalized value
-    // should be the default value of the field.
-    var defaultInstance = getDefaultInstance(Class);
-    obj[field] = defaultInstance[field];
+    // For field values that are `undefined` or `null`, preserve the original value
+    // instead of replacing it with the default value
     return true;
   }
   return false;
@@ -11475,12 +11478,13 @@ function _objectSpread$1(e) { for (var r = 1; r < arguments.length; r++) { var t
  *
  * - Instance method `assign(obj, options)`: Copies the properties of the object
  *   `obj` to this object, only copying properties defined in the class of this
- *   object. If a property in the `obj` object is `undefined` or `null`, it sets
- *   the property of this object to the default value. The function returns this
- *   object itself. Note that `obj` can have a different prototype than this object.
- *   The `options` parameter is the additional options for the assignment.
- *   Available options will be explained below. If the `options` parameter is
- *   `undefined` or `null`, the default options will be used. The default
+ *   object. If a property in `obj` does not exist, it sets the property of this
+ *   object to the default value. If a property exists in `obj` but its value is
+ *   `null` or `undefined`, the function preserves the `null` or `undefined` value.
+ *   The function returns this object itself. Note that `obj` can have a different
+ *   prototype than this object. The `options` parameter is the additional options
+ *   for the assignment. Available options will be explained below. If the `options`
+ *   parameter is `undefined` or `null`, the default options will be used. The default
  *   options can be retrieved by calling `DefaultOptions.get('assign')`.
  * - Instance method `clear()`: Sets all the properties of this object to their
  *   default values.
@@ -11707,8 +11711,10 @@ function Model(Class, context) {
      * Copies the properties from a specified data object to this object, only
      * copying properties defined in the class of this object.
      *
-     * If a property in the data object is `undefined` or `null`, the function
-     * sets the property of this object to the default value.
+     * If a property in the data object doesn't exist, the function
+     * sets the property of this object to the default value. However, if a property
+     * exists in the data object but its value is `null` or `undefined`, the function
+     * will preserve that `null` or `undefined` value in this object.
      *
      * Note that the data object may have a different prototype than this object.
      *
@@ -11824,6 +11830,10 @@ function Model(Class, context) {
      * A field is normalizable if and only if it is decorated with the
      * `@{@link Normalizable}` decorator.
      *
+     * If a field value is `null` or `undefined`, the normalization process will
+     * preserve the `null` or `undefined` value rather than replacing it with a
+     * default value.
+     *
      * @param {undefined|string|array} fields
      *     the names of fields to be normalized. If this argument is not specified,
      *     or `undefined`, or `null`, or a string `'*'`, this function normalizes
@@ -12124,8 +12134,10 @@ function Model(Class, context) {
      * It copies the property values from the corresponding properties of the
      * specified data object maintaining the same prototype and class definition.
      *
-     * If a property in the data object is `undefined` or `null`, the function
-     * sets the property of the created instance to the default value.
+     * If a property doesn't exist in the data object, the function sets the property
+     * of the created instance to the default value. If a property exists in the data
+     * object but its value is `null` or `undefined`, the function preserves the `null`
+     * or `undefined` value.
      *
      * This method is usually used to transform a plain JSON object into the
      * specified domain object.
@@ -12179,6 +12191,11 @@ function Model(Class, context) {
      * copied from the corresponding elements in the data object array,
      * maintaining the same prototype and class definition.
      *
+     * For each element in the array, if a property doesn't exist in the data object,
+     * the function sets the property of the created instance to the default value.
+     * If a property exists in the data object but its value is `null` or `undefined`,
+     * the function preserves the `null` or `undefined` value.
+     *
      * This method is usually used to transform an array of plain JSON objects
      * into an array of specified domain objects.
      *
@@ -12231,6 +12248,11 @@ function Model(Class, context) {
      *  list of domain objects obtained from a server using the GET method, and
      *  the object should conform to the `Page` class definition.
      *
+     *  For each element in the page content array, if a property doesn't exist in
+     *  the data object, the function sets the property of the created instance to
+     *  the default value. If a property exists in the data object but its value is
+     *  `null` or `undefined`, the function preserves the `null` or `undefined` value.
+     *
      * @param {object} page
      *     the specified pagination data object, which must conform to the
      *     `Page` class definition.