Redux Entity Adapter

Normalize entity collections with createEntityAdapter for O(1) lookups and pre-built CRUD reducers

When to Use

• Managing a collection of items with unique IDs (users, products, messages)
• Needing O(1) lookup by ID instead of array scanning
• Wanting pre-built

  addOne

  ,

  updateOne

  ,

  removeOne

  reducers without writing them manually
• Keeping collections sorted without re-sorting on every render

Instructions

1. Create the adapter with

   createEntityAdapter<Entity>()

   . Provide

   selectId

   if the ID field is not

   id

   , and

   sortComparer

   if the collection should be kept sorted.
2. Use

   adapter.getInitialState()

   to generate the initial

   { ids: [], entities: {} }

   shape. Pass additional state fields as an argument.
3. Use adapter CRUD methods directly as case reducers in

   createSlice

   , or call them inside reducer functions.
4. Use

   adapter.getSelectors()

   to generate

   selectAll

   ,

   selectById

   ,

   selectIds

   ,

   selectEntities

   , and

   selectTotal

   .
5. Prefer

   upsertMany

   for bulk operations (API responses) — it adds new entities and updates existing ones.

// features/users/users.slice.ts
import { createSlice, createEntityAdapter, PayloadAction } from '@reduxjs/toolkit';
import { RootState } from '../../store';
import { fetchUsers } from './users.thunks';

interface User {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'member';
}

const usersAdapter = createEntityAdapter<User>({
  sortComparer: (a, b) => a.name.localeCompare(b.name),
});

interface UsersExtraState {
  status: 'idle' | 'loading' | 'succeeded' | 'failed';
  error: string | null;
}

const initialState = usersAdapter.getInitialState<UsersExtraState>({
  status: 'idle',
  error: null,
});

const usersSlice = createSlice({
  name: 'users',
  initialState,
  reducers: {
    userAdded: usersAdapter.addOne,
    userUpdated: usersAdapter.updateOne,
    userRemoved: usersAdapter.removeOne,
    usersCleared: usersAdapter.removeAll,
  },
  extraReducers: (builder) => {
    builder.addCase(fetchUsers.fulfilled, (state, action) => {
      usersAdapter.upsertMany(state, action.payload);
      state.status = 'succeeded';
    });
  },
});

export const { userAdded, userUpdated, userRemoved, usersCleared } = usersSlice.actions;
export default usersSlice.reducer;

// Selectors — pass the slice state selector to scope them
export const {
  selectAll: selectAllUsers,
  selectById: selectUserById,
  selectIds: selectUserIds,
  selectTotal: selectTotalUsers,
} = usersAdapter.getSelectors<RootState>((state) => state.users);

Details

Normalized shape: The adapter stores

{ ids: string[], entities: Record<string, Entity> }

. The

ids

array controls display order;

entities

provides O(1) lookup. This is the same normalization pattern from the

normalizr

library.

CRUD methods: Each method has single and batch variants:

• addOne

  /

  addMany

  — insert if not present, no-op if ID exists

• setOne

  /

  setMany

  /

  setAll

  — replace entirely (add or overwrite)

• upsertOne

  /

  upsertMany

  — add or shallow merge

• updateOne

  /

  updateMany

  — apply a partial update to an existing entity (uses

  { id, changes }

  )

• removeOne

  /

  removeMany

  /

  removeAll

updateOne shape: Pass

{ id: string, changes: Partial<Entity> }

, not the full entity:

dispatch(userUpdated({ id: '1', changes: { name: 'New Name' } }));

Custom ID field: If your entity uses

_id

or

uuid

instead of

id

:

const adapter = createEntityAdapter<Entity>({ selectId: (entity) => entity._id });

Sorting:

sortComparer

keeps

ids

sorted after every CRUD operation. Omit it if sort order does not matter — unsorted is faster for large collections.

Source

https://redux-toolkit.js.org/api/createEntityAdapter

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.