Розробіть свою першу бібліотеку JavaScript і опублікуйте її - javascript.org.ua

Розробка JavaScript бібліотеки та публікація її на npm — це чудова можливість як для розвитку технічних навичок, так і для внеску в світ відкритих технологій. У цій статті я покажу, як розробити JavaScript бібліотеку і публікувати її на npm за допомогою бібліотеки, яку я створив — tckn-vkn-validator.

Визначення бібліотеки для розробки

Корисно працювати над темою, яка може принести користь як для вас, так і для спільноти. В моєму випадку я вибрав проблему валідації Турецького ідентифікаційного номеру (TCKN) та податкового номера (VKN). Такі операції валідації часто зустрічаються в різних проектах, тому вирішення цього питання через бібліотеку значно спрощує роботу.

Створення та налаштування бібліотеки

Створення проекту

Почнемо з створення папки для нашого проекту. Оскільки я хочу, щоб бібліотека підтримувала як JavaScript, так і TypeScript, я буду використовувати TypeScript.

mkdir tckn-vkn-validator  
cd tckn-vkn-validator

Створення файлу package.json

Щоб створити файл package.json, виконайте наступну команду:

npm init -y

Створення загальної структури папок

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

Якщо ви хочете створити бібліотеку тільки для JavaScript, цієї структури буде достатньо.

tckn-vkn-validator/  
├── src/  
│ └── index.js  
├── __test__/  
│ └── index.test.js  
├── .gitignore  
├── package.json  
├── babel.config.json  
└── README.md

Щоб додати підтримку TypeScript, потрібно створити файл tsconfig.json і змінити розширення файлів у папці src на .ts.

tckn-vkn-validator/  
├── src/  
│ └── index.ts  
├── __test__/  
│ └── index.test.js  
├── .gitignore  
├── package.json  
├── babel.config.json  
├── tsconfig.json  
└── README.md

Далі заповнимо наші файли.

Написання тестів для бібліотеки

Перед тим як написати код бібліотеки, варто визначити, які вхідні параметри ми будемо приймати і які результати видавати, а також написати тести для нашої бібліотеки, щоб зрозуміти її призначення. Якщо хочете, можна пропустити цей етап і перейти до безпосередньої розробки коду.

В цьому кроці я покажу, як написати прості тести для валідації TCKN та VKN. Функція для валідації TCKN буде називатися validateTckn, а для валідації VKN — validateVkn. Для цього ми будемо використовувати бібліотеку Jest, яку потрібно встановити в проект.

npm install --save-dev jest | yarn add --dev jest

// package.json  
"scripts": {  
 "test": "jest",  
 // інші скрипти...  
}

describe("Validation Functions", () => {  
 describe("validateTckn", () => {  
 it("should return true for a valid TCKN", () => {  
 expect(validateTckn("11111111110")).toBe(true);  
 });  

 it("should return false for an invalid TCKN", () => {  
 expect(validateTckn("12345678902")).toBe(false);  
 });  
 });  

 describe("validateVkn", () => {  
 it("should return true for a valid VKN", () => {  
 expect(validateVkn("1430466081")).toBe(true);  
 });  

 it("should return false for an invalid VKN", () => {  
 expect(validateVkn("1234567891")).toBe(false);  
 });  
 });  
});

На початку тести будуть видавати помилку, оскільки ми ще не написали самі функції. Однак, ми вже визначили параметри і результати, які функції повинні повертати. Функція validateTckn повинна приймати значення TCKN у вигляді рядка та повертати логічне значення після виконання необхідних перевірок.
Так само, ви можете помітити, що функція validateVkn приймає рядок vkn та повертає булеве значення. Код виглядає так, як ми описали в тестах, і тепер можемо розглянути, як написати саму бібліотеку.

Написання коду бібліотеки

Якщо ви пропустили попередній етап, ви можете подивитися на код нашої бібліотеки тут і побачити, яку структуру ми можемо створити. Якщо ви виконали тестування, ви зможете побачити, як ми пишемо код, відповідно до тестів.

/**  
 * Функція для валідації T.C. Ідентифікаційного Номеру.  
 * @param {string} tckn - T.C. Ідентифікаційний Номер (11 знаків).  
 * @returns {boolean} - Результат валідації (true/false).  
 */  
function validateTckn(tckn: string): boolean {  
 if (!/^\d{11}$/.test(tckn) || tckn[0] === "0") {  
 return false;  
 }  

 const digits: number[] = tckn.split("").map(Number);  
 const sumOfFirst10: number = digits  
 .slice(0, 10)  
 .reduce((sum, digit) => sum + digit, 0);  
 if (sumOfFirst10 % 10 !== digits[10]) {  
 return false;  
 }  

 const oddSum: number =  
 digits[0] + digits[2] + digits[4] + digits[6] + digits[8];  
 const evenSum: number = digits[1] + digits[3] + digits[5] + digits[7];  
 if ((oddSum * 7 - evenSum) % 10 !== digits[9]) {  
 return false;  
 }  

 return true;  
}  

/**  
 * Функція для валідації податкового ідентифікаційного номера.  
 * @param {string} vkn - Податковий Ідентифікаційний Номер (10 знаків).  
 * @returns {boolean} - Результат валідації (true/false).  
 */  
function validateVkn(vkn: string): boolean {  
 if (vkn.length !== 10) {  
 return false;  
 }  

 const stepOfVkn: number[] = [];  
 const lastDigit = Number(vkn.charAt(9));  
 for (let i = 0; i < 9; i++) {  
 const tmp: number = (Number(vkn.charAt(i)) + (9 - i)) % 10;  
 stepOfVkn[i] = (tmp * 2 ** (9 - i)) % 9;  
 if (tmp !== 0 && stepOfVkn[i] === 0) stepOfVkn[i] = 9;  
 }  
 const sum: number = stepOfVkn.reduce((a, b) => a + b, 0) % 10;  
 return (10 - (sum % 10)) % 10 === lastDigit;  
}  

export { validateTckn, validateVkn };

Під час написання коду бібліотеки важливо бути пояснювальним та інформативним для тих, хто хоче внести внесок або розібратися в бібліотеці. Для цього дуже важливо використовувати JSDoc. Це дозволяє чітко описати мету функції, її параметри та результати.

Як ми писали в тестах, функція validateTckn приймає рядок tckn і повертає булеве значення після виконання перевірок. Так само функція validateVkn приймає рядок vkn і повертає булеве значення після виконання перевірок. Після того, як ми написали функції та експортували їх, ми готові запускати тести та перевіряти, чи працюють функції так, як очікується.

npm run test | yarn test  

------------------------------------------------------  

 PASS __tests__/index.test.js  
 Validation Functions  
 validateTckn  
 ✓ повинна повернути true для валідного TCKN (1 ms)  
 ✓ повинна повернути false для невалідного TCKN  
 validateVkn  
 ✓ повинна повернути true для валідного VKN  
 ✓ повинна повернути false для невалідного VKN  

Test Suites: 1 пройшли, 1 всього  
Тести: 4 пройшли, 4 всього  
Знімки: 0 всього  
Час: 0.309 с, приблизно 1 с  
Запущено всі тестові набори.  
✨ Готово за 1.02 с.

Налаштування додаткових бібліотек та конфігураційних файлів

Хоча в моєму прикладі проекту це не було необхідно, я хотів би згадати про Babel. Babel допомагає підтримувати старі браузери, використовувати нові можливості JavaScript, має велику кількість плагінів і дозволяє створювати спеціальні синтаксиси. Тому залежно від складності вашої бібліотеки, ви можете додати Babel (та потрібні плагіни) до вашого проекту. Для більш детальної інформації ознайомтесь з офіційним сайтом Babel.
Щоб додати приклад структури проєкту, ось як це може виглядати:

npm install --save-dev @babel/cli @babel/core @babel/preset-env   
@babel/preset-typescript babel-jest  

yarn add --dev @babel/cli @babel/core @babel/preset-env   
@babel/preset-typescript babel-jest

// babel.config.json  
{  
 "presets": [  
 "@babel/preset-typescript",  
 ["@babel/preset-env", {  
 "targets": {  
 "node": "14",  
 "browsers": "> 0.25%, not dead"  
 }  
 }]  
 ]  
}  

// package.json  
"scripts": {  
 "build": "tsc && babel src --extensions \".ts,.tsx\" --out-dir dist",  
 // інші скрипти...  
}

Як я згадував на початку, якщо ви використовуєте TypeScript в вашому проєкті, ви можете налаштувати tsconfig.json відповідно до вимог вашого проєкту.

{  
 "compilerOptions": {  
 "target": "es2018", // визначення версії Ecmascript  
 "module": "commonjs", // визначення структури модулів  
 "moduleResolution": "node", // як будуть оброблятись модулі  
 "declaration": true, // створення файлів з розширенням .d.ts  
 "outDir": "./dist", // вихідний каталог компільованого коду  
 "strict": true, // сувора типізація  
 "esModuleInterop": true, // дозволяє використання імпорту за замовчуванням  
 "skipLibCheck": true, // ігнорування перевірки типів у таких каталогах як node_modules  
 "forceConsistentCasingInFileNames": true // забезпечення єдності в іменах файлів  
 },  
 "include": ["src/**/*"], // місце розташування файлів для компіляції  
 "exclude": ["node_modules", "dist"] // місце розташування файлів, які не будуть компільовані  
}

Нарешті, ви можете додати потрібні налаштування для вашого проєкту в файлі package.json. Ось приклад структури, яку я використовував:

{  
 "name": "tckn-vkn-validator",  
 "version": "0.0.1",  
 "description": "Бібліотека для валідації Турецьких Ідентифікаційних Номерів (TCKN) та Податкових Ідентифікаційних Номерів (VKN).",  
 "main": "./dist/index.js",  
 "module": "./dist/index.js",  
 "types": "./dist/index.d.ts",  
 "exports": {  
 "types": "./dist/index.d.ts",  
 "import": "./dist/index.js"  
 },  
 "keywords": [  
 "tckn",  
 "vkn",  
 "tckn validation",  
 "vkn validation",  
 "turkey",  
 "tax id",  
 "identity"  
 ],  
 "author": "MhmtMutlu",  
 "license": "MIT",  
 "repository": {  
 "type": "git",  
 "url": "https://github.com/MhmtMutlu/tckn-vkn-validator.git"  
 },  
 "bugs": {  
 "url": "https://github.com/MhmtMutlu/tckn-vkn-validator/issues"  
 },  
 "homepage": "https://github.com/MhmtMutlu/tckn-vkn-validator#readme",  
 "files": [  
 "dist",  
 "README.md"  
 ],  
 "devDependencies": {  
 "@babel/cli": "^7.26.4",  
 "@babel/core": "^7.26.0",  
 "@babel/preset-env": "^7.26.0",  
 "@babel/preset-typescript": "^7.26.0",  
 "@types/node": "^22.10.2",  
 "babel-jest": "^29.7.0",  
 "jest": "^29.7.0",  
 "typescript": "^5.7.2"  
 },  
 "scripts": {  
 "test": "jest",  
 "build": "tsc && babel src --extensions \".ts,.tsx\" --out-dir dist"  
 }  
}

Найважливіші налаштування тут - це main, module, types та exports. Ось їх значення:

main -> шлях для require у Commonjs
module -> шлях для import у ES модулях
types -> вказівка на типи для TypeScript
exports -> types: сучасне визначення типів для TypeScript, imports: необхідний шлях для імпорту

Підготовка README.md

Для відкритих проєктів та користувачів важливо мати чітко написаний та інформативний README. В ньому потрібно пояснити, як завантажити бібліотеку та як її використовувати.
Ось як виглядає README файл для моєї бібліотеки:

# Tckn & Vkn Validator  

Включає функції validateTckn та validateVkn для перевірки Турецького Ідентифікаційного Номера (Tckn) та Податкового Ідентифікаційного Номера (Vkn)  

[![pic](https://drive.javascript.org.ua/668fbc1165tckn_vkn_validator_svg)  

## Встановлення  

```bash  
npm install tckn-vkn-validator

Використання

Функція validateTckn приймає tckn (рядок) як параметр і повертає булеве значення як результат. Вона перевіряє tckn відповідно до правил.

import { validateTckn } from "tckn-vkn-validator";  

const tckn: string = "11111111110";  

const result: boolean = validateTckn(tckn);

Функція validateVkn приймає vkn (рядок) як параметр і повертає булеве значення як результат. Вона перевіряє vkn відповідно до правил.

import { validateVkn } from "tckn-vkn-validator";  

const vkn: string = "1430466081";  

const result: boolean = validateVkn(vkn);

Ліцензія

MIT
```

Публікація бібліотеки

Щоб опублікувати вашу бібліотеку, увійдіть у NPM. Якщо у вас немає акаунту, ви можете швидко його створити.

Не забувайте оновлювати версію через файл package.json після кожної зміни.

npm login  
// виконати вхід  

npm publish  
// публікація

Використання бібліотеки

Після публікації бібліотеки на NPM, ви можете встановити її в будь-який проєкт і почати використовувати.

npm install tckn-vkn-validator

import { validateTckn, validateVkn } from "tckn-vkn-validator";  

const tckn: string = "11111111110";  
const vkn: string = "1430466081";  

const result: boolean = validateTckn(tckn); // true  
const result: boolean = validateVkn(vkn); // true

Висновок

Розробка JavaScript бібліотеки та її публікація на платформі типу npm не тільки покращує ваші технічні навички, а й є цінним внеском в світ з відкритим кодом. У цьому процесі важливо використовувати правильні інструменти, створювати добре структуровані проєкти та застосовувати підхід, орієнтований на тестування.

Слідуючи наведеним вище крокам, ви зможете створити та опублікувати свою бібліотеку. Якщо у вас є питання або коментарі до статті, не соромтеся поділитися ними. Бажаю вам успіху на шляху створення вашої власної бібліотеки!

Перекладено з: İlk JavaScript Kütüphanenizi Geliştirip Yayına Alın