@astral/mobx-query 1.18.3 → 1.19.0

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)
@@ -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,6 +914,27 @@ docsFetcher.queries.document.createWithConfig({
 })
 ```
 
+## Последовательное получение данных
+
+Для последовательного получения данных используйте флаг `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, запроса данных не будет
+  }
+```
+
 ## Тестирование Fetcher на сонове QuerySet и InfiniteQuerySet.
 
 Для мокинга QuerySet и InfiniteQuerySet необходимо использовать mock следующего вида:
@@ -1037,6 +1256,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 +1284,17 @@ await when(() => !query.isLoading);
 docListQuery.data.length; // 60 записей
 ```
 
+#### Статус дозагрузки `fetchMore`
+
+- [Статус дозагрузки fetchMore](#статус-дозагрузки-fetchmore)
+
+#### Дополнительные возможности
+
+- [Старт не с начала списка](#старт-не-с-начала-списка)
+- [Запоминание последней успешной позиции](#запоминание-последней-успешной-позиции)
+- [Обратная дозагрузка данных](#обратная-дозагрузка-данных)
+- [Курсорная пагинация](#курсорная-пагинация)
+
 #### `isEndReached`. Определение конца списка
 
 Флаг `isEndReached` будет установлен в `true`, если записи для загрузки закончились:
@@ -1090,6 +1324,10 @@ docListQuery.isEndReached; // true
 
 Флаг `isEndReached` устанавливается в `true`, когда количество полученных элементов меньше запрошенного количества, что означает отсутствие дополнительных данных на сервере.
 
+#### `isStartReached`. Определение начала списка
+
+- [isStartReached. Определение начала списка](#isstartreached-определение-начала-списка)
+
 #### Изменение количества запрашиваемых записей
 
 Для изменения конфигурации InfiniteQuery необходимо использовать третий параметр `config`:
@@ -1103,7 +1341,7 @@ const createDocListInfiniteQuery = (filters: Omit<DocsDTO.DocListFilters, 'offse
 
 #### Интерфейс InfiniteQueryConfig
 ```ts
-export type InfiniteQueryConfig = {
+export type InfiniteQueryConfig<TResult = unknown> = {
   /**
    * Количество записей, которое будет загружено при первом и следующих запросах
    * @default 30
@@ -1121,6 +1359,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,
         });
     }
 }

package/node/InfiniteQuery/InfiniteQuery.d.ts

@@ -1,23 +1,61 @@
 import { AuxiliaryQuery } from '../AuxiliaryQuery';
 import { type DataStorage } from '../DataStorage';
 import { QueryContainer } from '../QueryContainer';
-import { type StatusStorage } from '../StatusStorage';
+import { StatusStorage } from '../StatusStorage';
 import { type FetchPolicy, type QueryBaseActions, type Sync, type SyncParams } from '../types';
 export declare const DEFAULT_INFINITE_ITEMS_COUNT = 30;
-export type InfiniteParams = {
+export type FetchMoreDirection = 'forward' | 'backward';
+export type InfiniteFetchMoreOptions<TResult> = {
+    /**
+     * Направление для дозапроса данных
+     * @default 'forward'
+     */
+    direction?: FetchMoreDirection;
+    /**
+     * Колбэк, вызываемый при успешном запросе, подразумевается использование, для запоминания последней успешной позиции
+     */
+    onSuccess?: (params: {
+        offset: number;
+        cursor: TResult;
+    }) => void;
+};
+export type InfiniteParams<TResult> = {
+    /**
+     * Смещение, от которого требуется сделать запрос
+     * @default 0
+     */
     offset: number;
+    /**
+     * Количество запрашиваемых элементов
+     * @default 30
+     */
     count: number;
+    /**
+     * Элемент использующийся в качестве точки отсчета при курсорной пагинации.
+     * При движении вперед (direction: 'forward') это последний элемент текущего набора данных
+     * При движении назад (direction: 'backward') это первый элемент текущего набора данных.
+     * Передается в двух случаях:
+     * - при использовании fetchMore.
+     * - при самом первом запросе, если указан initialCursor.
+     * Во всех остальных запросах, включая первый запрос без initialCursor и повторный запрос после invalidate(), cursor будет undefined.
+     */
+    cursor?: Partial<TResult>;
+    /**
+     * Направление запроса, присутствует только при использовании fetchMore
+     */
+    direction?: FetchMoreDirection;
 };
 export type InfiniteDataStorage<TResult> = DataStorage<{
     data: TResult[];
     offset: number;
     isEndReached: boolean;
+    isStartReached: boolean;
 }>;
 /**
  * Исполнитель запроса, ожидается,
  * что будет использоваться что-то возвращающее массив данных
  */
-export type InfiniteExecutor<TResult> = (params: InfiniteParams) => Promise<TResult[]>;
+export type InfiniteExecutor<TResult> = (params: InfiniteParams<TResult>) => Promise<TResult[]>;
 export type InfiniteQueryParams<TResult, TError, TIsBackground extends boolean = false> = {
     /**
      * Количество запрашиваемых элементов
@@ -54,6 +92,15 @@ export type InfiniteQueryParams<TResult, TError, TIsBackground extends boolean =
      * Колбэк, вызываемый при успешном завершении запроса, подразумевается использование, для подтверждения валидности данных, чтобы квери не был удален из памяти
      */
     submitValidity?: () => void;
+    /**
+     * Стартовое значение offset, от которого требуется сделать самый первый запрос.
+     * @default 0
+     */
+    initialOffset?: number;
+    /**
+     * Стартовый элемент, от которого требуется сделать самый первый запрос
+     */
+    initialCursor?: Partial<TResult>;
 };
 /**
  * Квери для работы с инфинити запросами,
@@ -85,7 +132,20 @@ export declare class InfiniteQuery<TResult, TError = void, TIsBackground extends
      * Колбэк, вызываемый при успешном завершении запроса, подразумевается использование, для подтверждения валидности данных, чтобы квери не был удален из памяти
      */
     private readonly submitValidity?;
-    constructor(executor: InfiniteExecutor<TResult>, { incrementCount, onError, enabledAutoFetch, fetchPolicy, dataStorage, statusStorage, backgroundStatusStorage, submitValidity, }: InfiniteQueryParams<TResult, TError, TIsBackground>);
+    /**
+     * Хранилище статусов для процесса дозапроса данных
+     */
+    private fetchMoreStatusStorage;
+    /**
+     * Стартовый offset для запроса,
+     */
+    private initialOffset;
+    /**
+     * Стартовое значение курсора, от которого должен произойти первый запрос.
+     * Предполагается, что этот элемент должен содержать только id сущности.
+     */
+    private initialCursor?;
+    constructor(executor: InfiniteExecutor<TResult>, { incrementCount, initialOffset, initialCursor, onError, enabledAutoFetch, fetchPolicy, dataStorage, statusStorage, backgroundStatusStorage, submitValidity, }: InfiniteQueryParams<TResult, TError, TIsBackground>);
     private get isNetworkOnly();
     /**
      * Счетчик отступа для инфинити запроса
@@ -99,7 +159,11 @@ export declare class InfiniteQuery<TResult, TError = void, TIsBackground extends
      * Флаг того, что мы достигли предела запрашиваемых элементов
      */
     get isEndReached(): boolean;
-    private calcIsEndReachedByResult;
+    /**
+     * Флаг того, что мы достигли самого начала запрашиваемых элементов
+     */
+    get isStartReached(): boolean;
+    private calcIsLimitReachedByResult;
     /**
      * Форс метод для установки данных
      */
@@ -107,15 +171,18 @@ export declare class InfiniteQuery<TResult, TError = void, TIsBackground extends
     /**
      * Метод для обогащения параметров текущими значениями для инфинити
      */
-    private get infiniteExecutor();
+    private makeInfiniteExecutor;
     /**
      * Метод для инвалидации данных
      */
     invalidate: () => void;
+    private setOffset;
+    get fetchMoreStatus(): import("../StatusStorage").Statuses<TError>;
     /**
      * Метод для запроса следующего набора данных
+     * @param options - параметры дозапроса данных
      */
-    fetchMore: () => void;
+    fetchMore: (options?: InfiniteFetchMoreOptions<TResult>) => void;
     /**
      * Синхронный метод получения данных
      */