feat: add support serialization to FormData

Author: LabEG

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()
+});
+
+```
+
+Naming strategies, custom names, ignoring and other decorators are supported during conversion.
+
 Bonus
 ------
 

package.json

@@ -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"
     },

src/classes/Serializable.ts

@@ -8,6 +8,8 @@
 
 import type {AcceptedTypes} from "../models/AcceptedType.js";
 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.
@@ -136,22 +138,43 @@ export class Serializable {
      * @memberof Serializable
      */
     public toJSON (): Record<string, unknown> {
-        const fromJson: this = {...this};
         const toJson: Record<string, unknown> = {};
+        const keys = Reflect.ownKeys(this);
 
-        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));
+        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
+     */
+    public toFormData (formPrefix?: string, formData?: FormData): FormData {
+        return classToFormData(this, formPrefix, formData);
+    }
+
     /**
      * Process serialization for @jsonIgnore decorator
      *
@@ -288,29 +311,16 @@ export class Serializable {
         return Reflect.get(this, prop);
     }
 
-    protected getJsonPropertyName (thisProperty: string, settings?: Partial<SerializationSettings>): string {
-        if (Reflect.hasMetadata("ts-serializable:jsonName", this.constructor.prototype, thisProperty)) {
-            return Reflect.getMetadata("ts-serializable:jsonName", this.constructor.prototype, thisProperty) as string;
-        }
-
-        if (settings?.namingStrategy) {
-            return settings.namingStrategy.toJsonName(thisProperty);
-        }
-
-        if (Reflect.hasMetadata("ts-serializable:jsonObject", this.constructor)) {
-            const objectSettings: Partial<SerializationSettings> = Reflect.getMetadata(
-                "ts-serializable:jsonObject",
-                this.constructor
-            ) as Partial<SerializationSettings>;
-            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
+     */
+    protected getJsonPropertyName (property: string, settings?: Partial<SerializationSettings>): string {
+        return getPropertyName(this, property, settings);
     }
 
 }

src/index.ts

@@ -24,3 +24,7 @@ export {SnakeCaseNamingStrategy} from "./naming-strategies/SnakeCaseNamingStrate
 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";

src/utils/ClassToFormData.ts

@@ -0,0 +1,59 @@
+import {getPropertyName} from "./GetProperyName.js";
+
+// eslint-disable-next-line max-statements, max-lines-per-function
+export const classToFormData = (obj: object, formPrefix?: string, formData?: 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: unknown, index?: number): void => {
+                    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: unknown = Reflect.get(obj, key);
+                processValue(uValue);
+            }
+        }
+    }
+
+    return newFormData;
+};

src/utils/GetProperyName.ts

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

tests/formdata-convertations.spec.ts

@@ -0,0 +1,67 @@
+/* eslint-disable max-lines-per-function */
+/* eslint-disable max-statements */
+
+import("reflect-metadata"); // Polyfill
+import {assert} from "chai";
+import {describe, it} from "node:test";
+
+// Import type {Friend as IFriend} from "./models/User";
+
+
+describe("FormData convertation", () => {
+    it("class can be converted to FormData", async () => {
+        const {User} = await import("./models/User");
+        const json = await import("./jsons/json-generator.json", {with: {type: "json"}});
+
+        const [object] = Reflect.get(json, "default") as typeof json;
+
+        const user = new User().fromJSON(object);
+
+        const formData = user.toFormData();
+
+        assert.isTrue(user instanceof User);
+        assert.isTrue(formData.has("id"), "form don't have field id");
+        assert.strictEqual(user.id, formData.get("id"), "id is not equal");
+        assert.strictEqual(String(user.index), formData.get("index"), "index is not equal");
+        assert.strictEqual(user.guid, formData.get("guid"), "guid is not equal");
+        assert.strictEqual(String(user.isActive), formData.get("isActive"), "isActive is not equal");
+        assert.strictEqual(user.balance, formData.get("balance"), "balance is not equal");
+        assert.strictEqual(user.picture, formData.get("picture"), "picture is not equal");
+        assert.strictEqual(String(user.age), formData.get("age"), "age is not equal");
+        assert.strictEqual(user.eyeColor, formData.get("eyeColor"), "eyeColor is not equal");
+        assert.strictEqual(user.name, formData.get("name"), "name is not equal");
+        assert.strictEqual(user.company, formData.get("company"), "company is not equal");
+        assert.strictEqual(user.email, formData.get("email"), "email is not equal");
+        assert.strictEqual(user.phone, formData.get("phone"), "phone is not equal");
+        assert.strictEqual(user.address, formData.get("address"), "address is not equal");
+        assert.strictEqual(user.about, formData.get("about"), "about is not equal");
+        assert.strictEqual(String(user.latitude), formData.get("latitude"), "latitude is not equal");
+        assert.strictEqual(String(user.longitude), formData.get("longitude"), "longitude is not equal");
+        assert.deepEqual(user.tags, formData.getAll("tags"), "tags is not equal");
+        assert.strictEqual(user.greeting, formData.get("greeting"), "greeting is not equal");
+        assert.strictEqual(user.favoriteFruit, formData.get("favoriteFruit"), "favoriteFruit is not equal");
+
+        fetch("api/sendFile", {
+            method: "POST",
+            body: user.toFormData()
+        });
+
+        /*
+         * Nodejs version of FormData don't support arrays of objects, but C# and browser version of FormData support him.
+         * Because test run under nodejs env, this next part disabled. Check this code in future versions of nodejs.
+         *
+         * user.friends.forEach((friend: IFriend, index: number) => {
+         *     assert.strictEqual(
+         *         String(friend.id),
+         *         formData.get(`friends[${index.toString()}].id`),
+         *         `friend ${String(index)} id is not equal`
+         *     );
+         *     assert.strictEqual(
+         *         friend.name,
+         *         formData.get(`friends[${index.toString()}].name`),
+         *         `friend ${String(index)} name is not equal`
+         *     );
+         * });
+         */
+    });
+});

tests/models/User.ts

@@ -84,4 +84,12 @@ export class User extends Serializable {
     @jsonIgnore()
     public isExpanded: boolean = false;
 
+    public getName (): string {
+        return [
+            this.email,
+            this.company,
+            this.address
+        ].join(" ");
+    }
+
 }