feat: enhance fromJSON function to accept class constructors for deserialization

Author: LabEG

README.md

@@ -298,7 +298,9 @@ The library provides standalone utility functions `fromJSON` and `toJSON` that c
 
 fromJSON Function:
 
-The `fromJSON` function populates an existing object instance with data from JSON, using decorator metadata for type conversion.
+The `fromJSON` function deserializes JSON data into a class instance. It can accept either an existing object instance or a class constructor.
+
+**Usage with instance:**
 
 ```typescript
 import { fromJSON, jsonProperty } from "ts-serializable";
@@ -320,6 +322,7 @@ const json = {
     releaseDate: "2024-01-15T10:00:00.000Z"
 };
 
+// Pass an existing instance
 const product = new Product();
 fromJSON(product, json);
 
@@ -328,13 +331,26 @@ console.log(product.price); // 999.99
 console.log(product.releaseDate instanceof Date); // true
 ```
 
+**Usage with class constructor:**
+
+```typescript
+// Pass a class constructor - the function will create an instance automatically
+const product = fromJSON(Product, json);
+
+console.log(product instanceof Product); // true
+console.log(product.name); // "Laptop"
+console.log(product.price); // 999.99
+```
+
 Benefits:
 
 - Works with plain classes (no need to extend `Serializable`)
+- Accepts both instance and constructor for flexibility
 - Respects all decorators (`@jsonProperty`, `@jsonName`, `@jsonIgnore`)
 - Supports naming strategies
 - Handles nested objects and arrays
 - Type-safe deserialization
+- Perfect for generic programming patterns
 
 toJSON Function:
 
@@ -398,13 +414,34 @@ class ApiRequest {
     public userTags: string[] = [];
 }
 
-// Deserialize from API response
+// Deserialize from API response using constructor
 const apiData = {
     request_id: "REQ-12345",
     user_name: "john_doe",
     user_tags: ["premium", "verified"]
 };
 
+// Using class constructor - creates new instance automatically
+const request = fromJSON(ApiRequest, apiData);
+
+console.log(request instanceof ApiRequest); // true
+console.log(request.requestId); // "REQ-12345"
+console.log(request.userName); // "john_doe"
+
+// Serialize for sending to API
+const jsonToSend = toJSON(request);
+console.log(jsonToSend);
+// Output: {
+//   request_id: "REQ-12345",
+//   user_name: "john_doe",
+//   user_tags: ["premium", "verified"]
+// }
+```
+
+**Alternative approach using instance:**
+
+```typescript
+// Using instance
 const request = new ApiRequest();
 fromJSON(request, apiData);
 
@@ -822,9 +859,22 @@ console.log(team.members[0] instanceof User); // true
 
 ### Standalone Functions
 
-- **`fromJSON<T>(obj: T, json: object, settings?: Partial<SerializationSettings>): T`**
+- **`fromJSON<T>(obj: T | (new () => T), json: object, settings?: Partial<SerializationSettings>): T`**
+
+  Deserializes JSON into an object instance. Accepts either:
+  - An existing object instance to populate
+  - A class constructor to create a new instance
+
+  **Examples:**
+
+  ```typescript
+  // With instance
+  const product = new Product();
+  fromJSON(product, jsonData);
 
-  Deserializes JSON into an existing object instance.
+  // With constructor
+  const product = fromJSON(Product, jsonData);
+  ```
 
 - **`toJSON(obj: Serializable | object): Record<string, unknown>`**
 

src/functions/FromJSON.ts

@@ -63,9 +63,18 @@ import {onWrongType} from "./OnWrongType.js";
  * fromJSON(product, { title: "Laptop" });
  * ```
  */
-// eslint-disable-next-line max-statements
-export const fromJSON = <T extends (Serializable | object)>(obj: T, json: object, settings?: Partial<SerializationSettings>): T => {
+// eslint-disable-next-line max-statements, max-lines-per-function
+export const fromJSON = <T extends (Serializable | object)>(
+    obj: T | (new () => T),
+    json: object,
+    settings?: Partial<SerializationSettings>
+): T => {
     const unknownJson: unknown = json;
+    if (typeof obj === "function") {
+        const ClassConstructor = obj as new () => T;
+        // eslint-disable-next-line no-param-reassign
+        obj = new ClassConstructor();
+    }
 
     if (
         unknownJson === null ||

tests/base-functions.spec.ts

@@ -9,7 +9,7 @@ import type {UserSimple as IUserSimple, FriendSimple as IFriendSimple} from "./m
 import {fromJSON} from "../src/functions/FromJSON";
 
 describe("Base functions", () => {
-    it("user from method fromJSON must be instance of User", async () => {
+    it("should deserialize JSON to User instance using instance method fromJSON()", async () => {
         const {User} = await import("./models/User");
         const json = await import("./jsons/json-generator.json", {with: {type: "json"}});
 
@@ -44,7 +44,7 @@ describe("Base functions", () => {
         });
     });
 
-    it("user from static method fromJSON must be instance of User", async () => {
+    it("should deserialize JSON to User instance using static method fromJSON()", 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;
@@ -78,7 +78,7 @@ describe("Base functions", () => {
         });
     });
 
-    it("user from method fromString must be instance of User", async () => {
+    it("should deserialize JSON string to User instance using instance method fromString()", 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;
@@ -112,7 +112,7 @@ describe("Base functions", () => {
         });
     });
 
-    it("user from static method fromString must be instance of User", async () => {
+    it("should deserialize JSON string to User instance using static method fromString()", 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;
@@ -146,7 +146,7 @@ describe("Base functions", () => {
         });
     });
 
-    it("user from function fromJSON must be instance of User", async () => {
+    it("should deserialize JSON to plain class instance using standalone fromJSON() function", async () => {
         const {UserSimple} = await import("./models/UserSimple");
         const json = await import("./jsons/json-generator.json", {with: {type: "json"}});
 
@@ -180,4 +180,39 @@ describe("Base functions", () => {
             assert.strictEqual(friend.name, object.friends[index].name, `friend ${String(index)} name is not equal`);
         });
     });
+
+    it("should deserialize JSON by passing class constructor to standalone fromJSON() function", async () => {
+        const {UserSimple} = await import("./models/UserSimple");
+        const json = await import("./jsons/json-generator.json", {with: {type: "json"}});
+
+        const [object] = Reflect.get(json, "default") as typeof json;
+
+        const user: IUserSimple = fromJSON(UserSimple, object);
+
+        assert.isTrue(user instanceof UserSimple);
+        assert.strictEqual(user.id, object.id, "id is not equal");
+        assert.strictEqual(user.index, object.index, "index is not equal");
+        assert.strictEqual(user.guid, object.guid, "guid is not equal");
+        assert.strictEqual(user.isActive, object.isActive, "isActive is not equal");
+        assert.strictEqual(user.balance, object.balance, "balance is not equal");
+        assert.strictEqual(user.picture, object.picture, "picture is not equal");
+        assert.strictEqual(user.age, object.age, "age is not equal");
+        assert.strictEqual(user.eyeColor, object.eyeColor, "eyeColor is not equal");
+        assert.strictEqual(user.name, object.name, "name is not equal");
+        assert.strictEqual(user.company, object.company, "company is not equal");
+        assert.strictEqual(user.email, object.email, "email is not equal");
+        assert.strictEqual(user.phone, object.phone, "phone is not equal");
+        assert.strictEqual(user.address, object.address, "address is not equal");
+        assert.strictEqual(user.about, object.about, "about is not equal");
+        assert.strictEqual(user.latitude, object.latitude, "latitude is not equal");
+        assert.strictEqual(user.longitude, object.longitude, "longitude is not equal");
+        assert.deepEqual(user.tags, object.tags, "tags is not equal");
+        assert.strictEqual(user.greeting, object.greeting, "greeting is not equal");
+        assert.strictEqual(user.favoriteFruit, object.favoriteFruit, "favoriteFruit is not equal");
+
+        user.friends.forEach((friend: IFriendSimple, index: number) => {
+            assert.strictEqual(friend.id, object.friends[index].id, `friend ${String(index)} id is not equal`);
+            assert.strictEqual(friend.name, object.friends[index].name, `friend ${String(index)} name is not equal`);
+        });
+    });
 });