@astral/mobx-query 1.8.1 → 1.10.0

package/README.md

@@ -3,414 +3,704 @@
 Библиотека для кеширования запросов.
 
 Особенности:
-- Ориентирована на специфику frontend приложений
-- Для обеспечения реактивности используется [mobx](https://mobx.js.org/)
-- По идеологии использования схожа с [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query/)
-- TS only, totally no `any`
-
----
+- ⚡️️️️ Реактивный кэш на основе [mobx](https://mobx.js.org/)
+- ️️️️️️⚡️️️️ Вдохновлено [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query/)
+- ⚡️️️️ Декларативный способ описания queries и mutations
+- ⚡️️️️ Реализация архитектурного подхода работы с данными [Astral Architecture Guide](https://guides.frontend.cloud.astral-dev.ru/docs/arch/intro)
+- ⚡️️️️ Фоновая подгрузка данных для работы с WebSocket
+- ⚡️️️️ Возможность тестирования
 
 ## Table of contents
+
 - [Installation](#installation)
-- [Basic meaning](#basic-meaning)
-- [Варианты использования query](#варианты-использования-query)
-  - [Ручной синхронный](#1-ручной-синхронный)
-  - [Ручной асинхронный](#2-ручной-асинхронный)
-  - [Автоматический](#3-автоматический)
-- [Инвалидация данных](#инвалидация-данных)
-  - [Особенности инвалидации](#особенности-инвалидации)
-- [Ручная установка данных в кэш](#ручная-установка-данных-в-кэш)
-- [InfiniteQuery](#infinitequery)
-  - [isEndReached](#isendreached)
-- [Mutation](#mutation)
-  - [Sync вариация](#sync-вариация)
-  - [Async вариация](#async-вариация)
-- [Fetch policy](#fetchpolicy)
-- [Вспомогательные флаги и поля](#вспомогательные-флаги-и-поля)
-  - [isLoading](#isloading)
-  - [isSuccess](#issuccess)
-  - [isError](#iserror)
-  - [error](#error)
-- [Тестирование](#тестирование)
-  - [Тестирование при включенном enabledAutoFetch](#тестирование-при-включенном-enabledautofetch)
-
-# Installation
-
-```shell
-npm i --save @astral/mobx-query
-```
-
-```shell
-yarn add @astral/mobx-query
+  - [Basic usage](#basic-usage)
+  - [Core concepts](#core-concepts)
+  - [QuerySet](#queryset)
+    - [Создание QuerySet](#создание-queryset)
+    - [Использование QuerySet](#использование-queryset)
+    - [Синхронный вызов запроса данных](#синхронный-вызов-запроса-данных)
+    - [Асинхронный вызов запроса данных](#асинхронный-вызов-запроса-данных)
+    - [Автоматический запрос данных](#автоматический-запрос-данных)
+  - [InfiniteQuerySet](#infinitequerygroups)
+    - [Создание InfiniteQuerySet](#создание-infinitequerygroups)
+    - [Использование InfiniteQuerySet](#использование-infinitequerygroups)
+    - [Загрузка данных](#загрузка-данных)
+    - [isEndReached. Определение конца списка](#isendreached-определение-конца-списка)
+    - [Изменение количества запрашиваемых записей](#изменение-количества-запрашиваемых-записей)
+  - [MutationSet](#mutationset)
+    - [Создание mutations](#создание-и-использование-mutations)
+    - [Синхронный вызов mutation](#синхронный-вызов-mutation)
+    - [Асинхронный вызов mutation](#асинхронный-вызов-mutation)
+  - [Кэширование QuerySet и InfiniteQuerySet](#кэширование-queryset-и-infinitequeryset)
+    - [FetchPolicy](#fetchpolicy)
+    - [Как работает кэш](#как-работает-кэш)
+    - [Инвалидация кэша QuerySet](#инвалидация-кэша-queryset)
+    - [Кастомная установка ключей кэширования](#кастомная-установка-ключей-кэширования)
+  - [Фоновая загрузка данных QuerySet и InfiniteQuerySet](#фоновая-загрузка-данных-queryset-и-infinitequeryset)
+  - [Изменение кэша QuerySet и InfiniteQuerySet](#изменение-кэша-queryset-и-infinitequeryset)
+  - [Тестирование QuerySet и InfiniteQuerySet](#тестирование-queryset-и-infinitequeryset)
+- [Core](#core)
+
+## Installation
+
+```bash
+npm install @astral/mobx-query --save
 ```
 
----
+```bash
+yarn add @astral/mobx-query
+```
 
-# Basic meaning
-- executor - исполнитель запроса, который будет совершать запрос. Второй аргумент при создании query
-- enabledAutoFetch - включает автоматический запрос данных при обращении к полю `data`.
-- fetchPolicy - политика, говорящая о том, как следует работать с новыми запросами
-    - 'cache-first' - политика применяемая по умолчанию, при отсутствии данных в памяти, будет исполнен executor, его ответ запишется в кеш, и при последующих обращениях данные будут взяты из кеша
-    - 'network-only' - каждый запрос будет приводить к вызову executor, его ответ будет записан в кеш(для использования в cache-first)
+## Basic usage
 
-# Basic usage
+```
+├── api/ 
+|    ├── _fakers/
+|    ├── endpoints/
+|    ├── fetchers/
+|    |    ├── docs.ts
+|    |    └── index.ts
+|    ├── services/
+|    |    ├── CacheService/
+|    |    |    ├── CacheService.ts
+|    |    |    └── index.ts
+|    |    └── index.ts
+|    └── index.ts                         
+```
 
-Для начала вам потребуется создать инстанс кеш сервиса
+Инициализация MobxQuery:
+```api/services/CacheService/CacheService.ts```
 ```ts
 import { MobxQuery } from '@astral/mobx-query';
 
-const mobxQuery = new MobxQuery({
-    onError: (error) => {
-        console.log(error); // место для вашей обработки ошибок по умолчанию, опционально
-    },
-    fetchPolicy: 'cache-first', // 'cache-first' по умолчанию, опционально 
-    enabledAutoFetch: false, // false по умолчанию, опционально
-});
+// рекомендуется явно задавать параметры для MobXQuery
+export const createCacheService = () =>
+  new MobxQuery({ enableAutoFetch: true, fetchPolicy: 'cache-first' });
+
+export const cacheService = createCacheService();
 ```
 
-# Варианты использования query
-## 1. Ручной синхронный.
+Определение fetcher и cacheGroups для docs:
+```api/services/Fetcher/docs.ts```
+```ts
+const docsFetcher = {
+  queries: {
+    doc: cacheService.createQuerySet((id: string) => ({
+      execute: () => docsEndpoint.getDoc(id).then(({ data }) => data),
+    })),
+  },
+  infiniteQueries: {
+    docList: cacheService.createInfiniteQuerySet(
+      (filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>) => ({
+        execute: ({ offset, count }) =>
+          docsEndpoint
+            .getDocList({ offset, count, ...filters })
+            .then(({ data }) => data.list),
+      }),
+    ),
+  },
+  mutations: {
+    editDoc: cacheService.createMutationSet(
+      (params: DocsEndpointsDTO.EditDocInput) => docsEndpoint.editDoc(params),
+    ),
+  },
+};
+
+export type DocsFetcher = typeof docsFetcher;
+```
 
-Можно вызывать встроенный метод `sync`, передавая в него колбэк опциональные параметры `onSucess` и `onError`. В onSuccess будут переданы полученные данные от успешного запроса, а в `onError`, соответственно, будет переданы данные ошибки в случае провального запроса.
-Если при вызове обработчик `onError` не был передан, вызовется стандартный, переданный при создании MobxQuery инстанса.
+Использование в store:
 
 ```ts
-const query = mobxQuery.createQuery(
-    ['some cache key'],
-    () => Promise.resolve('foo'),
-);
+import { type DocsFetcher } from '@example/api';
+
+class DocStore {
+  constructor(
+    private readonly _docID: string,
+    private readonly _docsFetcher: DocsFetcher,
+  ) {
+    makeAutoObservable(this, {}, { autoBind: true });
+  }
+
+  private get docQuery() {
+    return this._docsFetcher.queries.doc.create(this.docID);
+  }
 
-query.sync({
-    onSuccess: (data) => {
-        console.log(data); // место для реагирования на ответ
-    },
-    onError: (error) => {
-        console.log(error); // место для вашей ошибки
+  public get docName() {
+    if (!this.docQuery.data) {
+      return '';
     }
+
+    return `Название документа: ${this.docQuery.data.name}`;
+  }
+
+  public get isLoading() {
+    return this.docQuery.isLoading;
+  }
+}
+```
+
+```ts
+class DocManagerStore {
+  constructor(private readonly _docsFetcher: DocsFetcher) {}
+
+  public changeOrg = () => {
+    // инвалидирует все doc query, которые есть в кэше
+    this._docsFetcher.queries.doc.invalidate();
+  };
+}
+```
+
+## Core concepts
+
+[`Query`](#query) предназначен для получения данных. Не должен производить изменения.
+[`QuerySet`](#queryset) - набор queries для данных, получаемых по одной и той же сущности с разными параметрами.
+[`InfiniteQuery`](#infinitequery) предназначен для получения бесконечного списка данных.
+[`Mutation`](#mutation) предназначен для изменения данных на сервере.
+[`MutationSet`](#mutationset) - набор mutations для изменения данных. Необходим для консистенстности api с `QuerySet`.
+
+`QuerySet`, `InfiniteQuerySet` и `MutationSet` создаются через методы MobxQuery:
+- `createQuerySet`
+- `createInfiniteQuerySet`
+- `createMutationSet`
+
+`Query`, `InfiniteQuery` и `Mutation` создаются через методы MobxQuery:
+- `createQuery`
+- `createInfiniteQuery`
+- `createMutation`
+
+Рекомендуется использовать именно Set'ы потому что это выскоуровневое api, скрывающее внутри себя сложность работы с кэшем и позволяющее работать с данными более декларативно. Set'ы используют внутри себя `Query`, `InfiniteQuery` и `Mutation`.
+
+Методы `createQuery`, `createInfiniteQuery` и `createMutation` необходимо использовать для реализации собственных библиотек для работы с данными.
+
+## QuerySet
+
+[`Query`](#query) предназначен для получения данных. Не должен производить изменения.
+`QuerySet` - набор queries для данных, получаемых по одной и той же сущности с разными параметрами.
+
+### Создание QuerySet
+
+В примере ниже будет создан doc query, который будет получать данные по id документа. После успешного выполнения запроса данные будут закэшированы.
+
+```ts
+const docsFetcher = {
+  queries: {
+    doc: mobxQuery.createQuerySet((id: string) => ({
+      execute: () => docsEndpoint.getDoc(id).then(({ data }) => data),
+    })),
+  },
+};
+```
+
+### Использование QuerySet
+
+Для получения объекта query необходимо вызвать метод `create`.
+Параметры `create` полностью идентичны параметрам, указанным при определении query:
+```ts
+const docsFetcher = {
+  queries: {
+    doc: mobxQuery.createQuerySet((id: string) => ({
+      execute: () => docsEndpoint.getDoc(id).then(({ data }) => data),
+    })),
+  },
+};
+
+// create принимает только один параметр - id: string
+const docQuery = docsFetcher.queries.doc.create('docID');
+```
+
+Метод `create` вернет [объект query](#query-interface), который содержит всю информацию по запросу и методы работы с запросом.
+
+### Синхронный вызов запроса данных
+
+Метод `sync` позволяет синхронно запустить запрос на получение данных:
+```ts
+const docQuery = docsFetcher.queries.doc.create(docID);
+
+// есть callbacks на обработку success и error
+docQuery.sync({
+  onSuccess: (data) => {
+    console.log(data);
+  },
+  onError: (error) => {
+    console.log(error);
+  },
 });
+
+// true
+docQuery.isLoading;
 ```
 
-**[Пример в sandbox](https://codesandbox.io/s/adoring-wing-z8s9ng)**
+### Асинхронный вызов запроса данных
 
-## 2. Ручной асинхронный.
+Метод `async` позволяет асинхронно запустить запрос на получение данных:
+```ts
+const docQuery = docsFetcher.queries.doc.create(docID);
+
+// передавать параметры запроса не нужно потому что они уже были переданы при вызове init
+const response = await docQuery.async();
+
+docQuery.isSuccess; // true
+docQuery.data; // идентичен response
+```
+
+### Автоматический запрос данных
 
-Можно вызвать встроенный метод async. Возвращает промис, соответственно в then попадут данные успешного запроса.
-`Будьте внимательны, используя метод "async", позаботьтесь о добавлении ".catch", иначе ошибка запроса попадет в глобальный exception`.
+Если MobxQuery был создан с флагом `enableAutoFetch: true`, то данные будут автоматически запрошены при обращении к полю `data`:
 
 ```ts
-const query = mobxQuery.createQuery(
-    ['some cache key'],
-    () => Promise.resolve('foo'),
+const docQuery = docsFetcher.queries.doc.create(docID);
+
+docQuery.data; // триггер запроса данных
+
+docQuery.isLoading; // true
+```
+
+Если MobxQuery был создан с флагом `enableAutoFetch: false`, то автоматически запрос данных можно включить для текущего query:
+```ts
+const docQuery = docsFetcher.queries.doc.createWithConfig((
+  { enableAutoFetch: true },
+  docID
 );
 
-query
-    .async()
-    .then((data) => {
-        console.log(data); // место для реагирования на ответ
-    })
-    .catch((e) => {
-        console.log(e); // место для вашей ошибки
-    });
+docQuery.data; // триггер запроса данных
+
+docQuery.isLoading; // true
 ```
-**[Пример в sandbox](https://codesandbox.io/s/mobx-query-simple-async-k75tfg)**
 
-## 3. Автоматический.
+## InfiniteQuerySet
 
-При создании query, предусмотрен вариант автоматического запроса при обращении к полю `data` из `query`. Требуется активация флага `enabledAutoFetch` при создании query, либо установка стандартного значения, при создании MobxQuery инстанса.
-Т.е. благодаря реактивности предоставляемой `mobx`, пока не произойдет считывания поля `data` или же не будут вызваны `sync/async` методы, запрос данных так же не произойдет.
+[`InfiniteQuery`](#infinitequery) предназначен для получения бесконечного списка данных.
+`InfiniteQuerySet` - набор InfiniteQuery для данных, получаемых по одной и той же сущности с разными параметрами.
 
-```tsx
-import { observer } from 'mobx-react-lite';
+### Создание InfiniteQuerySet
 
-const query = mobxQuery.createQuery(
-    ['some cache key'],
-    () => Promise.resolve('foo'),
-    { enabledAutoFetch: true }
-);
+В примере ниже будет создан docList InfiniteQuerySet. После успешного выполнения запроса данные будут закэшированы.
 
-const MyComponent = observer(() => <div>{query.data}</div>) // <div>foo</div>
+```ts
+const docsFetcher = {
+  infiniteQueries: {
+    docList: mobxQuery.createInfiniteQuerySet(
+      (filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>) => ({
+        execute: ({ offset, count }) =>
+          docsEndpoint
+            .getDocList({ offset, count, ...filters })
+            .then(({ data }) => data.list),
+      }),
+    ),
+  },
+};
 ```
-**[Пример в sandbox](https://codesandbox.io/s/happy-cherry-ytqgry)**
 
-# Инвалидация данных
-Существует необходимость инвалидировать данные, типичным примером являются [CRUD операции](https://ru.wikipedia.org/wiki/CRUD).
-В контексте нашей библиотеки, инвалидация подразумевает под собой отметку для query, означающую, что данные устарели, и их необходимо обновить.
-Для корректной работы инвалидации, при создании query требуется использование `ключа`.
-Ключ для создания может быть как примитивом, так и объектом. Главное, чтобы они были подходящими для JSON сериализации.
+### Использование InfiniteQuerySet
+
+Для получения объекта `InfiniteQuery` необходимо вызвать метод `create`.
+Параметры `create` полностью идентичны параметрам, указанным при определении InfiniteQuery:
+```ts
+const docsFetcher = {
+  infiniteQueries: {
+    docList: mobxQuery.createInfiniteQuerySet(
+      // Omit необходим для того, чтобы не передавать offset и count при вызове запроса из логики. Offset и count будут сформированы и переданы автоматически
+      (filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>) => ({
+        execute: ({ offset, count }) =>
+          docsEndpoint
+            .getDocList({ offset, count, ...filters })
+            // fetch должен возвращать array
+            .then(({ data }) => data.list),
+      }),
+    ),
+  },
+};
+
+// первым параметром create является - filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>
+const docListQuery = docsFetcher.infiniteQueries.docList.create({ search: 'test' });
+```
 
-Инстанс MobxQuery содержит специальный метод `invalidate`, принимающий в качестве аргумента `массив ключей`.
+### Загрузка данных
 
 ```ts
-const query = mobxQuery.createQuery(
-    ['some cache key'],
-    () => Promise.resolve('foo'),
-    { enabledAutoFetch: true }
-);
+import { when } from 'mobx';
+
+const docListQuery = docsFetcher.infiniteQueries.docList.create({ search: 'test' });
+
+await docListQuery.async(); // запрос на получение первых 30 записей
 
-mobxQuery.invalidate(['some cache key'])
+docListQuery.data.length; // 30 записей
+
+docListQuery.fetchMore(); // запрос на получение следующих 30 записей
+
+// ждем загрузки
+await when(() => !query.isLoading);
+
+docListQuery.data.length; // 60 записей
 ```
 
-**[Пример в sandbox](https://codesandbox.io/s/mobx-query-invalidate-query-hhcngr)**
+### `isEndReached`. Определение конца списка
 
-## Особенности инвалидации
-- Как при создании query, так и при инвалидации, нужно использовать массив ключей. Предполагается, что query может быть инвалидирован по нескольким ключам
+Флаг `isEndReached` будет установлен в `true`, если записи для загрузки закончились:
 ```ts
-const query = mobxQuery.createQuery(
-    ['key one', 'key two'], // ключ - массив строк
-    () => Promise.resolve('foo'),
-    { enabledAutoFetch: true }
-);
+import { when } from 'mobx';
 
-mobxQuery.invalidate(['key two']); // query будет инвалидирован
-mobxQuery.invalidate(['key one']); // query будет инвалидирован
+const docListQuery = docsFetcher.infiniteQueries.docList.create({ search: 'test' });
+
+await docListQuery.async(); // запрос на получение первых 30 записей
+
+docListQuery.data.length; // 30 записей
+
+docListQuery.fetchMore(); // запрос на получение следующих 30 записей
+
+// ждем загрузки
+await when(() => !query.isLoading);
+
+docListQuery.data.length; // 19 записей. Последняя страница содержит 9 записей, а не 30, как было запрошено, значит больше данных нет
+
+docListQuery.isEndReached; // true
 ```
-Но, стоит учитывать, что ключом является цельный элемент массива, а не составляющие элемента
+
+Флаг `isEndReached` устанавливается в `true`, когда количество полученных элементов меньше запрошенного количества, что означает отсутствие дополнительных данных на сервере.
+
+### Изменение количества запрашиваемых записей
+
+Для изменения конфигурации InfiniteQuery необходимо использовать метод `createWithConfig`:
 ```ts
-const query = mobxQuery.createQuery(
-    [['key one', 'key two']], // ключ - двумерный массив строк
-    () => Promise.resolve('foo'),
-    { enabledAutoFetch: true }
+const docListQuery = docsFetcher.infiniteQueries.docList.createWithConfig(
+  { incrementCount: 10, enabledAutoFetch: true },
+  { search: 'test' },
 );
+```
 
-mobxQuery.invalidate(['key one']); // ключ не совпадает, query НЕ будет инвалидирован
+[Интерфейс `InfiniteQueryConfig`](#интерфейс-infinitequeryconfig).
+
+## MutationSet
+
+[`Mutation`](#mutation) предназначен для отправки данных на сервер.
+`MutationSet` - набор mutations, изменяющих одну и ту же сущность. Предоставляет интерфейс, идентичный `QuerySet`, для консистенстности api.
+
+### Создание и использование MutationSet
+
+В примере ниже будет создан `editDoc` mutation, который отправляет данные на сервер для редактирования документа:
+```ts
+const docsFetcher = {
+  mutations: {
+    editDoc: mobxQuery.createMutationSet((params: DocsEndpointsDTO.EditDocInput) => docsEndpoint.editDoc(params)),
+  },
+};
+
+const editDocMutation = docsFetcher.mutations.editDoc.create();
+
+// params являются параметрами, указанными при определении mutation - DocsEndpointsDTO.EditDocInput
+await editDocMutation.async({ params: { id: 'docID', name: 'test' } });
 ```
 
-- Инвалидация будет происходить только для query, поле `data` которых считывается в данный момент. Для query, `data` которых будут отрендерены позже, запрос произойдет только в момент использования. Для превентивного обновления данных потребуется последовательное использование `sync/async` методов сразу после `invalidate`.
+Метод `create` вернет [объект mutation](#интерфейс-mutation), который содержит всю информацию по запросу и методы работы с запросом.
 
-### Массовая инвалидация
-Для инвалидации всех query необходимо использовать метод `invalidateQueries`
+### Синхронный вызов mutation
+
+Метод `sync` позволяет синхронно запустить запрос:
 ```ts
-mobxQuery.invalidateQueries();
+const editDocMutation = docsFetcher.mutations.editDoc.create();
+
+// есть callbacks на обработку success и error
+editDocMutation.sync({
+  params: { id: 'docID', name: 'test' },
+  onSuccess: (data) => {
+    console.log(data);
+  },
+  onError: (error) => {
+    console.log(error);
+  },
+});
+
+// true
+editDocMutation.isLoading;
 ```
 
-# Ручная установка данных в кэш
+### Асинхронный вызов mutation
 
-Для установки данных, без исполнения executor, используйте метод `forceUpdate`. При вызове все статусные флаги устанавливаются как success состояние
+Метод `async` позволяет асинхронно запустить запрос:
+```ts
+const editDocMutation = docsFetcher.mutations.editDoc.create();
 
+await editDocMutation.async({ params: { id: 'docID', name: 'test' } });
+```
+
+## Кэширование QuerySet и InfiniteQuerySet
+
+`QuerySet` и `InfiniteQuerySet` позволяет закэшировать данные, которые были получены ранее.
+
+### FetchPolicy
+
+`FetchPolicy` определяет политику получения данных.
+
+Существует два типа политики:
+- `cache-first` - если в кэше есть данные, они будут возвращены, если нет, то данные будут получены из сети, после чего ответ будет записан в кэш
+- `network-only` - данные всегда берутся из сети, при этом ответ записывается в кэш
+
+#### Глобальная установка fetchPolicy
+
+Для глобальной установки конкретной политики fetchPolicy необходимо передать параметр `fetchPolicy` при создании `MobxQuery`:
 ```ts
-query.forceUpdate('foo');
+import { MobxQuery } from 'mobx-query';
+
+export const createQuery = () => new MobxQuery({ fetchPolicy: 'cache-first' });
 ```
 
-# InfiniteQuery
-Существует необходимость постепенного запроса массивов данных, в постраничном режиме. Типичный пример, инфинити скролл, когда новая пачка данных запрашивается, в момент когда пользователь докрутил список до конца.
-Для удобства, мы создали специальный `query`, который содержит дополнительный метод `fetchMore` и при вызове оного, происходит запрос с увеличенными счетчиками. Данные ответа на этот запрос, будут сконкатенированы с уже имеющимся. В случае, если количество данных меньше, чем длина страницы, будет считаться что мы дошли до конца списка.
-В `executor` будет передан объект с `offset` - количество элементов отступа от начала списка, и `count` - количество элементов на одну страницу.
+#### Локальная установка fetchPolicy
 
-Значение `count` и увеличение `offset` регулируется опциональным параметром `incrementCount` при создании `query`. По умолчанию равен `30`.
+Для каждого отдельного query можно установить свою fetchPolicy при инициализации.
 
+Пример для `Query`:
 ```ts
-import { when } from 'mobx';
+const docQuery = docsFetcher.queries.doc.createWithConfig(({ fetchPolicy: 'network-only' }, 'docID');
+```
 
-const query = mobxQuery.createInfiniteQuery(
-    ['some cache key'],
-    ({ offset, count }) => {
-        // можно использовать "offset/count" для необходимых преобразований и последующего запроса к api
-        return Promise.resolve(['foo'])
-    },
-    {
-        incrementCount: 30, // опционально, по умолчанию 30
-    }
+Пример для `InfiniteQuery`:
+```ts
+const docListQuery = docsFetcher.infiniteQueries.docList.createWithConfig(
+  { incrementCount: 10, fetchPolicy: 'network-only' },
+  { search: 'test' },
 );
+```
 
-await query.async();
+#### Принцип работы fetchPolicy
 
-console.log(query.data); // ['foo'] 
+`cache-first`:
+```ts
+const docQuery = docsFetcher.queries.doc.createWithConfig(({ fetchPolicy: 'cache-first' }, 'docID');
 
-query.fetchMore();
-await when(() => !query.isLoading); // ждем фоновой загрузки
+await docQuery.async(); // запрос будет выполнен потому что до этого запроса с такими параметрами не было
 
-console.log(query.data); // ['foo', 'foo'] 
-``` 
-## isEndReached
-Для определения того, что мы все таки достигли конца списка, присутствует флаг `isEndReached`.
+await docQuery.async(); // запрос не будет выполнен потому что данные уже есть в кэше. Promise будет завершен сразу
+```
 
+`network-only`:
 ```ts
-const query = mobxQuery.createInfiniteQuery(
-    ['some cache key'],
-    () => Promise.resolve([]),
-);
+const docQuery = docsFetcher.queries.doc.createWithConfig(({ fetchPolicy: 'network-only' }, 'docID');
+
+await docQuery.async(); // запрос будет выполнен
+await docQuery.async(); // запрос будет выполнен
 
-await query.async();
+const docQueryWithCache = docsFetcher.queries.doc.createWithConfig(({ fetchPolicy: 'cache-first' }, 'docID');
+
+await docQueryWithCache.async(); // запрос не будет выполнен потому что прежде данные были получены с политикой `network-only` и записаны в кэш
+```
 
-console.log(query.isEndReached); // true
-``` 
+### Как работает кэш
 
-**[Пример в sandbox](https://codesandbox.io/s/mobx-query-infinityquery-sdcc6g)**
+Все данные, возвращаемые `QuerySet` и `InfiniteQuerySet`, кэшируются в едином хранилище @astral/mobx-query.
 
-# Mutation
-Для изменения данных необходимо использовать mutation. Ответы Mutation не кэшируются.
+При первом вызове `create` в хранилище создается запись с ключем, состоящим из:
+- Хэш от функции конфигурации
+- `queryParams`
 
+Пример:
 ```ts
-const mutation = mobxQuery.createMutation(
-    (params) => {
-        console.log(params); // при необходмости, можем использовать опциональные параметры
-        return Promise.resolve('foo');
-    },
-);
+const docFetcher = {
+  queries: {
+    doc: mobxQuery.createQuerySet((id: string, filters: { search: string }) => ({
+      execute: () => docsEndpoint.getDoc(id, filters),
+    })),
+  },
+};
+
+// ключ кэша будет равен "12fj1d,doc,1,"{"search":"test"}""
+// 12fj1d - это хэш от функции конфигурации
+const docQuery = docFetcher.queries.doc.create('1', { search: 'test' });
+// ключ кэша будет равен "12fj1d,doc,2,"{"search":"test2"}""
+const docQuery = docsFetcher.queries.doc.create('1', { search: 'test2' });
 ```
-**[Пример в sandbox](https://codesandbox.io/s/mobx-query-mutation-p2pnct)**
 
-## async вариация
+#### Автоматическая чистка кэша
+
+Mobx-query кэш организован через `WeekRef`, поэтому не используемые данные автоматически удаляются сборщиком мусора.
+
+### Инвалидация кэша QuerySet и InfiniteQuerySet
+
+Если данные в query стали неактуальными, то необходимо вызвать метод `invalidate`:
 ```ts
-mutation
-    .async('bar') // тут, по нашему примеру, увидим консоль 'bar'
-    .then((data) => {
-        console.log(data) // а тут уже 'foo'
-    }); 
+// инвалидация всех query с именем `doc`
+docsFetcher.queries.doc.invalidate();
 ```
 
-## sync вариация
+После вызова `invalidate` данные в кэше будут помечены как невалидные и при следующем обращении к query будет выполнен запрос на сервер. Если при вызове метода `invalidate` на изменения `.data` подписан любой store, то произойдет моментальный перезапрос активных query:
+
 ```ts
-mutation.sync({
-    params: 'bar',    
-    onSuccess: (data) => {
-        console.log(data) // а тут уже 'foo'
-    }
-}); // тут, по нашему примеру, увидим консоль 'bar'
+const docQuery = docsFetcher.queries.doc.create('docID');
+
+await docQuery.async(); // данные записаны в кэш
+
+docsFetcher.queries.doc.invalidate();
+
+docQuery.data; // триггер запроса данных потому что они были помечены как невалидные
+docQuery.isLoading; // true
 ```
 
-# fetchPolicy
+#### Инвалидация всех query по их имени
 
+Для инвалидации всех query по их имени можно вызвать метод `invalidate`:
 ```ts
-const cacheFirstQuery = mobxQuery.createQuery(
-    ['cache-first key'],
-    () => {
-        console.log('cache-first request');
-        return Promise.resolve('foo');
-    },
-    {
-        fetchPolicy: 'cache-first',
-    }
-);
+const docQuery1 = docsFetcher.queries.doc.create('1');
+const docQuery2 = docsFetcher.queries.doc.create('2');
 
-const networkOnlyQuery = mobxQuery.createQuery(
-    ['network-only key'],
-    () => {
-        console.log('network-only request');
-        return Promise.resolve('bar');
-    },
-    {
-        fetchPolicy: 'network-only',
-    }
-);
+docsFetcher.queries.doc.invalidate(); // данные docQuery1 и docQuery2 помечены как невалидные
+```
 
-await cacheFirstQuery.async(); // увидим консоль 'cache-first request'
-await networkOnlyQuery.async(); // увидим консоль 'network-only request'
+#### Инвалидация query по частичному совпадению параметров
 
-await cacheFirstQuery.async(); // вызова executor не произойдет, и консоль не выведется
-await networkOnlyQuery.async(); // вновь увидим консоль 'network-only request'
+Если необходимо инвалидировать данные по конкретным параметрам, то их необходимо передать в метод `invalidate`:
+```ts
+const docsFetcher = {
+  queries: {
+    doc: mobxQuery.createQuerySet((id: string) => ({
+      execute: () => docsEndpoint.getDoc(id).then(({ data }) => data),
+    })),
+  },
+};
+
+docsFetcher.queries.doc.invalidate('1'); // документ с id = 1 будет помечен как невалидный
+```
 
-const duplicateCacheFirstQuery = mobxQuery.createQuery(
-        ['cache-first key'], // использован тот же самый ключ, что и для cacheFirstQuery
-        () => {
-          console.log('duplicate cache-first request');
-          return Promise.resolve('foo');
-        }
-);
+Параметры `invalidate` полностью совпадают с параметрами, описанными при определении query:
 
-await duplicateCacheFirstQuery.async(); // вызова executor не произойдет, и консоль не выведется
+```ts
+const docsFetcher = {
+  queries: {
+    doc: mobxQuery.createQuerySet((id: string, search: string, filters: Filters) => ({
+      execute: () => docsEndpoint.getDoc(id, search, filters),
+    })),
+  },
+};
+
+docsFetcher.queries.doc.invalidate('1', 'test', { sort: 'asc' });
 ```
-**[Пример в sandbox](https://codesandbox.io/s/mobx-query-fetchpolicy-wvh8jl)**
-
-# Вспомогательные флаги и поля
-`Query`, `InfiniteQuery` и `Mutation` имеют одинаковый набор вспомогательных флагов и полей, работающих по единому принципу.
 
-## isLoading
-Boolean флаг, указывающий на процесс выполнения запроса
-## isSuccess
-Boolean флаг, указывающий на успешное выполнение запроса
-## isError
-Boolean флаг, указывающий на провалившийся запрос
-## isIdle
-Boolean флаг, указывающий на простаивание query, первый же вызов запроса переключит его в false
-## error
-Поле, содержащее информацию о последней ошибке
+#### Инвалидация query по частичному совпадению параметра-объекта
 
 ```ts
-const query = mobxQuery.createQuery(
-    ['some cache key'],
-    () => Promise.reject('foo'),
-);
+const docsFetcher = {
+  queries: {
+    doc: mobxQuery.createQuerySet((id: string, filters: { sort: string; search: string }) => ({
+      execute: () => docsEndpoint.getDoc(id, filters),
+    })),
+  },
+};
+
+const query1 = docsFetcher.queries.doc.create('1', { sort: 'asc', search: 'test' });
+const query2 = docsFetcher.queries.doc.create('1', { sort: 'desc', search: 'test' });
+
+docsFetcher.queries.doc.invalidate('1', { sort: 'asc' }); // данные только query1 будут помечены как невалидные
+```
 
-await query
-    .async()
-    .catch((e) => {
-        console.log(e); // 'foo'
-    });
+### Кастомная установка ключей кэширования
+
+При определении `QuerySet` и `InfiniteQuerySet` можно указать параметр `keys` и `name`, которые будут использоваться для формирования ключей кэша.
+- `name` - название набора. Будет использоваться вместо хэша от функции конфигурации
+- `keys` - будут использоваться вместо параметров функции конфигурации
 
-console.log(query.isError); // 'true'
-console.log(query.error); // 'foo'
+```ts
+const docsFetcher = {
+  queries: {
+    doc: mobxQuery.createQuerySet(
+      (id: string, search: string) => ({
+        keys: [id],
+        execute: () => docsEndpoint.getDoc(id, search),
+      }),
+      { name: 'doc' }
+    ),
+  },
+};
+
+// ключ кэша будет равен "doc,1"
+const query = docsFetcher.queries.doc.create('1', 'test');
+
+docsFetcher.queries.doc.invalidate('1'); // данные query будут помечены как невалидные
+docsFetcher.queries.doc.invalidate('1', 'test'); // второй параметр будет проигнорирован
 ```
 
-## Режим фонового обновления
-`Query` и `InfiniteQuery` имеют режим фонового обновления. Предполагается, что будет хорошо подходить для обновления данных через websocket.
+## Фоновая загрузка данных QuerySet и InfiniteQuerySet
 
-В этом режиме, основные статусные флаги `isSuccess`, `isLoading`, `isError`, `error` будут изменяться до первого успешного запроса. Последующие запросы уже будут изменять статусные флаги под полем `background`
+Для фонового обновления данных возможно использовать флаг `isBackground` для query и infiniteQuery.
+Данный метод хорошо подходит для инвалидации данных по событиям из WebSocket.
 
+Пример для `QuerySet`:
 ```ts
-const query = mobxQuery.createQuery(
-    ['some cache key'],
-    () => Promise.resolve('foo'),
-    { isBackground: true }
-);
+const docQuery = docsFetcher.queries.doc.createWithConfig(({ isBackground: true }, 'docID');
+
+docQuery.sync(); // запрос будет выполнен в фоновом режиме
 
-await query.async();
-console.log(query.isLoading); // переключался в true на момент запроса
-console.log(query.isSuccess); // true
+docQuery.isLoading; // true. Первый запрос изменит статусные флаги
 
-query.invalidate();
-await query.async();
-console.log(query.isLoading); // не изменялся
-console.log(query.isSuccess); // остался неизменным - true
+await when(() => docQuery.isSuccess);
 
-console.log(query.background.isLoading); // переключался в true на момент обновления
-console.log(query.background.isSuccess); // true
+docsFetcher.queries.doc.invalidate();
+
+docQuery.isLoading; // false. При этом запрос данных уже выполняется в фоновом режиме, если где-то есть подписчик на изменения `.data`
+docQuery.background.isLoading; // true
+```
+
+## Изменение кэша QuerySet и InfiniteQuerySet
+
+Для изменения данных в кэше необходимо использовать `forceUpdate`, содержащийся в query:
+```ts
+const docQuery = docsFetcher.queries.doc.create('docID');
+
+// в кэше будет записано "{ name: 'test' }", а статустные флаги перейдут в состояние 'success'
+docQuery.forceUpdate({ name: 'test' });
 ```
 
-# Тестирование
+## Тестирование Fetcher на сонове QuerySet и InfiniteQuerySet.
+
+Для мокинга QuerySet и InfiniteQuerySet необходимо использовать mock следующего вида:
+```ts
+type Fetcher = {
+  queries: QuerySet<any[], any>;
+  infiniteQueries: InfiniteQuerySet<any[], any>;
+  mutations: MutationSet<any[], any>;
+};
+
+const mockFetcher = <TFetcher extends Fetcher>(config: DeepPartial<TFetcher>) => config as TFetcher;
+```
 
-## Тестирование при включенном ```enabledAutoFetch```
+**Не используйте 'vitest-mock-extended' для мокинга Fetcher.**
+Причина: `vitest-mock-extended` оборачивает объект в Proxy, что нарушает работу Mobx.
 
-### Исходный код
+### Тестирование с включенным ```enabledAutoFetch```
 
 ```MobxQuery``` инициализируется с параметром: ```enabledAutoFetch```:
 ```ts
-const createMobxQuery = () => new MobxQuery<ApiDataError>({
+const createMobxQuery = () => new MobxQuery({
   enabledAutoFetch: true,
 });
 ```
 
-```BookRepository``` - фасад для работы с данными, который использует MobxQuery:
+```booksFetcher.ts```
 ```ts
-export class BookRepository {
-  constructor(private readonly mobxQuery: MobxQuery) {}
-
-  public getBookListQuery = (params: BookRepositoryDTO.BookListInputDTO) =>
-    this.mobxQuery.createQuery<BookRepositoryDTO.BookListDTO>(
-      ['book-list', params],
-      () =>
-          apiHttpClient.get('/books', {
-              params,
-          }),
-    );
-}
+export const booksFetcher = {
+  queries: {
+    bookList: mobxQuery.createQuerySet((params: BooksEndpointsDTO.BookListInput) => ({
+      execute: () => booksEndpoint.getBookList(params),
+    })),
+  },
+};
+
+export type BooksFetcher = typeof booksFetcher;
 ```
 
-```BooksListStore``` - использует BookRepository для получения данных:
+```BooksListStore``` - использует `BooksFetcher` для получения данных:
 ```ts
 class BooksListStore {
   public sort?: SortData;
 
-  constructor(private readonly bookRepository: BookRepository) {
+  constructor(private readonly _booksFetcher: BooksFetcher) {
     makeAutoObservable(this);
   }
 
   private get listQuery() {
-    return this.bookRepository.getBookListQuery(this.sort);
+    return this._booksFetcher.queries.bookList.create(this.sort);
   }
 
   public get list(): ListItem[] {
-    const data = this.listQuery.data?.data || [];
+    const data = this.listQuery.data || [];
 
     return data.map(({ id, name, price }) => ({
       id,
@@ -421,34 +711,36 @@ class BooksListStore {
 }
 ```
 
-### Тест
+Тест ```BooksListStore```:
 
 ```ts
 import { when } from 'mobx';
+import { mockCacheGroups } from '@astral/mobx-query-vitest-mock';
 
 describe('BooksListStore', () => {
   it('Список книг форматируется для отображения', async () => {
     // Для каждого теста необходимо инициализировать свой instance MobxQuery,
-    // иначе будет проблема состояния гонки при выполнении нескольких тестов
+    // в противном случае каждый тест будет модифицировать кэш
     const mobxQuery = createMobxQuery();
 
     const fakeBookList = makeFakeBookList(2, { price: 1000 });
     const fakeBookListItem = fakeBookList.data[0];
 
-    const bookRepositoryMock = mock<BookRepository>({
-      // Подменяем реализацию метода для того, чтобы получить ожидаемый результат
-      getBookListQuery: () =>
-          // Создаем моковый Query, соответствующий интерфейсу BookRepository
-          mobxQuery.createQuery(['id'], async () => fakeBookList),
+   const booksFetcherMock = mockFetcher<BooksFetcher>({
+      queries: {
+        bookList: () => mobxQuery.createQuerySet(() => ({
+          execute: async () => fakeBookList,
+        })),
+      },
     });
 
-    const sut = new GoodsListStore(bookRepositoryMock);
+    const sut = new BooksListStore(booksFetcherMock);
 
     // Ждем автоматической загрузки данных
     // Загрузка данных начнется автоматически при обращении к sut.list за счет параметра enabledAutoFetch
     await when(() => Boolean(sut.list?.length));
 
-    expect(sut.list[0]).toMatchObject({
+    expect(sut.list[0]).toEqual({
       id: fakeBookListItem.id,
       name: fakeBookListItem.name,
       price: '1 000 руб.',
@@ -457,3 +749,472 @@ describe('BooksListStore', () => {
 });
 ```
 
+## Core
+
+Концепции, описанные ниже являются ядром библиотеки и используются внутри `QuerySet`, `InfiniteQuerySet` и `MutationSet`.
+
+### Query
+
+`Query` позволяет получать данные из API и кешировать их. Query не должны производить изменения.
+
+#### Создание Query
+
+В примере ниже будет создан doc query, который будет получать данные по id документа. После успешного выполнения запроса данные будут закэшированы.
+
+```ts
+const createDocQuery = (id: string) => 
+  // первый параметр - ключи, по которому в кэше будет храниться ответ запроса
+  cacheService.createQuery(['doc', id], 
+    (params: { id: string }) => docsEndpoint.getDoc(params.id)
+  ); 
+```
+
+#### Использование Query
+
+```ts
+const createDocQuery = (id: string) => 
+  // первый параметр - ключи, по которому в кэше будет храниться ответ запроса
+  cacheService.createQuery(['doc', id], 
+    (params: { id: string }) => docsEndpoint.getDoc(params.id)
+  ); 
+
+const docQuery = createDocQuery('docID');
+```
+
+`docQuery` является объектом, который содержит всю информацию по запросу и методы работы с запросом:
+
+#### Interface Query
+
+```ts
+export type Query<TResult = unknown, TError = unknown, TIsBackground = boolean> = {
+  /**
+   * Текущие данные запроса
+   */
+  data: TResult | undefined;
+
+  /**
+   * Флаг загрузки
+   */
+  isLoading: boolean;
+
+  /**
+   * Флаг успешного выполнения запроса
+   */
+  isSuccess: boolean;
+
+  /**
+   * Флаг наличия ошибки
+   */
+  isError: boolean;
+
+  /**
+   * Текущая ошибка
+   */
+  error: TError | null;
+
+  /**
+   * Флаг, обозначающий простаивание, т.е. запроса еще не было
+   */
+  isIdle: boolean;
+
+  /**
+   * Синхронизирует данные с сервером
+   * @param onSuccess - Callback успешного выполнения
+   * @param onError - Callback ошибки
+   */
+  sync: ({ onSuccess, onError }: SyncParams<TResult, TError>) => void;
+
+  /**
+   * Асинхронный метод получения данных
+   */
+  async: () => Promise<TResult>;
+
+  /**
+   * Метод инвалидации текущего query
+   */
+  invalidate: () => void;
+
+  // Статусы, изменяющиеся после первого успешного запроса в режиме фоновой загрузки isBackground: true
+  background: {
+    /**
+     * Флаг обозначающий загрузку данных в фоновом режиме
+     */
+    isLoading: boolean;
+
+    /**
+     * Флаг обозначающий, что последний запрос был зафейлен в фоновом режиме
+     */
+    isError: boolean;
+
+    /**
+     * Данные о последней ошибке в фоновом режиме
+     */
+    error?: TError;
+
+    /**
+     * Флаг, обозначающий успешность завершения последнего запроса в фоновом режиме
+     */
+    isSuccess: boolean;
+  };
+};
+```
+
+#### Синхронный вызов запроса данных
+
+Метод `sync` позволяет синхронно запустить запрос на получение данных:
+```ts
+const createDocQuery = (id: string) => 
+  // первый параметр - ключи, по которому в кэше будет храниться ответ запроса
+  cacheService.createQuery(['doc', id], 
+    (params: { id: string }) => docsEndpoint.getDoc(params.id)
+  ); 
+
+const docQuery = createDocQuery('docID');
+
+// есть callbacks на обработку success и error
+docQuery.sync({
+  onSuccess: (data) => {
+    console.log(data);
+  },
+  onError: (error) => {
+    console.log(error);
+  },
+});
+
+// true
+docQuery.isLoading;
+```
+
+#### Асинхронный вызов запроса данных
+
+Метод `async` позволяет асинхронно запустить запрос на получение данных:
+```ts
+const createDocQuery = (id: string) => 
+  // первый параметр - ключи, по которому в кэше будет храниться ответ запроса
+  cacheService.createQuery(['doc', id], 
+    (params: { id: string }) => docsEndpoint.getDoc(params.id)
+  ); 
+
+const docQuery = createDocQuery('docID');
+
+// передавать параметры запроса не нужно потому что они уже были переданы при вызове init
+const response = await docQuery.async();
+
+docQuery.isSuccess; // true
+docQuery.data; // идентичен response
+```
+
+#### Автоматический запрос данных
+
+Если MobxQuery был создан с флагом `enableAutoFetch: true`, то данные будут автоматически запрошены при обращении к полю `data`:
+```ts
+const cacheService = new MobxQuery({ enableAutoFetch: true });
+
+const createDocQuery = (id: string) => 
+  // первый параметр - ключи, по которому в кэше будет храниться ответ запроса
+  cacheService.createQuery(['doc', id], 
+    (params: { id: string }) => docsEndpoint.getDoc(params.id)
+  ); 
+
+docQuery.data; // триггер запроса данных
+
+docQuery.isLoading; // true
+```
+
+Если MobxQuery был создан с флагом `enableAutoFetch: false`, то автоматически запрос данных можно включить для текущего query:
+```ts
+const createDocQuery = (id: string) => 
+  cacheService.createQuery(['doc', id], 
+    (params: { id: string }) => docsEndpoint.getDoc(params.id),
+    { enableAutoFetch: true }
+  ); 
+
+docQuery.data; // триггер запроса данных
+
+docQuery.isLoading; // true
+```
+
+### InfiniteQuery
+
+`InfiniteQuery` предназначен для получения бесконечного списка данных.
+
+### Создание InfiniteQuery
+
+В примере ниже будет создан docList InfiniteQuery. После успешного выполнения запроса данные будут закэшированы.
+
+```ts
+const createDocListInfiniteQuery = (filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>) => 
+  cacheService.createInfiniteQuery(['docList', filters], 
+    (params: { offset: number; count: number }) => docsEndpoint.getDocList({ offset: params.offset, count: params.count, ...filters })
+  );
+```
+
+#### Использование InfiniteQuery
+
+```ts
+const createDocListInfiniteQuery = (filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>) => 
+  cacheService.createInfiniteQuery(['docList', filters], 
+    (params: { offset: number; count: number }) => docsEndpoint.getDocList({ offset: params.offset, count: params.count, ...filters })
+  );
+
+// первым параметром create является - filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>
+const docListQuery = createDocListInfiniteQuery({ search: 'test' });
+```
+
+#### Загрузка данных
+
+```ts
+import { when } from 'mobx';
+
+const createDocListInfiniteQuery = (filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>) => 
+  cacheService.createInfiniteQuery(['docList', filters], 
+    (params: { offset: number; count: number }) => docsEndpoint.getDocList({ offset: params.offset, count: params.count, ...filters })
+  );
+
+const docListQuery = createDocListInfiniteQuery({ search: 'test' });
+
+await docListQuery.async(); // запрос на получение первых 30 записей
+
+docListQuery.data.length; // 30 записей
+
+docListQuery.fetchMore(); // запрос на получение следующих 30 записей
+
+// ждем загрузки
+await when(() => !query.isLoading);
+
+docListQuery.data.length; // 60 записей
+```
+
+#### `isEndReached`. Определение конца списка
+
+Флаг `isEndReached` будет установлен в `true`, если записи для загрузки закончились:
+```ts
+import { when } from 'mobx';
+
+const createDocListInfiniteQuery = (filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>) => 
+  cacheService.createInfiniteQuery(['docList', filters], 
+    (params: { offset: number; count: number }) => docsEndpoint.getDocList({ offset: params.offset, count: params.count, ...filters })
+  );
+
+const docListQuery = createDocListInfiniteQuery({ search: 'test' });
+
+await docListQuery.async(); // запрос на получение первых 30 записей
+
+docListQuery.data.length; // 30 записей
+
+docListQuery.fetchMore(); // запрос на получение следующих 30 записей
+
+// ждем загрузки
+await when(() => !query.isLoading);
+
+docListQuery.data.length; // 19 записей. Последняя страница содержит 9 записей, а не 30, как было запрошено, значит больше данных нет
+
+docListQuery.isEndReached; // true
+```
+
+Флаг `isEndReached` устанавливается в `true`, когда количество полученных элементов меньше запрошенного количества, что означает отсутствие дополнительных данных на сервере.
+
+#### Изменение количества запрашиваемых записей
+
+Для изменения конфигурации InfiniteQuery необходимо использовать третий параметр `config`:
+```ts
+const createDocListInfiniteQuery = (filters: Omit<DocsEndpointsDTO.DocListFilters, 'offset' | 'count'>) => 
+  cacheService.createInfiniteQuery(['docList', filters], 
+    (params: { offset: number; count: number }) => docsEndpoint.getDocList({ offset: params.offset, count: params.count, ...filters }),
+    { incrementCount: 10 }
+  );
+```
+
+#### Интерфейс InfiniteQueryConfig
+```ts
+export type InfiniteQueryConfig = {
+  /**
+   * Количество записей, которое будет загружено при первом и следующих запросах
+   * @default 30
+   */
+  incrementCount?: number;
+  /**
+   * Обработчик ошибки
+   */
+  onError?: (error: unknown) => void;
+  /**
+   * Флаг, отвечающий за автоматический запрос данных при обращении к полю data
+   */
+  enabledAutoFetch?: boolean;
+  /**
+   * Политика кэширования данных.
+   */
+  fetchPolicy?: FetchPolicy;
+  /**
+   * Режим фонового обновления
+   * @default false
+   */
+  isBackground?: boolean;
+};
+```
+
+### Mutation
+
+`Mutation` предназначен для отправки данных на сервер с целью произведения изменений.
+
+### Создание и использование mutations
+
+В примере ниже будет создан `editDoc` mutation, который отправляет данные на сервер для редактирования документа:
+```ts
+const createEditDocMutation = (params: DocsEndpointsDTO.EditDocInput) => 
+  cacheService.createMutation((params: DocsEndpointsDTO.EditDocInput) => docsEndpoint.editDoc(params));
+
+const editDocMutation = createEditDocMutation();
+
+// params являются параметрами, указанными при определении mutation - DocsEndpointsDTO.EditDocInput
+await editDocMutation.async({ params: { id: 'docID', name: 'test' } });
+```
+
+#### Интерфейс Mutation
+
+```ts
+type Mutation<TResult, TError = unknown, TExecutorParams = void> = {
+  /**
+   * Синхронный метод выполнения мутации
+   */
+  sync: (options: {
+    onSuccess?: (res: TResult) => void;
+    onError?: (e: TError) => void;
+    params?: TExecutorParams;
+  }) => void;
+
+  /**
+   * Асинхронный метод выполнения мутации
+   */
+  async: (params: TExecutorParams) => Promise<TResult>;
+
+  /**
+   * Флаг загрузки
+   */
+  isLoading: boolean;
+
+  /**
+   * Флаг успешного выполнения запроса
+   */
+  isSuccess: boolean;
+
+  /**
+   * Флаг наличия ошибки
+   */
+  isError: boolean;
+
+  /**
+   * Текущая ошибка
+   */
+  error: TError | null;
+
+  /**
+   * Флаг, обозначающий простаивание, т.е. запроса еще не было
+   */
+  isIdle: boolean;
+
+  // Статусы, изменяющиеся после первого успешного запроса в режиме фоновой загрузки isBackground: true
+  background: {
+    /**
+     * Флаг обозначающий загрузку данных в фоновом режиме
+     */
+    isLoading: boolean;
+
+    /**
+     * Флаг обозначающий, что последний запрос был зафейлен в фоновом режиме
+     */
+    isError: boolean;
+
+    /**
+     * Данные о последней ошибке в фоновом режиме
+     */
+    error?: TError;
+
+    /**
+     * Флаг, обозначающий успешность завершения последнего запроса в фоновом режиме
+     */
+    isSuccess: boolean;
+  };
+};
+```
+
+#### Синхронный вызов mutation
+
+Метод `sync` позволяет синхронно запустить запрос:
+```ts
+const createEditDocMutation = (params: DocsEndpointsDTO.EditDocInput) => 
+  cacheService.createMutation((params: DocsEndpointsDTO.EditDocInput) => docsEndpoint.editDoc(params));
+
+const editDocMutation = createEditDocMutation();
+
+// есть callbacks на обработку success и error
+editDocMutation.sync({
+  params: { id: 'docID', name: 'test' },
+  onSuccess: (data) => {
+    console.log(data);
+  },
+  onError: (error) => {
+    console.log(error);
+  },
+});
+
+// true
+editDocMutation.isLoading;
+```
+
+##### Асинхронный вызов mutation
+
+Метод `async` позволяет асинхронно запустить запрос:
+```ts
+const createEditDocMutation = (params: DocsEndpointsDTO.EditDocInput) => 
+  cacheService.createMutation((params: DocsEndpointsDTO.EditDocInput) => docsEndpoint.editDoc(params));
+
+const editDocMutation = createEditDocMutation();
+
+await editDocMutation.async({ params: { id: 'docID', name: 'test' } });
+```
+
+### Особенности инвалидации Queries
+
+Как при создании query, так и при инвалидации, нужно использовать массив ключей. Предполагается, что query может быть инвалидирован по нескольким ключам.
+
+```ts
+const query = mobxQuery.createQuery(
+  ['key one', 'key two'], // ключ - массив строк
+  () => Promise.resolve('foo'),
+  { enabledAutoFetch: true }
+);
+
+mobxQuery.invalidate(['key two']); // query будет инвалидирован
+mobxQuery.invalidate(['key one']); // query будет инвалидирован
+```
+
+Но, стоит учитывать, что ключом является цельный элемент массива, а не составляющие элемента.
+```ts
+const query = mobxQuery.createQuery(
+  [['key one', 'key two']], // ключ - двумерный массив строк
+  () => Promise.resolve('foo'),
+  { enabledAutoFetch: true }
+);
+
+mobxQuery.invalidate(['key one']); // ключ не совпадает, query НЕ будет инвалидирован
+```
+
+Инвалидация будет происходить только для query, поле data которых считывается в данный момент. Для query, data которых будут отрендерены позже, запрос произойдет только в момент использования. Для превентивного обновления данных потребуется последовательное использование sync/async методов сразу после invalidate.
+
+### Массовая инвалидация
+
+Для инвалидации всех query необходимо использовать метод `invalidateQueries`:
+```ts
+mobxQuery.invalidateQueries();
+```
+
+### Изменение кэша
+
+Для изменения данных в кэше необходимо использовать `forceUpdate`, содержащийся в query:
+```ts
+const query = mobxQuery.createQuery(['key'], () => Promise.resolve('1'));
+
+// в кэше будет записано '2', а статустные флаги перейдут в состояние 'success'
+query.forceUpdate('2');
+```