scdate 0.2.4 → 0.2.5

package/dist/internal/SDate.d.ts

@@ -1,3 +1,6 @@
+/**
+ * SDate represents a date in the ISO-8601 format (YYYY-MM-DD)
+ */
 export declare class SDate {
     readonly date: string;
     constructor(isoValue: string);

package/dist/internal/SDate.js

@@ -1,4 +1,7 @@
 import { validateISODate } from './date.js';
+/**
+ * SDate represents a date in the ISO-8601 format (YYYY-MM-DD)
+ */
 export class SDate {
     date;
     constructor(isoValue) {

package/dist/internal/STime.d.ts

@@ -1,3 +1,6 @@
+/**
+ * STime represents a time in the ISO-8601 format (HH:MM)
+ */
 export declare class STime {
     readonly time: string;
     constructor(isoValue: string);

package/dist/internal/STime.js

@@ -1,4 +1,7 @@
 import { validateISOTime } from './time.js';
+/**
+ * STime represents a time in the ISO-8601 format (HH:MM)
+ */
 export class STime {
     time;
     constructor(isoValue) {

package/dist/internal/STimestamp.d.ts

@@ -1,3 +1,6 @@
+/**
+ * STimestamp represents a timestamp in the ISO-8601 format (YYYY-MM-DDTHH:MM)
+ */
 export declare class STimestamp {
     readonly timestamp: string;
     constructor(timestamp: string);

package/dist/internal/STimestamp.js

@@ -1,4 +1,7 @@
 import { validateISOTimestamp } from './timestamp.js';
+/**
+ * STimestamp represents a timestamp in the ISO-8601 format (YYYY-MM-DDTHH:MM)
+ */
 export class STimestamp {
     timestamp;
     constructor(timestamp) {

package/dist/internal/SWeekdays.d.ts

@@ -1,3 +1,10 @@
+/**
+ * SWeekdays represents a string of weekdays in the format 'SMTWTFS' where each
+ * position is represented by a flag indicating if the weekday (starting on
+ * Sunday and ending on Saturday using the first letter of the english word for
+ * the week day) is included or excluded. If excluded, the position is filled
+ * with a '-' character.
+ */
 export declare class SWeekdays {
     readonly weekdays: string;
     constructor(weekdays: string);

package/dist/internal/SWeekdays.js

@@ -1,4 +1,11 @@
 import { validateWeekdays } from './weekdays.js';
+/**
+ * SWeekdays represents a string of weekdays in the format 'SMTWTFS' where each
+ * position is represented by a flag indicating if the weekday (starting on
+ * Sunday and ending on Saturday using the first letter of the english word for
+ * the week day) is included or excluded. If excluded, the position is filled
+ * with a '-' character.
+ */
 export class SWeekdays {
     weekdays;
     constructor(weekdays) {

package/dist/internal/date.js

@@ -25,6 +25,7 @@ export const validateISODate = (isoDate) => {
     const date = Number(getISODateFromISODate(isoDate));
     const nativeDate = new Date();
     nativeDate.setUTCFullYear(year, month, date);
+    // This will result in an error if for example the date uses 32 as the date
     if (nativeDate.getUTCFullYear() !== year ||
         nativeDate.getUTCMonth() !== month ||
         nativeDate.getUTCDate() !== date) {

package/dist/internal/time.js

@@ -19,6 +19,8 @@ export const validateISOTime = (isoTime) => {
     const nativeDate = new Date();
     nativeDate.setUTCHours(hours);
     nativeDate.setUTCMinutes(minutes);
+    // The following will result in an error if for example the date uses a time
+    // outside of 0:00 and 23:59.
     if (nativeDate.getUTCMinutes() !== minutes ||
         nativeDate.getUTCHours() !== hours) {
         throw new Error(`Invalid ISO time value. Expected from 00:00 to 23:59. Current value: '${isoTime}'.`);

package/dist/internal/utils.d.ts

@@ -1,2 +1,6 @@
 export declare const hasFlag: (flags: number, checkFlag: number) => boolean;
+/**
+ * Retrieves the value from the array or string at the defined index or throws
+ * if the value is undefined.
+ */
 export declare const getAtIndex: <T extends string | unknown[]>(arrayOrString: T, index: number) => T[number];

package/dist/internal/utils.js

@@ -1,4 +1,8 @@
 export const hasFlag = (flags, checkFlag) => (flags & checkFlag) === checkFlag;
+/**
+ * Retrieves the value from the array or string at the defined index or throws
+ * if the value is undefined.
+ */
 export const getAtIndex = (arrayOrString, index) => {
     const value = arrayOrString[index];
     if (value === undefined) {

package/dist/internal/zoned.d.ts

@@ -2,4 +2,8 @@ import { SDate } from './SDate.js';
 import { STimestamp } from './STimestamp.js';
 export declare const getMillisecondsInUTCFromTimestamp: (timestamp: STimestamp, timeZone: string) => number;
 export declare const getMillisecondsInUTCFromDate: (date: SDate, timeZone: string) => number;
+/**
+ * @param timeZone For a list of valid time zones run
+ *   `Intl.supportedValuesOf('timeZone')` on your environment.
+ */
 export declare const getTimeZonedDate: (millisecondsInUTC: number, timeZone: string) => Date;

package/dist/internal/zoned.js

@@ -18,6 +18,10 @@ export const getMillisecondsInUTCFromDate = (date, timeZone) => {
     const timeZoneOffset = getValidatedTimeZoneOffset(timeZone, utcDate);
     return utcDate.getTime() - timeZoneOffset;
 };
+/**
+ * @param timeZone For a list of valid time zones run
+ *   `Intl.supportedValuesOf('timeZone')` on your environment.
+ */
 export const getTimeZonedDate = (millisecondsInUTC, timeZone) => {
     if (isNaN(millisecondsInUTC.valueOf())) {
         throw new Error(`Invalid date. Date: '${String(millisecondsInUTC.valueOf())}'`);

package/dist/sDate.d.ts

@@ -4,30 +4,310 @@ export interface SDateShortStringOptions {
     includeWeekday: boolean;
     onTodayText: () => string;
 }
+/**
+ * --- Factory ---
+ */
+/**
+ * Returns a new SDate instance.
+ *
+ * @param date An instance of SDate or a string in the YYYY-MM-DD format.
+ */
 export declare const sDate: (date: string | SDate) => SDate;
+/**
+ * --- 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 declare const getDateToday: (timeZone: string) => SDate;
+/**
+ * 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 declare const getNextDateByWeekday: (date: string | SDate, weekday: Weekday) => SDate;
+/**
+ * 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 declare const getPreviousDateByWeekday: (date: string | SDate, weekday: Weekday) => SDate;
+/**
+ * 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 declare const getDateForFirstDayOfMonth: (date: string | SDate) => SDate;
+/**
+ * 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 declare const getDateForLastDayOfMonth: (date: string | SDate) => SDate;
+/**
+ * --- 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 declare const getYearFromDate: (date: string | SDate) => number;
+/**
+ * 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 declare const getMonthFromDate: (date: string | SDate) => number;
+/**
+ * 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 declare const getDateFromDate: (date: string | SDate) => number;
+/**
+ * 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 declare const getWeekdayFromDate: (date: string | SDate) => number;
+/**
+ * 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 declare const getTimeZonedDateFromDate: (date: string | SDate, timeZone: string) => Date;
+/**
+ * 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 declare const getDaysBetweenDates: (date1: string | SDate, date2: string | SDate) => number;
+/**
+ * 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 declare const getFullDateString: (date: string | SDate, locale: Intl.LocalesArgument) => string;
+/**
+ * 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 declare const getShortDateString: (date: string | SDate, timeZone: string, locale: Intl.LocalesArgument, options: SDateShortStringOptions) => string;
+/**
+ * --- 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 declare const addDaysToDate: (date: string | SDate, days: number) => SDate;
+/**
+ * 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 declare const addMonthsToDate: (date: string | SDate, months: number) => SDate;
+/**
+ * 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 declare const addYearsToDate: (date: string | SDate, years: number) => SDate;
+/**
+ * --- 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 declare const isSameDate: (date1: string | SDate, date2: string | SDate) => boolean;
+/**
+ * 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 declare const isBeforeDate: (date1: string | SDate, date2: string | SDate) => boolean;
+/**
+ * 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 declare const isSameDateOrBefore: (date1: string | SDate, date2: string | SDate) => boolean;
+/**
+ * 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 declare const isAfterDate: (date1: string | SDate, date2: string | SDate) => boolean;
+/**
+ * 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 declare const isSameDateOrAfter: (date1: string | SDate, date2: string | SDate) => boolean;
+/**
+ * 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 declare const isDateToday: (date: string | SDate, timeZone: string) => boolean;
+/**
+ * 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 declare const areDatesInSameMonth: (date1: string | SDate, date2: string | SDate) => boolean;
+/**
+ * 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 declare const isDateInCurrentMonth: (date: string | SDate, timeZone: string) => boolean;
+/**
+ * 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 declare const areDatesInSameYear: (date1: string | SDate, date2: string | SDate) => boolean;
+/**
+ * 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 declare const isDateInCurrentYear: (date: string | SDate, timeZone: string) => boolean;