@astral/mobx-query 1.4.0 → 1.5.0

package/Query/Query.d.ts

@@ -1,108 +1,90 @@
+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;
     fetchPolicy?: FetchPolicy;
     /**
-     * @description инстанс хранилища данных
+     * инстанс хранилища данных
      */
     dataStorage: DataStorage<TResult>;
+    /**
+     * инстанс хранилища основных статусов
+     */
+    statusStorage: StatusStorage<TError>;
+    /**
+     * инстанс хранилища фоновых статусов
+     */
+    backgroundStatusStorage?: TIsBackground extends true ? StatusStorage<TError> : null | undefined;
 };
 /**
- * @description стор для работы с запросами,
+ * стор для работы с запросами,
  * которые должны быть закешированы,
  * но им не требуется усложнение в виде работы с фильтрами и инфинити запросами
  */
-export declare class Query<TResult, TError = void> implements QueryBaseActions<TResult, TError, undefined> {
+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 инстанс вспомогательного стора
-     */
-    private auxiliary;
-    /**
-     * @description флаг, по которому реактивно определяется необходимость запуска инвалидации
-     */
-    private isInvalid;
-    /**
-     * @description хранилище данных, для обеспечения возможности синхронизации данных между разными инстансами
+     * хранилище данных, для обеспечения возможности синхронизации данных между разными инстансами
      */
     private storage;
     /**
-     * @description исполнитель запроса, ожидается,
-     * что будет использоваться что-то из слоя sources
-     */
-    private executor;
-    /**
-     * @description обработчик ошибки, вызываемый по умолчанию
+     * обработчик ошибки, вызываемый по умолчанию
      */
     private defaultOnError?;
     /**
-     * @description флаг, отвечающий за автоматический запрос данных при обращении к полю data
+     * флаг, отвечающий за автоматический запрос данных при обращении к полю data
      */
     private enabledAutoFetch?;
     /**
-     * @description стандартное поведение политики кеширования
+     * стандартное поведение политики кеширования
      */
     private readonly defaultFetchPolicy?;
-    constructor(executor: QueryExecutor<TResult>, { onError, enabledAutoFetch, fetchPolicy, dataStorage, }: QueryParams<TResult, TError>);
+    constructor(executor: QueryExecutor<TResult>, { onError, enabledAutoFetch, fetchPolicy, dataStorage, statusStorage, backgroundStatusStorage, }: 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,46 @@
-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, }) {
+        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) => {
             this.storage.setData(resData);
-            this.isInvalid = false;
             return resData;
         };
         /**
-         * @description форс метод для установки данных
+         * форс метод для установки данных
          */
         this.forceUpdate = (data) => {
             this.auxiliary.submitSuccess();
             this.submitSuccess(data);
         };
         /**
-         * @description метод для переиспользования синхронной логики запроса
+         * метод для переиспользования синхронной логики запроса
          */
         this.proceedSync = (options) => {
             const { onSuccess, onError } = options || {};
@@ -67,29 +61,34 @@ 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);
+        makeObservable(this, {
+            async: action,
+            sync: action,
+            forceUpdate: action,
+            data: computed,
+            submitSuccess: action,
+        });
     }
     get isNetworkOnly() {
         return this.defaultFetchPolicy === 'network-only';
     }
     /**
-     * @description содержит реактивные данные
+     * содержит реактивные данные
      * благодаря mobx, при изменении isInvalid, свойство будет вычисляться заново,
      * следовательно, стриггерится условие невалидности,
      * и начнется запрос, в результате которого, данные обновятся
@@ -99,7 +98,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 +106,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.backgroundStatus.isLoading); // переключался в true на момент обновления
+     * console.log(query.backgroundStatus.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.backgroundStatus.isLoading); // переключался в true на момент обновления
+     * console.log(query.backgroundStatus.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` будут изменяться до первого успешного запроса. Последующие запросы уже будут изменять статусные флаги под полем `backgroundStatus`
+
+```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.backgroundStatus.isLoading); // переключался в true на момент обновления
+console.log(query.backgroundStatus.isSuccess); // true
+```
+
 # Тестирование
 
 ## Тестирование при включенном ```enabledAutoFetch```

package/StatusStorage/StatusStorage.d.ts

@@ -0,0 +1,25 @@
+import { StorageFactory } from '../StorageFactory';
+import { type CacheKey } from '../types';
+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>(key: CacheKey[]) => 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 = (key) => {
+            return this.getInternalStorage(key);
+        };
+    }
+}

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,13 @@
+import { type CacheKey } from '../types';
+export declare abstract class StorageFactory<TStorage> {
+    private readonly createStorage;
+    protected constructor(createStorage: () => TStorage);
+    /**
+     * Map хранящий инстансы хранилищ по хэшу ключа
+     */
+    private storageMap;
+    /**
+     * фабричный метод получения/создания инстанса хранилища по ключу
+     */
+    protected getInternalStorage: (key: CacheKey[]) => TStorage | undefined;
+}

package/StorageFactory/StorageFactory.js

@@ -0,0 +1,19 @@
+export class StorageFactory {
+    constructor(createStorage) {
+        this.createStorage = createStorage;
+        /**
+         * Map хранящий инстансы хранилищ по хэшу ключа
+         */
+        this.storageMap = new Map();
+        /**
+         * фабричный метод получения/создания инстанса хранилища по ключу
+         */
+        this.getInternalStorage = (key) => {
+            const keyHash = JSON.stringify(key);
+            if (!this.storageMap.has(keyHash)) {
+                this.storageMap.set(keyHash, this.createStorage());
+            }
+            return this.storageMap.get(keyHash);
+        };
+    }
+}

package/StorageFactory/index.d.ts

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

package/StorageFactory/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astral/mobx-query",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "browser": "./index.js",
   "main": "./index.js",
   "dependencies": {

package/types.d.ts

@@ -4,36 +4,36 @@ export type SyncParams<TResult, TError, TExecutorParams = void> = {
     params?: TExecutorParams;
 };
 /**
- * @description синхронный метод получения данных
+ * синхронный метод получения данных
  */
 export type Sync<TResult, TError, TExecutorParams = void> = (params?: SyncParams<TResult, TError, TExecutorParams>) => void;
 /**
- * @description асинхронный метод получения данных
+ * асинхронный метод получения данных
  */
 export type Async<TResult, TExecutorParams = void> = (params: TExecutorParams) => Promise<TResult>;
 export type QueryBaseActions<TResult, TError, TExecutorParams = void> = {
     /**
-     * @description синхронный метод получения данных
+     * синхронный метод получения данных
      */
     sync: Sync<TResult, TError, TExecutorParams>;
     /**
-     * @description асинхронный метод получения данных
+     * асинхронный метод получения данных
      */
     async: Async<TResult, TExecutorParams>;
     /**
-     * @description флаг обозначающий загрузку данных
+     * флаг обозначающий загрузку данных
      */
     isLoading: boolean;
     /**
-     * @description флаг обозначающий, что последний запрос был зафейлен
+     * флаг обозначающий, что последний запрос был зафейлен
      */
     isError: boolean;
     /**
-     * @description данные о последней ошибке
+     * данные о последней ошибке
      */
     error?: TError;
     /**
-     * @description флаг обзначающий, что последний запрос был успешно выполнен
+     * флаг обзначающий, что последний запрос был успешно выполнен
      */
     isSuccess: boolean;
     /**
@@ -42,13 +42,13 @@ export type QueryBaseActions<TResult, TError, TExecutorParams = void> = {
     isIdle: boolean;
 };
 /**
- * @description политика получения данных.
- * @variation 'cache-first' - данные сначала берутся из кеша, если их нет, тогда идет обращение к сети, ответ записывается в кэш
- * @kind 'network-only' - данные всегда беруться из сети, при этом ответ записывается в кэш
+ * политика получения данных.
+ * @enum cache-first - данные сначала берутся из кеша, если их нет, тогда идет обращение к сети, ответ записывается в кэш
+ * @enum network-only - данные всегда беруться из сети, при этом ответ записывается в кэш
  */
 export type FetchPolicy = 'network-only' | 'cache-first';
 /**
- * @description ключ для кешированя
+ * ключ для кешированя
  */
 export type CacheKey = string | number | boolean | null | undefined | CacheKey[] | {
     [key: string]: CacheKey;