Перейти к содержимому
Поиск
Разработка

p-queue: очередь задач JavaScript — лимиты, отмена и 9 практических примеров

Управляем пачками асинхронных задач: девять опытов с настоящей p-queue, прогресс, ограничения, пауза, отмена и ошибки. Мастерская, Node.js и исходники.

Александр Некрасов
p-queue: очередь задач JavaScript — лимиты, отмена и 9 практических примеров — обложка

p-queue: очередь Promise с понятным управлением

Приложению часто нужно выполнить много похожих действий: получить карточки клиентов, проверить ссылки, скачать документы, обновить справочник или подготовить превью. Если запустить всё сразу, можно перегрузить API, память или соединения. Если выполнять строго по одному, пользователь будет ждать дольше, чем необходимо. Между этими крайностями нужна управляемая очередь.

p-queue позволяет ограничить число одновременно выполняемых задач и частоту их запуска. Поверх этого можно построить приоритеты, паузу, отмену, тайм-ауты и понятный прогресс пачки. Библиотека работает с функциями, возвращающими Promise: HTTP-запросами, асинхронной обработкой файлов и другими операциями вашего приложения.

В статье разберём девять практических сценариев. На странице можно менять лимит, наблюдать очередь, приостанавливать работу и исследовать ошибки. Исходники включают настоящий планировщик, отдельный Node.js-пример с реальными HTTP-запросами, тесты и команды Windows/Linux. При этом мы явно разделим управление Promise, долговечную серверную очередь и параллельные CPU-вычисления.

Где применять: импорт, интеграции и действия в интерфейсе

В CRM очередь полезна при обновлении сведений по нескольким клиентам. В административном кабинете — при проверке пакета документов или формировании набора небольших запросов. В интеграции она помогает соблюдать допустимое число обращений к внешнему API, а в утилите импорта позволяет видеть, какие записи уже обработаны и какие требуют повторной попытки.

Для человека важен не только общий процент. Он должен понимать, сколько операций ожидает, сколько выполняется, что завершилось успешно и где возникла проблема. Пауза означает возможность временно прекратить новые запуски, отмена — отказаться от оставшейся работы, а повтор — осознанно обработать подходящие ошибки. Эти действия имеют разный смысл и должны отличаться в интерфейсе.

Начинайте с конкретного ограничения. Например, сервис допускает два запроса одновременно и не больше пяти стартов в секунду. Затем определите поведение при ошибке: продолжать независимые записи или остановить всю пачку. p-queue даёт механизмы планирования, но правила сохранения результата, повторов и уведомлений остаются частью вашего приложения.

p-queue, Promise.all, BullMQ и рабочие потоки

Promise.all удобно ждать результаты уже запущенных операций, но сам по себе он не ограничивает их число. Если создать тысячу fetch сразу, тысяча запросов уже начнёт свою работу до ожидания. p-queue принимает функции и решает, когда их вызвать. Именно отложенный запуск позволяет контролировать нагрузку.

Очередь p-queue находится в памяти одного процесса или вкладки. После перезапуска ожидающие задачи исчезают; другой процесс не видит этот список и не разделяет его лимиты. Для устойчивых фоновых задач с хранением, отдельными worker и восстановлением на сайте есть материал про BullMQ. Это другой уровень организации работы.

Concurrency также не создаёт CPU-потоки. Длинный синхронный цикл по-прежнему блокирует JavaScript-поток, даже если его положить в очередь. Для тяжёлых вычислений полезны worker threads и пул вроде Piscina. p-queue можно использовать вокруг таких операций для ограничения подачи, но сама библиотека не переносит вычисление в другой поток.

Потребность Подход
Подождать уже созданные Promise Promise.all / allSettled
Ограничить запуск внутри одного процесса p-queue
Сохранить задания после перезапуска Хранилище и серверная очередь, например BullMQ
Не блокировать поток тяжёлыми вычислениями Worker threads / пул Piscina

Мини-мастерская: девять опытов с настоящей p-queue

Выберите сценарий, установите число одновременных операций и нажмите запуск. Карточки проходят состояния ожидания, выполнения, успеха, ошибки или отмены. Над ними показаны счётчики, ниже — журнал событий с временем. После завершения можно скачать JSON и сравнить два запуска с разными настройками.

Планировщик p-queue здесь настоящий. Сами задания учебные: локальные таймеры разбиты на пять этапов и поддерживают AbortSignal. Проценты показывают эти этапы, а не сетевой трафик. Файлы и запросы наружу не отправляются. Для реальной HTTP-проверки в ZIP есть tools/http-demo.mjs, который поднимает собственный временный сервер и выполняет восемь запросов.

Такое разделение позволяет свободно изучать отмену и повторы прямо в статье. Смена сценария во время опыта отключена, чтобы старые результаты не смешались с новыми. Экспорт доступен только для завершённого опыта и сбрасывается после изменения параметров. Если хотите видеть больше карточек и журнал одновременно, откройте мастерскую отдельной вкладкой.

Версия 10: ESM, EventTarget и совместимость примеров

В проекте используется p-queue 10.0.0. Это ESM-пакет, поэтому примеры написаны через import, а package.json содержит type:module. Для лаборатории выбран Node.js 24 LTS; минимальное требование зависимости — Node 22. Точный набор пакетов закреплён в lock-файле, оформление использует Bootstrap 5.3.9.

В десятой версии очередь является EventTarget. Подписка выполняется через addEventListener, удаление — через removeEventListener. Старые примеры с queue.on относятся к предыдущему API и не должны механически переноситься в этот проект. Также важно читать актуальное поведение тайм-аутов, отмены и очистки ожидающих задач.

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

{
  "name": "aen-p-queue-workshop",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "license": "MIT",
  "engines": {
    "node": ">=22"
  },
  "scripts": {
    "build": "node tools/build.mjs",
    "start": "node tools/server.mjs",
    "test": "node --test tests/*.test.mjs"
  },
  "dependencies": {
    "bootstrap": "5.3.9",
    "p-queue": "10.0.0",
    "esbuild": "0.27.4"
  }
}

Windows: установить и запустить лабораторию

Распакуйте ZIP в отдельную папку, откройте PowerShell и проверьте Node.js. После npm ci запустите тесты, затем build и start. Сборка создаёт локальные JavaScript/CSS и точный просмотрщик исходников. Браузеру не требуется обращаться к CDN, а Redis для этой лаборатории не нужен.

По умолчанию мастерская доступна на http://127.0.0.1:8596/. Сервер слушает только локальный интерфейс. Остановка выполняется Ctrl+C в той же консоли. Если порт занят, задайте PORT, а не завершайте неизвестный процесс. Папка public уже включена в архив, но после изменения src её необходимо пересобрать.

Отдельно выполните node tools/http-demo.mjs. Скрипт создаёт временный HTTP-сервер, отправляет восемь настоящих запросов, проверяет максимум двух одновременных обращений и закрывает сервер. Одна учебная запись отвечает 503: ожидаемый итог — семь успехов и одна обработанная ошибка. Для этой проверки не нужны внешний API, учётная запись или секреты.

node --version
npm ci
npm test
npm run build
npm start

# В отдельной консоли:
node tools/http-demo.mjs

# Другой порт мастерской, если нужен:
$env:PORT = "8597"
npm start

Linux и Docker: повторить тот же проект

На Linux команды установки и сборки такие же. Используйте обычного пользователя проекта и Node.js 24 LTS. Временный сервер можно оставить на loopback, а для доступа с собственного компьютера открыть SSH-туннель. Это позволяет проверить мастерскую на VPS, не публикуя отладочный порт в интернет.

Dockerfile создаёт отдельную среду Node для тестов. Два запуска ниже проверяют очередь и настоящую HTTP-интеграцию. Контейнеры удаляются после завершения и не требуют пользовательских томов. Не выполняйте глобальную очистку Docker ради окончания этой лаборатории: она может затронуть чужие проекты и данные.

Для постоянного размещения интерфейса достаточно статической папки public. Для настоящего импорта нужен отдельный Node-скрипт с понятным источником данных и политикой завершения. Эти два способа описаны дальше. Браузерная мини-мастерская и серверная задача могут использовать одну библиотеку, но у них разные условия жизни и сохранения результата.

npm ci
npm test
npm run build
node tools/http-demo.mjs
PORT=8596 npm start

# Доступ к loopback-серверу на VPS:
ssh -L 8596:127.0.0.1:8596 user@your-server

docker build -t aen-p-queue-lab .
docker run --rm --name aen-p-queue-tests aen-p-queue-lab
docker run --rm --name aen-p-queue-http aen-p-queue-lab node tools/http-demo.mjs

Основной контракт: передавать функцию, а не готовый Promise

Очередь должна управлять моментом начала операции. Поэтому add получает функцию, которая выполнит работу позже. Если вызвать fetch заранее и передать уже созданный Promise, ограничение запуска потеряет смысл: запрос уже начался. Это одна из самых частых ошибок при первом знакомстве с очередями Promise.

Promise, возвращаемый add, завершается вместе с результатом задачи. Его нужно обработать, включая отклонение. Не ставьте await перед каждым add в обычном цикле, если хотите параллельность: тогда следующая задача будет добавлена только после предыдущей. Вместо этого соберите Promise результатов и дождитесь всей пачки отдельно.

Функция задачи получает signal. Передавайте его операции, которая умеет останавливаться, например fetch. Приложение должно хранить ID задачи отдельно от её позиции в массиве, чтобы поздний ответ или повтор не перепутал карточки. В мастерской это T1, T2 и далее; в продукте используйте устойчивый идентификатор записи или операции.

import PQueue from 'p-queue';
const queue = new PQueue({ concurrency: 3 });
const results = ids.map(id => queue.add(async ({ signal }) => {
  const response = await fetch(`/api/clients/${id}`, { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}).then(
  value => ({ id, ok: true, value }),
  error => ({ id, ok: false, error: error.message })
));
const report = await Promise.all(results);
await queue.onIdle();

Пример 1. Параллельный импорт и ограничение concurrency

В первом опыте восемь карточек обрабатываются независимо. При concurrency:1 одновременно выполняется одна операция, при значении три — до трёх. Как только одна завершилась, очередь запускает следующую. Общая длительность меняется, но порядок завершения не обязан совпадать с порядком добавления.

Лимит выбирают по реальному узкому месту: допустимым соединениям, скорости API, памяти на операцию и отзывчивости приложения. Значение «чем больше, тем лучше» редко работает бесконечно. На практике увеличение параллельности сначала сокращает ожидание, затем начинает усиливать ошибки, конкуренцию за ресурсы и задержки.

В мастерской показаны одновременно pending библиотеки и собственный максимум реально активной учебной работы. Это особенно важно для тайм-аутов: освобождённый слот очереди не всегда означает прекращение побочной операции. Для вашего сервиса измеряйте не только общий секундомер, но и число ошибок, время отдельных запросов и потребление ресурсов.

const queue = new PQueue({ concurrency: 3 });
const tasks = records.map(record =>
  queue.add(() => importRecord(record))
    .then(value => ({ ok: true, value }))
    .catch(error => ({ ok: false, message: error.message }))
);
const result = await Promise.all(tasks);

Пример 2. Частота запусков и скользящее окно

Concurrency ограничивает одновременную работу, но не число быстрых запросов за секунду. Если каждый запрос занимает десять миллисекунд, даже один слот может сделать много обращений. Для ограничения частоты используются intervalCap и interval. В мастерской разрешены два старта за 1200 миллисекунд.

Включён strict:true: учитывается скользящее окно. Это важно, когда API запрещает больше заданного числа запусков в любом отрезке времени, а не только в условных фиксированных секундах. При обычных фиксированных окнах на границе возможен короткий всплеск. Выбирайте режим по фактическим правилам провайдера и проверяйте реальные ответы сервера.

Локальный лимит одной очереди не распределяется между процессами, вкладками или серверами. Если каждый экземпляр приложения разрешит два запроса, их общая частота будет выше. Для общего ограничения нужен согласованный механизм. Даже с правильным локальным лимитом обрабатывайте 429 и Retry-After: внешняя система может учитывать дополнительные запросы и собственные правила.

const queue = new PQueue({
  concurrency: 3,
  intervalCap: 2,
  interval: 1200,
  strict: true
});
queue.addEventListener('rateLimit', () => showWaitingMessage());
queue.addEventListener('rateLimitCleared', () => hideWaitingMessage());

Пример 3. Приоритет срочной задачи

В опыте с приоритетом очередь сначала собирается на паузе. У T6 установлен priority:10, у остальных — ноль. После запуска она начинается первой. Такой сценарий полезен, когда интерактивное действие пользователя должно получить слот раньше большой фоновой пачки, которая ещё не начала выполняться.

Приоритет влияет на ожидающие задачи. Он не прерывает уже работающий запрос и не отменяет его побочный эффект. Поэтому обещание «срочная задача выполнится немедленно» было бы неверным: свободного слота может пока не быть. Если задержка критична, продумайте отдельную очередь или резерв ресурса, а не только большее число priority.

Не делайте все новые задачи высокоприоритетными. Старые операции могут долго не получать очередь. В продукте нужна понятная политика: какие действия действительно срочные, сколько таких задач допускается и как пользователь увидит ожидание обычной пачки. Мастерская показывает механизм порядка, а справедливость распределения остаётся вашей прикладной задачей.

const queue = new PQueue({ concurrency: 1, autoStart: false });
const regular = queue.add(() => loadRegular(), { priority: 0 });
const urgent = queue.add(() => loadUrgent(), { priority: 10 });
queue.start();
await Promise.allSettled([regular, urgent]);

Пример 4. Пауза не останавливает уже начатое

Нажмите паузу во время опыта. Новые карточки перестанут запускаться, но уже выполняющиеся дойдут до своего результата. После их завершения pending станет нулём, а size останется положительным: в очереди есть ожидающая работа. Кнопка продолжения снова разрешит запуск.

Такой режим удобен, когда оператору нужно временно снизить нагрузку или проверить входные данные перед продолжением. Он не равен отмене запроса. Текст интерфейса должен прямо объяснять, что начатые операции продолжаются, иначе человек может решить, что отправка или запись уже прекращена.

Если нужно изменить общие настройки только после завершения активных задач, можно вызвать pause, затем дождаться onPendingZero. При этом ожидающие задачи сохраняются. Перед возобновлением убедитесь, что они совместимы с новыми настройками и не содержат устаревших данных. Для настоящего импорта изменения правил в середине пачки желательно журнализировать.

queue.pause();
await queue.onPendingZero();
// Активных задач нет, ожидающие ещё могут оставаться.
applyNewSettings();
queue.start();

Пример 5. Тайм-аут и реальная остановка операции

В сценарии тайм-аута T3 специально выполняется дольше лимита 650 миллисекунд. Отсчёт начинается, когда задача получила слот и начала работу, а не в момент её добавления. Ожидание в очереди и длительность самой операции — разные интервалы; для общего срока жизни пачки нужен отдельный контроль.

В p-queue 10 тайм-аут отменяет signal задачи и отклоняет Promise от add с TimeoutError. Но функция должна поддержать этот сигнал. Если она продолжит тяжёлую работу или сетевой запрос без signal, слот уже освободится, а побочная операция ещё останется активной. Это может привести к нагрузке выше ожидаемого лимита.

Наш учебный sleep действительно очищает таймер и отклоняет Promise при отмене. В HTTP-примере signal передаётся fetch. В вашем коде проверьте каждую библиотеку ввода-вывода и её способ остановки. Если отмена не поддерживается, честно учитывайте продолжающуюся работу и не выдавайте тайм-аут ожидания за гарантированное прекращение действия.

const queue = new PQueue({ concurrency: 2, timeout: 650 });
try {
  await queue.add(async ({ signal }) => {
    const response = await fetch(url, { signal });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  });
} catch (error) {
  if (error.name === 'TimeoutError') showTimeout();
  else showError(error);
}

Пример 6. Отмена всей пачки через AbortController

Для пачки создаётся один AbortController. Его signal передаётся каждому add, а библиотека передаёт соответствующий сигнал внутрь функции. Нажатие отмены снимает ожидающие задачи и сообщает активным операциям, что нужно завершиться. Уже успешно полученные результаты остаются в отчёте.

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

Отмена на клиенте не означает откат на сервере. Запрос мог уже создать запись или отправить письмо до разрыва соединения. Для операций с побочными эффектами нужен ID операции и возможность проверить итог. Важные действия проектируют с идемпотентностью и явным состоянием, а не считают, что AbortController способен отменить всё произошедшее.

const batch = new AbortController();
const promise = queue.add(
  ({ signal }) => fetch(url, { signal }),
  { signal: batch.signal }
).catch(error => ({ cancelled: batch.signal.aborted, error: error.name }));

batch.abort(new DOMException('Пачка отменена', 'AbortError'));
await promise;

Пример 7. Частичная ошибка и ограниченный повтор

В опыте повторов T3 один раз получает временный отказ, ждёт небольшую паузу и успешно выполняется со второй попытки. T5 завершается постоянной ошибкой неправильных данных. Остальные карточки продолжают работу. Итог показывает семь успехов и одну ошибку, а у T3 сохранено число попыток.

p-queue не выбирает эту политику за приложение. Повтор написан явно внутри нашей задачи и ограничен двумя попытками. В таком варианте ожидание перед повтором занимает слот concurrency. Это просто и прозрачно для небольшой лаборатории; для больших систем можно планировать повтор иначе, но нужно не потерять общий результат и лимиты.

Разделяйте временные и постоянные ошибки. Сетевой сбой иногда можно повторить, а неверный формат документа обычно требует исправления данных. Ограничивайте число попыток, учитывайте Retry-After и добавляйте разумную задержку. Для неидемпотентного действия повтор без ключа операции способен создать дубликат, даже если первая попытка выглядела неуспешной.

await queue.add(async ({ signal }) => {
  for (let attempt = 1; attempt <= 2; attempt++) {
    try {
      return await sendIdempotentRequest({ signal, operationId });
    } catch (error) {
      if (!isTemporary(error) || attempt === 2) throw error;
      await sleep(180, signal);
    }
  }
});

Пример 8. Производитель ждёт свободное место в очереди

Ограничение concurrency не ограничивает количество ожидающих задач. Если прочитать огромный файл и сразу создать Promise для каждой строки, память всё равно будет занята всей пачкой. Для постепенной подачи используется backpressure: производитель ждёт, пока очередь станет достаточно короткой.

В мастерской двенадцать операций поступают постепенно. Перед добавлением следующей вызывается onSizeLessThan(2). Это ограничивает ожидающий список; активные задачи считаются отдельно. При отмене контроллер проверяется до и после ожидания, чтобы производитель не продолжил добавлять новые задания после решения пользователя остановиться.

Для настоящего импорта читайте входной поток порциями и записывайте результаты по мере завершения. Даже с короткой очередью массив всех результатов способен занять много памяти. Лаборатория сохраняет небольшой отчёт целиком ради наглядности, но миллион строк требует другой стратегии хранения. Также учитывайте нескольких производителей: каждый из них должен участвовать в общей политике подачи.

for await (const record of inputStream) {
  if (batch.signal.aborted) break;
  await queue.onSizeLessThan(2);
  if (batch.signal.aborted) break;
  const result = queue.add(
    ({ signal }) => processRecord(record, signal),
    { signal: batch.signal }
  );
  result.then(saveSuccess, saveFailure);
}
await queue.onIdle();

Пример 9. Изменить concurrency во время работы

В последнем сценарии можно двигать ползунок, пока пачка выполняется. Увеличение concurrency позволяет запустить дополнительные ожидающие задачи. Уменьшение не отменяет уже начатые операции: их текущее число некоторое время может быть выше нового лимита. Ограничение начнёт действовать для следующих стартов.

Это полезно для управляемого импорта, где оператор временно снижает нагрузку, или для адаптации по состоянию сервиса. Но автоматическое изменение лимита требует устойчивой логики: слишком частые колебания могут сделать поведение непредсказуемым. Сначала соберите измерения и определите допустимый диапазон, затем добавляйте адаптацию.

В мастерской диапазон ограничен одним–четырьмя слотами. Это удобное число карточек для сравнения, а не универсальное ограничение p-queue. После завершения изменение ползунка сбрасывает готовность экспорта, чтобы старый отчёт не выглядел результатом новых параметров. Для новой конфигурации нужно явно запустить новый опыт.

queue.concurrency = 4; // следующие задачи могут стартовать быстрее
queue.concurrency = 1; // активные не отменяются, новые ждут слот

Счётчики size и pending: почему «очередь пуста» недостаточно

size показывает ожидающие задачи, pending — задачи, которые библиотека считает выполняющимися. Когда последняя ожидающая операция получила слот, size уже равен нулю, но работа ещё не закончена. Поэтому onEmpty нельзя использовать как единственный сигнал «все результаты готовы».

onIdle ожидает и пустого списка, и завершения активных задач. В мастерской дополнительно ожидаются Promise результатов, чтобы состояния карточек успели перейти в итоговый вид. Это помогает отделить событие планировщика от сохранения прикладного результата: запись отчёта в базу или файл может быть самостоятельным действием, которое тоже нужно учитывать.

Для тайм-аутов и отмены помните о функции, игнорирующей signal. Она может продолжать побочную работу после освобождения слота. Наш стенд отслеживает реальную активность отдельно и проверяет, что она становится нулевой. В вашем приложении определите, что именно считается завершением: ответ API, сохранение файла, подтверждение транзакции или доставка уведомления.

console.log({ waiting: queue.size, running: queue.pending });
await queue.onEmpty(); // ожидающих больше нет, активные возможны
await queue.onIdle();  // очередь пуста и активных по её учёту нет

События EventTarget и обработка каждой ошибки

В версии 10 используется addEventListener. Это знакомая модель браузерных событий, доступная и в современном Node. Для completed и error значение находится в event.detail. Подписки можно удалять тем же обработчиком или привязать к отдельному AbortSignal жизненного цикла интерфейса.

Событие ошибки удобно для общего индикатора и журнала, но оно не заменяет обработку Promise от add. Если задача отклоняется, её результат нужно явно принять через catch, второй обработчик then или allSettled. Иначе ошибка может стать необработанным отклонением и завершить Node-процесс либо оставить интерфейс в непонятном состоянии.

В мастерской каждый add превращается в объект успешного или неуспешного результата, поэтому одна ожидаемая ошибка не разрушает всю пачку. В другом продукте может быть нужна остановка при первом отказе. Выберите политику явно и объясните её пользователю: «остальные записи продолжаются» и «пачка остановлена» означают разные действия и разные ожидания.

const listenerLife = new AbortController();
queue.addEventListener('completed', event => {
  console.log('Результат:', event.detail);
}, { signal: listenerLife.signal });
queue.addEventListener('error', event => {
  console.error('Ошибка задачи:', event.detail);
}, { signal: listenerLife.signal });

// При уходе интерфейса удаляем эти подписки:
listenerLife.abort();

clear в версии 10 и различие между очисткой и отменой

Метод clear удаляет ожидающие задачи, но не останавливает уже выполняющиеся. В p-queue 10 Promise удалённых задач отклоняются с AbortError; эти удалённые задачи не исполняются и не создают событие error. Такое поведение важно проверять именно для используемой версии, поскольку старые обсуждения могут описывать другую реализацию.

Для понятной отмены всей пачки в нашем проекте выбран общий AbortController. Он связывает ожидающие и активные операции одной причиной остановки. Если применить только clear, активные запросы продолжат работу, а интерфейсу всё равно придётся правильно обработать их поздние результаты.

Не используйте очистку как замену сохранению состояния. Если задания нужно восстановить завтра, их необходимо хранить вне памяти процесса. Для административной кнопки «отменить оставшееся» заранее определите, что произойдёт с уже завершёнными результатами, какие запросы ещё выполняются и можно ли повторить часть пачки без дубликатов. Именно эти правила делают управление безопасным и понятным.

queue.clear(); // удаляет ожидающие, активные продолжаются

// Для нашей пачки используем сигнал, поддержанный операциями:
batch.abort(new DOMException('Отмена по запросу пользователя', 'AbortError'));

Прогресс: этапы операции и общий результат пачки

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

В учебных операциях прогресс состоит из пяти одинаковых этапов. Это специально обозначено в мастерской. Для настоящей загрузки прогресс берут из переданных байтов, для импорта — из обработанных записей, для многошаговой операции — из подтверждённых этапов. Если измерения нет, честный индикатор «выполняется» лучше выдуманного процента.

Полезно показывать успехи, ошибки и отмены раздельно. Итоговый отчёт должен позволять найти проблемные ID и понять причину. В журнал не стоит копировать целиком персональные данные, токены и содержимое документов. Для диагностики обычно достаточно ID операции, длительности, номера попытки, категории ошибки и безопасного описания следующего действия.

const finished = tasks.filter(task =>
  ['done', 'error', 'timeout', 'cancelled'].includes(task.status)
).length;
const batchPercent = tasks.length ? finished / tasks.length * 100 : 0;
// Это доля завершённых карточек, а не прогноз оставшегося времени.

Настоящий Node.js HTTP-пример из архива

tools/http-demo.mjs создаёт собственный временный сервер и получает его свободный порт. Клиентская очередь выполняет восемь fetch с concurrency:2. Сервер считает реально активные запросы, задерживает ответ и для записи номер пять возвращает учебный 503. После завершения скрипт проверяет число обращений, максимум параллельности и результаты.

Этот пример показывает, как заменить таймерную операцию настоящим вводом-выводом. Важно проверять response.ok: fetch сам по себе не превращает HTTP 503 в отклонённый Promise. После проверки статуса приложение разбирает JSON и сохраняет результат либо понятную ошибку конкретного ID.

Временный сервер закрывается в finally, поэтому проверка не оставляет процесс слушать порт после окончания. При переносе на внешний API уберите учебный сервер, задайте разрешённый endpoint, добавьте авторизацию и политику повторов. Не помещайте секреты в браузерную сборку: серверные токены должны оставаться в серверной среде.

const queue = new PQueue({ concurrency: 2, timeout: 3000 });
const outcomes = ids.map(id => queue.add(async ({ signal }) => {
  const response = await fetch(`${endpoint}/clients/${id}`, { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}).then(
  value => ({ ok: true, value }),
  error => ({ ok: false, error: error.message })
));
const rows = await Promise.all(outcomes);

Linux/VPS: запуск одноразовой задачи через systemd

Для реального импорта удобно создать отдельного системного пользователя и каталог приложения. Установите зависимости из lock-файла, проверьте скрипт вручную под нужной учётной записью, затем оформите запуск через systemd. Абсолютный путь Node в ExecStart должен соответствовать вашей установке; command -v node помогает его уточнить.

В архиве unit имеет Type=oneshot и запускает локальную HTTP-проверку. Он завершается после выполнения, не является постоянным worker и не создаёт долговечную очередь. Для расписания можно добавить systemd timer или другой согласованный механизм. Не включайте бесконечный Restart для одноразового действия без понимания повторных побочных эффектов.

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

# Educational one-shot HTTP integration check, not a durable job worker.
[Unit]
Description=p-queue local integration check
After=network.target
[Service]
Type=oneshot
User=queue-demo
WorkingDirectory=/opt/queue-demo
ExecStart=/usr/bin/node tools/http-demo.mjs
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
StandardOutput=journal
StandardError=journal
sudo systemctl daemon-reload
sudo systemctl start p-queue-demo.service
sudo journalctl -u p-queue-demo.service --no-pager -n 40
# Type=oneshot после успеха может иметь состояние inactive (dead).

Разместить мастерскую как статику через Nginx

Публичная мастерская не требует постоянно работающего Node-процесса. После npm run build скопируйте public в отдельный каталог и добавьте location в существующий HTTPS server. Храните исходный проект и серверные настройки вне публичной папки. Посетителю нужны только собранные ресурсы и отдельный архив исходников.

Перед изменением конфигурации сохраните её копию, затем выполните nginx -t и reload. Убедитесь, что app.js отдаётся с JavaScript Content-Type, sources.json доступен, а относительные пути работают под выбранным префиксом. HTTP 200 на index.html ещё не подтверждает работу очереди: нужно запустить опыт и проверить изменения карточек.

Для интеграции в существующий кабинет отделите стили мастерской от глобальных правил сайта. Карточки и длинный JSON не должны расширять всю страницу на телефоне. На сайте также есть подробные материалы про повседневные настройки Nginx и Caddy; их можно использовать как продолжение после локального запуска.

# Put inside your existing HTTPS server block.
location /queue-lab/ {
    alias /var/www/queue-lab/;
    index index.html;
    add_header X-Content-Type-Options nosniff;
    # Include the standard mime.types at http level; .js must be text/javascript.
}
sudo install -d /var/www/queue-lab
sudo cp -a public/. /var/www/queue-lab/
sudo nginx -t
sudo systemctl reload nginx
curl -I https://your-domain/queue-lab/app.js

Память, несколько процессов и восстановление после сбоя

Очередь Promise удобна, пока её жизненный цикл соответствует жизненному циклу процесса. Закрытие вкладки или перезапуск Node уничтожает ожидающий список. Если задача должна пережить это событие, сохраните её описание и результат в надёжном хранилище либо выберите серверную очередь с подходящими гарантиями.

Несколько экземпляров p-queue также не создают общий лимит. При четырёх процессах с concurrency:3 одновременно могут выполняться до двенадцати операций, а внешняя система может считать их как одну нагрузку. В распределённой среде ограничение должно учитывать всех участников. Локальная очередь остаётся полезной как дополнительный предел внутри каждого процесса.

Не храните в ожидающих замыканиях большие буферы без необходимости. Лучше передавать ID и загружать данные непосредственно перед обработкой, если это соответствует требованиям. Результаты длинного импорта записывайте постепенно. Для восстановления сохраняйте подтверждённые этапы и ключи идемпотентности, а не только красивый процент на странице.

Тесты, мобильная проверка и границы результата

Проект содержит двенадцать тестов настоящей p-queue: последовательность и параллельность, приоритет, скользящий лимит, пауза и продолжение, тайм-аут с остановкой операции, общая отмена, повтор, ограниченная подача и изменение concurrency. Проверки используют ускоренные учебные интервалы, но вызывают реальную библиотеку и проверяют её результат.

Отдельная HTTP-проверка подтверждает восемь реальных запросов, семь успешных ответов, одну ожидаемую ошибку и максимум двух активных обращений. Команды доступны для Windows и Linux. Эти проверки не заменяют браузерную приёмку: кнопки, читаемость карточек, переполнение и состояния мастерской проверяются отдельно на узкой и широкой странице.

При переносе в продукт добавьте условия своего API: ответы 429, долгие соединения, повреждённый JSON, истёкшую авторизацию и частично сохранённые результаты. Мобильная эмуляция помогает найти проблемы раскладки, но не подтверждает поведение фоновой вкладки и ограничений ресурсов на каждом физическом телефоне. Для критичного сценария нужна проверка на целевых устройствах.

npm test
node tools/http-demo.mjs
npm run build

# Пользовательская приёмка:
# пауза → активные завершились → продолжить;
# отмена → все оставшиеся получили итог;
# timeout T3 → 7 успехов и 1 тайм-аут;
# retry T3 → 2 попытки, T5 → постоянная ошибка.

Исходники и первый полезный сценарий внедрения

Начните с небольшой независимой пачки: проверка нескольких записей или загрузка карточек из собственного API. Ограничьте concurrency, обработайте результат каждой задачи и добавьте понятный итог. После этого подключайте отмену, частоту и повторы. Такой порядок позволяет увидеть пользу без сложной инфраструктуры раньше времени.

В ZIP находятся исходники интерфейса, контроллер опытов, реальные Node HTTP-примеры, тесты, Dockerfile, варианты запуска и готовая статика. Просмотрщик на странице показывает те же файлы. Авторский код распространяется по MIT, лицензии зависимостей сохранены отдельно. После правок запускайте тесты и сборку, чтобы скачиваемые материалы и работающая мастерская оставались согласованными.

Подробности API доступны в официальной документации p-queue 10, поведение отмены — в описании AbortSignal, а границы CPU-параллельности — в документации worker_threads. Практический результат — управляемая пачка, у которой понятны нагрузка, ошибки, завершение и возможность продолжить работу без догадок.