@qubit-ltd/common-decorator 3.8.10 → 3.9.0

package/README.md

@@ -1,4 +1,4 @@
- # js-common-decorator
+# js-common-decorator
 
 [![npm package](https://img.shields.io/npm/v/@qubit-ltd/common-decorator.svg)](https://npmjs.com/package/@qubit-ltd/common-decorator)
 [![License](https://img.shields.io/badge/License-Apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
@@ -8,9 +8,29 @@
 
 [@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 May 2023) 
+supports the most recent (currently November 2023) 
 [stage 3 proposal of JavaScript decorators].
 
+## Features
+
+- **Modern Decorator Support**: Compatible with the latest Stage 3 proposal for JavaScript decorators
+- **Model Enhancement**: `@Model` decorator adds common methods to domain model classes
+- **Enum Implementation**: `@Enum` decorator provides Java-like enumeration capabilities
+- **Validation Support**: `@Validatable` decorator enables field validation
+- **Normalization Support**: `@Normalizable` decorator enables field normalization
+- **Type Safety**: `@Type` and `@ElementType` decorators for type checking
+- **Serialization Utilities**: Built-in JSON serialization/deserialization support
+
+## Installation
+
+```bash
+# Using npm
+npm install @qubit-ltd/common-decorator
+
+# Using yarn
+yarn add @qubit-ltd/common-decorator
+```
+
 ## <span id="content">Table of Contents</span>
 
 - [Usage](#usage)
@@ -1004,14 +1024,14 @@ expect(opt3.convertNaming).toBe(false);
 
 ## <span id="configuration">Configuration</span>
 
-This library uses the most recent (currently May 2023)
+This library uses the most recent (currently November 2023)
 [stage 3 proposal of JavaScript decorators]. Therefore, you must configure
 [Babel] with [@babel/plugin-transform-class-properties] and the
 [@babel/plugin-proposal-decorators] plugins.
 
-**NOTE:** To support the [stage 3 proposal of JavaScript decorator metadata],
-the version of the [Babel] plugin [@babel/plugin-proposal-decorators] must be
-at least `7.23.0`.
+**NOTE:** To support the [stage 3 proposal of JavaScript decorator metadata] 
+at November 2023, the version of the [Babel] plugin [@babel/plugin-proposal-decorators] 
+must be at least `7.24.0`.
 
 ### <span id="webpack">Bundling with [webpack]</span>
 
@@ -1031,7 +1051,7 @@ at least `7.23.0`.
       ],
       "plugins": [
         "@babel/plugin-transform-runtime",
-        ["@babel/plugin-proposal-decorators", { "version": "2023-05" }],
+        ["@babel/plugin-proposal-decorators", { "version": "2023-11" }],
         "@babel/plugin-transform-class-properties"
       ]
     }
@@ -1055,7 +1075,7 @@ at least `7.23.0`.
       ],
       "plugins": [
         "@babel/plugin-transform-runtime",
-        ["@babel/plugin-proposal-decorators", { "version": "2023-05" }],
+        ["@babel/plugin-proposal-decorators", { "version": "2023-11" }],
         "@babel/plugin-transform-class-properties"
       ]
     }
@@ -1154,3 +1174,608 @@ See the [LICENSE](LICENSE) file for more details.
 [vite-plugin-vue]: https://www.npmjs.com/package/@vitejs/plugin-vue
 [vite-plugin-babel]: https://www.npmjs.com/package/vite-plugin-babel
 [our version of vite-plugin-babel]: https://npmjs.com/package/@qubit-ltd/vite-plugin-babel
+
+## Front-end and Back-end Data Exchange Example
+
+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.
+
+### Complete Example
+
+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., `order_id`), while the front-end code uses camelCase (e.g., `orderId`). Additionally, order IDs use Java's Long type (which may exceed JavaScript's safe integer range).
+
+First, let's define our domain models:
+
+```javascript
+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)
+    // {
+    //   "id": "9223372036854775807",  // Note: Max value of Java Long, exceeds JS Number safe range
+    //   "order_number": "ORD-2023-001",
+    //   "customer_id": "5678",
+    //   "customer_name": "John Doe",
+    //   "order_date": "2023-08-15T14:30:00.000Z",
+    //   "order_items": [
+    //     {
+    //       "id": "8345678912345678901",  // Another large integer
+    //       "product_id": "101",
+    //       "product_name": "Laptop",
+    //       "quantity": 1,
+    //       "unit_price": 999.99
+    //     },
+    //     {
+    //       "id": "8345678912345678902",
+    //       "product_id": "202",
+    //       "product_name": "Wireless Mouse",
+    //       "quantity": 2,
+    //       "unit_price": 29.99
+    //     }
+    //   ],
+    //   "total_amount": 1059.97,
+    //   "status": "PENDING",
+    //   "note": 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: "ORD-2023-001" (converted to camelCase)
+    console.log(order.orderItems[0].productName);  // Output: "Laptop"
+    
+    // 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:
+    // {
+    //   "id": "9223372036854775807",  // BigInt converted to string, without 'n' suffix
+    //   "order_number": "ORD-2023-001",
+    //   "customer_id": "5678",
+    //   "customer_name": "John Doe",
+    //   "order_date": "2023-08-15T14:30:00.000Z",
+    //   "order_items": [
+    //     {
+    //       "id": "8345678912345678901",
+    //       "product_id": "101",
+    //       "product_name": "Laptop",
+    //       "quantity": 1,
+    //       "unit_price": 999.99
+    //     },
+    //     // ...other order items
+    //   ],
+    //   "total_amount": 1059.97,
+    //   "status": "PENDING"
+    //   // 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);
+}
+
+```
+
+### Key Points
+
+1. **Automatic Naming Style Conversion**:
+   - Data from the back-end uses snake_case format (e.g., `order_number`)
+   - Front-end domain objects use camelCase format (e.g., `orderNumber`)
+   - Through `DefaultOptions.set('assign', {...})` configuration, `Model.create()` and `model.assign()` automatically convert naming styles
+   - Through `DefaultOptions.set('toJSON', {...})` configuration, `model.toJSON()` automatically converts camelCase back to snake_case
+
+2. **Large Integer Handling**:
+   - Back-end uses Java Long type IDs (e.g., `9223372036854775807`) that exceed JavaScript's safe integer range
+   - `Model.create()` and `model.assign()` automatically convert these large integers to JavaScript's BigInt type
+   - `model.toJSON()` automatically converts BigInt to the correct JSON format (without the 'n' suffix)
+
+3. **Empty Field Handling**:
+   - With `removeEmptyFields: true` configuration, `model.toJSON()` automatically removes null, undefined, and empty string properties
+   - In the example, the 'note' field with null or empty string value won't be sent to the back-end
+
+4. **Type Conversion and Validation**:
+   - Use `@Type` and `@ElementType` decorators to ensure type safety
+   - Use `model.normalize()` for data normalization
+   - Use `model.validate()` to validate data integrity
+
+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.
+
+## Advanced Usage
+
+### Combining Multiple Decorators
+
+You can combine multiple decorators to add rich functionality to your classes:
+
+```javascript
+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
+```
+
+### Custom Validation and Normalization
+
+You can implement custom validation and normalization logic:
+
+```javascript
+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;
+  }
+}
+```
+
+### Working with DefaultOptions
+
+You can configure default options for various operations:
+
+```javascript
+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: 
+// {"order_id":"12345","customer_name":"John Doe","order_items":[{"item_id":1,"name":"Product 1","quantity":2}]}
+```
+
+## Integration Examples
+
+### Using with Vue.js
+
+```javascript
+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
+    };
+  }
+});
+```
+
+### Using with Express.js
+
+```javascript
+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');
+});
+```
+
+## Compatibility and Requirements
+
+- **Node.js**: 14.x or higher
+- **ECMAScript**: ES2022 or higher
+- **Decorator Support**: Requires babel configuration for Stage 3 decorators
+- **Browser Support**: Modern browsers with ES6+ support
+
+## Best Practices
+
+### Project Structure
+
+When using this library, we recommend organizing your domain models in a structured way:
+
+```
+src/
+├── models/
+│   ├── base/
+│   │   └── BaseModel.js
+│   ├── User.js
+│   ├── Product.js
+│   └── Order.js
+├── enums/
+│   ├── Status.js
+│   └── Role.js
+└── app.js
+```
+
+### Performance Considerations
+
+- Use `normalize()` only when necessary, not on every operation
+- Consider caching validation results for frequently accessed objects
+- For large collections, use `createArray()` method instead of mapping each item
+
+### Type Safety
+
+While JavaScript is dynamically typed, this library provides several ways to ensure type safety:
+
+1. Use the `@Type` decorator to enforce type checking for properties
+2. Use the `@ElementType` decorator for arrays
+3. Enable normalization to automatically convert values to the correct type
+
+### Memory Management
+
+When working with large object graphs:
+
+1. Avoid deep cloning unnecessarily
+2. Use the `removeEmptyFields` option in `toJSON` for large objects
+3. Be cautious with circular references when serializing objects