@qubit-ltd/common-decorator 3.9.1 → 3.10.0

package/doc/api/DefaultAssignmentOptions.html

@@ -668,7 +668,7 @@ include the class name of the target object.</p>
 
 <footer>
     Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
-     on Mon Apr 21 2025 16:47:56 GMT+0800 (China Standard Time)
+     on Wed Apr 30 2025 14:22:08 GMT+0800 (China Standard Time)
     using the <a href="https://github.com/Haixing-Hu/jsdoc-minami">customized Minami theme</a>.
 </footer>
 

package/doc/api/DefaultOptions.html

@@ -944,7 +944,7 @@ added to the old default options.</p>
 
 <footer>
     Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
-     on Mon Apr 21 2025 16:47:56 GMT+0800 (China Standard Time)
+     on Wed Apr 30 2025 14:22:08 GMT+0800 (China Standard Time)
     using the <a href="https://github.com/Haixing-Hu/jsdoc-minami">customized Minami theme</a>.
 </footer>
 

package/doc/api/DefaultToJsonOptions.html

@@ -623,7 +623,7 @@ result JSON string of the <code>toJSON()</code> method.</p>
 
 <footer>
     Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
-     on Mon Apr 21 2025 16:47:56 GMT+0800 (China Standard Time)
+     on Wed Apr 30 2025 14:22:08 GMT+0800 (China Standard Time)
     using the <a href="https://github.com/Haixing-Hu/jsdoc-minami">customized Minami theme</a>.
 </footer>
 

package/doc/api/Enum.html

@@ -1838,7 +1838,7 @@ or <code>undefined</code> if there is no such enumerator.</p>
 
 <footer>
     Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
-     on Mon Apr 21 2025 16:47:56 GMT+0800 (China Standard Time)
+     on Wed Apr 30 2025 14:22:08 GMT+0800 (China Standard Time)
     using the <a href="https://github.com/Haixing-Hu/jsdoc-minami">customized Minami theme</a>.
 </footer>
 

package/doc/api/Model.html

@@ -58,12 +58,13 @@
 <ul>
 <li>Instance method <code>assign(obj, options)</code>: Copies the properties of the object
 <code>obj</code> to this object, only copying properties defined in the class of this
-object. If a property in the <code>obj</code> object is <code>undefined</code> or <code>null</code>, it sets
-the property of this object to the default value. The function returns this
-object itself. Note that <code>obj</code> can have a different prototype than this object.
-The <code>options</code> parameter is the additional options for the assignment.
-Available options will be explained below. If the <code>options</code> parameter is
-<code>undefined</code> or <code>null</code>, the default options will be used. The default
+object. If a property in <code>obj</code> does not exist, it sets the property of this
+object to the default value. If a property exists in <code>obj</code> but its value is
+<code>null</code> or <code>undefined</code>, the function preserves the <code>null</code> or <code>undefined</code> value.
+The function returns this object itself. Note that <code>obj</code> can have a different
+prototype than this object. The <code>options</code> parameter is the additional options
+for the assignment. Available options will be explained below. If the <code>options</code>
+parameter is <code>undefined</code> or <code>null</code>, the default options will be used. The default
 options can be retrieved by calling <code>DefaultOptions.get('assign')</code>.</li>
 <li>Instance method <code>clear()</code>: Sets all the properties of this object to their
 default values.</li>
@@ -361,8 +362,10 @@ the <code>Person.prototype.equals()</code> method.</li>
 <div class="description">
     <p>Copies the properties from a specified data object to this object, only
 copying properties defined in the class of this object.</p>
-<p>If a property in the data object is <code>undefined</code> or <code>null</code>, the function
-sets the property of this object to the default value.</p>
+<p>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 <code>null</code> or <code>undefined</code>, the function
+will preserve that <code>null</code> or <code>undefined</code> value in this object.</p>
 <p>Note that the data object may have a different prototype than this object.</p>
 </div>
 
@@ -1198,6 +1201,9 @@ have default values.</p>
 this object.</p>
 <p>A field is normalizable if and only if it is decorated with the
 <code>@<a href="global.html#Normalizable">Normalizable</a></code> decorator.</p>
+<p>If a field value is <code>null</code> or <code>undefined</code>, the normalization process will
+preserve the <code>null</code> or <code>undefined</code> value rather than replacing it with a
+default value.</p>
 </div>
 
 
@@ -2490,8 +2496,10 @@ validation result.</p>
     <p>Creates a new instance of this class based on the specified data object.</p>
 <p>It copies the property values from the corresponding properties of the
 specified data object maintaining the same prototype and class definition.</p>
-<p>If a property in the data object is <code>undefined</code> or <code>null</code>, the function
-sets the property of the created instance to the default value.</p>
+<p>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 <code>null</code> or <code>undefined</code>, the function preserves the <code>null</code>
+or <code>undefined</code> value.</p>
 <p>This method is usually used to transform a plain JSON object into the
 specified domain object.</p>
 </div>
@@ -2727,6 +2735,10 @@ objects.</p>
 <p>The property values of each element in the created instances array are
 copied from the corresponding elements in the data object array,
 maintaining the same prototype and class definition.</p>
+<p>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 <code>null</code> or <code>undefined</code>,
+the function preserves the <code>null</code> or <code>undefined</code> value.</p>
 <p>This method is usually used to transform an array of plain JSON objects
 into an array of specified domain objects.</p>
 </div>
@@ -2962,6 +2974,10 @@ data object array, or <code>null</code> if the specified data object array is
 <p>Typically, the pagination data object is the JSON representation of a
 list of domain objects obtained from a server using the GET method, and
 the object should conform to the <code>Page</code> class definition.</p>
+<p>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
+<code>null</code> or <code>undefined</code>, the function preserves the <code>null</code> or <code>undefined</code> value.</p>
 </div>
 
 
@@ -3597,7 +3613,7 @@ of this argument is <code>'LOWER_CAMEL'</code>.</li>
 
 <footer>
     Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
-     on Mon Apr 21 2025 16:47:56 GMT+0800 (China Standard Time)
+     on Wed Apr 30 2025 14:22:08 GMT+0800 (China Standard Time)
     using the <a href="https://github.com/Haixing-Hu/jsdoc-minami">customized Minami theme</a>.
 </footer>
 

package/doc/api/Page.html

@@ -1095,7 +1095,7 @@ The default value is <code>{}</code>.</li>
 
 <footer>
     Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
-     on Mon Apr 21 2025 16:47:56 GMT+0800 (China Standard Time)
+     on Wed Apr 30 2025 14:22:08 GMT+0800 (China Standard Time)
     using the <a href="https://github.com/Haixing-Hu/jsdoc-minami">customized Minami theme</a>.
 </footer>
 

package/doc/api/global.html

@@ -3813,7 +3813,8 @@ The default value is <code>{}</code>.</li>
     <p>A default normalizer for a non-static class field.</p>
 <p>This normalizer does the following things:</p>
 <ul>
-<li>If the value is <code>undefined</code> or <code>null</code>, it returns the value itself;</li>
+<li>If the value is <code>undefined</code> or <code>null</code>, it returns the value itself without
+changing it;</li>
 <li>If the value is a string, it returns the trimmed string;</li>
 <li>If the value is a collection, it returns the same type of collection whose
 elements are normalized by the default normalizer;</li>
@@ -5804,7 +5805,7 @@ options.</p>
 
 <footer>
     Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
-     on Mon Apr 21 2025 16:47:56 GMT+0800 (China Standard Time)
+     on Wed Apr 30 2025 14:22:08 GMT+0800 (China Standard Time)
     using the <a href="https://github.com/Haixing-Hu/jsdoc-minami">customized Minami theme</a>.
 </footer>
 

package/doc/api/index.html

@@ -189,9 +189,11 @@ The default value is <code>{}</code>.</li>
 </li>
 </ul>
 <p>This function copies the fields of the object <code>obj</code> to this object, only copying
-fields defined in this object's class. If a field in the <code>obj</code> object is
-<code>undefined</code> or <code>null</code>, it sets the field's value to the default value. Note that
-<code>obj</code> can have a different prototype to this object.</p>
+fields defined in this object's class. If a field doesn't exist in the <code>obj</code> object,
+it sets the field's value to the default value. If a field exists in the <code>obj</code> object
+but its value is <code>null</code> or <code>undefined</code>, the function preserves the <code>null</code> or <code>undefined</code>
+value rather than setting it to the default value. Note that <code>obj</code> can have a different
+prototype to this object.</p>
 <h4><span id="model-clone">Instance method: Class.prototype.clone()</span></h4>
 <ul>
 <li>Parameters: none.</li>
@@ -314,6 +316,8 @@ parameter specifies the names of fields to be normalized. If <code>fields</code>
 fields of this object. If <code>fields</code> 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 <code>@Normalizable</code> decorator.</p>
+<p><strong>IMPORTANT</strong>: If a field value is <code>null</code> or <code>undefined</code>, the normalization process will
+preserve the <code>null</code> or <code>undefined</code> value rather than replacing it with a default value.</p>
 <h4><span id="model-validateField">Instance method: Class.prototype.validateField(field)</span></h4>
 <ul>
 <li>Parameters:
@@ -1932,7 +1936,7 @@ app.listen(3000, () => {
 
 <footer>
     Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
-     on Mon Apr 21 2025 16:47:56 GMT+0800 (China Standard Time)
+     on Wed Apr 30 2025 14:22:08 GMT+0800 (China Standard Time)
     using the <a href="https://github.com/Haixing-Hu/jsdoc-minami">customized Minami theme</a>.
 </footer>