scdate 0.2.4 → 0.2.5

package/dist/sDate.js

@@ -4,42 +4,91 @@ import { getDateAsUTCDateMini, getISODateFromISODate, getISODateFromZonedDate, g
 import { getAtIndex } from './internal/utils.js';
 import { getIndexForWeekday } from './internal/weekdays.js';
 import { getMillisecondsInUTCFromDate, getTimeZonedDate, } from './internal/zoned.js';
+/**
+ * --- Factory ---
+ */
+/**
+ * Returns a new SDate instance.
+ *
+ * @param date An instance of SDate or a string in the YYYY-MM-DD format.
+ */
 export const sDate = (date) => {
     if (date instanceof SDate) {
         return date;
     }
     return new SDate(date);
 };
+/**
+ * --- Factory helpers ---
+ */
+/**
+ * Returns a new SDate instance with the current date in the given time zone.
+ *
+ * @param timeZone The time zone to get the current date for. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export const getDateToday = (timeZone) => {
     const date = getTimeZonedDate(Date.now(), timeZone);
     return sDate(getISODateFromZonedDate(date));
 };
+/**
+ * Returns a new SDate instance set to the next date after the provided date
+ * that match the given weekday.
+ *
+ * @param date The date to start from (not included). It can be an SDate or a
+ * string in the YYYY-MM-DD format.
+ * @param weekday The weekday to find the next date for.
+ */
 export const getNextDateByWeekday = (date, weekday) => {
     const sDateValue = sDate(date);
     const weekdayIndex = getIndexForWeekday(weekday);
     const todaysWeekdayIndex = DayToWeekday.indexOf(getWeekdayFromDate(sDateValue));
+    // Find the adjustment to get the next date that matches `weekday`
     let adjustment = weekdayIndex - todaysWeekdayIndex;
     if (adjustment <= 0) {
         adjustment += DaysInWeek;
     }
     return addDaysToDate(sDateValue, adjustment);
 };
+/**
+ * Returns a new SDate instance set to date that is before the provided date and
+ * matches the given weekday.
+ *
+ * @param date The date to start from (not included).
+ * @param weekday The weekday to find the previous date for. It can be an SDate
+ * or a string in the YYYY-MM-DD format.
+ */
 export const getPreviousDateByWeekday = (date, weekday) => {
     const sDateValue = sDate(date);
     const weekdayIndex = getIndexForWeekday(weekday);
     const todaysWeekdayIndex = DayToWeekday.indexOf(getWeekdayFromDate(sDateValue));
+    // Find the adjustment to get the previous date that matches `weekday`
     let adjustment = weekdayIndex - todaysWeekdayIndex;
     if (adjustment >= 0) {
         adjustment -= DaysInWeek;
     }
     return addDaysToDate(sDateValue, adjustment);
 };
+/**
+ * Returns a new SDate instance set to the first day of the month for the
+ * provided date.
+ *
+ * @param date The date to get the first day of the month for. It can be an
+ * SDate or a string in the YYYY-MM-DD format.
+ */
 export const getDateForFirstDayOfMonth = (date) => {
     const sDateValue = sDate(date);
     const nativeDate = getDateAsUTCDateMini(sDateValue);
     nativeDate.setDate(1);
     return sDate(getISODateFromZonedDate(nativeDate));
 };
+/**
+ * Returns a new SDate instance set to the last day of the month for the
+ * provided date.
+ *
+ * @param date The date to get the last day of the month for. It can be an SDate
+ * or a string in the YYYY-MM-DD format.
+ */
 export const getDateForLastDayOfMonth = (date) => {
     const sDateValue = sDate(date);
     const nativeDate = getDateAsUTCDateMini(sDateValue);
@@ -47,29 +96,79 @@ export const getDateForLastDayOfMonth = (date) => {
     nativeDate.setHours(0, 0, 0, 0);
     return sDate(getISODateFromZonedDate(nativeDate));
 };
+/**
+ * --- Getters ---
+ */
+/**
+ * Returns the year from the given date.
+ *
+ * @param date The date to get the year from. It can be an SDate or a string in
+ * the YYYY-MM-DD format.
+ */
 export const getYearFromDate = (date) => {
     const sDateValue = sDate(date);
     return Number(getISOYearFromISODate(sDateValue.date));
 };
+/**
+ * Returns the month from the given date. Returns a 0-index value (i.e. Janary
+ * is 0 and December is 11) to match the result from native Date object.
+ *
+ * @param date The date to get the month from. It can be an SDate or a string in
+ * the YYYY-MM-DD format.
+ */
 export const getMonthFromDate = (date) => {
     const sDateValue = sDate(date);
     return Number(getISOMonthFromISODate(sDateValue.date)) - 1;
 };
+/**
+ * Returns the day of the month from the given date.
+ *
+ * @param date The date to get the day from. It can be an SDate or a string in
+ * the YYYY-MM-DD format.
+ */
 export const getDateFromDate = (date) => {
     const sDateValue = sDate(date);
     return Number(getISODateFromISODate(sDateValue.date));
 };
+/**
+ * Returns the day of the week from the given date (Sunday to Saturday / 0 to
+ * 6).
+ *
+ * @param date The date to get the weekday from. It can be an SDate or a string
+ * in the YYYY-MM-DD format.
+ */
 export const getWeekdayFromDate = (date) => {
     const sDateValue = sDate(date);
     const nativeDate = getDateAsUTCDateMini(sDateValue);
     return getAtIndex(DayToWeekday, nativeDate.getDay());
 };
+/**
+ * Returns a native Date adjusted so that the local time of that date matches
+ * the local time at the specified time zone.
+ *
+ * @param date The date to get the time zoned date from. It can be an SDate or a
+ * string in the YYYY-MM-DD format.
+ * @param timeZone The time zone to adjust the date to. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export const getTimeZonedDateFromDate = (date, timeZone) => {
     const sDateValue = sDate(date);
     const milliseconds = getMillisecondsInUTCFromDate(sDateValue, timeZone);
     const zonedTime = getTimeZonedDate(milliseconds, timeZone);
     return zonedTime;
 };
+/**
+ * Returns the number of days between the first date to the second date. The
+ * value is positive if the first date is before the second date, and negative
+ * if the first date is after the second date. This accounts for calendar days
+ * and not full 24-hour periods which could be different due to daylight saving
+ * adjustments.
+ *
+ * @param date1 The first date to get the days between. It can be an SDate or a
+ * string in the YYYY-MM-DD format.
+ * @param date2 The second date to get the days between. It can be an SDate or a
+ * string in the YYYY-MM-DD format.
+ */
 export const getDaysBetweenDates = (date1, date2) => {
     const sDate1 = sDate(date1);
     const sDate2 = sDate(date2);
@@ -77,6 +176,26 @@ export const getDaysBetweenDates = (date1, date2) => {
     const ms2 = getDateAsUTCDateMini(sDate2).getTime();
     return Math.round((ms2 - ms1) / MillisecondsInDay);
 };
+/**
+ * Returns a string representation that includes all of the date components of
+ * the given date formatted according to the given locale.
+ *
+ * @param date The date to get the full string representation for. It can be an
+ * SDate or a string in the YYYY-MM-DD format.
+ * @param locale The locale to use for the string representation.
+ *
+ * @example
+ * ```ts
+ * getFullDateString('2021-02-05', 'es')
+ * //=> 'viernes, 5 de febrero de 2021'
+ * ```
+ *
+ * @example
+ * ```ts
+ * getFullDateString('2021-02-05', 'en')
+ * //=> 'Friday, February 5, 2021'
+ * ```
+ */
 export const getFullDateString = (date, locale) => {
     const sDateValue = sDate(date);
     const utcDate = getDateAsUTCDateMini(sDateValue);
@@ -85,6 +204,34 @@ export const getFullDateString = (date, locale) => {
         dateStyle: 'full',
     });
 };
+/**
+ * Get the short string representation of the given date in the given locale.
+ *
+ * @param date The date to get the short string representation for. It can be an
+ * SDate or a string in the YYYY-MM-DD format.
+ * @param timeZone The time zone used to determine if in the current year. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ * @param locale The locale to use for the string representation.
+ * @param options The options to customize the short string representation.
+ *
+ * @example
+ * ```ts
+ * getShortDateString('2021-02-05', TestLocalTimeZone, 'en', {
+ *   onTodayText,
+ *   includeWeekday: false,
+ * }),
+ * //=> 'Feb 5' (year is not shown when in the current year)
+ * ```
+ *
+ * @example
+ * ```ts
+ * getShortDateString('2021-02-05', TestLocalTimeZone, 'es', {
+ *   onTodayText,
+ *   includeWeekday: true,
+ * })
+ * //=> 'vie, 5 feb 21' (year when not in current year)
+ * ```
+ */
 export const getShortDateString = (date, timeZone, locale, options) => {
     const sDateValue = sDate(date);
     if (isDateToday(sDateValue, timeZone)) {
@@ -96,71 +243,207 @@ export const getShortDateString = (date, timeZone, locale, options) => {
         month: 'short',
         day: 'numeric',
         weekday: options.includeWeekday ? 'short' : undefined,
+        // Include year only if not current
         year: isDateInCurrentYear(sDateValue, timeZone) ? undefined : '2-digit',
     });
 };
+/**
+ * --- Operations ---
+ */
+/**
+ * Returns a new SDates instance with the date resulting from adding the given
+ * number of days to the given date. Because it adds calendar days rather than
+ * 24-hour days, this operation is not affected by time zones.
+ *
+ * @param date The date to add days to. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param days The number of days to add to the date.
+ */
 export const addDaysToDate = (date, days) => {
     const sDateValue = sDate(date);
     const nativeDate = getDateAsUTCDateMini(sDateValue);
     nativeDate.setDate(nativeDate.getDate() + days);
     return sDate(getISODateFromZonedDate(nativeDate));
 };
+/**
+ * Returns a new SDate instance with the date resulting from adding the given
+ * number of months to the given date. Because it just adds to the month
+ * component of the date, this operation is not affected by time zones.
+ *
+ * @param date The date to add months to. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param months The number of months to add to the date.
+ */
 export const addMonthsToDate = (date, months) => {
     const sDateValue = sDate(date);
     const nativeDate = getDateAsUTCDateMini(sDateValue);
     nativeDate.setMonth(nativeDate.getMonth() + months);
     return sDate(getISODateFromZonedDate(nativeDate));
 };
+/**
+ * Returns a new SDate instance with the date resulting from adding the given
+ * number of years to the given date. Because this only adds to the year
+ * component of the date, this method is not affected by leap years.
+ *
+ * @param date The date to add years to. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param years The number of years to add to the date.
+ */
 export const addYearsToDate = (date, years) => {
     const sDateValue = sDate(date);
     const nativeDate = getDateAsUTCDateMini(sDateValue);
     nativeDate.setFullYear(nativeDate.getFullYear() + years);
     return sDate(getISODateFromZonedDate(nativeDate));
 };
+/**
+ * --- Comparisons ---
+ */
+/**
+ * Returns true when the two given dates represent the same day and false
+ * otherwise.
+ *
+ * @param date1 The first date to compare. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param date2 The second date to compare. It can be an SDate or a string in
+ * the YYYY-MM-DD format.
+ */
 export const isSameDate = (date1, date2) => {
     const sDate1 = sDate(date1);
     const sDate2 = sDate(date2);
     return sDate1.date === sDate2.date;
 };
+/**
+ * Returns true when the first date represents a date before the second date and
+ * false otherwise.
+ *
+ * @param date1 The first date to compare. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param date2 The second date to compare. It can be an SDate or a string in
+ * the YYYY-MM-DD format.
+ */
 export const isBeforeDate = (date1, date2) => {
     const sDate1 = sDate(date1);
     const sDate2 = sDate(date2);
     return sDate1.date < sDate2.date;
 };
+/**
+ * Returns true when the first date represents a date that happens on the same
+ * date or before the second date and false otherwise.
+ *
+ * @param date1 The first date to compare. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param date2 The second date to compare. It can be an SDate or a string in the
+ * the YYYY-MM-DD format.
+ */
 export const isSameDateOrBefore = (date1, date2) => {
     const sDate1 = sDate(date1);
     const sDate2 = sDate(date2);
     return sDate1.date <= sDate2.date;
 };
+/**
+ * Returns true when the first date represents a date that happens after the
+ * second date and false otherwise.
+ *
+ * @param date1 The first date to compare. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param date2 The second date to compare. It can be an SDate or a string in the
+ * the YYYY-MM-DD format.
+ */
 export const isAfterDate = (date1, date2) => {
     const sDate1 = sDate(date1);
     const sDate2 = sDate(date2);
     return sDate1.date > sDate2.date;
 };
+/**
+ * Returns true when the first date represents a date that happens on the same
+ * date or after the second date and false otherwise.
+ *
+ * @param date1 The first date to compare. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param date2 The second date to compare. It can be an SDate or a string in the
+ * the YYYY-MM-DD format.
+ */
 export const isSameDateOrAfter = (date1, date2) => {
     const sDate1 = sDate(date1);
     const sDate2 = sDate(date2);
     return sDate1.date >= sDate2.date;
 };
+/**
+ * Returns true when the date is today and false otherwise.
+ *
+ * @param date The date to check if it is today. It can be an SDate or a string
+ * in the YYYY-MM-DD format.
+ * @param timeZone The time zone to check if the date is today. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export const isDateToday = (date, timeZone) => {
     const sDateValue = sDate(date);
     return isSameDate(sDateValue, getDateToday(timeZone));
 };
+/**
+ * Returns true when the month on the first date is the same as the month on the
+ * second date. It also checks that the year is the same. Returns false
+ * otherwise.
+ *
+ * @param date1 The first date to compare. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param date2 The second date to compare. It can be an SDate or a string in
+ * the YYYY-MM-DD format.
+ *
+ * @example
+ * ```ts
+ * areDatesInSameMonth('2021-02-05', '2021-02-15')
+ * //=> true
+ * ```
+ *
+ * @example
+ * ```ts
+ * areDatesInSameMonth('2022-02-05', '2023-02-15')
+ * //=> false (different years)
+ * ```
+ */
 export const areDatesInSameMonth = (date1, date2) => {
     const sDate1 = sDate(date1);
     const sDate2 = sDate(date2);
     return (getISOYearFromISODate(sDate1.date) === getISOYearFromISODate(sDate2.date) &&
         getISOMonthFromISODate(sDate1.date) === getISOMonthFromISODate(sDate2.date));
 };
+/**
+ * Returns true when the date represents a date in the current month and year.
+ * Returns false otherwise.
+ *
+ * @param date The date to check if it is in the current month. It can be an
+ * SDate or a string in the YYYY-MM-DD format.
+ * @param timeZone The time zone to check if the date is in the current month.
+ * See `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export const isDateInCurrentMonth = (date, timeZone) => {
     const sDateValue = sDate(date);
     return areDatesInSameMonth(sDateValue, getDateToday(timeZone));
 };
+/**
+ * Returns true when the year of the first date is the same as the year on the
+ * second date. Returns false otherwise.
+ *
+ * @param date1 The first date to compare. It can be an SDate or a string in the
+ * YYYY-MM-DD format.
+ * @param date2 The second date to compare. It can be an SDate or a string in
+ * the YYYY-MM-DD format.
+ */
 export const areDatesInSameYear = (date1, date2) => {
     const sDate1 = sDate(date1);
     const sDate2 = sDate(date2);
     return (getISOYearFromISODate(sDate1.date) === getISOYearFromISODate(sDate2.date));
 };
+/**
+ * Returns true when the year component of the date matches the current year in
+ * the given time zone. Returns false otherwise.
+ *
+ * @param date The date to check if it is in the current year. It can be an
+ * SDate or a string in the YYYY-MM-DD format.
+ * @param timeZone The time zone to check if the date is in the current year.
+ * See `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export const isDateInCurrentYear = (date, timeZone) => {
     const sDateValue = sDate(date);
     return areDatesInSameYear(sDateValue, getDateToday(timeZone));

package/dist/sTime.d.ts

@@ -1,18 +1,149 @@
 import { STime } from './internal/STime.js';
+/**
+ * --- Factory ---
+ */
+/**
+ * Returns a new STime instance.
+ *
+ * @param time And instance of STime or a string in the format 'HH:MM'.
+ */
 export declare const sTime: (time: string | STime) => STime;
+/**
+ * --- Factory helpers ---
+ */
+/**
+ * Returns a new STime instance with the current time in the given time zone.
+ *
+ * @param timeZone The time zone to get the current time in. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export declare const getTimeNow: (timeZone: string) => STime;
+/**
+ * Returns a new STime instance with the time at midnight (00:00).
+ */
 export declare const getTimeAtMidnight: () => STime;
+/**
+ * Returns a new STime instance with the time resulting from adding the given
+ * number of minutes to midnight (00:00).
+ *
+ * @param timeInMinutes The number of minutes to add to midnight.
+ */
 export declare const getTimeFromMinutes: (timeInMinutes: number) => STime;
+/**
+ * --- Getters ---
+ */
+/**
+ * Returns the hours from the given time.
+ *
+ * @param time The time to get the hours from. It can be an STime or a string
+ * in the HH:MM format.
+ */
 export declare const getHoursFromTime: (time: string | STime) => number;
+/**
+ * Returns the hours from given time as a string (1 - 12).
+ *
+ * @param time The time to get the hours from. It can be an STime or a string
+ * in the HH:MM format.
+ */
 export declare const get12HoursHoursStringFromTime: (time: string | STime) => string;
+/**
+ * Returns the minutes from the given time.
+ *
+ * @param time The time to get the minutes from. It can be an STime or a string
+ * in the HH:MM format.
+ */
 export declare const getMinutesFromTime: (time: string | STime) => number;
+/**
+ * Returns the minutes from given time as a string (00-59).
+ *
+ * @param time The time to get the minutes from. It can be an STime or a string
+ * in the HH:MM format.
+ */
 export declare const getMinutesStringFromTime: (time: string | STime) => string;
+/**
+ * Returns a string that represents the time in a 12-hour format (HH:MM AM/PM).
+ *
+ * @param time The time to get the string from. It can be an STime or a string
+ * in the HH:MM format.
+ */
 export declare const get12HourTimeString: (time: string | STime) => string;
+/**
+ * Returns the time converted to minutes since midnight.
+ *
+ * @param time The time to get the minutes from. It can be an STime or a string
+ * in the HH:MM format.
+ */
 export declare const getTimeInMinutes: (time: string | STime, midnightIs24?: boolean) => number;
+/**
+ * --- Operations ---
+ */
+/**
+ * Returns a new STime instance with the time resulting from adding the given
+ * number of minutes to the given time. The time will wrap around a 24 hour
+ * clock.
+ *
+ * @param time The time to add the minutes to. It can be an STime or a string
+ * in the HH:MM format.
+ * @param minutes The number of minutes to add.
+ */
 export declare const addMinutesToTime: (time: string | STime, minutes: number) => STime;
+/**
+ * --- Comparisons ---
+ */
+/**
+ * Returns true when the two times are the same and false otherwise.
+ *
+ * @param time1 The first time to compare. It can be an STime or a string in the
+ * HH:MM format.
+ * @param time2 The second time to compare. It can be an STime or a string in
+ * the HH:MM format.
+ */
 export declare const isSameTime: (time1: string | STime, time2: string | STime) => boolean;
+/**
+ * Returns true when first time represents a time that happens after the second
+ * time. Returns false otherwise.
+ *
+ * @param time1 The first time to compare. It can be an STime or a string in the
+ * HH:MM format.
+ * @param time2 The second time to compare. It can be an STime or a string in
+ * the HH:MM format.
+ */
 export declare const isAfterTime: (time1: string | STime, time2: string | STime) => boolean;
+/**
+ * Returns true when first time represents a time that happens after or at the
+ * same time as the second time. Returns false otherwise.
+ *
+ * @param time1 The first time to compare. It can be an STime or a string in the
+ * HH:MM format.
+ * @param time2 The second time to compare. It can be an STime or a string in
+ * the HH:MM format.
+ */
 export declare const isSameTimeOrAfter: (time1: string | STime, time2: string | STime) => boolean;
+/**
+ * Returns true when first time represents a time that happens before the
+ * second time. Returns false otherwise.
+ *
+ * @param time1 The first time to compare. It can be an STime or a string in the
+ * HH:MM format.
+ * @param time2 The second time to compare. It can be an STime or a string in
+ * the HH:MM format.
+ */
 export declare const isBeforeTime: (time1: string | STime, time2: string | STime) => boolean;
+/**
+ * Returns true when first time represents a time that happens before or at the
+ * same time as the second time. Returns false otherwise.
+ *
+ * @param time1 The first time to compare. It can be an STime or a string in the
+ * HH:MM format.
+ * @param time2 The second time to compare. It can be an STime or a string in
+ * the HH:MM format.
+ */
 export declare const isSameTimeOrBefore: (time1: string | STime, time2: string | STime) => boolean;
+/**
+ * Returns true when the given time is at or after noon (12:00) and false
+ * otherwise.
+ *
+ * @param time The time to check. It can be an STime or a string in the HH:MM
+ * format.
+ */
 export declare const isTimePM: (time: string | STime) => boolean;