feat: format date based on local and timezone

docs/_sidebar.md

@@ -17,6 +17,7 @@
 - [Convert Time Zone](./guide/convertTimeZone.md)
 - [Time Zone Offset Difference](./guide/getTimeZoneOffsetDifference.md)
 - [Format Date in Time Zone](./guide/formatDateInTimeZone.md)
+- [Format Date Based On Local](./guide/formatDateForLocale.md)
 - [Calculate Duration](./guide/calculateDuration.md)
 
 </details>

docs/guide/formatDateForLocale.md

@@ -0,0 +1,35 @@
+# Format Date based on the given locale and timezone.
+
+## Description
+
+This feature allows you to format a date string based on the given locale and timezone.
+
+## Usage
+
+```javascript
+import { formatDateForLocale } from 'world-clockify';
+
+const formattedDateFR = formatDateForLocale('2024-10-17T10:30:00', 'fr', 'Europe/Paris');
+const formattedDateUS = formatDateForLocale('2024-10-17T10:30:00', 'en-US', 'America/New_York');
+
+console.log('Formatted Date (FR):', formattedDateFR);
+console.log('Formatted Date (US):', formattedDateUS);
+```
+
+## Expected Output
+
+```bash
+Formatted Date (FR): jeudi 17 octobre 2024 à 12:30:00 heure d’Europe centrale
+Formatted Date (US): Thursday, October 17, 2024, 06:30:00 AM Eastern Daylight Time
+
+```
+
+## Parameters
+
+- dateStr (string): The date string in ISO format.
+- local (string): The target local (e.g., 'fr', 'en-US').
+- timezone (string): The format to use for the output date string.
+
+## Returns
+
+- (string): The formatted string in the target local.

src/function.ts

@@ -123,6 +123,35 @@ export const formatDateInTimeZone = (dateStr: string, fromZone: string, toZone:
   return formattedDate;
 };
 
+/**
+ * Formats a date string based on the given locale and timezone.
+ *
+ * @param {string} dateStr - The date string in ISO format.
+ * @param {string} locale - The locale to format the date (e.g., 'fr', 'en-US').
+ * @param {string} timezone - The timezone for the date.
+ * @returns - The formatted date string.
+ */
+
+export const formatDateForLocale = (dateStr: string, locale: string, timezone: string): string => {
+  /* Create a DateTime object from the date string and timezone provided as arguments to the function.
+   The date string is expected to be in ISO format (e.g., '2022-01-01T12:00:00'). */
+  const date = DateTime.fromISO(dateStr, { zone: timezone });
+
+  if (!date.isValid) {
+    throw new Error(
+      `Invalid date string: "${dateStr}". Ensure the date is in ISO format (e.g., 'YYYY-MM-DDTHH:mm:ss').`,
+    );
+  }
+
+  if (!IANAZone.isValidZone(timezone)) {
+    throw new Error(
+      `Invalid timezone: "${timezone}". Please provide a valid IANA timezone (e.g., 'America/New_York').`,
+    );
+  }
+
+  return date.setLocale(locale).toLocaleString(DateTime.DATETIME_FULL);
+};
+
 /**
  * Calculates the duration between two dates across timezones.
  * @param {string} startDateStr - The start date in string format (ISO).

tests/index.test.ts

@@ -4,6 +4,7 @@ import {
   getCurrentTimeInZone,
   getTimeDifference,
   formatDateInTimeZone,
+  formatDateForLocale,
   calculateDuration,
   getSupportedTimezones,
   getSupportedCrrency,
@@ -41,6 +42,15 @@ describe('Timezone-Aware Date Helper', () => {
     expect(result).toBe('10/14/2024 08:00');
   });
 
+  it('should format date string based on the given locale and timezone.', () => {
+    const dateStr = '2024-10-17T10:30:00';
+    const local = 'en-US';
+    const timeZone = 'America/New_York';
+
+    const result = formatDateForLocale(dateStr, local, timeZone);
+    expect(result).toBe('October 17, 2024 at 10:30 AM EDT');
+  });
+
   it('should handle other timezones and format correctly', () => {
     const dateStr = '2024-10-14T12:00:00';
     const fromZone = 'UTC';