Date Time Helper

You are a utility developer creating reusable date/time helper functions. The user wants to build a collection of functions for parsing, formatting, calculating, and manipulating dates and times across different scenarios.

What to check first

• Determine target environment: Node.js, browser, or both (affects available APIs like Intl.DateTimeFormat)
• Check if you need timezone support or just local time handling
• Verify whether you're working with UTC or browser-local time zones

Steps

1. Create a base function that validates date inputs — accept strings, timestamps, or Date objects using new Date() and isNaN(date.getTime())
2. Build a formatter function that uses Intl.DateTimeFormat for locale-aware formatting instead of manual string building
3. Implement date arithmetic functions using getTime() and setTime() to add/subtract milliseconds safely
4. Create a function to get the start/end of day, week, or month using setHours(0,0,0,0) and date math
5. Add a relative time formatter (e.g., "2 days ago") by calculating millisecond differences and dividing by time units
6. Build a date range validator that compares two dates using getTime() comparison
7. Implement timezone offset calculation using getTimezoneOffset() for display purposes
8. Export all functions as named exports for tree-shaking in modern bundlers

Code

// dateTimeHelper.js
const DateTimeHelper = {
  // Validate and normalize any date input to Date object
  parseDate(input) {
    if (input instanceof Date) return input;
    const date = new Date(input);
    if (isNaN(date.getTime())) throw new Error(`Invalid date: ${input}`);
    return date;
  },

  // Format date using Intl API for locale awareness
  format(date, options = {}) {
    const parsedDate = this.parseDate(date);
    const {
      locale = 'en-US',
      timeZone = undefined,
      showTime = false,
      showSeconds = false,
    } = options;

    const dateTimeOptions = {
      year: 'numeric',
      month: 'short',
      day: 'numeric',
      ...(timeZone && { timeZone }),
      ...(showTime && { hour: '2-digit', minute: '2-digit' }),
      ...(showSeconds && { second: '2-digit' }),
    };

    return new Intl.DateTimeFormat(locale, dateTimeOptions).format(parsedDate);
  },

  // Add or subtract days, hours, minutes, or milliseconds
  addTime(date, amount, unit = 'days') {
    const parsedDate = this.parseDate(date);
    const unitMs = {
      milliseconds: 1,
      seconds: 1000,
      minutes: 60 * 1000,
      hours:

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change