feat: add change tracking and much more (6.0.2-beta.7) (#162)

* feat: add and test change tracking
* feat: big refactor
* add isOptimistic option and remove OPTIMISTIC entity actions
* DefaultDispatcherOptions can be provided.
* refactor entityreducer into two parts
* refactoring: sweeping renaming, mostly of things called 'default...'
* refactor: EntityCollectionServiceElementsFactory
* feat: cancellation

.prettierrc

@@ -1,5 +1,5 @@
 {
-  "printWidth": 80,
+  "printWidth": 140,
   "singleQuote": true,
   "tabWidth": 2
 }

CHANGELOG.md

@@ -5,13 +5,18 @@ Please look there.
 
 **_This_** Changelog covers changes to the repository and the demo applications.
 
-<a name="0.6.1">
+<a id="0.6.1">
+# 0.6.2 (2018-06-26)
+
+* Significantly refactored for ngrx-data `6.0.2-beta.7`.
+
+<a id="0.6.1">
 # 0.6.1 (2018-05-25)
 
 * Refactored for EntityAction operators as required by Beta 6
 * Add example of extending EntityDataServices with custom `HeroDataService` as described in `entity-dataservice.md` (#151).
 
-<a name="0.6.0"></a>
+<a id="0.6.0"></a>
 
 # 0.6.0 (2018-05-08)
 
@@ -30,7 +35,7 @@ which still works.
 
 <hr>
 
-<a name="0.2.13"></a>
+<a id="0.2.13"></a>
 
 # 0.2.13 (2018-05-04)
 
@@ -46,7 +51,7 @@ The downside is that "Go to definition" takes you to the `d.ts` file rather than
 That's inconvenient. But the benefit is that the routine build process reflects what apps will experience.
 This is the approach followed by the Angular CLI's library support.
 
-<a name="0.2.12"></a>
+<a id="0.2.12"></a>
 
 # 0.2.12 (2018-03-25)
 
@@ -55,19 +60,19 @@ This is the approach followed by the Angular CLI's library support.
 * Opted not to force trailing slash because as contrary to the goal of putting dev
   in complete control of url generation. May re-evaluate that decision later.
 
-<a name="0.2.11"></a>
+<a id="0.2.11"></a>
 
 # 0.2.11 (2018-03-19)
 
 * demonstrates `HttpResourceUrls` setting in config (new in beta.2)
 
-<a name="0.2.10"></a>
+<a id="0.2.10"></a>
 
 # 0.2.10 (2018-03-15)
 
 * Update ngPackagr from -rc to v.2.2
 
-<a name="0.2.9"></a>
+<a id="0.2.9"></a>
 
 # 0.2.9 (2018-03-14)
 
@@ -77,13 +82,13 @@ This is the approach followed by the Angular CLI's library support.
 
 None of these changes should break anything or interfere with creating the library package.
 
-<a name="0.2.8"></a>
+<a id="0.2.8"></a>
 
 # 0.2.8 (2018-03-12)
 
 * Update app to align with app in ngrx-data-lab (much cleaner)
 
-<a name="0.2.7"></a>
+<a id="0.2.7"></a>
 
 # 0.2.7 (2018-03-09)
 
@@ -101,7 +106,7 @@ This `VillainEditor` also shows
 
 Depends on alpha.14
 
-<a name="0.2.6"></a>
+<a id="0.2.6"></a>
 
 # 0.2.6 (2018-03-05)
 
@@ -121,27 +126,27 @@ Sample revised
 * Those components now start with the cached version of the `getAll()` results.
   Press refresh or toggle the datasource to trigger a new `getAll()`
 
-<a name="0.2.5"></a>
+<a id="0.2.5"></a>
 
 # 0.2.5 (2018-03-05)
 
 Add HeroesComponent tests to illustrate how one might write test components. Experimental.
 
 Requires Alpha.11
 
-<a name="0.2.4"></a>
+<a id="0.2.4"></a>
 
 # 0.2.4 (2018-02-26)
 
 App refactors based on learnings from our Angular Awesome workshop.
 
-<a name="0.2.3"></a>
+<a id="0.2.3"></a>
 
 # 0.2.3 (2018-02-24)
 
 Adapt to alpha.10
 
-<a name="0.2.2"></a>
+<a id="0.2.2"></a>
 
 # 0.2.2 (2018-02-23)
 
@@ -151,7 +156,7 @@ Revises the demo app and updates the docs to conform to alpha.9
 * Updates the `EntityMetadata`
 * Adds `HeroesV1Component` to illustrate using `EntityCollectionServiceFactory` directly w/o `HeroService`.
 
-<a name="0.2.1"></a>
+<a id="0.2.1"></a>
 
 # 0.2.1 (2018-02-19)
 
@@ -171,7 +176,7 @@ Revises the demo app and updates the docs to conform to alpha.9
 
   Should not affect the builds of the _ngrx-data lib packages_!
 
-<a name="0.2.0"></a>
+<a id="0.2.0"></a>
 
 # 0.2.0 (2018-02-13)
 
@@ -185,7 +190,7 @@ you must upgrade _ngrx_ to v5.1 or later,
 because the reducer uses the "upsert" feature, new in `@ngrx/entity` v5.1,
 for `QUERY_ONE_SUCCESS` and `QUERY_MANY_SUCCESS`.
 
-<a name="0.1.0"></a>
+<a id="0.1.0"></a>
 
 # 0.1.0 (2018-02-04)
 

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to angular-ngrx-data
 
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
 the rights to use your contribution. For details, visit https://cla.microsoft.com.
 
@@ -12,34 +12,38 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
- - [Code of Conduct](#coc)
- - [Issues and Bugs](#issue)
- - [Feature Requests](#feature)
- - [Submission Guidelines](#submit)
+* [Code of Conduct](#coc)
+* [Issues and Bugs](#issue)
+* [Feature Requests](#feature)
+* [Submission Guidelines](#submit)
+
+## <a id="coc"></a> Code of Conduct
 
-## <a name="coc"></a> Code of Conduct
 Help us keep this project open and inclusive. Please read and follow our [Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
 
-## <a name="issue"></a> Found an Issue?
+## <a id="issue"></a> Found an Issue?
+
 If you find a bug in the source code or a mistake in the documentation, you can help us by
 [submitting an issue](#submit-issue) to the GitHub Repository. Even better, you can
 [submit a Pull Request](#submit-pr) with a fix.
 
-## <a name="feature"></a> Want a Feature?
-You can *request* a new feature by [submitting an issue](#submit-issue) to the GitHub
-Repository. If you would like to *implement* a new feature, please submit an issue with
+## <a id="feature"></a> Want a Feature?
+
+You can _request_ a new feature by [submitting an issue](#submit-issue) to the GitHub
+Repository. If you would like to _implement_ a new feature, please submit an issue with
 a proposal for your work first, to be sure that we can use it.
 
 * **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr).
 
-## <a name="submit"></a> Submission Guidelines
+## <a id="submit"></a> Submission Guidelines
+
+### <a id="submit-issue"></a> Submitting an Issue
 
-### <a name="submit-issue"></a> Submitting an Issue
 Before you submit an issue, search the archive, maybe your question was already answered.
 
 If your issue appears to be a bug, and hasn't been reported, open a new issue.
 Help us to maximize the effort we can spend fixing issues and adding new
-features, by not reporting duplicate issues.  Providing the following information will increase the
+features, by not reporting duplicate issues. Providing the following information will increase the
 chances of your issue being dealt with quickly:
 
 * **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps
@@ -53,7 +57,8 @@ chances of your issue being dealt with quickly:
 
 You can file new issues by providing the above information at the corresponding repository's issues link: https://github.com/[organization-name]/[repository-name]/issues/new].
 
-### <a name="submit-pr"></a> Submitting a Pull Request (PR)
+### <a id="submit-pr"></a> Submitting a Pull Request (PR)
+
 Before you submit your Pull Request (PR) consider the following guidelines:
 
 * Search the repository (https://github.com/[organization-name]/[repository-name]/pulls) for an open or closed PR
@@ -65,6 +70,7 @@ Before you submit your Pull Request (PR) consider the following guidelines:
 * Push your fork to GitHub:
 * In GitHub, create a pull request
 * If we suggest changes then:
+
   * Make the required updates.
   * Rebase your fork and force push to your GitHub repository (this will update your Pull Request):
 

docs/entity-actions.md

@@ -20,17 +20,19 @@ export interface EntityAction<P = any> extends Action {
   readonly entityName: string;
   readonly op: EntityOp;
   readonly payload?: P;
-  readonly label?: string;
+  readonly tag?: string;
   error?: Error;
+  skip?: boolean
 }
 ```
 
-* `type` - action name, typically generated from the `label` and the `op`
+* `type` - action name, typically generated from the `tag` and the `op`
 * `entityName` - the name of the entity type
 * `op` - the name of an entity operation
 * `payload?` - the message data for the action.
-* `label?` - the label to use within the generated type. If not specified, the `entityName` is the label.
+* `tag?` - the tag to use within the generated type. If not specified, the `entityName` is the tag.
 * `error?` - an unexpected action processing error.
+* `skip?` - true if downstream consumers should skip processing the action.
 
 The `type` is the only property required by _ngrx_. It is a string that uniquely identifies the action among the set of all the types of actions that can be dispatched to the store.
 
@@ -48,13 +50,17 @@ that the _ngrx-data_ library can perform.
 The `payload` is conceptually the body of the message.
 Its type and content should fit the requirements of the operation to be performed.
 
-The optional `label` appears in the generated `type` text when the `EntityActionFactory` creates this `EntityAction`.
+The optional `tag` appears in the generated `type` text when the `EntityActionFactory` creates this `EntityAction`.
 
-The `entityName` is the default label that appears between brackets in the formatted `type`,
+The `entityName` is the default tag that appears between brackets in the formatted `type`,
 e.g., `'[Hero] ngrx-data/query-all'`.
 
 The `error` property indicates that something went wrong while processing the action. [See more below](#action-error).
 
+The `skip` property tells downstream action receivers that they should skip the usual action processing.
+This flag is usually missing and is implicitly false.
+[See more below](#action-skip).
+
 ## _EntityAction_ consumers
 
 The _ngrx-data_ library ignores the `Action.type`.
@@ -72,7 +78,7 @@ You can create an `EntityAction` by hand if you wish.
 The _ngrx-data_ library considers _any action_ with an `entityName` and `op` properties to be an `EntityAction`.
 
 The `EntityActionFactory.create()` method helps you create a consistently well-formed `EntityAction` instance
-whose `type` is a string composed from the `label` (the `entityName` by default) and the `op`.
+whose `type` is a string composed from the `tag` (the `entityName` by default) and the `op`.
 
 For example, the default generated `Action.type` for the operation that queries the server for all heroes is `'[Hero] ngrx-data/query-all'`.
 
@@ -84,7 +90,7 @@ For example, the default generated `Action.type` for the operation that queries
 
 Note that **_each entity type has its own \_unique_ `Action` for each operation\_**, as if you had created them individually by hand.
 
-## Labeling the EntityAction
+## Tagging the EntityAction
 
 A well-formed action `type` can tell the reader what changed and
 who changed it.
@@ -95,10 +101,10 @@ So you can get the same behavior from several different actions,
 each with its own informative `type`, as long as they share the same
 `entityName` and `entityOp`.
 
-The optional `label` parameter of the `EntityActionFactory.create()` method makes
+The optional `tag` parameter of the `EntityActionFactory.create()` method makes
 it easy to produce meaningful _EntityActions_.
 
-You don't have to specify a label. The `entityName` is the default label that appears between brackets in the formatted `type`,
+You don't have to specify a tag. The `entityName` is the default tag that appears between brackets in the formatted `type`,
 e.g., `'[Hero] ngrx-data/query-all'`.
 
 Here's an example that uses the injectable `EntityActionFactory` to construct the default "query all heroes" action.
@@ -118,11 +124,11 @@ Thanks to the _ngrx-data **effects**_, this produces _two_ actions in the log, t
 [Hero] ngrx-data/query-all-success
 ```
 
-This default `entityName` label identifies the action's target entity collection.
+This default `entityName` tag identifies the action's target entity collection.
 But you can't understand the _context_ of the action from these log entries. You don't know who dispatched the action or why.
 The action `type` is too generic.
 
-You can create a more informative action by providing a label that
+You can create a more informative action by providing a tag that
 better describes what is happening and also make it easier to find
 where that action is dispatched by your code.
 
@@ -164,7 +170,7 @@ store.dispatch(action);
 It triggers the HTTP request via _ngrx-data effects_, as in the previous examples.
 
 Just be aware that _ngrx-data effects_ uses the `EntityActionFactory` to create the second, success Action.
-Without the `label` property, it produces a generic success action.
+Without the `tag` property, it produces a generic success action.
 
 The log of the two action types will look like this:
 
@@ -209,7 +215,7 @@ That's a lot of code to write, test, and maintain.
 With the help of _ngrx-data_, you don't write any of it.
 _Ngrx-data_ creates the _actions_ and the _dispatchers_, _reducers_, and _effects_ that respond to those actions.
 
-<a name="action-error"></a>
+<a id="action-error"></a>
 
 ## _EntityAction.error_
 
@@ -229,7 +235,25 @@ The `EntityEffects` will see that such an action has an error and will return th
 
 > This is the only way we've found to prevent a bad action from getting through the effect and triggering an HTTP request.
 
-<a name="entity-cache-actions"></a>
+<a id="action-skip"></a>
+
+## _EntityAction.skip_
+
+The `skip` property tells downstream action receivers that they should skip the usual action processing.
+This flag is usually missing and is implicitly false.
+
+The ngrx-data sets `skip=true` when you try to delete a new entity that has not been saved.
+When the `EntityEffects.persist$` method sees this flag set true on the `EntityAction` envelope,
+it skips the HTTP request and dispatches an appropriate `_SUCCESS` action with the
+original request payload.
+
+This feature allows ngrx-data to avoid making a DELETE request when you try to delete an entity
+that has been added to the collection but not saved.
+Such a request would have failed on the server because there is no such entity to delete.
+
+See the [`EntityChangeTracker`](entity-change-tracker.md) page for more about change tracking.
+
+<a id="entity-cache-actions"></a>
 
 ## EntityCache-level actions