ts-serializable 3.6.0 → 3.7.2

package/README.md

@@ -181,6 +181,33 @@ JSON.stringify(user);
 // Result: {"firstName":"","familyName":""}
 ```
 
+Class to FormData
+------
+
+Sometimes classes contain properties with the File type. Sending such classes via json is a heavy task. Converting a file property to json can freeze the interface for a few seconds if the file is large. A much better solution is to send an Ajax form. Example:
+
+```typescript
+import { Serializable } from "ts-serializable";
+
+export class User extends Serializable {
+
+    public firstName: string = '';
+
+    public familyName: File | null = null;
+
+}
+
+// ... send file function ...
+
+await fetch("api/sendFile", {
+    method: "POST",
+    body: user.toFormData() // <- serialization class to FormData
+});
+
+```
+
+Naming strategies, custom names, ignoring and other decorators are supported during conversion.
+
 Bonus
 ------
 

package/dist/classes/Serializable.d.ts

@@ -68,6 +68,20 @@ export declare class Serializable {
      * @memberof Serializable
      */
     toJSON(): Record<string, unknown>;
+    /**
+     * Serialize 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.
+     *
+     * @param {string} formPrefix Prefix for form property names
+     * @param {FormData} formData Can be update an existing FormData
+     * @returns {FormData}
+     * @memberof Serializable
+     */
+    toFormData(formPrefix?: string, formData?: FormData): FormData;
     /**
      * Process serialization for @jsonIgnore decorator
      *
@@ -98,5 +112,13 @@ export declare class Serializable {
      * @memberof Serializable
      */
     protected deserializeProperty(prop: string, acceptedTypes: AcceptedTypes[], jsonValue: unknown, settings?: Partial<SerializationSettings>): unknown;
-    protected getJsonPropertyName(thisProperty: string, settings?: Partial<SerializationSettings>): string;
+    /**
+     * Extract correct name for property.
+     * Considers decorators for transforming the property name.
+     *
+     * @param {string} property Source name of property
+     * @param {Partial<SerializationSettings>} settings Serialization settings
+     * @returns
+     */
+    protected getJsonPropertyName(property: string, settings?: Partial<SerializationSettings>): string;
 }

package/dist/classes/Serializable.js

@@ -6,6 +6,8 @@
 /* eslint-disable max-statements */
 /* eslint-disable @typescript-eslint/no-unsafe-argument */
 import { SerializationSettings } from "../models/SerializationSettings.js";
+import { classToFormData } from "../utils/ClassToFormData.js";
+import { getPropertyName } from "../utils/GetProperyName.js";
 /**
  * Class how help you deserialize object to classes.
  *
@@ -98,19 +100,38 @@ export class Serializable {
      * @memberof Serializable
      */
     toJSON() {
-        const fromJson = { ...this };
         const toJson = {};
-        for (const prop in fromJson) {
-            // Json.hasOwnProperty(prop) - preserve for deserialization for other classes with methods
-            if (fromJson.hasOwnProperty(prop) && this.hasOwnProperty(prop)) {
-                if (Reflect.getMetadata("ts-serializable:jsonIgnore", this.constructor.prototype, prop) !== true) {
-                    const toProp = this.getJsonPropertyName(prop);
-                    Reflect.set(toJson, toProp, Reflect.get(fromJson, prop));
+        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;
     }
+    /**
+     * Serialize 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.
+     *
+     * @param {string} formPrefix Prefix for form property names
+     * @param {FormData} formData Can be update an existing FormData
+     * @returns {FormData}
+     * @memberof Serializable
+     */
+    toFormData(formPrefix, formData) {
+        return classToFormData(this, formPrefix, formData);
+    }
     /**
      * Process serialization for @jsonIgnore decorator
      *
@@ -227,22 +248,16 @@ export class Serializable {
         this.onWrongType(prop, "is invalid", jsonValue);
         return Reflect.get(this, prop);
     }
-    getJsonPropertyName(thisProperty, settings) {
-        if (Reflect.hasMetadata("ts-serializable:jsonName", this.constructor.prototype, thisProperty)) {
-            return Reflect.getMetadata("ts-serializable:jsonName", this.constructor.prototype, thisProperty);
-        }
-        if (settings?.namingStrategy) {
-            return settings.namingStrategy.toJsonName(thisProperty);
-        }
-        if (Reflect.hasMetadata("ts-serializable:jsonObject", this.constructor)) {
-            const objectSettings = Reflect.getMetadata("ts-serializable:jsonObject", this.constructor);
-            return objectSettings.namingStrategy?.toJsonName(thisProperty) ?? thisProperty;
-        }
-        if (Serializable.defaultSettings.namingStrategy) {
-            const { namingStrategy } = Serializable.defaultSettings;
-            return namingStrategy.toJsonName(thisProperty) ?? thisProperty;
-        }
-        return thisProperty;
+    /**
+     * Extract correct name for property.
+     * Considers decorators for transforming the property name.
+     *
+     * @param {string} property Source name of property
+     * @param {Partial<SerializationSettings>} settings Serialization settings
+     * @returns
+     */
+    getJsonPropertyName(property, settings) {
+        return getPropertyName(this, property, settings);
     }
 }
 /**

package/dist/index.d.ts

@@ -15,3 +15,5 @@ export { SnakeCaseNamingStrategy } from "./naming-strategies/SnakeCaseNamingStra
 export { PascalCaseNamingStrategy } from "./naming-strategies/PascalCaseNamingStrategy.js";
 export { KebabCaseNamingStrategy } from "./naming-strategies/KebabCaseNamingStrategy.js";
 export { CamelCaseNamingStrategy } from "./naming-strategies/CamelCaseNamingStrategy.js";
+export { classToFormData } from "./utils/ClassToFormData.js";
+export { getPropertyName } from "./utils/GetProperyName.js";

package/dist/index.js

@@ -18,3 +18,6 @@ export { SnakeCaseNamingStrategy } from "./naming-strategies/SnakeCaseNamingStra
 export { PascalCaseNamingStrategy } from "./naming-strategies/PascalCaseNamingStrategy.js";
 export { KebabCaseNamingStrategy } from "./naming-strategies/KebabCaseNamingStrategy.js";
 export { CamelCaseNamingStrategy } from "./naming-strategies/CamelCaseNamingStrategy.js";
+// Utils
+export { classToFormData } from "./utils/ClassToFormData.js";
+export { getPropertyName } from "./utils/GetProperyName.js";

package/dist/utils/ClassToFormData.d.ts

@@ -0,0 +1 @@
+export declare const classToFormData: (obj: object, formPrefix?: string, formData?: FormData) => FormData;

package/dist/utils/ClassToFormData.js

@@ -0,0 +1,56 @@
+import { getPropertyName } from "./GetProperyName.js";
+// eslint-disable-next-line max-statements, max-lines-per-function
+export const classToFormData = (obj, formPrefix, formData) => {
+    const newFormData = formData ?? new FormData();
+    const keys = Reflect.ownKeys(obj);
+    for (const key of keys) {
+        if (typeof key === "symbol") {
+            // eslint-disable-next-line no-continue
+            continue;
+        }
+        // eslint-disable-next-line no-prototype-builtins
+        if (obj.hasOwnProperty(key)) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            if (Reflect.getMetadata("ts-serializable:jsonIgnore", obj.constructor.prototype, key) !== true) {
+                const name = formPrefix ?
+                    `${formPrefix}.${getPropertyName(obj, key)}` :
+                    getPropertyName(obj, key);
+                /*
+                 * The function is defined inside the function to capture variables and
+                 * solve the problem of order of definition.
+                 */
+                const processValue = (value, index) => {
+                    if (Array.isArray(value)) {
+                        for (const [oneIndex, oneVal] of value.entries()) {
+                            processValue(oneVal, oneIndex);
+                        }
+                    }
+                    else if (value === null) {
+                        // Null is not sent in the form.
+                    }
+                    else if (value instanceof File) {
+                        newFormData.append(name, value);
+                    }
+                    else if (value instanceof Date) {
+                        newFormData.append(name, value.toISOString());
+                    }
+                    else if (typeof value === "object") {
+                        let prefix = name;
+                        // For arrays of objects in form need add index
+                        if (typeof index === "number") {
+                            prefix += `[${index.toString()}]`;
+                        }
+                        classToFormData(value, prefix, formData);
+                    }
+                    else {
+                        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                        newFormData.append(name, String(value));
+                    }
+                };
+                const uValue = Reflect.get(obj, key);
+                processValue(uValue);
+            }
+        }
+    }
+    return newFormData;
+};

package/dist/utils/GetProperyName.d.ts

@@ -0,0 +1,2 @@
+import { SerializationSettings } from "../models/SerializationSettings.js";
+export declare const getPropertyName: (obj: object, property: string, settings?: Partial<SerializationSettings>) => string;

package/dist/utils/GetProperyName.js

@@ -0,0 +1,20 @@
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+import { Serializable } from "../classes/Serializable.js";
+// eslint-disable-next-line max-statements
+export const getPropertyName = (obj, property, settings) => {
+    if (Reflect.hasMetadata("ts-serializable:jsonName", obj.constructor.prototype, property)) {
+        return Reflect.getMetadata("ts-serializable:jsonName", obj.constructor.prototype, property);
+    }
+    if (settings?.namingStrategy) {
+        return settings.namingStrategy.toJsonName(property);
+    }
+    if (Reflect.hasMetadata("ts-serializable:jsonObject", obj.constructor)) {
+        const objectSettings = Reflect.getMetadata("ts-serializable:jsonObject", obj.constructor);
+        return objectSettings.namingStrategy?.toJsonName(property) ?? property;
+    }
+    if (Serializable.defaultSettings.namingStrategy) {
+        const { namingStrategy } = Serializable.defaultSettings;
+        return namingStrategy.toJsonName(property);
+    }
+    return property;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ts-serializable",
-    "version": "3.6.0",
+    "version": "3.7.2",
     "author": "Eugene Labutin",
     "license": "MIT",
     "homepage": "https://github.com/LabEG/Serializable#readme",
@@ -23,9 +23,10 @@
     "scripts": {
         "lint": "eslint --fix ./src/ ./tests/",
         "test": "node --import ./ts-loader.js --test --test-reporter=spec --test-reporter-destination=stdout \"tests/**/*.spec.ts\"",
+        "test-watch": "node --watch --import ./ts-loader.js --test --test-reporter=spec --test-reporter-destination=stdout \"tests/**/*.spec.ts\"",
         "coverage": "node --import ./ts-loader.js --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info \"tests/**/*.spec.ts\"",
         "build": "tsc --project tsconfig.build.json && node ./dist/index.js",
-        "prepublishOnly": "npm run lint && npm run build && npm run test",
+        "prepublishOnly": "npm run lint && npm run build && npm run test && node ./dist/index.js",
         "release": "cliff-jumper --name 'ts-serializable' --package-path '.' --no-skip-changelog --no-skip-tag",
         "prepare": "husky install"
     },