Adjusted code formatting, documentation

Author: andreas-aeschlimann

CHANGELOG.md

@@ -1,3 +1,17 @@
+# v1.3.0 (2020-04-13)
+
+## Bug Fixes
+
+* Fixed content of `package-lock.json`, closes #125
+
+## Features
+
+* Implemented `ignoreRequiredCheck` flag and allow serialization without having instances, closes [#126](https://github.com/AppVision-GmbH/json2typescript/pull/126)
+
+## Breaking Changes
+
+* In previous version, the serialization of plain objects failed, because instances of classes were required. As of now, the serialization of plain object may succeed if the structure matches the class structure. Thus, this is considered a soft breaking change.
+
 # v1.2.5 (2020-03-01)
 
 ## Bug Fixes

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2018 Andreas Aeschlimann
+Copyright (c) 2020 Andreas Aeschlimann
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -16,4 +16,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -359,8 +359,9 @@ The type is still checked as soon the property is present again.
 The same applies for the case when you try to serialize a TypeScript object to a JSON object. If the property is not defined in the class and optional, it will not be added to the JSON object.
 
 > Tip: Some API's return null instead of omitting optional values. 
-If you flag a property as optional, `json2typescript` will ignore null values and keep the default value of the property instead. 
+If you flag a property as optional, `json2typescript` will ignore (JSON) null values at deserialization and keep the default value of the property instead. 
 This fact is particularly helpful if your project uses TypeScript `strictNullChecks` or/and disallows `null` values through the `valueCheckingMode` property in `json2typescript`.
+Furthermore, note that the instance property `ignoreRequiredCheck` – if set to true – overrides all `isOptional` values for all properties.
 
 #### Important notes
 
@@ -482,13 +483,23 @@ You may assign the following two values:
 
 The default is `PropertyMatchingRule.CASE_STRICT`.
 
+#### Ignore required property checks
+
+`(bool) JsonConvertignoreRequiredCheck`
+
+Determines whether the check for required properties should be ignored, making all mapped values optional, whether or not the isOptional property mapping parameter is set.
+If true, any missing properties (undefined) when serializing or deserializing will be ignored, as if they were marked optional.  
+Note that properties explicitly set to null will be unaffected by this flag – they will be ignored if optional and included if not.
+
+The default is `false`.
+
 ### Public methods
 
 `json2typescript` allows you to map JSON objects (or arrays) to TypeScript objects (or arrays) and vice versa.
 
 #### Serializing (TypeScript to JSON)
 
-`(any) serialize(data: T | T[])`
+`(any) serialize(data: any | any[])`
 
 Tries to serialize a TypeScript object or array of objects to JSON.
 
@@ -506,8 +517,8 @@ Tries to deserialize given JSON to a TypeScript object or array of objects.
 
 The methods `serialize()` and `deserialize()` will automatically detect the dimension of your param (either object or array).
 In case you would like to force `json2typescript` to use a specific way, you can use the following methods instead:
-- `(any) serializeObject(instance: T)`
-- `(any[]) serializeArray(instanceArray: T[])`
+- `(any) serializeObject(instance: any)`
+- `(any[]) serializeArray(instanceArray: any[])`
 - `(T) deserializeObject(jsonObject: any, classReference: { new(): T })`
 - `(T[]) deserializeArray(jsonArray: any[], classReference: { new(): T })`
 

src/json2typescript/json-convert-enums.ts

@@ -6,7 +6,6 @@
  * - ENABLE: json2typescript is enabled, but only errors are logged
  * - LOGGING: json2typescript is enabled and detailed information is logged
  *
- * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
  * @see https://www.npmjs.com/package/json2typescript full documentation
  */
 export enum OperationMode {
@@ -22,7 +21,6 @@ export enum OperationMode {
  * - CASE_STRICT: JSON properties need to match exactly the names in the decorators
  * - CASE_INSENSITIVE: JSON properties need to match names in the decorators, but names they are not case sensitive
  *
- * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
  * @see https://www.npmjs.com/package/json2typescript full documentation
  */
 export enum PropertyMatchingRule {
@@ -38,11 +36,10 @@ export enum PropertyMatchingRule {
  * - ALLOW_OBJECT_NULL: objects in the JSON are allowed to be null, primitive types are not allowed to be null
  * - DISALLOW_NULL: no null values are tolerated in the JSON
  *
- * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
  * @see https://www.npmjs.com/package/json2typescript full documentation
  */
 export enum ValueCheckingMode {
     ALLOW_NULL = 1,
     ALLOW_OBJECT_NULL = 2,
     DISALLOW_NULL = 3
-};
+};

src/json2typescript/json-convert.ts

@@ -5,7 +5,6 @@ import { Any } from "./any";
 /**
  * Offers a simple API for mapping JSON objects to TypeScript/JavaScript classes and vice versa.
  *
- * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
  * @see https://www.npmjs.com/package/json2typescript full documentation on NPM
  */
 export class JsonConvert {
@@ -32,7 +31,8 @@ export class JsonConvert {
      * - OperationMode.DISABLE: json2typescript will be disabled, no type checking or mapping is done
      * - OperationMode.ENABLE: json2typescript is enabled, but only errors are logged
      * - OperationMode.LOGGING: json2typescript is enabled and detailed information is logged
-     * @returns {number}
+     *
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     get operationMode(): number {
         return this._operationMode;
@@ -45,7 +45,8 @@ export class JsonConvert {
      * - OperationMode.DISABLE: json2typescript will be disabled, no type checking or mapping is done
      * - OperationMode.ENABLE: json2typescript is enabled, but only errors are logged
      * - OperationMode.LOGGING: json2typescript is enabled and detailed information is logged
-     * @param value
+     *
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     set operationMode(value: number) {
         if (value in OperationMode) this._operationMode = value;
@@ -69,7 +70,7 @@ export class JsonConvert {
      * - ValueCheckingMode.ALLOW_OBJECT_NULL: objects in the JSON are allowed to be null, primitive types are not allowed to be null
      * - ValueCheckingMode.DISALLOW_NULL: no null values are tolerated in the JSON
      *
-     * @returns {number}
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     get valueCheckingMode(): number {
         return this._valueCheckingMode;
@@ -83,7 +84,7 @@ export class JsonConvert {
      * - ValueCheckingMode.ALLOW_OBJECT_NULL: objects in the JSON are allowed to be null, primitive types are not allowed to be null
      * - ValueCheckingMode.DISALLOW_NULL: no null values are tolerated in the JSON
      *
-     * @param value
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     set valueCheckingMode(value: number) {
         if (value in ValueCheckingMode) this._valueCheckingMode = value;
@@ -99,7 +100,7 @@ export class JsonConvert {
      * Determines whether primitive types should be checked.
      * If true, it will be allowed to assign primitive to other primitive types.
      *
-     * @returns {boolean}
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     get ignorePrimitiveChecks(): boolean {
         return this._ignorePrimitiveChecks;
@@ -109,7 +110,7 @@ export class JsonConvert {
      * Determines whether primitive types should be checked.
      * If true, it will be allowed to assign primitive to other primitive types.
      *
-     * @param value
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     set ignorePrimitiveChecks(value: boolean) {
         this._ignorePrimitiveChecks = value;
@@ -130,7 +131,8 @@ export class JsonConvert {
      * You may assign the following values:
      * - PropertyMatchingRule.CASE_STRICT: JSON properties need to match exactly the names in the decorators
      * - PropertyMatchingRule.CASE_INSENSITIVE: JSON properties need to match names in the decorators, but names they are not case sensitive
-     * @returns {number}
+     *
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     get propertyMatchingRule(): number {
         return this._propertyMatchingRule;
@@ -142,47 +144,42 @@ export class JsonConvert {
      * You may assign the following values:
      * - PropertyMatchingRule.CASE_STRICT: JSON properties need to match exactly the names in the decorators
      * - PropertyMatchingRule.CASE_INSENSITIVE: JSON properties need to match names in the decorators, but names they are not case sensitive
-     * @param value
+     *
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     set propertyMatchingRule(value: number) {
         if (value in PropertyMatchingRule) this._propertyMatchingRule = value;
     }
 
     /**
-     * Determines whether the check for "required" properties should be ignored, making ALL
+     * Determines whether the check for "required" properties should be ignored, making all
      * mapped values optional, whether or not the isOptional property mapping parameter is set.
      * If true, any missing properties when serializing or deserializing will be ignored, as if they
-     * were marked optional.  Defaults to false.
+     * were marked optional.
      */
-    private _ignoreRequiredCheck = false;
+    private _ignoreRequiredCheck: boolean = false;
 
     /**
-     * Determines whether the check for "required" properties should be ignored, making ALL
+     * Determines whether the check for "required" properties should be ignored, making all
      * mapped values optional, whether or not the isOptional property mapping parameter is set.
      * If true, any missing properties (undefined) when serializing or deserializing will be
-     * ignored, as if they were marked optional.  Note that properties explicitly set to null
-     * will be unaffected by this flag - they will be ignored if optional and included if not.
-     * Defaults to false.
-     * @returns {boolean} true if all mapped properties will be considered optional, even if the mapping
-     *                    doesn't explicitly specify this, false if the mapping will determine whether
-     *                    a property is optional or not (default)
+     * ignored, as if they were marked optional.
+     *
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     get ignoreRequiredCheck(): boolean {
         return this._ignoreRequiredCheck;
     }
 
     /**
-     * Determines whether the check for "required" properties should be ignored, making ALL
+     * Determines whether the check for "required" properties should be ignored, making all
      * mapped values optional, whether or not the isOptional property mapping parameter is set.
      * If true, any missing properties (undefined) when serializing or deserializing will be
-     * ignored, as if they were marked optional.  Note that properties explicitly set to null
-     * will be unaffected by this flag - they will be ignored if optional and included if not.
-     * Defaults to false.
-     * @param value true if all mapped properties will be considered optional, even if the mapping
-     *              doesn't explicitly specify this, false if the mapping will determine whether a
-     *              property is optional or not (default)
+     * ignored, as if they were marked optional.
+     *
+     * @see https://www.npmjs.com/package/json2typescript full documentation
      */
-    set ignoreRequiredCheck( value: boolean) {
+    set ignoreRequiredCheck(value: boolean) {
         this._ignoreRequiredCheck = value;
     }
 
@@ -229,7 +226,6 @@ export class JsonConvert {
      *
      * @throws an Error in case of failure
      *
-     * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
      * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     serialize<T>(data: any | any[], classReference?: { new(): T }): any | any[] {
@@ -245,9 +241,9 @@ export class JsonConvert {
             return this.serializeObject(data, classReference);
         } else {
             throw new Error(
-              "Fatal error in JsonConvert. " +
-              "Passed parameter data in JsonConvert.serialize() is not in valid format (object or array)." +
-              "\n"
+                "Fatal error in JsonConvert. " +
+                "Passed parameter data in JsonConvert.serialize() is not in valid format (object or array)." +
+                "\n"
             );
         }
     }
@@ -268,7 +264,6 @@ export class JsonConvert {
      *
      * @throws an Error in case of failure
      *
-     * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
      * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     serializeObject<T>(data: any, classReference?: { new(): T }): any {
@@ -327,8 +322,7 @@ export class JsonConvert {
         for (const propertyKey of Object.keys(instance as any)) {
             try {
                 this.serializeObject_loopProperty(data, instance, propertyKey, jsonObject);
-            }
-            catch (ex) {
+            } catch (ex) {
                 if (this.operationMode === OperationMode.LOGGING) {
                     console.log("Failed to serialize property:");
                     console.log(ex);
@@ -364,7 +358,6 @@ export class JsonConvert {
      *
      * @throws an Error in case of failure
      *
-     * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
      * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     serializeArray<T>(dataArray: any[], classReference?: { new(): T }): any[] {
@@ -414,7 +407,7 @@ export class JsonConvert {
         let jsonArray: any[] = [];
 
         // Loop through all array elements
-        for (const dataObject of <any> dataArray) {
+        for (const dataObject of <any>dataArray) {
             jsonArray.push(this.serializeObject(dataObject, classReference));
         }
 
@@ -438,7 +431,6 @@ export class JsonConvert {
      *
      * @throws an Error in case of failure
      *
-     * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
      * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     deserialize<T>(json: any, classReference: { new(): T }): T | T[] {
@@ -472,7 +464,6 @@ export class JsonConvert {
      *
      * @throws an Error in case of failure
      *
-     * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
      * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     deserializeObject<T>(jsonObject: any, classReference: { new(): T }): T {
@@ -525,8 +516,7 @@ export class JsonConvert {
         for (const propertyKey of Object.keys(instance as any)) {
             try {
                 this.deserializeObject_loopProperty(instance, propertyKey, jsonObject);
-            }
-            catch (ex) {
+            } catch (ex) {
                 if (this.operationMode === OperationMode.LOGGING) {
                     console.log("Failed to deserialize property:");
                     console.log(ex);
@@ -556,7 +546,6 @@ export class JsonConvert {
      *
      * @throws an Error in case of failure
      *
-     * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
      * @see https://www.npmjs.com/package/json2typescript full documentation
      */
     deserializeArray<T>(jsonArray: any[], classReference: { new(): T }): T[] {
@@ -719,7 +708,8 @@ export class JsonConvert {
         let jsonValue: any = undefined;
         try {
             jsonValue = this.getObjectValue(json, jsonPropertyName);
-        } catch {}
+        } catch {
+        }
 
 
         // Check if the json value exists
@@ -1024,7 +1014,7 @@ export class JsonConvert {
                 return "any";
             } else if (expectedJsonType === String || expectedJsonType === Boolean || expectedJsonType === Number) {
                 return (new expectedJsonType()).constructor.name.toLowerCase();
-            } else if (typeof expectedJsonType === 'function') {
+            } else if (typeof expectedJsonType === "function") {
                 return (new expectedJsonType()).constructor.name;
             } else if (expectedJsonType === undefined) {
                 return "undefined"

src/json2typescript/json-custom-convert.ts

@@ -5,7 +5,6 @@
  * - serialize() to map a TypeScript object to a JSON object
  * - deserialize() to map a JSON object to a TypeScript object
  *
- * @author Andreas Aeschlimann, DHlab, University of Basel, Switzerland
  * @see https://www.npmjs.com/package/json2typescript full documentation on NPM$
  */
 export interface JsonCustomConvert<T> {