ts-serializable 4.2.2 → 4.3.2

package/dist/classes/Serializable.js

@@ -1,22 +1,35 @@
-/* eslint-disable max-lines */
-/* eslint-disable no-prototype-builtins */
-/* eslint-disable @typescript-eslint/no-unnecessary-condition */
-/* eslint-disable complexity */
-/* eslint-disable max-lines-per-function */
-/* eslint-disable max-statements */
 /* eslint-disable @typescript-eslint/no-unsafe-argument */
+import { deserializeProperty } from "../functions/DeserializeProperty.js";
 import { SerializationSettings } from "../models/SerializationSettings.js";
-import { classToFormData } from "../utils/ClassToFormData.js";
-import { getPropertyName } from "../utils/GetProperyName.js";
+import { classToFormData } from "../functions/ClassToFormData.js";
+import { getPropertyName } from "../functions/GetPropertyName.js";
+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}
@@ -24,245 +37,194 @@ export class Serializable {
      */
     static defaultSettings = 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 });
+     * ```
      */
     static fromJSON(json, settings) {
         return new this().fromJSON(json, settings);
     }
     /**
-     * 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}');
+     * ```
      */
     static fromString(str, settings) {
         return new this().fromJSON(JSON.parse(str), 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 object.
+     * Uses metadata from decorators to determine how to deserialize each property.
      *
-     * @param {string} str
-     * @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 });
+     * ```
      */
-    fromString(str, settings) {
-        return this.fromJSON(JSON.parse(str), settings);
+    fromJSON(json, settings) {
+        return fromJSON(this, json, settings);
     }
     /**
-     * Fill properties of the current model with data from JSON.
-     *
-     * Example:
-     * const obj: MyObject = new MyObject().fromJSON({...data});
+     * Populates the current instance's properties with data from a JSON string.
+     * Automatically parses the JSON string before populating properties.
      *
-     * @param {object} json
-     * @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}');
+     * ```
      */
-    fromJSON(json, settings) {
-        const unknownJson = json;
-        if (unknownJson === null ||
-            Array.isArray(unknownJson) ||
-            typeof unknownJson !== "object") {
-            this.onWrongType(String(unknownJson), "is not an object", unknownJson);
-            return this;
-        }
-        // eslint-disable-next-line guard-for-in
-        for (const thisProp in this) {
-            // Naming strategy and jsonName decorator
-            let jsonProp = this.getJsonPropertyName(thisProp, settings);
-            // For deep copy
-            if (!unknownJson?.hasOwnProperty(jsonProp) && unknownJson?.hasOwnProperty(thisProp)) {
-                jsonProp = thisProp;
-            }
-            if (unknownJson?.hasOwnProperty(jsonProp) &&
-                this.hasOwnProperty(thisProp) &&
-                Reflect.hasMetadata("ts-serializable:jsonTypes", this.constructor.prototype, thisProp)) {
-                const acceptedTypes = Reflect.getMetadata("ts-serializable:jsonTypes", this.constructor.prototype, thisProp);
-                const jsonValue = Reflect.get(unknownJson, jsonProp);
-                const extractedValue = this.deserializeProperty(thisProp, acceptedTypes, jsonValue, settings);
-                Reflect.set(this, thisProp, extractedValue);
-            }
-        }
-        return this;
+    fromString(str, settings) {
+        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 }
+     * ```
      */
     toJSON() {
-        const toJson = {};
-        const keys = Reflect.ownKeys(this);
-        for (const key of keys) {
-            if (typeof key === "symbol") {
-                // eslint-disable-next-line no-continue
-                continue;
-            }
-            if (this.hasOwnProperty(key)) {
-                if (Reflect.getMetadata("ts-serializable:jsonIgnore", this.constructor.prototype, key) !== true) {
-                    const toProp = this.getJsonPropertyName(key);
-                    Reflect.set(toJson, toProp, Reflect.get(this, key));
-                }
-            }
-        }
-        return toJson;
+        return toJSON(this);
     }
     /**
-     * Serialize the class to FormData.
-     *
-     * 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}
+     * 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.
+     *
+     * @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 });
+     * ```
      */
     toFormData(formPrefix, 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}'
+     * ```
      */
     toString() {
         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.
-     *
-     * @protected
-     * @param {string} prop
-     * @param {string} message
-     * @param {(unknown)} jsonValue
+     * 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.
+     *
+     * @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}`);
+     *   }
+     * }
+     * ```
      */
     onWrongType(prop, message, jsonValue) {
         // eslint-disable-next-line no-console
         console.error(`${this.constructor.name}.fromJSON: json.${prop} ${message}:`, jsonValue);
     }
     /**
-     * Deserialize one property.
-     *
-     * @private
-     * @param {object} object
-     * @param {string} prop
-     * @param {AcceptedTypes[]} acceptedTypes
-     * @param {(unknown)} jsonValue
-     * @returns {(Object | null | void)}
+     * 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.
+     *
+     * @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
     deserializeProperty(prop, acceptedTypes, jsonValue, settings) {
-        for (const acceptedType of acceptedTypes) { // Type Symbol is not a property
-            if ( // Null
-            acceptedType === null &&
-                jsonValue === null) {
-                return null;
-            }
-            else if ( // Void, for deep copy classes only, JSON doesn't have a void type
-            acceptedType === void 0 &&
-                jsonValue === void 0) {
-                return void 0;
-            }
-            else if ( // Boolean, Boolean
-            acceptedType === Boolean &&
-                (typeof jsonValue === "boolean" || jsonValue instanceof Boolean)) {
-                return Boolean(jsonValue);
-            }
-            else if ( // Number, Number
-            acceptedType === Number &&
-                (typeof jsonValue === "number" || jsonValue instanceof Number)) {
-                return Number(jsonValue);
-            }
-            else if ( // String, String
-            acceptedType === String &&
-                (typeof jsonValue === "string" || jsonValue instanceof String)) {
-                return String(jsonValue);
-            }
-            else if ( // Object, Object
-            acceptedType === Object &&
-                (typeof jsonValue === "object")) {
-                return Object(jsonValue);
-            }
-            else if ( // Date
-            acceptedType === Date &&
-                (typeof jsonValue === "string" || jsonValue instanceof String || jsonValue instanceof Date)) {
-                // 0 year, 0 month, 0 days, 0 hours, 0 minutes, 0 seconds
-                let unicodeTime = new Date("0000-01-01T00:00:00.000").getTime();
-                if (typeof jsonValue === "string") {
-                    unicodeTime = Date.parse(jsonValue);
-                }
-                else if (jsonValue instanceof String) {
-                    unicodeTime = Date.parse(String(jsonValue));
-                }
-                else if (jsonValue instanceof Date) {
-                    unicodeTime = jsonValue.getTime();
-                }
-                if (isNaN(unicodeTime)) { // Preserve invalid time
-                    this.onWrongType(prop, "is an invalid date", jsonValue);
-                }
-                return new Date(unicodeTime);
-            }
-            else if ( // Array
-            Array.isArray(acceptedType) &&
-                Array.isArray(jsonValue)) {
-                if (acceptedType[0] === void 0) {
-                    this.onWrongType(prop, "invalid type", jsonValue);
-                }
-                return jsonValue.map((arrayValue) => this.deserializeProperty(prop, acceptedType, arrayValue, settings));
-            }
-            else if ( // Serializable
-            acceptedType !== null &&
-                acceptedType !== void 0 &&
-                !Array.isArray(acceptedType) &&
-                (acceptedType.prototype instanceof Serializable ||
-                    Boolean(Reflect.getMetadata("ts-serializable:jsonObjectExtended", acceptedType))) &&
-                jsonValue !== null &&
-                jsonValue !== void 0 &&
-                typeof jsonValue === "object" && !Array.isArray(jsonValue)) {
-                const TypeConstructor = acceptedType;
-                return new TypeConstructor().fromJSON(jsonValue, settings);
-            }
-            else if ( // Instance any other class, not Serializable, for parsing from other class instances
-            acceptedType instanceof Function &&
-                jsonValue instanceof acceptedType) {
-                return jsonValue;
-            }
-        }
-        // Process incorrect type and return default value
-        this.onWrongType(prop, "is invalid", jsonValue);
-        return Reflect.get(this, prop);
+        return deserializeProperty(this, prop, acceptedTypes, jsonValue, settings);
     }
     /**
-     * Extract the correct name for a property.
-     * Considers decorators for transforming the property name.
-     *
-     * @param {string} property Source name of the property
-     * @param {Partial<SerializationSettings>} settings Serialization settings
-     * @returns
+     * 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.
+     *
+     * @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"
+     * ```
      */
     getJsonPropertyName(property, settings) {
         return getPropertyName(this, property, settings);

package/dist/functions/ClassToFormData.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 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 declare const classToFormData: (obj: object, formPrefix?: string, formData?: FormData) => FormData;

package/dist/{utils → functions}/ClassToFormData.js

@@ -1,13 +1,38 @@
 /* eslint-disable max-statements */
 /* eslint-disable max-lines-per-function */
-import { getPropertyName } from "./GetProperyName.js";
+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, formPrefix, formData) => {
     const newFormData = formData ?? new FormData();

package/dist/functions/DeserializeProperty.d.ts

@@ -0,0 +1,38 @@
+import { AcceptedTypes } from "../models/AcceptedType.js";
+import { SerializationSettings } from "../models/SerializationSettings.js";
+/**
+ * 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 {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
+ * ```
+ */
+export declare const deserializeProperty: (obj: object, prop: string, acceptedTypes: AcceptedTypes[], jsonValue: unknown, settings?: Partial<SerializationSettings>) => unknown;