docs: add description on useTypeDefaults-option

Author: sagold

README.md

@@ -539,6 +539,50 @@ console.log(data); // { valid: "stays", invalid: "removed" }
 
 </details>
 
+<details><summary>Option: useTypeDefaults (default: true)</summary>
+
+With `useTypeDefaults:true`, `getData` will return initial values for all primitives (non-objects/arrays) that do not have a default-property set:
+
+```ts
+const data = compileSchema({
+    required: ["valid"],
+    properties: { valid: { type: "string" } }
+}).getData(null, { useTypeDefaults: true });
+console.log(data); // { valid: "" }
+```
+
+Setting `useTypeDefaults:false` will _not_ remove data that is valid, but unspecified:
+
+```ts
+const data = compileSchema({
+    required: ["valid"],
+    properties: { valid: { type: "string" } }
+}).getData(null, { useTypeDefaults: false });
+console.log(data); // {}
+```
+
+_Note_ object and array-properties will still be added if required:
+
+```ts
+const data = compileSchema({
+    required: ["valid"],
+    properties: { valid: { type: "object" } }
+}).getData(null, { useTypeDefaults: true });
+console.log(data); // { valid: {} }
+```
+
+_Note_ enforced array-items will be `undefined` if required and `initialValues: false`
+
+```ts
+const data = compileSchema({
+    required: ["valid"],
+    properties: { valid: { type: "array", items: { type: "string" }, minItems: 1 } }
+}).getData(null, { useTypeDefaults: false });
+console.log(data); // { valid: [undefined] }
+```
+
+</details>
+
 ### getNode
 
 `getNode` returns the JSON Schema from data location specified by a JSON Pointer. In many cases the JSON Schema can be retrieved without passing any data, but in situations where the schema is dynamic (for example in _oneOf_, _dependencies_, etc.), input-data is required or `getNode` will return a _JsonError_ as is done when the JSON Pointer path is invalid.

src/methods/getData.test.ts

@@ -1657,6 +1657,44 @@ describe("getData", () => {
         });
     });
     describe("defaultTemplateOptions.useTypeDefaults", () => {
+        it("should return initial value for missing default-properties", () => {
+            const data = compileSchema({
+                required: ["valid"],
+                properties: { valid: { type: "string" } }
+            }).getData(null, { useTypeDefaults: true });
+
+            assert.deepEqual(data, { valid: "" });
+        });
+
+        it("should omit initial value for missing default-properties", () => {
+            const data = compileSchema({
+                required: ["valid"],
+                properties: { valid: { type: "string" } }
+            }).getData(null, { useTypeDefaults: false });
+
+            assert.deepEqual(data, {});
+        });
+
+        // @todo: reevaluate this behaviour
+        it("should return initial object-value for missing default-properties, even if useTypeDefaults: false", () => {
+            const data = compileSchema({
+                required: ["valid"],
+                properties: { valid: { type: "string" } }
+            }).getData(null, { useTypeDefaults: false });
+
+            assert.deepEqual(data, {});
+        });
+
+        // @todo: reevaluate this behaviour
+        it("should return initial array-value for missing default-properties", () => {
+            const data = compileSchema({
+                required: ["valid"],
+                properties: { valid: { type: "array", items: { type: "string" }, minItems: 1 } }
+            }).getData(null, { useTypeDefaults: false });
+
+            assert.deepEqual(data, { valid: [undefined] });
+        });
+
         it("should omit properties without default values when 'useTypeDefaults:false' even if required", () => {
             const node = compileSchema({
                 type: "object",
@@ -1668,7 +1706,8 @@ describe("getData", () => {
                 }
             });
             const res = node.getData(undefined, {
-                extendDefaults: false, useTypeDefaults: false
+                extendDefaults: false,
+                useTypeDefaults: false
             });
 
             assert.deepEqual(res, { name: "John Doe", country: "USA" });
@@ -1696,20 +1735,23 @@ describe("getData", () => {
                     active: { type: "boolean", default: true }
                 }
             });
-            const res = node.getData({}, { addOptionalProps: true, useTypeDefaults: false});
+            const res = node.getData({}, { addOptionalProps: true, useTypeDefaults: false });
 
-            assert.deepEqual(JSON.stringify(res), JSON.stringify({
-                user: {
-                    username: "guest",
-                    profile: {
-                        theme: "light"
-                    }
-                },
-                active: true
-            }));
+            assert.deepEqual(
+                JSON.stringify(res),
+                JSON.stringify({
+                    user: {
+                        username: "guest",
+                        profile: {
+                            theme: "light"
+                        }
+                    },
+                    active: true
+                })
+            );
         });
 
-       it("should handle type string with default value and 'useTypeDefaults:false'", () => {
+        it("should handle type string with default value and 'useTypeDefaults:false'", () => {
             const node = compileSchema({
                 type: "string",
                 default: "default value"
@@ -1722,9 +1764,9 @@ describe("getData", () => {
 
         it("should handle type string without default value and 'useTypeDefaults:false'", () => {
             const node = compileSchema({
-                type: "string",
+                type: "string"
             });
-            const res = node.getData(undefined, {useTypeDefaults: false});
+            const res = node.getData(undefined, { useTypeDefaults: false });
             assert.deepEqual(res, undefined);
         });
 
@@ -1733,13 +1775,13 @@ describe("getData", () => {
                 type: "object",
                 required: ["title"],
                 properties: {
-                    title: { 
+                    title: {
                         type: "array",
                         items: { type: "string" }
                     }
                 }
             });
-            const res = node.getData(undefined, {useTypeDefaults: false});
+            const res = node.getData(undefined, { useTypeDefaults: false });
             assert.deepEqual(res, { title: [] });
         });
     });