ترحيل JavaScript إلى TypeScript

# تثبيت TypeScript npm install --save-dev typescript # تهيئة tsconfig.json npx tsc --init # تثبيت تعريفات الأنواع لتبعياتك npm install --save-dev @types/node @types/react @types/lodash

{ "compilerOptions": { // إعدادات أساسية للترحيل "allowJs": true, // السماح بملفات JavaScript "checkJs": false, // عدم فحص أنواع ملفات JS (بعد) "noEmit": true, // عدم الإصدار أثناء الترحيل "esModuleInterop": true, "skipLibCheck": true, // إعدادات الهدف والوحدة "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", // الترحيل التدريجي "strict": false, // ابدأ بالتساهل، فعل لاحقاً "noImplicitAny": false, // السماح بـ any ضمني أثناء الترحيل // خرائط المصدر للتصحيح "sourceMap": true, // دليل الإخراج (عندما تبدأ الإصدار) "outDir": "./dist", "rootDir": "./src" }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] }

// قبل: utils.js export function formatDate(date) { return date.toISOString().split('T')[0]; } export function calculateTotal(items) { return items.reduce((sum, item) => sum + item.price, 0); } // بعد: utils.ts export function formatDate(date: Date): string { return date.toISOString().split('T')[0]; } interface Item { price: number; } export function calculateTotal(items: Item[]): number { return items.reduce((sum, item) => sum + item.price, 0); }

// 1. تحويل main.js → main.ts // 2. إصلاح الأخطاء في الاستيرادات // 3. تحويل الملفات المستوردة واحداً تلو الآخر // 4. كرر حتى يتم تحويل جميع الملفات

// قبل: JavaScript const user = { id: 1, name: 'John Doe', email: 'john@example.com' }; function updateUser(user, updates) { return { ...user, ...updates }; } // بعد: TypeScript interface User { id: number; name: string; email: string; } function updateUser(user: User, updates: Partial<User>): User { return { ...user, ...updates }; }

// قبل: JavaScript function fetchData(url, onSuccess, onError) { fetch(url) .then(response => response.json()) .then(onSuccess) .catch(onError); } // بعد: TypeScript type SuccessCallback<T> = (data: T) => void; type ErrorCallback = (error: Error) => void; function fetchData<T>( url: string, onSuccess: SuccessCallback<T>, onError: ErrorCallback ): void { fetch(url) .then(response => response.json()) .then(onSuccess) .catch(onError); }

// قبل: JavaScript class UserService { constructor(apiUrl) { this.apiUrl = apiUrl; this.cache = new Map(); } async getUser(id) { if (this.cache.has(id)) { return this.cache.get(id); } const response = await fetch(`${this.apiUrl}/users/${id}`); const user = await response.json(); this.cache.set(id, user); return user; } } // بعد: TypeScript interface User { id: number; name: string; email: string; } class UserService { private cache: Map<number, User> = new Map(); constructor(private apiUrl: string) {} async getUser(id: number): Promise<User> { const cached = this.cache.get(id); if (cached) { return cached; } const response = await fetch(`${this.apiUrl}/users/${id}`); const user = await response.json() as User; this.cache.set(id, user); return user; } }

// @ts-check /** * @param {number} a * @param {number} b * @returns {number} */ function add(a, b) { return a + b; } add(1, 2); // ✓ صحيح add(1, '2'); // ✗ خطأ: Argument of type 'string' is not assignable to parameter

// @ts-check /** * @typedef {Object} User * @property {number} id * @property {string} name * @property {string} email */ /** * @param {User[]} users * @returns {User[]} */ function sortUsersByName(users) { return users.sort((a, b) => a.name.localeCompare(b.name)); }

// legacy-api.js (لا يمكن التحويل بعد) export function legacyFunction(data) { // تنفيذ معقد return processData(data); } // legacy-api.d.ts (تعريفات الأنواع) export interface LegacyData { id: number; value: string; } export function legacyFunction(data: LegacyData): string;

# البحث عن تعريفات الأنواع npm search @types/library-name # تثبيت تعريفات الأنواع npm install --save-dev @types/library-name # إذا لم توجد أنواع، أنشئ أنواعك الخاصة # إنشاء: src/types/library-name.d.ts declare module 'library-name' { export function doSomething(param: string): number; }

// المرحلة 1: ترحيل سريع مع any function processData(data: any): any { return data.value * 2; } // المرحلة 2: إضافة أنواع محددة interface InputData { value: number; } function processData(data: InputData): number { return data.value * 2; } // المرحلة 3: إضافة التحقق function processData(data: InputData): number { if (typeof data.value !== 'number') { throw new Error('Invalid data'); } return data.value * 2; }

{ "compilerOptions": { // الخطوة 1: ابدأ هنا "strict": false, "noImplicitAny": false, // الخطوة 2: قم بالتمكين بعد تحويل ملفات الأدوات "noImplicitAny": true, // الخطوة 3: قم بالتمكين بعد تنظيف فحوصات null "strictNullChecks": true, // الخطوة 4: قم بالتمكين للفئات "strictPropertyInitialization": true, // الخطوة 5: قم بالتمكين لأنواع الدوال "strictFunctionTypes": true, // الخطوة 6: قم بتمكين علامات صارمة متبقية "strictBindCallApply": true, "noImplicitThis": true, "alwaysStrict": true, // الخطوة الأخيرة: قم بتمكين الوضع الصارم الكامل "strict": true } }

// ❌ سيء: تأكيدات كثيرة جداً const data = JSON.parse(jsonString) as User; const users = response.data as User[]; // ✓ أفضل: التحقق في وقت التشغيل function parseUser(data: unknown): User { if ( typeof data === 'object' && data !== null && 'id' in data && 'name' in data ) { return data as User; } throw new Error('Invalid user data'); } const user = parseUser(JSON.parse(jsonString));

// ❌ سيء: قمع الأخطاء // @ts-ignore const value = obj.unknownProperty; // ✓ أفضل: إصلاح النوع interface MyObject { unknownProperty?: string; } const obj: MyObject = {}; const value = obj.unknownProperty;

// ❌ سيء: افتراض شكل بيانات API async function fetchUser(id: number): Promise<User> { const response = await fetch(`/api/users/${id}`); return response.json(); // يرجع any! } // ✓ أفضل: التحقق من البيانات الخارجية async function fetchUser(id: number): Promise<User> { const response = await fetch(`/api/users/${id}`); const data: unknown = await response.json(); if (isUser(data)) { return data; } throw new Error('Invalid user data from API'); } function isUser(data: unknown): data is User { return ( typeof data === 'object' && data !== null && 'id' in data && typeof (data as User).id === 'number' && 'name' in data && typeof (data as User).name === 'string' ); }

# ESLint مع TypeScript npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin # أداة تغطية الأنواع npm install --save-dev type-coverage # فحص تغطية الأنواع npx type-coverage --detail # أدوات الترحيل الآلي npm install --save-dev ts-migrate npx ts-migrate-full <project-directory>

// قبل: user-service.js class UserService { constructor(config) { this.apiUrl = config.apiUrl; this.timeout = config.timeout || 5000; } async getUsers(filters) { const params = new URLSearchParams(filters); const response = await fetch( `${this.apiUrl}/users?${params}`, { timeout: this.timeout } ); return response.json(); } async updateUser(id, updates) { const response = await fetch( `${this.apiUrl}/users/${id}`, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(updates) } ); return response.json(); } } // بعد: user-service.ts interface Config { apiUrl: string; timeout?: number; } interface User { id: number; name: string; email: string; } interface UserFilters { name?: string; email?: string; status?: string; } type UserUpdates = Partial<Omit<User, 'id'>>; class UserService { private readonly apiUrl: string; private readonly timeout: number; constructor(config: Config) { this.apiUrl = config.apiUrl; this.timeout = config.timeout ?? 5000; } async getUsers(filters?: UserFilters): Promise<User[]> { const params = new URLSearchParams(filters as Record<string, string>); const response = await fetch( `${this.apiUrl}/users?${params}`, { signal: AbortSignal.timeout(this.timeout) } ); if (!response.ok) { throw new Error(`Failed to fetch users: ${response.statusText}`); } const data: unknown = await response.json(); if (Array.isArray(data)) { return data as User[]; } throw new Error('Invalid response format'); } async updateUser(id: number, updates: UserUpdates): Promise<User> { const response = await fetch( `${this.apiUrl}/users/${id}`, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(updates), signal: AbortSignal.timeout(this.timeout) } ); if (!response.ok) { throw new Error(`Failed to update user: ${response.statusText}`); } return response.json() as Promise<User>; } } export { UserService, type Config, type User, type UserFilters, type UserUpdates };

# عد ملفات TypeScript مقابل JavaScript echo "TypeScript files:" && find src -name "*.ts" -o -name "*.tsx" | wc -l echo "JavaScript files:" && find src -name "*.js" -o -name "*.jsx" | wc -l # تغطية الأنواع npx type-coverage --detail # مثال على الإخراج: # 2345 / 3000 87.50% # type-coverage success: >= 80.00%