TypeScript JS loyihalarida (JSDoc)

TypeScript bilan JSDoc JavaScript fayllarini .ts ga aylantirmasdan turini tekshirishni qo‘shish imkonini beradi.

Bu asta-sekin migratsiya uchun yoki JavaScript loyihalarida yozish xavfsizligini xohlasangiz juda mos keladi.

Ishni boshlash

JavaScript fayllarida TypeScript tekshiruvini yoqish uchun sizga quyidagilar kerak:

tsconfig.json fayl yarating (agar sizda yo‘q bo‘lsa)
checkJs ni yoqing yoki alohida fayllarda // @ts-check dan foydalaning

Misol: Xavfsizlik turi uchun JSDoc

// @ts-check

/**
* Adds two numbers.
* @param {number} a
* @param {number} b
* @returns {number}
*/
function add(a, b) {
return a + b;
}

O‘zingiz sinab ko‘ring »

Obyektlar va interfacelar

Inline obyekt turlari

// @ts-check

/**
* @param {{ firstName: string, lastName: string, age?: number }} person
*/
function greet(person) {
return `Hello, ${person.firstName} ${person.lastName}`;
}

greet({ firstName: 'John', lastName: 'Doe' }); // OK
greet({ firstName: 'Jane' }); // Error: Property 'lastName' is missing

O‘zingiz sinab ko‘ring »

Murakkab turlar uchun @typedef dan foydalanish

// @ts-check

/**
* @typedef {Object} User
* @property {number} id - The user ID
* @property {string} username - The username
* @property {string} [email] - Optional email address
* @property {('admin'|'user'|'guest')} role - User role
* @property {() => string} getFullName - Method that returns full name
*/

/** @type {User} */
const currentUser = {
  id: 1,
  username: 'johndoe',
  role: 'admin',
  getFullName() {
    return 'John Doe';
  }
};

// TypeScript will provide autocomplete for User properties
console.log(currentUser.role);

O‘zingiz sinab ko‘ring »

Kengaytirish turlari

// @ts-check

/** @typedef {{ x: number, y: number }} Point */

/**
* @typedef {Point & { z: number }} Point3D
*/

/** @type {Point3D} */
const point3d = { x: 1, y: 2, z: 3 };

// @ts-expect-error - missing z property
const point2d = { x: 1, y: 2 };

O‘zingiz sinab ko‘ring »

Funksiya turlari

Funksiya deklaratsiyasi

// @ts-check

/**
* Calculates the area of a rectangle
* @param {number} width - The width of the rectangle
* @param {number} height - The height of the rectangle
* @returns {number} The calculated area
*/
function calculateArea(width, height) {
return width * height;
}

// TypeScript knows the parameter and return types
const area = calculateArea(10, 20);

O‘zingiz sinab ko‘ring »

Funksiya ifodalari va callback funksiyasilar

// @ts-check

/**
* @callback StringProcessor
* @param {string} input
* @returns {string}
*/

/**
* @type {StringProcessor}
*/
const toUpperCase = (str) => str.toUpperCase();

/**
* @param {string[]} strings
* @param {StringProcessor} processor
* @returns {string[]}
*/
function processStrings(strings, processor) {
return strings.map(processor);
}

const result = processStrings(['hello', 'world'], toUpperCase);
// result will be ['HELLO', 'WORLD']

O‘zingiz sinab ko‘ring »

Funksiyaning haddan tashqari yuklanishi

// @ts-check

/**
* @overload
* @param {string} a
* @param {string} b
* @returns {string}
*/
/**
* @overload
* @param {number} a
* @param {number} b
* @returns {number}
*/
/**
* @param {string | number} a
* @param {string | number} b
* @returns {string | number}
*/
function add(a, b) {
  if (typeof a === 'string' || typeof b === 'string') {
    return String(a) + String(b);
  }
  return a + b;
}

const strResult = add('Hello, ', 'World!'); // string
const numResult = add(10, 20); // number

O‘zingiz sinab ko‘ring »

Kengaytirilgan turlari

Birlashma va kesishish turlari

// @ts-check

/** @typedef {{ name: string, age: number }} Person */
/** @typedef {Person & { employeeId: string }} Employee */
/** @typedef {Person | { guestId: string, visitDate: Date }} Visitor */

/** @type {Employee} */
const employee = {
  name: 'Alice',
  age: 30,
  employeeId: 'E123'
};

/** @type {Visitor} */
const guest = {
  guestId: 'G456',
  visitDate: new Date()
};

/**
* @param {Visitor} visitor
* @returns {string}
*/
function getVisitorId(visitor) {
  if ('guestId' in visitor) {
    return visitor.guestId; // TypeScript knows this is a guest
  }
  return visitor.name; // TypeScript knows this is a Person
}

O‘zingiz sinab ko‘ring »

Xaritalangan va shartli turlar

// @ts-check

/** * @template T * @typedef {[K in keyof T]: T[K] extends Function ? K : never}[keyof T] MethodNames */

/** * @template T * @typedef {{ *   [K in keyof T as `get${'<' }Capitalize<string & K>{'>'}`]: () => T[K] * }} Getters */

/** @type {Getters<{ name: string, age: number }> } */
const userGetters = {
  getName: () => 'John',
  getAge: () => 30
};

// TypeScript enforces the return types
const name = userGetters.getName(); // string
const age = userGetters.getAge(); // number

O‘zingiz sinab ko‘ring »

Importlarni yozing

Boshqa fayllardan turlarni import qilish

// @ts-check

// Importing types from TypeScript files
/** @typedef {import('./types').User} User */

// Importing types from node_modules
/** @typedef {import('express').Request} ExpressRequest */

// Importing with renaming
/** @typedef {import('./api').default as ApiClient} ApiClient */

Deklaratsiya fayllarini yaratish

Loyihangizda types.d.ts fayl yarating:

// types.d.ts
declare module 'my-module' {
  export interface Config {
    apiKey: string;
    timeout?: number;
    retries?: number;
  }

  export function initialize(config: Config): void;
  export function fetchData<T = any>(url: string): Promise<T>;
}

Keyin uni JavaScript fayllaringizda foydalaning:

// @ts-check

/** @type {import('my-module').Config} */
const config = {
apiKey: '12345',
timeout: 5000
};

// TypeScript will provide autocomplete and type checking
import { initialize } from 'my-module';
initialize(config);

Eng yaxshi amaliyotlar

TypeScript bilan JSDoc-dan foydalanishda quyidagi eng yaxshi amaliyotlarga amal qiling:

Turini tekshirmoqchi bo‘lgan fayllarning yuqori qismida // @ts-check ni yoqing
Bir nechta joylarda ishlatiladigan murakkab turlar uchun @typedef dan foydalaning
Barcha funksiya parametrlari va qaytish turlarini hujjatlashtiring
Umumiy funksiyalar va turlar uchun @template dan foydalaning
Create declaration files (.d.ts) for third-party libraries without types
Xato kutilayotganda @ts-ignore o‘rniga @ts-expect-error dan foydalaning

Umumiy tuzoqlar

Ushbu umumiy muammolarga e’tibor bering:

Missing // @ts-check: Turni tekshirish usiz ishlamaydi
Incorrect JSDoc syntax: Bitta matn terish xatosi turini tekshirishni o‘chirib qo‘yishi mumkin
Type conflicts: Turli manbalardagi turlar mos kelmasa
Inference issues: Ba’zan TypeScript turlar haqida to‘g‘ri xulosa chiqara olmaydi
Performance: Murakkab turlarga ega bo‘lgan katta JavaScript fayllarini tekshirish sekin bo‘lishi mumkin

Xulosa

JSDoc-dan TypeScript-dan foydalanish fayllarni TypeScript-ga o‘zgartirmasdan JavaScript loyihalaringizga turdagi xavfsizlikni qo‘shishning kuchli usulini ta’minlaydi.

Ushbu yondashuv ayniqsa quyidagilar uchun foydalidir:

JavaScript kod bazalarini asta-sekin TypeScript-ga ko‘chirish
Mavjud JavaScript loyihalariga tur tekshiruvini qo‘shish
.ts fayllar qo‘llab-quvvatlanmaydigan muhitlarda ishlash
JavaScript kodini tur ma’lumotlari bilan hujjatlash

Ushbu qo‘llanmada keltirilgan namunalar va eng yaxshi amaliyotlarga rioya qilish orqali siz JavaScript bilan ishlashda davom etayotganda TypeScript ning ko‘plab afzalliklaridan bahramand bo‘lishingiz mumkin.

Remember: JSDoc yangi loyihalar yoki to‘liq ko‘chirishlar uchun mukammal turdagi tekshirishni ta’minlasa-da, eng yaxshi TypeScript tajribasi uchun .ts fayllardan foydalanishni o‘ylab ko‘ring.

TypeScript-ni JSDoc bilan sinab ko‘rishga tayyormisiz?

JavaScript fayllaringizga // @ts-check qo‘shishdan boshlang va asta-sekin JSDoc yordamida turdagi izohlarni qo‘shing.

TypeScript kompilyatori xatolarni ishlab chiqarishga yetguncha aniqlashga yordam beradi!

W3Schools Pathfinder

Yutuqlaringizni kuzating – bu bepul!

Ro'yxatdan o'tish Kirish