@astral/mobx-query 1.4.0 → 1.6.0

package/Mutation/Mutation.js

@@ -1,17 +1,18 @@
-import { makeAutoObservable } from 'mobx';
+import { action, makeObservable } from 'mobx';
 import { AuxiliaryQuery } from '../AuxiliaryQuery';
+import { QueryContainer } from '../QueryContainer';
+import { StatusStorage } from '../StatusStorage';
 /**
- * @description простой стор для запросов, которые не требуют кэширования,
+ * Простой квери для запросов, которые не требуют кэширования,
  * пример - POST запросы
  */
-export class Mutation {
+export class Mutation extends QueryContainer {
     constructor(executor, { onError } = {}) {
+        const statusStorage = new StatusStorage();
+        super(statusStorage, null, new AuxiliaryQuery(statusStorage, null));
+        this.executor = executor;
         /**
-         * @description инстанс вспомогательного стора
-         */
-        this.auxiliary = new AuxiliaryQuery();
-        /**
-         * @description синхронный метод получения/отправки данных
+         * Синхронный метод получения/отправки данных
          */
         this.sync = (options) => {
             const { onSuccess, onError, params } = options || {};
@@ -31,41 +32,13 @@ export class Mutation {
             });
         };
         /**
-         * @description асинхронный метод получения/отправки данных,
+         * Асинхронный метод получения/отправки данных,
          * предполагается, что нужно будет самостоятельно обрабатывать ошибку
          */
         this.async = (params) => {
             return this.auxiliary.getUnifiedPromise(() => this.executor(params));
         };
-        this.executor = executor;
         this.defaultOnError = onError;
-        makeAutoObservable(this);
-    }
-    /**
-     * @description флаг загрузки данных
-     */
-    get isLoading() {
-        return this.auxiliary.isLoading;
-    }
-    /**
-     * @description флаг обозначающий, что последний запрос был зафейлен
-     */
-    get isError() {
-        return this.auxiliary.isError;
-    }
-    /**
-     * @description данные о последней ошибке
-     */
-    get error() {
-        return this.auxiliary.error;
-    }
-    /**
-     * @description флаг обозначающий, что последний запрос был успешно завершен
-     */
-    get isSuccess() {
-        return this.auxiliary.isSuccess;
-    }
-    get isIdle() {
-        return this.auxiliary.isIdle;
+        makeObservable(this, { async: action, sync: action });
     }
 }

package/Query/Query.d.ts

@@ -1,108 +1,103 @@
+import { AuxiliaryQuery } from '../AuxiliaryQuery';
 import type { FetchPolicy, QueryBaseActions, Sync, SyncParams } from '../types';
 import type { DataStorage } from '../DataStorage';
+import { QueryContainer } from '../QueryContainer';
+import { type StatusStorage } from '../StatusStorage';
 /**
- * @description исполнитель запроса
+ * Исполнитель запроса
  */
 export type QueryExecutor<TResult> = () => Promise<TResult>;
-export type QueryParams<TResult, TError> = {
+export type QueryParams<TResult, TError, TIsBackground extends boolean = false> = {
     /**
-     * @description обработчик ошибки, вызываемый по умолчанию
+     * Обработчик ошибки, вызываемый по умолчанию
      */
     onError?: SyncParams<TResult, TError>['onError'];
     /**
-     * @description флаг, отвечающий за автоматический запрос данных при обращении к полю data
+     * Флаг, отвечающий за автоматический запрос данных при обращении к полю data
      */
     enabledAutoFetch?: boolean;
+    /**
+     * Политика получения данных.
+     * @enum cache-first - данные сначала берутся из кеша, если их нет, тогда идет обращение к сети, ответ записывается в кэш
+     * @enum network-only - данные всегда берутся из сети, при этом ответ записывается в кэш
+     */
     fetchPolicy?: FetchPolicy;
     /**
-     * @description инстанс хранилища данных
+     * Инстанс хранилища данных
      */
     dataStorage: DataStorage<TResult>;
-};
-/**
- * @description стор для работы с запросами,
- * которые должны быть закешированы,
- * но им не требуется усложнение в виде работы с фильтрами и инфинити запросами
- */
-export declare class Query<TResult, TError = void> implements QueryBaseActions<TResult, TError, undefined> {
     /**
-     * @description инстанс вспомогательного стора
+     * Инстанс хранилища основных статусов
      */
-    private auxiliary;
+    statusStorage: StatusStorage<TError>;
     /**
-     * @description флаг, по которому реактивно определяется необходимость запуска инвалидации
+     * Инстанс хранилища фоновых статусов
      */
-    private isInvalid;
+    backgroundStatusStorage?: TIsBackground extends true ? StatusStorage<TError> : null | undefined;
     /**
-     * @description хранилище данных, для обеспечения возможности синхронизации данных между разными инстансами
+     * Колбэк, вызываемый при успешном завершении запроса, подразумевается использование, для подтверждения валидности данных, чтобы квери не был удален из памяти
      */
-    private storage;
+    submitValidity?: () => void;
+};
+/**
+ * Стор для работы с запросами,
+ * которые должны быть закешированы,
+ * но им не требуется усложнение в виде работы с фильтрами и инфинити запросами
+ */
+export declare class Query<TResult, TError = void, TIsBackground extends boolean = false> extends QueryContainer<TError, AuxiliaryQuery<TResult, TError>, TIsBackground> implements QueryBaseActions<TResult, TError, undefined> {
+    private readonly executor;
     /**
-     * @description исполнитель запроса, ожидается,
-     * что будет использоваться что-то из слоя sources
+     * Хранилище данных, для обеспечения возможности синхронизации данных между разными инстансами
      */
-    private executor;
+    private storage;
     /**
-     * @description обработчик ошибки, вызываемый по умолчанию
+     * Обработчик ошибки, вызываемый по умолчанию
      */
     private defaultOnError?;
     /**
-     * @description флаг, отвечающий за автоматический запрос данных при обращении к полю data
+     * Флаг, отвечающий за автоматический запрос данных при обращении к полю data
      */
     private enabledAutoFetch?;
     /**
-     * @description стандартное поведение политики кеширования
+     * Стандартное поведение политики кеширования
      */
     private readonly defaultFetchPolicy?;
-    constructor(executor: QueryExecutor<TResult>, { onError, enabledAutoFetch, fetchPolicy, dataStorage, }: QueryParams<TResult, TError>);
+    /**
+     * Колбэк, вызываемый при успешном завершении запроса, подразумевается использование, для подтверждения валидности данных, чтобы квери не был удален из памяти
+     */
+    private readonly submitValidity?;
+    constructor(executor: QueryExecutor<TResult>, { onError, enabledAutoFetch, fetchPolicy, dataStorage, statusStorage, backgroundStatusStorage, submitValidity, }: QueryParams<TResult, TError, TIsBackground>);
     private get isNetworkOnly();
     /**
-     * @description метод для инвалидации данных
+     * Метод для инвалидации данных
      */
     invalidate: () => void;
     /**
-     * @description синхронный метод получения данных
+     * Синхронный метод получения данных
      */
     sync: Sync<TResult, TError, undefined>;
     /**
-     * @description обработчик успешного ответа
+     * Обработчик успешного ответа
      */
     private submitSuccess;
     /**
-     * @description форс метод для установки данных
+     * Форс метод для установки данных
      */
     forceUpdate: (data: TResult) => void;
     /**
-     * @description метод для переиспользования синхронной логики запроса
+     * Метод для переиспользования синхронной логики запроса
      */
-    private proceedSync;
+    protected proceedSync: Sync<TResult, TError>;
     /**
-     * @description асинхронный метод получения данных,
+     * Асинхронный метод получения данных,
      * предполагается, что нужно будет самостоятельно обрабатывать ошибку
      */
     async: () => Promise<TResult>;
     /**
-     * @description содержит реактивные данные
+     * Содержит реактивные данные
      * благодаря mobx, при изменении isInvalid, свойство будет вычисляться заново,
      * следовательно, стриггерится условие невалидности,
      * и начнется запрос, в результате которого, данные обновятся
      */
     get data(): TResult | undefined;
-    /**
-     * @description флаг загрузки данных
-     */
-    get isLoading(): boolean;
-    /**
-     * @description флаг обозначающий, что последний запрос был зафейлен
-     */
-    get isError(): boolean;
-    /**
-     * @description данные о последней ошибке
-     */
-    get error(): TError | undefined;
-    /**
-     * @description флаг обозначающий, что последний запрос был успешно завершен
-     */
-    get isSuccess(): boolean;
-    get isIdle(): boolean;
 }

package/Query/Query.js

@@ -1,52 +1,48 @@
-import { makeAutoObservable, when } from 'mobx';
+import { action, computed, makeObservable, when } from 'mobx';
 import { AuxiliaryQuery } from '../AuxiliaryQuery';
+import { QueryContainer } from '../QueryContainer';
 /**
- * @description стор для работы с запросами,
+ * Стор для работы с запросами,
  * которые должны быть закешированы,
  * но им не требуется усложнение в виде работы с фильтрами и инфинити запросами
  */
-export class Query {
-    constructor(executor, { onError, enabledAutoFetch, fetchPolicy, dataStorage, }) {
-        /**
-         * @description инстанс вспомогательного стора
-         */
-        this.auxiliary = new AuxiliaryQuery();
-        /**
-         * @description флаг, по которому реактивно определяется необходимость запуска инвалидации
-         */
-        this.isInvalid = false;
+export class Query extends QueryContainer {
+    constructor(executor, { onError, enabledAutoFetch, fetchPolicy, dataStorage, statusStorage, backgroundStatusStorage = null, submitValidity, }) {
+        super(statusStorage, backgroundStatusStorage, new AuxiliaryQuery(statusStorage, backgroundStatusStorage));
+        this.executor = executor;
         /**
-         * @description метод для инвалидации данных
+         * Метод для инвалидации данных
          */
         this.invalidate = () => {
-            this.isInvalid = true;
+            this.auxiliary.invalidate();
         };
         /**
-         * @description синхронный метод получения данных
+         * Синхронный метод получения данных
          */
         this.sync = (params) => {
             const isInstanceAllow = !(this.isLoading || this.isSuccess);
-            if (this.isNetworkOnly || this.isInvalid || isInstanceAllow) {
+            if (this.isNetworkOnly || this.auxiliary.isInvalid || isInstanceAllow) {
                 this.proceedSync(params);
             }
         };
         /**
-         * @description обработчик успешного ответа
+         * Обработчик успешного ответа
          */
         this.submitSuccess = (resData) => {
+            var _a;
             this.storage.setData(resData);
-            this.isInvalid = false;
+            (_a = this.submitValidity) === null || _a === void 0 ? void 0 : _a.call(this);
             return resData;
         };
         /**
-         * @description форс метод для установки данных
+         * Форс метод для установки данных
          */
         this.forceUpdate = (data) => {
             this.auxiliary.submitSuccess();
             this.submitSuccess(data);
         };
         /**
-         * @description метод для переиспользования синхронной логики запроса
+         * Метод для переиспользования синхронной логики запроса
          */
         this.proceedSync = (options) => {
             const { onSuccess, onError } = options || {};
@@ -67,29 +63,35 @@ export class Query {
             });
         };
         /**
-         * @description асинхронный метод получения данных,
+         * Асинхронный метод получения данных,
          * предполагается, что нужно будет самостоятельно обрабатывать ошибку
          */
         this.async = () => {
-            if (!this.isNetworkOnly && this.isSuccess && !this.isInvalid) {
+            if (!this.isNetworkOnly && this.isSuccess && !this.auxiliary.isInvalid) {
                 return Promise.resolve(this.storage.data);
             }
             return this.auxiliary
                 .getUnifiedPromise(this.executor)
                 .then(this.submitSuccess);
         };
-        this.executor = executor;
         this.defaultOnError = onError;
         this.enabledAutoFetch = enabledAutoFetch;
         this.defaultFetchPolicy = fetchPolicy;
         this.storage = dataStorage;
-        makeAutoObservable(this);
+        this.submitValidity = submitValidity;
+        makeObservable(this, {
+            async: action,
+            sync: action,
+            forceUpdate: action,
+            data: computed,
+            submitSuccess: action,
+        });
     }
     get isNetworkOnly() {
         return this.defaultFetchPolicy === 'network-only';
     }
     /**
-     * @description содержит реактивные данные
+     * Содержит реактивные данные
      * благодаря mobx, при изменении isInvalid, свойство будет вычисляться заново,
      * следовательно, стриггерится условие невалидности,
      * и начнется запрос, в результате которого, данные обновятся
@@ -99,7 +101,7 @@ export class Query {
             !this.isSuccess &&
             !this.isLoading &&
             !this.isError;
-        if (this.isInvalid || shouldSync) {
+        if (this.auxiliary.isInvalid || shouldSync) {
             // т.к. при вызове апдейта, изменяются флаги, на которые подписан data,
             // нужно вызывать этот экшн асинхронно
             when(() => true, this.proceedSync);
@@ -107,31 +109,4 @@ export class Query {
         // возвращаем имеющиеся данные
         return this.storage.data;
     }
-    /**
-     * @description флаг загрузки данных
-     */
-    get isLoading() {
-        return this.auxiliary.isLoading;
-    }
-    /**
-     * @description флаг обозначающий, что последний запрос был зафейлен
-     */
-    get isError() {
-        return this.auxiliary.isError;
-    }
-    /**
-     * @description данные о последней ошибке
-     */
-    get error() {
-        return this.auxiliary.error;
-    }
-    /**
-     * @description флаг обозначающий, что последний запрос был успешно завершен
-     */
-    get isSuccess() {
-        return this.auxiliary.isSuccess;
-    }
-    get isIdle() {
-        return this.auxiliary.isIdle;
-    }
 }

package/QueryContainer/QueryContainer.d.ts

@@ -0,0 +1,61 @@
+import { type StatusStorage } from '../StatusStorage';
+export type QueryContainerAuxiliary = {
+    isIdle: boolean;
+};
+type Statuses<TError> = StatusStorage<TError>;
+/**
+ * Контейнер для бойлерплейт части,
+ * позволяет не повторять в каждом наследуемом классе использование стандартных статусов
+ */
+export declare abstract class QueryContainer<TError, TAuxiliary extends QueryContainerAuxiliary, TIsBackground extends boolean> implements Statuses<TError> {
+    private readonly statusStorage;
+    private readonly backgroundStatusStorage;
+    protected readonly auxiliary: TAuxiliary;
+    protected constructor(statusStorage: StatusStorage<TError>, backgroundStatusStorage: StatusStorage<TError> | null, auxiliary: TAuxiliary);
+    /**
+     * Флаг загрузки данных
+     */
+    get isLoading(): boolean;
+    /**
+     * Флаг обозначающий, что последний запрос был зафейлен
+     */
+    get isError(): boolean;
+    /**
+     * Данные о последней ошибке
+     */
+    get error(): TError | undefined;
+    /**
+     * Флаг обозначающий, что последний запрос был успешно завершен
+     */
+    get isSuccess(): boolean;
+    /**
+     * Флаг, обозначающий простаивание, т.е. запроса еще не было
+     */
+    get isIdle(): boolean;
+    /**
+     * Статусы, изменяющиеся после первого успешного запроса в режиме isBackground: true
+     * @example
+     * const query = mobxQuery.createQuery(
+     *     ['some cache key'],
+     *     () => Promise.resolve('foo'),
+     *     { isBackground: true }
+     * );
+     *
+     * await query.async();
+     * console.log(query.isLoading); // переключался в true на момент запроса
+     * console.log(query.isSuccess); // true
+     *
+     * query.invalidate();
+     * await query.async();
+     * console.log(query.isLoading); // не изменялся
+     * console.log(query.isSuccess); // остался неизменным - true
+     *
+     * console.log(query.background.isLoading); // переключался в true на момент обновления
+     * console.log(query.background.isSuccess); // true
+     *
+     * @exception isBackground:false (а так же по умолчанию) background не доступен, и равен null
+     * @exception Mutation не доступен в мутации и равен null
+     */
+    get background(): TIsBackground extends true ? Statuses<TError> : null;
+}
+export {};

package/QueryContainer/QueryContainer.js

@@ -0,0 +1,79 @@
+import { computed, makeObservable } from 'mobx';
+/**
+ * Контейнер для бойлерплейт части,
+ * позволяет не повторять в каждом наследуемом классе использование стандартных статусов
+ */
+export class QueryContainer {
+    constructor(statusStorage, backgroundStatusStorage, auxiliary) {
+        this.statusStorage = statusStorage;
+        this.backgroundStatusStorage = backgroundStatusStorage;
+        this.auxiliary = auxiliary;
+        makeObservable(this, {
+            error: computed,
+            isError: computed,
+            isIdle: computed,
+            isLoading: computed,
+            isSuccess: computed,
+        });
+    }
+    /**
+     * Флаг загрузки данных
+     */
+    get isLoading() {
+        return this.statusStorage.isLoading;
+    }
+    /**
+     * Флаг обозначающий, что последний запрос был зафейлен
+     */
+    get isError() {
+        return this.statusStorage.isError;
+    }
+    /**
+     * Данные о последней ошибке
+     */
+    get error() {
+        return this.statusStorage.error;
+    }
+    /**
+     * Флаг обозначающий, что последний запрос был успешно завершен
+     */
+    get isSuccess() {
+        return this.statusStorage.isSuccess;
+    }
+    /**
+     * Флаг, обозначающий простаивание, т.е. запроса еще не было
+     */
+    get isIdle() {
+        return this.auxiliary.isIdle;
+    }
+    /**
+     * Статусы, изменяющиеся после первого успешного запроса в режиме isBackground: true
+     * @example
+     * const query = mobxQuery.createQuery(
+     *     ['some cache key'],
+     *     () => Promise.resolve('foo'),
+     *     { isBackground: true }
+     * );
+     *
+     * await query.async();
+     * console.log(query.isLoading); // переключался в true на момент запроса
+     * console.log(query.isSuccess); // true
+     *
+     * query.invalidate();
+     * await query.async();
+     * console.log(query.isLoading); // не изменялся
+     * console.log(query.isSuccess); // остался неизменным - true
+     *
+     * console.log(query.background.isLoading); // переключался в true на момент обновления
+     * console.log(query.background.isSuccess); // true
+     *
+     * @exception isBackground:false (а так же по умолчанию) background не доступен, и равен null
+     * @exception Mutation не доступен в мутации и равен null
+     */
+    get background() {
+        if (!this.backgroundStatusStorage) {
+            return null;
+        }
+        return this.backgroundStatusStorage;
+    }
+}

package/QueryContainer/index.d.ts

@@ -0,0 +1 @@
+export * from './QueryContainer';

package/QueryContainer/index.js

@@ -0,0 +1 @@
+export * from './QueryContainer';

package/README.md

@@ -342,6 +342,31 @@ console.log(query.isError); // 'true'
 console.log(query.error); // 'foo'
 ```
 
+## Режим фонового обновления
+`Query` и `InfiniteQuery` имеют режим фонового обновления. Предполагается, что будет хорошо подходить для обновления данных через websocket.
+
+В этом режиме, основные статусные флаги `isSuccess`, `isLoading`, `isError`, `error` будут изменяться до первого успешного запроса. Последующие запросы уже будут изменять статусные флаги под полем `background`
+
+```ts
+const query = mobxQuery.createQuery(
+    ['some cache key'],
+    () => Promise.resolve('foo'),
+    { isBackground: true }
+);
+
+await query.async();
+console.log(query.isLoading); // переключался в true на момент запроса
+console.log(query.isSuccess); // true
+
+query.invalidate();
+await query.async();
+console.log(query.isLoading); // не изменялся
+console.log(query.isSuccess); // остался неизменным - true
+
+console.log(query.background.isLoading); // переключался в true на момент обновления
+console.log(query.background.isSuccess); // true
+```
+
 # Тестирование
 
 ## Тестирование при включенном ```enabledAutoFetch```

package/StatusStorage/StatusStorage.d.ts

@@ -0,0 +1,24 @@
+import { StorageFactory } from '../StorageFactory';
+export declare class StatusStorage<TError> {
+    constructor();
+    /**
+     * Флаг обозначающий загрузку данных
+     */
+    isLoading: boolean;
+    /**
+     * Флаг обозначающий, что последний запрос был зафейлен
+     */
+    isError: boolean;
+    /**
+     * Данные о последней ошибке
+     */
+    error?: TError;
+    /**
+     * Флаг, обозначающий успешность завершения последнего запроса
+     */
+    isSuccess: boolean;
+}
+export declare class StatusStorageFactory extends StorageFactory<StatusStorage<void>> {
+    constructor();
+    getStorage: <TError>(keyHash: string) => StatusStorage<TError>;
+}

package/StatusStorage/StatusStorage.js

@@ -0,0 +1,36 @@
+import { makeObservable, observable } from 'mobx';
+import { StorageFactory } from '../StorageFactory';
+export class StatusStorage {
+    constructor() {
+        /**
+         * Флаг обозначающий загрузку данных
+         */
+        this.isLoading = false;
+        /**
+         * Флаг обозначающий, что последний запрос был зафейлен
+         */
+        this.isError = false;
+        /**
+         * Данные о последней ошибке
+         */
+        this.error = undefined;
+        /**
+         * Флаг, обозначающий успешность завершения последнего запроса
+         */
+        this.isSuccess = false;
+        makeObservable(this, {
+            error: observable,
+            isError: observable,
+            isLoading: observable,
+            isSuccess: observable,
+        });
+    }
+}
+export class StatusStorageFactory extends StorageFactory {
+    constructor() {
+        super(() => new StatusStorage());
+        this.getStorage = (keyHash) => {
+            return this.getInternalStorage(keyHash);
+        };
+    }
+}

package/StatusStorage/index.d.ts

@@ -0,0 +1 @@
+export * from './StatusStorage';

package/StatusStorage/index.js

@@ -0,0 +1 @@
+export * from './StatusStorage';

package/StorageFactory/StorageFactory.d.ts

@@ -0,0 +1,9 @@
+export declare abstract class StorageFactory<TStorage extends {}> {
+    private readonly createStorage;
+    private readonly adaptableMap;
+    protected constructor(createStorage: () => TStorage);
+    /**
+     * Фабричный метод получения/создания инстанса хранилища по ключу
+     */
+    getInternalStorage: (keyHash: string) => TStorage;
+}

package/StorageFactory/StorageFactory.js

@@ -0,0 +1,19 @@
+import { AdaptableMap } from '../AdaptableMap';
+export class StorageFactory {
+    constructor(createStorage) {
+        this.createStorage = createStorage;
+        this.adaptableMap = new AdaptableMap();
+        /**
+         * Фабричный метод получения/создания инстанса хранилища по ключу
+         */
+        this.getInternalStorage = (keyHash) => {
+            const storage = this.adaptableMap.get(keyHash);
+            if (!storage) {
+                const createdStorage = this.createStorage();
+                this.adaptableMap.set(keyHash, createdStorage);
+                return createdStorage;
+            }
+            return storage;
+        };
+    }
+}

package/StorageFactory/index.d.ts

@@ -0,0 +1 @@
+export * from './StorageFactory';

package/StorageFactory/index.js

@@ -0,0 +1 @@
+export * from './StorageFactory';