EntityAdapter.upsert vs Custom Reducer for Nested State Merging

Question

State Preservation in Entity State Management
When managing complex entities with NgRx EntityAdapter, there is a requirement to update specific properties of an entity without losing existing nested collections or optional fields not present in the update payload.
The documented upsertOne and upsertMany methods replace the existing entity by ID. If the dispatched payload contains only a subset of the entity's properties, the remaining fields in the existing state are discarded rather than merged.
This creates a trade-off between using the built-in adapter methods for brevity and implementing a custom reducer to handle deep merging of entity properties to prevent partial state loss.
Technical Constraints

Requirement to maintain immutable state updates.
Need to preserve nested arrays or objects during partial updates.
Assumption of NgRx 15+ environment.

Should the state merge logic be handled via a custom reducer wrapping the adapter, or is there a documented configuration for EntityAdapter to perform a shallow merge during upsert operations?

Tasadduq Burney · Answer

EntityAdapter.upsert vs Custom Reducer for Nested State Merging
In NgRx 15+, EntityAdapter.upsertOne and upsertMany replace the entire entity object keyed by ID. Any properties omitted from the dispatched payload—including nested arrays or optional fields—are discarded. The adapter does not expose a configuration option for shallow or deep merging during upsert operations.
The update method can preserve unchanged top-level fields by spreading the existing entity with the payload: state.entities[id] = { ...state.entities[id], ...payload }. This works when only leaf-level properties need updating and nested collections under those leaves are either immutable or replaced entirely.
When nested structures must survive a partial update, a custom reducer that performs a pure deep merge is required. The reducer must return a new state object without mutating the existing entity; mutable operations break NgRx change detection. A typical pattern combines createEntityAdapter with a reducer that merges payload depth-first, preserving arrays and objects not present in the payload.

If the update affects only top-level properties and nested collections are either replaced or stored elsewhere, use adapter.update with spread logic.
  If nested arrays or objects under the same key must be preserved, implement a custom reducer that deep-merges the payload into the existing entity state.
  Verify the operation with a unit test that dispatches a partial payload and asserts unchanged nested fields remain intact.

Diagnostic question: Does the update need to preserve nested collections (arrays/objects) under keys not present in the payload, or only top-level property overrides? This determines whether adapter.update suffices or a custom deep-reducer is required.

EntityAdapter.upsert vs Custom Reducer for Nested State Merging

State Preservation in Entity State Management

Technical Constraints

1 answer

EntityAdapter.upsert vs Custom Reducer for Nested State Merging

Your perspective belongs here.

0 question comments