docu: update changelog and add user guide entry about form state type…

… inference

CHANGELOG.md

@@ -24,15 +24,16 @@ This release requires TypeScript >=2.8.0 for the conditional type support.
 
 #### Features
 
-* use conditional types to infer the type of child controls
+* use conditional types to infer the type of child controls (see the [documentation](docs/FORM_STATE_TYPE_INFERENCE.md) for more details)
+* add `formStateReducer` function, a reducer which can reduce any kind of form state and is correctly typed due to conditional type inference ([48eaaeb](https://github.com/MrWolfZ/ngrx-forms/commit/48eaaeb))
 * rework `updateArray` to support different parameter combinations for update functions (i.e. single function, array of functions, and rest parameters) ([f82abf8](https://github.com/MrWolfZ/ngrx-forms/commit/f82abf8))
 * rework `updateGroup` to support different parameter combinations for update function objects (i.e. single object, array of objects, and rest parameters) which reduces the probability of false type inference results ([0bb1ca7](https://github.com/MrWolfZ/ngrx-forms/commit/0bb1ca7))
 * rework `updateRecursive` to support different parameter combinations for update function objects (i.e. single object, array of objects, and rest parameters) ([96121c3](https://github.com/MrWolfZ/ngrx-forms/commit/96121c3))
 * add `updateArrayWithFilter` update function which works the same as `updateArray` except that it also takes a filter function that is applied to each array element to determine whether the update function should be applied ([0b66a6f](https://github.com/MrWolfZ/ngrx-forms/commit/0b66a6f))
 * add `notEqualTo` validation function ([851a1ed](https://github.com/MrWolfZ/ngrx-forms/commit/851a1ed))
 * enhance all form state reducers to match type signature for `ActionReducer` (they will still throw an error if the state is `undefined`) ([f3b5fea](https://github.com/MrWolfZ/ngrx-forms/commit/f3b5fea))
 * add support for `undefined` values for all validation functions ([6cce8d0](https://github.com/MrWolfZ/ngrx-forms/commit/6cce8d0), thanks @romankhrystynych for his contribution in [#65](https://github.com/MrWolfZ/ngrx-forms/pull/65)), closes [#64](https://github.com/MrWolfZ/ngrx-forms/issues/64)
-* improve typing of `errors` property on form states by using module augmentation inside of validation module to add well defined error properties to `ValidationErrors` interface
+* improve typing of `errors` property on form states by using module augmentation inside of validation module to add well defined error properties to `ValidationErrors` interface ([e202e65](https://github.com/MrWolfZ/ngrx-forms/commit/e202e65))
 
 #### Bugfixes
 

docs/FORM_STATE_TYPE_INFERENCE.md

@@ -0,0 +1,15 @@
+## Form State Type Inference
+
+TypeScript 2.8 introduced a feature called [conditional types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html). Since ngrx-forms uses the value type of a form state to determine the kind of the state this allows us to properly type states depending on the value type parameter instead of having to explicitly specify the kind of state. This is especially useful for nested form states (i.e. groups and arrays). Conceptually it works like this pseudo code:
+
+```typescript
+export type FormState<TValue> =
+  (TValue is primitive type) ? FormControlState<TValue>
+  : (TValue is array type) ? FormArrayState<TValue>
+  : (TValue is object type) ? FormGroupState<TValue>
+  : never;
+```
+
+There is also a corresponding `formStateReducer` function that can reduce any kind of form state.
+
+It is therefore possible to only use `FormState` in your code without ever specifying the concrete type of the state. However, it may be better for readability of your code to specify the concrete type where it is known and only use `FormState` where it is unknown.

docs/USER_GUIDE.md

@@ -13,6 +13,7 @@ The following sections will explain and showcase the different features of `ngrx
   * [Dynamic Form Groups](FORM_GROUPS.md#dynamic-form-groups)
 * [Form Arrays](FORM_ARRAYS.md)
   * [Dynamic Form Arrays](FORM_ARRAYS.md#dynamic-form-arrays)
+* [Form State Type Inferece](FORM_STATE_TYPE_INFERENCE.md)
 * [Updating the State](UPDATING_THE_STATE.md)
   * [`updateArray`](UPDATING_THE_STATE.md#updatearray)
   * [`updateGroup`](UPDATING_THE_STATE.md#updategroup)