Декоратор `withDebounce`

Декоратор withDebounce (дребезг) — это инструмент оптимизации, который применяется в сценариях с высокой частотой генерации событий, когда нам важен строго финальный результат после того, как поток действий полностью прекратился или затих на определенное время.

В отличие от троттлинга, дебаунс полностью игнорирует промежуточные состояния и сбрасывает таймер ожидания при каждом новом действии пользователя. Запрос отправляется один раз только тогда, когда наступает фаза «тишины».

1. Асинхронная валидация полей ввода (Формы регистрации / Оформления)

Проблема без декоратора: Нам нужно проверять уникальность введенного email, username или промокода на сервере прямо во время ввода (интерактивный UX). Если вешать сетевой запрос на событие onChange, то при вводе строки user@example.com приложение сделает 16 последовательных тяжелых HTTP-запросов к базе данных (на каждую букву). Это создаст колоссальную паразитную нагрузку на сеть и сервер.
Решение с Debounce: Декоратор блокирует отправку данных, пока пользователь активно стучит по клавиатуре. Как только человек завершает ввод слова или делает паузу (например, на 500 мс), дебаунс понимает, что ввод окончен, и отправляет один-единственный, финальный и чистый запрос на валидацию.

2. Поиск по каталогу или фильтрация (Search Input)

Проблема: Пользователь вводит поисковый запрос в интернет-магазине, например смартфон apple iphone. Без оптимизации приложение начнет фильтровать базу данных и перерисовывать тяжелые списки товаров уже на слове с, затем на см, затем на сма и т.д. Пользователь увидит хаотично прыгающую выдачу товаров, а сервер получит лавину бесполезных поисковых транзакций.
Решение с Debounce: Вы выставляете задержку delay: 400. Пока пользователь набирает фразу, сеть молчит, а интерфейс работает отзывчиво. Запрос улетает к API только тогда, когда пользователь дописал мысль до конца.

3. Автосохранение черновиков (Текстовые редакторы / Блоги)

Проблема: Пользователь пишет длинную статью, пост или заполняет большое описание задачи в Jira/Confluence. Нам нужно сохранять черновик в облачную базу данных, чтобы текст не потерялся при случайном закрытии вкладки. Делать сохранение на каждое нажатие клавиши — значит слать сотни запросов в минуту и забивать базу микро-апдейтами.
Решение с Debounce: Настраивается большой дебаунс (например, delay: 2000 — две секунды). Пока пользователь непрерывно печатает абзац текста, сохранения не происходит. Как только автор остановился подумать над следующей мыслью или сделал паузу на 2 секунды, декоратор автоматически синхронизирует и сохраняет текущий текст на сервер.

4. Элементы управления с ползунками (Sliders / Range Inputs / Цветовые палитры)

Проблема: В интерфейсе есть ползунок выбора ценового диапазона (<input type="range">) или пипетка выбора цвета. Когда пользователь плавно тащит ползунок мышкой, событие генерируется непрерывно (сотни раз в секунду). Если этот ползунок триггерит тяжелый пересчет цен, сложную аналитическую выборку или отправку координат на сервер, интерфейс начнет сильно лагать.
Решение с Debounce: Декоратор полностью замораживает вычисления и сетевую активность на время перетаскивания. Выдача результатов или обновление данных на сервере произойдет ровно один раз — в тот момент, когда пользователь отпустит ползунок мыши в финальной позиции.

Сводная шпаргалка по декораторам ресурсов:

withDebounce — Нужен, когда важен только финальный результат после того, как пользователь затих (пример: валидация формы при вводе email).
withThrottle — Нужен, когда важен процесс в динамике, но порциями (пример: плавное рисование на холсте, анимация куба Three.js при ресайзе).
withThrottleAndCache — Нужен, когда важен процесс в динамике, но данные внутри этого процесса имеют свойство повторяться на коротком промежутке времени (пример: скролл, перемещение карт, живой поиск).

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

import { AbstractService } from '@pravosleva/reactive-engine'

// Наш декоратор дебаунса (wip)
interface DebounceOptions {
  delay?: number
}

export const withDebounce = <S, T>(
  fetcher: (source: S, signal: AbortSignal) => Promise<T>,
  options: DebounceOptions = {}
) => {
  const delay = options.delay ?? 300
  let timeoutId: ReturnType<typeof setTimeout> | null = null
  let rejectPrevious: ((reason: any) => void) | null = null

  return (source: S, signal: AbortSignal): Promise<T> => {
    if (timeoutId) clearTimeout(timeoutId)
    if (rejectPrevious) {
      rejectPrevious(new DOMException('Aborted due to debounce', 'AbortError'))
    }

    return new Promise<T>((resolve, reject) => {
      rejectPrevious = reject

      const onAbort = () => {
        if (timeoutId) clearTimeout(timeoutId)
        reject(new DOMException('Aborted by resource signal', 'AbortError'))
      }

      if (signal.aborted) return onAbort()
      signal.addEventListener('abort', onAbort)

      timeoutId = setTimeout(async () => {
        signal.removeEventListener('abort', onAbort)
        rejectPrevious = null
        timeoutId = null

        try {
          const data = await fetcher(source, signal)
          resolve(data)
        } catch (error) {
          reject(error)
        }
      }, delay)
    })
  }
}

// Сам бизнес-сервис
export class SearchLogic extends AbstractService {
  // Сигнал, куда React-инпут будет записывать текст на каждый символ
  public querySignal = this.createSignal<string>('', 'search:signal:query')

  /**
   * Реактивный ресурс, обёрнутый в декоратор withDebounce.
   * Движок автоматически перезапускает его при изменении querySignal,
   * но декоратор принудительно задерживает реальное выполнение на 500 мс.
   */
  public searchResource = this.engine.resource(
    withDebounce(
      async (queryValue, abortSignal) => {
        // Имитируем задержку ответа от сервера (например, чтение из базы)
        await new Promise((resolve) => setTimeout(resolve, 400))

        // Фейковый результат поиска
        // В этом месте возвращается массив строк исключительно ради наглядности демонстрации в UI
        // (чтобы в блоке результатов под инпутом можно было отрендерить список с помощью метода .map()).
        return [
          `Результат 1 для "${queryValue}"`,
          `Результат 2 для "${queryValue}"`,
          `Результат 3 для "${queryValue}"`
        ]
      },
      { delay: 500 } // Задержка дебаунса 500 мс
    ),
    this.querySignal,
    {
      name: 'search:resource:fetch',
      // Не отправляем запрос, если инпут пустой
      validateBeforeFetch: (queryValue) => !!queryValue.trim()
    }
  )

  /**
   * Экшен обновления поисковой строки из UI
   */
  public updateQuery(val: string) {
    this.querySignal.value = val
  }
}

tsx

import { ReactiveEngine, useReactiveValue } from '@pravosleva/reactive-engine'
import { SearchLogic } from './service.SearchLogic'
import { Input } from '~/shared/Input'
import baseClasses from '~/ui.common.module.scss'
import clsx from 'clsx'

const engine = new ReactiveEngine()

export const SearchExample = () => {
  const logic = engine.inject(SearchLogic)

  // Подписываемся на сигналы и ресурс
  const query = engine.use(logic.querySignal)
  const { loading, data: results, error } = useReactiveValue(logic.searchResource)

  return (
    <div
      className={clsx(baseClasses.unit, baseClasses.stack2)}
      style={{
        fontFamily: 'system-ui',
        width: 'max(100px, calc(100vw - 24px - 24px - 24px - 24px - 16px - 16px - 4px - 4px))'
      }}
    >
      <div className={baseClasses.absoluteUnitLabel}>Simple Debounce Search Demo</div>

      {/* Поле ввода текста */}
      <div className={baseClasses.stack1} style={{ width: '100%', color: '#000' }}>
        <label style={{ fontSize: 'small' }}>Живой поиск (дебаунс 500мс):</label>
        <Input
          variant='outlined'
          type="text"
          placeholder="Начните вводить текст..."
          value={query}
          onChange={(e) => logic.updateQuery(e.target.value)}
        />
      </div>

      {/* Статус-бар загрузки */}
      <div className={baseClasses.stack1} style={{ fontSize: 'small' }}>
        {
          loading
            ? <span style={{ color: '#e6af2e' }}>⏳ Ждем окончания ввода и ответа сервера...</span>
            : (query && !results)
              ? <span>Печатайте дальше...</span>
              : <span>Печатайте дальше...</span>
        }
        {error && <span style={{ color: '#ef5350' }}>❌ Ошибка: {error.message}</span>}
      </div>

      {/* Отрендеренный список результатов */}
      <div style={{ display: 'flex', flexDirection: 'column', gap: '6px', width: '100%' }}>
        <div style={{ fontSize: 'small' }}>Результаты выдачи:</div>
        <div style={{ background: '#111', borderRadius: '6px', padding: '12px', minHeight: '80px', display: 'flex', flexDirection: 'column', gap: '6px', fontSize: '13px' }}>
          {results && results.map((item, idx) => (
            <div key={idx} style={{ color: '#4caf50' }}>{item}</div>
          ))}
          {!query.trim() && <span style={{ color: '#aaa' }}>Строка поиска пуста</span>}
          {query.trim() && !loading && !results && <span style={{ color: '#aaa' }}>Запрос задебаунсен...</span>}
        </div>
      </div>
    </div>
  )
}

Декоратор withDebounce ​

1. Асинхронная валидация полей ввода (Формы регистрации / Оформления) ​

2. Поиск по каталогу или фильтрация (Search Input) ​

3. Автосохранение черновиков (Текстовые редакторы / Блоги) ​

4. Элементы управления с ползунками (Sliders / Range Inputs / Цветовые палитры) ​

Сводная шпаргалка по декораторам ресурсов: ​