В чем различие таймеров в Node.js и browser?
#nodejs_api

Сегодня обсудим setTimeout и setInterval. На обоих платформах данные функции доступны глобально и предназначены для запуска отложенного кода.

Первым аргументом должен быть TimerHandler. В #nodejs это может быть только функция, но в браузере это может быть еще и строка. К ней будет применен eval. Что безусловно является плохой практикой, так как может привести к проблемам с безопасностью. Используйте eslint правило no-implied-eval, чтобы следить за кодом.

Вторым аргументом является количество миллисекунд, а дальнейшие параметры будут переданы в качестве аргументов внутрь TimerHandler. Тут различий нет. Различие есть в возвращаемом значение. В браузере это будет число, а в Node.js объект типа NodeJS.Timeout.

NodeJS.Timeout имеет такие методы публичные методы:
- unref – отметить таймаут как не активный, т.е. он не будет удерживать EventLoop. Аналогичные вещи есть у сокетов, воркеров и т.д.
- ref – отменяет unref
- hasRef – дает текущее значение активности таймера.
- refresh – перезапускает таймер.
- close – аналогичен вызову clearInterval на таймере.

Чтобы отменить выполнение таймера используется clearInterval/clearTimeout. Они полностью заменяемы и в браузере, и в Node.js – по сути являются алиасами. Node.js в качестве аргумента принимает как число, так и NodeJS.Timeout объект.

На этом пора остановиться, хотя в рецепт не попали setImmediate, не публичные апи, особенности поведения в браузере в зависимости от активности таба, связь async_hooks и таймеров, event loop delay и прочее.

Как обнаружить синхронные операции в Node.js коде?
#nodejs_api

Каждый #nodejs разработчик знает, что блокировать Event Loop-а плохо. Блокировка может быть по двум причинам:
– cpu intensive операции, т.е. с большим количеством вычислений. Примеры: трансформация JSON объекта на 2 мегабайта, обход большого массива, подсчеты хешей.
– синхронные операции, т.е. операции которые до своего завершения блокируют Event Loop, читай дальнейшее выполнение JavaScript. Пример – все синхронные файловые операции.

Ваш код может использовать синхронные операции неявно. Кто его знает, что там в node_modules. Именно о том, как быстро найти такие места этот рецепт.

У Node.js есть специальный флаг --trace-sync-io. При его использование в консоль будут выводить trace для первого вызова любого синхронного вызова. Запускаем с этим флагом или c переменной окружения NODE_OPTIONS=--trace-sync-io и анализируем результаты. На своем проекте я так обнаружил, что пора выкинуть module-alias и переконфигурировать pino.

Рецепты по теме:
- Как запускать Node.js с доп. аргументами?

Обзор Node.js v16: Что такое corepack и как он работает?
#nodejs_api

В Node.js v16.9 добавили corepack. Данный инструмент является экспериментальным и упрощать работу с альтернативными менеджеров зависимостей. При обращение к yarn или pnpm (поддерживаемые менеджеры) будет происходит вызов установленных corepack-ом так называемые глобальных binary proxies. Данные прокси смотрят поле packageManager в package.json и вызывает соответствующую версию yarn/pnpm. При необходимости происходит установка отсутствующего менеджера. Если package.json нет, то используется LTS версия менеджера. Поддержки npm нет, так как npm устанавливается глобально вместе с Node.js. Инструмент улучшает Repeatability и решает проблему отсутствия аналогов nvm для yarn/pnp.

Мое личное отношение к альтернативным менеджерам – они расслаивают экосистему и комьюнити. Я стараюсь избегать таких вещей. В разработке хватает инструментов и проблем вызванных их обилием. Однако я понимаю почему данный инструмент необходим комьюнити. Уверен и вы поймете, если вспомните что в марте 2020 GitHub/Microsoft поглотили компанию npm. Именно в марте 2020 был написан первый коммит corepack, который тогда назывался pmm. Поэтому я считаю, что corepack это правильный шаг без которого слишком легко оказаться в тупике развития моностэка технологий.

Что нужно знать об Error stack trace?
#nodejs_api

В JavaScript есть встроенный объект Error, который сохраняет stack trace (на русском трассировка стека). Так называется список методов, которые были вызваны до момента, когда в приложении произошло ошибка. Он доступен как error.stack и выглядит так:
Error: Things keep happening!
at /home/user/file.js:525:2
at Frobnicator.refrobulate (/home/user/business-logic.js:424:21)
at Actor.<anonymous> (/home/user/actors.js:400:8)
at increaseSynergy (/home/user/actors.js:701:6)
Плохой практикой является использование throw c литералами или объектами не наследниками Error. У них не будет stack trace.

По умолчанию длина стэка ограничена 10 методами. Параметр можно изменить на уровне кода через Error.stackTraceLimit. На уровне v8 существует флаг --stack-trace-limit. Его можно передать как аргумент или через переменную окружения NODE_OPTIONS=--stack-trace-limit=10

Начиная с 12-ой версии Node.js у нас есть поддержка Async Stack Traces. Пример stack trace:
Error: Oops
at bar (/workspace/test.js:11:9)
at async run (/workspace/test.js:5:3)
Для поддержки этих stack trace рекомендуется делать await перед return. Подробней в nodebestpractices.

Если код скомпилирован с помощью babel или typescript, то правильным будет показывать stack trace для исходного кода, а не скомпилированного. Для этого использовался пакет source-map-support. Под капотом идет использование Error.prepareStackTrace. Однако сейчас Node.js умеет это делать из коробки с помощью флага --enable-source-maps

Как сделать object deep clone?
#nodejs_api

Как вы знаете объекты в отличие от примитивов передаются по ссылке, а не по значению. Поэтому, когда вам нужна копия объекта, приходиться прибегать к определенным ухищрениям.

Native JavaScript предлагает два варианта копирования:
– Через spread оператор const copied = { ...original }
– Через Object.assign const copied = Object.assign({}, original)

Эти варианты работают только на первом уровне объекта. Для глубокого копирования необходимо использовать рекурсию или пакеты (см lodash.cloneDeep). В простых случаях можно использовать JSON.parse(JSON.stringify(obj)), но имейте ввиду так можно потерять данные.

Текущий способ для Node.js это использование модуля v8:
const v8 = require('v8');
const copied = v8.deserialize(v8.serialize(original))

Но через год это измениться. Задача настолько часто встречается, что разработчики JS движков придумали structuredClone. Пока внедрено только в Firefox 94 и Node.js v17.

Как проверить, что строка timezone или encoding?
#nodejs_api

Для того, чтобы проверить что строка является таймзоной можно использовать Internationalization модуль.

function isTimezone(str) {
try {
Intl.DateTimeFormat(undefined, { timeZone: str });
return true;
} catch (ex) {
return false;
}
}

Для проверки кодировки (encoding) можно использовать Buffer.isEncoding.

Собственно цель сегодняшнего рецепта напомнить, что часть buildin modules в #nodejs являются глобальными и их не нужно импортировать.

Как отследить работу Garbage Collector?
#web_api #nodejs_api

Плохая организация JavaScript кода может привести к утечке памяти. Для отслеживания утечки ресурсов в ES2021 появился FinalizationRegistry. Так можно вызвать callback после отработки Garbage Collector по указанному ресурсу:
const registry = new FinalizationRegistry((startTime) => {
const delay = ((Date.now() - startTime) / 1000).toFixed(1);
console.log(`foo was garbage collected after ${delay}s`);
});
let foo = {};
registry.register(foo, Date.now());
foo = undefined; // Clear strong reference

⚠️Пример максимально упрощен. При запуске без массового создания новых объектов ждать сборки мусора придется долго.

Авторы не рекомендует использовать для построение бизнес логики, реализация сборки мусора, зависит от реализации любого конкретного движка JavaScript.

Работает в #nodejs 14.6.0 и новее. Для работы в TypeScript необходимо включить es2021.weakref.

Ссылки:
🔗 пример для запуска в браузере
🔗 MDN
🔗 TC39
🔗 Can I use

Как работать с Event Emitter в async/await стиле?
#nodejs_api

В 2022 году асинхронных #nodejs код строиться на async/await. Однако важный модуль Event Emitter построен на callback-ах. Начиная с 12.16 версии в нем есть встроенный функционал для упрощения работы с Promise. За это отвечают две функции:
events.on(emitter, eventName[, options]) – возвращает AsyncIterator, который легко итерировать конструкцией for await
events.once(emitter, name[, options]) – возвращает Promise, который будет разрешен по событию.
В 16 Node.js добавили options для передачи AbortController.

Упрощенный пример кода демонстрирующий обе функции:
const events = require('events');
const { setTimeout } = require('timers/promises');
const server = require('http').createServer();

async function handle(req, res) {
await setTimeout(200);
res.end('Hello World');
}

async function bootstrap() {
server.listen(8080);
await events.once(server, 'listening')
for await (const [req, res] of events.on(server, 'request')) {
await handle(req, res);
}
}

bootstrap();

⚠️В пример await handle, сделано для демонстрации работы AsyncIterator. В результате такой конструкции HttpServer будет обрабатывать запросы не параллельно, а последовательно. Чтобы это исправить можно убрать await на этой строке.

Ссылки:
⚙️ Код на runkit
📕 Документация events
👩‍🍳 Обзор AbortController

Как узнать является ли текущий файл точкой запуска?
#nodejs_api

Точка запуска (entry point) это файл, который указывается в качестве аргумента в команде node file_name.js. Зачем знать является ли текущий файл точкой запуска? Чтобы правильно организовывать код. Например, вы можете стартовать web server или экспортировать его для последующего использования в тестах.

Для проверки с CommonJS (стандарт в Node.js) используется require.main или его аналог process.mainModule. Пример, кода:
if (require.main === module) {
console.log('Entry point');
} else {
console.log('Not entry point');
}

Для ES модулей код выглядит так:
import { fileURLToPath } from 'url';
if (process.argv[1] === fileURLToPath(import.meta.url)) {
console.log('Entry point');
} else {
console.log('Not entry point');
}

Топ-5 заблуждений об работе JavaScript
#nodejs_api

На календаре пятница, а значит пора сбавить градус практичности. Сегодня поделюсь "перлам" с собеседований. Цель поста – ликвидация безграмотность.

👎Все логические операторы (&&, ||, !) возвращают булевы значения.
Вообще-то только ! возвращает Boolean.
Вопрос для выявления заблуждения, что будет выведено: console.log('0' && 3)

👎Расчет возвращаемого Promise-ом значения будет запущен при await.
Нет, он будет запущен в момент создания, т.е. как только мы создали Promise мы сразу запустили цепочку (promise chain). Где вы ставите await, и ставите ли, не имеет значения.

👎Все аргументы в функциях работают одинаково.
Как и в других языках программирования примитивные и ссылочные типы ведут себя по разному.
Вопрос для выявления заблуждения, что плохо в коде:
function getTomorrow(d) {
d.setDate(d.getDate() + 1);
return d;
}

👎Обработка событий происходит асинхронно.
Ошибка характерна и для Node.js с Event Emitter, и для FE разработчиков с Browser Events. Event handler-ы работают синхронно, причем их порядок вызова зависит от порядка добавления.

👎JavaScript обладает идеальной точностью арифметики.
Уже столько раз писали, о том что 0.1 + 0.2 == 0.3 это false, что многие это зазубрили. Однако, об этом забывают в доменах, где ошибка округления критична (финансы и т.п.). В таких случаях стоит использовать BigInt или подобные решения.

Що таке Event Loop Delay?
#nodejs_api

Node.js може обробляти одночасно кілька запитів. За це відповідає Event Loop. Синхронний код (require('fs').readFileSync) або підвищене споживання CPU (обробка великого JSON) гальмуватиме Event Loop. Для вимірювання, наскільки це відбувається, використовується метрика Event Loop Delay. Наприклад, якщо якісь endpoint блочить Event Loop Delay на 100ms, то процес не може опрацювати більше 10 таких запитів на секунду. Приклад

Чим можна вимірювати:
– існує Node.js апі perf_hooks.monitorEventLoopDelay
– це частина метрик у pm2
– prom-client та його аналоги теж збирають цю метрику

​​Огляд Node.js v18: structuredClone
#nodejs_api

Як ви знаєте об'єкти на відміну від примітивів передаються за посиланням, а не за значенням. Тому потрібно вміти робити копію об'єкта. Раніше для цього використовували spread оператор чи Object.assign. Але це працювало лише для об'єктів з одним рівнем вкладеності.

Сьогодні всі сучасні браузери підтримують structuredClone, який підтримує  deep clone та кругові посилання. Він з'явиться в Node.js 18. Приклад із документації на зображенні.

У Node.js вже зараз його можна використовувати за допомогою Structured clone polyfill.

Node.js прибирає термін native modules
#nodejs_api
Документація та source code більше не використовує терміни native чи core modules. Натомість повсюдно використовується built-in modules. Нагадаю, що з 16-ї версії такі модулі можна імпортувати з префіксом node:. Наприклад:
const http = require('node:http')
🔗 Pull

Як користуватися промісіфікованими таймерами?
#nodejs_api
У Node.js v16 змінилися принципи роботи з таймерами: додано timers/promises аналогічно fs/promises. Розглянемо best practices по роботі з ними:

1️⃣ Як підключати? Ось приклад поганого коду:
import { setTimeout } from 'timers/promises';
Тут ми робимо variables shadowing, так як перевизначаємо в поточному файлі однойменну глобальну змінну setTimeout. А ще імена built-in модулів краще писати з префіксом node:. Тобто гарний код:
import { setTimeout as wait } from 'node:timers/promises';

2️⃣ Коли який таймер використовувати?
👉 Найчастіше використовується промісіфікований setTimeout. За допомогою нього реалізується затримка виконання.
👉 За допомогою промісіфікованого setInterval створюється AsyncIterable. Приклад:
for await (const startTime of setInterval(100, Date.now())) {
if ((Date.now() - startTime) > 1000) break;
// some logic
}
👉 setImmediate використовується щоб розблокувати EventLoop. Приклад

3️⃣ Порівняння з callback таймерами
👉 callback-based доступні глобально, а промісіфіковані потрібно імпортувати.
👉 У обох випадках використовується ref, щоб визначити чи буде таймер тримати event loop активним
👉 Скасування в callback-based відбувається через clearTimeout (і його аналоги), а у промісіфікованого через AbortController.
👉 В callback-based таймерах ми можемо передати аргументи для хендлера, а промісіфікований можна сказати, яке значення буде повертати проміс.

4️⃣ Ще раз про колізії імен
Мені не подобається, що імена в callback і промісах версій співпадають. Це не створює проблем у модулі fs, так як його методи не доступні глобально, але в таймерах це ускладнює підтримку коду. Як альтернативу я рекомендую використовувати об'єкт scheduler. Виглядає це так
import { scheduler } from 'node:timers/promises';
await scheduler.wait(100);
Його додали у лютому 2022 року з флагом experimental. Аналіз коду показує, що всі його методи це синтаксичний сахар:
👉 scheduler.yield() це теж саме що setImmediate() без аргументів.
👉 scheduler.wait(delay, options) це теж саме що setTimeout(delay, undefined, options) за винятком того, що опція ref не підтримується.

Як запустити Node.js debug mode?
#nodejs_api

Для налагодження Node.js використовується Inspector Protocol. Його можна запустити:
👉 під час запуску за допомогою CLI аргументу --inspect
👉 під час запуску за допомогою env var NODE_OPTIONS='--inspect'
👉 під час роботи за допомогою відправлення SIGUSR1
👉 на рівні коду за допомогою inspector.open

Після цього до ноди можна буде підключитись за допомогою вашої IDE.

Сьогодні вийшов реліз Node.js v18.13.0.
#nodejs_api

Цей мінорний реліз містить оновлює ICU (бібліотека для інтернаціоналізації) v71.1➡️v72.1. Якщо ваш застосунок використовує активно timezone, internationalization, etс, то це оновлення є breaking change. В цьому випадку краще використовувати system-icu. Зміна Time Zone Database 2022a➡️2022e означає правильний правопис нашої таймзони 🇺🇦 Europe/Kyiv

Повний опис у блозі. Для нових Docker images чекаємо pull.

Як завдання не варто вирішувати за допомогою Node.js?
#nodejs_api #list

👉 CPU Intensive Tasks, тобто завдання, що навантажують процесор. Типова відповідь на інтерв'ю включає лише цей варіант. Якщо таке завдання необхідно вирішити, то тут варто використовувати передкалькуляцію з кешуванням або Worker threads/Child process.
👉 Aggregation, окремий випадок CPU Intensive завдання, у якому требо разрахувати якісь метрики. Наприклад, мінімальна/максимальна ціна за торговий день. Тут краще використовувати функції DB.
👉 Compression. Ми перекладаємо це завдання на інфраструктуру, щоб зайвий раз не навантажувати процесор.
👉 Rate Limiting. Ще одне типове завдання для інфраструктури, інакше легко заблокувати масштабування.
👉 Serve Static. За це має відповідати CDN, у якому Node.js може бути лише джерелом статики.
👉 File Uploads. Не варто використовувати Node.js як проксі для завантаження файлу в S3. Для цього є signed url.

Як не втрачати stack trace?
#nodejs_api

Сьогодні ми обговоримо, що робити з помилками, у яких stack trace закінчується at processTicksAndRejections (node:internal/process/task_queues)

Багато популярних пакетів викидають помилки таким чином, що stack trace обривається у коді самого пакета. Це ускладнює відлагодження таких виключень, оскільки втрачається стек викликів у коду додатка. Нажаль, у багатьох випадках контрибутори пакетів відхиляють запити на виправлення цієї проблеми. Приклади:
- Improve axios stack traces axios/axios#2387
- Missing stack trace on errors stripe/stripe-node#1066

Якщо пакет популярний, то ком'юніті запропонує якісь рішення. Наприклад axios-better-stacktrace.

Загальним рішенням є використання try-catch та викидати нову помилки з cause. Нагадую, що ми маємо Error: cause з Node v16.9.0. Для цього я використовую такий хелпер:

export function reThrow(reason: unknown, errorConstructor: ErrorConstructor = Error): never {
const errorMessage = reason instanceof Error ? reason.message : errorConstructor.name;
const error = new errorConstructor(errorMessage, { cause: reason });
Error.captureStackTrace(error, reThrow);
throw error;
}

Error.captureStackTrace(... видаляє з stack trace рядки хелпера.

Приклад використання:
const session = await stripeClient.billingPortal.sessions.create({customer: ''}).catch(reThrow);

🚀 Вийшов реліз Node.js v22.15.0
#nodejs_api

У цьому мінорному оновленні є два важливі моменти, на які варто звернути увагу.

1️⃣ Оновлення бази часових поясів: tzdata 2024b → 2025a
Деталі змін у реліз-нотах tzdata 2025a.
Якщо ваш застосунок має бізнес-логіку, що залежить від таймзон, це оновлення може стати breaking change. Щоб уникнути подібних ризиків у майбутньому, краще використовувати system-ICU, щоб оновлювати таймзони незалежно від оновлень Node.js.

2️⃣ Зʼявився новий метод process.execve() — системний виклик, який повністю замінює поточний процес на новий, зберігаючи той самий PID. Приклад:
console.log('Before execve pid:', process.pid);
try {
process.execve('/bin/sh', ['sh', '-c', 'echo After execve pid: $$']);
} catch (err) {
console.error('execve failed:', err);
}
Що це означає для Node.js розробників?
🐳 Мінімалістичний init-процес на JS у Docker-контейнерах: наприклад, можна спочатку отримати секрети з AWS Secrets Manager, а потім запускати основну програму, як треба по 12 Factor.
🔁 Hot-reload без втрати PID: перезапуск застосунку без його зупинки — актуально для IoT-пристроїв або embedded-систем.
⚠️ Новий вектор атак: тепер можливе підміщення логіки без зміни PID, що вимагає додаткової уваги до безпеки.

Як і навіщо перевіряти, що код запущено під потрібною версією Node.js?
#nodejs_api

Використання нових можливостей nodejs або сучасного синтаксису мови може призвести до того, що ваш застосунок не запуститься на застарілій версії Node.js. Тому варто перевіряти версію Node.js і кидати необроблену помилку, якщо код запущено під неправильною версією. Робити це потрібно у файлі входу (entry point), з якого запускається все застосування. Таким чином ви гарантуєте, що середовище, в якому розробляється ваш код і яке буде використовуватися на інших оточеннях чи комп'ютерах інших розробників, буде те саме.

Приклад коду:

const expectedVersion = '22.16.0';
if (process.versions.node !== expectedVersion) throw new Error(`App requires node.js version ${expectedVersion}`);

Під час оновлення версії Node.js ми змінюємо expectedVersion у коді, Dockerfile і GitHub actions.

PS Це повтор рецепту від 2021 року.