@astral/mobx-query 1.18.3 → 1.19.1

package/README.md

@@ -10,6 +10,7 @@
 - ⚡️️️️ Фоновая подгрузка данных для работы с WebSocket
 - ⚡️️️️ Возможность тестирования
 
+
 ## Table of contents
 
 - [Installation](#installation)
@@ -25,7 +26,13 @@
     - [Создание InfiniteQuerySet](#создание-infinitequerygroups)
     - [Использование InfiniteQuerySet](#использование-infinitequerygroups)
     - [Загрузка данных](#загрузка-данных)
+    - [Статус дозагрузки fetchMore](#статус-дозагрузки-fetchmore)
+    - [Старт не с начала списка](#старт-не-с-начала-списка)
+    - [Запоминание последней успешной позиции](#запоминание-последней-успешной-позиции)
+    - [Обратная дозагрузка данных](#обратная-дозагрузка-данных)
+    - [Курсорная пагинация](#курсорная-пагинация)
     - [isEndReached. Определение конца списка](#isendreached-определение-конца-списка)
+    - [isStartReached. Определение начала списка](#isstartreached-определение-начала-списка)
     - [Изменение количества запрашиваемых записей](#изменение-количества-запрашиваемых-записей)
   - [MutationSet](#mutationset)
     - [Создание mutations](#создание-и-использование-mutations)
@@ -39,7 +46,7 @@
     - [Кастомная установка ключей кэширования](#кастомная-установка-ключей-кэширования)
   - [Фоновая загрузка данных QuerySet и InfiniteQuerySet](#фоновая-загрузка-данных-queryset-и-infinitequeryset)
   - [Изменение кэша QuerySet и InfiniteQuerySet](#изменение-кэша-queryset-и-infinitequeryset)
-  - [Тестирование QuerySet и InfiniteQuerySet](#тестирование-queryset-и-infinitequeryset)
+  - [Тестирование](#тестирование)
 - [Core](#core)
 
 ## Installation
@@ -340,6 +347,189 @@ await when(() => !query.isLoading);
 docListQuery.data.length; // 60 записей
 ```
 
+#### Статус дозагрузки `fetchMore`
+
+`fetchMoreStatus` содержит отдельные статусы дозагрузки следующей страницы. Это позволяет отдельно отслеживать состояние `fetchMore`, не смешивая его с общим статусом `InfiniteQuery`.
+
+```ts
+import { when } from 'mobx';
+
+const createDocListInfiniteQuery = (filters: Omit<DocsDTO.DocListFilters, 'offset' | 'count'>) => 
+  cacheService.createInfiniteQuery(['docList', filters], 
+    (params: { offset: number; count: number }) => docsEndpoints.getDocList({ offset: params.offset, count: params.count, ...filters })
+  );
+
+const docListQuery = createDocListInfiniteQuery({ search: 'test' });
+
+await docListQuery.async();
+
+docListQuery.fetchMore();
+
+docListQuery.fetchMoreStatus.isLoading; // true
+docListQuery.fetchMoreStatus.isSuccess; // false
+docListQuery.fetchMoreStatus.isError; // false
+
+await when(() => !docListQuery.fetchMoreStatus.isLoading);
+
+docListQuery.fetchMoreStatus.isLoading; // false
+docListQuery.fetchMoreStatus.isSuccess; // true
+docListQuery.fetchMoreStatus.error; // undefined
+```
+
+Если `fetchMore` завершится ошибкой, `fetchMoreStatus.isError` станет `true`, а `fetchMoreStatus.error` будет содержать ошибку. Значение `offset` будет возвращено к предыдущему успешному состоянию, поэтому повторный вызов `fetchMore` повторит запрос той же страницы.
+
+### Старт не с начала списка
+
+Для сценариев восстановления позиции списка можно передать `initialOffset` или `initialCursor`.
+Эти значения используются только для самого первого запроса нового инстанса `InfiniteQuery`.
+После `invalidate()` следующий запрос снова начнется с начала списка.
+
+Это полезно, когда нужно восстановить список с определенной позиции, например после возврата на страницу в SPA или при открытии ссылки, в которой уже закодирована нужная точка входа в список.
+
+#### Offset-пагинация
+
+Если API использует смещение, передайте `initialOffset`.
+
+```ts
+const docListQuery = docsFetcher.infiniteQueries.docList.createWithConfig(
+  {
+    initialOffset: 120,
+  },
+  { search: 'test' },
+);
+
+await docListQuery.async(); // первый запрос будет выполнен с offset=120
+
+docListQuery.invalidate();
+await docListQuery.async(); // после invalidate запрос снова начнется с offset=0
+```
+
+#### Курсорная пагинация
+
+Если API использует курсор, передайте `initialCursor`.
+
+```ts
+const docListQuery = docsFetcher.infiniteQueries.docList.createWithConfig(
+  {
+    initialCursor: { id: 'doc-120' },
+  },
+  { search: 'test' },
+);
+
+await docListQuery.async(); // первый запрос будет выполнен с cursor={ id: 'doc-120' }
+
+docListQuery.invalidate();
+await docListQuery.async(); // после invalidate запрос снова начнется без курсора
+```
+
+### Запоминание последней успешной позиции
+
+```ts
+await docListQuery.async(); // запрос на получение первых 30 записей
+
+docListQuery.fetchMore({
+  onSuccess: ({ offset, cursor }) => {
+    savedOffset = offset; // запоминаем offset последней успешной дозагрузки
+    savedCursor = cursor; // запоминаем cursor последней успешной дозагрузки
+  },
+});
+
+docsFetcher.infiniteQueries.docList.createWithConfig(
+  { search: 'test' },
+  {
+    initialOffset: savedOffset,
+    initialCursor: savedCursor,
+  },
+); // новый инстанс продолжит загрузку с сохраненной позиции
+```
+
+```ts
+const searchParams = new URLSearchParams(window.location.search);
+
+await docListQuery.async();
+
+docListQuery.fetchMore({
+  onSuccess: ({ offset, cursor }) => {
+    searchParams.set('offset', String(offset));
+    searchParams.set('cursorId', cursor.id);
+
+    window.history.replaceState(
+      null,
+      '',
+      `?${searchParams.toString()}`,
+    );
+  },
+});
+
+const restoredQuery = docsFetcher.infiniteQueries.docList.createWithConfig(
+  {
+    initialOffset: Number(searchParams.get('offset') ?? 0),
+    initialCursor: searchParams.get('cursorId')
+      ? { id: searchParams.get('cursorId')! }
+      : undefined,
+  },
+  { search: 'test' },
+);
+```
+
+### Обратная дозагрузка данных
+
+По умолчанию `fetchMore()` загружает следующую страницу и добавляет ее в конец списка.
+Вызов `fetchMore({ direction: 'backward' })` загружает предыдущую страницу и добавляет ее в начало списка.
+
+```ts
+const docListQuery = docsFetcher.infiniteQueries.docList.createWithConfig(
+  { initialOffset: 60 },
+  { search: 'test' },
+);
+
+await docListQuery.async(); // будут загружены записи начиная с offset=60
+
+docListQuery.fetchMore({ direction: 'backward' }); // будет запрошена предыдущая страница
+```
+
+При `fetchMore({ direction: 'backward' })` библиотека уменьшает `offset`, передает в `execute` первый элемент текущего списка как `cursor` и указывает `direction: 'backward'`.
+
+### Курсорная пагинация
+
+```ts
+type Doc = {
+  id: string;
+  title: string;
+};
+
+const docsFetcher = {
+  infiniteQueries: {
+    docList: mobxQuery.createInfiniteQuerySet(
+      (filters: Omit<DocsDTO.DocListFilters, 'count'>) => ({
+        execute: ({ count, cursor, direction }) =>
+          docsEndpoint
+            .getDocList({
+              count,
+              cursorId: cursor?.id,
+              direction,
+              ...filters,
+            })
+            .then(({ data }) => data.list as Doc[]),
+      }),
+    ),
+  },
+};
+
+const docListQuery = docsFetcher.infiniteQueries.docList.createWithConfig(
+  { initialCursor: { id: 'doc-120' } },
+  { search: 'test' },
+);
+
+await docListQuery.async(); // при первом запросе execute получит initialCursor, если он задан
+
+docListQuery.fetchMore(); // execute получит последний элемент списка и direction: 'forward'
+
+docListQuery.fetchMore({ direction: 'backward' }); // execute получит первый элемент списка и direction: 'backward'
+```
+
+Во всех остальных запросах `cursor` будет `undefined`, включая первый запрос без `initialCursor` и повторный запрос после `invalidate()`.
+
 ### `isEndReached`. Определение конца списка
 
 Флаг `isEndReached` будет установлен в `true`, если записи для загрузки закончились:
@@ -364,6 +554,11 @@ docListQuery.isEndReached; // true
 
 Флаг `isEndReached` устанавливается в `true`, когда количество полученных элементов меньше запрошенного количества, что означает отсутствие дополнительных данных на сервере.
 
+### `isStartReached`. Определение начала списка
+
+Флаг `isStartReached` будет установлен в `true`, если при `fetchMore({ direction: 'backward' })` сервер вернул меньше элементов, чем было запрошено.
+Это означает, что более ранних данных больше нет, и повторные вызовы `fetchMore({ direction: 'backward' })` не будут запускать новые запросы.
+
 ### Изменение количества запрашиваемых записей
 
 Для изменения конфигурации InfiniteQuery необходимо использовать метод `createWithConfig`:
@@ -520,6 +715,9 @@ const docQueryWithCache = docsFetcher.queries.doc.createWithConfig(({ fetchPolic
 await docQueryWithCache.async(); // запрос не будет выполнен потому что прежде данные были получены с политикой `network-only` и записаны в кэш
 ```
 
+Для `InfiniteQuery` параметры `initialOffset` и `initialCursor` позволяют при первом запросе нового инстанса начать загрузку с нужной позиции.
+После `invalidate()` эти стартовые значения больше не применяются, и следующий запрос начинается с начала списка.
+
 ### Как работает кэш
 
 Все данные, возвращаемые `QuerySet` и `InfiniteQuerySet`, кэшируются в едином хранилище @astral/mobx-query.
@@ -716,7 +914,30 @@ docsFetcher.queries.document.createWithConfig({
 })
 ```
 
-## Тестирование Fetcher на сонове QuerySet и InfiniteQuerySet.
+## Последовательное получение данных
+
+Для последовательного получения данных используйте флаг `enabledAutoFetch`.
+
+```ts
+  private get fileQuery() {
+    const fileId = this._documentStore.data?.FileId;
+
+    return this._docsFetcher.queries.file.createWithConfig(
+      {
+        enabledAutoFetch: Boolean(fileId),
+      },
+      fileId,
+    );
+  }
+
+  public get file() {
+    return this.fileQuery.data; // пока enabledAutoFetch==false, запроса данных не будет
+  }
+```
+
+## Тестирование
+
+### Реализация `mockFetcher` (один раз в проекте)
 
 Для мокинга QuerySet и InfiniteQuerySet необходимо использовать mock следующего вида:
 ```ts
@@ -729,92 +950,73 @@ type Fetcher = {
 const mockFetcher = <TFetcher extends Fetcher>(config: DeepPartial<TFetcher>) => config as TFetcher;
 ```
 
-**Не используйте 'vitest-mock-extended' для мокинга Fetcher.**
-Причина: `vitest-mock-extended` оборачивает объект в Proxy, что нарушает работу Mobx.
+**Не используйте `vitest-mock-extended` для мокинга Fetcher.**
+Причина: `vitest-mock-extended` нарушает работу Mobx.
 
-### Тестирование с включенным ```enabledAutoFetch```
+### 1 тест - 1 mobx-query instance
 
-```MobxQuery``` инициализируется с параметром: ```enabledAutoFetch```:
 ```ts
-const createMobxQuery = () => new MobxQuery({
-  enabledAutoFetch: true,
-});
+const setup = () => {
+  const mobxQuery = createMobxQuery();
+
+  const booksFetcherMock = mockFetcher<BooksFetcher>({
+    queries: {
+      list: mobxQuery.createQuerySet(...),
+    },
+  });
+}
 ```
 
-```booksFetcher.ts```
+### Mock Query, Mutation
+
+Для определения queries, mutations использовать соответствующие методы mobxQuery:
 ```ts
-export const booksFetcher = {
+const booksFetcherMock = mockFetcher<BooksFetcher>({
   queries: {
-    bookList: mobxQuery.createQuerySet((params: BooksDTO.BookListInput) => ({
-      execute: () => booksEndpoint.getBookList(params),
+    bookList: mobxQuery.createQuerySet((filters) => ({
+      execute: async () => fakeBookList,
     })),
   },
-};
-
-export type BooksFetcher = typeof booksFetcher;
-```
-
-```BooksListStore``` - использует `BooksFetcher` для получения данных:
-```ts
-class BooksListStore {
-  public sort?: SortData;
-
-  constructor(private readonly _booksFetcher: BooksFetcher) {
-    makeAutoObservable(this);
-  }
-
-  private get listQuery() {
-    return this._booksFetcher.queries.bookList.create(this.sort);
+  mutations: {
+    createBook: mobxQuery.createMutation(async (book) => undefined),
   }
+});
+```
 
-  public get list(): ListItem[] {
-    const data = this.listQuery.data || [];
+### Mock InfiniteQuery
 
-    return data.map(({ id, name, price }) => ({
-      id,
-      name,
-      price: formatPriceToView(price),
-    }));
+Для определения `InfiniteQueries` использовать `createInfiniteQuerySet`:
+```ts
+const booksFetcherMock = mockFetcher<BooksFetcher>({
+  infiniteQueries: {
+    bookList: mobxQuery.createInfiniteQuerySet(
+      (filters) => ({
+        execute: ({ offset, count }) => fakeBookList,
+      }),
+    ),
   }
-}
+});
 ```
 
-Тест ```BooksListStore```:
+### Ожидание|триггер запроса данных при `enabledAutoFetch` (дефолтное поведение)
 
 ```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 booksFetcherMock = mockFetcher<BooksFetcher>({
-      queries: {
-        bookList: () => mobxQuery.createQuerySet(() => ({
-          execute: async () => fakeBookList,
-        })),
-      },
-    });
 
-    const sut = new BooksListStore(booksFetcherMock);
+const booksFetcherMock = mockFetcher<BooksFetcher>({
+  queries: {
+    bookList: mobxQuery.createQuerySet((filters) => ({
+      execute: async () => fakeBookList,
+    })),
+  },
+});
+
+const sut = new Store(booksFetcherMock);
 
-    // Ждем автоматической загрузки данных
-    // Загрузка данных начнется автоматически при обращении к sut.list за счет параметра enabledAutoFetch
-    await when(() => Boolean(sut.list?.length));
+// Обращаемся к data из query -> триггер запроса данных -> ожидаем когда загрузятся данные
+await when(() => Boolean(sut.data));
 
-    expect(sut.list[0]).toEqual({
-      id: fakeBookListItem.id,
-      name: fakeBookListItem.name,
-      price: '1 000 руб.',
-    });
-  });
-});
+expect(sut.status.isSuccess).toBe(true);
 ```
 
 ## Core
@@ -1037,6 +1239,10 @@ const createDocListInfiniteQuery = (filters: Omit<DocsDTO.DocListFilters, 'offse
 const docListQuery = createDocListInfiniteQuery({ search: 'test' });
 ```
 
+Executor `InfiniteQuery` получает объект `{ offset, count, cursor, direction }`.
+Если нужна только offset-пагинация, можно использовать только `offset` и `count`.
+`cursor` передается только при `fetchMore()` или при самом первом запросе, если задан `initialCursor`. В обычном первом запросе без `initialCursor` и после `invalidate()` значение `cursor` будет `undefined`.
+
 #### Загрузка данных
 
 ```ts
@@ -1061,6 +1267,17 @@ await when(() => !query.isLoading);
 docListQuery.data.length; // 60 записей
 ```
 
+#### Статус дозагрузки `fetchMore`
+
+- [Статус дозагрузки fetchMore](#статус-дозагрузки-fetchmore)
+
+#### Дополнительные возможности
+
+- [Старт не с начала списка](#старт-не-с-начала-списка)
+- [Запоминание последней успешной позиции](#запоминание-последней-успешной-позиции)
+- [Обратная дозагрузка данных](#обратная-дозагрузка-данных)
+- [Курсорная пагинация](#курсорная-пагинация)
+
 #### `isEndReached`. Определение конца списка
 
 Флаг `isEndReached` будет установлен в `true`, если записи для загрузки закончились:
@@ -1090,6 +1307,10 @@ docListQuery.isEndReached; // true
 
 Флаг `isEndReached` устанавливается в `true`, когда количество полученных элементов меньше запрошенного количества, что означает отсутствие дополнительных данных на сервере.
 
+#### `isStartReached`. Определение начала списка
+
+- [isStartReached. Определение начала списка](#isstartreached-определение-начала-списка)
+
 #### Изменение количества запрашиваемых записей
 
 Для изменения конфигурации InfiniteQuery необходимо использовать третий параметр `config`:
@@ -1103,7 +1324,7 @@ const createDocListInfiniteQuery = (filters: Omit<DocsDTO.DocListFilters, 'offse
 
 #### Интерфейс InfiniteQueryConfig
 ```ts
-export type InfiniteQueryConfig = {
+export type InfiniteQueryConfig<TResult = unknown> = {
   /**
    * Количество записей, которое будет загружено при первом и следующих запросах
    * @default 30
@@ -1121,6 +1342,15 @@ export type InfiniteQueryConfig = {
    * Политика кэширования данных.
    */
   fetchPolicy?: FetchPolicy;
+  /**
+   * Стартовое значение offset, от которого требуется сделать самый первый запрос.
+   * @default 0
+   */
+  initialOffset?: number;
+  /**
+   * Стартовый элемент, от которого требуется сделать самый первый запрос.
+   */
+  initialCursor?: Partial<TResult>;
   /**
    * Режим фонового обновления
    * @default false

package/Sets/InfiniteQuerySet/InfiniteQuerySet.d.ts

@@ -7,7 +7,7 @@ export type InfiniteQuerySetConfig = {
 };
 export type InfiniteQuerySetConfigurator<TParams extends any[], TResponse> = (...params: TParams) => {
     keys?: CacheKey[];
-    execute: (infiniteParams: InfiniteParams) => Promise<TResponse[]>;
+    execute: (infiniteParams: InfiniteParams<TResponse>) => Promise<TResponse[]>;
 };
 /**
  * Набор infinite queries под одним ключем с целью повышения читаемости кода и удобства инвалидации по общему ключу

package/StatusStorage/StatusStorage.d.ts

@@ -24,6 +24,10 @@ export declare class StatusStorage<TError> implements Statuses<TError> {
      */
     isSuccess: boolean;
     setStatues: (data: Statuses<TError>) => void;
+    setStartLoading: () => void;
+    setError: (error: TError) => void;
+    setSuccess: () => void;
+    setEndLoading: () => void;
     get statuses(): Statuses<TError>;
 }
 export declare class StatusStorageFactory extends StorageFactory<StatusStorage<any>> {

package/StatusStorage/StatusStorage.js

@@ -24,6 +24,24 @@ export class StatusStorage {
             this.error = data.error;
             this.isSuccess = data.isSuccess;
         };
+        this.setStartLoading = () => {
+            this.isLoading = true;
+            this.isError = false;
+            this.isSuccess = false;
+        };
+        this.setError = (error) => {
+            this.isSuccess = false;
+            this.isError = true;
+            this.error = error;
+        };
+        this.setSuccess = () => {
+            this.error = undefined;
+            this.isError = false;
+            this.isSuccess = true;
+        };
+        this.setEndLoading = () => {
+            this.isLoading = false;
+        };
         makeAutoObservable(this);
     }
     get statuses() {

package/node/AuxiliaryQuery/AuxiliaryQuery.d.ts

@@ -31,22 +31,17 @@ export declare class AuxiliaryQuery<TResult, TError = void> {
      * для устранения гонки запросов
      */
     getUnifiedPromise: (executor: Executor<TResult>, onSuccess?: (data: TResult) => void) => Promise<TResult>;
-    private setSuccess;
     private checkBackgroundAndSet;
     /**
      * Обработчик успешного ответа
      */
     submitSuccess: () => void;
-    private setError;
-    /**
-     * Обработчик ошибки
-     */
-    submitError: (error: TError) => void;
-    private setLoading;
+    private submitError;
     /**
      * Метод, вызываемый в самом начале запроса, чтобы сбросить флаги в соответствующее значение
      */
     startLoading: () => void;
+    private endLoading;
     /**
      * Метод для инвалидации данных
      */

package/node/AuxiliaryQuery/AuxiliaryQuery.js

@@ -41,19 +41,10 @@ class AuxiliaryQuery {
                     });
                     throw e;
                 })
-                    .finally(() => {
-                    this.unifiedPromise = undefined;
-                    (0, mobx_1.runInAction)(() => {
-                        this.statusStorage.isLoading = false;
-                    });
-                });
+                    .finally(this.endLoading);
             }
             return this.unifiedPromise;
         };
-        this.setSuccess = (storage) => {
-            storage.isError = false;
-            storage.isSuccess = true;
-        };
         this.checkBackgroundAndSet = (setStorage) => {
             if (this.backgroundStatusStorage && this.statusStorage.isSuccess) {
                 setStorage(this.backgroundStatusStorage);
@@ -66,32 +57,27 @@ class AuxiliaryQuery {
          * Обработчик успешного ответа
          */
         this.submitSuccess = () => {
-            this.checkBackgroundAndSet(this.setSuccess);
+            this.checkBackgroundAndSet((storage) => storage.setSuccess());
             this.isInvalid = false;
         };
-        this.setError = (storage, error) => {
-            storage.isSuccess = false;
-            storage.isError = true;
-            storage.error = error;
-        };
-        /**
-         * Обработчик ошибки
-         */
         this.submitError = (error) => {
-            this.checkBackgroundAndSet((storage) => this.setError(storage, error));
+            this.checkBackgroundAndSet((storage) => storage.setError(error));
             this.isInvalid = false;
         };
-        this.setLoading = (storage) => {
-            storage.isLoading = true;
-            storage.isError = false;
-            storage.isSuccess = false;
-        };
         /**
          * Метод, вызываемый в самом начале запроса, чтобы сбросить флаги в соответствующее значение
          */
         this.startLoading = () => {
             this.isIdle = false;
-            this.checkBackgroundAndSet(this.setLoading);
+            this.checkBackgroundAndSet((storage) => storage.setStartLoading());
+        };
+        this.endLoading = () => {
+            var _a;
+            this.unifiedPromise = undefined;
+            this.statusStorage.setEndLoading();
+            if (this.statusStorage.isSuccess) {
+                (_a = this.backgroundStatusStorage) === null || _a === void 0 ? void 0 : _a.setEndLoading();
+            }
         };
         /**
          * Метод для инвалидации данных
@@ -104,12 +90,10 @@ class AuxiliaryQuery {
             isIdle: mobx_1.observable,
             isInvalid: mobx_1.observable,
             submitSuccess: mobx_1.action,
-            setSuccess: mobx_1.action,
-            setError: mobx_1.action,
-            setLoading: mobx_1.action,
             submitError: mobx_1.action,
             startLoading: mobx_1.action,
             invalidate: mobx_1.action,
+            endLoading: mobx_1.action,
         });
     }
 }