Self-documenting code

Fwdays team продовжує підтримувати захисників та захисниць України 🇺🇦, до чого закликаємо і вас!

В рамках конференції Software Architecture fwdays'22, 16 вересня (п’ятниця) о 17:00 (GMT+3) ми проведемо благодійний live stream з Дмитром "Метр": Артилерія і технології.

У мирному житті Дмитро – Lead DevOps Engineer у Kasta, наразі Дмитро "Метр" – військовослужбовець 45 оабр, лейтенант.

Ведучий стріму – Олександр Соловйов.

Під час стріму будемо обговорювати теми артилерії та технологій, кібер сек’юріті, волонтерство, відносин армії, людей і грошей. Також, кожен зможе приєднатись до обговорення і поставити своє питання Дмитру чи Олександру.

І, вже традиційно, ми збиратимемо кошти для наших бійців з передової.
🎯 Наша ціль – зібрати 200 000 грн на покращення інфраструктури розвідки 45 оабр (мережеве і комп'ютерне обладнання, покращення автомобілів тощо).

Серед 10 найбільших донейтів ми рандомно розіграємо сувеніри від 45 оабр🎁

Дізнатись більше про стрім, теми, а також задонейтити вже зараз – https://fwdays.com/event/architecture-fwdays-2022/review/artillery-and-technologies

Посилання на Youtube стрім – https://bit.ly/3BCBltp
Ставте нагадування, підписуйтесь і до зустрічі завтра!

Слава Україні! 💙💛

Як безкоштовно отримати Cloud Digital Leader?

Cloud Digital Leader є початковою сертифікацією. Її наявність показує, що власник розуміє як працює GCP. Цільова аудиторія: інженери без досвіду роботи в Cloud та менеджери. Детальніше. Звичайна ціна сертифікації 99 $ (55 $ для України).

Індійська компанія Hack2skill проводить Cloud Tech Camp. У його рамках відбудеться роздача ваучерів на безкоштовну сертифікацію.

Алгоритм дій:
1. Реєстрація на cloudskillsboost
2. Реєстрація на tech camp. Реєстрацію на першу когорту ще не закрили.
3. Отримуємо всі 4 бейджі. Для отримання необхідно пройти quizzes (перегляд відео не є обов'язковим). Кожен курс із переглядом відео займає близько години. Якщо ж використовивати google, то можна вкластися за 30 хвилин на всі 4 бейджі.
4. У dashboard вже є посилання для отримання ваучера. Основне в цій google-формі це посилання на ваш публічний профайл з cloudskillsboost, де є бейджи.
5. Нагадаю, проводять індуси. Тому не варто витрачати час на перегляд вебінару або участь у WhatsApp.
6. Опціонально. Зареєструватись на Associate Cloud Engineer.

знайшов у пошті, що OpenJS Foundation оголосило до кінця місяця знижку 60% на Node.js сертифікації. Промокод JAVA60

Нагадаю, що існує дві сертифікації:
1️⃣ OpenJS Node.js Services Developer (JSNSD) – простіша, потребує досвіду, як робити Web API.
2️⃣ OpenJS Node.js Application Developer (JSNAD) – складніша, потребує розуміння всій Node.js документації.

Сертифікацію можна буде скласти протягом року. Промокод працює на бандли сертифікація + курс. Але курси там відверто слабкі, і я б їх не рекомендував.

PS Промокод викликає сміх 😂, але він працює.

​​Нагадаю, що в JavaScript є label та їх необхідно використовувати у вкладених циклах для вказівки з якого саме циклу вийти за допомогою break/continue.

Що таке .nvmrc?
#cli
Для локальної розробки я рекомендую встановлювати Node.js через nvm. Це дозволяє легко перемикатися між версіями Node.js.

Після встановлення nvm необхідно налаштувати ваш shell, щоб nvm use автоматично викликався при заході в папку де є .nvmrc. Як це зробити описано тут.

Залишилося створити .nvmrc:
node -v > .nvmrc
git commit -am 'Add nvmrc'

PS Не плутайте .npmrc та .nvmrc

Як правильно налаштувати TypeScript?
#typenoscript

Більшість стартерів генерує неправильний tsconfig.json. Наприклад, після nest new project-name необхідно правильно налаштувати compilerOptions.target. Детальніше

Є такий репозиторій tsconfig/bases. З нього генеруються пакети виду @tsconfig/node18. Я рекомендую починати tsconfig.json із "extends": "@tsconfig/node18/tsconfig.json" і перевизначати тільки потрібні параметри. Для фанатів типізації можна використовувати @tsconfig/node18-strictest

Детальніше в репозиторії. Там, до речі, є і React.

Що таке glob шаблони (або globbing)?
#cli #npm

JavaScript розробники нерідко роблять помилку у glob шаблонах. Ми їх використовуємо, щоб задати маску для файлів. Приклад:
eslint --fix 'src/*.js'.

Ці glob шаблони (або globbing) йдуть з Unix та нагадують RegExp. У JavaScript екосистемі є пакет minimatch який конвертую glob шаблон у RegExp. Звичайно ж, є і пакет glob від того самого автора, який є обгорткой до minimatch. Тому зустрічається термін minimatch syntax (приклад у eslint). Але правильний термін – glob/globbing.

Покажу, як виглядає типова помилка у використанні:
prettier --write 'src/*.js'
Очікування: будуть переформатовані всі файли у src.
Реальність: будуть переформатовані лише файли на першому рівні вкладеності.

Треба мати на увазі, що */?/etc працюють лише у path segments, тобто у іменах файлів/директорії. Для рекурсивного пошуку необхідно використовувати **. Тому правильна команда:
prettier --write 'src/**/*.js'

👉 Інструмент для перевірки/тренування тут.

Що таке теги електронної пошти?

Більшість поштових серверів доставлять повідомлення на <local-part>+<tag>@<domain> до скриньки <local-part>@<domain>. Така поведінка не визначена специфікацією. Тому кожен проект повинен приймати рішення чи дозволяти користувачам використовувати такі емейли при реєстрації.

Багато сервісів (GitHub, Figma, etc) використовують такі скриньки, щоб дозволити користувачеві надіслати коментар до чогось через пошту. Приклад: issues+2618235@github.com, де 2618235 – Issue ID.

Використання емейлів з тегами особливо зручне під час тестування фіч, пов'язаних з онбоардингом. Це дозволяє не видаляти старих користувачів, і отримувати емейли на одну поштову скриньку.

Node.js розробнику буде корисно використовувати тег для вказівки оточення в емейлі. Приклад env vars:
SENDGRID_API_KEY=SG....
SENDGRID_FROM=info+dev@your-domain.com

Що таке AsyncIterator?

AsyncIterator в JavaScript - це інтерфейс, який дозволяє робити асинхронний перебір колекцій. Він поєднує два інтерфейси JavaScript - Iterator і AsyncIterable - щоб створити об'єкт, який можна використовувати для асинхронного перебору елементів колекції. Це дозволяє писати код, який може асинхронно обробляти дані по одному елементу за раз, не створюючи зайву оперативну пам'ять чи блокуючи дані запити. Для використання AsyncIterator, ви повинні використовувати конструкцію for await...of, яка дозволяє асинхронно обробляти елементи колекції.

Один з прикладів використання AsyncIterator в Node.js - це асинхронне оброблення багатьох файлів. Наприклад, якщо у вас є кілька CSV-файлів, які ви хочете пострічати і обробити їх дані по одному файлу за раз, ви можете використовувати AsyncIterator для цього. Наступний приклад показує, як це може виглядати:

const fs = require('fs');
const path = require('path');

async function processCSVFiles() {
 // Створюємо масив з шляхами до файлів CSV
 const csvFiles = [
  path.join(__dirname, 'file1.csv'),
  path.join(__dirname, 'file2.csv'),
  path.join(__dirname, 'file3.csv')
 ];

 // Створюємо AsyncIterator з масиву файлів
 const csvFilesIterator = csvFiles[Symbol.asyncIterator]();
 // Використовуємо конструкцію for await...of для асинхронного перебору файлів
 for await (const csvFile of csvFilesIterator) {
  // Читаємо файл CSV
  const csvData = await fs.promises.readFile(csvFile, 'utf-8');
  // Обробляємо дані файлу CSV
  // ...
 }
}

processCSVFiles();

У цьому прикладі, ми створюємо масив з шляхами до файлів CSV, з якого створюємо AsyncIterator, використовуючи метод Symbol.asyncIterator. Потім ми використовуємо конструкцію for await...of для асинхронного перебору файлів CSV і читаємо їх дані за допомогою методу fs.promises.readFile. Цей код буде асинхронно обробляти кожен файл по одному, не блокуючи інші запити до сервера. Після обробки кожного файлу, цей код буде очікувати наступний запит до сервера, щоб продовжити обробку файлів.

Цей текст був вступом до новини, що контент згенерований за допомогою ChatGPT заборонен на Stack Overflow. #news

Як користуватися промісіфікованими таймерами?
#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 не підтримується.

Як використовувати npm ls?
#npm

Команда npm ls виводить версії пакетів та їх залежності. Формат виведення деревоподібний. Причому дерево будуватиметься на основі логічних зв'язків, а не фізичного розташування пакетів у node_modules. Глибина дерева визначається параметром depth.

Приклади використання:
👉 npm ls – покаже лише безпосередні залежності.
👉 npm ls --all – покаже лише всі залежності на будь-якому рівні.
👉 npm ls -g – покаже список глобально встановлених пакетів.
👉 npm ls axios – покаже дерево для пакету axios. Має зрозуміліший вигляд, ніж npm explain.

SourceCode
#code_only #typenoscript

Як протестувати routeHandler (api endpoint)?
#testing #package

Якщо вам не подобається писати типи, то доводиться писати тести. Сьогоднішній рецепт про них.

Route handler це функція, яка використовується обробки запитів, які надходять до сервера. У Nest.js це один із методів контролера з відповідними декораторами. У Express ця функція, яка приймає два параметри: об'єкт запиту (request) та об'єкт відповіді (response), та виконує необхідні дії для обробки запиту. Наприклад у цьому коді стрілочна функція є routeHandler-м:
app.get('/', (req, res) => {
res.send('hello world')
})

Способи тестування:
1️⃣ Unit testing, тобто без підняття http серверу. Так тестувати недоцільно, за винятком serverless functions. До функції передаються Req/Res моки. Щоб уникнути проблем з типізацією та прискорити створення моків, використовується node-mocks-http.
2️⃣ Integration Testing, тобто з підняттям http серверу у тестах. Ще може називатися White Box Integration Testing. Часто використовується supertest. Саме так найчастіше тестують Nest.js apps.
3️⃣ End to end testing, тобто з підняттям http серверу до запуску тестів або у global beforeAll. Ще може називатися Black Box Integration Testing, Contract testing, etc. Також може використовувати supertest, але краще використовувати newman чи просто axios.

Ще існує end to end user testing. У цих тестах перевіряється користувальницький досвід і їх пишуть QA automation.

Шкідливі поради про залежності
#npm

⚠️ npm install займає багато часу, тому зберігайте node_modules в git.
⚠️ Для зміни залежностей редагуйте package.json. Так, у вас більше буде у виборі версії. Її краще вказувати * або latest
⚠️ Додайте до .gitignore package-lock.json/yarn.lock, це зменшить кількість git конфліктів.
⚠️ Економте місце за рахунок глобальної встановлення популярних залежностей: npm install -g lodash babel typenoscript
⚠️ Якщо ви перестали використовувати залежність, то не видаляйте її з package.json. Можливо вона десь ще використовується.
⚠️ Ігноруйте повідомлення під час npm install. Усі ці deprecated warnings і npm audit report це лише зайва витрата часу.
⚠️ Не використовуйте devDependencies/optionalDependencies – вони так само, як і NODE_ENV, застаріли.

Для покращення читабельності великих файлів варто підказувати вашому редактору. У WebStorm цього використовується Custom folding regions.
Плагін-аналог для Visual Studio Code – #region folding for VS Code.

Підняв нотатки річної давності. У цей час у сусідньому відділі відбувалося звільнення розробника. Він мав відмінне резюме та понад 20 років досвіду, але не розумів, що робив. Вічний Junior. Він був найнятий у США, тому ми пропрацювали понад рік. Цей час допоміг мені навчитися:

👉 не боятися поставити свій тикет у blocked by;
👉 давати sandwich feedback (must have у американському середовищі);
👉 тримати документацію в актуальному стані, щоб не писати ті самі речі в код-ревью, а можна було просто посилатися на неї;
👉 лагодити зламане локальне оточення за допомогою history;
👉 відновлювати видалені commit-и за допомогою git reflog.

Мораль цієї історії: розробник повинен вміти налаштувати/полагодити своє локальне оточення. У цьому йому допоможуть history та git reflog.

Якщо у вас не встановлен Chrome Extension JSON Viewer, рекомендую це зробити.

Які tsconfig файли створювати?
#typenoscript

Ще один рецепт з налаштування TypeScript. З допомогою --project можна визначити який файл з налаштуваннями використовувати. Приклад із одного з моїх проектів.
"noscripts": {
  "build": "tsc --project tsconfig.build.json",
  "test": "jest --config jest.config.ts",
  "typecheck": "tsc --project tsconfig.json",
  "watch": "tsc --project tsconfig.dev.json --watch"
 },

У цьому проекті використовується 4 файли:
👉 tsconfig.json успадковується від @tsconfig. Від нього успадковуються всі інші. Використовується для перевірки типів у команді typecheck.
👉 tsconfig.build.json використовується під час збирання Docker image. Тільки він має "noEmit": false
👉 tsconfig.dev.json відключає правила, які зайві в процесі розробки або troubleshooting. Наприклад: "noUnusedLocals": false
👉 tsconfig.test.json використовується для тестів. Саме його я вказую у jest.config.ts

Кількість файлів буде залежить від вашого проекту та й використовуваних процесів. Просто пам'ятайте налаштування можна міняти в залежності від контексту запуску TypeScript.

Нагадаю, що наступного року буде припинено підтримку 14 та 16 Node.js версій. 16 версія має підтримку на 7 місяців менше, ніж звичайно. Таке рішення спричинене закінченням терміну підтримки OpenSSL 1.1.1. Детальніше тут

#wrapped

Відкриттям року у 2022 для мене є Raycast. Це Spotlight, як він має бути для розробника. Raycast cам по собі вміє багато, функціонал можна ще розширювати плагінами. SDK для цих плагінів написаний на JavaScript/React.

Діліться в коментарях, які програми стали для вас відкриттям у 2022 році?