Persian-Calendar

Overview

The Persian Calendar API provides comprehensive functionality for retrieving Persian calendar dates, holidays, and date conversions. This documentation outlines all available endpoints, their responses, and integration examples.

Features

• Yearly Calendar: Displays the full calendar for a specified Persian year (e.g., 1405).
• Holiday Check: Determines if a specific date (e.g., 14040621) is a holiday.
• Year Holidays: Lists all holidays in a given Persian year.
• Year Workdays: Lists all workdays in a given Persian year.
• Monthly Calendar: Retrieves the calendar for a specific month and year (e.g., Farvardin 1404).
• Leap Year Check: Checks if a given Persian year is a leap year.
• Days Between Dates: Calculates the number of days between two Persian dates.
• Date Conversion: Converts dates between Persian (Shamsi) and Gregorian (Miladi) formats.

Prerequisites

• Node.js: Ensure you have Node.js installed (recommended version: 18.x or higher).
• Angular CLI: Install the Angular CLI globally using npm install -g @angular/cli.
• PersianCalendarService: Ensure the PersianCalendarService is available and properly configured (assumed to be an external service or library).

Installation

1. Clone the Repository:

   git clone <repository-url>
   cd persian-calendar

2. Install Dependencies:

   npm install persian-calendar

3. Run the Application:

   ng serve

   The app will be available at http://localhost:4200.

Project Structure

• app.component.ts: The main component that interacts with the PersianCalendarService to fetch and display calendar data.
• app.component.html: The template file for rendering the calendar data.
• app.component.css: The styles for the app component.
• PersianCalendarService: An external service (assumed to be injected) that provides methods for Persian calendar operations.

Usage

The AppComponent is a standalone Angular component that uses the PersianCalendarService to perform the following operations in the ngOnInit lifecycle hook:

1. Get Yearly Calendar: Fetches the full calendar for the Persian year 1405.
2. Check Holiday: Checks if the date 14040621 (21st of Shahrivar, 1404) is a holiday.
3. Get Year Holidays: Retrieves all holidays for the Persian year 1405.
4. Get Year Workdays: Retrieves all workdays for the Persian year 1405.
5. Get Month Calendar: Fetches the calendar for Farvardin (month 01) of 1404.
6. Check Leap Year: Determines if 1404 is a leap year.
7. Days Between Dates: Calculates the number of days between 14040621 and 14040630.
8. Convert Shamsi to Miladi: Converts the Persian date 14040621 to its Gregorian equivalent.
9. Convert Miladi to Shamsi: Converts the Gregorian date 2025-09-12 to its Persian equivalent.

The results are stored in component properties and can be displayed in the template (app.component.html).

Error Handling

The application includes basic error handling:

• All service calls are wrapped in a try-catch block to handle potential errors from the PersianCalendarService.
• Errors are logged to the console, and a loading flag is used to indicate when data fetching is complete.

Example Output

Assuming the PersianCalendarService returns valid data, the component properties will be populated as follows:

• yearlyCalendar: The full calendar for 1405.
• holidayStatus: true or false indicating if 14040621 is a holiday.
• yearHolidays: A list of holidays in 1405.
• yearWorkdays: A list of workdays in 1405.
• monthCalendar: The calendar for Farvardin 1404.
• leapYearStatus: true or false indicating if 1404 is a leap year.
• daysBetween: The number of days between 14040621 and 14040630.
• miladiDate: The Gregorian equivalent of 14040621 (e.g., 2025-09-12).
• shamsiDate: The Persian equivalent of 2025-09-12 (e.g., 14040621).

Example Using

import { Component, OnInit } from '@angular/core';
import { CommonModule } from '@angular/common';
import { PersianCalendarService } from 'persian-calendar';

@Component({
selector: 'app-root',
standalone: true,
imports: [CommonModule],
templateUrl: './app.component.html',
styleUrls: ['./app.component.css'],
})
export class AppComponent implements OnInit {
title = 'demo-app';

yearlyCalendar: any;
holidayStatus: boolean | null = null;
yearHolidays: any;
yearWorkdays: any;
monthCalendar: any;
leapYearStatus: boolean | null = null;
daysBetween: any ;
miladiDate: string | null = null;
shamsiDate: string | null = null;

constructor(private calendarService: PersianCalendarService) { }
loading = true;

async ngOnInit() {
 try {
   // 1. Get yearly calendar
   this.yearlyCalendar = await this.calendarService.call('getYearlyCalendar', '1405');

   // 2. Check if a specific date is holiday
   this.holidayStatus = await this.calendarService.call('isHoliday', '14040621');

   // 3. Get year holidays
   this.yearHolidays = await this.calendarService.call('getYearHolidays', '1405');

   // 4. Get year workdays
   this.yearWorkdays = await this.calendarService.call('getYearWorkdays', '1405');

   // 5. Get month calendar
   this.monthCalendar = await this.calendarService.call('getMonthCalendar', { year: '1404', month: '01' });

   // 6. Check leap year
   this.leapYearStatus = await this.calendarService.call('isLeapYear', '1404');

   // 7. Get days between two dates
   this.daysBetween = await this.calendarService.call('getDaysBetween', { start: '14040621', end: '14040630' });

   // 8. Convert Shamsi to Miladi
   this.miladiDate = await this.calendarService.call('convertShamsiToMiladi', '14040621');

   // 9. Convert Miladi to Shamsi
   this.shamsiDate = await this.calendarService.call('convertMiladiToShamsi', '2025-09-12');

 } catch (err) {
   console.error('Error calling PersianCalendarService:', err);
 }
 finally {
   this.loading = false;
 }
}
}

Notes

• The PersianCalendarService is assumed to be an external dependency. Ensure it is properly configured and available in your project.
• The date format used for Persian dates is YYYYMMDD (e.g., 14040621 for 21st Shahrivar 1404).
• The application uses Angular's standalone component feature, requiring Angular 14 or higher.

Contributing

Contributions are welcome! Please submit a pull request or open an issue for any bugs or feature requests.

License

This project is licensed under the MIT License.