@qubit-ltd/common-decorator 3.8.10 → 3.9.0

package/doc/api/index.html

@@ -24,7 +24,7 @@
 <label for="nav-trigger" class="overlay"></label>
 
 <nav>
-    <li class="nav-link nav-home-link"><a href="index.html">Home</a></li><li class="nav-heading">Classes</li><li class="nav-heading"><span class="nav-item-type type-class">C</span><span class="nav-item-name"><a href="DefaultAssignmentOptions.html">DefaultAssignmentOptions</a></span></li><li class="nav-heading"><span class="nav-item-type type-class">C</span><span class="nav-item-name"><a href="DefaultOptions.html">DefaultOptions</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="DefaultOptions.html#.get">get</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="DefaultOptions.html#.merge">merge</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="DefaultOptions.html#.reset">reset</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="DefaultOptions.html#.set">set</a></span></li><li class="nav-heading"><span class="nav-item-type type-class">C</span><span class="nav-item-name"><a href="DefaultToJsonOptions.html">DefaultToJsonOptions</a></span></li><li class="nav-heading"><span class="nav-item-type type-class">C</span><span class="nav-item-name"><a href="Page.html">Page</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Page.html#assign">assign</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Page.html#.getFrom">getFrom</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Page.html#.newEmpty">newEmpty</a></span></li><li class="nav-heading">Namespaces</li><li class="nav-heading"><span class="nav-item-type type-namespace">N</span><span class="nav-item-name"><a href="Enum.html">Enum</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.has">Class.has</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.hasCode">Class.hasCode</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.hasName">Class.hasName</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.hasValue">Class.hasValue</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.of">Class.of</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.ofCode">Class.ofCode</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.ofName">Class.ofName</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.ofValue">Class.ofValue</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.values">Class.values</a></span></li><li class="nav-heading"><span class="nav-item-type type-namespace">N</span><span class="nav-item-name"><a href="Model.html">Model</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#assign">assign</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#clear">clear</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#clone">clone</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#equals">equals</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#generateId">generateId</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#isEmpty">isEmpty</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#normalize">normalize</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#normalizeField">normalizeField</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#toJSON">toJSON</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#toJsonString">toJsonString</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#validate">validate</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#validateField">validateField</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.create">Class.create</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.createArray">Class.createArray</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.createPage">Class.createPage</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.isNullishOrEmpty">Class.isNullishOrEmpty</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.parseJsonString">Class.parseJsonString</a></span></li><li class="nav-heading"><a href="global.html">Globals</a></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#ElementType">ElementType</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Enumerable">Enumerable</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Label">Label</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#NameField">NameField</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#NonEmpty">NonEmpty</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#NonEnumerable">NonEnumerable</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Normalizable">Normalizable</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Nullable">Nullable</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Payload">Payload</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Readonly">Readonly</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Timeout">Timeout</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Type">Type</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Validatable">Validatable</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#assign">assign</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#create">create</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#createArray">createArray</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#createPage">createPage</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#defaultNormalizer">defaultNormalizer</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#defaultValidator">defaultValidator</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#enumNormalizer">enumNormalizer</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#isEnumClass">isEnumClass</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#isEnumerator">isEnumerator</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#isValidPageSource">isValidPageSource</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#normalize">normalize</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#stringifyId">stringifyId</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#toJSON">toJSON</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#toJsonString">toJsonString</a></span></li>
+    <li class="nav-link nav-home-link"><a href="index.html">Home</a></li><li class="nav-heading">Classes</li><li class="nav-heading"><span class="nav-item-type type-class">C</span><span class="nav-item-name"><a href="DefaultAssignmentOptions.html">DefaultAssignmentOptions</a></span></li><li class="nav-heading"><span class="nav-item-type type-class">C</span><span class="nav-item-name"><a href="DefaultOptions.html">DefaultOptions</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="DefaultOptions.html#.get">get</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="DefaultOptions.html#.merge">merge</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="DefaultOptions.html#.reset">reset</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="DefaultOptions.html#.set">set</a></span></li><li class="nav-heading"><span class="nav-item-type type-class">C</span><span class="nav-item-name"><a href="DefaultToJsonOptions.html">DefaultToJsonOptions</a></span></li><li class="nav-heading"><span class="nav-item-type type-class">C</span><span class="nav-item-name"><a href="Page.html">Page</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Page.html#assign">assign</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Page.html#.getFrom">getFrom</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Page.html#.newEmpty">newEmpty</a></span></li><li class="nav-heading">Namespaces</li><li class="nav-heading"><span class="nav-item-type type-namespace">N</span><span class="nav-item-name"><a href="Enum.html">Enum</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.has">Class.has</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.hasCode">Class.hasCode</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.hasName">Class.hasName</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.hasValue">Class.hasValue</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.of">Class.of</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.ofCode">Class.ofCode</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.ofName">Class.ofName</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.ofValue">Class.ofValue</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Enum.html#.Class.values">Class.values</a></span></li><li class="nav-heading"><span class="nav-item-type type-namespace">N</span><span class="nav-item-name"><a href="Model.html">Model</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#assign">assign</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#clear">clear</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#clone">clone</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#equals">equals</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#generateId">generateId</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#isEmpty">isEmpty</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#normalize">normalize</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#normalizeField">normalizeField</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#toJSON">toJSON</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#toJsonString">toJsonString</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#validate">validate</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#validateField">validateField</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.create">Class.create</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.createArray">Class.createArray</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.createPage">Class.createPage</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.isNullishOrEmpty">Class.isNullishOrEmpty</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="Model.html#.Class.parseJsonString">Class.parseJsonString</a></span></li><li class="nav-heading"><a href="global.html">Globals</a></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#ElementType">ElementType</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Label">Label</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#NameField">NameField</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#NonEmpty">NonEmpty</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Normalizable">Normalizable</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Nullable">Nullable</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Readonly">Readonly</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Timeout">Timeout</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Type">Type</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#Validatable">Validatable</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#assign">assign</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#create">create</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#createArray">createArray</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#createDeferredReadonlyInitializer">createDeferredReadonlyInitializer</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#createImmediateReadonlyInitializer">createImmediateReadonlyInitializer</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#createPage">createPage</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#defaultNormalizer">defaultNormalizer</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#defaultValidator">defaultValidator</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#enumNormalizer">enumNormalizer</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#isEnumClass">isEnumClass</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#isEnumerator">isEnumerator</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#isValidPageSource">isValidPageSource</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#normalize">normalize</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#stringifyId">stringifyId</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#toJSON">toJSON</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#toJsonString">toJsonString</a></span></li>
 </nav>
 
 <div id="main">
@@ -56,8 +56,25 @@
 <a href="https://coveralls.io/github/Haixing-Hu/js-common-decorator?branch=master"><img src="https://coveralls.io/repos/github/Haixing-Hu/js-common-decorator/badge.svg?branch=master" alt="Coverage Status"></a></p>
 <p><a href="https://npmjs.com/package/@qubit-ltd/common-decorator">@qubit-ltd/common-decorator</a> is a JavaScript library of common decorators,
 provides decorators to add common methods to domain classes. The library
-supports the most recent (currently May 2023)
+supports the most recent (currently November 2023)
 <a href="https://github.com/tc39/proposal-decorators">stage 3 proposal of JavaScript decorators</a>.</p>
+<h2>Features</h2>
+<ul>
+<li><strong>Modern Decorator Support</strong>: Compatible with the latest Stage 3 proposal for JavaScript decorators</li>
+<li><strong>Model Enhancement</strong>: <code>@Model</code> decorator adds common methods to domain model classes</li>
+<li><strong>Enum Implementation</strong>: <code>@Enum</code> decorator provides Java-like enumeration capabilities</li>
+<li><strong>Validation Support</strong>: <code>@Validatable</code> decorator enables field validation</li>
+<li><strong>Normalization Support</strong>: <code>@Normalizable</code> decorator enables field normalization</li>
+<li><strong>Type Safety</strong>: <code>@Type</code> and <code>@ElementType</code> decorators for type checking</li>
+<li><strong>Serialization Utilities</strong>: Built-in JSON serialization/deserialization support</li>
+</ul>
+<h2>Installation</h2>
+<pre class="prettyprint source lang-bash"><code># Using npm
+npm install @qubit-ltd/common-decorator
+
+# Using yarn
+yarn add @qubit-ltd/common-decorator
+</code></pre>
 <h2><span id="content">Table of Contents</span></h2>
 <ul>
 <li><a href="#usage">Usage</a>
@@ -1178,13 +1195,13 @@ const opt3 = DefaultOptions.merge('assign', null);
 expect(opt3.convertNaming).toBe(false);
 </code></pre>
 <h2><span id="configuration">Configuration</span></h2>
-<p>This library uses the most recent (currently May 2023)
+<p>This library uses the most recent (currently November 2023)
 <a href="https://github.com/tc39/proposal-decorators">stage 3 proposal of JavaScript decorators</a>. Therefore, you must configure
 <a href="https://babeljs.io/">Babel</a> with <a href="https://babeljs.io/docs/babel-plugin-transform-class-properties">@babel/plugin-transform-class-properties</a> and the
 <a href="https://babeljs.io/docs/babel-plugin-proposal-decorators">@babel/plugin-proposal-decorators</a> plugins.</p>
-<p><strong>NOTE:</strong> To support the <a href="https://github.com/tc39/proposal-decorator-metadata">stage 3 proposal of JavaScript decorator metadata</a>,
-the version of the <a href="https://babeljs.io/">Babel</a> plugin <a href="https://babeljs.io/docs/babel-plugin-proposal-decorators">@babel/plugin-proposal-decorators</a> must be
-at least <code>7.23.0</code>.</p>
+<p><strong>NOTE:</strong> To support the <a href="https://github.com/tc39/proposal-decorator-metadata">stage 3 proposal of JavaScript decorator metadata</a>
+at November 2023, the version of the <a href="https://babeljs.io/">Babel</a> plugin <a href="https://babeljs.io/docs/babel-plugin-proposal-decorators">@babel/plugin-proposal-decorators</a>
+must be at least <code>7.24.0</code>.</p>
 <h3><span id="webpack">Bundling with <a href="https://webpack.js.org/">webpack</a></span></h3>
 <ol>
 <li>Install the required dependencies:<pre class="prettyprint source lang-shell"><code>yarn add @qubit-ltd/common-decorator
@@ -1200,7 +1217,7 @@ configuration file <code>babelrc.json</code> is as follows:<pre class="prettypri
   ],
   &quot;plugins&quot;: [
     &quot;@babel/plugin-transform-runtime&quot;,
-    [&quot;@babel/plugin-proposal-decorators&quot;, { &quot;version&quot;: &quot;2023-05&quot; }],
+    [&quot;@babel/plugin-proposal-decorators&quot;, { &quot;version&quot;: &quot;2023-11&quot; }],
     &quot;@babel/plugin-transform-class-properties&quot;
   ]
 }
@@ -1222,7 +1239,7 @@ file <code>babelrc.json</code> is as follows:<pre class="prettyprint source lang
   ],
   &quot;plugins&quot;: [
     &quot;@babel/plugin-transform-runtime&quot;,
-    [&quot;@babel/plugin-proposal-decorators&quot;, { &quot;version&quot;: &quot;2023-05&quot; }],
+    [&quot;@babel/plugin-proposal-decorators&quot;, { &quot;version&quot;: &quot;2023-11&quot; }],
     &quot;@babel/plugin-transform-class-properties&quot;
   ]
 }
@@ -1301,7 +1318,590 @@ export default defineConfig({
 to open an issue or submit a pull request to the <a href="https://github.com/Haixing-Hu/js-common-decorator">GitHub repository</a>.</p>
 <h2><span id="license">License</span></h2>
 <p><a href="https://npmjs.com/package/@qubit-ltd/common-decorator">@qubit-ltd/common-decorator</a> is distributed under the Apache 2.0 license.
-See the <a href="LICENSE">LICENSE</a> file for more details.</p></article>
+See the <a href="LICENSE">LICENSE</a> file for more details.</p>
+<h2>Front-end and Back-end Data Exchange Example</h2>
+<p>In real-world applications, data exchange between front-end and back-end is a common scenario. The following example demonstrates how to use this library to process data from RESTful APIs and send it back to the server.</p>
+<h3>Complete Example</h3>
+<p>Suppose we have an e-commerce application that needs to handle order data. The back-end API returns data in snake_case naming convention (e.g., <code>order_id</code>), while the front-end code uses camelCase (e.g., <code>orderId</code>). Additionally, order IDs use Java's Long type (which may exceed JavaScript's safe integer range).</p>
+<p>First, let's define our domain models:</p>
+<pre class="prettyprint source lang-javascript"><code>import { Model, Type, ElementType, Normalizable, Validatable, NonEmpty } from '@qubit-ltd/common-decorator';
+
+// Configure default options for naming style conversion
+DefaultOptions.set('assign', {
+  normalize: true,
+  convertNaming: true,
+  sourceNamingStyle: 'LOWER_UNDERSCORE',  // JSON data format from back-end
+  targetNamingStyle: 'LOWER_CAMEL'        // Format used in front-end
+});
+
+DefaultOptions.set('toJSON', {
+  normalize: true,
+  removeEmptyFields: true,    // Automatically remove empty fields
+  convertNaming: true,
+  sourceNamingStyle: 'LOWER_CAMEL',       // Format used in front-end
+  targetNamingStyle: 'LOWER_UNDERSCORE'   // Format to send to back-end
+});
+
+// Define the OrderItem model
+@Model
+class OrderItem {
+  constructor() {
+    this.id = null;           // Java Long type, automatically converted to BigInt
+    this.productId = null;    // Front-end uses camelCase, corresponding to product_id in back-end
+    this.productName = '';
+    this.quantity = 0;
+    this.unitPrice = 0;
+  }
+  
+  @Normalizable
+  @Validatable
+  @Type(String)
+  get productName() {
+    return this._productName;
+  }
+  
+  set productName(value) {
+    this._productName = value;
+  }
+  
+  @Normalizable
+  @Validatable
+  @Type(Number)
+  get quantity() {
+    return this._quantity;
+  }
+  
+  set quantity(value) {
+    this._quantity = value;
+  }
+  
+  @Normalizable
+  @Validatable
+  @Type(Number)
+  get unitPrice() {
+    return this._unitPrice;
+  }
+  
+  set unitPrice(value) {
+    this._unitPrice = value;
+  }
+  
+  // Calculate total price
+  getTotalPrice() {
+    return this.quantity * this.unitPrice;
+  }
+}
+
+// Define the Order model
+@Model
+class Order {
+  constructor() {
+    this.id = null;               // Java Long type, automatically converted to BigInt
+    this.orderNumber = '';        // Front-end uses camelCase, corresponding to order_number in back-end
+    this.customerId = null;
+    this.customerName = '';
+    this.orderDate = null;
+    this.orderItems = [];         // Array of order items
+    this.totalAmount = 0;
+    this.status = '';
+    this.note = '';               // Optional field, empty values will be removed when sent to back-end
+  }
+  
+  @Normalizable
+  @Validatable
+  @NonEmpty
+  @Type(String)
+  get orderNumber() {
+    return this._orderNumber;
+  }
+  
+  set orderNumber(value) {
+    this._orderNumber = value;
+  }
+  
+  @Normalizable
+  @Validatable
+  @Type(String)
+  get customerName() {
+    return this._customerName;
+  }
+  
+  set customerName(value) {
+    this._customerName = value;
+  }
+  
+  @Normalizable
+  @Validatable
+  @Type(Date)
+  get orderDate() {
+    return this._orderDate;
+  }
+  
+  set orderDate(value) {
+    this._orderDate = value;
+  }
+  
+  @Normalizable
+  @Validatable
+  @ElementType(OrderItem)
+  get orderItems() {
+    return this._orderItems;
+  }
+  
+  set orderItems(value) {
+    this._orderItems = value;
+  }
+}
+
+// Example usage - Fetching data from back-end
+async function fetchOrder(orderId) {
+  try {
+    // Assume this is the response from a back-end API
+    const response = await fetch(`/api/orders/${orderId}`);
+    const data = await response.json();
+    
+    // Sample data (in snake_case naming style)
+    // {
+    //   &quot;id&quot;: &quot;9223372036854775807&quot;,  // Note: Max value of Java Long, exceeds JS Number safe range
+    //   &quot;order_number&quot;: &quot;ORD-2023-001&quot;,
+    //   &quot;customer_id&quot;: &quot;5678&quot;,
+    //   &quot;customer_name&quot;: &quot;John Doe&quot;,
+    //   &quot;order_date&quot;: &quot;2023-08-15T14:30:00.000Z&quot;,
+    //   &quot;order_items&quot;: [
+    //     {
+    //       &quot;id&quot;: &quot;8345678912345678901&quot;,  // Another large integer
+    //       &quot;product_id&quot;: &quot;101&quot;,
+    //       &quot;product_name&quot;: &quot;Laptop&quot;,
+    //       &quot;quantity&quot;: 1,
+    //       &quot;unit_price&quot;: 999.99
+    //     },
+    //     {
+    //       &quot;id&quot;: &quot;8345678912345678902&quot;,
+    //       &quot;product_id&quot;: &quot;202&quot;,
+    //       &quot;product_name&quot;: &quot;Wireless Mouse&quot;,
+    //       &quot;quantity&quot;: 2,
+    //       &quot;unit_price&quot;: 29.99
+    //     }
+    //   ],
+    //   &quot;total_amount&quot;: 1059.97,
+    //   &quot;status&quot;: &quot;PENDING&quot;,
+    //   &quot;note&quot;: null
+    // }
+    
+    // Create domain object using Order.create(), automatically handling naming style conversion and large integers
+    const order = Order.create(data);
+    
+    console.log(order.id);  // Output: 9223372036854775807n (BigInt type)
+    console.log(order.orderNumber);  // Output: &quot;ORD-2023-001&quot; (converted to camelCase)
+    console.log(order.orderItems[0].productName);  // Output: &quot;Laptop&quot;
+    
+    // Validation and normalization
+    order.normalize();
+    const validationResult = order.validate();
+    if (!validationResult.valid) {
+      console.error('Order data validation failed:', validationResult.message);
+    }
+    
+    return order;
+  } catch (error) {
+    console.error('Failed to fetch order:', error);
+    throw error;
+  }
+}
+
+// Sending data back to the back-end
+async function updateOrder(order) {
+  try {
+    // Use toJSON to convert domain object to plain JavaScript object
+    // Automatically handles: 1. Naming style conversion 2. Empty field removal 3. BigInt conversion
+    const orderData = order.toJSON();
+    
+    // Example of converted data format:
+    // {
+    //   &quot;id&quot;: &quot;9223372036854775807&quot;,  // BigInt converted to string, without 'n' suffix
+    //   &quot;order_number&quot;: &quot;ORD-2023-001&quot;,
+    //   &quot;customer_id&quot;: &quot;5678&quot;,
+    //   &quot;customer_name&quot;: &quot;John Doe&quot;,
+    //   &quot;order_date&quot;: &quot;2023-08-15T14:30:00.000Z&quot;,
+    //   &quot;order_items&quot;: [
+    //     {
+    //       &quot;id&quot;: &quot;8345678912345678901&quot;,
+    //       &quot;product_id&quot;: &quot;101&quot;,
+    //       &quot;product_name&quot;: &quot;Laptop&quot;,
+    //       &quot;quantity&quot;: 1,
+    //       &quot;unit_price&quot;: 999.99
+    //     },
+    //     // ...other order items
+    //   ],
+    //   &quot;total_amount&quot;: 1059.97,
+    //   &quot;status&quot;: &quot;PENDING&quot;
+    //   // Note: 'note' field was null and has been automatically removed
+    // }
+    
+    const response = await fetch(`/api/orders/${order.id}`, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(orderData)  // No additional processing needed, already in the right format
+    });
+    
+    if (!response.ok) {
+      throw new Error(`Failed to update order: ${response.status}`);
+    }
+    
+    return await response.json();
+  } catch (error) {
+    console.error('Failed to update order:', error);
+    throw error;
+  }
+}
+
+// Example usage
+async function example() {
+  // Fetch order data and modify it
+  const order = await fetchOrder('123');
+  order.status = 'COMPLETED';
+  order.note = '';  // Empty string, will be removed when sent to back-end
+  
+  // Add a new item to the order
+  const newItem = new OrderItem();
+  newItem.productId = '303';
+  newItem.productName = 'Headphones';
+  newItem.quantity = 1;
+  newItem.unitPrice = 79.99;
+  order.orderItems.push(newItem);
+  
+  // Recalculate total amount
+  order.totalAmount = order.orderItems.reduce(
+    (sum, item) => sum + item.getTotalPrice(), 0
+  );
+  
+  // Send the updated order back to the server
+  await updateOrder(order);
+}
+
+</code></pre>
+<h3>Key Points</h3>
+<ol>
+<li>
+<p><strong>Automatic Naming Style Conversion</strong>:</p>
+<ul>
+<li>Data from the back-end uses snake_case format (e.g., <code>order_number</code>)</li>
+<li>Front-end domain objects use camelCase format (e.g., <code>orderNumber</code>)</li>
+<li>Through <code>DefaultOptions.set('assign', {...})</code> configuration, <code>Model.create()</code> and <code>model.assign()</code> automatically convert naming styles</li>
+<li>Through <code>DefaultOptions.set('toJSON', {...})</code> configuration, <code>model.toJSON()</code> automatically converts camelCase back to snake_case</li>
+</ul>
+</li>
+<li>
+<p><strong>Large Integer Handling</strong>:</p>
+<ul>
+<li>Back-end uses Java Long type IDs (e.g., <code>9223372036854775807</code>) that exceed JavaScript's safe integer range</li>
+<li><code>Model.create()</code> and <code>model.assign()</code> automatically convert these large integers to JavaScript's BigInt type</li>
+<li><code>model.toJSON()</code> automatically converts BigInt to the correct JSON format (without the 'n' suffix)</li>
+</ul>
+</li>
+<li>
+<p><strong>Empty Field Handling</strong>:</p>
+<ul>
+<li>With <code>removeEmptyFields: true</code> configuration, <code>model.toJSON()</code> automatically removes null, undefined, and empty string properties</li>
+<li>In the example, the 'note' field with null or empty string value won't be sent to the back-end</li>
+</ul>
+</li>
+<li>
+<p><strong>Type Conversion and Validation</strong>:</p>
+<ul>
+<li>Use <code>@Type</code> and <code>@ElementType</code> decorators to ensure type safety</li>
+<li>Use <code>model.normalize()</code> for data normalization</li>
+<li>Use <code>model.validate()</code> to validate data integrity</li>
+</ul>
+</li>
+</ol>
+<p>This complete example demonstrates how to use the features of this library to easily handle various challenges in front-end and back-end data exchange in real-world applications.</p>
+<h2>Advanced Usage</h2>
+<h3>Combining Multiple Decorators</h3>
+<p>You can combine multiple decorators to add rich functionality to your classes:</p>
+<pre class="prettyprint source lang-javascript"><code>import { 
+  Model, 
+  Type, 
+  ElementType, 
+  Normalizable, 
+  Validatable, 
+  NonEmpty 
+} from '@qubit-ltd/common-decorator';
+
+@Model
+class Product {
+  constructor() {
+    this.id = null;
+    this.name = '';
+    this.price = 0;
+    this.tags = [];
+    this.createdAt = null;
+  }
+  
+  @NonEmpty
+  @Validatable
+  @Normalizable
+  @Type(String)
+  get name() {
+    return this._name;
+  }
+  
+  set name(value) {
+    this._name = value;
+  }
+  
+  @Validatable
+  @Normalizable
+  @Type(Number)
+  get price() {
+    return this._price;
+  }
+  
+  set price(value) {
+    this._price = value;
+  }
+  
+  @Normalizable
+  @ElementType(String)
+  get tags() {
+    return this._tags;
+  }
+  
+  set tags(value) {
+    this._tags = value;
+  }
+}
+
+// Usage
+const product = new Product();
+product.assign({
+  name: '  Product Name  ',
+  price: '99.99',
+  tags: ['tag1', 2, 'tag3']
+});
+
+// After normalization, product.name will be trimmed, 
+// product.price will be a Number,
+// and all elements in product.tags will be strings
+product.normalize();
+
+console.log(product.validate()); // Checks if name is not empty and all types match
+</code></pre>
+<h3>Custom Validation and Normalization</h3>
+<p>You can implement custom validation and normalization logic:</p>
+<pre class="prettyprint source lang-javascript"><code>import { Model, Normalizable, Validatable } from '@qubit-ltd/common-decorator';
+
+@Model
+class EmailSubscription {
+  constructor() {
+    this.email = '';
+    this.subscribed = false;
+  }
+  
+  @Normalizable((value) => {
+    // Custom normalizer that converts email to lowercase and trims whitespace
+    return typeof value === 'string' ? value.toLowerCase().trim() : value;
+  })
+  @Validatable((value) => {
+    // Custom validator that checks if email is valid
+    if (typeof value !== 'string' || !value.includes('@')) {
+      return {
+        valid: false,
+        message: 'Invalid email address',
+      };
+    }
+    return { valid: true };
+  })
+  get email() {
+    return this._email;
+  }
+  
+  set email(value) {
+    this._email = value;
+  }
+}
+</code></pre>
+<h3>Working with DefaultOptions</h3>
+<p>You can configure default options for various operations:</p>
+<pre class="prettyprint source lang-javascript"><code>import { DefaultOptions, Model } from '@qubit-ltd/common-decorator';
+
+// Configure default options for JSON serialization
+DefaultOptions.set('toJSON', {
+  normalize: true,
+  removeEmptyFields: true,
+  convertNaming: true,
+  sourceNamingStyle: 'LOWER_CAMEL',
+  targetNamingStyle: 'LOWER_UNDERSCORE'
+});
+
+@Model
+class Order {
+  constructor() {
+    this.orderId = null;
+    this.customerName = '';
+    this.orderItems = [];
+  }
+}
+
+const order = new Order();
+order.assign({
+  orderId: '12345',
+  customerName: 'John Doe',
+  orderItems: [
+    { itemId: 1, name: 'Product 1', quantity: 2 }
+  ]
+});
+
+// Will use the configured default options for serialization
+const json = order.toJsonString();
+console.log(json);
+// Output will use lower_underscore naming: 
+// {&quot;order_id&quot;:&quot;12345&quot;,&quot;customer_name&quot;:&quot;John Doe&quot;,&quot;order_items&quot;:[{&quot;item_id&quot;:1,&quot;name&quot;:&quot;Product 1&quot;,&quot;quantity&quot;:2}]}
+</code></pre>
+<h2>Integration Examples</h2>
+<h3>Using with Vue.js</h3>
+<pre class="prettyprint source lang-javascript"><code>import { Model, Normalizable, Validatable } from '@qubit-ltd/common-decorator';
+import { defineComponent, ref } from 'vue';
+
+@Model
+class UserProfile {
+  constructor() {
+    this.username = '';
+    this.email = '';
+    this.bio = '';
+  }
+  
+  @Normalizable
+  @Validatable
+  get username() {
+    return this._username;
+  }
+  
+  set username(value) {
+    this._username = value;
+  }
+  
+  // Other getters and setters...
+}
+
+export default defineComponent({
+  setup() {
+    const profile = ref(new UserProfile());
+    
+    const updateProfile = (formData) => {
+      profile.value.assign(formData);
+      profile.value.normalize();
+      const validation = profile.value.validate();
+      
+      if (validation.valid) {
+        // Save profile
+      } else {
+        // Handle validation errors
+        console.error(validation.message);
+      }
+    };
+    
+    return {
+      profile,
+      updateProfile
+    };
+  }
+});
+</code></pre>
+<h3>Using with Express.js</h3>
+<pre class="prettyprint source lang-javascript"><code>import express from 'express';
+import { Model, Normalizable, Validatable, NonEmpty } from '@qubit-ltd/common-decorator';
+
+const app = express();
+app.use(express.json());
+
+@Model
+class NewUserRequest {
+  constructor() {
+    this.username = '';
+    this.email = '';
+    this.password = '';
+  }
+  
+  @NonEmpty
+  @Normalizable
+  @Validatable
+  get username() {
+    return this._username;
+  }
+  
+  set username(value) {
+    this._username = value;
+  }
+  
+  // Other getters and setters...
+}
+
+app.post('/api/users', (req, res) => {
+  try {
+    const userRequest = NewUserRequest.create(req.body);
+    userRequest.normalize();
+    const validation = userRequest.validate();
+    
+    if (!validation.valid) {
+      return res.status(400).json({ error: validation.message });
+    }
+    
+    // Create user in database
+    return res.status(201).json({ message: 'User created successfully' });
+  } catch (error) {
+    return res.status(500).json({ error: error.message });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Server is running on port 3000');
+});
+</code></pre>
+<h2>Compatibility and Requirements</h2>
+<ul>
+<li><strong>Node.js</strong>: 14.x or higher</li>
+<li><strong>ECMAScript</strong>: ES2022 or higher</li>
+<li><strong>Decorator Support</strong>: Requires babel configuration for Stage 3 decorators</li>
+<li><strong>Browser Support</strong>: Modern browsers with ES6+ support</li>
+</ul>
+<h2>Best Practices</h2>
+<h3>Project Structure</h3>
+<p>When using this library, we recommend organizing your domain models in a structured way:</p>
+<pre class="prettyprint source"><code>src/
+├── models/
+│   ├── base/
+│   │   └── BaseModel.js
+│   ├── User.js
+│   ├── Product.js
+│   └── Order.js
+├── enums/
+│   ├── Status.js
+│   └── Role.js
+└── app.js
+</code></pre>
+<h3>Performance Considerations</h3>
+<ul>
+<li>Use <code>normalize()</code> only when necessary, not on every operation</li>
+<li>Consider caching validation results for frequently accessed objects</li>
+<li>For large collections, use <code>createArray()</code> method instead of mapping each item</li>
+</ul>
+<h3>Type Safety</h3>
+<p>While JavaScript is dynamically typed, this library provides several ways to ensure type safety:</p>
+<ol>
+<li>Use the <code>@Type</code> decorator to enforce type checking for properties</li>
+<li>Use the <code>@ElementType</code> decorator for arrays</li>
+<li>Enable normalization to automatically convert values to the correct type</li>
+</ol>
+<h3>Memory Management</h3>
+<p>When working with large object graphs:</p>
+<ol>
+<li>Avoid deep cloning unnecessarily</li>
+<li>Use the <code>removeEmptyFields</code> option in <code>toJSON</code> for large objects</li>
+<li>Be cautious with circular references when serializing objects</li>
+</ol></article>
     </section>
 
 
@@ -1315,7 +1915,7 @@ See the <a href="LICENSE">LICENSE</a> file for more details.</p></article>
 
 <footer>
     Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
-     on Mon Jan 06 2025 12:29:37 GMT+0800 (China Standard Time)
+     on Mon Apr 21 2025 02:07:33 GMT+0800 (China Standard Time)
     using the <a href="https://github.com/Haixing-Hu/jsdoc-minami">customized Minami theme</a>.
 </footer>