scdate 0.2.4 → 0.2.6

package/dist/sTimestamp.js

@@ -4,43 +4,187 @@ import { getISODateFromISOTimestamp, getISOTimeFromISOTimestamp, getISOTimestamp
 import { getMillisecondsInUTCFromTimestamp, getTimeZonedDate, } from './internal/zoned.js';
 import { getShortDateString, sDate } from './sDate.js';
 import { get12HourTimeString, sTime } from './sTime.js';
+/**
+ * --- Factory ---
+ */
+/**
+ * Returns a new STimestamp instance.
+ *
+ * @param timestamp An instance of STimestamp or a string in the
+ * YYYY-MM-DDTHH:MM format.
+ */
 export const sTimestamp = (timestamp) => {
     if (timestamp instanceof STimestamp) {
         return timestamp;
     }
     return new STimestamp(timestamp);
 };
+/**
+ * --- Factory helpers ---
+ */
+/**
+ * Returns a new STimestamp instance set to the date and time that results from
+ * converting the given number of milliseconds since the Unix epoch to the given
+ * time zone.
+ *
+ * @param utcDateInMilliseconds The number of milliseconds since the Unix epoch.
+ * @param timeZone The time zone to use when creating the timestamp. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export const getTimestampFromUTCMilliseconds = (utcDateInMilliseconds, timeZone) => {
     const date = getTimeZonedDate(utcDateInMilliseconds, timeZone);
     return sTimestamp(getISOTimestampFromZonedDate(date));
 };
+/**
+ * Returns a new STimestamp instance set to the current date and time in the
+ * given time zone.
+ *
+ * @param timeZone The time zone to use when creating the timestamp. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export const getTimestampNow = (timeZone) => {
     return getTimestampFromUTCMilliseconds(Date.now(), timeZone);
 };
+/**
+ * Returns a new STimestamp instance set to the date and time that results from
+ * combining the given date and time.
+ *
+ * @param date The date to use when creating the timestamp. It can be an SDate
+ * or a string in the YYYY-MM-DD format.
+ * @param time The time to use when creating the timestamp. It can be an STime
+ * or a string in the HH:MM format.
+ */
 export const getTimestampFromDateAndTime = (date, time) => {
     const sDateValue = sDate(date);
     const sDimeValue = sTime(time);
     return sTimestamp(`${sDateValue.date}T${sDimeValue.time}`);
 };
+/**
+ * --- Getters ---
+ */
+/**
+ * Returns a native Date adjusted so that the local time of that date matches
+ * the local timestamp 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 getTimeZonedDateFromTimestamp = (timestamp, timeZone) => {
     const sTimestampValue = sTimestamp(timestamp);
     const dateInUTCMilliseconds = getMillisecondsInUTCFromTimestamp(sTimestampValue, timeZone);
     return getTimeZonedDate(dateInUTCMilliseconds, timeZone);
 };
+/**
+ * Returns the number of seconds from now to the given timestamp. If the
+ * timestamp is in the future, the number of seconds will be positive. If the
+ * timestamp is in the past, the number of seconds will be negative.
+ *
+ * Daylight Saving Notes:
+ *
+ * The following notes use `America/New_York` as the time zone to explain how
+ * Daylight Savings is handled, but it works the same across time zones on their
+ * respective Daylight Saving schedules as defined by Intl API.
+ *
+ * Notice that when looking at a watch (that adjusts for Daylight Saving
+ * automatically) on 2024-03-10 (the day Daylight Savings goes into effect and
+ * the time moves forward one hour) the times between 02:00 and 02:59 never
+ * happen as the watch goes from 01:59 to 03:00. In the case of 2024-11-03 (the
+ * day the time zone goes back to Standard Time), the times between 01:00 and
+ * 01:59 happen twice as the first time the watch hits 02:00 it goes back to
+ * 01:00.
+ *
+ * To account for time zone changes, this method converts the timestamp to UTC
+ * milliseconds (for both the current time and the expected timestamp) before
+ * calculating the difference in seconds. This works as expected for all times,
+ * but the expectation for the transition times (those that don't happen on a
+ * watch that automatically adjusts or that happen twice) it can work in
+ * unexpected ways.
+ *
+ * For example, trying to calculate the number of seconds to 2024-03-10T02:00
+ * (the start of Daylight Saving Time) at 2024-03-10T01:59 (still in Standard
+ * Time) will result in -3540 seconds (59 minutes in the past). A similar
+ * situation happens when the time zone transitions from Daylight Saving Time to
+ * Standard Time as can be derived from the table below.
+ *
+ * In 'America/New_York'
+ *
+ * Transition to Eastern Daylight Time (EDT) in 2024
+ * | Time Zone        | T1                    | T2                     | T3                    |
+ * |------------------|-----------------------|------------------------|-----------------------|
+ * | America/New_York | 2024-03-10T01:59(EST) | 2024-03-10T02:00(EDT)  | 2024-03-10T03:00(EST) |
+ * | UTC              | 2024-03-10T06:59      | 2024-03-10T06:00       | 2024-03-10T07:00      |
+ *
+ * Transition to Eastern Standard Time (EST) in 2024
+ * | Time Zone        | T1                    | T2                     | T3                    |
+ * |------------------|-----------------------|------------------------|-----------------------|
+ * | America/New_York | 2024-11-03T01:59(EDT) | 2024-11-03T02:00(EST)  | 2024-11-03T03:00(EST) |
+ * | UTC              | 2024-11-03T05:59      | 2024-11-03T07:00       | 2024-11-03T08:00      |
+ *
+ * @param timestamp The timestamp to get the seconds to. It can be an STimestamp
+ * or a string in the YYYY-MM-DDTHH:MM format.
+ * @param timeZone The time zone to use when creating the timestamp. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export const getSecondsToTimestamp = (timestamp, timeZone) => {
     const sTimestampValue = sTimestamp(timestamp);
     const millisecondsNow = Date.now();
     const millisecondsAtTimestamp = getMillisecondsInUTCFromTimestamp(sTimestampValue, timeZone);
     return Math.floor((millisecondsAtTimestamp - millisecondsNow) / MillisecondsInSecond);
 };
+/**
+ * Returns a new SDate instance set to the date part of the given timestamp.
+ *
+ * @param timestamp The timestamp to get the date from. It can be an STimestamp
+ * or a string in the YYYY-MM-DDTHH:MM format.
+ */
 export const getDateFromTimestamp = (timestamp) => {
     const sTimestampValue = sTimestamp(timestamp);
     return sDate(getISODateFromISOTimestamp(sTimestampValue.timestamp));
 };
+/**
+ * Returns a new STime instance set to the time part of the given timestamp.
+ *
+ * @param timestamp The timestamp to get the time from. It can be an STimestamp
+ * or a string in the YYYY-MM-DDTHH:MM format.
+ */
 export const getTimeFromTimestamp = (timestamp) => {
     const sTimestampValue = sTimestamp(timestamp);
     return sTime(getISOTimeFromISOTimestamp(sTimestampValue.timestamp));
 };
+/**
+ * Returns a string representation that includes a minimum set of components
+ * from the given timestamp. This is a combination of the the results of
+ * the `getShortDateString` method, and `get12HourTimeString`.
+ *
+ * @param timestamp The timestamp to get the short string from. It can be an
+ * STimestamp or a string in the YYYY-MM-DDTHH:MM format.
+ * @param timeZone The time zone to use when creating the short string. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ * @param locale The locale to use for the string representation.
+ * @param options An object with options for the short string representation.
+ *
+ * @example
+ * ```ts
+ * // Example when the timestamp is today
+ * getShortTimestampString('2021-08-10T08:00', 'America/Puerto_Rico', 'en', {
+ *   includeWeekday: true,
+ *   onTodayAtText: () => 'Today at',
+ * })
+ * //=> 'Today at 8:00 AM'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example when the timestamp is not today
+ * getShortTimestampString('2022-09-11T08:00', 'America/Puerto_Rico', 'es', {
+ *   includeWeekday: true,
+ *   onTodayAtText: () => 'Hoy a las',
+ * })
+ * //=> 'dom, 11 sept 22 8:00 AM'
+ * ```
+ */
 export const getShortTimestampString = (timestamp, timeZone, locale, options) => {
     const sTimestampValue = sTimestamp(timestamp);
     const date = getDateFromTimestamp(sTimestampValue);
@@ -52,12 +196,86 @@ export const getShortTimestampString = (timestamp, timeZone, locale, options) =>
     const timeText = get12HourTimeString(time);
     return `${dateText} ${timeText}`;
 };
+/**
+ * --- Operations ---
+ */
+/**
+ * Returns a new STimestamp instance resulting from adding the given number of
+ * calendar days to the given timestamp. Because it adds calendar days rather
+ * than 24-hour days, this operation is not affected by time zones.
+ *
+ * @param timestamp The timestamp to add days to. It can be an STimestamp or a
+ * string in the YYYY-MM-DDTHH:MM format.
+ * @param days The number of days to add to the timestamp.
+ */
 export const addDaysToTimestamp = (timestamp, days) => {
     const sTimestampValue = sTimestamp(timestamp);
     const nativeDate = getTimestampAsUTCDateMini(sTimestampValue);
     nativeDate.setDate(nativeDate.getDate() + days);
     return sTimestamp(getISOTimestampFromZonedDate(nativeDate));
 };
+/**
+ * Returns a new STimestamp instance resulting from adding the given number of
+ * minutes to the given timestamp.
+ *
+ * Daylight Saving Time Notes:
+ *
+ * The following notes use `America/New_York` as the time zone to explain how
+ * Daylight Savings is handled, but it works the same across time zones on their
+ * respective Daylight Saving schedules as defined by Intl API.
+ *
+ * Notice that when looking at a watch (that adjusts for Daylight Saving
+ * automatically) on 2024-03-10 (the day Daylight Savings goes into effect and
+ * the time moves forward one hour) the times between 02:00 and 02:59 never
+ * happen as the watch goes from 01:59 to 03:00. In the case of 2024-11-03 (the
+ * day the time zone goes back to Standard Time), the times between 01:00 and
+ * 01:59 happen twice as the first time the watch hits 02:00 it goes back to
+ * 01:00.
+ *
+ * To account for time zone changes, this method converts the timestamp to UTC
+ * milliseconds before adding the specified minutes. This works as expected for
+ * all times, but the expectation for the transition times (those that don't
+ * happen on a watch that automatically adjusts or that happen twice) it can
+ * work in unexpected ways.
+ *
+ * Time is converted from the given time zone to
+ * UTC before the minutes are added, and then converted back to the specified
+ * time zone. This results in the resulting time being adjusted for daylight saving time
+ * changes. (e.g. Adding 60 minutes to 2024-03-10T01:59 in America/New_York will
+ * result in 2024-03-10T03:59 as time move forward one hour for daylight saving
+ * time at 2024-03-10T02:00.)
+ *
+ * For example, adding one minute to 2024-03-10T01:59 will result in
+ * 2024-03-10T03:00 as expected. However, trying to add one minute to
+ * 2024-03-10T02:00 (a time that technically does not exist on a watch that
+ * automatically adjusts for Daylight Saving) will result in 2024-03-10T01:01.
+ * This is because 2024-03-10T02:00 is converted to 2024-03-10T06:00 UTC (due
+ * to timezone offset being -4 starting from 02:00 local time) and one minute
+ * later would be 2024-03-10T06:01 UTC  which would be 2024-03-10T01:01 in
+ * `America/New_York`. A similar situation happens when the time zone
+ * transitions from Daylight Saving Time to Standard Time as can be derived from
+ * the table below.
+ *
+ * In 'America/New_York'
+ *
+ * Transition to Eastern Daylight Time (EDT) in 2024
+ * | Time Zone        | T1                    | T2                     | T3                    |
+ * |------------------|-----------------------|------------------------|-----------------------|
+ * | America/New_York | 2024-03-10T01:59(EST) | 2024-03-10T02:00(EDT)  | 2024-03-10T03:00(EST) |
+ * | UTC              | 2024-03-10T06:59      | 2024-03-10T06:00       | 2024-03-10T07:00      |
+ *
+ * Transition to Eastern Standard Time (EST) in 2024
+ * | Time Zone        | T1                    | T2                     | T3                    |
+ * |------------------|-----------------------|------------------------|-----------------------|
+ * | America/New_York | 2024-11-03T01:59(EDT) | 2024-11-03T02:00(EST)  | 2024-11-03T03:00(EST) |
+ * | UTC              | 2024-11-03T05:59      | 2024-11-03T07:00       | 2024-11-03T08:00      |
+ *
+ * @param timestamp The timestamp to add minutes to. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ * @param minutes The number of minutes to add to the timestamp.
+ * @param timeZone The time zone to use when creating the timestamp. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
 export const addMinutesToTimestamp = (timestamp, minutes, timeZone) => {
     const sTimestampValue = sTimestamp(timestamp);
     const newMillisecondsInUTC = getMillisecondsInUTCFromTimestamp(sTimestampValue, timeZone) +
@@ -65,26 +283,74 @@ export const addMinutesToTimestamp = (timestamp, minutes, timeZone) => {
     const newTimestamp = getTimestampFromUTCMilliseconds(newMillisecondsInUTC, timeZone);
     return newTimestamp;
 };
+/**
+ * --- Comparisons ---
+ */
+/**
+ * Returns true if the two timestamps represent the same date and time. Returns
+ * false otherwise.
+ *
+ * @param timestamp1 The first timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ * @param timestamp2 The second timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ */
 export const isSameTimestamp = (timestamp1, timestamp2) => {
     const sTimestamp1 = sTimestamp(timestamp1);
     const sTimestamp2 = sTimestamp(timestamp2);
     return sTimestamp1.timestamp === sTimestamp2.timestamp;
 };
+/**
+ * Returns true if the first timestamp represents a date and time that happens
+ * before the second timestamp. Returns false otherwise.
+ *
+ * @param timestamp1 The first timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ * @param timestamp2 The second timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ */
 export const isBeforeTimestamp = (timestamp1, timestamp2) => {
     const sTimestamp1 = sTimestamp(timestamp1);
     const sTimestamp2 = sTimestamp(timestamp2);
     return sTimestamp1.timestamp < sTimestamp2.timestamp;
 };
+/**
+ * Returns true if the first timestamp represents a date and time that happens
+ * on or before the second timestamp. Returns false otherwise.
+ *
+ * @param timestamp1 The first timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ * @param timestamp2 The second timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ */
 export const isSameTimestampOrBefore = (timestamp1, timestamp2) => {
     const sTimestamp1 = sTimestamp(timestamp1);
     const sTimestamp2 = sTimestamp(timestamp2);
     return sTimestamp1.timestamp <= sTimestamp2.timestamp;
 };
+/**
+ * Returns true if the first timestamp represents a date and time that happens
+ * after the second timestamp. Returns false otherwise.
+ *
+ * @param timestamp1 The first timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ * @param timestamp2 The second timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ */
 export const isAfterTimestamp = (timestamp1, timestamp2) => {
     const sTimestamp1 = sTimestamp(timestamp1);
     const sTimestamp2 = sTimestamp(timestamp2);
     return sTimestamp1.timestamp > sTimestamp2.timestamp;
 };
+/**
+ * Returns true if the first timestamp represents a date and time that happens
+ * on or after the second timestamp. Returns false otherwise.
+ *
+ * @param timestamp1 The first timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ * @param timestamp2 The second timestamp to compare. It can be an STimestamp or
+ * a string in the YYYY-MM-DDTHH:MM format.
+ */
 export const isSameTimestampOrAfter = (timestamp1, timestamp2) => {
     const sTimestamp1 = sTimestamp(timestamp1);
     const sTimestamp2 = sTimestamp(timestamp2);

package/dist/sWeekdays.d.ts

@@ -1,12 +1,128 @@
+/**
+ * --- Factory ---
+ */
 import { Weekday } from './constants.js';
 import { SDate } from './internal/SDate.js';
 import { SWeekdays } from './internal/SWeekdays.js';
+/**
+ * Returns a new SWeekdays instance.
+ *
+ * @param weekdays An instance of SWeekdays that will be returned or a string in
+ * the SMTWTFS format. Each character in the string represents a weekday
+ * starting on Sunday and ending on Saturday using the first letter of the
+ * English word for the week day. If the weekday is excluded, the position is
+ * filled with a '-' character.
+ *
+ * @example
+ * ```ts
+ * sWeekdays('SM----S')
+ * // Returns an instance of SWeekdays with the weekdays Sunday, Monday, and
+ * // Saturday included while the rest are excluded.
+ * ```
+ *
+ * @example
+ * ```ts
+ * sWeekdays('SMTWTFS')
+ * // Returns an instance of SWeekdays with all weekdays included.
+ * ```
+ */
 export declare const sWeekdays: (weekdays: string | SWeekdays) => SWeekdays;
+/**
+ * --- Factory helpers ---
+ */
+/**
+ * Returns a new SWeekdays instance with all provided weekdays included. The
+ * provided weekdays can be any combination of the Weekday enum values.
+ *
+ * @param weekdays A combination of the Weekday enum values.
+ *
+ * @example
+ * ```ts
+ * getWeekdaysFromWeekdayFlags(Weekday.Monday | Weekday.Wednesday | Weekday.Friday)
+ * // Returns an instance of SWeekdays with the weekdays Monday, Wednesday, and
+ * // Friday included while the rest are excluded.
+ * ```
+ *
+ * @example
+ * ```ts
+ * getWeekdaysFromWeekdayFlags(Weekday.Tuesday)
+ * // Returns an instance of SWeekdays with the weekday Tuesday included while
+ * // the rest are excluded.
+ * ```
+ */
 export declare const getWeekdaysFromWeekdayFlags: (weekdays: Weekday) => SWeekdays;
+/**
+ * Returns a new SWeekdays instance with all weekdays included.
+ */
 export declare const getWeekdaysWithAllIncluded: () => SWeekdays;
+/**
+ * Returns a new SWeekdays instance with no weekdays included.
+ */
 export declare const getWeekdaysWithNoneIncluded: () => SWeekdays;
+/**
+ * --- Operations ---
+ */
+/**
+ * Returns a new SWeekdays instance with the weekdays shifted forward by one
+ * day.
+ *
+ * @param weekdays The weekdays to shift forward. It can be an SWeekdays or a
+ * string in the SMTWTFS format.
+ *
+ * @example
+ * ```ts
+ * shiftWeekdaysForward('SM----S')
+ * // Returns an instance of SWeekdays with the weekdays shifted forward by one
+ * // day. 'SM----S' becomes 'SMT----'.
+ * ```
+ */
 export declare const shiftWeekdaysForward: (weekdays: string | SWeekdays) => SWeekdays;
+/**
+ * Returns a new SWeekdays instance where only the weekdays that are within the
+ * provided date range are included.
+ *
+ * @param weekdays The weekdays to filter. It can be an SWeekdays or a string in
+ * the SMTWTFS format.
+ * @param fromDate The start date of the range. It can be an SDate or a string
+ * in the YYYY-MM-DD format.
+ * @param toDate The end date of the range. It can be an SDate or a string in
+ * the YYYY-MM-DD format.
+ *
+ * @example
+ * ```ts
+ * filterWeekdaysForDates('SMTWTFS', '2020-03-05', '2020-03-05')
+ * // Returns an instance of SWeekdays with only Thursday included.
+ * ```
+ */
 export declare const filterWeekdaysForDates: (weekdays: string | SWeekdays, fromDate: string | SDate, toDate: string | SDate) => SWeekdays;
+/**
+ * Returns a new SWeekdays instance with the provided weekday added to the
+ * current set of weekdays.
+ *
+ * @param weekdays The weekdays to add the weekday to. It can be an SWeekdays or
+ * a string in the SMTWTFS format.
+ * @param weekdayToAdd The weekday to add.
+ */
 export declare const addWeekdayToWeekdays: (weekdays: string | SWeekdays, weekdayToAdd: Weekday) => SWeekdays;
+/**
+ * --- Comparisons ---
+ */
+/**
+ * Returns true if the provided weekdays include the provided weekday. Returns
+ * false otherwise.
+ *
+ * @param weekdays The weekdays to check. It can be an SWeekdays or a string in
+ * the SMTWTFS format.
+ * @param weekday The weekday to check.
+ */
 export declare const doesWeekdaysIncludeWeekday: (weekdays: string | SWeekdays, weekday: Weekday) => boolean;
+/**
+ * Returns true if any of the included weekdays in weekdays1 is also included in
+ * weekdays2. Returns false otherwise.
+ *
+ * @param weekdays1 The first set of weekdays to compare. It can be an SWeekdays
+ * or a string in the SMTWTFS format.
+ * @param weekdays2 The second set of weekdays to compare. It can be an
+ * SWeekdays or a string in the SMTWTFS format.
+ */
 export declare const doesWeekdaysHaveOverlapWithWeekdays: (weekdays1: string | SWeekdays, weekdays2: string | SWeekdays) => boolean;

package/dist/sWeekdays.js

@@ -1,3 +1,6 @@
+/**
+ * --- Factory ---
+ */
 import { SWeekdays } from './internal/SWeekdays.js';
 import { DayToWeekday, DaysInWeek } from './internal/constants.js';
 import { getAtIndex, hasFlag } from './internal/utils.js';
@@ -7,12 +10,57 @@ const AllWeekdaysIncludedMask = 'SMTWTFS';
 const NotIncludedDay = '-';
 const NoWeekdaysIncluded = NotIncludedDay.repeat(AllWeekdaysIncludedMask.length);
 const WeekdaysCount = AllWeekdaysIncludedMask.length;
+/**
+ * Returns a new SWeekdays instance.
+ *
+ * @param weekdays An instance of SWeekdays that will be returned or a string in
+ * the SMTWTFS format. Each character in the string represents a weekday
+ * starting on Sunday and ending on Saturday using the first letter of the
+ * English word for the week day. If the weekday is excluded, the position is
+ * filled with a '-' character.
+ *
+ * @example
+ * ```ts
+ * sWeekdays('SM----S')
+ * // Returns an instance of SWeekdays with the weekdays Sunday, Monday, and
+ * // Saturday included while the rest are excluded.
+ * ```
+ *
+ * @example
+ * ```ts
+ * sWeekdays('SMTWTFS')
+ * // Returns an instance of SWeekdays with all weekdays included.
+ * ```
+ */
 export const sWeekdays = (weekdays) => {
     if (weekdays instanceof SWeekdays) {
         return weekdays;
     }
     return new SWeekdays(weekdays);
 };
+/**
+ * --- Factory helpers ---
+ */
+/**
+ * Returns a new SWeekdays instance with all provided weekdays included. The
+ * provided weekdays can be any combination of the Weekday enum values.
+ *
+ * @param weekdays A combination of the Weekday enum values.
+ *
+ * @example
+ * ```ts
+ * getWeekdaysFromWeekdayFlags(Weekday.Monday | Weekday.Wednesday | Weekday.Friday)
+ * // Returns an instance of SWeekdays with the weekdays Monday, Wednesday, and
+ * // Friday included while the rest are excluded.
+ * ```
+ *
+ * @example
+ * ```ts
+ * getWeekdaysFromWeekdayFlags(Weekday.Tuesday)
+ * // Returns an instance of SWeekdays with the weekday Tuesday included while
+ * // the rest are excluded.
+ * ```
+ */
 export const getWeekdaysFromWeekdayFlags = (weekdays) => {
     const newWeekdays = [...AllWeekdaysIncludedMask];
     for (let i = 0; i < DayToWeekday.length; i++) {
@@ -23,12 +71,35 @@ export const getWeekdaysFromWeekdayFlags = (weekdays) => {
     }
     return sWeekdays(newWeekdays.join(''));
 };
+/**
+ * Returns a new SWeekdays instance with all weekdays included.
+ */
 export const getWeekdaysWithAllIncluded = () => {
     return sWeekdays(AllWeekdaysIncludedMask);
 };
+/**
+ * Returns a new SWeekdays instance with no weekdays included.
+ */
 export const getWeekdaysWithNoneIncluded = () => {
     return sWeekdays(NoWeekdaysIncluded);
 };
+/**
+ * --- Operations ---
+ */
+/**
+ * Returns a new SWeekdays instance with the weekdays shifted forward by one
+ * day.
+ *
+ * @param weekdays The weekdays to shift forward. It can be an SWeekdays or a
+ * string in the SMTWTFS format.
+ *
+ * @example
+ * ```ts
+ * shiftWeekdaysForward('SM----S')
+ * // Returns an instance of SWeekdays with the weekdays shifted forward by one
+ * // day. 'SM----S' becomes 'SMT----'.
+ * ```
+ */
 export const shiftWeekdaysForward = (weekdays) => {
     const sWeekdaysInstance = sWeekdays(weekdays);
     const after = [...NoWeekdaysIncluded];
@@ -42,6 +113,23 @@ export const shiftWeekdaysForward = (weekdays) => {
     }
     return sWeekdays(after.join(''));
 };
+/**
+ * Returns a new SWeekdays instance where only the weekdays that are within the
+ * provided date range are included.
+ *
+ * @param weekdays The weekdays to filter. It can be an SWeekdays or a string in
+ * the SMTWTFS format.
+ * @param fromDate The start date of the range. It can be an SDate or a string
+ * in the YYYY-MM-DD format.
+ * @param toDate The end date of the range. It can be an SDate or a string in
+ * the YYYY-MM-DD format.
+ *
+ * @example
+ * ```ts
+ * filterWeekdaysForDates('SMTWTFS', '2020-03-05', '2020-03-05')
+ * // Returns an instance of SWeekdays with only Thursday included.
+ * ```
+ */
 export const filterWeekdaysForDates = (weekdays, fromDate, toDate) => {
     const sWeekdaysInstance = sWeekdays(weekdays);
     const sFromDate = sDate(fromDate);
@@ -50,9 +138,11 @@ export const filterWeekdaysForDates = (weekdays, fromDate, toDate) => {
         throw new Error('The from date must be before the to date.');
     }
     const diff = getDaysBetweenDates(sFromDate, sToDate);
+    // All selected weekdays are already included
     if (diff >= DaysInWeek) {
         return sWeekdaysInstance;
     }
+    // Less than a week only include the applicable days
     let result = getWeekdaysWithNoneIncluded();
     const DayAfterDelta = 1;
     for (let date = fromDate; isSameDateOrBefore(date, toDate); date = addDaysToDate(date, DayAfterDelta)) {
@@ -63,6 +153,14 @@ export const filterWeekdaysForDates = (weekdays, fromDate, toDate) => {
     }
     return result;
 };
+/**
+ * Returns a new SWeekdays instance with the provided weekday added to the
+ * current set of weekdays.
+ *
+ * @param weekdays The weekdays to add the weekday to. It can be an SWeekdays or
+ * a string in the SMTWTFS format.
+ * @param weekdayToAdd The weekday to add.
+ */
 export const addWeekdayToWeekdays = (weekdays, weekdayToAdd) => {
     const sWeekdaysInstance = sWeekdays(weekdays);
     const newWeekdays = [...sWeekdaysInstance.weekdays];
@@ -70,11 +168,31 @@ export const addWeekdayToWeekdays = (weekdays, weekdayToAdd) => {
     newWeekdays[weekdayIndex] = getAtIndex(AllWeekdaysIncludedMask, weekdayIndex);
     return sWeekdays(newWeekdays.join(''));
 };
+/**
+ * --- Comparisons ---
+ */
+/**
+ * Returns true if the provided weekdays include the provided weekday. Returns
+ * false otherwise.
+ *
+ * @param weekdays The weekdays to check. It can be an SWeekdays or a string in
+ * the SMTWTFS format.
+ * @param weekday The weekday to check.
+ */
 export const doesWeekdaysIncludeWeekday = (weekdays, weekday) => {
     const sWeekdaysInstance = sWeekdays(weekdays);
     const weekdayIndex = getIndexForWeekday(weekday);
     return getAtIndex(sWeekdaysInstance.weekdays, weekdayIndex) !== NotIncludedDay;
 };
+/**
+ * Returns true if any of the included weekdays in weekdays1 is also included in
+ * weekdays2. Returns false otherwise.
+ *
+ * @param weekdays1 The first set of weekdays to compare. It can be an SWeekdays
+ * or a string in the SMTWTFS format.
+ * @param weekdays2 The second set of weekdays to compare. It can be an
+ * SWeekdays or a string in the SMTWTFS format.
+ */
 export const doesWeekdaysHaveOverlapWithWeekdays = (weekdays1, weekdays2) => {
     const sWeekdays1 = sWeekdays(weekdays1);
     const sWeekdays2 = sWeekdays(weekdays2);