feat: sleep time advisor (#37)

docs/_sidebar.md

@@ -22,6 +22,7 @@
 - [Mental Health Management](./guide/mentalHealth.md)
 - [Focus Time Management](./guide/focusTimeManagement.md)
 - [Water Intake Reminder](./guide/waterIntakeReminder.md)
+- [Sleep Time Advisor](./guide/sleepTimeAdvisor.md)
 
 </details>
 

docs/guide/sleepTimeAdvisor.md

@@ -0,0 +1,35 @@
+# Sleep Time Advisor.
+
+## Description
+
+The sleepTimeAdvisor function helps users determine an optimal bedtime based on their desired wake-up time, number of sleep cycles, and time zone. Each sleep cycle is assumed to last approximately 90 minutes, following standard recommendations for uninterrupted, restful sleep.
+
+## Usage
+
+```javascript
+import { sleepTimeAdvisor } from 'world-clockify';
+
+const result = sleepTimeAdvisor('07:00', 5, 'America/New_York');
+
+console.log(result.suggestedSleepTime);
+console.log(result.message);
+```
+
+## Expected Output
+
+```bash
+ bedtime, e.g., "11:30 PM"
+"To get 5 cycles of sleep, you should go to bed by 11:30 PM."
+```
+
+## Parameters
+
+```javascript
+- {string} wakeUpTime
+- {number} sleepCycles
+- {string} preferredTimeZone
+```
+
+## Returns
+
+- (object): As a result.

src/function.ts

@@ -377,3 +377,24 @@ export const waterIntakeReminder = (preference: waterUserPreference) => {
 
   return reminders;
 };
+
+/**
+ * sleep schedule based on their desired wake-up time and how many hours of sleep they need.
+ * @param {string} wakeUpTime
+ * @param {number} sleepCycles
+ * @param {string} preferredTimeZone
+ */
+
+export const sleepTimeAdvisor = (wakeUpTime: string, sleepCycles: number, preferredTimeZone: string) => {
+  const cycleDuration = 90; // in minutes
+  const totalSleepTime = cycleDuration * sleepCycles;
+
+  const wakeUp = DateTime.fromFormat(wakeUpTime, 'HH:mm', { zone: preferredTimeZone });
+
+  const suggestedSleepTime = wakeUp.minus({ minutes: totalSleepTime });
+
+  return {
+    suggestedSleepTime: suggestedSleepTime.toFormat('hh:mm a'),
+    message: `To get ${sleepCycles} cycles of sleep, you should go to bed by ${suggestedSleepTime.toFormat('hh:mm a')}.`,
+  };
+};

tests/index.test.ts

@@ -13,6 +13,7 @@ import {
   sheduleWorkAndBreaks,
   focusTimeManager,
   waterIntakeReminder,
+  sleepTimeAdvisor,
 } from '../src/function.js';
 
 describe('Timezone-Aware Date Helper', () => {
@@ -172,4 +173,14 @@ describe('Timezone-Aware Date Helper', () => {
 
     expect(waterIntake).toEqual(expectedReminders);
   });
+
+  it('should suggest sleep time', () => {
+    const wakeUpTime = '07:00';
+    const sleepCycles = 5;
+    const timeZone = 'America/New_York';
+
+    const result = sleepTimeAdvisor(wakeUpTime, sleepCycles, timeZone);
+    expect(result.suggestedSleepTime).toBe('11:30 PM');
+    expect(result.message).toBe('To get 5 cycles of sleep, you should go to bed by 11:30 PM.');
+  });
 });