Merge pull request #1460 from jjspace/setOne-setMany-docs

Docs: add `setOne` and `setMany`, describe `add` vs `set` vs `upsert`

Author: markerikson

docs/api/createEntityAdapter.mdx

@@ -203,9 +203,11 @@ export interface EntityAdapter<T> extends EntityStateAdapter<T> {
 
 The primary content of an entity adapter is a set of generated reducer functions for adding, updating, and removing entity instances from an entity state object:
 
-- `addOne`: accepts a single entity, and adds it.
-- `addMany`: accepts an array of entities or an object in the shape of `Record<EntityId, T>`, and adds them.
-- `setAll`: accepts an array of entities or an object in the shape of `Record<EntityId, T>`, and replaces the existing entity contents with the values in the array.
+- `addOne`: accepts a single entity, and adds it if it's not already present.
+- `addMany`: accepts an array of entities or an object in the shape of `Record<EntityId, T>`, and adds them if not already present.
+- `setOne`: accepts a single entity and adds or replaces it
+- `setMany`: accepts an array of entities or an an object in the shape of `Record<EntityId, T>`, and adds or replaces them.
+- `setAll`: accepts an array of entities or an object in the shape of `Record<EntityId, T>`, and replaces all existing entities with the values in the array.
 - `removeOne`: accepts a single entity ID value, and removes the entity with that ID if it exists.
 - `removeMany`: accepts an array of entity ID values, and removes each entity with those IDs if they exist.
 - `removeAll`: removes all entities from the entity state object.
@@ -214,6 +216,17 @@ The primary content of an entity adapter is a set of generated reducer functions
 - `upsertOne`: accepts a single entity. If an entity with that ID exists, it will perform a shallow update and the specified fields will be merged into the existing entity, with any matching fields overwriting the existing values. If the entity does not exist, it will be added.
 - `upsertMany`: accepts an array of entities or an object in the shape of `Record<EntityId, T>` that will be shallowly upserted.
 
+:::info Should I add, set or upsert my entity?
+
+All three options will insert _new_ entities into the list. However they differ in how they handle entities that already exist. If an entity **already exists**:
+
+- `addOne` and `addMany` will do nothing with the new entity
+- `setOne` and `setMany` will completely replace the old entity with the new one. This will also get rid of any properties on the entity that are not present in the new version of said entity.
+- `upsertOne` and `upsertMany` will do a shallow copy to merge the old and new entities overwritng existing values, adding any that were not there and not touching properties not provided in the new entity.
+
+:::
+
+
 Each method has a signature that looks like:
 
 ```ts no-transpile