feat: expose methods for converting between iso8601 and calendars

README.md

@@ -249,6 +249,44 @@ it('should get today date in Ethiopic', () => {
 })
 ```
 
+## convertFromIso8601 and convertToIso8601
+
+`convertFromIso8601` and `convertToIso8601` are used to convert between Iso8601 (gregorian) dates and specific calendars (i.e. Ethiopic or Nepali). It accepts either a string in the format `yyyy-MM-dd` or an object representing the date properties (`year`, `month` and `day`).
+
+### Examples
+
+```js
+it('should convert a gregorian date to ethiopic', () => {
+    const result = convertFromIso8601('2024-05-23', 'ethiopic')
+    expect(result).toMatchObject({
+        year: 7516,
+        eraYear: 2016,
+        month: 9,
+        day: 15,
+    })
+})
+it('should convert a Nepali date to gregorian', () => {
+    const result = convertToIso8601('2081-02-10', 'nepali')
+    expect(result).toMatchObject({ year: 2024, month: 5, day: 23 })
+})
+ it('should convert an ethiopic date to gregorian', () => {
+    const result = convertToIso8601('2016-09-15', 'ethiopic')
+    expect(result).toMatchObject({ year: 2024, month: 5, day: 23 })
+})
+it('should accept a date object instead of a string', () => {
+    const result = convertToIso8601(
+        {
+            year: 2081,
+            month: 2,
+            day: 10,
+        },
+        'nepali'
+    )
+    expect(result).toMatchObject({ year: 2024, month: 5, day: 23 })
+})
+```
+
+
 ### Types
 
 The method takes two positional arguments:

src/index.ts

@@ -1,4 +1,9 @@
 export * from './hooks'
 export * as constants from './constants'
 export * from './period-calculation'
-export { getNowInCalendar, validateDateString, convertDate } from './utils'
+export {
+    getNowInCalendar,
+    validateDateString,
+    convertFromIso8601,
+    convertToIso8601,
+} from './utils'

src/utils/convert-date.spec.ts

@@ -0,0 +1,122 @@
+import { convertFromIso8601, convertToIso8601 } from '../'
+
+describe('date conversion from gregorian', () => {
+    describe('to ethiopic', () => {
+        it('should convert a date', () => {
+            const result = convertFromIso8601('2024-05-23', 'ethiopic')
+            expect(result).toMatchObject({
+                year: 7516,
+                eraYear: 2016,
+                month: 9,
+                day: 15,
+            })
+        })
+        it('should convert a date object', () => {
+            const result = convertFromIso8601(
+                {
+                    year: 2024,
+                    month: 5,
+                    day: 23,
+                },
+                'ethiopic'
+            )
+            expect(result).toMatchObject({
+                year: 7516,
+                eraYear: 2016,
+                month: 9,
+                day: 15,
+            })
+        })
+        it('should convert a date if "ethiopian" is passed instad of "ethiopic"', () => {
+            const result = convertFromIso8601('2024-05-23', 'ethiopian' as any)
+            expect(result).toMatchObject({
+                year: 7516,
+                eraYear: 2016,
+                month: 9,
+                day: 15,
+            })
+        })
+    })
+    describe('to nepali', () => {
+        it('should convert a date', () => {
+            const result = convertFromIso8601('2024-05-23', 'nepali')
+            expect(result).toMatchObject({
+                eraYear: 2081,
+                year: 2081,
+                month: 2,
+                day: 10,
+            })
+        })
+
+        it('should convert a date object', () => {
+            const result = convertFromIso8601(
+                {
+                    year: 2024,
+                    month: 5,
+                    day: 23,
+                },
+                'nepali'
+            )
+            expect(result).toMatchObject({
+                eraYear: 2081,
+                year: 2081,
+                month: 2,
+                day: 10,
+            })
+        })
+    })
+    it('should convert to islamic date', () => {
+        const result = convertFromIso8601('2024-05-23', 'islamic')
+        expect(result).toMatchObject({
+            eraYear: 1445,
+            year: 1445,
+            month: 11,
+            day: 15,
+        })
+    })
+})
+
+describe('date conversion to gregorian', () => {
+    describe('ethiopic to gregorian', () => {
+        it('should convert a date taking care of setting the correct era for ethiopic calendar', () => {
+            const result = convertToIso8601('2016-09-15', 'ethiopic')
+            expect(result).toMatchObject({ year: 2024, month: 5, day: 23 })
+        })
+        it('should convert a date if "ethiopian" is passed instad of "ethiopic"', () => {
+            const result = convertToIso8601('2016-09-15', 'ethiopian' as any)
+            expect(result).toMatchObject({ year: 2024, month: 5, day: 23 })
+        })
+        it('should convert a date object', () => {
+            const result = convertToIso8601(
+                {
+                    year: 2016,
+                    month: 9,
+                    day: 15,
+                },
+                'ethiopic'
+            )
+            expect(result).toMatchObject({ year: 2024, month: 5, day: 23 })
+        })
+    })
+    describe('nepali to gregorian', () => {
+        it('should convert a date', () => {
+            const result = convertToIso8601('2081-02-10', 'nepali')
+            expect(result).toMatchObject({ year: 2024, month: 5, day: 23 })
+        })
+        it('should convert a date object', () => {
+            const result = convertToIso8601(
+                {
+                    year: 2081,
+                    month: 2,
+                    day: 10,
+                },
+                'nepali'
+            )
+            expect(result).toMatchObject({ year: 2024, month: 5, day: 23 })
+        })
+    })
+    it('islamic to gregorian', () => {
+        const result = convertToIso8601('1445-11-15', 'islamic')
+        expect(result).toMatchObject({ year: 2024, month: 5, day: 23 })
+    })
+})

src/utils/convert-date.ts

@@ -1,15 +1,81 @@
 import { Temporal } from '@js-temporal/polyfill'
-import { NepaliCalendar } from '../custom-calendars/nepaliCalendar'
+import { dhis2CalendarsMap } from '../constants/dhis2CalendarsMap'
 import { SupportedCalendar } from '../types'
+import { extractDatePartsFromDateString } from './extract-date-parts-from-date-string'
+import { getCustomCalendarIfExists } from './helpers'
+
+type PlainDate = {
+    year: number
+    month: number
+    day: number
+    // keeping eraYear to be consistent with the default behaviour of Temporal (check method documentation for more info)
+    eraYear?: number
+}
 
 type ConvertDateFn = (
-    date: string | Temporal.PlainDate,
+    date: string | Temporal.PlainDateLike,
     calendar: SupportedCalendar
-) => Temporal.PlainDate
+) => PlainDate
+
+/**
+ * converts from an iso8601 (gregorian) date to a specific calendar
+ *
+ * @param date string in the format yyyy-MM-dd
+ * @param userCalendar the calendar to covert to
+ * @returns an object representing the date
+ *
+ * NOTE: the returned object contains two properties year and eraYear
+ * to be consistent with the default behaviour of Temporal. This only affects
+ * ethiopic calendar in practice. When accessing year, consumers should be defensive
+ * and do: `const yearToUse = result.eraYear ?? result.year` for example.
+ *
+ * @see https://github.com/tc39/ecma402/issues/534 for more details
+ */
+export const convertFromIso8601: ConvertDateFn = (date, userCalendar) => {
+    const calendar = getCustomCalendarIfExists(
+        dhis2CalendarsMap[userCalendar] ?? userCalendar
+    ) as SupportedCalendar
+
+    const { eraYear, year, month, day } =
+        Temporal.PlainDate.from(date).withCalendar(calendar)
+
+    return {
+        eraYear,
+        year,
+        month,
+        day,
+    }
+}
+
+/**
+ * converts from a specific calendar (i.e. ethiopic or nepali) to iso8601 (gregorian)
+ *
+ * @param date calendar date in the format yyyy-MM-dd
+ * @param userCalendar the calendar to convert from
+ * @returns an object representing the iso8601 date
+ */
+export const convertToIso8601: ConvertDateFn = (date, userCalendar) => {
+    const calendar = getCustomCalendarIfExists(
+        dhis2CalendarsMap[userCalendar] ?? userCalendar
+    ) as SupportedCalendar
+
+    const dateParts: Temporal.PlainDateLike =
+        typeof date === 'string' ? extractDatePartsFromDateString(date) : date
 
-export const convertDate: ConvertDateFn = (date, calendar) => {
-    if (calendar === 'nepali') {
-        return Temporal.PlainDate.from(date).withCalendar(new NepaliCalendar())
+    // this is a workaround for the ethiopic calendar being in a different
+    // era by default. There is a discussion on Temporal on which should be
+    // considered the default era. For us, we need to manually set it to era1
+    // https://github.com/js-temporal/temporal-polyfill/blob/8fd0dead40de7c31398f4d2d41e145466ca57a16/lib/calendar.ts#L2010
+    if (calendar === 'ethiopic') {
+        dateParts.eraYear = dateParts.year
+        dateParts.era = 'era1'
+        delete dateParts.year
     }
-    return Temporal.PlainDate.from(date).withCalendar(calendar)
+
+    dateParts.calendar = calendar
+
+    const { year, month, day } =
+        Temporal.PlainDate.from(dateParts).withCalendar('iso8601')
+
+    return { year, month, day }
 }

src/utils/index.ts

@@ -5,4 +5,4 @@ export * from './helpers'
 export { default as localisationHelpers } from './localisationHelpers'
 export { validateDateString } from './validate-date-string'
 
-export { convertDate } from './convert-date'
+export { convertFromIso8601, convertToIso8601 } from './convert-date'