refactor: enhance documentation for methods in Serializable class and related functions

Author: LabEG

src/classes/Serializable.ts

@@ -10,15 +10,31 @@ import {fromJSON} from "../functions/FromJSON.js";
 import {toJSON} from "../functions/ToJSON.js";
 
 /**
- * Class that helps you deserialize objects to classes.
+ * Base class that provides serialization and deserialization functionality for converting
+ * objects to and from JSON format. This class uses decorators to define how properties
+ * should be serialized and deserialized.
  *
  * @export
  * @class Serializable
+ * @example
+ * ```typescript
+ * class User extends Serializable {
+ *   @JsonProperty()
+ *   name: string;
+ *
+ *   @JsonProperty()
+ *   age: number;
+ * }
+ *
+ * const user = User.fromJSON({ name: "John", age: 30 });
+ * const json = user.toJSON();
+ * ```
  */
 export class Serializable {
 
     /**
-     * Global settings for serialization and deserialization.
+     * Global default settings for all serialization and deserialization operations.
+     * These settings can be overridden per operation by passing custom settings.
      *
      * @static
      * @type {SerializationSettings}
@@ -27,15 +43,19 @@ export class Serializable {
     public static defaultSettings: SerializationSettings = new SerializationSettings();
 
     /**
-     * Deserialize an object using a static method.
-     *
-     * Example:
-     * const obj: MyObject = MyObject.fromJSON({...data});
+     * Creates a new instance of the class and deserializes JSON data into it.
+     * This is a convenient static method that combines instantiation and deserialization.
      *
      * @static
-     * @param {object} json
-     * @returns {object}
+     * @template T - The type of the Serializable class
+     * @param {object} json - The JSON object to deserialize
+     * @param {Partial<SerializationSettings>} [settings] - Optional settings to override default serialization behavior
+     * @returns {T} A new instance of the class with properties populated from the JSON
      * @memberof Serializable
+     * @example
+     * ```typescript
+     * const user = User.fromJSON({ name: "John", age: 30 });
+     * ```
      */
     public static fromJSON<T extends Serializable>(
         this: new () => T,
@@ -46,15 +66,20 @@ export class Serializable {
     }
 
     /**
-     * Deserialize an object from a string using a static method.
-     *
-     * Example:
-     * const obj: MyObject = MyObject.fromString("{...data}");
+     * Creates a new instance of the class and deserializes JSON string data into it.
+     * Automatically parses the JSON string before deserialization.
      *
      * @static
-     * @param {string} str
-     * @returns {object}
+     * @template T - The type of the Serializable class
+     * @param {string} str - The JSON string to parse and deserialize
+     * @param {Partial<SerializationSettings>} [settings] - Optional settings to override default serialization behavior
+     * @returns {T} A new instance of the class with properties populated from the parsed JSON
      * @memberof Serializable
+     * @throws {SyntaxError} If the string is not valid JSON
+     * @example
+     * ```typescript
+     * const user = User.fromString('{"name":"John","age":30}');
+     * ```
      */
     public static fromString<T extends Serializable>(
         this: new () => T,
@@ -65,94 +90,138 @@ export class Serializable {
     }
 
     /**
-     * Fill properties of the current model with data from JSON.
+     * Populates the current instance's properties with data from a JSON object.
+     * Uses metadata from decorators to determine how to deserialize each property.
      *
-     * Example:
-     * const obj: MyObject = new MyObject().fromJSON({...data});
-     *
-     * @param {object} json
-     * @returns {this}
+     * @param {object} json - The JSON object containing data to populate the instance
+     * @param {Partial<SerializationSettings>} [settings] - Optional settings to override default serialization behavior
+     * @returns {this} The current instance for method chaining
      * @memberof Serializable
+     * @example
+     * ```typescript
+     * const user = new User();
+     * user.fromJSON({ name: "John", age: 30 });
+     * ```
      */
     public fromJSON (json: object, settings?: Partial<SerializationSettings>): this {
         return fromJSON<this>(this, json, settings);
     }
 
     /**
-     * Fill properties of the current model with data from a string.
-     *
-     * Example:
-     * const obj: MyObject = new MyObject().fromString("{...data}");
+     * Populates the current instance's properties with data from a JSON string.
+     * Automatically parses the JSON string before populating properties.
      *
-     * @param {string} str
-     * @returns {this}
+     * @param {string} str - The JSON string to parse and use for populating the instance
+     * @param {Partial<SerializationSettings>} [settings] - Optional settings to override default serialization behavior
+     * @returns {this} The current instance for method chaining
      * @memberof Serializable
+     * @throws {SyntaxError} If the string is not valid JSON
+     * @example
+     * ```typescript
+     * const user = new User();
+     * user.fromString('{"name":"John","age":30}');
+     * ```
      */
     public fromString (str: string, settings?: Partial<SerializationSettings>): this {
         return this.fromJSON(JSON.parse(str), settings);
     }
 
     /**
-     * Process serialization for the @jsonIgnore decorator.
+     * Serializes the current instance to a plain JavaScript object.
+     * Respects @JsonIgnore decorators to exclude specific properties from serialization.
+     * Applies naming strategies and @JsonName decorators for property name transformation.
      *
-     * @returns {object}
+     * @returns {Record<string, unknown>} A plain object representation of the instance
      * @memberof Serializable
+     * @example
+     * ```typescript
+     * const user = new User();
+     * user.name = "John";
+     * user.age = 30;
+     * const json = user.toJSON(); // { name: "John", age: 30 }
+     * ```
      */
     public toJSON (): Record<string, unknown> {
         return toJSON(this);
     }
 
     /**
-     * Serialize the class to FormData.
+     * Serializes the current instance to FormData format, suitable for multipart/form-data requests.
+     * This is particularly useful for AJAX form submissions that include file uploads.
+     * Unlike JSON serialization with base64-encoded files, FormData provides better performance
+     * and avoids UI freezing when handling large files.
      *
-     * 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 update an existing FormData
-     * @returns {FormData}
+     * @param {string} [formPrefix] - Optional prefix to prepend to all form field names
+     * @param {FormData} [formData] - Optional existing FormData instance to append to
+     * @returns {FormData} A FormData instance containing the serialized data
      * @memberof Serializable
+     * @example
+     * ```typescript
+     * const user = new User();
+     * user.name = "John";
+     * user.avatar = fileInput.files[0];
+     * const formData = user.toFormData();
+     * // Use with fetch: fetch('/api/users', { method: 'POST', body: formData });
+     * ```
      */
     public toFormData (formPrefix?: string, formData?: FormData): FormData {
         return classToFormData(this, formPrefix, formData);
     }
 
     /**
-     * Process serialization for the @jsonIgnore decorator.
+     * Serializes the current instance to a JSON string.
+     * This is a convenience method that combines toJSON() with JSON.stringify().
      *
-     * @returns {string}
+     * @returns {string} A JSON string representation of the instance
      * @memberof Serializable
+     * @example
+     * ```typescript
+     * const user = new User();
+     * user.name = "John";
+     * user.age = 30;
+     * const jsonString = user.toString(); // '{"name":"John","age":30}'
+     * ```
      */
     public toString (): string {
         return JSON.stringify(this.toJSON());
     }
 
     /**
-     * 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.
+     * Handles type mismatch errors during deserialization.
+     * By default, logs an error to the console. Can be overridden in subclasses to implement
+     * custom error handling such as throwing exceptions, logging to external services, or
+     * collecting validation errors.
      *
-     * @protected
-     * @param {string} prop
-     * @param {string} message
-     * @param {(unknown)} jsonValue
+     * @public
+     * @param {string} prop - The name of the property that has a type mismatch
+     * @param {string} message - A description of the type error
+     * @param {unknown} jsonValue - The actual value that caused the type mismatch
      * @memberof Serializable
+     * @example
+     * ```typescript
+     * class User extends Serializable {
+     *   onWrongType(prop: string, message: string, jsonValue: unknown): void {
+     *     throw new Error(`Invalid ${prop}: ${message}`);
+     *   }
+     * }
+     * ```
      */
     public onWrongType (prop: string, message: string, jsonValue: unknown): void {
         // eslint-disable-next-line no-console
         console.error(`${this.constructor.name}.fromJSON: json.${prop} ${message}:`, jsonValue);
     }
 
     /**
-     * Deserialize one property.
+     * Deserializes a single property value based on its accepted types.
+     * This method is used internally during deserialization to convert JSON values
+     * to the appropriate TypeScript types defined by decorators.
      *
-     * @private
-     * @param {object} object
-     * @param {string} prop
-     * @param {AcceptedTypes[]} acceptedTypes
-     * @param {(unknown)} jsonValue
-     * @returns {(Object | null | void)}
+     * @public
+     * @param {string} prop - The name of the property being deserialized
+     * @param {AcceptedTypes[]} acceptedTypes - Array of allowed types for this property
+     * @param {unknown} jsonValue - The JSON value to deserialize
+     * @param {Partial<SerializationSettings>} [settings] - Optional settings to override default behavior
+     * @returns {unknown} The deserialized value matching one of the accepted types
      * @memberof Serializable
      */
     // eslint-disable-next-line max-params
@@ -166,12 +235,24 @@ export class Serializable {
     }
 
     /**
-     * Extract the correct name for a property.
-     * Considers decorators for transforming the property name.
+     * Determines the JSON property name for a given class property.
+     * Takes into account @JsonName decorators and naming strategies (camelCase, snake_case, etc.)
+     * defined in the serialization settings.
      *
-     * @param {string} property Source name of the property
-     * @param {Partial<SerializationSettings>} settings Serialization settings
-     * @returns
+     * @public
+     * @param {string} property - The source property name as defined in the class
+     * @param {Partial<SerializationSettings>} [settings] - Optional settings to override default naming behavior
+     * @returns {string} The transformed property name to use in JSON
+     * @memberof Serializable
+     * @example
+     * ```typescript
+     * // With @JsonName decorator
+     * class User extends Serializable {
+     *   @JsonName("user_name")
+     *   userName: string;
+     * }
+     * // user.getJsonPropertyName("userName") returns "user_name"
+     * ```
      */
     public getJsonPropertyName (property: string, settings?: Partial<SerializationSettings>): string {
         return getPropertyName(this, property, settings);

src/functions/ClassToFormData.ts

@@ -3,12 +3,37 @@
 import {getPropertyName} from "./GetPropertyName.js";
 
 /**
- * Converts a class instance to FormData for use in AJAX forms.
+ * Converts a class instance to FormData format for multipart/form-data HTTP requests.
+ * This function recursively processes nested objects, arrays, and handles special types like File and Date.
+ * Properties marked with @JsonIgnore decorator are excluded from the conversion.
  *
- * @param {object} obj - The class instance to convert.
- * @param {string} [formPrefix] - Optional prefix for form property names.
- * @param {FormData} [formData] - Optional existing FormData to update.
- * @returns {FormData} - The resulting FormData object.
+ * @param {object} obj - The class instance or object to convert to FormData
+ * @param {string} [formPrefix] - Optional prefix for form property names (used for nested objects, e.g., "user.address")
+ * @param {FormData} [formData] - Optional existing FormData instance to append to. If not provided, creates a new one
+ * @returns {FormData} The FormData object containing all serialized properties
+ *
+ * @example
+ * ```typescript
+ * const user = {
+ *   name: "John",
+ *   age: 30,
+ *   avatar: fileInput.files[0],
+ *   address: { city: "New York" }
+ * };
+ * const formData = classToFormData(user);
+ * // Results in FormData with entries:
+ * // name: "John"
+ * // age: "30"
+ * // avatar: [File object]
+ * // address.city: "New York"
+ * ```
+ *
+ * @remarks
+ * - File objects are appended directly to FormData
+ * - Date objects are converted to ISO strings
+ * - Null values are skipped
+ * - Arrays are processed recursively with indices for nested objects
+ * - Nested objects use dot notation for property names
  */
 export const classToFormData = (obj: object, formPrefix?: string, formData?: FormData) => {
     const newFormData = formData ?? new FormData();

src/functions/DeserializeProperty.ts

@@ -5,16 +5,39 @@ import {fromJSON} from "./FromJSON";
 import {onWrongType} from "./OnWrongType";
 
 /**
- * Deserializes a property value from JSON based on the accepted types.
- * This function attempts to convert the provided JSON value into one of the specified accepted types,
- * handling primitives, arrays, dates, and serializable objects.
+ * Deserializes a single property value from JSON data based on accepted type definitions.
+ * This function iterates through accepted types and attempts to match and convert the JSON value
+ * to the appropriate TypeScript type. Supports primitives, arrays, dates, and complex object types.
  *
- * @param obj - The object instance to which the property belongs.
- * @param prop - The name of the property being deserialized.
- * @param acceptedTypes - An array of accepted types for the property.
- * @param jsonValue - The JSON value to deserialize.
- * @param settings - Optional serialization settings to customize the deserialization process.
- * @returns The deserialized value matching one of the accepted types, or the original property value if deserialization fails.
+ * @param {object} obj - The object instance to which the property belongs
+ * @param {string} prop - The name of the property being deserialized
+ * @param {AcceptedTypes[]} acceptedTypes - Array of type constructors or type definitions that the property can accept
+ * @param {unknown} jsonValue - The raw JSON value to deserialize and convert
+ * @param {Partial<SerializationSettings>} [settings] - Optional settings to customize deserialization behavior
+ * @returns {unknown} The deserialized and typed value, or the original property value if no type match is found
+ *
+ * @remarks
+ * Supported type conversions:
+ * - `null` - Preserves null values
+ * - `undefined` (void 0) - For deep copy operations
+ * - `Boolean` - Converts boolean values and Boolean objects
+ * - `Number` - Converts numeric values and Number objects
+ * - `String` - Converts string values and String objects
+ * - `Object` - Converts plain objects
+ * - `Date` - Parses ISO strings, Date objects, and validates date values
+ * - `Array` - Recursively deserializes array elements
+ * - `Serializable` subclasses - Creates instances and calls fromJSON
+ * - Custom classes - Creates instances and applies fromJSON for non-Serializable classes
+ * - Instance checks - Validates existing instances of specific classes
+ *
+ * If no type matches, calls `onWrongType` error handler and returns the original property value.
+ *
+ * @example
+ * ```typescript
+ * const acceptedTypes = [String, Number];
+ * const result = deserializeProperty(obj, "age", acceptedTypes, "30");
+ * // Returns the string "30" since String is checked first
+ * ```
  */
 // eslint-disable-next-line max-lines-per-function, max-statements, complexity
 export const deserializeProperty = (