PersianDateTimeHelper 1.0.0

PersianDateTimeHelper

A comprehensive .NET library for working with the Iranian (Jalali/Shamsi) calendar.

Holiday detection · Working hours · Overtime · Persian date conversion

Features

• Detect whether any date is an Iranian public holiday
• Get all holidays in a given Jalali month or year
• Count holidays / working days in any period
• Calculate working hours and overtime (per Iranian labour law)
• Convert between Gregorian and Jalali (Shamsi) dates
• ASP.NET Core DI integration (services.AddPersianDateTimeHelper())
• Custom holiday provider support (IHolidayProvider)
• Fluent extension methods on DateTime

Installation

dotnet add package PersianDateTimeHelper

Quick Start

using PersianDateTimeHelper.Services;
using PersianDateTimeHelper.Extensions;

// --- Holiday checks ---
var svc = new IranHolidayService();

DateTime today = DateTime.Now;
bool isHoliday = svc.IsHoliday(today);            // true if official holiday OR weekend
bool isOfficial = svc.IsOfficialHoliday(today);   // official holiday only (not weekend)
bool isWorkday = svc.IsWorkday(today);

// --- Or use extension methods ---
bool holiday = today.IsIranHoliday();
string shamsi = today.ToShamsi();                  // "1403/07/15"
string dayName = today.ToPersianDayName();         // "شنبه"

Holiday Queries

var svc = new IranHolidayService();

// Get all holidays in Farvardin 1403
var holidays = svc.GetHolidaysInMonth(1403, 1);
foreach (var h in holidays)
    Console.WriteLine($"{h.Day} {h.TitleFa} ({h.TitleEn})");

// Get all holidays in a year
var yearHolidays = svc.GetHolidaysInYear(1403);

// Count
int officialCount  = svc.CountOfficialHolidaysInYear(1403);
int workdays       = svc.CountWorkdaysInMonth(1403, 6);
int nonWorkingDays = svc.CountNonWorkingDaysInMonth(1403, 1);

// Range queries
var range = svc.GetHolidaysInRange(new DateTime(2024, 3, 1), new DateTime(2024, 4, 30));

// Navigation
var nextHoliday  = svc.GetNextHoliday(DateTime.Now);
var nextWorkday  = svc.GetNextWorkday(DateTime.Now);
var holidayInfo  = svc.GetHolidayInfo(new DateTime(2024, 3, 20)); // returns IranHoliday or null

Working Hours & Overtime

var calc = new IranWorkCalculator();

DateTime monday = new DateTime(2024, 3, 25);

double scheduledHours = calc.GetWorkingHours(monday);          // 8.0
double overtime       = calc.GetOvertimeHours(monday, 10.0);   // 2.0  (10h worked - 8h official)
double effective      = calc.GetEffectiveHours(monday, 10.0);  // 10.8 (8 + 2×1.4)

// Full daily summary
WorkDaySummary summary = calc.GetDaySummary(monday, actualHoursWorked: 10.0);
Console.WriteLine($"{summary.PersianDate} | {summary.DayNameFa}");
Console.WriteLine($"Regular: {summary.RegularHours}h | Overtime: {summary.OvertimeHours}h @ {summary.OvertimeRate}x");
Console.WriteLine($"Effective: {summary.EffectiveHours}h");

// Holiday overtime — all hours count as overtime
DateTime nowruz = new DateTime(2024, 3, 20);
double holidayOT = calc.GetOvertimeHours(nowruz, 6.0);  // 6.0 (all hours are OT on holidays)

// Monthly / yearly schedules
var monthSchedule = calc.GetMonthSchedule(1403, 1);   // all 31 days of Farvardin
double monthHours = calc.GetTotalWorkingHoursInMonth(1403, 6);
double yearHours  = calc.GetTotalWorkingHoursInYear(1403);

// Work start/end times
DateTime? start = calc.GetWorkStartTime(monday);  // 2024-03-25 08:00
DateTime? end   = calc.GetWorkEndTime(monday);    // 2024-03-25 17:00

Persian Date Conversion

using PersianDateTimeHelper.Services;

// Gregorian → Jalali
var (year, month, day) = PersianDateHelper.ToJalali(new DateTime(2024, 3, 20));
// year=1403, month=1, day=1

// Jalali → Gregorian
DateTime greg = PersianDateHelper.ToGregorian(1403, 1, 1); // 2024-03-20

// Formatted string
string shamsi = PersianDateHelper.ToShamsiString(DateTime.Now);          // "1403/07/15"
string dashed = PersianDateHelper.ToShamsiString(DateTime.Now, "-");     // "1403-07-15"

// Names
string monthFa = PersianDateHelper.GetMonthNameFa(1);    // "فروردین"
string monthEn = PersianDateHelper.GetMonthNameEn(1);    // "Farvardin"
string dayFa   = PersianDateHelper.GetDayNameFa(DateTime.Now);

// Helpers
bool isLeap     = PersianDateHelper.IsLeapYear(1403);     // true
int  daysInMon  = PersianDateHelper.GetDaysInMonth(1403, 1); // 31

Custom Work Configuration

using PersianDateTimeHelper.Models;

var config = new WorkConfig
{
    WorkStartTime      = new TimeSpan(9, 0, 0),    // 09:00
    WorkEndTime        = new TimeSpan(18, 0, 0),   // 18:00
    BreakDuration      = new TimeSpan(0, 30, 0),   // 30 min break
    OfficialDailyHours = 7.5,                      // 7.5h official day
    OvertimeRateWeekday = 1.5,                     // 50% overtime on weekdays
    OvertimeRateHoliday = 1.4,                     // 40% overtime on holidays
};

var calc = new IranWorkCalculator(config: config);

Custom Holiday Provider

Plug in your own data source (database, API, etc.):

using PersianDateTimeHelper.Abstractions;
using PersianDateTimeHelper.Models;

public class MyHolidayProvider : IHolidayProvider
{
    public IEnumerable<IranHoliday> GetHolidays(int jalaliYear)
    {
        // load from your database/API here
        return myDb.GetIranHolidays(jalaliYear);
    }
}

// Use it:
var svc  = new IranHolidayService(provider: new MyHolidayProvider());
var calc = new IranWorkCalculator(holidayService: svc);

ASP.NET Core Dependency Injection

// Program.cs
builder.Services.AddPersianDateTimeHelper();

// Or with custom configuration:
builder.Services.AddPersianDateTimeHelper(cfg =>
{
    cfg.WorkStartTime       = new TimeSpan(8, 30, 0);
    cfg.WorkEndTime         = new TimeSpan(17, 30, 0);
    cfg.OvertimeRateHoliday = 1.5;
});

// With a custom holiday provider:
builder.Services.AddPersianDateTimeHelper(
    cfg => cfg.OfficialDailyHours = 7.5,
    provider: new MyHolidayProvider()
);

// In your service/controller:
public class AttendanceService
{
    private readonly IranHolidayService _holidays;
    private readonly IranWorkCalculator _work;

    public AttendanceService(IranHolidayService holidays, IranWorkCalculator work)
    {
        _holidays = holidays;
        _work     = work;
    }
}

Extension Methods Reference

About Holidays

The library ships with all official Iranian public holidays embedded:

Fixed national holidays (same Jalali date every year): Nowruz (4 days), Islamic Republic Day, Nature Day (Sizdah Bedar), Death of Imam Khomeini, Uprising of Khordad 15, Revolution Anniversary, Oil Nationalisation Day.

Religious/lunar holidays: Dates are approximate because Islamic holidays follow the lunar (Hijri) calendar and shift each Jalali year. For production use, update these via IHolidayProvider with confirmed government announcements for each year.

Weekend: Friday is always treated as weekend (modern Iranian government/business standard). Pass includeThursdayWeekend: true to also flag Thursday for organisations that still follow the old Thursday+Friday weekend.

License

MIT © 2026. Contributions welcome!