إعلان وحدات TypeScript: التنقل بين الوحدات المحيطة وتعريفات الأنواع العامة لتطوير عالمي قوي

في عالم تطوير البرمجيات الحديث الشاسع والمترابط، غالبًا ما تنتشر الفرق عبر القارات، وتعمل على مشاريع تتطلب تكاملًا سلسًا، وقابلية صيانة عالية، وسلوكًا متوقعًا. لقد برز TypeScript كأداة حاسمة لتحقيق هذه الأهداف، حيث يوفر كتابة ثابتة تضفي الوضوح والمرونة على قواعد بيانات JavaScript. بالنسبة للفرق الدولية التي تتعاون في تطبيقات معقدة، فإن القدرة على تعريف وتطبيق الأنواع عبر الوحدات والمكتبات المتنوعة لا تقدر بثمن.

ومع ذلك، نادرًا ما توجد مشاريع TypeScript في عزلة. فهي تتفاعل بشكل متكرر مع مكتبات JavaScript الموجودة، وتتكامل مع واجهات برمجة تطبيقات المتصفح الأصلية، أو تقوم بتوسيع الكائنات المتاحة عالميًا. وهنا تصبح ملفات إعلان TypeScript (.d.ts) لا غنى عنها، مما يسمح لنا بوصف شكل كود JavaScript لمترجم TypeScript دون تغيير سلوك وقت التشغيل. ضمن هذه الآلية القوية، يبرز نهجان أساسيان للتعامل مع الأنواع الخارجية: إعلانات الوحدات المحيطة (Ambient Module Declarations) وتعريفات الأنواع العامة (Global Type Definitions).

يعد فهم متى وكيف يمكن استخدام الوحدات المحيطة مقابل تعريفات الأنواع العامة بفعالية أمرًا أساسيًا لأي مطور TypeScript، وخاصة أولئك الذين يبنون حلولًا واسعة النطاق على مستوى المؤسسات لجمهور عالمي. يمكن أن يؤدي سوء التطبيق إلى تعارضات في الأنواع، واعتمادات غير واضحة، وتقليل قابلية الصيانة. سيستكشف هذا الدليل الشامل هذه المفاهيم بعمق، ويقدم أمثلة عملية وأفضل الممارسات لمساعدتك على اتخاذ قرارات مستنيرة في مشاريع TypeScript الخاصة بك، بغض النظر عن حجم فريقك أو توزيعه الجغرافي.

نظام أنواع TypeScript ودوره في تطوير البرمجيات العالمية

يوسع TypeScript لغة JavaScript عن طريق إضافة أنواع ثابتة، مما يمكن المطورين من اكتشاف الأخطاء مبكرًا في دورة التطوير بدلاً من وقت التشغيل. بالنسبة للفرق الموزعة عالميًا، يحقق هذا العديد من الفوائد العميقة:

• تعزيز التعاون: باستخدام الأنواع الصريحة، يمكن لأعضاء الفريق عبر مناطق زمنية وخلفيات ثقافية مختلفة فهم المدخلات والمخرجات المتوقعة للدوال والواجهات والفئات بسهولة أكبر، مما يقلل من سوء التفسير والعبء التواصلي.
• تحسين قابلية الصيانة: مع تطور المشاريع وإضافة ميزات جديدة من قبل فرق مختلفة، تعمل إعلانات الأنواع كعقد، مما يضمن أن التغييرات في جزء واحد من النظام لا تؤدي إلى كسر جزء آخر عن غير قصد. هذا أمر بالغ الأهمية للتطبيقات طويلة الأمد.
• ثقة إعادة الهيكلة: تستفيد قواعد التعليمات البرمجية الكبيرة، التي غالبًا ما يتم بناؤها بواسطة العديد من المساهمين بمرور الوقت، بشكل كبير من إمكانيات إعادة هيكلة TypeScript. يوجه المترجم المطورين خلال تحديثات الأنواع الضرورية، مما يجعل التغييرات الهيكلية الكبيرة أقل إرباكًا.
• دعم الأدوات: يتم تشغيل ميزات بيئة التطوير المتكاملة المتقدمة مثل الإكمال التلقائي، ومساعدة التوقيع، والإبلاغ الذكي عن الأخطاء بواسطة معلومات نوع TypeScript، مما يعزز إنتاجية المطورين في جميع أنحاء العالم.

في صميم الاستفادة من TypeScript مع JavaScript الموجودة توجد ملفات إعلان النوع (.d.ts). تعمل هذه الملفات كجسر، حيث توفر معلومات النوع لمترجم TypeScript حول كود JavaScript الذي لا يمكنه استنتاجه بنفسه. إنها تمكن من التشغيل البيني السلس، مما يسمح لـ TypeScript باستهلاك مكتبات وأطر عمل JavaScript بأمان.

فهم ملفات إعلان النوع (.d.ts)

يحتوي ملف .d.ts على تعريفات الأنواع فقط - لا يوجد كود تنفيذ فعلي. إنه يشبه ملف رأس في C++ أو ملف واجهة في Java، يصف واجهة برمجة التطبيقات العامة لوحدة أو كيان عام. عندما يقوم مترجم TypeScript بمعالجة مشروعك، فإنه يبحث عن ملفات الإعلان هذه لفهم الأنواع التي يوفرها كود JavaScript الخارجي. وهذا يسمح لكود TypeScript الخاص بك باستدعاء دوال JavaScript، وإنشاء كائنات من فئات JavaScript، والتفاعل مع كائنات JavaScript بأمان كامل للأنواع.

بالنسبة لمعظم مكتبات JavaScript الشائعة، تتوفر تعريفات الأنواع بالفعل عبر مؤسسة @types على npm (مدعومة بمشروع DefinitelyTyped). على سبيل المثال، يوفر تثبيت npm install @types/react تعريفات أنواع لمكتبة React. ومع ذلك، هناك سيناريوهات ستحتاج فيها إلى إنشاء ملفات الإعلان الخاصة بك:

• استخدام مكتبة JavaScript داخلية مخصصة لا تحتوي على تعريفات أنواع.
• العمل مع مكتبات خارجية أقدم وأقل صيانة.
• إعلان أنواع للأصول غير JavaScript (مثل الصور، وحدات CSS).
• توسيع الكائنات العامة أو الأنواع الأصلية.

في سيناريوهات الإعلان المخصصة هذه يصبح التمييز بين إعلانات الوحدات المحيطة وتعريفات الأنواع العامة أمرًا بالغ الأهمية.

إعلان الوحدة المحيطة (declare module 'module-name')

يُستخدم إعلان الوحدة المحيطة لوصف شكل وحدة JavaScript خارجية لا تحتوي على تعريفات أنواع خاصة بها. في الأساس، يخبر مترجم TypeScript: "توجد وحدة اسمها 'X' هناك، وهذا ما تبدو عليه صادراتها." وهذا يسمح لك بـ import أو require تلك الوحدة في كود TypeScript الخاص بك مع فحص كامل للنوع.

متى تستخدم إعلانات الوحدات المحيطة

يجب عليك اختيار إعلانات الوحدات المحيطة في الحالات التالية:

• مكتبات JavaScript الخارجية بدون @types: إذا كنت تستخدم مكتبة JavaScript (مثل أداة مساعدة أقدم، أو أداة تخطيط متخصصة، أو مكتبة داخلية خاصة) لا يوجد لها حزمة @types رسمية، فستحتاج إلى الإعلان عن وحدتها بنفسك.
• وحدات JavaScript المخصصة: إذا كان لديك جزء قديم من تطبيقك مكتوب بلغة JavaScript العادية، وتريد استهلاكه من TypeScript، فيمكنك الإعلان عن وحدته.
• استيراد الأصول غير البرمجية: للوحدات التي لا تصدر كود JavaScript ولكن يتم التعامل معها بواسطة المجمعات (مثل Webpack أو Rollup)، مثل الصور (.svg، .png)، وحدات CSS (.css، .scss)، أو ملفات JSON، يمكنك الإعلان عنها كوحدات لتمكين عمليات الاستيراد الآمنة للأنواع.

بنية وهيكل

يعيش إعلان الوحدة المحيطة عادةً في ملف .d.ts ويتبع هذا الهيكل الأساسي:

            declare module 'module-name' {
  // Declare exports here
  export function myFunction(arg: string): number;
  export const myConstant: string;
  export interface MyInterface { prop: boolean; }
  export class MyClass { constructor(name: string); greeting: string; }
  // If the module exports a default, use 'export default'
  export default function defaultExport(value: any): void;
}

            

              
                Copy
              
            
          

يجب أن يتطابق module-name تمامًا مع السلسلة التي ستستخدمها في عبارة import (مثل 'lodash-es-legacy' أو './utils/my-js-utility').

مثال عملي 1: مكتبة خارجية بدون @types

تخيل أنك تستخدم مكتبة تخطيط JavaScript قديمة تسمى 'd3-legacy-charts' لا تحتوي على تعريفات أنواع. قد يبدو ملف JavaScript الخاص بك node_modules/d3-legacy-charts/index.js شيئًا كهذا:

            // d3-legacy-charts/index.js (simplified)
export function createBarChart(data, elementId) {
  console.log('Creating bar chart with data:', data, 'on', elementId);
  // ... actual D3 chart creation logic ...
  return { success: true, id: elementId };
}

export function createLineChart(data, elementId) {
  console.log('Creating line chart with data:', data, 'on', elementId);
  // ... actual D3 chart creation logic ...
  return { success: true, id: elementId };
}

            

              
                Copy
              
            
          

لاستخدام هذا في مشروع TypeScript الخاص بك، ستقوم بإنشاء ملف إعلان، على سبيل المثال، src/types/d3-legacy-charts.d.ts:

            declare module 'd3-legacy-charts' {
  interface ChartResult {
    success: boolean;
    id: string;
  }

  export function createBarChart(data: number[], elementId: string): ChartResult;
  export function createLineChart(data: { x: number; y: number }[], elementId: string): ChartResult;
}

            

              
                Copy
              
            
          

الآن، في كود TypeScript الخاص بك، يمكنك استيراده واستخدامه بأمان الأنواع:

            import { createBarChart, createLineChart } from 'd3-legacy-charts';

const chartData = [10, 20, 30, 40, 50];
const lineChartData = [{ x: 1, y: 10 }, { x: 2, y: 20 }];

const barChartStatus = createBarChart(chartData, 'myBarChartContainer');
console.log(barChartStatus.success); // Type-checked access

// TypeScript will now correctly flag if you pass wrong arguments:
// createLineChart(chartData, 'anotherContainer'); // Error: Argument of type 'number[]' is not assignable to parameter of type '{ x: number; y: number; }[]'.

            

              
                Copy
              
            
          

تذكر أن تتأكد من أن tsconfig.json الخاص بك يتضمن دليل الأنواع المخصصة الخاص بك:

            {
  "compilerOptions": {
    // ... other options
    "typeRoots": ["./node_modules/@types", "./src/types"]
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts"]
}

            

              
                Copy
              
            
          

مثال عملي 2: الإعلان عن الأصول غير البرمجية

عند استخدام مجمع مثل Webpack، غالبًا ما تستورد الأصول غير JavaScript مباشرةً إلى الكود الخاص بك. على سبيل المثال، قد يؤدي استيراد ملف SVG إلى إرجاع مساره أو مكون React. لجعل هذا آمنًا للأنواع، يمكنك الإعلان عن وحدات لأنواع الملفات هذه.

أنشئ ملفًا، على سبيل المثال، src/types/assets.d.ts:

            declare module '*.svg' {
  import React = require('react');
  export const ReactComponent: React.FC<React.SVGProps<SVGSVGElement> & React.HTMLAttributes<SVGSVGElement>>;
  const src: string;
  export default src;
}

declare module '*.png' {
  const value: string;
  export default value;
}

declare module '*.jpg' {
  const value: string;
  export default value;
}

declare module '*.jpeg' {
  const value: string;
  export default value;
}

declare module '*.gif' {
  const value: string;
  export default value;
}

declare module '*.bmp' {
  const value: string;
  export default value;
}

declare module '*.tiff' {
  const value: string;
  export default value;
}

declare module '*.webp' {
  const value: string;
  export default value;
}

declare module '*.ico' {
  const value: string;
  export default value;
}

declare module '*.avif' {
  const value: string;
  export default value;
}

            

              
                Copy
              
            
          

الآن، يمكنك استيراد ملفات الصور بأمان الأنواع:

            import myImage from './assets/my-image.png';
import { ReactComponent as MyIcon } from './assets/my-icon.svg';

function MyComponent() {
  return (
    <div>
      <img src={myImage} alt="My Image" />
      <MyIcon style={{ width: 24, height: 24 }} />
    </div>
  );
}

            

              
                Copy
              
            
          

اعتبارات رئيسية لإعلانات الوحدات المحيطة

• الحبيبية: يمكنك إنشاء ملف .d.ts واحد لجميع إعلانات الوحدات المحيطة أو فصلها منطقيًا (مثل legacy-libs.d.ts، asset-declarations.d.ts). بالنسبة للفرق العالمية، يعد الفصل الواضح واتفاقيات التسمية أمرًا بالغ الأهمية للاكتشاف.
• الموقع: عادةً، توضع ملفات .d.ts المخصصة في دليل src/types/ أو types/ في جذر مشروعك. تأكد من أن tsconfig.json الخاص بك يتضمن هذه المسارات في typeRoots إذا لم يتم التقاطها ضمنيًا.
• الصيانة: إذا أصبحت حزمة @types رسمية متاحة لمكتبة قمت بكتابتها يدويًا، فيجب عليك إزالة إعلان الوحدة المحيطة المخصصة لتجنب التعارضات والاستفادة من تعريفات الأنواع الرسمية، والتي غالبًا ما تكون أكثر اكتمالًا.
• حل الوحدات: تأكد من أن tsconfig.json الخاص بك يحتوي على إعدادات moduleResolution مناسبة (مثل "node") حتى يتمكن TypeScript من العثور على وحدات JavaScript الفعلية في وقت التشغيل.

تعريفات الأنواع العامة (declare global)

على عكس الوحدات المحيطة، التي تصف وحدات محددة، تقوم تعريفات الأنواع العامة بتوسيع أو تعزيز النطاق العام. وهذا يعني أن أي نوع أو واجهة أو متغير يتم الإعلان عنه داخل كتلة declare global يصبح متاحًا في كل مكان في مشروع TypeScript الخاص بك دون الحاجة إلى عبارة import صريحة. توضع هذه الإعلانات عادةً داخل وحدة (مثل وحدة فارغة أو وحدة ذات صادرات) لمنع التعامل مع الملف كملف نصي عام، مما سيجعل جميع إعلاناته عامة افتراضيًا.

متى تستخدم تعريفات الأنواع العامة

تعريفات الأنواع العامة مناسبة لـ:

• توسيع كائنات المتصفح العامة: إذا كنت تضيف خصائص أو طرقًا مخصصة إلى كائنات المتصفح القياسية مثل window، document، أو HTMLElement.
• الإعلان عن متغيرات/كائنات عامة: للمتغيرات أو الكائنات التي يمكن الوصول إليها بشكل عام حقًا في جميع أنحاء وقت تشغيل تطبيقك (مثل كائن تكوين عام، أو polyfill يقوم بتعديل نموذج نوع أصلي).
• مكتبات Polyfills و Shim: عندما تقدم polyfills تضيف طرقًا إلى الأنواع الأصلية (مثل Array.prototype.myCustomMethod).
• توسيع كائن Node.js العام: على غرار window المتصفح، توسيع global أو process.env في Node.js لتطبيقات الواجهة الخلفية.

بنية وهيكل

لتعزيز النطاق العام، يجب وضع كتلة declare global الخاصة بك داخل وحدة. وهذا يعني أن ملف .d.ts الخاص بك يجب أن يحتوي على الأقل على عبارة import أو export واحدة (حتى لو كانت فارغة) لجعله وحدة. إذا كان ملف .d.ts مستقلاً بدون أي استيرادات/صادرات، فإن جميع إعلاناته تصبح عامة افتراضيًا، وdeclare global ليست ضرورية بشكل صارم، ولكن استخدامها صراحةً يوضح القصد.

            // Example of a module that augments the global scope
// global.d.ts or augmentations.d.ts

export {}; // Makes this file a module, so declare global can be used

declare global {
  interface Window {
    myGlobalConfig: { apiUrl: string; version: string; };
    myAnalyticsTracker: (eventName: string, data?: object) => void;
  }

  // Declare a global function
  function calculateChecksum(data: string): string;

  // Declare a global variable
  var MY_APP_NAME: string;

  // Extend a native interface (e.g., for polyfills)
  interface Array<T> {
    first(): T | undefined;
    last(): T | undefined;
  }
}

            

              
                Copy
              
            
          

مثال عملي 1: توسيع كائن Window

افترض أن إعداد تطبيقك العام (ربما حزمة JavaScript قديمة أو نص برمجي خارجي يتم حقنه في الصفحة) يجعل كائن myAppConfig ودالة analytics متاحين مباشرة على كائن window للمتصفح. للوصول إلى هذه العناصر بأمان من TypeScript، ستقوم بإنشاء ملف إعلان، على سبيل المثال، src/types/window.d.ts:

            // src/types/window.d.ts

export {}; // This makes the file a module, allowing 'declare global'

declare global {
  interface Window {
    myAppConfig: {
      apiBaseUrl: string;
      environment: 'development' | 'production';
      featureFlags: Record<string, boolean>;
    };
    analytics: {
      trackEvent(eventName: string, properties?: Record<string, any>): void;
      identifyUser(userId: string, traits?: Record<string, any>): void;
    };
  }
}

            

              
                Copy
              
            
          

الآن، في أي ملف TypeScript، يمكنك الوصول إلى هذه الخصائص العامة مع فحص كامل للأنواع:

            // In any .ts file

console.log(window.myAppConfig.apiBaseUrl);
window.analytics.trackEvent('page_view', { path: '/dashboard' });

// TypeScript will catch errors:
// window.analytics.trackEvent(123); // Error: Argument of type 'number' is not assignable to parameter of type 'string'.
// console.log(window.myAppConfig.nonExistentProperty); // Error: Property 'nonExistentProperty' does not exist on type '{ apiBaseUrl: string; ... }'.

            

              
                Copy
              
            
          

مثال عملي 2: تعزيز الأنواع الأصلية (Polyfill)

إذا كنت تستخدم polyfill أو أداة مساعدة مخصصة تضيف طرقًا جديدة إلى نماذج JavaScript الأصلية (مثل Array.prototype)، فستحتاج إلى الإعلان عن هذه التعزيزات عالميًا. لنفترض أن لديك أداة مساعدة تضيف طريقة .isEmpty() إلى String.prototype.

أنشئ ملفًا مثل src/types/polyfills.d.ts:

            // src/types/polyfills.d.ts

export {}; // Ensures this is treated as a module

declare global {
  interface String {
    isEmpty(): boolean;
    isPalindrome(): boolean;
  }

  interface Array<T> {
    /**
     * Returns the first element of the array, or undefined if the array is empty.
     */
    first(): T | undefined;
    /**
     * Returns the last element of the array, or undefined if the array is empty.
     */
    last(): T | undefined;
  }
}

            

              
                Copy
              
            
          

وبعد ذلك، سيكون لديك polyfill JavaScript الفعلي الخاص بك:

            // src/utils/string-polyfills.js

if (!String.prototype.isEmpty) {
  String.prototype.isEmpty = function() {
    return this.length === 0;
  };
}

if (!String.prototype.isPalindrome) {
  String.prototype.isPalindrome = function() {
    const cleaned = this.toLowerCase().replace(/[^a-z0-9]/g, '');
    return cleaned === cleaned.split('').reverse().join('');
  };
}

            

              
                Copy
              
            
          

ستحتاج إلى التأكد من تحميل polyfill JavaScript الخاص بك *قبل* أي كود TypeScript يستخدم هذه الطرق. مع الإعلان، يكتسب كود TypeScript الخاص بك أمان الأنواع:

            // In any .ts file

const myString = "Hello World";
console.log(myString.isEmpty()); // false
console.log("".isEmpty());      // true
console.log("madam".isPalindrome()); // true

const numbers = [1, 2, 3];
console.log(numbers.first()); // 1
console.log(numbers.last());  // 3

const emptyArray: number[] = [];
console.log(emptyArray.first()); // undefined

// TypeScript will flag if you try to use a non-existent method:
// console.log(myString.toUpper()); // Error: Property 'toUpper' does not exist on type 'String'.

            

              
                Copy
              
            
          

اعتبارات رئيسية لتعريفات الأنواع العامة

• استخدم بحذر شديد: بينما يكون توسيع النطاق العام قويًا، يجب القيام به باعتدال. يمكن أن يؤدي إلى "تلوث عالمي"، حيث تتضارب الأنواع أو المتغيرات عن غير قصد مع مكتبات أخرى أو ميزات JavaScript المستقبلية. هذا يمثل مشكلة خاصة في قواعد التعليمات البرمجية الكبيرة والموزعة عالميًا حيث قد تقدم فرق مختلفة إعلانات عالمية متعارضة.
• الخصوصية: كن محددًا قدر الإمكان عند تعريف الأنواع العامة. تجنب الأسماء العامة التي يمكن أن تتعارض بسهولة.
• التأثير: تؤثر الإعلانات العامة على قاعدة التعليمات البرمجية بأكملها. تأكد من أن أي تعريف نوع عام مخصص حقًا ليكون متاحًا عالميًا وتم التحقق منه بدقة من قبل فريق الهندسة المعمارية.
• النمطية مقابل العمومية: تفضل JavaScript و TypeScript الحديثة النمطية بقوة. قبل الوصول إلى تعريف نوع عام، فكر فيما إذا كانت الوحدة المستوردة بشكل صريح أو دالة مساعدة تمرر كاعتماد ستكون حلاً أنظف وأقل تدخلاً.

توسيع الوحدة (declare module 'module-name' { ... })

توسيع الوحدة هو شكل متخصص من إعلان الوحدة يستخدم للإضافة إلى أنواع الوحدة الموجودة. على عكس إعلانات الوحدات المحيطة التي تنشئ أنواعًا لوحدات لا تحتوي على أي، يقوم التوسيع بتوسيع الوحدات التي لديها بالفعل تعريفات أنواع (إما من ملفات .d.ts الخاصة بها أو من حزمة @types).

متى تستخدم توسيع الوحدة

توسيع الوحدة هو الحل الأمثل عندما:

• توسيع أنواع مكتبات الطرف الثالث: تحتاج إلى إضافة خصائص أو طرق أو واجهات مخصصة إلى أنواع مكتبة طرف ثالث تستخدمها (مثل إضافة خاصية مخصصة إلى كائن Request في Express.js، أو طريقة جديدة إلى خصائص مكون React).
• الإضافة إلى وحداتك الخاصة: على الرغم من أنها أقل شيوعًا، يمكنك توسيع أنواع وحداتك الخاصة إذا كنت بحاجة إلى إضافة خصائص ديناميكيًا في أجزاء مختلفة من تطبيقك، على الرغم من أن هذا غالبًا ما يشير إلى نمط تصميم محتمل يمكن إعادة هيكلته.

بنية وهيكل

يستخدم توسيع الوحدة نفس بناء جملة declare module 'module-name' { ... } مثل الوحدات المحيطة، ولكن TypeScript يدمج هذه الإعلانات بذكاء مع الإعلانات الموجودة إذا تطابق اسم الوحدة. يجب أن يتواجد عادةً داخل ملف وحدة نفسه ليعمل بشكل صحيح، وغالبًا ما يتطلب export {} فارغًا أو استيرادًا فعليًا.

            // express.d.ts (or any .ts file that's part of a module)

import 'express'; // This is crucial to make the augmentation work for 'express'

declare module 'express' {
  interface Request {
    user?: { // Augmenting the existing Request interface
      id: string;
      email: string;
      roles: string[];
    };
    organizationId?: string;
    // You can also add new functions to the Express Request object
    isAuthenticated(): boolean;
  }

  // You can also augment other interfaces/types from the module
  // interface Response {
  //   sendJson(data: object): Response;
  // }
}

            

              
                Copy
              
            
          

مثال عملي: توسيع كائن Express.js Request

في تطبيق ويب نموذجي مبني باستخدام Express.js، قد يكون لديك برمجيات وسيطة تقوم بمصادقة المستخدم وإرفاق معلوماته بكائن req (Request). افتراضيًا، لا تعرف أنواع Express عن خاصية user المخصصة هذه. يتيح لك توسيع الوحدة الإعلان عنها بأمان.

أولاً، تأكد من تثبيت أنواع Express: npm install express @types/express.

أنشئ ملف إعلان، على سبيل المثال، src/types/express.d.ts:

            // src/types/express.d.ts

// It's crucial to import the module you are augmenting.
// This ensures TypeScript knows which module's types to extend.
import 'express';

declare module 'express' {
  // Augment the Request interface from the 'express' module
  interface Request {
    user?: {
      id: string;
      email: string;
      firstName: string;
      lastName: string;
      permissions: string[];
      locale: string; // Relevant for global applications
    };
    requestStartTime?: Date; // Custom property added by logging middleware
    // Other custom properties can be added here
  }
}

            

              
                Copy
              
            
          

الآن، يمكن لتطبيق TypeScript Express الخاص بك استخدام خصائص user وrequestStartTime بأمان الأنواع:

            import express, { Request, Response, NextFunction } from 'express';

const app = express();

// Middleware to attach user information
app.use((req: Request, res: Response, next: NextFunction) => {
  // Simulate authentication and user attachment
  req.user = {
    id: 'user-123',
    email: 'john.doe@example.com',
    firstName: 'John',
    lastName: 'Doe',
    permissions: ['read', 'write'],
    locale: 'en-US'
  };
  req.requestStartTime = new Date();
  next();
});

app.get('/profile', (req: Request, res: Response) => {
  if (req.user) {
    res.json({
      userId: req.user.id,
      userEmail: req.user.email,
      userLocale: req.user.locale, // Accessing custom locale property
      requestTime: req.requestStartTime?.toISOString() // Optional chaining for safety
    });
  } else {
    res.status(401).send('Unauthorized');
  }
});

// TypeScript will now correctly type-check access to req.user:
// app.get('/admin', (req: Request, res: Response) => {
//   if (req.user && req.user.permissions.includes('admin')) { ... }
// });

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

            

              
                Copy
              
            
          

اعتبارات رئيسية لتوسيع الوحدة

• عبارة الاستيراد: الجانب الأكثر أهمية لتوسيع الوحدة هو عبارة import 'module-name'; الصريحة داخل ملف الإعلان. بدونها، قد يتعامل TypeScript معها على أنها إعلان وحدة محيطة بدلاً من توسيع لوحدة موجودة.
• الخصوصية: التوسيعات خاصة بالوحدة التي تستهدفها، مما يجعلها أكثر أمانًا من تعريفات الأنواع العامة لتوسيع أنواع المكتبات.
• التأثير على المستهلكين: أي مشروع يستهلك أنواعك الموسعة سيستفيد من أمان الأنواع المضاف، وهو أمر ممتاز للمكتبات المشتركة أو الخدمات المصغرة التي تم تطويرها بواسطة فرق مختلفة.
• تجنب التعارضات: إذا كانت هناك عدة توسيعات لنفس اسم الوحدة، فسوف يدمجها TypeScript. تأكد من أن هذه التوسيعات متوافقة ولا تقدم تعريفات خصائص متعارضة.

أفضل الممارسات للفرق العالمية وقواعد التعليمات البرمجية الكبيرة

بالنسبة للمؤسسات التي تعمل مع فرق عالمية وتدير قواعد بيانات ضخمة، يعد اعتماد نهج متسق ومنضبط لإعلانات الأنواع أمرًا بالغ الأهمية. ستساعد هذه الممارسات الأفضل في تقليل التعقيد وزيادة فوائد نظام أنواع TypeScript.

1. قلل من العموميات، وفضل النمطية

فضل دائمًا استيرادات الوحدات الصريحة على تعريفات الأنواع العامة كلما أمكن ذلك. يمكن أن تؤدي الإعلانات العامة، على الرغم من أنها مريحة لبعض السيناريوهات، إلى تعارضات في الأنواع، واعتمادات يصعب تتبعها، وتقليل قابلية إعادة الاستخدام عبر المشاريع المتنوعة. تجعل الاستيرادات الصريحة من الواضح مصدر الأنواع، مما يحسن سهولة القراءة وقابلية الصيانة للمطورين عبر مناطق مختلفة.

2. تنظيم ملفات .d.ts بشكل منهجي

• دليل مخصص: قم بإنشاء دليل src/types/ أو types/ مخصص في جذر مشروعك. يحافظ هذا على جميع إعلانات الأنواع المخصصة في مكان واحد يمكن اكتشافه.
• اتفاقيات تسمية واضحة: استخدم أسماء وصفية لملفات الإعلان الخاصة بك. للوحدات المحيطة، سمها باسم الوحدة (مثل d3-legacy-charts.d.ts). للأنواع العامة، اسم عام مثل global.d.ts أو augmentations.d.ts مناسب.
• تكوين tsconfig.json: تأكد من أن tsconfig.json الخاص بك يتضمن هذه الدلائل بشكل صحيح في typeRoots (للوحدات المحيطة العامة) وinclude (لجميع ملفات الإعلان)، مما يمكن مترجم TypeScript من العثور عليها. على سبيل المثال:

              {
    "compilerOptions": {
      // ...
      "typeRoots": [
        "./node_modules/@types",
        "./src/types"
      ],
      "moduleResolution": "node"
    },
    "include": [
      "src/**/*.ts",
      "src/**/*.tsx",
      "src/**/*.d.ts"
    ]
  }
      
              
  
                
                  Copy
                
              
            

3. استفد من حزم @types الموجودة أولاً

قبل كتابة أي ملفات .d.ts مخصصة لمكتبات الطرف الثالث، تحقق دائمًا مما إذا كانت حزمة @types/{اسم-المكتبة} موجودة على npm. غالبًا ما تكون هذه الحزم مجتمعية، وشاملة، ويتم تحديثها باستمرار، مما يوفر على فريقك جهدًا كبيرًا ويقلل من الأخطاء المحتملة.

4. توثيق إعلانات الأنواع المخصصة

لأي ملف .d.ts مخصص، قدم تعليقات واضحة تشرح الغرض منه، وما يعلنه، ولماذا كان ضروريًا. هذا مهم بشكل خاص للأنواع التي يمكن الوصول إليها عالميًا أو إعلانات الوحدات المحيطة المعقدة، مما يساعد أعضاء الفريق الجدد على فهم النظام بشكل أسرع ويمنع التلف العرضي خلال دورات التطوير المستقبلية.

5. الاندماج في عمليات مراجعة الكود

تعامل مع إعلانات الأنواع المخصصة على أنها كود من الدرجة الأولى. يجب أن تخضع لنفس عملية مراجعة الكود الصارمة مثل منطق تطبيقك. يجب على المراجعين التأكد من الدقة والاكتمال والالتزام بأفضل الممارسات والاتساق مع القرارات المعمارية.

6. اختبار تعريفات الأنواع

بينما لا تحتوي ملفات .d.ts على كود وقت التشغيل، فإن صحتها أمر بالغ الأهمية. فكر في كتابة "اختبارات الأنواع" باستخدام أدوات مثل dts-jest أو ببساطة التأكد من أن كود مستهلك تطبيقك يتم تجميعه بدون أخطاء في الأنواع. هذا أمر حيوي لضمان أن إعلانات الأنواع تعكس بدقة JavaScript الأساسي.

7. ضع في اعتبارك تداعيات التدويل (i18n) والترجمة (l10n)

بينما لا تعتمد إعلانات الأنواع على اللغة من حيث اللغات البشرية، إلا أنها تلعب دورًا حاسمًا في تمكين التطبيقات العالمية:

• هياكل البيانات المتسقة: تأكد من تعريف أنواع السلاسل الدولية وتنسيقات التواريخ أو كائنات العملات بوضوح واستخدامها باستمرار عبر جميع الوحدات والمناطق.
• موفرون الترجمة: إذا كان تطبيقك يستخدم موفر ترجمة عالميًا، فيجب الإعلان عن أنواعه بشكل صحيح (على سبيل المثال، window.i18n.translate('key')).
• البيانات الخاصة بالمناطق: يمكن أن تساعد الأنواع في ضمان التعامل مع هياكل البيانات الخاصة بالمناطق (مثل تنسيقات العناوين) بشكل صحيح، مما يقلل من الأخطاء عند دمج البيانات من مناطق جغرافية مختلفة.

المزالق الشائعة واستكشاف الأخطاء وإصلاحها

حتى مع التخطيط الدقيق، يمكن أن يمثل العمل مع إعلانات الأنواع تحديات في بعض الأحيان. فيما يلي بعض المزالق الشائعة ونصائح لاستكشاف الأخطاء وإصلاحها:

• "Cannot find module 'X'" أو "Cannot find name 'Y'":
  • للوحدات: تأكد من أن سلسلة إعلان الوحدة المحيطة (على سبيل المثال، 'my-library') تتطابق تمامًا مع ما هو موجود في عبارة import الخاصة بك.
  • للأنواع العامة: تأكد من تضمين ملف .d.ts الخاص بك في مصفوفة include في tsconfig.json وأن الدليل الذي يحتويه موجود في typeRoots إذا كان ملفًا محيطًا عامًا.
  • تحقق من أن إعداد moduleResolution في tsconfig.json مناسب لمشروعك (عادةً "node").
• تعارضات المتغيرات العامة: إذا قمت بتعريف نوع عام (على سبيل المثال، var MY_GLOBAL) وقامت مكتبة أخرى أو جزء من الكود الخاص بك بالإعلان عن شيء بنفس الاسم، فستواجه تعارضات. هذا يعزز نصيحة استخدام العموميات باعتدال.
• نسيان export {} لـ declare global: إذا كان ملف .d.ts الخاص بك يحتوي على إعلانات عامة فقط ولا يحتوي على import أو export، فإن TypeScript يتعامل معه على أنه "ملف نصي" وتكون جميع محتوياته متاحة عالميًا *بدون* غلاف declare global. بينما قد يعمل هذا، فإن استخدام export {} صراحةً يجعله وحدة، مما يسمح لـ declare global بالتعبير بوضوح عن نيتك لتعزيز النطاق العام من داخل سياق الوحدة.
• إعلانات محيطة متداخلة: إذا كان لديك عدة إعلانات وحدات محيطة لنفس سلسلة الوحدة في ملفات .d.ts مختلفة، فسوف يدمجها TypeScript. بينما يكون هذا مفيدًا عادةً، فقد يتسبب في مشكلات إذا كانت الإعلانات غير متوافقة.
• بيئة التطوير المتكاملة لا تلتقط الأنواع: بعد إضافة ملفات .d.ts جديدة أو تعديل tsconfig.json، يحتاج أحيانًا بيئة التطوير المتكاملة الخاصة بك (مثل VS Code) إلى إعادة تشغيل خادم لغة TypeScript الخاص بها.

الخاتمة

تعد إمكانيات إعلان الوحدات في TypeScript، والتي تشمل الوحدات المحيطة، وتعريفات الأنواع العامة، وتوسيع الوحدات، ميزات قوية تمكن المطورين من دمج TypeScript بسلاسة مع أنظمة JavaScript البيئية الموجودة وتعريف أنواع مخصصة. بالنسبة للفرق العالمية التي تبني برمجيات معقدة، فإن إتقان هذه المفاهيم ليس مجرد تمرين أكاديمي؛ إنه ضرورة عملية لتقديم تطبيقات قوية وقابلة للتوسع والصيانة.

إعلانات الوحدات المحيطة هي خيارك الأمثل لوصف وحدات JavaScript الخارجية التي تفتقر إلى تعريفات أنواع خاصة بها، مما يتيح استيرادات آمنة للأنواع لكل من الكود والأصول غير البرمجية. تسمح تعريفات الأنواع العامة، المستخدمة بحذر أكبر، بتوسيع النطاق العام، وتعزيز كائنات window المتصفح أو النماذج الأصلية. يوفر توسيع الوحدة طريقة جراحية للإضافة إلى إعلانات الوحدات الموجودة، مما يعزز أمان الأنواع للمكتبات المستخدمة على نطاق واسع مثل Express.js.

من خلال الالتزام بأفضل الممارسات - إعطاء الأولوية للنمطية، وتنظيم ملفات الإعلان الخاصة بك، والاستفادة من حزم @types الرسمية، وتوثيق أنواعك المخصصة بدقة - يمكن لفريقك تسخير القوة الكاملة لـ TypeScript. سيؤدي هذا إلى تقليل الأخطاء، وكود أوضح، وتعاون أكثر كفاءة عبر مواقع جغرافية وخلفيات تقنية متنوعة، مما يعزز في النهاية دورة تطوير برمجيات أكثر مرونة ونجاحًا. احتضن هذه الأدوات، وعزز جهود التطوير العالمية بأمان ووضوح للأنواع لا مثيل له.