diff --git a/docs/_sidebar.md b/docs/_sidebar.md index ed288bd..f70f371 100644 --- a/docs/_sidebar.md +++ b/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) diff --git a/docs/guide/formatDateForLocale.md b/docs/guide/formatDateForLocale.md new file mode 100644 index 0000000..12e15d6 --- /dev/null +++ b/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. diff --git a/src/function.ts b/src/function.ts index 3f54d68..034a8a1 100644 --- a/src/function.ts +++ b/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). diff --git a/tests/index.test.ts b/tests/index.test.ts index e6d5143..3d72e84 100644 --- a/tests/index.test.ts +++ b/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';