chronos-ts 1.0.1 → 1.0.3

package/README.md

@@ -65,7 +65,7 @@ const periodsOverlap = year2023.overlapsWith(q2_2023); // true
 
 // Get the overlapping period
 const overlap = year2023.overlap(q2_2023);
-console.log(overlap?.getStartDate()t, overlap?.getEndDate()); // 2023-04-01, 2023-06-30
+console.log(overlap?.getStartDate(), overlap?.getEndDate()); // 2023-04-01, 2023-06-30
 
 // Subtract a period
 const remainingPeriods = year2023.subtract(q2_2023);
@@ -186,7 +186,8 @@ Static Methods
 #### Enums
 ##### Precision
 The Precision enum represents different levels of time precision.
-typescriptCopyenum Precision {
+```typescript
+enum Precision {
     MINUTE = 'minute',
     HOUR = 'hour',
     DAY = 'day',
@@ -194,7 +195,7 @@ typescriptCopyenum Precision {
     MONTH = 'month',
     YEAR = 'year',
 }
-
+```
 ### Utility Function
 The package includes various utility functions for working with dates:
 

package/dist/interval.d.ts

@@ -4,11 +4,58 @@ export declare class Interval {
     private days;
     private weeks;
     private months;
+    /**
+     * Constructs a new instance of the Interval class.
+     *
+     * @param minutes - The number of minutes (default is 0).
+     * @param hours - The number of hours (default is 0).
+     * @param days - The number of days (default is 0).
+     * @param weeks - The number of weeks (default is 0).
+     * @param months - The number of months (default is 0).
+     */
     private constructor();
+    /**
+     * Creates an Interval instance representing the specified number of minutes.
+     *
+     * @param minutes - The number of minutes for the interval.
+     * @returns An Interval instance representing the specified number of minutes.
+     */
     static minutes(minutes: number): Interval;
+    /**
+     * Creates an Interval instance representing the given number of hours.
+     *
+     * @param hours - The number of hours for the interval.
+     * @returns An Interval instance with the specified hours.
+     */
     static hours(hours: number): Interval;
+    /**
+     * Creates an Interval instance representing the specified number of days.
+     *
+     * @param days - The number of days for the interval.
+     * @returns An Interval instance with the specified number of days.
+     */
     static days(days: number): Interval;
+    /**
+     * Creates an Interval instance representing the specified number of weeks.
+     *
+     * @param weeks - The number of weeks for the interval.
+     * @returns An Interval instance with the specified number of weeks.
+     */
     static weeks(weeks: number): Interval;
+    /**
+     * Creates an Interval instance representing a specified number of months.
+     *
+     * @param months - The number of months for the interval.
+     * @returns An Interval instance with the specified number of months.
+     */
     static months(months: number): Interval;
+    /**
+     * Calculates the total interval in minutes.
+     *
+     * This method sums up the minutes, hours, days, weeks, and months
+     * to return the total interval in minutes.
+     *
+     * @returns {number} The total interval in minutes.
+     */
     getMinutesInterval(): number;
 }

package/dist/interval.js

@@ -2,6 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Interval = void 0;
 class Interval {
+    /**
+     * Constructs a new instance of the Interval class.
+     *
+     * @param minutes - The number of minutes (default is 0).
+     * @param hours - The number of hours (default is 0).
+     * @param days - The number of days (default is 0).
+     * @param weeks - The number of weeks (default is 0).
+     * @param months - The number of months (default is 0).
+     */
     constructor(minutes = 0, hours = 0, days = 0, weeks = 0, months = 0) {
         this.minutes = minutes;
         this.hours = hours;
@@ -9,21 +18,59 @@ class Interval {
         this.weeks = weeks;
         this.months = months;
     }
+    /**
+     * Creates an Interval instance representing the specified number of minutes.
+     *
+     * @param minutes - The number of minutes for the interval.
+     * @returns An Interval instance representing the specified number of minutes.
+     */
     static minutes(minutes) {
         return new Interval(minutes);
     }
+    /**
+     * Creates an Interval instance representing the given number of hours.
+     *
+     * @param hours - The number of hours for the interval.
+     * @returns An Interval instance with the specified hours.
+     */
     static hours(hours) {
         return new Interval(0, hours);
     }
+    /**
+     * Creates an Interval instance representing the specified number of days.
+     *
+     * @param days - The number of days for the interval.
+     * @returns An Interval instance with the specified number of days.
+     */
     static days(days) {
         return new Interval(0, 0, days);
     }
+    /**
+     * Creates an Interval instance representing the specified number of weeks.
+     *
+     * @param weeks - The number of weeks for the interval.
+     * @returns An Interval instance with the specified number of weeks.
+     */
     static weeks(weeks) {
         return new Interval(0, 0, 0, weeks);
     }
+    /**
+     * Creates an Interval instance representing a specified number of months.
+     *
+     * @param months - The number of months for the interval.
+     * @returns An Interval instance with the specified number of months.
+     */
     static months(months) {
         return new Interval(0, 0, 0, 0, months);
     }
+    /**
+     * Calculates the total interval in minutes.
+     *
+     * This method sums up the minutes, hours, days, weeks, and months
+     * to return the total interval in minutes.
+     *
+     * @returns {number} The total interval in minutes.
+     */
     getMinutesInterval() {
         return (this.minutes +
             this.hours * 60 +

package/dist/period.d.ts

@@ -5,29 +5,181 @@ export declare class Period {
     private endDate;
     private precision;
     private interval;
+    /**
+     * Constructs a new Period instance.
+     *
+     * @param start - The start date of the period, either as a string or a Date object.
+     * @param end - The end date of the period, either as a string or a Date object.
+     * @param precision - The precision level of the period, defaulting to Precision.DAY.
+     * @param interval - An optional interval associated with the period, defaulting to null.
+     */
     constructor(start: string | Date, end: string | Date, precision?: Precision, interval?: Interval | null);
+    /**
+     * Retrieves the start date of the period.
+     *
+     * @returns {Date} The start date as a Date object.
+     */
     getStartDate(): Date;
+    /**
+     * Retrieves the end date of the period.
+     *
+     * @returns {Date} The end date as a Date object.
+     */
     getEndDate(): Date;
+    /**
+     * Checks if a given date is within the period defined by `startDate` and `endDate`.
+     *
+     * @param date - The date to check, either as a string or a Date object.
+     * @returns `true` if the date is within the period, `false` otherwise.
+     */
     contains(date: string | Date): boolean;
+    /**
+     * Determines if the current period overlaps with another period.
+     *
+     * @param other - The other period to compare with.
+     * @returns `true` if the periods overlap, otherwise `false`.
+     */
     overlapsWith(other: Period): boolean;
+    /**
+     * Determines if the current period is adjacent to another period.
+     *
+     * Two periods are considered adjacent if they do not overlap and the gap
+     * between them is within one precision unit of the larger precision of the two periods.
+     *
+     * @param other - The other period to compare with.
+     * @returns `true` if the periods are adjacent, `false` otherwise.
+     */
     isAdjacentTo(other: Period): boolean;
+    /**
+     * Retrieves an array of dates within the specified interval.
+     *
+     * @returns {Date[] | null} An array of dates if the interval is defined, otherwise `null`.
+     */
     getDatesInInterval(): Date[] | null;
+    /**
+     * Calculates the number of minutes in the interval between the start and end dates.
+     *
+     * @returns {number} The number of minutes between the start and end dates.
+     */
     getMinutesInInterval(): number;
+    /**
+     * Calculates the number of whole hours in the interval.
+     *
+     * @returns {number} The number of whole hours in the interval.
+     */
     getHoursInInterval(): number;
+    /**
+     * Calculates the number of whole days in the interval.
+     *
+     * @returns The number of whole days in the interval.
+     */
     getDaysInInterval(): number;
+    /**
+     * Calculates the number of whole weeks in the interval.
+     *
+     * @returns The number of whole weeks in the interval.
+     */
     getWeeksInInterval(): number;
+    /**
+     * Calculates the number of whole months in the interval between the start and end dates.
+     *
+     * This method computes the difference in months between the `startDate` and `endDate` properties.
+     * It adjusts for month boundaries by decrementing the month count if the end date's day is less than the start date's day.
+     *
+     * @returns {number} The number of whole months in the interval.
+     */
     getMonthsInInterval(): number;
+    /**
+     * Calculates the number of whole years in the interval.
+     *
+     * @returns The number of whole years in the interval.
+     */
     getYearsInInterval(): number;
+    /**
+     * Calculates the length of the period in the specified precision.
+     *
+     * @returns {number} The length of the period, rounded down to the nearest whole number.
+     */
     length(): number;
+    /**
+     * Determines the overlapping period between this period and another period.
+     *
+     * @param other - The other period to check for overlap with.
+     * @returns The overlapping period as a new `Period` instance, or `null` if there is no overlap.
+     */
     overlap(other: Period): Period | null;
+    /**
+     * Subtracts the given period from the current period and returns the resulting periods.
+     * If the periods do not overlap, the current period is returned as a single-element array.
+     * If they do overlap, the resulting periods are returned as an array.
+     *
+     * @param other - The period to subtract from the current period.
+     * @returns An array of resulting periods after subtraction.
+     */
     subtract(other: Period): Period[];
+    /**
+     * Calculates the gap between this period and another period.
+     * If the periods overlap or are adjacent, returns null.
+     * Otherwise, returns a new Period representing the gap between the two periods.
+     *
+     * @param other - The other period to compare with.
+     * @returns A new Period representing the gap, or null if the periods overlap or are adjacent.
+     */
     gap(other: Period): Period | null;
+    /**
+     * Computes the symmetric difference between this period and another period.
+     * The symmetric difference is defined as the set of periods that are in either
+     * of the two periods but not in their intersection.
+     *
+     * @param other - The other period to compute the symmetric difference with.
+     * @returns An array of periods representing the symmetric difference, sorted
+     *          by start date and merged if adjacent.
+     */
     symmetricDifference(other: Period): Period[];
     private mergeAdjacentPeriods;
+    /**
+     * Renews the current period by creating a new `Period` instance.
+     * The new period starts immediately after the end of the current period
+     * and has the same length and precision.
+     *
+     * @returns {Period} A new `Period` instance with updated start and end dates.
+     */
     renew(): Period;
+    /**
+     * Computes the union of this period with another period.
+     * If the periods overlap or are adjacent, they are merged into a single period.
+     * Otherwise, the periods are returned as separate, sorted periods.
+     *
+     * @param other - The other period to union with this period.
+     * @returns An array of periods resulting from the union operation.
+     */
     union(other: Period): Period[];
+    /**
+     * Sets the start date for the period.
+     *
+     * @param start - The start date, which can be a string or a Date object.
+     * @returns The current instance for method chaining.
+     */
     setStart(start: string | Date): this;
+    /**
+     * Sets the end date for the period.
+     *
+     * @param end - The end date as a string or Date object.
+     * @returns The current instance for method chaining.
+     */
     setEnd(end: string | Date): this;
+    /**
+     * Sets the precision for the period.
+     *
+     * @param precision - The precision to set.
+     * @returns The current instance for method chaining.
+     */
     setPrecision(precision: Precision): this;
+    /**
+     * Sets the interval for the period.
+     *
+     * @param interval - The interval to be set.
+     * @returns The current instance of the period.
+     */
     setInterval(interval: Interval): this;
 }

package/dist/period.js

@@ -4,25 +4,64 @@ exports.Period = void 0;
 const precision_1 = require("./precision");
 const utils_1 = require("./utils");
 class Period {
+    /**
+     * Constructs a new Period instance.
+     *
+     * @param start - The start date of the period, either as a string or a Date object.
+     * @param end - The end date of the period, either as a string or a Date object.
+     * @param precision - The precision level of the period, defaulting to Precision.DAY.
+     * @param interval - An optional interval associated with the period, defaulting to null.
+     */
     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;
     }
+    /**
+     * Retrieves the start date of the period.
+     *
+     * @returns {Date} The start date as a Date object.
+     */
     getStartDate() {
         return new Date(this.startDate);
     }
+    /**
+     * Retrieves the end date of the period.
+     *
+     * @returns {Date} The end date as a Date object.
+     */
     getEndDate() {
         return new Date(this.endDate);
     }
+    /**
+     * Checks if a given date is within the period defined by `startDate` and `endDate`.
+     *
+     * @param date - The date to check, either as a string or a Date object.
+     * @returns `true` if the date is within the period, `false` otherwise.
+     */
     contains(date) {
         const checkDate = new Date(date);
         return checkDate >= this.startDate && checkDate <= this.endDate;
     }
+    /**
+     * Determines if the current period overlaps with another period.
+     *
+     * @param other - The other period to compare with.
+     * @returns `true` if the periods overlap, otherwise `false`.
+     */
     overlapsWith(other) {
         return this.startDate < other.endDate && this.endDate > other.startDate;
     }
+    /**
+     * Determines if the current period is adjacent to another period.
+     *
+     * Two periods are considered adjacent if they do not overlap and the gap
+     * between them is within one precision unit of the larger precision of the two periods.
+     *
+     * @param other - The other period to compare with.
+     * @returns `true` if the periods are adjacent, `false` otherwise.
+     */
     isAdjacentTo(other) {
         const thisPrecisionMs = (0, precision_1.getPrecisionInMilliseconds)(this.precision);
         const otherPrecisionMs = (0, precision_1.getPrecisionInMilliseconds)(other.precision);
@@ -41,24 +80,57 @@ class Period {
         return ((gap > 0 && gap <= maxPrecisionMs) ||
             (reverseGap > 0 && reverseGap <= maxPrecisionMs));
     }
+    /**
+     * Retrieves an array of dates within the specified interval.
+     *
+     * @returns {Date[] | null} An array of dates if the interval is defined, otherwise `null`.
+     */
     getDatesInInterval() {
         if (this.interval) {
             return (0, utils_1.getDatesWithInterval)(this.startDate, this.endDate, this.interval);
         }
         return null;
     }
+    /**
+     * Calculates the number of minutes in the interval between the start and end dates.
+     *
+     * @returns {number} The number of minutes between the start and end dates.
+     */
     getMinutesInInterval() {
         return Math.floor((this.endDate.getTime() - this.startDate.getTime()) / (1000 * 60));
     }
+    /**
+     * Calculates the number of whole hours in the interval.
+     *
+     * @returns {number} The number of whole hours in the interval.
+     */
     getHoursInInterval() {
         return Math.floor(this.getMinutesInInterval() / 60);
     }
+    /**
+     * Calculates the number of whole days in the interval.
+     *
+     * @returns The number of whole days in the interval.
+     */
     getDaysInInterval() {
         return Math.floor(this.getHoursInInterval() / 24);
     }
+    /**
+     * Calculates the number of whole weeks in the interval.
+     *
+     * @returns The number of whole weeks in the interval.
+     */
     getWeeksInInterval() {
         return Math.floor(this.getDaysInInterval() / 7);
     }
+    /**
+     * Calculates the number of whole months in the interval between the start and end dates.
+     *
+     * This method computes the difference in months between the `startDate` and `endDate` properties.
+     * It adjusts for month boundaries by decrementing the month count if the end date's day is less than the start date's day.
+     *
+     * @returns {number} The number of whole months in the interval.
+     */
     getMonthsInInterval() {
         let months = (this.endDate.getFullYear() - this.startDate.getFullYear()) * 12;
         months += this.endDate.getMonth() - this.startDate.getMonth();
@@ -68,13 +140,29 @@ class Period {
         }
         return months;
     }
+    /**
+     * Calculates the number of whole years in the interval.
+     *
+     * @returns The number of whole years in the interval.
+     */
     getYearsInInterval() {
         return Math.floor(this.getMonthsInInterval() / 12);
     }
+    /**
+     * Calculates the length of the period in the specified precision.
+     *
+     * @returns {number} The length of the period, rounded down to the nearest whole number.
+     */
     length() {
         return Math.floor((this.endDate.getTime() - this.startDate.getTime()) /
             (0, precision_1.getPrecisionInMilliseconds)(this.precision));
     }
+    /**
+     * Determines the overlapping period between this period and another period.
+     *
+     * @param other - The other period to check for overlap with.
+     * @returns The overlapping period as a new `Period` instance, or `null` if there is no overlap.
+     */
     overlap(other) {
         if (!this.overlapsWith(other)) {
             return null;
@@ -83,6 +171,14 @@ class Period {
         const end = new Date(Math.min(this.endDate.getTime(), other.endDate.getTime()));
         return new Period(start, end, this.precision);
     }
+    /**
+     * Subtracts the given period from the current period and returns the resulting periods.
+     * If the periods do not overlap, the current period is returned as a single-element array.
+     * If they do overlap, the resulting periods are returned as an array.
+     *
+     * @param other - The period to subtract from the current period.
+     * @returns An array of resulting periods after subtraction.
+     */
     subtract(other) {
         if (!this.overlapsWith(other)) {
             return [this];
@@ -98,6 +194,14 @@ class Period {
         }
         return periods;
     }
+    /**
+     * Calculates the gap between this period and another period.
+     * If the periods overlap or are adjacent, returns null.
+     * Otherwise, returns a new Period representing the gap between the two periods.
+     *
+     * @param other - The other period to compare with.
+     * @returns A new Period representing the gap, or null if the periods overlap or are adjacent.
+     */
     gap(other) {
         if (this.overlapsWith(other) || this.isAdjacentTo(other)) {
             return null;
@@ -107,6 +211,15 @@ class Period {
         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);
     }
+    /**
+     * Computes the symmetric difference between this period and another period.
+     * The symmetric difference is defined as the set of periods that are in either
+     * of the two periods but not in their intersection.
+     *
+     * @param other - The other period to compute the symmetric difference with.
+     * @returns An array of periods representing the symmetric difference, sorted
+     *          by start date and merged if adjacent.
+     */
     symmetricDifference(other) {
         const periods = [];
         const overlapPeriod = this.overlap(other);
@@ -139,12 +252,27 @@ class Period {
         }
         return merged;
     }
+    /**
+     * Renews the current period by creating a new `Period` instance.
+     * The new period starts immediately after the end of the current period
+     * and has the same length and precision.
+     *
+     * @returns {Period} A new `Period` instance with updated start and end dates.
+     */
     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);
     }
+    /**
+     * Computes the union of this period with another period.
+     * If the periods overlap or are adjacent, they are merged into a single period.
+     * Otherwise, the periods are returned as separate, sorted periods.
+     *
+     * @param other - The other period to union with this period.
+     * @returns An array of periods resulting from the union operation.
+     */
     union(other) {
         if (this.overlapsWith(other) || this.isAdjacentTo(other)) {
             const start = new Date(Math.min(this.startDate.getTime(), other.startDate.getTime()));
@@ -154,18 +282,42 @@ class Period {
         return [this, other].sort((a, b) => a.startDate.getTime() - b.startDate.getTime());
     }
     // Fluent API methods
+    /**
+     * Sets the start date for the period.
+     *
+     * @param start - The start date, which can be a string or a Date object.
+     * @returns The current instance for method chaining.
+     */
     setStart(start) {
         this.startDate = new Date(start);
         return this;
     }
+    /**
+     * Sets the end date for the period.
+     *
+     * @param end - The end date as a string or Date object.
+     * @returns The current instance for method chaining.
+     */
     setEnd(end) {
         this.endDate = new Date(end);
         return this;
     }
+    /**
+     * Sets the precision for the period.
+     *
+     * @param precision - The precision to set.
+     * @returns The current instance for method chaining.
+     */
     setPrecision(precision) {
         this.precision = precision;
         return this;
     }
+    /**
+     * Sets the interval for the period.
+     *
+     * @param interval - The interval to be set.
+     * @returns The current instance of the period.
+     */
     setInterval(interval) {
         this.interval = interval;
         return this;

package/dist/precision.d.ts

@@ -6,4 +6,19 @@ export declare enum Precision {
     MONTH = "month",
     YEAR = "year"
 }
+/**
+ * Converts a given precision to its equivalent duration in milliseconds.
+ *
+ * @param precision - The precision to convert. It can be one of the following:
+ * - `Precision.MINUTE`: 1 minute in milliseconds.
+ * - `Precision.HOUR`: 1 hour in milliseconds.
+ * - `Precision.DAY`: 1 day in milliseconds.
+ * - `Precision.WEEK`: 1 week in milliseconds.
+ * - `Precision.MONTH`: 1 month (approximated as 30 days) in milliseconds.
+ * - `Precision.YEAR`: 1 year (approximated as 365 days) in milliseconds.
+ *
+ * @returns The duration in milliseconds corresponding to the given precision.
+ *
+ * @throws Will throw an error if the provided precision is not supported.
+ */
 export declare function getPrecisionInMilliseconds(precision: Precision): number;

package/dist/precision.js

@@ -11,6 +11,21 @@ var Precision;
     Precision["MONTH"] = "month";
     Precision["YEAR"] = "year";
 })(Precision || (exports.Precision = Precision = {}));
+/**
+ * Converts a given precision to its equivalent duration in milliseconds.
+ *
+ * @param precision - The precision to convert. It can be one of the following:
+ * - `Precision.MINUTE`: 1 minute in milliseconds.
+ * - `Precision.HOUR`: 1 hour in milliseconds.
+ * - `Precision.DAY`: 1 day in milliseconds.
+ * - `Precision.WEEK`: 1 week in milliseconds.
+ * - `Precision.MONTH`: 1 month (approximated as 30 days) in milliseconds.
+ * - `Precision.YEAR`: 1 year (approximated as 365 days) in milliseconds.
+ *
+ * @returns The duration in milliseconds corresponding to the given precision.
+ *
+ * @throws Will throw an error if the provided precision is not supported.
+ */
 function getPrecisionInMilliseconds(precision) {
     switch (precision) {
         case Precision.MINUTE:

package/dist/utils.d.ts

@@ -1,19 +1,188 @@
 import { Interval } from './interval';
 import { Precision } from './precision';
+/**
+ * Generates an array of dates between the given start and end dates,
+ * with a specified interval between each date.
+ *
+ * @param start - The start date.
+ * @param end - The end date.
+ * @param interval - An object representing the interval between dates.
+ * @returns An array of dates between the start and end dates, inclusive,
+ *          with the specified interval.
+ */
 export declare function getDatesWithInterval(start: Date, end: Date, interval: Interval): Date[];
+/**
+ * Generates an array of dates representing the start of each week within a given interval.
+ *
+ * @param start - The start date of the interval.
+ * @param end - The end date of the interval.
+ * @param interval - An object representing the interval in minutes.
+ * @returns An array of dates, each representing the start of a week within the interval.
+ */
 export declare function getWeeksWithInterval(start: Date, end: Date, interval: Interval): Date[];
+/**
+ * Generates an array of dates between the start and end dates, inclusive,
+ * with a specified interval.
+ *
+ * @param start - The start date.
+ * @param end - The end date.
+ * @param interval - The interval object that provides the interval in minutes.
+ * @returns An array of dates with the specified interval.
+ */
 export declare function getDaysWithInterval(start: Date, end: Date, interval: Interval): Date[];
+/**
+ * Generates an array of Date objects representing hours between the start and end dates,
+ * incremented by a specified interval.
+ *
+ * @param start - The start date and time.
+ * @param end - The end date and time.
+ * @param interval - An object that provides the interval in minutes.
+ * @returns An array of Date objects representing the hours within the specified interval.
+ */
 export declare function getHoursWithInterval(start: Date, end: Date, interval: Interval): Date[];
+/**
+ * Generates an array of Date objects representing each minute within a specified interval
+ * between a start and end date.
+ *
+ * @param start - The start date and time.
+ * @param end - The end date and time.
+ * @param interval - An object that provides the interval in minutes.
+ * @returns An array of Date objects, each representing a minute within the specified interval.
+ */
 export declare function getMinutesWithInterval(start: Date, end: Date, interval: Interval): Date[];
+/**
+ * Generates an array of Date objects representing the start of each month
+ * within the specified interval between the start and end dates.
+ *
+ * @param start - The start date of the interval.
+ * @param end - The end date of the interval.
+ * @param interval - An object representing the interval in minutes.
+ * @returns An array of Date objects, each representing the start of a month within the interval.
+ */
 export declare function getMonthsWithInterval(start: Date, end: Date, interval: Interval): Date[];
+/**
+ * Generates an array of Date objects representing the start of each year
+ * within the specified interval between the start and end dates.
+ *
+ * @param start - The start date.
+ * @param end - The end date.
+ * @param interval - An Interval object that determines the interval in minutes.
+ * @returns An array of Date objects representing the start of each year within the interval.
+ */
 export declare function getYearsWithInterval(start: Date, end: Date, interval: Interval): Date[];
+/**
+ * Adds a specified amount of time to a given date based on the provided precision unit.
+ *
+ * @param date - The original date to which the amount will be added.
+ * @param amount - The amount of time to add. Can be positive or negative.
+ * @param unit - The unit of time to add (e.g., minute, hour, day, week, month, year).
+ *
+ * @returns A new `Date` object with the specified amount of time added.
+ *
+ * @example
+ * ```typescript
+ * const originalDate = new Date(Date.UTC(2023, 0, 1));
+ * const newDate = addToDate(originalDate, 5, Precision.DAY);
+ * console.log(newDate); // Outputs: 2023-01-06T00:00:00.000Z
+ * ```
+ */
 export declare function addToDate(date: Date, amount: number, unit: Precision): Date;
+/**
+ * Subtracts a specified amount of time from a given date.
+ *
+ * @param date - The original date from which to subtract.
+ * @param amount - The amount of time to subtract.
+ * @param unit - The unit of time to subtract (e.g., days, months, years).
+ * @returns A new Date object with the specified amount of time subtracted.
+ */
 export declare function subtractFromDate(date: Date, amount: number, unit: Precision): Date;
+/**
+ * Checks if two dates are on the same calendar day.
+ *
+ * @param date1 - The first date to compare.
+ * @param date2 - The second date to compare.
+ * @returns `true` if both dates are on the same day, otherwise `false`.
+ */
 export declare function isSameDay(date1: Date, date2: Date): boolean;
+/**
+ * Calculates the ISO week number for a given date.
+ *
+ * The ISO week date system is a leap week calendar system that is part of the ISO 8601 date and time standard.
+ * It assigns a week number to each week of the year, where the first week of the year is the week that contains
+ * the first Thursday of the year.
+ *
+ * @param date - The date object for which to calculate the week number.
+ * @returns The ISO week number of the given date.
+ */
 export declare function getWeekNumber(date: Date): number;
+/**
+ * Returns the quarter of the year for a given date.
+ *
+ * @param date - The date object for which to determine the quarter.
+ * @returns The quarter of the year (1, 2, 3, or 4).
+ */
 export declare function getQuarter(date: Date): number;
+/**
+ * Determines whether a given year is a leap year.
+ *
+ * A leap year is exactly divisible by 4 except for end-of-century years, which must be divisible by 400.
+ * This means that the year 2000 was a leap year, although 1900 was not.
+ *
+ * @param year - The year to be checked.
+ * @returns `true` if the year is a leap year, otherwise `false`.
+ */
 export declare function isLeapYear(year: number): boolean;
+/**
+ * Returns the number of days in a given month of a specific year.
+ *
+ * @param year - The year for which to get the number of days in the month.
+ * @param month - The month (0-indexed, where 0 = January, 11 = December) for which to get the number of days.
+ * @returns The number of days in the specified month of the given year.
+ */
 export declare function getDaysInMonth(year: number, month: number): number;
+/**
+ * Formats a given date according to the specified format string.
+ *
+ * The format string can contain the following placeholders:
+ * - `YYYY`: Full year (e.g., 2023)
+ * - `MM`: Month (01-12)
+ * - `DD`: Day of the month (01-31)
+ * - `HH`: Hours (00-23)
+ * - `mm`: Minutes (00-59)
+ * - `ss`: Seconds (00-59)
+ *
+ * Example usage:
+ * ```typescript
+ * const date = new Date(2023, 0, 1, 12, 30, 45);
+ * const formattedDate = formatDate(date, 'YYYY-MM-DD HH:mm:ss');
+ * console.log(formattedDate); // Output: "2023-01-01 12:30:45"
+ * ```
+ *
+ * @param date - The date object to format.
+ * @param format - The format string.
+ * @returns The formatted date string.
+ */
 export declare function formatDate(date: Date, format: string): string;
+/**
+ * Parses a date string according to the specified format and returns a Date object.
+ *
+ * @param dateString - The date string to parse.
+ * @param format - The format of the date string. Supported format parts are YYYY, MM, DD, HH, mm, ss.
+ * @returns A Date object representing the parsed date.
+ *
+ * @example
+ * ```typescript
+ * const date = parseDate('2023-10-05 14:30:00', 'YYYY-MM-DD HH:mm:ss');
+ * console.log(date); // Outputs: Thu Oct 05 2023 14:30:00 GMT+0000 (Coordinated Universal Time)
+ * ```
+ */
 export declare function parseDate(dateString: string, format: string): Date;
+/**
+ * Generates an array of numbers within a specified range.
+ *
+ * @param start - The starting number of the range.
+ * @param end - The ending number of the range.
+ * @param step - The step between each number in the range. Defaults to 1.
+ * @returns An array of numbers from start to end, incremented by step.
+ */
 export declare function range(start: number, end: number, step?: number): number[];

package/dist/utils.js

@@ -18,6 +18,16 @@ exports.formatDate = formatDate;
 exports.parseDate = parseDate;
 exports.range = range;
 const precision_1 = require("./precision");
+/**
+ * Generates an array of dates between the given start and end dates,
+ * with a specified interval between each date.
+ *
+ * @param start - The start date.
+ * @param end - The end date.
+ * @param interval - An object representing the interval between dates.
+ * @returns An array of dates between the start and end dates, inclusive,
+ *          with the specified interval.
+ */
 function getDatesWithInterval(start, end, interval) {
     const dates = [];
     const current = new Date(start);
@@ -27,6 +37,14 @@ function getDatesWithInterval(start, end, interval) {
     }
     return dates;
 }
+/**
+ * Generates an array of dates representing the start of each week within a given interval.
+ *
+ * @param start - The start date of the interval.
+ * @param end - The end date of the interval.
+ * @param interval - An object representing the interval in minutes.
+ * @returns An array of dates, each representing the start of a week within the interval.
+ */
 function getWeeksWithInterval(start, end, interval) {
     const weeks = [];
     let current = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate()));
@@ -41,6 +59,15 @@ function getWeeksWithInterval(start, end, interval) {
     }
     return weeks;
 }
+/**
+ * Generates an array of dates between the start and end dates, inclusive,
+ * with a specified interval.
+ *
+ * @param start - The start date.
+ * @param end - The end date.
+ * @param interval - The interval object that provides the interval in minutes.
+ * @returns An array of dates with the specified interval.
+ */
 function getDaysWithInterval(start, end, interval) {
     const days = [];
     const current = new Date(start);
@@ -51,6 +78,15 @@ function getDaysWithInterval(start, end, interval) {
     }
     return days;
 }
+/**
+ * Generates an array of Date objects representing hours between the start and end dates,
+ * incremented by a specified interval.
+ *
+ * @param start - The start date and time.
+ * @param end - The end date and time.
+ * @param interval - An object that provides the interval in minutes.
+ * @returns An array of Date objects representing the hours within the specified interval.
+ */
 function getHoursWithInterval(start, end, interval) {
     const hours = [];
     const current = new Date(start);
@@ -61,6 +97,15 @@ function getHoursWithInterval(start, end, interval) {
     }
     return hours;
 }
+/**
+ * Generates an array of Date objects representing each minute within a specified interval
+ * between a start and end date.
+ *
+ * @param start - The start date and time.
+ * @param end - The end date and time.
+ * @param interval - An object that provides the interval in minutes.
+ * @returns An array of Date objects, each representing a minute within the specified interval.
+ */
 function getMinutesWithInterval(start, end, interval) {
     const minutes = [];
     const current = new Date(start);
@@ -71,6 +116,15 @@ function getMinutesWithInterval(start, end, interval) {
     }
     return minutes;
 }
+/**
+ * Generates an array of Date objects representing the start of each month
+ * within the specified interval between the start and end dates.
+ *
+ * @param start - The start date of the interval.
+ * @param end - The end date of the interval.
+ * @param interval - An object representing the interval in minutes.
+ * @returns An array of Date objects, each representing the start of a month within the interval.
+ */
 function getMonthsWithInterval(start, end, interval) {
     const months = [];
     const current = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), 1));
@@ -80,6 +134,15 @@ function getMonthsWithInterval(start, end, interval) {
     }
     return months;
 }
+/**
+ * Generates an array of Date objects representing the start of each year
+ * within the specified interval between the start and end dates.
+ *
+ * @param start - The start date.
+ * @param end - The end date.
+ * @param interval - An Interval object that determines the interval in minutes.
+ * @returns An array of Date objects representing the start of each year within the interval.
+ */
 function getYearsWithInterval(start, end, interval) {
     const years = [];
     const current = new Date(Date.UTC(start.getUTCFullYear(), 0, 1));
@@ -91,6 +154,22 @@ function getYearsWithInterval(start, end, interval) {
     }
     return years;
 }
+/**
+ * Adds a specified amount of time to a given date based on the provided precision unit.
+ *
+ * @param date - The original date to which the amount will be added.
+ * @param amount - The amount of time to add. Can be positive or negative.
+ * @param unit - The unit of time to add (e.g., minute, hour, day, week, month, year).
+ *
+ * @returns A new `Date` object with the specified amount of time added.
+ *
+ * @example
+ * ```typescript
+ * const originalDate = new Date(Date.UTC(2023, 0, 1));
+ * const newDate = addToDate(originalDate, 5, Precision.DAY);
+ * console.log(newDate); // Outputs: 2023-01-06T00:00:00.000Z
+ * ```
+ */
 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) {
@@ -118,14 +197,39 @@ function addToDate(date, amount, unit) {
     }
     return newDate;
 }
+/**
+ * Subtracts a specified amount of time from a given date.
+ *
+ * @param date - The original date from which to subtract.
+ * @param amount - The amount of time to subtract.
+ * @param unit - The unit of time to subtract (e.g., days, months, years).
+ * @returns A new Date object with the specified amount of time subtracted.
+ */
 function subtractFromDate(date, amount, unit) {
     return addToDate(date, -amount, unit);
 }
+/**
+ * Checks if two dates are on the same calendar day.
+ *
+ * @param date1 - The first date to compare.
+ * @param date2 - The second date to compare.
+ * @returns `true` if both dates are on the same day, otherwise `false`.
+ */
 function isSameDay(date1, date2) {
     return (date1.getFullYear() === date2.getFullYear() &&
         date1.getMonth() === date2.getMonth() &&
         date1.getDate() === date2.getDate());
 }
+/**
+ * Calculates the ISO week number for a given date.
+ *
+ * The ISO week date system is a leap week calendar system that is part of the ISO 8601 date and time standard.
+ * It assigns a week number to each week of the year, where the first week of the year is the week that contains
+ * the first Thursday of the year.
+ *
+ * @param date - The date object for which to calculate the week number.
+ * @returns The ISO week number of the given date.
+ */
 function getWeekNumber(date) {
     const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
     const dayNum = d.getUTCDay() || 7;
@@ -133,15 +237,59 @@ function getWeekNumber(date) {
     const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
     return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
 }
+/**
+ * Returns the quarter of the year for a given date.
+ *
+ * @param date - The date object for which to determine the quarter.
+ * @returns The quarter of the year (1, 2, 3, or 4).
+ */
 function getQuarter(date) {
     return Math.floor(date.getMonth() / 3) + 1;
 }
+/**
+ * Determines whether a given year is a leap year.
+ *
+ * A leap year is exactly divisible by 4 except for end-of-century years, which must be divisible by 400.
+ * This means that the year 2000 was a leap year, although 1900 was not.
+ *
+ * @param year - The year to be checked.
+ * @returns `true` if the year is a leap year, otherwise `false`.
+ */
 function isLeapYear(year) {
     return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
 }
+/**
+ * Returns the number of days in a given month of a specific year.
+ *
+ * @param year - The year for which to get the number of days in the month.
+ * @param month - The month (0-indexed, where 0 = January, 11 = December) for which to get the number of days.
+ * @returns The number of days in the specified month of the given year.
+ */
 function getDaysInMonth(year, month) {
     return new Date(year, month + 1, 0).getDate();
 }
+/**
+ * Formats a given date according to the specified format string.
+ *
+ * The format string can contain the following placeholders:
+ * - `YYYY`: Full year (e.g., 2023)
+ * - `MM`: Month (01-12)
+ * - `DD`: Day of the month (01-31)
+ * - `HH`: Hours (00-23)
+ * - `mm`: Minutes (00-59)
+ * - `ss`: Seconds (00-59)
+ *
+ * Example usage:
+ * ```typescript
+ * const date = new Date(2023, 0, 1, 12, 30, 45);
+ * const formattedDate = formatDate(date, 'YYYY-MM-DD HH:mm:ss');
+ * console.log(formattedDate); // Output: "2023-01-01 12:30:45"
+ * ```
+ *
+ * @param date - The date object to format.
+ * @param format - The format string.
+ * @returns The formatted date string.
+ */
 function formatDate(date, format) {
     const pad = (n) => n.toString().padStart(2, '0');
     const map = {
@@ -154,6 +302,19 @@ function formatDate(date, format) {
     };
     return format.replace(/YYYY|MM|DD|HH|mm|ss/gi, (matched) => map[matched]);
 }
+/**
+ * Parses a date string according to the specified format and returns a Date object.
+ *
+ * @param dateString - The date string to parse.
+ * @param format - The format of the date string. Supported format parts are YYYY, MM, DD, HH, mm, ss.
+ * @returns A Date object representing the parsed date.
+ *
+ * @example
+ * ```typescript
+ * const date = parseDate('2023-10-05 14:30:00', 'YYYY-MM-DD HH:mm:ss');
+ * console.log(date); // Outputs: Thu Oct 05 2023 14:30:00 GMT+0000 (Coordinated Universal Time)
+ * ```
+ */
 function parseDate(dateString, format) {
     const map = {};
     const formatParts = format.match(/YYYY|MM|DD|HH|mm|ss/gi) || [];
@@ -163,6 +324,14 @@ function parseDate(dateString, format) {
     });
     return new Date(map['YYYY'] || 0, (map['MM'] || 1) - 1, map['DD'] || 1, map['HH'] || 0, map['mm'] || 0, map['ss'] || 0);
 }
+/**
+ * Generates an array of numbers within a specified range.
+ *
+ * @param start - The starting number of the range.
+ * @param end - The ending number of the range.
+ * @param step - The step between each number in the range. Defaults to 1.
+ * @returns An array of numbers from start to end, incremented by step.
+ */
 function range(start, end, step = 1) {
     return Array.from({ length: Math.floor((end - start) / step) + 1 }, (_, i) => start + i * step);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chronos-ts",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A comprehensive TypeScript package for handling time periods, intervals, and date-related operations.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",