Angular-ngrx-data — state management і CRUD за п’ять хвилин
На сьогоднішній день жодна велика SPA програма не обходиться без state management (управління). Для Angular за даним напрямом є кілька рішень. Найпопулярнішим з них є NgRx. Він реалізує Redux патерн з використанням бібліотеки RxJs і володіє хорошим інструментарієм.
У даній статті ми коротко пройдемося по основним модулям NgRx і більш детально зосередимося на бібліотеці angular-ngrx-data, яка дозволяє зробити повноцінний CRUD зі state management за п’ять хвилин.
Огляд NgRx
Детально про NgRx можна почитати в наступних статтях:
— Реактивні програми на Angular/NGRX. Частина 1. Введення
— Реактивні програми на Angular/NGRX. Частина 2. Store
— Реактивні програми на Angular/NGRX. Частина 3. Effects
Коротко розглянемо основні модулі NgRx, його плюси і мінуси.
NgRx/store — реалізує Redux патерн.
Проста реалізація storecounter.actions.ts
export const INCREMENT = 'INCREMENT';
export const DECREMENT = 'DECREMENT';
export const RESET = 'RESET';
counter.reducer.ts
import { Action } from '@ngrx/store';
const initialState = 0;
export function counterReducer(state: number = initialState, action: Action) {
switch (action.type) {
case INCREMENT:
return state + 1;
case DECREMENT:
return state - 1;
case RESET:
return 0;
default:
return state;
}
}
.
Підключення до модуля
import { NgModule } from '@angular/core';
import { StoreModule } from '@ngrx/store';
import { counterReducer } from './counter';
@NgModule({
imports: [StoreModule.forRoot({ count: counterReducer })],
})
export class AppModule {}
Використання в компоненті
import { Component } from '@angular/core';
import { Store, select } from '@ngrx/store';
import { Вами } from 'rxjs';
import { INCREMENT, DECREMENT, RESET } from './counter';
interface AppState {
count: number;
}
@Component({
selector: 'app-my-counter',
template: `
<button (click)="increment()">Increment</button>
<div>Current Count: {{ count$ | async }}</div>
<button (click)="decrement()">Decrement</button>
<button (click)="reset()">Reset Counter</button>
`,
})
export class MyCounterComponent {
count$: Вами<number>;
constructor(private store: Store<AppState>) {
this.count$ = store.pipe(select('count'));
}
increment() {
this.store.dispatch({ type: INCREMENT });
}
decrement() {
this.store.dispatch({ type: DECREMENT });
}
reset() {
this.store.dispatch({ type: RESET });
}
}
NgRx/store-devtools — дозволяє відстежувати зміни в додатку через redux-devtools.
Приклад підключення
import { StoreDevtoolsModule } from '@ngrx/store-devtools';
@NgModule({
imports: [
StoreModule.forRoot(reducers),
// Модуль повинен бути підключений після StoreModule
StoreDevtoolsModule.instrument({
maxAge: 25, // Зберігаються останні 25 станів
}),
],
})
export class AppModule {}NgRx/effects дозволяє додавати в сховище дані, що приходять в додаток, такі як http запити.
Приклад./effects/auth.effects.ts
import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Action } from '@ngrx/store';
import { Actions, Effect, ofType } from '@ngrx/effects';
import { Вами, of } from 'rxjs';
import { catchError, map, mergeMap } from 'rxjs/operators';
@Injectable()
export class AuthEffects {
// Listen for the 'LOGIN' action
@Effect()
login$: Вами<Action> = this.actions$.pipe(
ofType('LOGIN'),
mergeMap(action =>
this.http.post('/auth', action.payload).pipe(
// If successful, dispatch success action with result
map(data => ({ type: 'LOGIN_SUCCESS', payload: data })),
// If request fails, dispatch failed action
catchError(() => of({ type: 'LOGIN_FAILED' }))
)
)
);
constructor(private http: HttpClient, private actions$: Actions) {}
}
Підключення ефекту в модуль
import { EffectsModule } from '@ngrx/effects';
import { AuthEffects } from './effects/auth.effects';
@NgModule({
imports: [EffectsModule.forRoot([AuthEffects])],
})
export class AppModule {}
NgRx/entity — надає можливість працювати з масивами даних.
Прикладuser.model.ts
export User interface {
id: string;
name: string;
}
user.actions.ts
import { Action } from '@ngrx/store';
import { Оновити } from '@ngrx/entity';
import { User } from './user.model';
export enum UserActionTypes {
LOAD_USERS = '[User] Load Users',
ADD_USER = '[User] Add User',
UPSERT_USER = '[User] Upsert User',
ADD_USERS = '[User] Add Users',
UPSERT_USERS = '[User] Upsert Users',
UPDATE_USER = '[User] Update User',
UPDATE_USERS = '[User] Update Users',
DELETE_USER = '[User] Delete User',
DELETE_USERS = '[User] Delete Users',
CLEAR_USERS = '[User] Clear Users',
}
export class LoadUsers implements Action {
readonly type = UserActionTypes.LOAD_USERS;
constructor(public payload: { users: User[] }) {}
}
export class AddUser implements Action {
readonly type = UserActionTypes.ADD_USER;
constructor(public payload: { user: User }) {}
}
export class UpsertUser implements Action {
readonly type = UserActionTypes.UPSERT_USER;
constructor(public payload: { user: User }) {}
}
export class AddUsers implements Action {
readonly type = UserActionTypes.ADD_USERS;
constructor(public payload: { users: User[] }) {}
}
export class UpsertUsers implements Action {
readonly type = UserActionTypes.UPSERT_USERS;
constructor(public payload: { users: User[] }) {}
}
export class UpdateUser implements Action {
readonly type = UserActionTypes.UPDATE_USER;
constructor(public payload: { user: Update<User> }) {}
}
export class UpdateUsers implements Action {
readonly type = UserActionTypes.UPDATE_USERS;
constructor(public payload: { users: Update<User>[] }) {}
}
export class DeleteUser implements Action {
readonly type = UserActionTypes.DELETE_USER;
constructor(public payload: { id: string }) {}
}
export class DeleteUsers implements Action {
readonly type = UserActionTypes.DELETE_USERS;
constructor(public payload: { ids: string[] }) {}
}
export class ClearUsers implements Action {
readonly type = UserActionTypes.CLEAR_USERS;
}
export type UserActionsUnion =
| LoadUsers
| AddUser
| UpsertUser
| AddUsers
| UpsertUsers
| UpdateUser
| UpdateUsers
| DeleteUser
| DeleteUsers
| ClearUsers;
user.reducer.ts
import { EntityState, EntityAdapter, createEntityAdapter } from '@ngrx/entity';
import { User } from './user.model';
import { UserActionsUnion, UserActionTypes } from './user.actions';
export interface State extends EntityState<User> {
// additional entities state properties
selectedUserId: number | null;
}
export const adapter: EntityAdapter<User> = createEntityAdapter<User>();
export const initialState: State = adapter.getInitialState({
// additional entity state properties
selectedUserId: null,
});
export function reducer(state = initialState, action: UserActionsUnion): State {
switch (action.type) {
case UserActionTypes.ADD_USER: {
return adapter.addOne(action.payload.user, state);
}
case UserActionTypes.UPSERT_USER: {
return adapter.upsertOne(action.payload.user, state);
}
case UserActionTypes.ADD_USERS: {
return adapter.addMany(action.payload.users, state);
}
case UserActionTypes.UPSERT_USERS: {
return adapter.upsertMany(action.payload.users, state);
}
case UserActionTypes.UPDATE_USER: {
return adapter.updateOne(action.payload.user, state);
}
case UserActionTypes.UPDATE_USERS: {
return adapter.updateMany(action.payload.users, state);
}
case UserActionTypes.DELETE_USER: {
return adapter.removeOne(action.payload.id state);
}
case UserActionTypes.DELETE_USERS: {
return adapter.removeMany(action.payload.ids, state);
}
case UserActionTypes.LOAD_USERS: {
return adapter.addAll(action.payload.users, state);
}
case UserActionTypes.CLEAR_USERS: {
return adapter.removeAll({ ...state, selectedUserId: null });
}
default: {
return state;
}
}
}
export const getSelectedUserId = (state: State) => state.selectedUserId;
// get the selectors
const { selectIds, selectEntities, selectAll, selectTotal } = adapter.getSelectors();
// select the array of user ids
export const selectUserIds = selectIds;
// select the dictionary of user entities
export const selectUserEntities = selectEntities;
// select the array of users
export const selectAllUsers = selectAll;
// select the total user count
export const selectUserTotal = selectTotal;
reducers/index.ts
import {
createSelector,
createFeatureSelector,
ActionReducerMap,
} from '@ngrx/store';
import * as fromUser from './user.reducer';
export interface State {
користувачі: fromUser.State;
}
export const reducers: ActionReducerMap<State> = {
користувачі: fromUser.reducer,
};
export const selectUserState = createFeatureSelector<fromUser.State>('users');
export const selectUserIds = createSelector(
selectUserState,
fromUser.selectUserIds
);
export const selectUserEntities = createSelector(
selectUserState,
fromUser.selectUserEntities
);
export const selectAllUsers = createSelector(
selectUserState,
fromUser.selectAllUsers
);
export const selectUserTotal = createSelector(
selectUserState,
fromUser.selectUserTotal
);
export const selectCurrentUserId = createSelector(
selectUserState,
fromUser.getSelectedUserId
);
export const selectCurrentUser = createSelector(
selectUserEntities,
selectCurrentUserId,
(userEntities, userId) => userEntities[userId]
);
Що в підсумку?
Ми отримуємо повноцінний state management з купою плюсів:
— єдиний джерело даних для програми,
— стан зберігається окремо від програми,
— єдиний стиль написання для всіх розробників у проекті,
— changeDetectionStrategy.OnPush у всіх компонентах програми,
— зручне налагодження через redux-devtools,
— легкість тестування, так як reducers є “чистими” функціями.
Але є і мінуси:
— велика кількість незрозумілих на перший погляд модулів,
— багато однотипного коду, на який без смутку не глянеш,
— складність в освоєнні через все вище перераховане.
CRUD
Як правило, значну частину програми займає робота з об’єктами (створення, читання, оновлення, видалення), тому для зручності роботи була придумана концепція CRUD (Create, Read, Update, Delete). Таким чином, базові операції для роботи з усіма типами об’єктів стандартизовані. На бэкенді це уже давно процвітає. Багато бібліотеки допомагають реалізувати дану функціональність і позбутися від рутинної роботи.
У NgRx за CRUD відповідає модуль entity, і якщо подивитися приклад його реалізації, відразу видно, що це найбільша і найскладніша частина NgRx. Саме тому Papa John Ward і Bell створили angular-ngrx-data.
angular-ngrx-data
angular-ngrx-data — це бібліотека-надбудова над NgRx, яка дозволяє працювати з масивами даних без написання зайвого коду.
Крім створення повноцінного state management, вона бере на себе створення сервісів з http для взаємодії з сервером.
Розглянемо на прикладі
Установка
npm install --save @ngrx/store @ngrx/effects @ngrx/entity @ngrx/store-devtools ngrx-data
Модуль angular-ngrx-data
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import {
EntityMetadataMap,
NgrxDataModule,
DefaultDataServiceConfig
} from 'ngrx-data';
const defaultDataServiceConfig: DefaultDataServiceConfig = {
root: 'crud'
};
export const entityMetadata: EntityMetadataMap = {
Hero: {},
User:{}
};
export const pluralNames = { Hero: 'heroes' };
@NgModule({
imports: [
CommonModule,
NgrxDataModule.forRoot({ entityMetadata, pluralNames })
],
declarations: [],
providers: [
{ provide: DefaultDataServiceConfig, useValue: defaultDataServiceConfig }
]
})
export class EntityStoreModule {}Підключення в додаток
@NgModule({
imports: [
BrowserModule,
HttpClientModule,
StoreModule.forRoot({}),
EffectsModule.forRoot([]),
EntityStoreModule,
StoreDevtoolsModule.instrument({
maxAge: 25,
}),
],
declarations: [
AppComponent
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule {}
Тільки що ми отримали згенероване API для роботи з беком та інтеграцію API з NgRx, не написавши при цьому жодного effect, reducer і action і selector.
Розберемо більш докладно те, що тут відбувається
Константа defaultDataServiceConfig задає конфігурацію для нашого API і підключається в providers модуля. Властивість root вказує, куди звертатися за запитами. Якщо його не поставити, то за замовчуванням буде «api».
const defaultDataServiceConfig: DefaultDataServiceConfig = {
root: 'crud'
};Константа entityMetadata визначає назви сторів, які будуть створені при підключенні NgrxDataModule.forRoot.
export const entityMetadata: EntityMetadataMap = {
Hero: {},
User:{}
};
...
NgrxDataModule.forRoot({ entityMetadata, pluralNames })
Шлях до API складається з базового шляху (у нашому випадку «crud») та імені стора.
Наприклад, для отримання користувача з певним номером шлях буде такий — «crud/user/{userId}».
Для одержання повного списку користувачів в кінці імені стора за замовчуванням додається літера «s» — «crud/users».
Якщо для одержання повного списку потрібен (наприклад, «heroes», а не «heros»), його можна змінити, задавши pluralNames і підключивши їх в NgrxDataModule.forRoot.
export const pluralNames = { Hero: 'heroes' };
...
NgrxDataModule.forRoot({ entityMetadata, pluralNames })
Підключення в компоненті
Для підключення в компоненті необхідно передати в конструктор entityServices і через метод getEntityCollectionService вибрати сервіс потрібного сховища
import { Component, OnInit, ChangeDetectionStrategy } from '@angular/core';
import { Вами } from 'rxjs';
import { Hero } from '@appModels/hero';
import { EntityServices, EntityCollectionService } from 'ngrx-data';
@Component({
selector: 'app-heroes',
templateUrl: './heroes.component.html',
styleUrls: ['./heroes.component.css'],
changeDetection: ChangeDetectionStrategy.OnPush
})
export class HeroesComponent implements OnInit {
heroes$: Вами<Hero[]>;
heroesService: EntityCollectionService<Hero>;
constructor(entityServices: EntityServices) {
this.heroesService = entityServices.getEntityCollectionService('Hero');
}
...
}
Для прив’язки до списку компоненту достатньо взяти з сервісу властивість entities$, а для отримання даних з сервера викликати метод getAll().
ngOnInit() {
this.heroes$ = this.heroesService.entities$;
this.heroesService.getAll();
}
Також, крім основних даних, можна отримати:
— loaded$, loading$ — отримання статусу завантаження даних,
— errors$ — помилки при роботі сервісу,
— count$ — загальна кількість записів у сховище.
Основні методи взаємодії з сервером:
— getAll() — отримання списку даних,
— getWithQuery(query) — отримання списку, відфільтрованого з допомогою query-параметрів,
— getByKey(id) — отримання запису за ідентифікатором,
— add(entity) — додавання нової сутності із запитом на бек,
— delete(entity) — видалення сутності із запитом на бек,
— update(entity) — оновлення сутності із запитом на бек.
Методи локальної роботи зі сховищем:
— addManyToCache(entity) — додавання масиву нових сутностей в сховище,
— addOneToCache(entity) — додавання нової сутності тільки в сховище,
— removeOneFromCache(id) — видалення однієї сутності з сховища,
— updateOneInCache(entity) — оновлення сутності в сховищі,
— upsertOneInCache(entity) — якщо сутність із зазначеним id існує, вона оновлюється, якщо немає — створюється нова,
— та ін
Приклад використання в компоненті
import { EntityCollectionService, EntityServices } from 'ngrx-data';
import { Hero } from '../../core';
@Component({
selector: 'app-heroes',
templateUrl: './heroes.component.html',
changeDetection: ChangeDetectionStrategy.OnPush
})
export class HeroesComponent implements OnInit {
heroes$: Вами<Hero[]>;
heroesService: EntityCollectionService<Hero>;
constructor(entityServices: EntityServices) {
this.heroesService = entityServices.getEntityCollectionService('Hero');
}
ngOnInit() {
this.heroes$ = this.heroesService.entities$;
this.getHeroes();
}
getHeroes() {
this.heroesService.getAll();
}
addHero(hero: Hero) {
this.heroesService.add(hero);
}
deleteHero(hero: Hero) {
this.heroesService.delete(hero.id);
}
updateHero(hero: Hero) {
this.heroesService.update(hero);
}
}Всі методи angular-ngrx-data поділяються на працюючі локально і взаємодіють з сервером. Це дозволяє використовувати бібліотеку при маніпуляціях з даними як на клієнті, так і з використанням сервера.
Логування
Для логування необхідно заінжектити EntityServices в компонент або сервіс і використовувати властивості:
— reducedActions$ — для логування дій,
— entityActionErrors$ — для логування помилок.
import { Component, OnInit } from '@angular/core';
import { MessageService } from '@appServices/message.service';
import { EntityServices } from 'ngrx-data';
@Component({
selector: 'app-messages',
templateUrl: './messages.component.html',
styleUrls: ['./messages.component.css']
})
export class MessagesComponent implements OnInit {
constructor(
public messageService: MessageService,
private entityServices: EntityServices
) {}
ngOnInit() {
this.entityServices.reducedActions$.subscribe(res => {
if (res && res.type) {
this.messageService.add(res.type);
}
});
}
}
Переїзд в основний репозиторій NgRx
Як було оголошено на ng-conf 2018, angular-ngrx-data найближчим часом буде перенесений в основний репозиторій NgRx.
Відео з доповіддю Reducing the Boilerplate with NgRx – Brandon Roberts & Mike Ryan
Джерела
Творці anguar-ngrx-data:
— Papa John twitter.com/John_Papa
— Ward Bell twitter.com/wardbell
Російськомовне Angular співтовариство в Telegram
