DateTrigger

A powerful, flexible JavaScript library for scheduling date-based events with a modern, fluent API.

✨ Key Features

• Fluent API: Chainable, intuitive method calls
• Flexible Scheduling: Specific dates, ranges, recurring patterns, and custom matchers
• Priority System: Control execution order
• TypeScript: Full type support
• Browser & Node: Works everywhere

🚀 Installation

NodeJS:

npm install datetrigger

Browser:

<script src="https://unpkg.com/datetrigger/dist/web.min.js" type="module"></script>

📖 Basic Usage

import DateTrigger from 'datetrigger';

// Create instance (starts automatically)
const dt = new DateTrigger({ verbose: true });

// Trigger on a specific date
dt.trigger.on(new Date(2025, 11, 25), () => {
  console.log('Merry Christmas! 🎄');
});

// That's it!

🎯 API Examples

Specific Date Triggers

// Single date
dt.trigger.on(new Date(2025, 0, 1), () => {
  console.log('Happy New Year!');
}, { name: 'New Year 2025' });

// Date range
dt.trigger.between(
  new Date(2025, 11, 1),
  new Date(2025, 11, 31),
  () => {
    console.log('December vibes!');
  }
);

Recurring Triggers

// Every day
dt.trigger.daily(() => {
  console.log('Good morning!');
});

// Specific days of week
dt.trigger.onDayOfWeek(1, () => {
  console.log('Monday motivation!');
}); // 0=Sunday, 1=Monday, etc.

// Multiple days
dt.trigger.onDayOfWeek([1, 3, 5], () => {
  console.log('MWF workout day!');
});

// Weekdays only
dt.trigger.onWeekdays(() => {
  console.log('Time to work!');
});

// Weekends only
dt.trigger.onWeekends(() => {
  console.log('Relax time!');
});

// Specific day of month
dt.trigger.onDayOfMonth(15, () => {
  console.log('Mid-month check-in');
});

// Multiple days
dt.trigger.onDayOfMonth([1, 15], () => {
  console.log('Bi-monthly reminder');
});

// Specific months
dt.trigger.onMonth([0, 6], () => {
  console.log('January or July');
});

Holiday Helpers

dt.trigger.onChristmas(2025, () => {
  console.log('🎄 Merry Christmas!');
});

dt.trigger.onNewYear(2026, () => {
  console.log('🎉 Happy New Year!');
});

dt.trigger.onEaster(2025, () => {
  console.log('🐰 Happy Easter!');
});

Custom Matchers

// Leap year only
dt.trigger.when(
  (date) => {
    const year = date.getFullYear();
    return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
  },
  () => {
    console.log('It\'s a leap year!');
  },
  { name: 'Leap Year Trigger' }
);

// First Monday of every month
dt.trigger.when(
  (date) => {
    return date.getDay() === 1 && date.getDate() <= 7;
  },
  () => {
    console.log('First Monday of the month!');
  }
);

// Last day of month
dt.trigger.when(
  (date) => {
    const tomorrow = new Date(date);
    tomorrow.setDate(date.getDate() + 1);
    return tomorrow.getDate() === 1;
  },
  () => {
    console.log('Last day of the month!');
  }
);

Advanced Configuration

// One-time trigger
const id = dt.trigger.on(
  new Date(2025, 0, 1),
  () => console.log('This runs only once'),
  { 
    once: true,
    name: 'One-time event'
  }
);

// Priority execution (higher numbers run first)
dt.trigger.on(
  new Date(2025, 0, 1),
  () => console.log('I run first!'),
  { priority: 100 }
);

dt.trigger.on(
  new Date(2025, 0, 1),
  () => console.log('I run second'),
  { priority: 50 }
);

// Start disabled
const disabledId = dt.trigger.on(
  new Date(2025, 0, 1),
  () => console.log('Not yet...'),
  { enabled: false }
);

// Enable later
dt.enable(disabledId);

Managing Triggers

// Remove a trigger
const id = dt.trigger.daily(() => console.log('Daily'));
dt.remove(id);

// Disable/enable triggers
dt.disable(id);
dt.enable(id);

// Clear all triggers
dt.clear();

// Check triggers manually
await dt.checkNow();

// View statistics
const stats = dt.stats();
console.log(stats);
/*
{
  total: 5,
  enabled: 4,
  disabled: 1,
  triggers: [
    { id: '...', name: '...', enabled: true, executions: 3 },
    ...
  ]
}
*/

Lifecycle Control

// Create without auto-starting
const dt = new DateTrigger({ autoStart: false });

// Add triggers
dt.trigger.daily(() => console.log('Ready'));

// Start when ready
dt.start();

// Stop scheduler
dt.stop();

// Restart
dt.start();

Custom Check Interval

// Check every 10 seconds instead of every minute
const dt = new DateTrigger({ 
  checkInterval: 10000,
  verbose: true 
});

🔧 Configuration Options

DateTrigger Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | checkInterval | number | 60000 | How often to check triggers (ms) | | verbose | boolean | false | Enable console logging | | autoStart | boolean | true | Start scheduler immediately |

Trigger Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | id | string | auto | Custom trigger ID | | name | string | auto | Descriptive name | | enabled | boolean | true | Initially enabled | | once | boolean | false | Execute only once | | priority | number | 0 | Execution priority (higher first) |

🎨 Real-World Examples

Website Seasonal Theme

const dt = new DateTrigger();

// Christmas theme
dt.trigger.between(
  new Date(2025, 11, 1),
  new Date(2025, 11, 26),
  () => {
    document.body.classList.add('christmas-theme');
  }
);

// Halloween theme
dt.trigger.onMonth(9, () => {
  if (new Date().getDate() <= 31) {
    document.body.classList.add('halloween-theme');
  }
});

Reminder System

// Morning reminder (weekdays only)
dt.trigger.onWeekdays(() => {
  notify('Good morning! Time to start the day!');
}, { name: 'Morning Reminder' });

// Weekly meeting reminder (every Monday)
dt.trigger.onDayOfWeek(1, () => {
  notify('Weekly team meeting at 10am!');
});

// Monthly report reminder (1st of each month)
dt.trigger.onDayOfMonth(1, () => {
  notify('Monthly report is due!');
});

Feature Flags & A/B Testing

// Enable feature during specific period
const featureId = dt.trigger.between(
  new Date(2025, 0, 1),
  new Date(2025, 2, 31),
  () => {
    enableFeature('new-dashboard');
  },
  { name: 'Q1 Feature Rollout' }
);

// Disable when done
// dt.remove(featureId);

💡 Tips

1. Use descriptive names for easier debugging
2. Set priorities when multiple triggers run on the same date
3. Use once: true for one-time events like announcements
4. Check stats regularly to monitor trigger performance
5. Adjust checkInterval based on your precision needs

📝 TypeScript

Full TypeScript support included:

import DateTrigger from 'datetrigger';

const dt = new DateTrigger({ verbose: true });

const id: string = dt.trigger.on(
  new Date(),
  async () => {
    await doSomethingAsync();
  },
  { priority: 10 }
);

🌐 Browser Usage

<!DOCTYPE html>
<html>
<head>
  <title>DateTrigger Demo</title>
</head>
<body>
  <h1>Check console!</h1>
  
  <script type="module">
    import DateTrigger from 'https://unpkg.com/datetrigger/dist/web.min.js';
    
    const dt = new DateTrigger({ verbose: true });
    
    dt.trigger.onWeekends(() => {
      console.log('It\'s the weekend! 🎉');
    });
  </script>
</body>
</html>

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.