🗓 Natural Language Date Parser

A modular, preference-based date/time parser that handles natural language expressions with confidence scoring and debugging capabilities.

✨ Features

• 📝 Parse natural language date/time expressions
• 🌍 Timezone-aware with full DST support
• ⚙️ Configurable preferences (week start, reference date)
• 🎯 Confidence scoring for parse results
• 🐛 Debug mode with detailed parse traces
• 📦 Modular rule system for easy extension

🚀 Quick Start

import { NLDP } from 'natural-language-date-parser';

const parser = new NLDP({
    referenceDate: new Date(),
    weekStartsOn: 1, // Monday
    timeZone: 'America/New_York'
});

const result = parser.parse('next Monday at 3pm');
console.log(result);

📖 Supported Expressions

🗓 Absolute Dates

• ISO format: "2024-03-20", "03/20/2024"
• Month names: "January 5, 2025", "Jan 5th, 2025"
• Day first: "5 January 2025", "5th Jan 2025"
• Current year: "January 5", "5th Jan"

⏰ Time

• 12-hour: "3:30 PM", "3pm"
• 24-hour: "15:30"
• Special times: "noon", "midnight"
• With dates: "March 20th at 3:30 PM"

📅 Relative Days

• Simple: "today", "tomorrow", "yesterday"
• Extended: "day after tomorrow", "day before yesterday"
• Offset: "3 days from now", "2 days ago"
• Next weekday: "next Monday", "next Friday"

📊 Ordinal Days

• Month-based: "first Monday in March", "last Friday in March"
• Numeric: "2nd Thursday in March"
• Month end: "last day of month", "penultimate day"
• Position: "third to last day of month"

📦 Week Expressions

• Simple: "this week", "next week", "last week"
• Extended: "week after next"
• Offset: "3 weeks from now"
• With weekday start preference

📋 Month Parts

• Segments: "early March", "mid March", "late March"
• Halves: "first half of April", "second half of April"
• Boundaries: "beginning of April", "end of March"

🎯 Fuzzy Ranges

• Weekends: "this weekend", "next weekend"
• Multiple: "next 2 weekends", "following 3 weekends"
• Month parts: "first 3 days of next month", "last 5 days of March"

🔄 Combined Expressions

• Date + Time: "tomorrow at 3pm", "next Monday at 3:30pm"
• Relative + Time: "3 days from now at noon"
• Ordinal + Time: "1st of April at midnight"

All expressions support:

• 🌍 Timezone awareness
• 📊 Confidence scoring
• 🎯 Range or single date output
• 🐛 Detailed debug traces

⚙️ Configuration

interface DateParsePreferences {
    referenceDate?: Date;
    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
    timeZone?: string;
    debug?: boolean;
}

🔍 Debug Mode

Enable detailed parsing traces:

const result = parser.parse('next Monday at 3pm', { debug: true });

🧪 Testing

npm test

🤝 Contributing

Contributions are welcome! Please see the CONTRIBUTING.md for details.

📝 License

This project is open-sourced under the MIT License - see the LICENSE file for details.