sprof 0.9.5 → 0.9.7

package/dist/core/composables/index.d.ts

@@ -3,7 +3,9 @@
  *
  * - useCrud — CRUD-страница: store + loading/items/count/item/searchStr/load/remove/reset;
  * - useFilters — фильтры FTSP: add/replace/remove/has/clear;
- * - usePagination — пагинация FTSP: page (1-based)/rowsPerPage/next/prev/reset.
+ * - usePagination — пагинация FTSP: page (1-based)/rowsPerPage/next/prev/reset;
+ * - useOptions — справочник для селекта: кэш + дедуп (К1, Т8);
+ * - useLoader — состояния загрузки: loading/error/data + ретрай (Т2a, пара к `PLoader`).
  *
  * По умолчанию работают с глобальным синглтоном FTSP.Get(); во всех трёх можно
  * передать свой экземпляр FTSP (страница/компонент) — см. T1 в TECH_DEBT.md.
@@ -12,6 +14,10 @@ export type { UseCrudOptions, UseCrudReturn } from './useCrud';
 export { useCrud } from './useCrud';
 export type { UseFiltersReturn } from './useFilters';
 export { useFilters } from './useFilters';
+export type { LoaderFn, LoaderRetryOptions, UseLoaderOptions, UseLoaderReturn } from './useLoader';
+export { useLoader } from './useLoader';
+export type { UseOptionsOptions, UseOptionsReturn } from './useOptions';
+export { useOptions } from './useOptions';
 export type { UsePaginationReturn } from './usePagination';
 export { usePagination } from './usePagination';
 export type { PlatformName, ThemeName, UseThemeOptions, UseThemeReturn } from './useTheme';

package/dist/core/composables/useLoader.d.ts

@@ -0,0 +1,63 @@
+import { ComputedRef, Ref } from 'vue';
+import { TryOpts } from '../helpers/Try';
+/** Функция загрузки: может принимать признак «принудительно» (мимо кэша/флага loaded). */
+export type LoaderFn<T> = (force: boolean) => Promise<T> | T;
+/** Попытка загрузки: сколько раз пробуем и с какой паузой (мс). */
+export interface LoaderRetryOptions {
+    /** Всего попыток, включая первую (по умолчанию 1 — без повторов). */
+    attempts?: number;
+    /** Пауза между попытками, мс (по умолчанию 2000; растёт линейно). */
+    delay?: number;
+}
+export interface UseLoaderOptions extends LoaderRetryOptions {
+    /** Запускать сразу при создании (иначе — вручную: `onMounted(load)`). */
+    immediate?: boolean;
+    /** Загружать один раз: повторные `load()` без `force` выходят сразу. */
+    once?: boolean;
+    /**
+     * Запросы к `PF.UI.Notify` при ошибке. По умолчанию — МОЛЧА: состояние ошибки
+     * показывает сам виджет `PLoader`/экран, и уведомление на каждый отказ — шум.
+     * Включать, когда ошибку больше показать негде.
+     */
+    notify?: boolean | Pick<TryOpts, 'message'>;
+    /** Своё сообщение об ошибке (когда `notify` включён). */
+    message?: string;
+}
+export interface UseLoaderReturn<T> {
+    /** Идёт загрузка (включая повторные попытки). */
+    loading: Ref<boolean>;
+    /** Текст ошибки последней попытки; пустая строка — ошибки нет. */
+    error: Ref<string>;
+    /** Загруженные данные (null — ещё не было успешной загрузки). */
+    data: Ref<T | null>;
+    /** Успешная загрузка состоялась хотя бы раз. */
+    loaded: ComputedRef<boolean>;
+    /** Факт ошибки (для `v-if`/слотов виджета). */
+    failed: ComputedRef<boolean>;
+    /** Ошибка при ПЕРВОЙ загрузке (данных нет) — показываем экран ошибки целиком. */
+    failedFirstLoad: ComputedRef<boolean>;
+    /**
+     * Загрузка людей. При ошибке НЕ бросает: ошибка уходит в `error`
+     * (и в уведомление, если `notify`).
+     */
+    load: (force?: boolean) => Promise<void>;
+    /** Сбросить состояние (данные, ошибку, признак `once`) — перед сменой фильтров. */
+    reset: () => void;
+}
+/**
+ * Единая обёртка загрузки (запрос из rdkb/map, 14.09): убирает `try/catch` +
+ * флаг `loading` + поле `error` + ретрай, которые в 8 клиентах писались руками
+ * (ср. `MyTasksPage.vue` до перевода, панель дерева, онбординг incident).
+ *
+ * ```ts
+ * const { loading, error, data, load } = useLoader(() =>
+ *   PF.H.HttpClient.Get<MyTasks>(), { immediate: true, attempts: 3 },
+ * );
+ * ```
+ *
+ * ⚠️ Не дублирует `PF.H.Try`: `Try` — про разбор ошибки и уведомление,
+ * `useLoader` — про СОСТОЯНИЕ загрузки (loading/error/data). Ретрай вынесен
+ * сюда, потому что он нужен именно циклу загрузки; уведомление включается
+ * опцией `notify` и внутри идёт через `Try.Silent` + `Try.Message`.
+ */
+export declare function useLoader<T>(fn: LoaderFn<T>, options?: UseLoaderOptions): UseLoaderReturn<T>;

package/dist/core/composables/useLoader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/composables/useOptions.d.ts

@@ -0,0 +1,60 @@
+import { ComputedRef, Ref } from 'vue';
+import { OptionsCacheOptions, default as BaseStore } from '../helpers/BaseStore';
+import { default as IFileInfosGetter } from '../interfaces/IFileInfosGetter';
+import { default as Option } from '../interfaces/IOption';
+import { default as IWithId } from '../interfaces/IWithId';
+export interface UseOptionsOptions extends OptionsCacheOptions {
+    /** Колонка-подпись в `/options/<label>/<value>` */
+    labelCol?: string;
+    /** Колонка-значение в `/options/<label>/<value>` */
+    valueCol?: string;
+    /**
+     * Грузить сразу при создании (по умолчанию — да).
+     * Выключите, если загрузку надо привязать к открытию диалога.
+     */
+    immediate?: boolean;
+    /**
+     * Справочник ТЯЖЁЛЫЙ: искать на сервере (`?query=`), а не тянуть целиком.
+     * Включайте для больших справочников (сотрудники, помещения и т.п.).
+     */
+    searchable?: boolean;
+    /** Задержка дебаунса поиска, мс (по умолчанию 300). */
+    debounceMs?: number;
+    /** Лимит серверной выдачи (сервер зажмёт по своему потолку). */
+    limit?: number;
+}
+export interface UseOptionsReturn {
+    /** Опции справочника (реактивный массив стора) */
+    options: ComputedRef<Option[]>;
+    /** Справочник уже загружен */
+    isLoading: ComputedRef<boolean>;
+    /** Загрузить (с кэшем; `force` — перечитать) */
+    load(override?: OptionsCacheOptions): Promise<void>;
+    /** Сбросить кэш справочника (после правки в другом месте) */
+    invalidate(): void;
+    /** Текущая строка поиска (v-model у поля с `use-input`); только при `searchable` */
+    query: Ref<string>;
+    /**
+     * Строка поиска прямо сейчас (без дебаунса) — для программного поиска
+     * (напр. при открытии селекта сразу показать первые варианты).
+     */
+    search(rawQuery: string): Promise<void>;
+}
+/**
+ * Справочник для селекта: кэш + дедуп (К1) и серверный поиск (К2) в одном вызове.
+ *
+ * Заменяет ручные `await store.GetOptions()` в `onMounted` — тот подход
+ * запрашивал справочник заново при каждом входе и плодил дубли запросов.
+ *
+ * ```ts
+ * // небольшой справочник: тянем целиком, кэш экономит повторные входы
+ * const { options } = useOptions(Store.Workers);
+ *
+ * // тяжёлый: ищем на сервере, в `query` вяжем v-model поля с `use-input`
+ * const { options, query } = useOptions(Store.Workers, {
+ *   searchable: true,
+ *   labelCol: 'full_name',
+ * });
+ * ```
+ */
+export declare function useOptions<T extends IWithId & IFileInfosGetter>(store: BaseStore<T>, options?: UseOptionsOptions): UseOptionsReturn;

package/dist/core/composables/useOptions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/helpers/BaseStore.d.ts

@@ -9,6 +9,15 @@ export interface GetAllOptions {
     withCache?: boolean;
     ftsp: FTSP;
 }
+/** Настройки кэша справочников (`GetOptions`); К1 (Т8). */
+export interface OptionsCacheOptions {
+    /** Использовать кэш (по умолчанию — да). */
+    cache?: boolean;
+    /** TTL в минутах (по умолчанию 10). */
+    ttl?: number;
+    /** Перечитать из сети, игнорируя кэш. */
+    force?: boolean;
+}
 export default class BaseStore<T extends IWithId & IFileInfosGetter> {
     readonly items: T[];
     readonly item: T;
@@ -20,7 +29,35 @@ export default class BaseStore<T extends IWithId & IFileInfosGetter> {
     constructor(i: Constructable<T>, url: string);
     Set(item: T | void): void;
     getUrl(query?: string): string;
-    GetOptions(labelCol?: string, valueCol?: string): Promise<void>;
+    /**
+     * Загрузить справочник (`<url>/options/<label>/<value>`) — с КЭШЕМ и ДЕДУПОМ (К1, Т8).
+     *
+     * Раньше каждый вход в список/форму дёргал сервер заново, а параллельные
+     * вызовы (несколько селектов на странице) давали несколько одинаковых запросов.
+     * Теперь: TTL-кэш в sessionStorage + один запрос на все параллельные вызовы.
+     *
+     * ⚠️ Ключ кэша включает label/value: тот же справочник можно просить в разных
+     * парах полей, это РАЗНЫЕ наборы опций.
+     */
+    GetOptions(labelCol?: string, valueCol?: string, options?: OptionsCacheOptions): Promise<void>;
+    /**
+     * Сбросить кэш справочника — после записи (`Create`/`Update`/`Remove`) (К4).
+     * `labelCol`/`valueCol` можно не указывать — сбросится кэш всех вариантов пары.
+     */
+    InvalidateOptions(labelCol?: string, valueCol?: string): void;
+    /**
+     * Серверный поиск по справочнику (К2, Т8) — для тяжёлых справочников.
+     *
+     * ⚠️ Зачем, если есть `GetOptions`. Крупный справочник (сотрудники — 2250)
+     * нельзя тянуть целиком в селект: это секунды и список из тысяч строк, в котором
+     * нужное не найти. Здесь сервер отдаёт только совпадения (белый список полей —
+     * на модели, см. `Searchable` в sprob).
+     *
+     * Результат НЕ кэшируется по TTL: это поисковый запрос, а не справочник.
+     * Ответ — последние найденные варианты (они же попадают в `Options`).
+     */
+    SearchOptions(query: string, labelCol?: string, valueCol?: string, limit?: number): Promise<Option[]>;
+    private SetOptions;
     GetAll(options?: GetAllOptions): Promise<void>;
     Get(id?: string): Promise<void>;
     GetBySlug(slug?: string): Promise<void>;

package/dist/core/helpers/Cache.d.ts

@@ -1,7 +1,9 @@
 export default class Cache {
     name: string;
     constructor(i?: Cache);
-    static Set(): void;
+    static Set<DataType>(name: string, data: DataType): void;
     static Get<DataType>(name: string, min?: number): DataType | null;
+    /** Удалить запись (инвалидация после записи справочника). */
+    static Clear(name?: string): void;
     static TryGet<DataType>(name: string, get: () => Promise<DataType | void>, min?: number): Promise<DataType | void | null>;
 }

package/dist/global-components.d.ts

@@ -22,6 +22,7 @@ declare module 'vue' {
         PLeftSlider: typeof Atoms.PLeftSlider;
         PList: typeof Atoms.PList;
         PListItem: typeof Atoms.PListItem;
+        PLoader: typeof Atoms.PLoader;
         POptionsListSingle: typeof Atoms.POptionsListSingle;
         POpts: typeof Atoms.POpts;
         PRadio: typeof Atoms.PRadio;

package/dist/index.d.ts

@@ -43,10 +43,13 @@ export type { default as Btn } from './core/ui/Btn';
 export type { default as AnswerVariant } from './modules/forms/classes/AnswerVariant';
 /** @internal Used by unplugin-auto-import configuration */
 export declare const pfName: readonly ["PF", "PFM"];
-export { useCrud, useFilters, usePagination } from './core/composables/index';
+export { useCrud, useFilters, useLoader, usePagination } from './core/composables/index';
 export type { UseCrudOptions, UseCrudReturn } from './core/composables/useCrud';
 export type { UseFiltersReturn } from './core/composables/useFilters';
+export type { LoaderFn, LoaderRetryOptions, UseLoaderOptions, UseLoaderReturn } from './core/composables/useLoader';
 export type { UsePaginationReturn } from './core/composables/usePagination';
+export type { UseOptionsOptions, UseOptionsReturn } from './core/composables/useOptions';
+export { useOptions } from './core/composables/useOptions';
 export type { PlatformName, ThemeName, UseThemeOptions, UseThemeReturn } from './core/composables/useTheme';
 export { DEFAULT_PLATFORM, getStoredTheme, isThemeLockedLight, lockLightTheme, MOBILE_MAX_WIDTH, resolvePlatform, useTheme } from './core/composables/useTheme';
 export type { QuasarBrand } from './core/brand/quasar';