Entity State and Adapter APIs

Entity state stores collections as id-keyed maps for constant-time lookups, rather than arrays that require linear search.

Entity State Interface

import { EntityState, EntityAdapter, createEntityAdapter } from '@ngrx/entity';

export interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
}

export interface UserState extends EntityState<User> {
  loading: boolean;
  error: string | null;
}

Creating an Entity Adapter

export const userAdapter: EntityAdapter<User> = createEntityAdapter<User>({
  selectId: (user) => user.id,  // Default: 'id' property
  sortComparer: false,            // Default: no sorting
});

Initial State

export const initialState: UserState = userAdapter.getInitialState({
  loading: false,
  error: null,
});

Adapter State Shape

{
  ids: [1, 2, 3],           // Array of IDs (order preserved)
  entities: {               // Map of id -> entity
    1: { id: 1, name: 'Alice', email: 'alice@example.com', isActive: true },
    2: { id: 2, name: 'Bob', email: 'bob@example.com', isActive: false },
    3: { id: 3, name: 'Charlie', email: 'charlie@example.com', isActive: true },
  },
  loading: false,
  error: null,
}

EntityAdapter provides methods for common collection operations and generates selectors.

Adapter Methods

// Reducer with adapter operations
export const userReducer = createReducer(
  initialState,

  on(UserActions.loadUsersSuccess, (state, { users }) =>
    userAdapter.setAll(users, { ...state, loading: false })
  ),

  on(UserActions.addUser, (state, { user }) =>
    userAdapter.addOne(user, state)
  ),

  on(UserActions.updateUser, (state, { user }) =>
    userAdapter.upsertOne(user, state)
  ),

  on(UserActions.deleteUser, (state, { id }) =>
    userAdapter.removeOne(id, state)
  ),

  on(UserActions.deleteUsers, (state, { ids }) =>
    userAdapter.removeMany(ids, state)
  ),
);

Adapter Method Reference

Adapter-Generated Selectors

export const {
  selectIds,      // (state) => state.ids
  selectEntities, // (state) => state.entities
  selectAll,      // (state) => User[]
  selectTotal,    // (state) => number
} = userAdapter.getSelectors(selectUserState);

// In component
users$ = this.store.select(selectAll);
userCount$ = this.store.select(selectTotal);

Why Normalize?