📆 ChronosKit

A lightweight TypeScript utility for consistent and localizable date-time formatting with support for Gregorian and Persian (Jalali) calendars using the native Intl.DateTimeFormat.

✨ Features

✅ Localized date-time formatting (en-US, fa-IR)
🍍 Support for Gregorian and Persian calendars
🔁 Caching for Intl.DateTimeFormat to improve performance
📄 Converts to ISO-like strings: YYYY-MM-DDTHH:mm:ss
🔍 Graceful handling of invalid dates

📦 Installation

npm install chronoskit

🛠 Usage

import {
  toDateTime,
  toDateTimePersian,
  toDateTimePersianFa,
  generateFormattedDateTimeObject
} from 'chronoskit'

// Standard Gregorian ISO string
toDateTime(new Date())
// => "2025-05-13T12:45:00"

// Persian calendar in ISO-like format
toDateTimePersian('2025-05-13')
// => "1404-02-23T00:00:00"

// Persian + Farsi locale (output is still numeric, but culturally formatted)
toDateTimePersianFa(Date.now())
// => "۱۴۰۴-۰۲-۲۳T۱۶:۳۰:۵۱"

🔧 API Reference

`toDateTime(param, calendar?, lang?)`

Param	Type	Default	Description
`param`	`string \	number \	Date`	required	Any valid date input
`calendar`	`'gregory' \	'persian'`	`'gregory'`	Which calendar to use
`lang`	`'en-US' \	'fa-IR'`	`'en-US'`	Which locale to use

Returns: YYYY-MM-DDTHH:mm:ss as a string or 'INVALID_DATE' if input is invalid.

`toDateTimePersian(param)`

Shortcut for:

toDateTime(param, 'persian', 'en-US')

`toDateTimePersianFa(param)`

Shortcut for:

toDateTime(param, 'persian', 'fa-IR')

`generateFormattedDateTimeObject(timestamp, calendar?, lang?)`

Parses a timestamp into an object like:

{
  year: '2025',
  month: '05',
  day: '13',
  hour: '12',
  minute: '45',
  second: '00'
}

🧪 Example Output

toDateTime(new Date('2025-05-13T12:00:00+03:30'))
// "2025-05-13T12:00:00"

toDateTimePersianFa(Date.now())
// "1404-02-23T13:15:00"

📂 Internal Types

Type	Description
`DateTimeString`	Template literal `"YYYY-MM-DDTHH:mm:ss"`
`DateTimeParts`	`{ year, month, day, hour, minute, second }`
`InvalidDateLiteral`	`'INVALID_DATE'`

包详细信息

chronoskit

自述文件