feat: add parseNepaliFormat method on NepaliDate (#111)

- updated README for parsing docs
- renamed parse function to simpleParse (internal)

Author: aj3sh

README.md

@@ -194,6 +194,14 @@ For the list of month names and their abbreviations, you can refer to the table
 | 10             | Fal          | Falgun    |
 | 11             | Cha          | Chaitra   |
 
+#### Parsing Dates
+
+You can parse a date-time string into a `NepaliDate` object using the following methods:
+
+- `new NepaliDate(dateString, formatStr)`: Parses an Nepali date-time string according to the specified format.
+- `NepaliDate.parseNepaliFormat(dateStringNe, formatStr)`: Parses a Nepali date-time string in Devanagari form according to the specified format.
+- `NepaliDate.parseEnglishDate(dateString, formatStr)`: Parses an English date-time string according to the specified format.
+
 #### Converting to JavaScript Date object
 
 You can get the equivalent JavaScript `Date` object of a `NepaliDate` object using the `getDateObject()` method.

src/NepaliDate.ts

@@ -8,7 +8,12 @@ import {
     nepaliDateToString,
 } from './format'
 
-import { parse, parseFormat, parseEnglishDateFormat } from './parse'
+import {
+    simpleParse,
+    parseFormat,
+    parseEnglishDateFormat,
+    parseNepaliFormat,
+} from './parse'
 import { getDate, getNepalDateAndTime } from './utils'
 import { validateTime } from './validators'
 
@@ -170,7 +175,7 @@ class NepaliDate {
     }
 
     private parseFromString(value: string) {
-        const parsedResult = parse(value)
+        const parsedResult = simpleParse(value)
         this.set(
             parsedResult[0], // Year
             parsedResult[1], // Month
@@ -250,7 +255,7 @@ class NepaliDate {
      *
      * @returns {Date} The equivalent JavaScript Date object.
      */
-    getDateObject() {
+    getDateObject(): Date {
         return this.timestamp
     }
 
@@ -624,8 +629,27 @@ class NepaliDate {
     }
 
     /**
-     * Creates a NepaliDate instance by parsing a provided English Date and Time string
-     * with the given format.
+     * Parses a Nepali date-time string in Devanagari form according to the
+     * specified format and returns a `NepaliDate` instance.
+     *
+     * @param dateStringNe - The Nepali Date and time string in Devanagari.
+     * @param format - The format of the provided date-time string.
+     * @example
+     * const dateStringNe = '२०८०/०८/१२ १४-०५-२३.७८९'
+     * const format = 'YYYY/MM/DD HH-mm-ss.SSS'
+     * const nepaliDate = NepaliDate.parseNepaliFormat(dateStringNe, format)
+     */
+    static parseNepaliFormat(dateStringNe: string, format: string): NepaliDate {
+        const [year, month0, day, hour, minute, second, ms] = parseNepaliFormat(
+            dateStringNe,
+            format
+        )
+        return new NepaliDate(year, month0, day, hour, minute, second, ms)
+    }
+
+    /**
+     * Parses an English date-time string according to the specified format
+     * and returns a `NepaliDate` instance.
      *
      * @param dateString - The English Date and time string.
      * @param format - The format of the provided date-time string.

src/parse/index.ts

@@ -1,2 +1,3 @@
-export { parseFormat, parse } from './parse'
+export { parseFormat, simpleParse } from './parse'
 export { parseEnglishDateFormat } from './parseEnglishDate'
+export { parseNepaliFormat } from './parseNepaliFormat'

src/parse/parse.ts

@@ -1,15 +1,5 @@
 /**
- * parse.ts
- *
- * This module provides methods for parsing dates and times from strings.
- *
- * Functions:
- *
- * parse(dateTimeString)
- * - Parses date and time from the given string.
- *
- * Further extension is needed in this module as there are limited formats supported for parsing.
- * Developers should consider extending the module to support additional date and time formats.
+ * This module provides features for parsing Nepali Date strings (in English).
  */
 
 import {
@@ -92,7 +82,7 @@ function parseTimeString(timeString: string): number[] {
  * @throws {Error} if date or time string is invalid
  * @returns return array of date information [hour, minute, second, ms].
  */
-export function parse(dateTimeString: string): number[] {
+export function simpleParse(dateTimeString: string): number[] {
     const [dateString, timeString] = dateTimeString.split(' ', 2)
     const [year, month0, day] = parseDateString(dateString)
     const [hour, minute, second, ms] = parseTimeString(timeString)

src/parse/parseEnglishDate.ts

@@ -1,3 +1,7 @@
+/**
+ * This module provides methods for parsing English Date strings.
+ */
+
 import {
     ENGLISH_MONTHS_EN,
     ENGLISH_MONTHS_SHORT_EN,

src/parse/parseNepaliFormat.ts

@@ -0,0 +1,36 @@
+/**
+ * This module provides methods for parsing Nepali Date strings (in Devanagari).
+ */
+
+import {
+    NEPALI_MONTHS_EN,
+    NEPALI_MONTHS_NE,
+    NUM_NE,
+    WEEKDAYS_LONG_EN,
+    WEEKDAYS_LONG_NE,
+    WEEKDAYS_SHORT_EN,
+    WEEKDAYS_SHORT_NE,
+} from '../constants'
+import { parseFormat } from './parse'
+
+function convertNepaliStringToEnglish(dateStringNe: string): string {
+    const regexLookup: Record<string, string> = {
+        एम: 'AM',
+        पिम: 'PM',
+    }
+    NEPALI_MONTHS_NE.forEach((ne, i) => (regexLookup[ne] = NEPALI_MONTHS_EN[i]))
+    WEEKDAYS_LONG_NE.forEach((ne, i) => (regexLookup[ne] = WEEKDAYS_LONG_EN[i]))
+    WEEKDAYS_SHORT_NE.forEach((ne, i) => (regexLookup[ne] = WEEKDAYS_SHORT_EN[i]))
+    NUM_NE.forEach((ne, i) => (regexLookup[ne] = String(i)))
+
+    // create a regex pattern
+    const pattern = new RegExp(Object.keys(regexLookup).join('|'), 'g')
+
+    // replace the match
+    return dateStringNe.replace(pattern, match => regexLookup[match])
+}
+
+export function parseNepaliFormat(dateStringNe: string, format: string): number[] {
+    const convertedDateString = convertNepaliStringToEnglish(dateStringNe)
+    return parseFormat(convertedDateString, format)
+}

tests/NepaliDate.test.ts

@@ -67,6 +67,14 @@ describe('NepaliDate', () => {
         }).toThrow('Date out of range')
     })
 
+    it('should initialize by parsing Nepali Date string in Devanagari with given format', () => {
+        const n1 = NepaliDate.parseNepaliFormat(
+            '२०८०/०८/१२ १४-०५-२३.७८९',
+            'YYYY/MM/DD HH-mm-ss.SSS'
+        )
+        expect(n1.toString()).toBe('2080-08-12 14:05:23.789')
+    })
+
     it('should initialize by parsing English Date string with given format', () => {
         const n1 = NepaliDate.parseEnglishDate(
             '2024 August 13 14-05-23.789',

tests/parse/parseNepaliFormat.test.ts

@@ -0,0 +1,13 @@
+import { parseNepaliFormat } from '../../src/parse'
+
+describe('parseNepaliFormat', () => {
+    // another test will be covered from NepaliDate.parseNepaliFormat test
+    it('parses the Nepali date-time string in Devanagari', () => {
+        expect(
+            parseNepaliFormat(
+                'साल: २०८०, महिना: जेठ, गते(दिन): ३२, बार: बिहिबार, बार(आधा): बिहि, समय: १:३४:५६ पिम',
+                'साल: YYYY, महिना: MMMM, गते(दिन): DD, बार: dddd, बार(आधा): ddd, समय: hh:mm:ss A'
+            )
+        ).toEqual([2080, 1, 32, 13, 34, 56, 0])
+    })
+})