@tsed/json-mapper 8.0.0 → 8.0.2

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tsed/json-mapper",
   "description": "Json mapper module for Ts.ED Framework",
   "type": "module",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
@@ -10,6 +10,7 @@
   "browser": "./lib/browser/json-mapper.umd.min.js",
   "exports": {
     ".": {
+      "@tsed/source": "./src/index.ts",
       "types": "./lib/types/index.d.ts",
       "browser": "./lib/browser/json-mapper.umd.min.js",
       "import": "./lib/esm/index.js",
@@ -41,18 +42,18 @@
     "tslib": "2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.0.0",
-    "@tsed/core": "8.0.0",
-    "@tsed/schema": "8.0.0",
-    "@tsed/typescript": "8.0.0",
+    "@tsed/barrels": "8.0.2",
+    "@tsed/core": "8.0.2",
+    "@tsed/schema": "8.0.2",
+    "@tsed/typescript": "8.0.2",
     "eslint": "9.12.0",
     "typescript": "5.4.5",
     "vitest": "2.1.2",
     "webpack": "^5.75.0"
   },
   "peerDependencies": {
-    "@tsed/core": "8.0.0",
-    "@tsed/schema": "8.0.0"
+    "@tsed/core": "8.0.2",
+    "@tsed/schema": "8.0.2"
   },
   "peerDependenciesMeta": {
     "@tsed/core": {

package/src/components/DateMapper.spec.ts

@@ -0,0 +1,43 @@
+import {DateMapper} from "./DateMapper.js";
+
+describe("DateMapper", () => {
+  describe("deserialize()", () => {
+    it("should return a Date when the data is a string", () => {
+      const date = new Date();
+      const mapper = new DateMapper();
+
+      const value = mapper.deserialize(date.toISOString());
+
+      expect(value).toEqual(date);
+    });
+
+    it("should return a Date when the data is a number", () => {
+      const date = new Date();
+      const mapper = new DateMapper();
+
+      const value = mapper.deserialize(date.getTime());
+
+      expect(value).toEqual(date);
+    });
+
+    it("should return value when the data is a boolean/null/undefined", () => {
+      const date = new Date();
+      const mapper = new DateMapper();
+
+      expect(mapper.deserialize(false)).toEqual(false);
+      expect(mapper.deserialize(true)).toEqual(true);
+      expect(mapper.deserialize(null)).toEqual(null);
+      expect(mapper.deserialize(undefined)).toBeUndefined();
+    });
+  });
+  describe("serialize()", () => {
+    it("should return value", () => {
+      const date = new Date();
+      const mapper = new DateMapper();
+
+      const value = mapper.serialize(date);
+
+      expect(value).toEqual(date.toISOString());
+    });
+  });
+});

package/src/components/DateMapper.ts

@@ -0,0 +1,29 @@
+import {isBoolean} from "@tsed/core";
+
+import {JsonMapper} from "../decorators/jsonMapper.js";
+import {JsonMapperMethods} from "../interfaces/JsonMapperMethods.js";
+
+/**
+ * Mapper for `Date` type.
+ * @jsonmapper
+ * @component
+ */
+@JsonMapper(Date)
+export class DateMapper implements JsonMapperMethods {
+  deserialize(data: string | number): Date;
+  deserialize(data: boolean | null | undefined): boolean | null | undefined;
+  deserialize(data: any): any {
+    // don't convert unexpected data. In normal case, Ajv reject unexpected data.
+    // But by default, we have to skip data deserialization and let user to apply
+    // the right mapping
+    if (isBoolean(data) || data === null || data === undefined) {
+      return data;
+    }
+
+    return new Date(data);
+  }
+
+  serialize(object: Date): any {
+    return object ? new Date(object).toISOString() : object;
+  }
+}

package/src/components/PrimitiveMapper.spec.ts

@@ -0,0 +1,179 @@
+import {catchError} from "@tsed/core";
+
+import {PrimitiveMapper} from "./PrimitiveMapper.js";
+
+describe("PrimitiveMapper", () => {
+  describe("deserialize()", () => {
+    it("should return value (number => string)", () => {
+      const mapper = new PrimitiveMapper();
+      const data = 1;
+      const ctx = {
+        type: String,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      const value = mapper.deserialize(data, ctx as never);
+
+      expect(value).toEqual("1");
+    });
+    it("should return value (string => string)", () => {
+      const mapper = new PrimitiveMapper();
+      const data = "1";
+      const ctx = {
+        type: String,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      const value = mapper.deserialize(data, ctx as never);
+
+      expect(value).toEqual("1");
+    });
+    it("should return value (null => number)", () => {
+      const mapper = new PrimitiveMapper();
+      const data = null;
+      const ctx = {
+        type: Number,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      const value = mapper.deserialize(data, ctx as never);
+
+      expect(value).toEqual(null);
+    });
+    it("should return value ('null' => number)", () => {
+      const mapper = new PrimitiveMapper();
+      const data = "null";
+      const ctx = {
+        type: Number,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      const value = mapper.deserialize(data, ctx as never);
+
+      expect(value).toEqual(null);
+    });
+    it("should return value (string => number)", () => {
+      const mapper = new PrimitiveMapper();
+      const data = "1";
+      const ctx = {
+        type: Number,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      const value = mapper.deserialize(data, ctx as never);
+
+      expect(value).toEqual(1);
+    });
+    it("should return value (number => number)", () => {
+      const mapper = new PrimitiveMapper();
+      const data = 1;
+      const ctx = {
+        type: Number,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      const value = mapper.deserialize(data, ctx as never);
+
+      expect(value).toEqual(1);
+    });
+    it("should return value (wrong number => number)", () => {
+      const mapper = new PrimitiveMapper();
+      const data = "t1";
+      const ctx = {
+        type: Number,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      let actualError: any = catchError(() => mapper.deserialize(data, ctx as never));
+
+      expect(actualError.message).toEqual("Cast error. Expression value is not a number.");
+    });
+    it("should return value (truthy => boolean)", () => {
+      const mapper = new PrimitiveMapper();
+      const ctx: any = {
+        type: Boolean,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      expect(mapper.deserialize(1, ctx)).toEqual(true);
+      expect(mapper.deserialize("1", ctx)).toEqual(true);
+      expect(mapper.deserialize("true", ctx)).toEqual(true);
+      expect(mapper.deserialize(true, ctx)).toEqual(true);
+    });
+    it("should return value (falsy => boolean)", () => {
+      const mapper = new PrimitiveMapper();
+      const ctx: any = {
+        type: Boolean,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      expect(mapper.deserialize(0, ctx)).toEqual(false);
+      expect(mapper.deserialize("0", ctx)).toEqual(false);
+      expect(mapper.deserialize("", ctx)).toEqual(false);
+      expect(mapper.deserialize("false", ctx)).toEqual(false);
+      expect(mapper.deserialize(false, ctx)).toEqual(false);
+      expect(mapper.deserialize(undefined, ctx)).toBeUndefined();
+    });
+    it("should return value (null => boolean)", () => {
+      const mapper = new PrimitiveMapper();
+      const ctx: any = {
+        type: Boolean,
+        collectionType: undefined,
+        next: vi.fn()
+      };
+
+      expect(mapper.deserialize(null, ctx)).toEqual(null);
+      expect(mapper.deserialize("null", ctx)).toEqual(null);
+    });
+  });
+  describe("serialize()", () => {
+    it("should return value (string to string)", () => {
+      const mapper = new PrimitiveMapper();
+
+      const value = mapper.serialize("1", {type: String} as any);
+
+      expect(value).toEqual("1");
+    });
+
+    it("should return value (string to number)", () => {
+      const mapper = new PrimitiveMapper();
+
+      const value = mapper.serialize("1", {type: Number} as any);
+
+      expect(value).toEqual(1);
+    });
+
+    it("should return value (object)", () => {
+      const mapper = new PrimitiveMapper();
+
+      // in this case it's probably intended to be an object (or an error but we can decide for the developer and we can broke the code)
+      // TODO: for the major version, we can return undefined or throw an error?
+      const value = mapper.serialize({"1": "1"} as any, {type: Number} as any);
+
+      expect(value).toEqual({"1": "1"});
+    });
+
+    it("should return value (null)", () => {
+      const mapper = new PrimitiveMapper();
+      const value = mapper.serialize(null as any, {type: Number} as any);
+
+      expect(value).toEqual(null);
+    });
+
+    it("should return value (undefined)", () => {
+      const mapper = new PrimitiveMapper();
+      const value = mapper.serialize(undefined as any, {type: Number} as any);
+
+      expect(value).toEqual(undefined);
+    });
+  });
+});

package/src/components/PrimitiveMapper.ts

@@ -0,0 +1,64 @@
+import {nameOf} from "@tsed/core";
+
+import {JsonMapper} from "../decorators/jsonMapper.js";
+import {JsonMapperCtx, JsonMapperMethods} from "../interfaces/JsonMapperMethods.js";
+
+function isNullish(data: any) {
+  return [null, "null"].includes(data);
+}
+
+export class CastError extends Error {
+  name = "CAST_ERROR";
+
+  constructor(message: string) {
+    super(`Cast error. ${message}`);
+  }
+}
+
+/**
+ * Mapper for the `String`, `Number`, `BigInt` and `Boolean` types.
+ * @jsonmapper
+ * @component
+ */
+@JsonMapper(String, Number, Boolean, BigInt)
+export class PrimitiveMapper implements JsonMapperMethods {
+  deserialize<T>(data: any, ctx: JsonMapperCtx): string | number | boolean | void | null | BigInt {
+    return (this as any)[nameOf(ctx.type)] ? (this as any)[nameOf(ctx.type)](data, ctx) : undefined;
+  }
+
+  serialize(object: string | number | boolean | BigInt, ctx: JsonMapperCtx): string | number | boolean | BigInt {
+    return (this as any)[nameOf(ctx?.type)] && typeof object !== "object" ? (this as any)[nameOf(ctx.type)](object, ctx) : object;
+  }
+
+  protected String(data: any) {
+    return data === null ? null : "" + data;
+  }
+
+  protected Boolean(data: any) {
+    if (["true", "1", true].includes(data)) return true;
+    if (["false", "0", false].includes(data)) return false;
+    if (isNullish(data)) return null;
+    if (data === undefined) return undefined;
+
+    return !!data;
+  }
+
+  protected Number(data: any) {
+    if (isNullish(data)) return null;
+    if (data === undefined) return data;
+
+    const n = +data;
+
+    if (isNaN(n)) {
+      throw new CastError("Expression value is not a number.");
+    }
+
+    return n;
+  }
+
+  protected BigInt(data: any) {
+    if (isNullish(data)) return null;
+
+    return BigInt(data);
+  }
+}

package/src/components/SymbolMapper.spec.ts

@@ -0,0 +1,23 @@
+import {SymbolMapper} from "./SymbolMapper.js";
+
+describe("SymbolMapper", () => {
+  describe("deserialize()", () => {
+    it("should return value", () => {
+      const mapper = new SymbolMapper();
+
+      const value = mapper.deserialize("SYMBOL");
+
+      expect(typeof value).toEqual("symbol");
+      expect(value.toString()).toEqual("Symbol(SYMBOL)");
+    });
+  });
+  describe("serialize()", () => {
+    it("should return value", () => {
+      const mapper = new SymbolMapper();
+
+      const value = mapper.serialize(Symbol.for("SYMBOL"));
+
+      expect(value).toEqual("SYMBOL");
+    });
+  });
+});

package/src/components/SymbolMapper.ts

@@ -0,0 +1,19 @@
+import {JsonMapper} from "../decorators/jsonMapper.js";
+import {JsonMapperMethods} from "../interfaces/JsonMapperMethods.js";
+
+/**
+ * Mapper for the `Symbol` type.
+ *
+ * @jsonmapper
+ * @component
+ */
+@JsonMapper(Symbol)
+export class SymbolMapper implements JsonMapperMethods {
+  deserialize(data: string): symbol {
+    return Symbol.for(data);
+  }
+
+  serialize(object: Symbol): any {
+    return object.toString().replace("Symbol(", "").replace(")", "");
+  }
+}

package/src/decorators/afterDeserialize.ts

@@ -0,0 +1,39 @@
+import {JsonEntityFn, JsonHookContext} from "@tsed/schema";
+
+export interface AfterDeserializeCallback {
+  (value: any, ctx: JsonHookContext): any;
+}
+
+/**
+ * Call the function after JsonMapper.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * @AfterDeserialize((data: Model) => { // After deserialize get the instance class
+ *    if (data.prop1 === 'VALUE' && data.prop2 !== 'VALUE2') {
+ *      throw BadRequest('MyMessage'); // or throw a ValidationError
+ *    } else {
+ *      data.prop2 = 'VALUE2';
+ *      return data;
+ *    }
+ * })
+ * class Model {
+ *    @Property()
+ *    prop1: string;
+ *    @Property()
+ *    prop2: string;
+ * }
+ * ```
+ *
+ * @returns {Function}
+ * @decorator
+ * @schema
+ * @property
+ * @param cb
+ */
+export function AfterDeserialize(cb: AfterDeserializeCallback): ClassDecorator {
+  return JsonEntityFn((storedJson) => {
+    storedJson.schema.$hooks.on("afterDeserialize", cb);
+  });
+}

package/src/decorators/beforeDeserialize.ts

@@ -0,0 +1,39 @@
+import {JsonEntityFn, JsonHookContext} from "@tsed/schema";
+
+export interface BeforeDeserializeCallback {
+  (value: any, ctx: JsonHookContext): any;
+}
+
+/**
+ * Call the function before JsonMapper.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * @BeforeDeserialize((data: Record<string, unknown>) => { // Before deserialize get the data
+ *    if (data.prop1 === 'VALUE' && data.prop2 !== 'VALUE2') {
+ *      throw BadRequest('MyMessage'); // or throw a ValidationError
+ *    } else {
+ *      data.prop2 = 'VALUE2';
+ *      return data;
+ *    }
+ * })
+ * class Model {
+ *    @Property()
+ *    prop1: string;
+ *    @Property()
+ *    prop2: string;
+ * }
+ * ```
+ *
+ * @returns {Function}
+ * @decorator
+ * @schema
+ * @property
+ * @param cb
+ */
+export function BeforeDeserialize(cb: BeforeDeserializeCallback): ClassDecorator {
+  return JsonEntityFn((storedJson) => {
+    storedJson.schema.$hooks.on("beforeDeserialize", cb);
+  });
+}

package/src/decorators/jsonMapper.ts

@@ -0,0 +1,16 @@
+import {Type} from "@tsed/core";
+
+import {registerJsonTypeMapper} from "../domain/JsonMapperTypesContainer.js";
+
+/**
+ * Register a new JsonMapper Type
+ * @param types
+ * @constructor
+ */
+export function JsonMapper(...types: (any | Type)[]): ClassDecorator {
+  return (target) => {
+    types.forEach((type) => {
+      registerJsonTypeMapper(type, target as any);
+    });
+  };
+}

package/src/decorators/onDeserialize.ts

@@ -0,0 +1,29 @@
+import {JsonEntityFn, JsonHookContext} from "@tsed/schema";
+
+export interface OnDeserializeCallback {
+  (value: any, ctx: JsonHookContext): any;
+}
+
+/**
+ * Call the function before property deserialization.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @OnDeserialize(v => v + 1)
+ *    property: string;
+ * }
+ * ```
+ *
+ * @returns {Function}
+ * @decorator
+ * @schema
+ * @property
+ * @param cb
+ */
+export function OnDeserialize(cb: OnDeserializeCallback): PropertyDecorator {
+  return JsonEntityFn((storedJson) => {
+    storedJson.schema.$hooks.on("onDeserialize", cb);
+  });
+}

package/src/decorators/onSerialize.ts

@@ -0,0 +1,29 @@
+import {JsonEntityFn, JsonHookContext} from "@tsed/schema";
+
+export interface OnSerializeCallback {
+  (value: any, ctx: JsonHookContext): any;
+}
+
+/**
+ * Call the function before property serialization.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * class Model {
+ *    @OnSerialize(v => v + 1)
+ *    property: string;
+ * }
+ * ```
+ *
+ * @returns {Function}
+ * @decorator
+ * @schema
+ * @property
+ * @param cb
+ */
+export function OnSerialize(cb: OnSerializeCallback): PropertyDecorator {
+  return JsonEntityFn((storedJson) => {
+    storedJson.schema.$hooks.on("onSerialize", cb);
+  });
+}