sprof 0.9.3 → 0.9.6

package/dist/assets/styles/theme/dark.test.d.ts

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

package/dist/core/classes/FileInfo.d.ts

@@ -14,6 +14,15 @@ export default class FileInfo {
     description: string;
     order: number;
     constructor(i?: FileInfo);
+    /**
+     * Ссылка на файл: `url`, иначе `${StaticUrl}/${fileSystemPath}`.
+     *
+     * ⚠️ Если ЗАПОЛНЕНО НЕТ (осиротевшая запись `file_infos` без пути и баннера) —
+     * возвращаем ПУСТУЮ строку, а НЕ `${StaticUrl}/`. Раньше в этом случае получался
+     * `/api/static/` с пустым путём: браузер звал его при каждом рендере `<img>` и
+     * получал 404 (на pros — десятки в сутки). Пустая ссылка — сигнал вызывающему коду
+     * не рендерить картинку вовсе (см. способы применения: `if (getFileUrl())`).
+     */
     getFileUrl(): string | URL;
     getFileListObject(): {
         name: string;

package/dist/core/classes/FileInfo.test.d.ts

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

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

@@ -3,7 +3,8 @@
  *
  * - 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).
  *
  * По умолчанию работают с глобальным синглтоном FTSP.Get(); во всех трёх можно
  * передать свой экземпляр FTSP (страница/компонент) — см. T1 в TECH_DEBT.md.
@@ -12,6 +13,8 @@ export type { UseCrudOptions, UseCrudReturn } from './useCrud';
 export { useCrud } from './useCrud';
 export type { UseFiltersReturn } from './useFilters';
 export { useFilters } from './useFilters';
+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/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>;
 }