Updated documentation, updated texts

Author: andreas-aeschlimann

README.md

@@ -1,6 +1,6 @@
 # json2typescript
 
-In Angular 2 applications, everyone consumes JSON API's from an external source. 
+In Angular applications, everyone consumes JSON API's from an external source. 
 Type checking and object mapping is only possible in TypeScript, but not in the JavaScript runtime.
 As the API may change at any point, it is important for larger projects to verify the consumed data.
 
@@ -21,15 +21,17 @@ let user: User = jsonConvert.deserializeObject(jsonObj, User);
 console.log(user); // prints User{ ... } in JavaScript runtime, not Object{ ... }
 ```
 
-> Tip: All `serialize()` and `deserialize()` methods may throw an exception in case of failure. Make sure you catch the errors in production!
+> Tip: All `serialize()` and `deserialize()` methods may throw an exception in case of failure. 
+Make sure you catch the errors in production!
 
 ---
 
 # Changelog
 
 See the changelog in the seperate file for bug fixes, new features and breaking changes: [Changelog](CHANGELOG.md)
 
-> Tip: Starting from version 1.0.6, we recommend to use unique class identifiers in the `@JsonObject` decorator. Read below how to use the decorators properly.
+> Tip: Starting from version 1.0.6, we recommend to use unique class identifiers in the `@JsonObject` decorator. 
+Read below how to use the decorators properly.
 
 > Tip: Version 1.0.0 has several breaking changes. When upgrading from `json2typescript` < 1.0.0, please make sure you fix these issues.
 
@@ -39,11 +41,13 @@ See the changelog in the seperate file for bug fixes, new features and breaking
 
 ## Requirements
 
-We developed **json2typescript** for Angular 2+. In this document, we only cover this use case. However, you may use our package for pure TypeScript or even JavaScript applications.
+We developed **json2typescript** for Angular and Ionic 2+. In this document, we only cover this use case. 
+However, you may use our package for pure TypeScript or even JavaScript applications.
 
 ## Setup a Test Application
 
-We recommend to use the official **angular-cli** tool in order to set up a new Angular project. Then, all you need to do is type the following into your operating system's terminal:
+We recommend to use the official **angular cli** tool in order to set up a new Angular project. 
+Then, all you need to do is type the following into your operating system's terminal:
 
 ```sh
 ng new testApplication
@@ -52,7 +56,8 @@ cd testApplication
 npm install json2typescript
 ```
 
-Our package makes use of TypeScript decorators. Please activate them in your **tsconfig.json** under `compilerOptions` as follows:
+Our package makes use of TypeScript decorators. 
+If not done already, please activate them in your **tsconfig.json** under `compilerOptions` as follows:
 
 ```json
 {
@@ -64,11 +69,15 @@ Our package makes use of TypeScript decorators. Please activate them in your **t
 }
 ```
 
+> Tip: We have tried to make the compiler options of `json2typescript` to be as strict as possible. 
+This enables you to use compiler options such as `"strictNullChecks": true` or `"noImplicitAny": true` in your own project.
+
 Now you are ready to use the package.
 
 ## Mapping example
 
-In order to use the **json2typescript** package, all you need to do is write decorators and import the package. The following things need to be done if you would like to map JSON to existing classes:
+In order to use the **json2typescript** package, all you need to do is write decorators and import the package. 
+The following things need to be done if you would like to map JSON to existing classes:
 
 * Classes need to be preceeded by `@JsonObject(classIdentifier)`
 * Properties need to be preceeded by `@JsonProperty(jsonProperty, conversionOption, isOptional)`
@@ -209,7 +218,8 @@ Play around with the JSON to provocate exceptions when deserializing the object.
 
 ## Important notes
 
-Avoid circular depencencies on the classes that use `json2typescript`. Even if you don't have any errors in your IDE, `json2typescript` will not properly work in this case.
+Avoid circular depencencies on the classes that use `json2typescript`. 
+Even if you don't have any errors in your IDE, `json2typescript` will not properly work in this case.
 
 ---
 
@@ -235,7 +245,6 @@ objects as above.
 
 > Tip: Make sure you import `JsonObject` from `json2typescript`.  
 
-
 ```typescript
     @JsonProperty("jsonPropName", String, true)
     @JsonProperty("jsonPropertyName", String, true)
@@ -448,6 +457,17 @@ If true, it will be allowed to assign primitive to other primitive types.
 
 The default is `false`.
 
+#### Property matching rule
+
+`(number) JsonConvert.propertyMatchingRule`
+
+Determines the rule of how JSON properties shall be matched with class properties during deserialization.
+You may assign the following two 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
+
+The default is `PropertyMatchingRule.CASE_STRICT`.
+
 ### Public methods
 
 `json2typescript` allows you to map JSON objects (or arrays) to TypeScript objects (or arrays) and vice versa.

src/json2typescript/json-convert-decorators.ts

@@ -70,7 +70,7 @@ export function JsonObject(target?: string | any): any {
 
             throw new Error(
                 "Fatal error in JsonConvert. " +
-                "It's mandatory to pass a string as parameter in the @JsonObject decorator.\n\n" +
+                "It is mandatory to pass a string as parameter in the @JsonObject decorator.\n\n" +
                 "Use either @JsonObject or @JsonObject(classId) where classId is a string.\n\n"
             );
 
@@ -111,7 +111,7 @@ export function JsonProperty(...params: any[]): any {
             case 1:
                 if (params[0] === undefined) throw new Error(
                     "Fatal error in JsonConvert. " +
-                    "It's not allowed to explicitly pass \"undefined\" as first parameter in the @JsonProperty decorator.\n\n" +
+                    "It is not allowed to explicitly pass \"undefined\" as first parameter in the @JsonProperty decorator.\n\n" +
                     "\tClass property: \n" +
                     "\t\t" + classPropertyName + "\n\n" +
                     "Leave the decorator parameters empty if you do not wish to pass the first parameter.\n\n"
@@ -121,14 +121,14 @@ export function JsonProperty(...params: any[]): any {
             case 2:
                 if (params[0] === undefined) throw new Error(
                     "Fatal error in JsonConvert. " +
-                    "It's not allowed to explicitly pass \"undefined\" as first parameter in the @JsonProperty decorator.\n\n" +
+                    "It is not allowed to explicitly pass \"undefined\" as first parameter in the @JsonProperty decorator.\n\n" +
                     "\tClass property: \n" +
                     "\t\t" + classPropertyName + "\n\n" +
                     "Leave the decorator parameters empty if you do not wish to pass the first parameter.\n\n"
                 );
                 if (params[1] === undefined) throw new Error(
                     "Fatal error in JsonConvert. " +
-                    "It's not allowed to explicitly pass \"undefined\" as second parameter in the @JsonProperty decorator.\n\n" +
+                    "It is not allowed to explicitly pass \"undefined\" as second parameter in the @JsonProperty decorator.\n\n" +
                     "\tClass property: \n" +
                     "\t\t" + classPropertyName + "\n\n" +
                     "Use \"Any\" to allow any type. You can import this class from \"json2typescript\".\n\n"
@@ -139,14 +139,14 @@ export function JsonProperty(...params: any[]): any {
             case 3:
                 if (params[0] === undefined) throw new Error(
                     "Fatal error in JsonConvert. " +
-                    "It's not allowed to explicitly pass \"undefined\" as first parameter in the @JsonProperty decorator.\n\n" +
+                    "It is not allowed to explicitly pass \"undefined\" as first parameter in the @JsonProperty decorator.\n\n" +
                     "\tClass property: \n" +
                     "\t\t" + classPropertyName + "\n\n" +
                     "Leave the decorator parameters empty if you do not wish to pass the first parameter.\n\n"
                 );
                 if (params[1] === undefined) throw new Error(
                     "Fatal error in JsonConvert. " +
-                    "It's not allowed to explicitly pass \"undefined\" as second parameter in the @JsonProperty decorator.\n\n" +
+                    "It is not allowed to explicitly pass \"undefined\" as second parameter in the @JsonProperty decorator.\n\n" +
                     "\tClass property: \n" +
                     "\t\t" + classPropertyName + "\n\n" +
                     "Use \"Any\" to allow any type. You can import this class from \"json2typescript\".\n\n"

src/json2typescript/json-convert.ts

@@ -119,29 +119,29 @@ export class JsonConvert {
      * Determines the rule of how JSON properties shall be matched with class properties during deserialization.
      *
      * You may assign the following values:
-     * - 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
+     * - 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
      */
     private _propertyMatchingRule: number = PropertyMatchingRule.CASE_STRICT;
 
     /**
      * Determines the rule of how JSON properties shall be matched with class properties during deserialization.
      *
      * You may assign the following values:
-     * - 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
+     * - 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}
      */
     get propertyMatchingRule(): number {
         return this._propertyMatchingRule;
     }
 
     /**
-     *  Determines the rule of how JSON properties shall be matched with class properties during deserialization.
+     * Determines the rule of how JSON properties shall be matched with class properties during deserialization.
      *
      * You may assign the following values:
-     * - 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
+     * - 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
      */
     set propertyMatchingRule(value: number) {