@endge/utils 0.24.12 → 0.24.14

package/dist/serialize/Serialize.d.ts

@@ -0,0 +1,14 @@
+import { ClassConstructor } from 'class-transformer';
+/**
+ * Описывает ответственность Serialize в архитектуре проекта.
+ */
+export declare class Serialize {
+    /**
+     * Выполняет действие toPlain в рамках ответственности Serialize.
+     */
+    static toPlain<T>(instance: T): any;
+    /**
+     * Выполняет действие fromJSON в рамках ответственности Serialize.
+     */
+    static fromJSON<T>(cls: ClassConstructor<T>, json: any): T;
+}

package/dist/serialize/decorators/json.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Декоратор для преобразования JSON-поля:
+ * - сериализует объект - строку
+ * - десериализует строку - объект
+ *
+ * Пример:
+ * @Json()
+ * collection: Record<string, any> = {}
+ */
+export declare function Json(): PropertyDecorator;

package/dist/serialize/decorators/jsonString.d.ts

@@ -0,0 +1 @@
+export declare function JsonString(): PropertyDecorator;

package/dist/serialize/decorators/onDeserialized.d.ts

@@ -0,0 +1,2 @@
+export declare function onDeserialized(): MethodDecorator;
+export declare function getOnDeserializedMethod<T>(instance: T): (() => void) | null;

package/dist/serialize/decorators/script.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Декоратор для хранения текста скрипта:
+ * - сериализует как обычную строку
+ * - десериализует строку, очищая лишние пробелы
+ *
+ * Пример:
+ * @Script()
+ * code: string = ''
+ */
+export declare function Script(): PropertyDecorator;

package/dist/serialize/decorators/typeMap.d.ts

@@ -0,0 +1,55 @@
+import { ClassConstructor } from 'class-transformer';
+/**
+ * Декоратор @TypeMap для автоматической сериализации и десериализации `Map<K, V>`.
+ * Поддерживает два формата JSON:
+ * 1. **Объект - `Map<K, V>`** (если `keyField` не указан)
+ * 2. **Массив - `Map<K, V>`** (если указан `keyField`)
+ *
+ * @param valueType - Класс значений в `Map<K, V>`.
+ * @param keyField - (необязательно) Поле, используемое как ключ (`name`, `id`, и т. д.).
+ *
+ * ## Пример использования (объект - `Map`)
+ * ```typescript
+ * export class ReflectDomain {
+ *   @TypeMap(RType) // JSON-объект { key: value } - Map<string, RType>
+ *   private types: Map<string, RType> = new Map()
+ * }
+ * ```
+ * **JSON**
+ * ```json
+ * {
+ *   "types": {
+ *     "User": { "name": "User", "fields": {} },
+ *     "Company": { "name": "Company", "fields": {} }
+ *   }
+ * }
+ * ```
+ * **Результат**
+ * ```typescript
+ * ReflectDomain.types // Map<string, RType>
+ * ReflectDomain.getType('User') // RType('User')
+ * ```
+ *
+ * ## Пример использования (массив - `Map`)
+ * ```typescript
+ * export class ReflectDomain {
+ *   @TypeMap(RType, 'name') // JSON-массив [{ name: value }, ...] - Map<string, RType>
+ *   private types: Map<string, RType> = new Map()
+ * }
+ * ```
+ * **JSON**
+ * ```json
+ * {
+ *   "types": [
+ *     { "name": "User", "fields": {} },
+ *     { "name": "Company", "fields": {} }
+ *   ]
+ * }
+ * ```
+ * **Результат**
+ * ```typescript
+ * ReflectDomain.types // Map<string, RType>
+ * ReflectDomain.getType('User') // RType('User')
+ * ```
+ */
+export declare function TypeMap<V>(valueType: ClassConstructor<V>, keyField?: keyof V): PropertyDecorator;

package/dist/serialize/decorators/typeRecord.d.ts

@@ -0,0 +1,59 @@
+import { ClassConstructor } from 'class-transformer';
+/**
+ * Декоратор `@TypeRecord` для автоматической (де)сериализации полей типа `Record<string, V>`.
+ * Работает аналогично `@Type(() => V)`, но для структур, где ключами являются строки (как у обычного объекта),
+ * а значениями — экземпляры определённого класса.
+ *
+ * Используется с библиотекой `class-transformer`.
+ *
+ * @param valueType - Класс значений, содержащихся в `Record<string, V>`.
+ *
+ * @example
+ * ```ts
+ * import { Expose } from 'class-transformer'
+ *
+ * class RField {
+ *   @Expose()
+ *   name!: string
+ * }
+ *
+ * class Component {
+ *   @Expose()
+ *   @TypeRecord(RField)
+ *   inputFields!: Record<string, RField>
+ * }
+ * ```
+ *
+ * ## Пример JSON:
+ * ```json
+ * {
+ *   "inputFields": {
+ *     "user": { "name": "user" },
+ *     "email": { "name": "email" }
+ *   }
+ * }
+ * ```
+ * После `plainToInstance(Component, json)`:
+ * ```ts
+ * component.inputFields // Record<string, RField>
+ * component.inputFields.user instanceof RField // true
+ * ```
+ *
+ * ## Пример сериализации:
+ * ```ts
+ * const component = new Component()
+ * component.inputFields = {
+ *   user: new RField("user"),
+ *   email: new RField("email"),
+ * }
+ *
+ * const json = instanceToPlain(component)
+ * // json = {
+ * //   inputFields: {
+ * //     user: { name: "user" },
+ * //     email: { name: "email" }
+ * //   }
+ * // }
+ * ```
+ */
+export declare function TypeRecord<V>(valueType: ClassConstructor<V>): PropertyDecorator;

package/dist/serialize/useStorageDebounced.d.ts

@@ -0,0 +1,2 @@
+import { Ref } from 'vue';
+export declare function useStorageDebounced<T>(key: string, initial: T, fromJSON?: (data: any) => T, toJSON?: (data: T) => any, delay?: number): Ref<T>;

package/dist/shared/serialize/decorator.d.ts

@@ -0,0 +1,15 @@
+import { ExposeOptions } from 'class-transformer';
+import { ValidationOptions } from 'class-validator';
+export declare function GenericExpose(options: ExposeOptions): (target: object, propertyKey: string | symbol) => void;
+export declare function BeforeSerialize(): (target: any, propertyKey: string, _descriptor: PropertyDescriptor) => void;
+export declare function AfterDeserialize(target: any, propertyKey: string, _descriptor: PropertyDescriptor): void;
+export declare function IsOptionalTransformed(validationOptions?: ValidationOptions): (object: object, propertyName: string) => void;
+export interface ISerializable {
+    toPlain(): any;
+    toJson(): string;
+}
+export declare function DeserializeId(): PropertyDecorator;
+export declare function DeserializeArrayField(field: string): PropertyDecorator;
+export declare function SerializeId(): PropertyDecorator;
+export declare function SerializeIds(): PropertyDecorator;
+export declare function IgnoreToPlain(): PropertyDecorator;

package/dist/shared/serialize/parse.d.ts

@@ -0,0 +1,3 @@
+import { ClassConstructor } from 'class-transformer';
+export declare function toInstance<T>(ctor: ClassConstructor<T>, json: object): T;
+export declare function toPlain<T>(obj: T): object;

package/dist/shared/types/getter-fn.d.ts

@@ -0,0 +1,3 @@
+import { Maybe } from './maybe';
+type GetterFn<T> = (x: T) => Maybe<T>;
+export default GetterFn;

package/dist/shared/types/maybe.d.ts

@@ -0,0 +1,2 @@
+export type Maybe<T> = T | null | undefined;
+export declare function isNullOrUndefined<T>(value: T | null | undefined): value is null | undefined;

package/dist/shared/utils/compare.d.ts

@@ -0,0 +1 @@
+export declare function compareNumber(a: any, b: any): number;

package/dist/shared/utils/generate.d.ts

@@ -0,0 +1,2 @@
+export declare const generateUUID: () => string;
+export declare function randomString(length: number): string;

package/dist/shared/utils/keyboard.d.ts

@@ -0,0 +1,9 @@
+export interface KeyCombo {
+    ctrl?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+    meta?: boolean;
+    key: string;
+}
+export type KeyComboArray = Array<KeyCombo>;
+export declare function isAnyKeyComboActive(combos: KeyComboArray, event: KeyboardEvent): boolean;

package/dist/shared/utils/text.d.ts

@@ -0,0 +1 @@
+export declare function capitalize(val: unknown): string;

package/dist/shared/utils/time.d.ts

@@ -0,0 +1,41 @@
+export interface DateRange {
+    start: Date;
+    end: Date;
+}
+export declare function isAfterOrEqual(dateA: Date, dateB: Date): boolean;
+export declare function isDateRangeOverlap(s1: Date, s2: Date, validFrom: Date, validTo: Date): boolean;
+export declare function isDateInRange(date: Date, validFrom: Date, validTo: Date): boolean;
+export declare const parseDate: (isoString: string) => "" | Date;
+export declare function formatDatetime(date: Date, formatString?: string, options?: {}): string;
+export declare function formatDatetimeTZ(date: Date | string | object, formatString?: string, options?: {}, isLocalTime?: boolean): string;
+export declare function getDayOfWeek(date: any): string;
+export declare function formatDateToMSK(date: any): string;
+export declare function extractTime(date: Date | string | object, isLocalTime?: boolean): string;
+export declare function findMinMaxDates(dates: Set<Date>): {
+    minDate: Date;
+    maxDate: Date;
+};
+export declare function diffDuration(d1: Date, d2: Date): string;
+export declare function diffDurationTable(d1: Date, d2: Date): string;
+export declare function removeTime(date?: Date): Date;
+export declare function getDateOnlyDiffFactor(d1: Date, d2: Date): {
+    variant: 'red' | 'blue';
+    value: string;
+} | null;
+export declare function toIsoZDate(value: string): string | null;
+export declare function toIsoZDateTime(value: string): string | null;
+export declare function isoToDateInput(value: unknown): string;
+export declare function isoToDateTimeLocalInput(value: unknown): string;
+/** Formats a DateTime as `HH:mm` in the configured IANA timezone or browser-local timezone. */
+export declare function isoDateTimeToTimeInput(value: unknown, timezone?: unknown): string;
+/** Replaces only hours and minutes while preserving the DateTime calendar date in the selected timezone. */
+export declare function mergeTimeIntoDateTime(value: unknown, time: unknown, timezone?: unknown): string | null;
+export declare function timeToTimeInput(value: unknown): string;
+export declare function toTimeHHMMSS(value: unknown): string | null;
+export declare function parseDuration(duration: string): string;
+export declare function formatDatetimeTZSpecial(date?: Date | string | object | null, formatString?: string, options?: {}): string;
+/**
+ * Возвращает первую найденную IANA-таймзону с данным смещением (например, "+03:00").
+ */
+export declare function parseOffsetToTimezone(offsetStr: string): string | null;
+export declare function getTimezoneOffsetMs(timezone: string): number;

package/dist/tools/compare.d.ts

@@ -0,0 +1 @@
+export { compareNumber } from '../shared/utils/compare';

package/dist/tools/console.d.ts

@@ -0,0 +1,4 @@
+/** Returns a bounded string without traversing or retaining the supplied value. */
+export declare function consoleValueSummary(value: unknown): string;
+/** Returns Error metadata as text without forwarding the Error object to Console. */
+export declare function consoleErrorSummary(error: unknown): string;

package/dist/tools/debug.d.ts

@@ -0,0 +1,2 @@
+export declare const IS_DEBUG: boolean;
+export declare function profile<T>(label: string, fn: () => T): T;

package/dist/tools/generate.d.ts

@@ -0,0 +1 @@
+export { generateUUID, randomString } from '../shared/utils/generate';

package/dist/tools/geometry.d.ts

@@ -0,0 +1,15 @@
+export interface DataRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface DataSize {
+    width: number;
+    height: number;
+}
+export interface DataPoint {
+    x: number;
+    y: number;
+}
+export type Side = 'left' | 'right' | 'top' | 'bottom';

package/dist/tools/hotkeys.d.ts

@@ -0,0 +1,56 @@
+type HotkeyHandler = (event: KeyboardEvent) => void;
+interface HotkeyManagerOptions {
+    ignoreInput?: boolean;
+    target?: EventTarget;
+}
+/**
+ * Управляет ресурсами и состоянием HotkeyManager.
+ */
+export declare class HotkeyManager {
+    private bindings;
+    private enabled;
+    private readonly target;
+    private readonly ignoreInput;
+    private readonly handleBound;
+    /**
+     * Создает экземпляр HotkeyManager и подготавливает базовое состояние.
+     */
+    constructor(options?: HotkeyManagerOptions);
+    /**
+     * Выполняет внутренний шаг isIgnoredTarget для HotkeyManager.
+     */
+    private isIgnoredTarget;
+    /**
+     * Нормализует входные данные HotkeyManager.
+     */
+    private normalizeKey;
+    /**
+     * Обрабатывает runtime-событие HotkeyManager.
+     */
+    private handle;
+    /**
+     * Обрабатывает входящее событие HotkeyManager.
+     */
+    on(keys: string | Array<string>, handler: HotkeyHandler): void;
+    /**
+     * Выполняет действие off в рамках ответственности HotkeyManager.
+     */
+    off(keys: string | Array<string>, handler: HotkeyHandler): void;
+    /**
+     * Очищает накопленное состояние HotkeyManager.
+     */
+    clear(key?: string): void;
+    /**
+     * Выполняет действие enable в рамках ответственности HotkeyManager.
+     */
+    enable(): void;
+    /**
+     * Выполняет действие disable в рамках ответственности HotkeyManager.
+     */
+    disable(): void;
+    /**
+     * Освобождает runtime-ресурсы и подписки HotkeyManager.
+     */
+    destroy(): void;
+}
+export {};

package/dist/tools/keyboard.d.ts

@@ -0,0 +1,21 @@
+export { isAnyKeyComboActive, type KeyCombo, type KeyComboArray } from '../shared/utils/keyboard';
+export type KeyboardStatePlatform = 'macos' | 'windows' | 'linux' | 'unknown';
+export interface KeyboardStateSnapshot {
+    platform: KeyboardStatePlatform;
+    modifiers: {
+        ctrl: boolean;
+        shift: boolean;
+        alt: boolean;
+        meta: boolean;
+        mod: boolean;
+        altGraph: boolean;
+    };
+    held: {
+        key: string[];
+        code: string[];
+    };
+}
+/** Returns the shared document-scoped keyboard snapshot, installing one tracker lazily. */
+export declare function getKeyboardStateSnapshot(target: Document): KeyboardStateSnapshot;
+/** Subscribes to the shared document-scoped keyboard state and immediately emits its snapshot. */
+export declare function subscribeKeyboardState(target: Document, listener: (snapshot: KeyboardStateSnapshot) => void): () => void;

package/dist/tools/logs.d.ts

@@ -0,0 +1,176 @@
+import { Subscribable } from '../events/Subscribable';
+/**
+ * Структурированная запись лога.
+ *
+ * @example
+ * {
+ *   timestamp: 1692826342203,
+ *   level: 'info',
+ *   message: 'Компонент успешно собран',
+ *   context: ['components', 'DriverCard'],
+ *   actions: [
+ *     {
+ *       icon: 'ti ti-eye',
+ *       tooltip: 'Посмотреть компонент',
+ *       handler: () => alert('Открываю DriverCard'),
+ *     },
+ *   ],
+ * }
+ */
+export interface StructuredLogEntry {
+    /** Время создания лога (timestamp в ms) */
+    timestamp: number;
+    /** Уровень лога: _debug, info, warn или error */
+    level: 'debug' | 'info' | 'warn' | 'error' | 'success';
+    /** Сообщение лога */
+    message: string;
+    /** Контекст (иерархия вложенности) */
+    context: Array<string>;
+    /** Дополнительные действия (например, кнопки для лога) */
+    actions?: Array<{
+        icon: string;
+        tooltip?: string;
+        handler: () => void;
+    }>;
+}
+/**
+ * Логгер с поддержкой:
+ * - Иерархического контекста (`context`, `start`, `end`).
+ * - Разных уровней (`_debug`, `info`, `warn`, `error`).
+ * - Action-кнопок для каждого лога.
+ * - Подписки на обновления (через `Subscribable`).
+ *
+ * @example
+ * const logger = new StructuredLogger()
+ *
+ * // Устанавливаем контекст
+ * logger.context('components', 'DriverCard')
+ *
+ * // Логируем сообщение
+ * logger.info('Компонент успешно собран')
+ *
+ * // Добавляем действие
+ * logger.warn('Предупреждение', [
+ *   { icon: 'ti ti-alert', tooltip: 'Подробнее', handler: () => alert('Подробнее!') },
+ * ])
+ *
+ * // Используем вложенные уровни
+ * logger.start('attributes').info('Загрузка атрибутов')
+ * logger.end()
+ *
+ * // Получаем все логи
+ * const logs = logger.getLogs()
+ */
+export declare class StructuredLogger extends Subscribable {
+    /** Массив всех логов */
+    private logs;
+    /** Текущий контекст (иерархия) */
+    private currentContext;
+    private currentActions;
+    /**
+     * Устанавливает текущий контекст.
+     * Сбрасывает предыдущий контекст.
+     *
+     * @param context Массив строк или несколько строк с уровнями контекста.
+     * @returns _surface (для цепочки вызовов)
+     * @example
+     * logger.context('components', 'DriverCard')
+     */
+    context(...context: Array<string>): this;
+    /**
+     * Добавляет дополнительный уровень контекста.
+     *
+     * @param context Новый уровень (например, 'attributes').
+     * @returns _surface (для цепочки вызовов)
+     * @example
+     * logger.start('attributes')
+     */
+    start(context: string): this;
+    /**
+     * Убирает последний уровень контекста.
+     * При этом может сразу добавить финальный лог, связанный с этим контекстом.
+     *
+     * @param level Уровень лога (по умолчанию 'info')
+     * @param message Сообщение лога (опционально)
+     * @param actions Дополнительные действия (опционально)
+     * @example
+     * logger.end('info', 'Компиляция завершена', [...])
+     */
+    end(level?: 'debug' | 'info' | 'warn' | 'error' | 'success', message?: string, actions?: StructuredLogEntry['actions']): this;
+    /**
+     * Добавляет экшены в текущий контекст (для следующего `end`)
+     * @param icon Иконка (например, "ti ti-check text-xl")
+     * @param tooltip Подсказка (опционально)
+     * @param handler Функция при клике (опционально)
+     * @example
+     * logger.action('ti ti-check', 'Все успешно', () => console.logFrame('Успешно!'))
+     */
+    action(icon: string, tooltip?: string, handler?: () => void): this;
+    /**
+     * Внутренний метод для создания лога.
+     *
+     * @param level Уровень (_debug, info, warn, error)
+     * @param message Сообщение
+     * @param actions Дополнительные действия (иконки с обработчиками)
+     */
+    private log;
+    /**
+     * Лог уровня _debug.
+     *
+     * @param message Сообщение
+     * @param actions Дополнительные действия (опционально)
+     * @example
+     * logger._debug('Загрузка данных')
+     */
+    debug(message: string, actions?: StructuredLogEntry['actions']): void;
+    /**
+     * Лог уровня info.
+     *
+     * @param message Сообщение
+     * @param actions Дополнительные действия (опционально)
+     * @example
+     * logger.info('Загрузка завершена')
+     */
+    info(message: string, actions?: StructuredLogEntry['actions']): void;
+    /**
+     * Лог уровня warn.
+     *
+     * @param message Сообщение
+     * @param actions Дополнительные действия (опционально)
+     * @example
+     * logger.warn('Низкий заряд батареи')
+     */
+    warn(message: string, actions?: StructuredLogEntry['actions']): void;
+    /**
+     * Лог уровня error.
+     *
+     * @param message Сообщение
+     * @param actions Дополнительные действия (опционально)
+     * @example
+     * logger.error('Ошибка загрузки', [
+     *   { icon: 'ti ti-refresh', tooltip: 'Повторить', handler: () => retry() },
+     * ])
+     */
+    error(message: string, actions?: StructuredLogEntry['actions']): void;
+    /**
+     * Лог уровня success.
+     *
+     * @param message Сообщение
+     * @param actions Дополнительные действия (опционально)
+     * @example
+     * logger.success('Успешно', [
+     *   { icon: 'ti ti-refresh', tooltip: 'Повторить', handler: () => retry() },
+     * ])
+     */
+    success(message: string, actions?: StructuredLogEntry['actions']): void;
+    /**
+     * Получить все логи.
+     *
+     * @returns Массив логов
+     */
+    getLogs(): Array<StructuredLogEntry>;
+    /**
+     * Очистить все логи (полностью).
+     */
+    clear(): void;
+}

package/dist/tools/reflect.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Проверяет, является ли переданная функция конструктором.
+ */
+export declare function isConstructor<T extends new (...args: Array<any>) => any>(fn: any): fn is T;
+/**
+ * Утилитарный тип: или конструктор, или фабрика.
+ */
+export type ConstructorOrFactory<T, Args extends Array<any> = Array<any>> = (new (...args: Args) => T) | ((...args: Args) => T);
+/**
+ * Универсальный вызов: конструктор или фабрика.
+ */
+export declare function createInstance<T, Args extends Array<any>>(source: ConstructorOrFactory<T, Args>, ...args: Args): T;

package/dist/tools/state.d.ts

@@ -0,0 +1 @@
+export declare function globalState<T>(factory: () => T): () => T;

package/dist/tools/system-clock.d.ts

@@ -0,0 +1,14 @@
+import { DateTime } from 'ts-luxon';
+export declare const SystemClock: {
+    DateTime: typeof DateTime;
+    toDateTime(jsDate: Date): DateTime;
+    fromFormat(text: string, format: string, opts: any): DateTime;
+    fromISO(text: string, opts?: any): DateTime | null;
+    getNow(): DateTime;
+    getNowUTC(): DateTime;
+    getToday(): DateTime;
+    getTime(format?: string): string;
+    getUTCTime(format?: string): string;
+    getZone(): import('ts-luxon').Zone;
+};
+export declare const dt: (date: Date) => DateTime;

package/dist/tools/text.d.ts

@@ -0,0 +1 @@
+export { capitalize } from '../shared/utils/text';

package/dist/tools/time.d.ts

@@ -0,0 +1 @@
+export * from '../shared/utils/time';