Перейти к основному содержимому

Utils

Набор утилитарных функций общего назначения для использования во всём приложении. Предоставляет методы для генерации UUID, управления вызовами функций и контроля изменения состояния.

Назначение​

Модуль решает следующие задачи:

  • Генерация уникальных идентификаторов
  • Управление частотой вызова функций (дебаунсинг)
  • Защита от нежелательных изменений состояния

Утилиты​

Генератор уникальных ID​

// Генерация гарантированно уникального идентификатора
const id = Utils.uuid();
// Пример результата: 'lrz5hd8k-01-x7q9'

// Многократная генерация в одну миллисекунду
const ids = Array(5).fill(0).map(() => Utils.uuid());
// Результаты будут гарантированно разными:
// 'lrz5hd8k-00-x7q9'
// 'lrz5hd8k-01-a2b3'
// 'lrz5hd8k-02-c4d5'
// ...

Дебаунсинг​

// Создание функции с дебаунсингом
const handleResize = Utils.debounce(() => {
    console.log('Размер окна изменён');
}, 200);

// Подписка на событие
window.addEventListener('resize', handleResize);
// Функция выполнится только через 200мс после последнего вызова

Proxy-декоратор​

// Создание защищённого состояния
const state = Utils.createProxyDecorator({
    count: 0,
    user: { name: 'John' }
});

// Попытка прямого изменения вызовет предупреждение
state.count = 1; // Предупреждение: Direct state mutation is not allowed

API​

Методы​

uuid(): string​

Генерирует уникальный идентификатор на основе текущего времени и случайного числа.

const id = Utils.uuid();

debounce(callback: Function, delay: number = 0): Function​

Создаёт функцию с задержкой выполнения.

  • callback: функция для выполнения
  • delay: задержка в миллисекундах
const debouncedFn = Utils.debounce(callback, 200);

createProxyDecorator<T>(data: T): T​

Создаёт Proxy-объект, защищающий от прямых изменений.

  • data: объект для защиты
const protected = Utils.createProxyDecorator(data);

Особенности реализации​

Генератор уникальных ID​

  • Использует комбинацию трёх компонентов:
    • timestamp: время в миллисекундах (base36)
    • counter: счётчик в пределах миллисекунды (00-zz)
    • random: 4 случайных символа для дополнительной энтропии
  • Гарантирует уникальность даже при многократной генерации в одну миллисекунду
  • Сохраняет временную последовательность (можно сортировать)
  • Формирует читаемые ID в формате 'timestamp-counter-random'

Дебаунсинг​

  • Отменяет предыдущий таймер при новом вызове
  • Сохраняет контекст и аргументы вызова
  • Поддерживает как синхронные, так и асинхронные функции

Proxy-декоратор​

  • Рекурсивно защищает вложенные объекты
  • Позволяет чтение свойств
  • Блокирует прямую запись с предупреждением

Примеры использования​

Комбинированное использование​

// Создаём защищённый объект с ID
const entity = Utils.createProxyDecorator({
    id: Utils.uuid(),
    data: {}
});

// Создаём дебаунсированную функцию сохранения
const saveEntity = Utils.debounce(async () => {
    await api.save(entity);
}, 1000);

В контексте ECS​

// Создание Entity с уникальным ID
class Entity {
    private id = Utils.uuid();
    private state = Utils.createProxyDecorator({
        components: new Map()
    });
}

Частые вопросы​

Когда использовать этот генератор вместо инкрементного ID?​

Генератор подходит для случаев, когда:

  • Нужна быстрая генерация ID без обращения к базе
  • Требуется гарантия уникальности в рамках одного процесса
  • ID генерируются в разных частях системы
  • Нужна возможность сортировки по времени создания

Как выбрать правильную задержку для debounce?​

  • Для UI событий (resize, scroll): 100-200мс
  • Для автосохранения: 500-1000мс
  • Для API запросов: зависит от частоты обновления данных

Зачем нужен createProxyDecorator?​

  • Для отслеживания изменений состояния
  • Для предотвращения случайных мутаций
  • Для поддержки паттерна иммутабельного состояния