Как узнать является ли текущий файл точкой запуска?
#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 року.