feat: countdown timer to specific timezone events (#19)

docs/_sidebar.md

@@ -11,6 +11,7 @@
 
 - [Get Current Time in Zone](./guide/getCurrentTimeInZone.md)
 - [Get list of Time Zones](./guide/getListOfSupportedTimeZones.md)
+- [Get Count Down To Event](./guide//getCountdownToEvent.md)
 - [Convert Time Zone](./guide/convertTimeZone.md)
 - [Time Zone Offset Difference](./guide/getTimeZoneOffsetDifference.md)
 - [Format Date in Time Zone](./guide/formatDateInTimeZone.md)

docs/guide/getCountdownToEvent.md

@@ -0,0 +1,32 @@
+# Get Count down To Event
+
+## Description
+
+This feature calculates the countdown to a specified event date in a given timezone and returns the countdown in a human-readable format.
+
+## Usage
+
+```javascript
+import { getCountdownToEvent } from 'world-clockify';
+
+const eventDate = '2024-10-20T15:00:00';
+const eventTimezone = 'America/New_York';
+
+const countdown = getCountdownToEvent(eventDate, eventTimezone);
+console.log(countdown);
+```
+
+## Expected Output
+
+```bash
+1 day, 1 hour, 30 minutes, 0 seconds
+```
+
+## Parameters
+
+- eventDate (string): The event date string in ISO format.
+- eventTimezone (string): The timezone of the event.
+
+## Returns
+
+Returns the countdown as an object with `{ days, hours, minutes, seconds }` ensuring each value is floored to the nearest integer.

src/function.ts

@@ -168,3 +168,37 @@ export const getSupportedTimezones = (): string[] => {
 
   return getListOfSupportedTimeZones;
 };
+
+/**
+ * Get the countdown to a specific event in a given timezone.
+ *
+ * @param eventDate - The date of the event (ISO string format).
+ * @param eventTimezone - The timezone of the event.
+ * @returns - The countdown as an object (days, hours, minutes, seconds).
+ */
+
+export const getCountdownToEvent = (
+  eventDate: string,
+  eventTimezone: string,
+): { days: number; hours: number; minutes: number; seconds: number } => {
+  if (!IANAZone.isValidZone(eventTimezone)) {
+    throw new Error(
+      `Invalid timezone: "${eventTimezone}". Please provide a valid IANA timezone (e.g., 'America/New_York').`,
+    );
+  }
+
+  if (!DateTime.fromISO(eventDate).isValid) {
+    throw new Error(`Invalid date: "${eventDate}". Ensure the date is in ISO format (e.g., 'YYYY-MM-DDTHH:mm:ss').`);
+  }
+  const now = DateTime.now().setZone(eventTimezone);
+  const eventTime = DateTime.fromISO(eventDate, { zone: eventTimezone });
+
+  const diff = eventTime.diff(now, ['days', 'hours', 'minutes', 'seconds']).toObject();
+
+  return {
+    days: Math.floor(diff.days || 0),
+    hours: Math.floor(diff.hours || 0),
+    minutes: Math.floor(diff.minutes || 0),
+    seconds: Math.floor(diff.seconds || 0),
+  };
+};

tests/index.test.ts

@@ -6,6 +6,7 @@ import {
   formatDateInTimeZone,
   calculateDuration,
   getSupportedTimezones,
+  getCountdownToEvent,
 } from '../src/function.js';
 
 describe('Timezone-Aware Date Helper', () => {
@@ -67,6 +68,17 @@ describe('Timezone-Aware Date Helper', () => {
 
   it('should returns a list of all supported IANA timezones', () => {
     const timezones = getSupportedTimezones();
-    expect(timezones);
+    expect(timezones).toBeInstanceOf(Array);
+  });
+
+  it('should calculate the countdown to a specific event', () => {
+    const eventDate = '2024-10-20T15:00:00';
+    const eventTimezone = 'America/New_York';
+    const countdown = getCountdownToEvent(eventDate, eventTimezone);
+
+    expect(countdown).toHaveProperty('days');
+    expect(countdown).toHaveProperty('hours');
+    expect(countdown).toHaveProperty('minutes');
+    expect(countdown).toHaveProperty('seconds');
   });
 });