feat: managing focused work sessions (#35)

* feat: managing focused work sessions

* chore: validate timezone

docs/_sidebar.md

@@ -20,6 +20,7 @@
 - [Format Date Based On Local](./guide/formatDateForLocale.md)
 - [Calculate Duration](./guide/calculateDuration.md)
 - [Mental Health Management](./guide/mentalHealth.md)
+- [Focus Time Management](./guide/focusTimeManagement.md)
 
 </details>
 

docs/guide/focusTimeManagement.md

@@ -0,0 +1,49 @@
+# Focus Time Manager.
+
+## Description
+
+The focusTimeManager function assists users in managing focused work sessions throughout their day. It provides a schedule with alternating focus and break sessions, which is particularly useful for productivity techniques like the Pomodoro Technique.
+
+## Note:
+
+It is similar to [Mental Health Manager](./mentalHealth.md) but it is more focused on work sessions.
+
+## Usage
+
+```javascript
+import { focusTimeManager } from 'world-clockify';
+
+const preference = {
+  workStartTime: '09:00',
+  workEndTime: '17:00',
+  preferredTimeZone: 'America/New_York',
+  focusDuration: 50,
+  shortBreakDuration: 10,
+};
+
+const schedule = focusTimeManager(preference);
+
+console.log(schedule);
+```
+
+## Expected Output
+
+```bash
+  {
+   focusSessions: [
+     { start: '09:00 am', end: '09:50 am' },
+     { start: '10:00 am', end: '10:50 am' },
+     ...
+   ],
+   reminders: ['Time to focus!', 'Take a short break!', 'Focus time starts again soon!']
+ }
+
+```
+
+## Parameters
+
+- focusUserPreferences(object): The date string in ISO format.
+
+## Returns
+
+- (object): As a result.

src/function.ts

@@ -301,3 +301,45 @@ export const sheduleWorkAndBreaks = (preference: UserPreferences) => {
     endOfDayReminder: `Your workday ends at ${workEndTime}. Time to relax!`,
   };
 };
+
+interface focusUserPreferences {
+  workStartTime: string; // Start time of the workday in 'HH:mm' format
+  workEndTime: string; // End time of the workday in 'HH:mm' format
+  preferredTimeZone: string; // IANA time zone string (e.g., 'America/New_York')
+  focusDuration: number; // Focus session duration in minutes
+  shortBreakDuration: number; // Break duration in minutes
+}
+
+/**
+ * feature designed to schedule blocks of uninterrupted focus time throughout the day.
+ * @param preference- User preference for daily work hours
+ * @returns- An object containing focusSession and reminders.
+ */
+export const focusTimeManager = (preference: focusUserPreferences) => {
+  const { workStartTime, workEndTime, preferredTimeZone, focusDuration, shortBreakDuration } = preference;
+
+  const focusSession = [];
+
+  if (!IANAZone.isValidZone(preferredTimeZone)) {
+    throw Error(
+      `Invalid timezone: "${preferredTimeZone}". Please provide a valid IANA timezone (e.g., 'America/New_York').`,
+    );
+  }
+
+  let currentTime = DateTime.fromFormat(workStartTime, 'HH:mm', { zone: preferredTimeZone });
+  const endOfDay = DateTime.fromFormat(workEndTime, 'HH:mm', { zone: preferredTimeZone });
+
+  while (currentTime < endOfDay) {
+    const focusEnd = currentTime.plus({ minutes: focusDuration });
+    const breakEnd = focusEnd.plus({ minutes: shortBreakDuration });
+
+    focusSession.push({ start: currentTime.toFormat('hh:mm a'), end: focusEnd.toFormat('hh:mm a') });
+
+    currentTime = breakEnd;
+  }
+
+  return {
+    focusSession,
+    reminders: ['Time to focus!', 'Take a short break!', 'Focus time starts again soon!'],
+  };
+};

tests/index.test.ts

@@ -11,6 +11,7 @@ import {
   getSupportedCalendar,
   getCountdownToEvent,
   sheduleWorkAndBreaks,
+  focusTimeManager,
 } from '../src/function.js';
 
 describe('Timezone-Aware Date Helper', () => {
@@ -130,4 +131,23 @@ describe('Timezone-Aware Date Helper', () => {
 
     expect(dailySchedule.endOfDayReminder).toBe('Your workday ends at 17:00. Time to relax!');
   });
+
+  it('should assists users in managing focused work sessions throughout their day', () => {
+    const preference = {
+      workStartTime: '09:00',
+      workEndTime: '17:00',
+      preferredTimeZone: 'America/New_York',
+      focusDuration: 50,
+      shortBreakDuration: 10,
+    };
+
+    const schedule = focusTimeManager(preference);
+
+    expect(schedule.focusSession.length).toBeGreaterThan(0);
+
+    expect(schedule.focusSession[0]).toEqual({
+      start: '09:00 AM',
+      end: '09:50 AM',
+    });
+  });
 });