feat: enhance documentation with detailed comments for serialization classes and decorators

LabEG · LabEG · commit 20bb3e92a4ba · 2025-04-10T23:34:39.000+03:00
diff --git a/src/classes/Serializable.ts b/src/classes/Serializable.ts
@@ -12,15 +12,15 @@ import {classToFormData} from "../utils/ClassToFormData.js";
 import {getPropertyName} from "../utils/GetProperyName.js";
 
 /**
- * Class how help you deserialize object to classes.
+ * Class that helps you deserialize objects to classes.
  *
  * @export
  * @class Serializable
  */
 export class Serializable {
 
     /**
-     * Global setting for serialization and deserialization
+     * Global settings for serialization and deserialization.
      *
      * @static
      * @type {SerializationSettings}
@@ -29,7 +29,7 @@ export class Serializable {
     public static defaultSettings: SerializationSettings = new SerializationSettings();
 
     /**
-     * Deserialize object from static method.
+     * Deserialize an object using a static method.
      *
      * Example:
      * const obj: MyObject = MyObject.fromJSON({...data});
@@ -48,13 +48,13 @@ export class Serializable {
     }
 
     /**
-     * Deserialize object from static method.
+     * Deserialize an object from a string using a static method.
      *
      * Example:
-     * const obj: MyObject = MyObject.fromString({...data});
+     * const obj: MyObject = MyObject.fromString("{...data}");
      *
      * @static
-     * @param {object} json
+     * @param {string} str
      * @returns {object}
      * @memberof Serializable
      */
@@ -67,10 +67,10 @@ export class Serializable {
     }
 
     /**
-     * Fill property of current model by data from string.
+     * Fill properties of the current model with data from a string.
      *
      * Example:
-     * const obj: MyObject = new MyObject().fromString("{...data}"");
+     * const obj: MyObject = new MyObject().fromString("{...data}");
      *
      * @param {string} str
      * @returns {this}
@@ -81,7 +81,7 @@ export class Serializable {
     }
 
     /**
-     * Fill property of current model by data from json.
+     * Fill properties of the current model with data from JSON.
      *
      * Example:
      * const obj: MyObject = new MyObject().fromJSON({...data});
@@ -98,7 +98,7 @@ export class Serializable {
             Array.isArray(unknownJson) ||
             typeof unknownJson !== "object"
         ) {
-            this.onWrongType(String(unknownJson), "is not object", unknownJson);
+            this.onWrongType(String(unknownJson), "is not an object", unknownJson);
             return this;
         }
 
@@ -132,7 +132,7 @@ export class Serializable {
     }
 
     /**
-     * Process serialization for @jsonIgnore decorator
+     * Process serialization for the @jsonIgnore decorator.
      *
      * @returns {object}
      * @memberof Serializable
@@ -159,15 +159,15 @@ export class Serializable {
     }
 
     /**
-     * Serialize class to FormData.
+     * Serialize the class to FormData.
      *
-     * Can be used for prepare ajax form with files.
-     * Send files via ajax json its heavy task, because need convert file to base 64 format,
-     * user interface can be freeze on many seconds on this operation if file is too big.
-     * Ajax forms its lightweight alternative.
+     * Can be used to prepare an AJAX form with files.
+     * Sending files via AJAX JSON is a heavy task because it requires converting files to base64 format.
+     * The user interface can freeze for several seconds during this operation if the file is too large.
+     * AJAX forms are a lightweight alternative.
      *
      * @param {string} formPrefix Prefix for form property names
-     * @param {FormData} formData Can be update an existing FormData
+     * @param {FormData} formData Can update an existing FormData
      * @returns {FormData}
      * @memberof Serializable
      */
@@ -176,7 +176,7 @@ export class Serializable {
     }
 
     /**
-     * Process serialization for @jsonIgnore decorator
+     * Process serialization for the @jsonIgnore decorator.
      *
      * @returns {string}
      * @memberof Serializable
@@ -186,8 +186,8 @@ export class Serializable {
     }
 
     /**
-     * Process exceptions from wrong types.
-     * By default just print warning in console, but can by override for drop exception or logging to backend.
+     * Process exceptions for incorrect types.
+     * By default, it just prints a warning in the console, but it can be overridden to throw exceptions or log to the backend.
      *
      * @protected
      * @param {string} prop
@@ -201,7 +201,7 @@ export class Serializable {
     }
 
     /**
-     * Deserialize one property
+     * Deserialize one property.
      *
      * @private
      * @param {object} object
@@ -224,7 +224,7 @@ export class Serializable {
                 jsonValue === null
             ) {
                 return null;
-            } else if (// Void, for deep copy classes only, json don't have void type
+            } else if (// Void, for deep copy classes only, JSON doesn't have a void type
                 acceptedType === void 0 &&
                 jsonValue === void 0
             ) {
@@ -264,7 +264,7 @@ export class Serializable {
                     unicodeTime = jsonValue.getTime();
                 }
                 if (isNaN(unicodeTime)) { // Preserve invalid time
-                    this.onWrongType(prop, "is invalid date", jsonValue);
+                    this.onWrongType(prop, "is an invalid date", jsonValue);
                 }
 
                 return new Date(unicodeTime);
@@ -297,25 +297,25 @@ export class Serializable {
                 const TypeConstructor: new () => Serializable = acceptedType as new () => Serializable;
 
                 return new TypeConstructor().fromJSON(jsonValue, settings);
-            } else if (// Instance any other class, not Serializable, for parse from other classes instance
+            } else if (// Instance any other class, not Serializable, for parsing from other class instances
                 acceptedType instanceof Function &&
                 jsonValue instanceof acceptedType
             ) {
                 return jsonValue;
             }
         }
 
-        // Process wrong type and return default value
+        // Process incorrect type and return default value
         this.onWrongType(prop, "is invalid", jsonValue);
 
         return Reflect.get(this, prop);
     }
 
     /**
-     * Extract correct name for property.
+     * Extract the correct name for a property.
      * Considers decorators for transforming the property name.
      *
-     * @param {string} property Source name of property
+     * @param {string} property Source name of the property
      * @param {Partial<SerializationSettings>} settings Serialization settings
      * @returns
      */
diff --git a/src/decorators/JsonIgnore.ts b/src/decorators/JsonIgnore.ts
@@ -1,3 +1,6 @@
+/**
+ * Decorator to mark a property to be ignored during serialization.
+ */
 export const jsonIgnore = (): PropertyDecorator => (
     target: object,
     propertyKey: string | symbol
diff --git a/src/decorators/JsonName.ts b/src/decorators/JsonName.ts
@@ -1,3 +1,8 @@
+/**
+ * Decorator to specify a custom JSON property name for a class property.
+ *
+ * @param {string} jsonPropertyName - The custom JSON property name.
+ */
 export const jsonName = (jsonPropertyName: string): PropertyDecorator => (
     target: object,
     propertyKey: string | symbol
diff --git a/src/decorators/JsonObject.ts b/src/decorators/JsonObject.ts
@@ -1,5 +1,10 @@
 import type {SerializationSettings} from "../models/SerializationSettings.js";
 
+/**
+ * Decorator to mark a class as serializable to JSON.
+ *
+ * @param {Partial<SerializationSettings>} [settings] - Optional serialization settings.
+ */
 export const jsonObject = (settings?: Partial<SerializationSettings>): ClassDecorator => (target: object): void => {
     if (settings) {
         Reflect.defineMetadata("ts-serializable:jsonObject", settings, target);
diff --git a/src/decorators/JsonProperty.ts b/src/decorators/JsonProperty.ts
@@ -1,5 +1,10 @@
 import type {AcceptedTypes} from "./../models/AcceptedType.js";
 
+/**
+ * Decorator to specify the accepted types for a JSON property.
+ *
+ * @param {...AcceptedTypes[]} args - The accepted types for the property.
+ */
 export const jsonProperty = (...args: AcceptedTypes[]): PropertyDecorator => (
     target: object,
     propertyKey: string | symbol
diff --git a/src/enums/DateFormatHandling.ts b/src/enums/DateFormatHandling.ts
@@ -1,3 +1,6 @@
+/**
+ * Enum for handling date formats during serialization.
+ */
 export enum DateFormatHandling {
     IsoDateFormat = 0,
     MicrosoftDateFormat = 1 // Not supported yet
diff --git a/src/enums/DefaultValueHandling.ts b/src/enums/DefaultValueHandling.ts
@@ -1,3 +1,6 @@
+/**
+ * Enum for handling default values during serialization.
+ */
 export enum DefaultValueHandling {
     Include = 0,
     Ignore = 1, // Not supported yet
diff --git a/src/enums/LogLevels.ts b/src/enums/LogLevels.ts
@@ -1,3 +1,6 @@
+/**
+ * Enum for defining log levels.
+ */
 export enum LogLevels {
     Trace = 0,
     Debug = 1,
diff --git a/src/enums/MissingMemberHandling.ts b/src/enums/MissingMemberHandling.ts
@@ -1,3 +1,6 @@
+/**
+ * Enum for handling missing members during deserialization.
+ */
 export enum MissingMemberHandling {
     Ignore = 0,
     Error = 1 // Not supported yet
diff --git a/src/enums/NullValueHandling.ts b/src/enums/NullValueHandling.ts
@@ -1,3 +1,6 @@
+/**
+ * Enum for handling null values during serialization.
+ */
 export enum NullValueHandling {
     Include = 0,
     Ignore = 1 // Not supported yet
diff --git a/src/enums/ReferenceLoopHandling.ts b/src/enums/ReferenceLoopHandling.ts
@@ -1,3 +1,6 @@
+/**
+ * Enum for handling reference loops during serialization.
+ */
 export enum ReferenceLoopHandling {
     Error = 0,
     Ignore = 1,
diff --git a/src/index.ts b/src/index.ts
@@ -1,4 +1,4 @@
-// Decoratore
+// Decorators
 export {jsonIgnore} from "./decorators/JsonIgnore.js";
 export {jsonName} from "./decorators/JsonName.js";
 export {jsonObject} from "./decorators/JsonObject.js";
diff --git a/src/models/AcceptedType.ts b/src/models/AcceptedType.ts
@@ -1,5 +1,8 @@
 /* eslint-disable @typescript-eslint/no-invalid-void-type */
 
+/**
+ * Type definition for accepted types in serialization and deserialization.
+ */
 export type AcceptedType =
   BooleanConstructor |
   DateConstructor |
@@ -12,8 +15,11 @@ export type AcceptedType =
   (new (...args: unknown[]) => object) |
   null |
     void;
-// Add ArrayBufferConstructor, MapConstructor, RegExpConstructor and many others...
+// Add ArrayBufferConstructor, MapConstructor, RegExpConstructor, and many others...
 
 type IRecursiveArray<T> = (IRecursiveArray<T> | T)[];
 
+/**
+ * Type definition for recursive arrays of accepted types.
+ */
 export type AcceptedTypes = AcceptedType | IRecursiveArray<AcceptedType>;
diff --git a/src/models/SerializationSettings.ts b/src/models/SerializationSettings.ts
@@ -1,4 +1,3 @@
-
 import {LogLevels} from "../enums/LogLevels.js";
 import {DefaultValueHandling} from "../enums/DefaultValueHandling.js";
 import {NullValueHandling} from "../enums/NullValueHandling.js";
@@ -8,20 +7,45 @@ import {DateFormatHandling} from "../enums/DateFormatHandling.js";
 import type {INamingStrategy} from "../naming-strategies/INamingStrategy.js";
 
 // From newtonsoft https://www.newtonsoft.com/json/help/html/SerializationSettings.htm
+
+/**
+ * Class representing serialization settings.
+ */
 export class SerializationSettings {
 
+    /**
+     * Specifies how dates are formatted during serialization.
+     */
     public dateFormatHandling: DateFormatHandling = DateFormatHandling.IsoDateFormat;
 
+    /**
+     * Specifies how missing members are handled during deserialization.
+     */
     public missingMemberHandling: MissingMemberHandling = MissingMemberHandling.Ignore;
 
+    /**
+     * Specifies how reference loops are handled during serialization.
+     */
     public referenceLoopHandling: ReferenceLoopHandling = ReferenceLoopHandling.Serialize;
 
+    /**
+     * Specifies how null values are handled during serialization.
+     */
     public nullValueHandling: NullValueHandling = NullValueHandling.Include;
 
+    /**
+     * Specifies how default values are handled during serialization.
+     */
     public defaultValueHandling: DefaultValueHandling = DefaultValueHandling.Ignore;
 
+    /**
+     * Specifies the naming strategy for property names during serialization.
+     */
     public namingStrategy: INamingStrategy | null = null;
 
+    /**
+     * Specifies the log level for serialization operations.
+     */
     public logLevel: LogLevels = LogLevels.Warning;
 
 }
diff --git a/src/naming-strategies/CamelCaseNamingStrategy.ts b/src/naming-strategies/CamelCaseNamingStrategy.ts
@@ -2,12 +2,27 @@
 
 import type {INamingStrategy} from "./INamingStrategy.js";
 
+/**
+ * Naming strategy for converting property names to camel case.
+ */
 export class CamelCaseNamingStrategy implements INamingStrategy {
 
+    /**
+     * Converts a JSON property name to a camel case property name.
+     *
+     * @param {string} name - The JSON property name.
+     * @returns {string} - The camel case property name.
+     */
     public fromJsonName (name: string): string {
         return name.slice(0, 1).toUpperCase() + name.slice(1, name.length);
     }
 
+    /**
+     * Converts a camel case property name to a JSON property name.
+     *
+     * @param {string} name - The camel case property name.
+     * @returns {string} - The JSON property name.
+     */
     public toJsonName (name: string): string {
         return name.slice(0, 1).toLowerCase() + name.slice(1, name.length);
     }
diff --git a/src/naming-strategies/INamingStrategy.ts b/src/naming-strategies/INamingStrategy.ts
@@ -1,6 +1,22 @@
+/**
+ * Interface for defining naming strategies for property names during serialization.
+ */
 export interface INamingStrategy {
 
+    /**
+     * Converts a JSON property name to a class property name.
+     *
+     * @param {string} name - The JSON property name.
+     * @returns {string} - The class property name.
+     */
     fromJsonName: (name: string) => string;
+
+    /**
+     * Converts a class property name to a JSON property name.
+     *
+     * @param {string} name - The class property name.
+     * @returns {string} - The JSON property name.
+     */
     toJsonName: (name: string) => string;
 
 }
diff --git a/src/naming-strategies/KebabCaseNamingStrategy.ts b/src/naming-strategies/KebabCaseNamingStrategy.ts
diff --git a/src/naming-strategies/PascalCaseNamingStrategy.ts b/src/naming-strategies/PascalCaseNamingStrategy.ts
diff --git a/src/utils/ClassToFormData.ts b/src/utils/ClassToFormData.ts
diff --git a/src/utils/GetProperyName.ts b/src/utils/GetProperyName.ts
