@qubit-ltd/common-decorator 3.9.0 → 3.10.0

package/README.md

@@ -6,10 +6,11 @@
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/Haixing-Hu/js-common-decorator/tree/master.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/Haixing-Hu/js-common-decorator/tree/master)
 [![Coverage Status](https://coveralls.io/repos/github/Haixing-Hu/js-common-decorator/badge.svg?branch=master)](https://coveralls.io/github/Haixing-Hu/js-common-decorator?branch=master)
 
-[@qubit-ltd/common-decorator] is a JavaScript library of common decorators,
-provides decorators to add common methods to domain classes. The library 
-supports the most recent (currently November 2023) 
-[stage 3 proposal of JavaScript decorators].
+## Overview
+
+[@qubit-ltd/common-decorator] is a JavaScript library of common decorators that provides powerful tools to enhance your domain classes. The library supports the most recent (as of November 2023) [stage 3 proposal of JavaScript decorators].
+
+With this library, you can easily add common methods to your domain classes, implement Java-like enum functionality, add validation and normalization capabilities, and much more - all using the modern decorator syntax.
 
 ## Features
 
@@ -20,6 +21,7 @@ supports the most recent (currently November 2023)
 - **Normalization Support**: `@Normalizable` decorator enables field normalization
 - **Type Safety**: `@Type` and `@ElementType` decorators for type checking
 - **Serialization Utilities**: Built-in JSON serialization/deserialization support
+- **High Test Coverage**: Comprehensive test suite ensuring reliability of all features
 
 ## Installation
 
@@ -29,6 +31,9 @@ npm install @qubit-ltd/common-decorator
 
 # Using yarn
 yarn add @qubit-ltd/common-decorator
+
+# Using pnpm
+pnpm add @qubit-ltd/common-decorator
 ```
 
 ## <span id="content">Table of Contents</span>
@@ -74,6 +79,7 @@ yarn add @qubit-ltd/common-decorator
 - [Configuration](#configuration)
   - [Bundling with webpack](#webpack)
   - [Bundling with vite](#vite)
+- [Recent Updates](#recent-updates)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -121,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>
 
@@ -221,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:
@@ -1152,6 +1163,20 @@ must be at least `7.24.0`.
     });
     ```
 
+## <span id="recent-updates">Recent Updates</span>
+
+### Test Coverage Enhancements (December 2023)
+
+- **Enum Clone Hook Test**: Added comprehensive tests to verify the behavior of enum clone hooks, ensuring that enumerator objects are properly handled during cloning operations.
+- **Field Validation Coverage**: Enhanced test coverage for field validation, specifically targeting edge cases to ensure robust validation in all scenarios.
+- **Model Implementation Tests**: Added additional tests for various model implementation functions to achieve higher code coverage.
+
+The latest updates focus on improving test coverage and reliability, with particular attention to:
+
+- Ensuring enumerator objects maintain their singleton pattern during cloning
+- Validating empty fields with proper error handling
+- Verifying that model implementation functions work correctly in all edge cases
+
 ## <span id="contributing">Contributing</span>
 
 If you find any issues or have suggestions for improvements, please feel free

package/README.zh_CN.md

@@ -6,8 +6,11 @@
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/Haixing-Hu/js-common-decorator/tree/master.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/Haixing-Hu/js-common-decorator/tree/master)
 [![Coverage Status](https://coveralls.io/repos/github/Haixing-Hu/js-common-decorator/badge.svg?branch=master)](https://coveralls.io/github/Haixing-Hu/js-common-decorator?branch=master)
 
-[@qubit-ltd/common-decorator] 是一个 JavaScript 通用装饰器库，提供装饰器用于为领域类添加常用方法。
-该库支持 JavaScript 装饰器的最新 (截至2023年11月) [stage 3 提案]。
+## 概述
+
+[@qubit-ltd/common-decorator] 是一个JavaScript通用装饰器库，为您的领域类提供强大的增强工具。该库支持最新的（截至2023年11月）JavaScript装饰器[stage 3 提案]。
+
+使用这个库，您可以轻松地为领域类添加常用方法，实现类似Java的枚举功能，添加验证和规范化功能等 - 所有这些都使用现代装饰器语法。
 
 ## 特性
 
@@ -18,6 +21,7 @@
 - **规范化支持**：`@Normalizable` 装饰器实现字段规范化
 - **类型安全**：`@Type` 和 `@ElementType` 装饰器用于类型检查
 - **序列化工具**：内置 JSON 序列化/反序列化支持
+- **高测试覆盖率**：全面的测试套件确保所有功能的可靠性
 
 ## 安装
 
@@ -27,6 +31,9 @@ npm install @qubit-ltd/common-decorator
 
 # 使用 yarn
 yarn add @qubit-ltd/common-decorator
+
+# 使用 pnpm
+pnpm add @qubit-ltd/common-decorator
 ```
 
 ## <span id="content">目录</span>
@@ -72,6 +79,7 @@ yarn add @qubit-ltd/common-decorator
 - [配置](#configuration)
     - [使用 webpack 打包](#webpack)
     - [使用 vite 打包](#vite)
+- [最新更新](#recent-updates)
 - [贡献](#contributing)
 - [许可证](#license)
 
@@ -104,7 +112,8 @@ yarn 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>
@@ -181,6 +190,9 @@ yarn add @qubit-ltd/common-decorator
 如果 `fields` 是一个字符串数组，则规范化数组中指定名称的所有可规范化字段。
 请注意，字段只有在被 `@Normalizable` 装饰器装饰时才是可规范化的。
 
+**重要提示**：如果字段值为 `null` 或 `undefined`，规范化过程将会保留这些 `null` 或 `undefined` 值，
+而不会将其替换为默认值。
+
 #### <span id="model-validateField">实例方法：Class.prototype.validateField(field)</span>
 
 - 参数：
@@ -927,6 +939,20 @@ expect(opt1.convertNaming).toBe(false);
     });
     ```
 
+## <span id="recent-updates">最新更新</span>
+
+### 测试覆盖增强（2023年12月）
+
+- **枚举克隆钩子测试**：添加了全面的测试，验证枚举克隆钩子的行为，确保在克隆操作中正确处理枚举器对象。
+- **字段验证覆盖**：增强了字段验证的测试覆盖率，特别针对边缘情况，确保在所有场景下都能进行可靠的验证。
+- **模型实现测试**：为各种模型实现函数添加了额外的测试，以实现更高的代码覆盖率。
+
+最新更新主要集中在提高测试覆盖率和可靠性，特别关注：
+
+- 确保枚举器对象在克隆过程中保持单例模式
+- 验证空字段的处理与适当的错误处理
+- 验证模型实现函数在所有边缘情况下都能正常工作
+
 ## <span id="contributing">贡献</span>
 
 如果你发现任何问题或有改进建议，请随时在 [GitHub 仓库] 上提交 issue 或 pull request。

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.
@@ -12786,11 +12808,11 @@ function createDeferredReadonlyInitializer(propertyName) {
  * ```js
  * class Meal {
  *   // Field with initial value - immediately read-only
- *   @Readonly
+ *   &#64;Readonly
  *   entree = 'steak';
  *
  *   // Field without initial value - will be read-only after first assignment
- *   @Readonly
+ *   &#64;Readonly
  *   dessert;
  * }
  *