التسجيل في TypeScript: مكتبة winston

```html

ما هو winston ولماذا هو مطلوب؟

Winston هي مكتبة قوية ومرنة لتسجيل السجلات (logging) في تطبيقات TypeScript و JavaScript. تسمح بتسجيل رسائل منظمة بمستويات مختلفة (info, warn, error, debug) في وحدة التحكم، الملفات، قواعد البيانات أو الخدمات الخارجية. يحل Winston مشكلة عدم وجود آلية تسجيل مدمجة في Node.js، من خلال توفير واجهة برمجة تطبيقات (API) ملائمة لتكوين التنسيقات، والناقلات (أين يتم كتابة السجلات) ومستويات الأهمية. تُستخدم المكتبة على نطاق واسع في مشاريع الإنتاج، والخدمات المصغرة، وتطبيقات الويب.

التثبيت

لتثبيت winston في مشروع TypeScript، قم بتنفيذ:

npm install winstonnpm install --save-dev @types/winston

أو عبر yarn:

yarn add winstonyarn add --dev @types/winston

الوظائف الأساسية

مستويات التسجيل: error, warn, info, http, verbose, debug, silly (يمكن تخصيص مستوياتك الخاصة).
الناقلات: Console, File, HTTP, Stream، بالإضافة إلى ناقلات مخصصة (مثل Elasticsearch).
التنسيقات: JSON، نص عادي، طابع زمني (timestamp)، علامات، ألوان في وحدة التحكم.
ناقلات متعددة: الكتابة في وقت واحد إلى وحدة التحكم وملف.
تسجيل الاستثناءات: اعتراض تلقائي لـ uncaughtException.
غلاف وكيل (Proxy wrapper) لـ TypeScript: مسجل سجلات (logger) بنمط كتابة (typed) مع إكمال تلقائي.

مثال كود بلغة TypeScript

import winston from 'winston';

const logger = winston.createLogger({  level: 'info',  format: winston.format.combine(    winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),    winston.format.json()  ),  transports: [    new winston.transports.Console({      format: winston.format.combine(        winston.format.colorize(),        winston.format.simple()      )    }),    new winston.transports.File({ filename: 'error.log', level: 'error' }),    new winston.transports.File({ filename: 'combined.log' })  ]});

// الاستخدامlogger.info('الخادم يعمل على المنفذ 3000');logger.warn('مستوى ذاكرة منخفض');logger.error('خطأ في الاتصال بقاعدة البيانات', { error: err });

متى تستخدم winston

Winston مثالي لـ:

تطبيقات الواجهة الخلفية (Backend) على Node.js/TypeScript (Express, NestJS, Fastify).
الهندسة المعمارية للخدمات المصغرة — جمع مركزي للسجلات عبر ناقل HTTP.
مراقبة الإنتاج — كتابة السجلات إلى ملفات مع التدوير (winston-daily-rotate-file).
التصحيح والتطوير — إخراج ملون في وحدة التحكم بمستويات مختلفة.
الأنظمة ذات متطلبات التدقيق — سجلات منظمة بصيغة JSON للتحليل.

لا تستخدم winston في البرامج النصية البسيطة حيث يكون console.log كافياً — فهو مبالغ فيه للمشاريع الصغيرة. تجنب أيضاً استخدام winston في تطبيقات المتصفح من جانب العميل (من الأفضل استخدام console أو مكتبات متخصصة هناك).

الخلاصة

Winston هو المعيار الفعلي (de facto) لتسجيل السجلات في مشاريع TypeScript. يوفر المرونة والأداء والأمان النمطي (type safety) عند التكوين الصحيح. ابدأ بمسجل سجلات بسيط وقم بتوسيعه مع نمو تطبيقك.

```