npm package: @n3/react-entities
Description: Provider of entities with loading and updating for react applications
Author: Vadim Taits
Latest version: 0.1.2

# @n3/react-entities

Провайдер сущностей для страниц с возможностью загрузки, перезагрузки и обновления.

## Api

### Описание списка сущности

Список сущности описывается следующим объектом:

```
type ListType = {
  values: {
    [string]: any;
  };
  listValues: {
    [string]: any;
  };
  params: ?any;
  subscribersCount: number;
}
```

- **values** - значения, полученные в результате маппинга по конфигу;
- **listValues** - значения, полученные в результате маппинга по конфигу;
- **params** - параметры (например, параметры браузерной строки);
- **subscribersCount** - **внутреннее**, количество компонентов, слушающих данное состояние списка.

### Описание детального просмотра сущности

Детальный просмотр сущности описывается следующим объектом:

```
type DetailType = {
  data: ?any;
  error: ?any;
  values: {
    [string]: any;
  };
  detailValues: {
    [string]: any;
  };
  loading: boolean;
  reloading: boolean;
  hasError: boolean;
  params: ?any;
  subscribersCount: number;
}
```

- **data** - текущие данные сущности;
- **error** - ошибка загрузки сущности;
- **values** - значения, полученные в результате маппинга по конфигу;
- **detailValues** - значения, полученные в результате маппинга по конфигу;
- **loading** - текущие данные сущности;
- **reloading** - текущие данные сущности;
- **hasError** - текущие данные сущности;
- **params** - параметры (например, параметры браузерной строки);
- **subscribersCount** - **внутреннее**, количество компонентов, слушающих данное состояние детального просмотра.

### Описание конфига сущности

Конфиг сущности описывается следующим объектом:

```
type StateMappers = {
  getListState: (entityType: string, params: any) => ListType;
  getDetailState: (entityType: string, params: any) => DetailType;
};

type EntityConfigType = {
  mappers: {
    [string]: (params: any, stateMappers: StateMappers) => ?any;
  };
  listMappers: {
    [string]: (params: any, stateMappers: StateMappers) => ?any;
  };
  detailMappers: {
    [string]: (params: any, stateMappers: StateMappers) => ?any;
  };

  loadEntity: (params: any, stateMappers: StateMappers) => ?any;

  getListUniq: ?(params) => string;
  getDetailUniq: (params) => string;
}
```

- **getListState** - функция для получения состояния списка сущности `entityType`;
- **getDetailState** - функция для получения состояния детального просмотра сущности `entityType`;

- **mappers** - объект мапперов, результаты вызовов которых будут записаны в `values` списка и детального просмотра;
- **listMappers** - объект мапперов, результаты вызовов которых будут записаны в `listValues` списка;
- **detailMappers** - объект мапперов, результаты вызовов которых будут записаны в `detailValues` детального просмотра;

- **loadEntity** - асинхронная функция загрузки сущности. В результате успешного выполнения, результат будет записан в `data` детального просмотра. Если в результате исполнения будет брошено исключение `LoadEntityError(error)`, `error` будет записано в `error` детального просмотра;

- **getListUniq** - необязательное, функция получения уникального идентификатора списка;
- **getDetailUniq** - функция получения уникального идентификатора детального просмотра.

### Объект конфигов сущностей

```
type EntityConfigsType = {
  [entityType: string]: EntityConfigType;
};
```

### EntitiesProvider

Провайдер, хранящий состояния сущностей

```
import { EntitiesProvider, DEFAULT_CONFIG } from '@n3/react-entities';

<EntitiesProvider
  configs={{
    [DEFAULT_CONFIG]: defaultConfig,
    otherConfigName: otherConfig,
  }}
  compareParams={compareParams}
>
  ...
</EntitiesProvider>
```

- **configs** - необязательное, объект конфигов. Конфиг по ключу `DEFAULT_CONFIG` будет загружаться по умолчанию в дочерних компонентах, если у них не указан `configType`. Каждый конфиг по каждому ключу является `EntityConfigsType`.

- **compareParams** - необязательное, функция сравнения параметров для перезагрузки сущностей в случае их изменения. Принимает первым и вторым аргументами старые и новые значения параметров. По умолчанию, сравнивает их с помощью `===`.

### ConfigInjector

Компонент для добавления конфигов глобальному провайдеру. При монтировании асинхронно добавляет конфиг, а при размонтировании удаляет его.

```
import { ConfigInjector } from '@n3/react-entities';

<ConfigInjector
  configType={configType}
  config={config}
>
  {({ isInjected }) => (
    ...
  )}
</ConfigInjector>
```

- **configType** - необязательное, строка, тип конфига, по умолчанию `DEFAULT_CONFIG`;
- **config** - обязательное, конфиг типа `EntityConfigsType`;

- **isInjected** - булево, загружен ли конфиг в провайдер.

### Entities

Компонент для предоставления списков сущностей и детальных просмотров.

```
import { Entities } from '@n3/react-entities';

<Entities
  configType={configType}
  params={params}
  listTypes={['entity1', 'entity2', 'entity3']}
  detailTypes={['entity4', 'entity5', 'entity6']}
>
  {({
    list: {
      entity1,
      entity2,
      entity3,
    },
    detail: {
      entity4,
      entity5,
      entity6,
    },

    reloadEntity,
    updateEntity,
  }) => (
    ...
  )}
</Entities>
```

- **configType** - необязательное, строка, тип конфига, по умолчанию `DEFAULT_CONFIG`;
- **params** - обязательное, параметры (например, параметры браузерной строки);
- **listTypes** - необязательное, массив типов списков сущностей;
- **detailTypes** - необязательное, массив типов детальных просмотров сущностей;

- **list** - объект состояний `ListType` сущностей, типы которых переданы в `listTypes`;
- **detail** - объект состояний `DetailType` сущностей, типы которых переданы в `detailTypes`;

- **reloadEntity** - функиця перезагрузки сущности в детальном просмотре, первым аргументом принимает тип сущности;
- **updateEntity** - функиця обновления сущности в детальном просмотре, первым аргументом принимает тип сущности, вторым - новые данные сущности.

### EntityList

Компонент для предоставления списка одной сущности.

```
import { EntityList } from '@n3/react-entities';

<EntityList
  configType={configType}
  params={params}
  entityType={entityType}
>
  {({ entityList }) => (
    ...
  )}
</EntityList>
```

- **configType** - необязательное, строка, тип конфига, по умолчанию `DEFAULT_CONFIG`;
- **params** - обязательное, параметры (например, параметры браузерной строки);
- **entityType** - необязательное, строка, тип сущности;

- **entityList** - `ListType` сущности.

### EntityDetail

Компонент для предоставления детального просмотра сущности.

```
import { EntityDetail } from '@n3/react-entities';

<EntityDetail
  configType={configType}
  params={params}
  entityType={entityType}
>
  {({
    entityDetail,

    reloadEntity,
    updateEntity,
  }) => (
    ...
  )}
</EntityDetail>
```

- **configType** - необязательное, строка, тип конфига, по умолчанию `DEFAULT_CONFIG`;
- **params** - обязательное, параметры (например, параметры браузерной строки);
- **entityType** - необязательное, строка, тип сущности;

- **entityDetail** - `DetailType` сущности;

- **reloadEntity** - функиця перезагрузки текущей сущности;
- **updateEntity** - функиця обновления текущей сущности, первым аргументом принимает новые данные сущности.