مجدول المهام بلغة TypeScript: دليل شامل لمكتبة node-schedule

مجدول المهام بلغة TypeScript: الأتمتة باستخدام node-schedule

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

التثبيت والإعداد

لتثبيت المكتبة، نفّذ الأمر التالي:

npm install node-schedulenpm install @types/node-schedule --save-dev

بعد التثبيت، يمكنك استيراد الوحدة في ملف TypeScript الخاص بك:

import * as schedule from 'node-schedule';

الإمكانيات الأساسية لـ node-schedule

• الجدولة باستخدام تعبيرات cron — دعم الأقنعة الكلاسيكية المكونة من 6 حقول (الثواني، الدقائق، الساعات، يوم الشهر، الشهر، يوم الأسبوع).
• المهام لمرة واحدة — تنفيذ الكود في لحظة زمنية محددة.
• قواعد التكرار — إنشاء فترات زمنية مخصصة باستخدام كائن RecurrenceRule.
• إلغاء المهام — إمكانية إيقاف تنفيذ مهمة مجدولة.
• دعم المناطق الزمنية — تنفيذ دقيق في المنطقة الزمنية المحددة.

مثال 1: مجدول cron بسيط

لننشئ مهمة يتم تنفيذها كل دقيقة:

import * as schedule from 'node-schedule';

const job = schedule.scheduleJob('*/1 * * * *', () => {  console.log('تم تنفيذ المهمة:', new Date().toLocaleString());});

// بعد 5 دقائق، سنلغي المهمةsetTimeout(() => {  job.cancel();  console.log('تم إلغاء المهمة');}, 5 * 60 * 1000);

في هذا المثال، تعبير cron '*/1 * * * *' يعني "كل دقيقة". لاحظ ترتيب الحقول: الثواني، الدقائق، الساعات، يوم الشهر، الشهر، يوم الأسبوع.

مثال 2: مهمة بتاريخ محدد

يمكنك جدولة التنفيذ في وقت محدد في المستقبل:

import * as schedule from 'node-schedule';

const date = new Date(2025, 11, 31, 23, 59, 0); // 31 ديسمبر 2025، الساعة 23:59

const job = schedule.scheduleJob(date, () => {  console.log('حلّت السنة الجديدة!');});

// نتحقق مما إذا كانت المهمة مجدولةconsole.log('المهمة نشطة:', job !== null);

مثال 3: قاعدة التكرار (RecurrenceRule)

إذا كانت تعبيرات cron تبدو معقدة، استخدم كائن RecurrenceRule لإنشاء قواعد واضحة:

import * as schedule from 'node-schedule';

const rule = new schedule.RecurrenceRule();rule.hour = 9;rule.minute = 30;rule.dayOfWeek = [1, 3, 5]; // الإثنين، الأربعاء، الجمعة

const job = schedule.scheduleJob(rule, () => {  console.log('اجتماع الصباح الساعة 9:30 في أيام الأسبوع (إثنين، أربعاء، جمعة)');});

// للإلغاء بعد شهر:setTimeout(() => job.cancel(), 30 * 24 * 60 * 60 * 1000);

مثال 4: مهمة بمنطقة زمنية

إذا كان تطبيقك يعمل في مناطق زمنية مختلفة، حدد المنطقة الزمنية:

import * as schedule from 'node-schedule';

const job = schedule.scheduleJob(  { hour: 8, minute: 0, tz: 'Europe/Moscow' },  () => {    console.log('صباح موسكو: 8:00');  });

معالجة الأخطاء وإلغاء المهام

احرص دائمًا على تضمين معالجة الأخطاء داخل دالة الاستدعاء لتجنب تعطل التطبيق:

import * as schedule from 'node-schedule';

const job = schedule.scheduleJob('*/5 * * * *', async () => {  try {    // الكود غير المتزامن الخاص بك    const data = await fetchDataFromAPI();    console.log('تم استلام البيانات:', data);  } catch (error) {    console.error('خطأ في المجدول:',