chronos-ts 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2024 Josiah Endurance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,513 @@
+# Chronos-ts ⏰
+Chronos-ts from the name is inspired by the Greek god of time, Chronos. It is a comprehensive TypeScript package for handling time periods, intervals, and date-related operations.
+
+## Table of Contents
+- [Installation](#installation)
+- [Overview](#overview)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+    - [Classes](#classes)
+        - [Period](#period)
+        - [Interval](#interval)
+    - [Enums](#enums)
+    - [Precision](#precision)
+    - [Utility Function](#utility-function)
+    - [Real-world Scenarios](#real-world-scenarios)
+        - [Event Planning and Management](#event-planning-and-management)
+        - [Financial Reporting Periods](#financial-reporting-periods)
+        - [Employee Leave Management](#employee-leave-management)
+        - [Project Timeline Management](#project-timeline-management)
+        - [Subscription Billing Cycle Management](#subscription-billing-cycle-management)
+        - [Employee Shift Management](#employee-shift-management)
+        - [Travel Itinerary Planning](#travel-itinerary-planning)
+
+## Installation
+```bash
+npm install chronos-ts
+
+# or
+yarn add chronos-ts
+
+# or
+
+pnpm add chronos-ts
+```
+
+## Overview
+This package provides an easy-to-use API for working with periods and intervals, along with precise handling of date and time logic. Inspired by the [spatie/period](https://github.com/spatie/period) package in PHP, this package provides support for both TypeScript and JavaScript environments, offering advanced time manipulation. It offers a user-friendly API for working with periods and intervals, providing precise date and time logic handling. Key features include:
+- Flexible period creation and manipulation with customizable precision (minute to year)
+- Interval generation for recurring events (e.g., "every 3 days")
+- Comprehensive period comparisons (overlaps, contains, adjacent)
+- Precise start/end date handling with various time units
+- Advanced operations like symmetric differences and unions between periods
+- Adjacent period detection for seamless time range management
+- Extensive utility functions for common date operations and formatting
+
+Whether you're building scheduling systems, financial applications, or any project requiring sophisticated time calculations, Chronos simplifies complex time-based operations in both TypeScript and JavaScript environments.
+
+
+## Usage
+### Creating and Manipulating Periods
+````typescript
+import { Period, Precision, Interval } from 'chronos-ts';
+
+// Create a period for the year 2023
+const year2023 = new Period('2023-01-01', '2023-12-31', Precision.DAY);
+
+// Check if a date is within the period
+const isInPeriod = year2023.contains('2023-06-15'); // true
+
+// Create a period for Q2 2023
+const q2_2023 = new Period('2023-04-01', '2023-06-30', Precision.DAY);
+
+// Check if periods overlap
+const periodsOverlap = year2023.overlapsWith(q2_2023); // true
+
+// Get the overlapping period
+const overlap = year2023.overlap(q2_2023);
+console.log(overlap?.startDate, overlap?.endDate); // 2023-04-01, 2023-06-30
+
+// Subtract a period
+const remainingPeriods = year2023.subtract(q2_2023);
+console.log(remainingPeriods.length); // 2
+console.log(remainingPeriods[0].startDate, remainingPeriods[0].endDate); // 2023-01-01, 2023-03-31
+console.log(remainingPeriods[1].startDate, remainingPeriods[1].endDate); // 2023-07-01, 2023-12-31
+
+// Create a period with an interval
+const weeklyPeriod = new Period('2023-01-01', '2023-12-31', Precision.WEEK, Interval.weeks(1));
+
+// Get dates in the interval
+const weeklyDates = weeklyPeriod.getDatesInInterval();
+console.log(weeklyDates?.length); // 53 (number of weeks in 2023)
+
+// Renew a period
+const nextYear = year2023.renew();
+console.log(nextYear.startDate, nextYear.endDate); // 2024-01-01, 2024-12-31
+
+// Use fluent API
+const customPeriod = new Period('2023-01-01', '2023-12-31')
+  .setPrecision(Precision.MONTH)
+  .setInterval(Interval.months(3));
+
+console.log(customPeriod.getDatesInInterval()?.length); // 5 (Jan, Apr, Jul, Oct, Jan)
+````
+
+### Working with Intervals
+``` typescript
+import { Interval } from 'chronos-ts';
+
+const twoHours = Interval.hours(2);
+console.log(twoHours.getMinutesInterval()); // 120
+
+const threeWeeks = Interval.weeks(3);
+console.log(threeWeeks.getMinutesInterval()); // 30240 (3 * 7 * 24 * 60)
+
+const customInterval = new Interval(30, 2, 1, 0, 1); // 30 minutes, 2 hours, 1 day, 0 weeks, 1 month
+console.log(customInterval.getMinutesInterval()); // 44310 (30 + 120 + 1440 + 43200)
+```
+### Using Utility Functions
+```typescript
+import { addToDate, subtractFromDate, formatDate, parseDate, getWeekNumber, isLeapYear, Precision } from 'chronos-ts';
+
+const today = new Date();
+
+// Add 3 months to today
+const futureDate = addToDate(today, 3, Precision.MONTH);
+
+// Subtract 2 weeks from today
+const pastDate = subtractFromDate(today, 2, Precision.WEEK);
+
+// Format a date
+const formattedDate = formatDate(today, 'YYYY-MM-DD HH:mm:ss');
+
+// Parse a date string
+const parsedDate = parseDate('2023-06-15 14:30:00', 'YYYY-MM-DD HH:mm:ss');
+
+// Get the week number
+const weekNumber = getWeekNumber(today);
+
+// Check if it's a leap year
+const isLeap = isLeapYear(2024); // true
+```
+
+
+
+## API Reference
+### Classes
+#### Period
+The `Period` class represents a time period with a start date, end date, precision, and optional interval.
+
+##### Constructor
+```typescript
+constructor(start: string | Date, end: string | Date, precision: Precision = Precision.DAY, interval: Interval | null = null)
+```
+
+##### Methods
+- `contains(date: string | Date): boolean`: Checks if the given date is within the period.
+- `overlapsWith(other: Period): boolean`: Checks if this period overlaps with another period.
+- `isAdjacentTo(other: Period): boolean`: Checks if this period is adjacent to another period.
+- `getDatesInInterval(): Date[] | null`: Returns an array of dates within the period based on the interval.
+- `getMinutesInInterval(): number`: Returns the number of minutes in the period.
+- `getHoursInInterval(): number`: Returns the number of hours in the period.
+- `getDaysInInterval(): number`: Returns the number of days in the period.
+- `getWeeksInInterval(): number`: Returns the number of weeks in the period.
+- `getMonthsInInterval(): number`: Returns the number of months in the period.
+- `getYearsInInterval(): number`: Returns the number of years in the period.
+- `length(): number`: Returns the length of the period in the specified precision.
+- `overlap(other: Period): Period | null`: Returns the overlapping period with another period, if any.
+- `subtract(other: Period): Period[]`: Subtracts another period from this period.
+- `gap(other: Period): Period | null`: Returns the gap between this period and another period, if any.
+- `symmetricDifference(other: Period): Period[]`: Returns the symmetric difference between this period and another period.
+- `renew(): Period`: Creates a new period of the same length immediately following this period.
+- `union(other: Period): Period[]`: Returns the union of this period with another period.
+
+##### Fluent API Methods
+
+`setStart(start: string | Date): this`: Sets the start date of the period.
+`setEnd(end: string | Date): this`: Sets the end date of the period.
+`setPrecision(precision: Precision): this`: Sets the precision of the period.
+`setInterval(interval: Interval): this`: Sets the interval of the period.
+
+#### Interval
+The `Interval` class represents a time interval with minutes, hours, days, weeks, and months.
+Static Methods
+
+- `minutes(minutes: number): Interval:` Creates an interval with the specified number of minutes.
+- `hours(hours: number): Interval`: Creates an interval with the specified number of hours.
+- `days(days: number): Interval`: Creates an interval with the specified number of days.
+- `weeks(weeks: number): Interval`: Creates an interval with the specified number of weeks.
+- `months(months: number): Interval`: Creates an interval with the specified number of months.
+
+##### Methods
+
+`getMinutesInterval(): number`: Returns the total number of minutes in the interval.
+
+
+#### Enums
+##### Precision
+The Precision enum represents different levels of time precision.
+typescriptCopyenum Precision {
+    MINUTE = 'minute',
+    HOUR = 'hour',
+    DAY = 'day',
+    WEEK = 'week',
+    MONTH = 'month',
+    YEAR = 'year',
+}
+
+### Utility Function
+The package includes various utility functions for working with dates:
+
+- `getDatesWithInterval(start: Date, end: Date, interval: Interval): Date[]` - Returns an array of dates within the specified interval.
+- `getWeeksWithInterval(start: Date, end: Date, interval: Interval): Date[]` - Returns an array of weeks within the specified interval.
+- `getDaysWithInterval(start: Date, end: Date, interval: Interval): Date[]` - Returns an array of days within the specified interval.
+- `getHoursWithInterval(start: Date, end: Date, interval: Interval): Date[]` - Returns an array of hours within the specified interval.
+- `getMinutesWithInterval(start: Date, end: Date, interval: Interval): Date[]` - Returns an array of minutes within the specified interval.
+- `getMonthsWithInterval(start: Date, end: Date, interval: Interval): Date[]` - Returns an array of months within the specified interval.
+- `getYearsWithInterval(start: Date, end: Date, interval: Interval): Date[]` - Returns an array of years within the specified interval.
+- `addToDate(date: Date, amount: number, unit: Precision): Date` - Adds the specified amount of time to a date.
+- `subtractFromDate(date: Date, amount: number, unit: Precision): Date` - Subtracts the specified amount of time from a date.
+- `isSameDay(date1: Date, date2: Date): boolean` - Checks if two dates are on the same day.
+- `getWeekNumber(date: Date): number` - Returns the week number of a date.
+- `getQuarter(date: Date): number` - Returns the quarter of a date.
+- `isLeapYear(year: number): boolean` - Checks if a year is a leap year.
+- `getDaysInMonth(year: number, month: number): number` - Returns the number of days in a month.
+- `formatDate(date: Date, format: string): string`
+- `parseDate(dateString: string, format: string): Date` - Parses a date string using the specified format.
+- `range(start: number, end: number, step: number = 1): number[]` - Returns an array of numbers within the specified range.
+
+### Real-world Scenarios
+**1. Event Planning and Management**
+The `Period` class can be used to represent events, while the `Interval` class can help manage recurring events.
+``` typescript
+import { Period, Interval, Precision } from 'chronos-ts';
+
+// Create an event
+const conference = new Period('2023-09-15 09:00', '2023-09-17 18:00', Precision.HOUR);
+
+// Check if a specific time is during the conference
+const isDuringConference = conference.contains('2023-09-16 14:30'); // true
+
+// Create a recurring weekly meeting
+const weeklyMeeting = new Period('2023-01-01 10:00', '2023-12-31 11:00', Precision.HOUR, Interval.weeks(1));
+
+// Get all meeting dates
+const meetingDates = weeklyMeeting.getDatesInInterval();
+
+// Check for conflicts with the conference
+const conflictingMeetings = meetingDates?.filter(date => conference.contains(date)) || [];
+console.log(`There are ${conflictingMeetings.length} conflicting meetings during the conference.`);
+```
+
+**2. Financial  Reporting Periods**
+Use the `Period` class to represent financial quarters and calculate year-to-date periods.
+``` typescript
+import { Period, Precision } from 'chronos-ts';
+
+const q1_2023 = new Period('2023-01-01', '2023-03-31', Precision.DAY);
+const q2_2023 = new Period('2023-04-01', '2023-06-30', Precision.DAY);
+const q3_2023 = new Period('2023-07-01', '2023-09-30', Precision.DAY);
+const q4_2023 = new Period('2023-10-01', '2023-12-31', Precision.DAY);
+
+// Calculate Year-to-Date period
+const ytd = (currentQuarter: Period): Period => {
+  return new Period('2023-01-01', currentQuarter.endDate, Precision.DAY);
+};
+
+const q3YTD = ytd(q3_2023);
+console.log(`Q3 YTD period: ${q3YTD.startDate.toDateString()} - ${q3YTD.endDate.toDateString()}`);
+
+// Calculate quarter-over-quarter growth
+const calculateQoQGrowth = (currentQuarter: number, previousQuarter: number): string => {
+  const growth = (currentQuarter - previousQuarter) / previousQuarter * 100;
+  return `${growth.toFixed(2)}%`;
+};
+
+const q2Revenue = 1000000;
+const q3Revenue = 1200000;
+console.log(`Q3 QoQ Growth: ${calculateQoQGrowth(q3Revenue, q2Revenue)}`);
+```
+
+**3. Employee Leave Management**
+Use the `Period` class to manage employee leave requests and calculate leave balances.
+``` typescript
+import { Period, Precision } from 'chronos-ts';
+
+// Create a leave request period
+const leaveRequest = new Period('2023-09-15', '2023-09-17', Precision.DAY);
+
+// Check if the leave request overlaps with existing leave periods
+const existingLeaves = [
+  new Period('2023-09-10', '2023-09-14', Precision.DAY),
+  new Period('2023-09-18', '2023-09-20', Precision.DAY),
+];
+
+const overlappingLeaves = existingLeaves.filter(leave => leaveRequest.overlapsWith(leave));
+console.log(`There are ${overlappingLeaves.length} overlapping leave requests.`);
+
+// Calculate remaining leave balance
+const totalLeaveDays = 20;
+const usedLeaveDays = existingLeaves.reduce((total, leave) => total + leave.length(), 0);
+const remainingLeaveDays = totalLeaveDays - usedLeaveDays;
+console.log(`Remaining leave days: ${remainingLeaveDays}`);
+
+// Renew leave balance for the next year
+const nextYearLeaveBalance = remainingLeaveDays > 0 ? new Period('2024-01-01', '2024-12-31') : null;
+console.log(`Next year's leave balance: ${nextYearLeaveBalance ? nextYearLeaveBalance.length() : 0} days`);
+
+```
+
+**4.  Project Timeline Management**
+Use the Period class to manage project timelines and track overlapping tasks.
+``` typescript
+import { Period, Precision } from 'chronos-ts';
+
+const projectTimeline = new Period('2023-01-01', '2023-12-31', Precision.DAY);
+
+const tasks = [
+  new Period('2023-01-15', '2023-03-31', Precision.DAY),
+  new Period('2023-03-01', '2023-05-15', Precision.DAY),
+  new Period('2023-05-01', '2023-08-31', Precision.DAY),
+  new Period('2023-08-15', '2023-11-30', Precision.DAY),
+];
+
+// Find overlapping tasks
+const findOverlappingTasks = (tasks: Period[]): [Period, Period][] => {
+  const overlaps: [Period, Period][] = [];
+  for (let i = 0; i < tasks.length; i++) {
+    for (let j = i + 1; j < tasks.length; j++) {
+      if (tasks[i].overlapsWith(tasks[j])) {
+        overlaps.push([tasks[i], tasks[j]]);
+      }
+    }
+  }
+  return overlaps;
+};
+
+const overlappingTasks = findOverlappingTasks(tasks);
+console.log(`There are ${overlappingTasks.length} overlapping tasks in the project.`);
+
+// Calculate project progress
+const calculateProgress = (currentDate: Date): number => {
+  const daysPassed = projectTimeline.startDate.getMinutesInInterval() / (24 * 60);
+  const totalDays = projectTimeline.getDaysInInterval();
+  return (daysPassed / totalDays) * 100;
+};
+
+const currentProgress = calculateProgress(new Date('2023-06-15'));
+console.log(`Project progress: ${currentProgress.toFixed(2)}%`);
+```
+
+**5. Subscription Billing Cycle Management**
+Use the Period class to manage subscription periods and calculate renewal dates.
+``` typescript
+import { Period, Precision, addToDate } from 'chronos-ts';
+
+class Subscription {
+  constructor(public startDate: Date, public plan: 'monthly' | 'annual') {}
+
+  getCurrentPeriod(): Period {
+    const endDate = addToDate(this.startDate, 1, this.plan === 'monthly' ? Precision.MONTH : Precision.YEAR);
+    return new Period(this.startDate, endDate, Precision.DAY);
+  }
+
+  isActive(date: Date = new Date()): boolean {
+    return this.getCurrentPeriod().contains(date);
+  }
+
+  getRenewalDate(): Date {
+    return this.getCurrentPeriod().endDate;
+  }
+
+  renew(): void {
+    this.startDate = this.getRenewalDate();
+  }
+}
+
+const monthlySubscription = new Subscription(new Date('2023-01-01'), 'monthly');
+console.log(`Monthly subscription active: ${monthlySubscription.isActive()}`);
+console.log(`Monthly subscription renewal date: ${monthlySubscription.getRenewalDate().toDateString()}`);
+
+const annualSubscription = new Subscription(new Date('2023-01-01'), 'annual');
+console.log(`Annual subscription active: ${annualSubscription.isActive()}`);
+console.log(`Annual subscription renewal date: ${annualSubscription.getRenewalDate().toDateString()}`);
+
+const annualSubscription = new Subscription(new Date('2023-01-01'), 'annual');
+console.log(`Annual subscription active: ${annualSubscription.isActive()}`);
+console.log(`Annual subscription renewal date: ${annualSubscription.getRenewalDate().toDateString()}`);
+// Check if a subscription will be active on a future date
+const futureDate = new Date('2023-12-15');
+console.log(`Monthly subscription active on ${futureDate.toDateString()}: ${monthlySubscription.isActive(futureDate)}`);
+console.log(`Annual subscription active on ${futureDate.toDateString()}: ${annualSubscription.isActive(futureDate)}`);
+// Renew a subscription
+monthlySubscription.renew();
+console.log(`Monthly subscription renewed. New period: ${monthlySubscription.getCurrentPeriod().startDate.toDateString()} - ${monthlySubscription.getCurrentPeriod().endDate.toDateString()})`;
+```
+
+**6. Employee Shift Management**
+
+Use the `Period` and `Interval` classes to manage employee shifts and calculate overtime.
+
+```typescript
+import { Period, Interval, Precision, addToDate } from 'chronos-ts';
+
+class Shift extends Period {
+  constructor(public employee: string, start: Date, end: Date) {
+    super(start, end, Precision.MINUTE);
+  }
+
+  getDuration(): number {
+    return this.getHoursInInterval();
+  }
+
+  isOvertime(): boolean {
+    return this.getDuration() > 8;
+  }
+
+  getOvertimeHours(): number {
+    return Math.max(0, this.getDuration() - 8);
+  }
+}
+
+// Create a week's worth of shifts for an employee
+const createWeekShifts = (employee: string, startDate: Date): Shift[] => {
+  const shifts: Shift[] = [];
+  for (let i = 0; i < 5; i++) { // Assuming 5-day work week
+    const shiftStart = addToDate(startDate, i, Precision.DAY);
+    shiftStart.setHours(9, 0, 0, 0); // 9 AM start
+    const shiftEnd = new Date(shiftStart);
+    shiftEnd.setHours(17, 0, 0, 0); // 5 PM end
+    shifts.push(new Shift(employee, shiftStart, shiftEnd));
+  }
+  return shifts;
+};
+
+const employeeShifts = createWeekShifts('John Doe', new Date('2023-06-19'));
+
+// Calculate total hours worked and overtime
+const totalHours = employeeShifts.reduce((sum, shift) => sum + shift.getDuration(), 0);
+const overtimeHours = employeeShifts.reduce((sum, shift) => sum + shift.getOvertimeHours(), 0);
+
+console.log(`Total hours worked: ${totalHours}`);
+console.log(`Overtime hours: ${overtimeHours}`);
+
+// Check for conflicting shifts
+const hasConflict = (shifts: Shift[]): boolean => {
+  for (let i = 0; i < shifts.length; i++) {
+    for (let j = i + 1; j < shifts.length; j++) {
+      if (shifts[i].overlapsWith(shifts[j])) {
+        return true;
+      }
+    }
+  }
+  return false;
+};
+
+console.log(`Shifts have conflicts: ${hasConflict(employeeShifts)}`);
+```
+
+**7. Travel Itinerary Planning**
+Use the `Period` class to manage travel itineraries and check for scheduling conflicts.
+``` typescript
+import { Period, Precision, addToDate } from 'chronos-ts';
+
+class TravelEvent extends Period {
+  constructor(public description: string, start: Date, end: Date) {
+    super(start, end, Precision.MINUTE);
+  }
+}
+
+class Itinerary {
+  events: TravelEvent[] = [];
+
+  addEvent(event: TravelEvent): void {
+    if (this.hasConflict(event)) {
+      throw new Error('Event conflicts with existing events');
+    }
+    this.events.push(event);
+  }
+
+  hasConflict(newEvent: TravelEvent): boolean {
+    return this.events.some(event => event.overlapsWith(newEvent));
+  }
+
+  getDuration(): number {
+    if (this.events.length === 0) return 0;
+    const start = this.events.reduce((min, e) => e.startDate < min ? e.startDate : min, this.events[0].startDate);
+    const end = this.events.reduce((max, e) => e.endDate > max ? e.endDate : max, this.events[0].endDate);
+    return new Period(start, end, Precision.HOUR).getDaysInInterval();
+  }
+}
+
+// Create a travel itinerary
+const itinerary = new Itinerary();
+
+// Add events to the itinerary
+try {
+  itinerary.addEvent(new TravelEvent('Flight to Paris', new Date('2023-07-01 10:00'), new Date('2023-07-01 12:00')));
+  itinerary.addEvent(new TravelEvent('Hotel Check-in', new Date('2023-07-01 14:00'), new Date('2023-07-01 15:00')));
+  itinerary.addEvent(new TravelEvent('Eiffel Tower Visit', new Date('2023-07-02 10:00'), new Date('2023-07-02 13:00')));
+  itinerary.addEvent(new TravelEvent('Louvre Museum', new Date('2023-07-03 09:00'), new Date('2023-07-03 12:00')));
+  itinerary.addEvent(new TravelEvent('Flight to Rome', new Date('2023-07-04 15:00'), new Date('2023-07-04 17:00')));
+} catch (error) {
+  console.error('Error creating itinerary:', error.message);
+}
+
+console.log(`Itinerary duration: ${itinerary.getDuration()} days`);
+
+// Try to add a conflicting event
+try {
+  itinerary.addEvent(new TravelEvent('Conflicting Event', new Date('2023-07-01 11:00'), new Date('2023-07-01 13:00')));
+} catch (error) {
+  console.log('Caught conflicting event:', error.message);
+}
+```
+
+## Contributing 🤝
+Contributions, issues and feature requests are welcome. After cloning & setting up project locally, you can just submit a PR to this repo and it will be deployed once it's accepted. There is a list of TODOs in the [TODO.md](TODO.md) file. The project is still in its early stages, so there are plenty of opportunities to contribute.
+
+## License 📝
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgements 🙏
+- [spatie/period]((https://github.com/spatie/period)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Period } from './period';
+export { Precision } from './precision';
+export { Interval } from './interval';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Interval = exports.Precision = exports.Period = void 0;
+var period_1 = require("./period");
+Object.defineProperty(exports, "Period", { enumerable: true, get: function () { return period_1.Period; } });
+var precision_1 = require("./precision");
+Object.defineProperty(exports, "Precision", { enumerable: true, get: function () { return precision_1.Precision; } });
+var interval_1 = require("./interval");
+Object.defineProperty(exports, "Interval", { enumerable: true, get: function () { return interval_1.Interval; } });

package/dist/interval.d.ts

@@ -0,0 +1,14 @@
+export declare class Interval {
+    private minutes;
+    private hours;
+    private days;
+    private weeks;
+    private months;
+    private constructor();
+    static minutes(minutes: number): Interval;
+    static hours(hours: number): Interval;
+    static days(days: number): Interval;
+    static weeks(weeks: number): Interval;
+    static months(months: number): Interval;
+    getMinutesInterval(): number;
+}

package/dist/interval.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Interval = void 0;
+class Interval {
+    constructor(minutes = 0, hours = 0, days = 0, weeks = 0, months = 0) {
+        this.minutes = minutes;
+        this.hours = hours;
+        this.days = days;
+        this.weeks = weeks;
+        this.months = months;
+    }
+    static minutes(minutes) {
+        return new Interval(minutes);
+    }
+    static hours(hours) {
+        return new Interval(0, hours);
+    }
+    static days(days) {
+        return new Interval(0, 0, days);
+    }
+    static weeks(weeks) {
+        return new Interval(0, 0, 0, weeks);
+    }
+    static months(months) {
+        return new Interval(0, 0, 0, 0, months);
+    }
+    getMinutesInterval() {
+        return (this.minutes +
+            this.hours * 60 +
+            this.days * 24 * 60 +
+            this.weeks * 7 * 24 * 60 +
+            this.months * 30 * 24 * 60);
+    }
+}
+exports.Interval = Interval;

package/dist/period.d.ts

@@ -0,0 +1,31 @@
+import { Interval } from './interval';
+import { Precision } from './precision';
+export declare class Period {
+    private startDate;
+    private endDate;
+    private precision;
+    private interval;
+    constructor(start: string | Date, end: string | Date, precision?: Precision, interval?: Interval | null);
+    contains(date: string | Date): boolean;
+    overlapsWith(other: Period): boolean;
+    isAdjacentTo(other: Period): boolean;
+    getDatesInInterval(): Date[] | null;
+    getMinutesInInterval(): number;
+    getHoursInInterval(): number;
+    getDaysInInterval(): number;
+    getWeeksInInterval(): number;
+    getMonthsInInterval(): number;
+    getYearsInInterval(): number;
+    length(): number;
+    overlap(other: Period): Period | null;
+    subtract(other: Period): Period[];
+    gap(other: Period): Period | null;
+    symmetricDifference(other: Period): Period[];
+    private mergeAdjacentPeriods;
+    renew(): Period;
+    union(other: Period): Period[];
+    setStart(start: string | Date): this;
+    setEnd(end: string | Date): this;
+    setPrecision(precision: Precision): this;
+    setInterval(interval: Interval): this;
+}

package/dist/period.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Period = void 0;
+const precision_1 = require("./precision");
+const utils_1 = require("./utils");
+class Period {
+    constructor(start, end, precision = precision_1.Precision.DAY, interval = null) {
+        this.startDate = new Date(start);
+        this.endDate = new Date(end);
+        this.precision = precision;
+        this.interval = interval;
+    }
+    contains(date) {
+        const checkDate = new Date(date);
+        return checkDate >= this.startDate && checkDate <= this.endDate;
+    }
+    overlapsWith(other) {
+        return this.startDate < other.endDate && this.endDate > other.startDate;
+    }
+    isAdjacentTo(other) {
+        const thisPrecisionMs = (0, precision_1.getPrecisionInMilliseconds)(this.precision);
+        const otherPrecisionMs = (0, precision_1.getPrecisionInMilliseconds)(other.precision);
+        const maxPrecisionMs = Math.max(thisPrecisionMs, otherPrecisionMs);
+        const thisEndTime = this.endDate.getTime();
+        const otherStartTime = other.startDate.getTime();
+        const thisStartTime = this.startDate.getTime();
+        const otherEndTime = other.endDate.getTime();
+        // Check for overlap
+        if (thisStartTime <= otherEndTime && otherStartTime <= thisEndTime) {
+            return false;
+        }
+        // Check if the gap between periods is within one precision unit
+        const gap = Math.abs(otherStartTime - thisEndTime);
+        const reverseGap = Math.abs(thisStartTime - otherEndTime);
+        return ((gap > 0 && gap <= maxPrecisionMs) ||
+            (reverseGap > 0 && reverseGap <= maxPrecisionMs));
+    }
+    getDatesInInterval() {
+        if (this.interval) {
+            return (0, utils_1.getDatesWithInterval)(this.startDate, this.endDate, this.interval);
+        }
+        return null;
+    }
+    getMinutesInInterval() {
+        return Math.floor((this.endDate.getTime() - this.startDate.getTime()) / (1000 * 60));
+    }
+    getHoursInInterval() {
+        return Math.floor(this.getMinutesInInterval() / 60);
+    }
+    getDaysInInterval() {
+        return Math.floor(this.getHoursInInterval() / 24);
+    }
+    getWeeksInInterval() {
+        return Math.floor(this.getDaysInInterval() / 7);
+    }
+    getMonthsInInterval() {
+        let months = (this.endDate.getFullYear() - this.startDate.getFullYear()) * 12;
+        months += this.endDate.getMonth() - this.startDate.getMonth();
+        // Adjust for month boundaries
+        if (this.endDate.getDate() < this.startDate.getDate()) {
+            months--;
+        }
+        return months;
+    }
+    getYearsInInterval() {
+        return Math.floor(this.getMonthsInInterval() / 12);
+    }
+    length() {
+        return Math.floor((this.endDate.getTime() - this.startDate.getTime()) /
+            (0, precision_1.getPrecisionInMilliseconds)(this.precision));
+    }
+    overlap(other) {
+        if (!this.overlapsWith(other)) {
+            return null;
+        }
+        const start = new Date(Math.max(this.startDate.getTime(), other.startDate.getTime()));
+        const end = new Date(Math.min(this.endDate.getTime(), other.endDate.getTime()));
+        return new Period(start, end, this.precision);
+    }
+    subtract(other) {
+        if (!this.overlapsWith(other)) {
+            return [this];
+        }
+        const periods = [];
+        if (this.startDate < other.startDate) {
+            const endDate = new Date(other.startDate.getTime() - 1);
+            periods.push(new Period(this.startDate, endDate, this.precision));
+        }
+        if (this.endDate > other.endDate) {
+            const startDate = new Date(other.endDate.getTime() + 1);
+            periods.push(new Period(startDate, this.endDate, this.precision));
+        }
+        return periods;
+    }
+    gap(other) {
+        if (this.overlapsWith(other) || this.isAdjacentTo(other)) {
+            return null;
+        }
+        const precisionMs = (0, precision_1.getPrecisionInMilliseconds)(this.precision);
+        const start = this.endDate < other.startDate ? this.endDate : other.endDate;
+        const end = this.startDate > other.startDate ? this.startDate : other.startDate;
+        return new Period(new Date(start.getTime() + precisionMs), new Date(end.getTime() - precisionMs), this.precision);
+    }
+    symmetricDifference(other) {
+        const periods = [];
+        const overlapPeriod = this.overlap(other);
+        if (!overlapPeriod) {
+            // No overlap, return both periods
+            return [this, other].sort((a, b) => a.startDate.getTime() - b.startDate.getTime());
+        }
+        const thisSubtracted = this.subtract(overlapPeriod);
+        const otherSubtracted = other.subtract(overlapPeriod);
+        periods.push(...thisSubtracted, ...otherSubtracted);
+        // Sort periods and merge adjacent ones
+        return this.mergeAdjacentPeriods(periods);
+    }
+    mergeAdjacentPeriods(periods) {
+        if (periods.length <= 1)
+            return periods;
+        periods.sort((a, b) => a.startDate.getTime() - b.startDate.getTime());
+        const merged = [periods[0]];
+        for (let i = 1; i < periods.length; i++) {
+            const current = periods[i];
+            const previous = merged[merged.length - 1];
+            if (previous.isAdjacentTo(current) || previous.overlapsWith(current)) {
+                merged[merged.length - 1] = new Period(previous.startDate, current.endDate > previous.endDate
+                    ? current.endDate
+                    : previous.endDate, this.precision);
+            }
+            else {
+                merged.push(current);
+            }
+        }
+        return merged;
+    }
+    renew() {
+        const length = this.length();
+        const newStart = new Date(this.endDate.getTime() + (0, precision_1.getPrecisionInMilliseconds)(this.precision));
+        const newEnd = new Date(newStart.getTime() + length * (0, precision_1.getPrecisionInMilliseconds)(this.precision));
+        return new Period(newStart, newEnd, this.precision, this.interval);
+    }
+    union(other) {
+        if (this.overlapsWith(other) || this.isAdjacentTo(other)) {
+            const start = new Date(Math.min(this.startDate.getTime(), other.startDate.getTime()));
+            const end = new Date(Math.max(this.endDate.getTime(), other.endDate.getTime()));
+            return [new Period(start, end, this.precision)];
+        }
+        return [this, other].sort((a, b) => a.startDate.getTime() - b.startDate.getTime());
+    }
+    // Fluent API methods
+    setStart(start) {
+        this.startDate = new Date(start);
+        return this;
+    }
+    setEnd(end) {
+        this.endDate = new Date(end);
+        return this;
+    }
+    setPrecision(precision) {
+        this.precision = precision;
+        return this;
+    }
+    setInterval(interval) {
+        this.interval = interval;
+        return this;
+    }
+}
+exports.Period = Period;

package/dist/precision.d.ts

@@ -0,0 +1,9 @@
+export declare enum Precision {
+    MINUTE = "minute",
+    HOUR = "hour",
+    DAY = "day",
+    WEEK = "week",
+    MONTH = "month",
+    YEAR = "year"
+}
+export declare function getPrecisionInMilliseconds(precision: Precision): number;

package/dist/precision.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Precision = void 0;
+exports.getPrecisionInMilliseconds = getPrecisionInMilliseconds;
+var Precision;
+(function (Precision) {
+    Precision["MINUTE"] = "minute";
+    Precision["HOUR"] = "hour";
+    Precision["DAY"] = "day";
+    Precision["WEEK"] = "week";
+    Precision["MONTH"] = "month";
+    Precision["YEAR"] = "year";
+})(Precision || (exports.Precision = Precision = {}));
+function getPrecisionInMilliseconds(precision) {
+    switch (precision) {
+        case Precision.MINUTE:
+            return 1000 * 60;
+        case Precision.HOUR:
+            return 1000 * 60 * 60;
+        case Precision.DAY:
+            return 1000 * 60 * 60 * 24;
+        case Precision.WEEK:
+            return 1000 * 60 * 60 * 24 * 7;
+        case Precision.MONTH:
+            return 1000 * 60 * 60 * 24 * 30;
+        case Precision.YEAR:
+            return 1000 * 60 * 60 * 24 * 365;
+        default:
+            throw new Error('Unsupported precision');
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1,19 @@
+import { Interval } from './interval';
+import { Precision } from './precision';
+export declare function getDatesWithInterval(start: Date, end: Date, interval: Interval): Date[];
+export declare function getWeeksWithInterval(start: Date, end: Date, interval: Interval): Date[];
+export declare function getDaysWithInterval(start: Date, end: Date, interval: Interval): Date[];
+export declare function getHoursWithInterval(start: Date, end: Date, interval: Interval): Date[];
+export declare function getMinutesWithInterval(start: Date, end: Date, interval: Interval): Date[];
+export declare function getMonthsWithInterval(start: Date, end: Date, interval: Interval): Date[];
+export declare function getYearsWithInterval(start: Date, end: Date, interval: Interval): Date[];
+export declare function addToDate(date: Date, amount: number, unit: Precision): Date;
+export declare function subtractFromDate(date: Date, amount: number, unit: Precision): Date;
+export declare function isSameDay(date1: Date, date2: Date): boolean;
+export declare function getWeekNumber(date: Date): number;
+export declare function getQuarter(date: Date): number;
+export declare function isLeapYear(year: number): boolean;
+export declare function getDaysInMonth(year: number, month: number): number;
+export declare function formatDate(date: Date, format: string): string;
+export declare function parseDate(dateString: string, format: string): Date;
+export declare function range(start: number, end: number, step?: number): number[];

package/dist/utils.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDatesWithInterval = getDatesWithInterval;
+exports.getWeeksWithInterval = getWeeksWithInterval;
+exports.getDaysWithInterval = getDaysWithInterval;
+exports.getHoursWithInterval = getHoursWithInterval;
+exports.getMinutesWithInterval = getMinutesWithInterval;
+exports.getMonthsWithInterval = getMonthsWithInterval;
+exports.getYearsWithInterval = getYearsWithInterval;
+exports.addToDate = addToDate;
+exports.subtractFromDate = subtractFromDate;
+exports.isSameDay = isSameDay;
+exports.getWeekNumber = getWeekNumber;
+exports.getQuarter = getQuarter;
+exports.isLeapYear = isLeapYear;
+exports.getDaysInMonth = getDaysInMonth;
+exports.formatDate = formatDate;
+exports.parseDate = parseDate;
+exports.range = range;
+const precision_1 = require("./precision");
+function getDatesWithInterval(start, end, interval) {
+    const dates = [];
+    const current = new Date(start);
+    while (current <= end) {
+        dates.push(new Date(current));
+        current.setMinutes(current.getMinutes() + interval.getMinutesInterval());
+    }
+    return dates;
+}
+function getWeeksWithInterval(start, end, interval) {
+    const weeks = [];
+    let current = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate()));
+    // Move to the start of the week (Sunday)
+    current.setUTCDate(current.getUTCDate() - current.getUTCDay());
+    while (current <= end) {
+        weeks.push(new Date(current));
+        // Add the interval in minutes, converted to milliseconds
+        current = new Date(current.getTime() + interval.getMinutesInterval() * 60000);
+        // Ensure we're at the start of the week
+        current.setUTCDate(current.getUTCDate() - current.getUTCDay());
+    }
+    return weeks;
+}
+function getDaysWithInterval(start, end, interval) {
+    const days = [];
+    const current = new Date(start);
+    current.setUTCHours(0, 0, 0, 0);
+    while (current <= end) {
+        days.push(new Date(current));
+        current.setUTCDate(current.getUTCDate() + interval.getMinutesInterval() / (24 * 60));
+    }
+    return days;
+}
+function getHoursWithInterval(start, end, interval) {
+    const hours = [];
+    const current = new Date(start);
+    current.setMinutes(0, 0, 0);
+    while (current <= end) {
+        hours.push(new Date(current));
+        current.setHours(current.getHours() + interval.getMinutesInterval() / 60);
+    }
+    return hours;
+}
+function getMinutesWithInterval(start, end, interval) {
+    const minutes = [];
+    const current = new Date(start);
+    current.setSeconds(0, 0);
+    while (current <= end) {
+        minutes.push(new Date(current));
+        current.setMinutes(current.getMinutes() + interval.getMinutesInterval());
+    }
+    return minutes;
+}
+function getMonthsWithInterval(start, end, interval) {
+    const months = [];
+    const current = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), 1));
+    while (current <= end) {
+        months.push(new Date(current));
+        current.setUTCMonth(current.getUTCMonth() + interval.getMinutesInterval() / (30 * 24 * 60));
+    }
+    return months;
+}
+function getYearsWithInterval(start, end, interval) {
+    const years = [];
+    const current = new Date(Date.UTC(start.getUTCFullYear(), 0, 1));
+    while (current <= end) {
+        years.push(new Date(current));
+        // Calculate the number of years to add based on the interval
+        const yearsToAdd = Math.max(1, Math.round(interval.getMinutesInterval() / 525600)); // 525600 minutes in a year
+        current.setUTCFullYear(current.getUTCFullYear() + yearsToAdd);
+    }
+    return years;
+}
+function addToDate(date, amount, unit) {
+    const newDate = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), date.getUTCHours(), date.getUTCMinutes(), date.getUTCSeconds(), date.getUTCMilliseconds()));
+    switch (unit) {
+        case precision_1.Precision.MINUTE:
+            newDate.setUTCMinutes(newDate.getUTCMinutes() + amount);
+            break;
+        case precision_1.Precision.HOUR:
+            newDate.setUTCHours(newDate.getUTCHours() + amount);
+            break;
+        case precision_1.Precision.DAY:
+            newDate.setUTCDate(newDate.getUTCDate() + amount);
+            break;
+        case precision_1.Precision.WEEK:
+            newDate.setUTCDate(newDate.getUTCDate() + amount * 7);
+            break;
+        case precision_1.Precision.MONTH:
+            newDate.setUTCMonth(newDate.getUTCMonth() + amount);
+            if (newDate.getUTCDate() !== date.getUTCDate()) {
+                newDate.setUTCDate(0); // Set to last day of previous month
+            }
+            break;
+        case precision_1.Precision.YEAR:
+            newDate.setUTCFullYear(newDate.getUTCFullYear() + amount);
+            break;
+    }
+    return newDate;
+}
+function subtractFromDate(date, amount, unit) {
+    return addToDate(date, -amount, unit);
+}
+function isSameDay(date1, date2) {
+    return (date1.getFullYear() === date2.getFullYear() &&
+        date1.getMonth() === date2.getMonth() &&
+        date1.getDate() === date2.getDate());
+}
+function getWeekNumber(date) {
+    const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+    const dayNum = d.getUTCDay() || 7;
+    d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+    const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+    return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+}
+function getQuarter(date) {
+    return Math.floor(date.getMonth() / 3) + 1;
+}
+function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+function getDaysInMonth(year, month) {
+    return new Date(year, month + 1, 0).getDate();
+}
+function formatDate(date, format) {
+    const pad = (n) => n.toString().padStart(2, '0');
+    const map = {
+        YYYY: date.getFullYear().toString(),
+        MM: pad(date.getMonth() + 1),
+        DD: pad(date.getDate()),
+        HH: pad(date.getHours()),
+        mm: pad(date.getMinutes()),
+        ss: pad(date.getSeconds()),
+    };
+    return format.replace(/YYYY|MM|DD|HH|mm|ss/gi, (matched) => map[matched]);
+}
+function parseDate(dateString, format) {
+    const map = {};
+    const formatParts = format.match(/YYYY|MM|DD|HH|mm|ss/gi) || [];
+    const dateParts = dateString.match(/\d+/g) || [];
+    formatParts.forEach((part, index) => {
+        map[part] = parseInt(dateParts[index]);
+    });
+    return new Date(map['YYYY'] || 0, (map['MM'] || 1) - 1, map['DD'] || 1, map['HH'] || 0, map['mm'] || 0, map['ss'] || 0);
+}
+function range(start, end, step = 1) {
+    return Array.from({ length: Math.floor((end - start) / step) + 1 }, (_, i) => start + i * step);
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "chronos-ts",
+  "version": "1.0.0",
+  "description": "A comprehensive TypeScript package for handling time periods, intervals, and date-related operations.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "format": "prettier --write 'src/**/*.{ts,js,json,md}'",
+    "lint": "eslint 'src/**/*.{ts,js}'",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run format && npm run lint && npm test",
+    "postpublish": "git push --follow-tags"
+  },
+  "keywords": [
+    "time",
+    "date",
+    "period",
+    "interval",
+    "duration",
+    "range",
+    "typescript",
+    "calendar",
+    "datetime",
+    "time-management",
+    "date-range",
+    "date-manipulation",
+    "time-utils",
+    "date-utils",
+    "temporal",
+    "scheduling",
+    "time-period",
+    "date-interval",
+    "time-arithmetic",
+    "date-arithmetic"
+  ],
+  "files": [
+    "dist/**",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hendurhance/chronos-ts.git"
+  },
+  "author": "Josiah Endurance",
+  "homepage": "https://github.com/hendurhance/chronos-ts#readme",
+  "contributors": [
+    {
+      "name": "Josiah Endurance",
+      "email": "hendurhance.dev@gmail.com"
+    }
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.10.0",
+    "@types/eslint__js": "^8.42.3",
+    "@types/jest": "^29.5.13",
+    "@types/node": "^22.5.5",
+    "eslint": "^9.10.0",
+    "globals": "^15.9.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.3.3",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.6.0"
+  }
+}