Merge branch 'develop'

Author: michaelkrone

CHANGELOG.md

@@ -1,5 +1,8 @@
+* _2.2.0_
+  * Support for adding and removing child data. Adding `AddChildData` and `RemoveChildData` actions and `addChildData` and `removeChildData` action creators.
+
 * _2.1.0_
-  entitiesProjector takes an optional array of id strings ([@juanpmarin](https://github.com/juanpmarin)) Closes #18
+  * entitiesProjector takes an optional array of id strings ([@juanpmarin](https://github.com/juanpmarin)) Closes #18
 
 * _2.0.0_
   * Serialization support for actions. _Details:_  The normalization of entities is now perfomed in the action constructor. Previously it was handled by the reducer. As ([@PachowStudios](https://github.com/PachowStudios)) pointed out in Issue #16, ngrx-normalizr actions were not serializable. This could raise issues with other redux/ngrx libraries. The normalizr `schema.Entity` is not part of the action payload anymore, hence the interfaces for describing the payload have changed and the action constructor does no longer take the payload itself as an argument. As long as you did not type any action parameters in your code or dispatched actions directly with a simle pojo by using the exported action type names, you should have no problem updating, since the arity/keys of the constructor API did not change - see Breaking Changes. Closes #16

README.md

@@ -5,11 +5,12 @@
 
 > Managing [normalized state](https://redux.js.org/docs/recipes/reducers/NormalizingStateShape.html) in [ngrx](https://github.com/ngrx/platform) applications, transparently.
 
-
 This package provides a set of actions, reducers and selectors for handling normalization and denormalization of state data **transparently**.
 *ngrx-normalizr* uses [normalizr](https://github.com/paularmstrong/normalizr) for [normalizing](https://github.com/paularmstrong/normalizr/blob/master/docs/api.md#normalizedata-schema) and [denormalizing](https://github.com/paularmstrong/normalizr/blob/master/docs/api.md#denormalizeinput-schema-entities) data. All normalization and denormalization
 is defined by the use of [normalizr schemas](https://github.com/paularmstrong/normalizr/blob/master/docs/api.md#schema), since that's the way normalizr works. This enables selectors to use a transparent and powerful projection of state data.
 
+> Releases will be published from the [`master`](https://github.com/michaelkrone/ngrx-normalizr/tree/master) branch. [Go there](https://github.com/michaelkrone/ngrx-normalizr/tree/master) for documentation that aligns with the npm repo version.
+
 ## Installation
 To install this package:
 ```sh
@@ -81,7 +82,7 @@ Actions are used to set data in - and remove data from - the normalized store.
 
 ### Adding data
 To add data and automatically normalize it, *ngrx-normalizr* provides a `AddData` action. This action takes an object with `data` and `schema` as an argument. Entities are identified by their id attribute set in the passed schema.
-Existing entities will be overwritten by updated data, new entities will be added to the store.
+Existing entities will be overwritten by updated data, new entities will be added to the store. For adding related childs, an `AddChildData` action is provided.
 
 ###### Using `AddData` in an effect
 ```javascript
@@ -98,6 +99,29 @@ loadEffect$ = this.actions$
   .catch(err => Observable.of(new LoadFail(err)));
 ```
 
+#### Adding child data
+Adding a related child data to a parent entity can be done with the `AddChildData` action. Note that for this to work, the relation has to be defined in the schema. The action takes a couple of arguments which need to be given in an object:
+
+* `data`: Array of child entities to add
+* `childSchema`The `schema.Entity` of the child entity
+* `parentSchema`: The `schema.Entity` of the parent entity
+* `parentId`: The id of the entity to add child references to
+
+###### Using `AddChildData` in an effect
+```javascript
+@Effect()
+addPetEffect$ = this.actions$
+  .ofType(ADD_PET)
+  .switchMap(action => this.http.post('https://example.com/api/pets'))
+  .mergeMap((data: Pet[]) => [
+    // dispatch to add data to the store
+    new AddChildData<Pet>({ data, childSchema, parentSchema, parentId }),
+    // dispatch to inform feature reducer
+    new AddPetSuccess(data)
+  ])
+  .catch(err => Observable.of(new LoadFail(err)));
+```
+
 ### Setting data
 The `SetData` action will overwrite all entities for a given schema with the normalized entities of the `data` property of the action constructor argument. This action can
 be used for resetting entity state data instead of adding and updating existing entities.
@@ -120,12 +144,36 @@ removeEffect$ = this.actions$
   ])
   .catch(err => Observable.of(new RemoveFail(err)));
 ```
+#### Removing child data
+Removing a child entity which is 1:1 related to a parent entity can be done with the `RemoveChildData` action. Note that for this to work, the relation has to be defined in the schema. The action takes a couple of arguments which need to be given in an object:
+
+* `id`: Id of the child entity that should be removed
+* `childSchema`The `schema.Entity` of the child entity
+* `parentSchema`: The `schema.Entity` of the parent entity
+* `parentId`: The id of the entity to remove child references from
+
+###### Using `AddChildData` in an effect
+```javascript
+@Effect()
+removePetEffect$ = this.actions$
+  .ofType(REMOVE_PET)
+  .switchMap(action => this.http.remove(`https://example.com/api/pets/${action.payload.id}`))
+  .mergeMap((data: Pet) => [
+    // dispatch to add data to the store
+    new RemoveChildData({ id: data.id, childSchema, parentSchema, parentId }),
+    // dispatch to inform feature reducer
+    new RemovePetSuccess(data)
+  ])
+  .catch(err => Observable.of(new LoadFail(err)));
+```
 
 ### Action creators
 For convenience, *ngrx-normalizr* provides an `actionCreators` function which will return an object with following schema bound action creators:
 * `setData` - `(data: T[]) => SetData<T>`
 * `addData` - `(data: T[]) => AddData<T>`
+* `addChildData<C>` - `(data: C[], childSchema: schema.Entity, parentId: string) => AddChildData`
 * `removeData` - `(id: string, removeChildren?: SchemaMap) => RemoveData`
+* `removeChildData` - `(id: string, childSchema: schema.Entity, parentId: string) => RemoveChildData`
 
 Action creators could be exported along whith other feature actions:
 ```javascript
@@ -173,7 +221,7 @@ const schemaSelectors = createSchemaSelectors<User>(userSchema);
 `createSchemaSelectors` will return schema bound selectors (instance of `SchemaSelectors`):
 * `getEntities` - ` MemoizedSelector<{}, T[]>` Returns all denormalized entities for the schema
 * `getNormalizedEntities` - `MemoizedSelector<any, EntityMap>` Returns all normalized (raw) state entities of every schema (the whole entities state)
-* `entitiesProjector` - `(entities: {}, ids?: Array<string>) => T[]` Projector function for denormalizing a the set of normalized entities to an denormalized entity array
+* `entitiesProjector` - `(entities: {}, ids?: Array<string>) => T[]` Projector function for denormalizing a the set of normalized entities to an denormalized entity array. If no `ids` are given, all entities will be denormalized.
 * `entityProjector` - `(entities: {}, id: string) => T` Projector function for denormalizing a single normalized entity with the given id
 
 You might create several selectors with several schemas, i.e. a *listView* schema, which only denormalizes the data used in the list