scdate 1.0.1 → 2.0.0

package/README.md

@@ -1,42 +1,277 @@
 # scDate
 
-**Date and time library for dealing with schedules.**
+**Date and time library for working with schedules**
 
 [![github license](https://img.shields.io/github/license/ericvera/scdate.svg?style=flat-square)](https://github.com/ericvera/scdate/blob/master/LICENSE)
 [![npm version](https://img.shields.io/npm/v/scdate.svg?style=flat-square)](https://npmjs.org/package/scdate)
 
-Features:
+## Overview
 
-- Supports dates, times, time stamps, and active weekdays
-- Time zone required for operations only when relevant
-- Serializable to simple ISO formatted strings
+scDate is a TypeScript library designed specifically for handling date and time operations in scheduling applications. It provides a set of immutable classes and utility functions that make working with dates, times, timestamps, and weekday patterns simple and predictable.
+
+## Features
+
+- **Comprehensive date/time handling**: Work with dates (`SDate`), times (`STime`), timestamps (`STimestamp`), and weekday patterns (`SWeekdays`)
+- **Time zone aware**: Time zone information is only required when performing operations where it's relevant
+- **Serializable**: All objects serialize to simple ISO-formatted strings for easy storage and transmission
+- **Immutable**: All operations return new instances, ensuring data consistency
+- **Flexible inputs**: All methods accept either serialized strings or class instances, simplifying code and improving readability
+- **Schedule-focused**: Built specifically for applications that need to handle schedules and recurring patterns
+
+## Installation
+
+```bash
+npm install scdate
+# or
+yarn add scdate
+```
+
+## Basic Usage
+
+```typescript
+import { sDate, sTime, sTimestamp, sWeekdays, Weekday } from 'scdate'
+
+// Working with dates
+const today = getDateToday('America/Puerto_Rico')
+const nextMonday = getNextDateByWeekday(today, Weekday.Mon)
+
+// Working with times
+const currentTime = getTimeNow('America/Puerto_Rico')
+const inOneHour = addMinutesToTime(currentTime, 60)
+
+// Working with timestamps
+const now = getTimestampNow('America/Puerto_Rico')
+const meeting = getTimestampFromDateAndTime(nextMonday, sTime('14:30'))
+
+// Working with weekday patterns
+const weekendDays = getWeekdaysFromWeekdayFlags(Weekday.Sat | Weekday.Sun)
+const businessDays = getWeekdaysFromWeekdayFlags(
+  Weekday.Mon | Weekday.Tue | Weekday.Wed | Weekday.Thu | Weekday.Fri,
+)
+```
+
+## API Documentation
+
+### Date Operations (`SDate`)
+
+`SDate` represents a date in the ISO 8601 format (`YYYY-MM-DD`).
+
+```typescript
+// Creating dates
+const date1 = sDate('2023-12-25') // From ISO string
+const date2 = getDateToday('America/Puerto_Rico') // Current date in timezone
+const date3 = getDateForFirstDayOfMonth(date1) // First day of month
+const date4 = getDateForLastDayOfMonth(date1) // Last day of month
+
+// Date arithmetic
+const nextDay = addDaysToDate(date1, 1) // Add days
+const nextMonth = addMonthsToDate(date1, 1) // Add months
+const nextYear = addYearsToDate(date1, 1) // Add years
+
+// Date information
+const year = getYearFromDate(date1) // Get year (number)
+const month = getMonthFromDate(date1) // Get month (0-11)
+const day = getDateFromDate(date1) // Get day of month
+const weekday = getWeekdayFromDate(date1) // Get weekday (0-6)
+
+// Date navigation
+const nextTuesday = getNextDateByWeekday(date1, Weekday.Tue)
+const prevFriday = getPreviousDateByWeekday(date1, Weekday.Fri)
+
+// Date comparison
+const isEqual = isSameDate(date1, date2)
+const isBefore = isBeforeDate(date1, date2)
+const isAfter = isAfterDate(date1, date2)
+const isSameOrBefore = isSameDateOrBefore(date1, date2)
+const isSameOrAfter = isSameDateOrAfter(date1, date2)
+const isToday = isDateToday(date1, 'America/Puerto_Rico')
+
+// Date formatting
+const fullDateStr = getFullDateString(date1, 'en-US')
+const shortDateStr = getShortDateString(date1, 'America/Puerto_Rico', 'en-US', {
+  includeWeekday: true,
+  onTodayText: () => 'Today',
+})
+```
+
+#### Important Behaviors and Edge Cases
+
+- **`getNextDateByWeekday(date, weekday)`**: Always returns a date _after_ the provided date. If the current date falls on the specified weekday, it will return the _next_ occurrence (7 days later), not the current date.
+
+- **`getPreviousDateByWeekday(date, weekday)`**: Always returns a date _before_ the provided date. If the current date falls on the specified weekday, it will return the _previous_ occurrence (7 days earlier), not the current date.
+
+- **`getDateForFirstDayOfMonth(date)`**: Returns a new date set to the first day of the month from the input date, preserving the year and month.
+
+- **`getDateForLastDayOfMonth(date)`**: Returns a new date set to the last day of the month, which varies depending on the month and year (accounting for leap years).
+
+- **`addMonthsToDate(date, months, options?)`**: Properly handles month boundaries by clamping to the last day of the target month. For example, adding one month to January 31 will result in February 28/29 (depending on leap year), adding 3 months will result in April 30, and adding 5 months will result in June 30. This ensures consistent and predictable date handling when crossing between months with different numbers of days.
+
+  Accepts an optional `options` object with:
+
+  - `capToCommonDate`: When set to `true`, dates greater than the 28th will always be capped to the 28th of the target month (the last date common to all months). For example, `addMonthsToDate('2023-01-31', 3, { capToCommonDate: true })` will result in `'2023-04-28'` rather than `'2023-04-30'`. This is useful for scheduling scenarios where you need consistent date behavior across all months.
+
+- **`isDateToday(date, timeZone)`**: The comparison is time-zone aware, so a date that is "today" in one time zone might not be "today" in another time zone.
+
+### Time Operations (`STime`)
+
+`STime` represents a time in the ISO 8601 format (`HH:MM`).
+
+```typescript
+// Creating times
+const time1 = sTime('14:30') // From ISO string
+const time2 = getTimeNow('America/Puerto_Rico') // Current time in timezone
+const time3 = getTimeAtMidnight() // 00:00
+const time4 = getTimeFromMinutes(60) // 01:00 (60 minutes after midnight)
+
+// Time arithmetic
+const laterTime = addMinutesToTime(time1, 30) // Add minutes
+
+// Time information
+const hours = getHoursFromTime(time1) // Get hours (0-23)
+const minutes = getMinutesFromTime(time1) // Get minutes (0-59)
+const totalMinutes = getTimeInMinutes(time1) // Get total minutes since midnight
+
+// Time formatting
+const timeString = get12HourTimeString(time1) // e.g., "2:30 PM"
+
+// Time comparison
+const isEqual = isSameTime(time1, time2)
+const isBefore = isBeforeTime(time1, time2)
+const isAfter = isAfterTime(time1, time2)
+const isSameOrBefore = isSameTimeOrBefore(time1, time2)
+const isSameOrAfter = isSameTimeOrAfter(time1, time2)
+const isPM = isTimePM(time1)
+```
+
+#### Important Behaviors and Edge Cases
+
+- **`addMinutesToTime(time, minutes)`**: When adding minutes, the time wraps around a 24-hour clock. For example, adding 30 minutes to 23:45 results in 00:15, not 24:15.
+
+- **`getTimeInMinutes(time, midnightIs24)`**: By default, midnight (00:00) is represented as 0 minutes. If `midnightIs24` is set to `true`, midnight will be represented as 1440 minutes (24 hours).
+
+- **`isTimePM(time)`**: Hours from 12:00 to 23:59 are considered PM, while 00:00 to 11:59 are AM. 12:00 is considered PM, not AM.
+
+### Timestamp Operations (`STimestamp`)
+
+`STimestamp` combines a date and time in the ISO 8601 format (`YYYY-MM-DDTHH:MM`).
+
+```typescript
+// Creating timestamps
+const ts1 = sTimestamp('2023-12-25T14:30') // From ISO string
+const ts2 = getTimestampNow('America/Puerto_Rico') // Current timestamp in timezone
+const ts3 = getTimestampFromDateAndTime(date1, time1) // From date and time
+const ts4 = getTimestampFromUTCMilliseconds(
+  1640444400000,
+  'America/Puerto_Rico',
+) // From UTC milliseconds
+
+// Timestamp arithmetic
+const tsNextDay = addDaysToTimestamp(ts1, 1)
+const ts30MinLater = addMinutesToTimestamp(ts1, 30, 'America/Puerto_Rico')
+
+// Timestamp breakdown
+const tsDate = getDateFromTimestamp(ts1) // Extract date part
+const tsTime = getTimeFromTimestamp(ts1) // Extract time part
+
+// Timestamp conversion
+const tsMilliseconds = getUTCMillisecondsFromTimestamp(
+  ts1,
+  'America/Puerto_Rico',
+)
+const tsNativeDate = getTimeZonedDateFromTimestamp(ts1, 'America/Puerto_Rico')
+const secondsToTs = getSecondsToTimestamp(ts1, 'America/Puerto_Rico')
+
+// Timestamp formatting
+const tsString = getShortTimestampString(ts1, 'America/Puerto_Rico', 'en-US', {
+  includeWeekday: true,
+  onTodayAtText: () => 'Today at',
+})
+
+// Timestamp comparison
+const isEqual = isSameTimestamp(ts1, ts2)
+const isBefore = isBeforeTimestamp(ts1, ts2)
+const isAfter = isAfterTimestamp(ts1, ts2)
+const isSameOrBefore = isSameTimestampOrBefore(ts1, ts2)
+const isSameOrAfter = isSameTimestampOrAfter(ts1, ts2)
+```
+
+#### Important Behaviors and Edge Cases
+
+- **`getTimestampFromUTCMilliseconds(milliseconds, timeZone)`**: Converts UTC milliseconds to a timestamp in the specified time zone, accounting for time zone offsets.
+
+- **`addMinutesToTimestamp(timestamp, minutes, timeZone)`**: Time zone awareness is critical for this operation, especially around Daylight Saving Time transitions. When a timestamp lands in the "missing hour" during a spring-forward transition, it's adjusted to the valid time.
+
+- **`getSecondsToTimestamp(timestamp, timeZone)`**: Returns a positive value for future timestamps and negative for past timestamps. Handles DST transitions correctly but might produce unexpected results for timestamps that fall in skipped or repeated hours during DST transitions.
+
+- **`getUTCMillisecondsFromTimestamp(timestamp, timeZone)`**: Converts a timestamp to UTC milliseconds, accounting for the time zone offset at that specific date and time (important for historical dates with different time zone rules).
+
+### Weekday Operations (`SWeekdays`)
+
+`SWeekdays` represents a set of weekdays in the format `SMTWTFS`, where each position corresponds to a day of the week (Sunday to Saturday).
+
+```typescript
+// Creating weekday patterns
+const weekdays1 = sWeekdays('SMTWTFS') // All days
+const weekdays2 = sWeekdays('SM----S') // Sunday, Monday, Saturday
+const weekdays3 = getWeekdaysFromWeekdayFlags(Weekday.Mon | Weekday.Wed) // Monday, Wednesday
+const weekdays4 = getWeekdaysWithAllIncluded() // All days
+const weekdays5 = getWeekdaysWithNoneIncluded() // No days
+
+// Weekday operations
+const shiftedWeekdays = shiftWeekdaysForward(weekdays2) // Shift pattern one day forward
+const filteredWeekdays = filterWeekdaysForDates(
+  // Filter to days in date range
+  weekdays1,
+  '2023-12-25',
+  '2023-12-31',
+)
+const updatedWeekdays = addWeekdayToWeekdays(weekdays5, Weekday.Fri) // Add Friday to pattern
+
+// Weekday queries
+const includesMonday = doesWeekdaysIncludeWeekday(weekdays2, Weekday.Mon)
+const hasOverlap = doesWeekdaysHaveOverlapWithWeekdays(weekdays2, weekdays3)
+```
+
+#### Important Behaviors and Edge Cases
+
+- **`sWeekdays(pattern)`**: The pattern must be exactly 7 characters long, with each position representing a day from Sunday to Saturday. Valid characters are the first letter of the English weekday name (S, M, T, W, T, F, S) or a dash '-' for excluded days.
+
+- **`shiftWeekdaysForward(weekdays)`**: Shifts the pattern forward by one day with circular wrapping. For example, 'SM----S' becomes 'SMT----'. The last character (Saturday) wraps around to become the first day (Sunday) position.
+
+- **`filterWeekdaysForDates(weekdays, fromDate, toDate)`**: Returns a new weekday pattern that only includes the weekdays that fall within the given date range. If the date range spans less than a week, only the applicable days are included.
+
+- **`getWeekdaysFromWeekdayFlags(flags)`**: Uses bitwise operations to combine multiple weekday flags. Each weekday is represented by a power of 2, allowing for efficient combination and checking.
 
 ## Dependencies
 
 This package has the following dependencies:
 
-- `date-fns-tz`: used for time zone calculations
-- `date-fns`: it is a peer dependency of `date-fns-tz`
-- `@date-fns/utc`: used for its `UTCDateMini` implementation that simplifies some of the time calculations
+- `date-fns-tz`: Used for time zone calculations
+- `date-fns`: Peer dependency of `date-fns-tz`
+- `@date-fns/utc`: Used for its `UTCDateMini` implementation that simplifies time calculations
 
 ## Design Decisions
 
-### ISO formatted values
+### ISO 8601 Format
+
+scDate uses a subset of the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard for all date and time representations. This format was chosen for several key benefits:
 
-A subset of [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) is used as the valid format for SDate, STime, and STimestamp. This was done because:
+- **Human readability**: Dates and times are easy to read and interpret
+- **String sortability**: ISO-formatted strings can be sorted chronologically using simple string comparison
+- **Direct comparison**: Values can be compared directly as strings without conversion
 
-- the format is human readable
-- the values are easily sortable as strings
-- the values are easily comparable as strings
+### Minute-Level Precision
 
-### No seconds in time components
+scDate intentionally omits seconds and milliseconds from time representations. This design choice reflects the library's focus on scheduling applications, where:
 
-The library was designed with schedules in mind that do not require second or smaller granularity as such STime and STimestamp only provide minute granularity.
+- Minute-level granularity is typically sufficient for most scheduling needs
+- Simpler time representations lead to more intuitive API and usage patterns
+- Performance is optimized by avoiding unnecessary precision
 
 ## Time zones
 
 For a list of valid time zones run `Intl.supportedValuesOf('timeZone')` in your environment.
 
-## API Reference
+## License
 
-See [docs](docs/README.md)
+MIT

package/dist/internal/zoned.d.ts

@@ -1,7 +1,3 @@
-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.

package/dist/internal/zoned.js

@@ -1,23 +1,4 @@
-import { getTimezoneOffset, toZonedTime } from 'date-fns-tz';
-import { getDateAsUTCDateMini } from './date.js';
-import { getTimestampAsUTCDateMini } from './timestamp.js';
-const getValidatedTimeZoneOffset = (timeZone, utcDate) => {
-    const timeZoneOffset = getTimezoneOffset(timeZone, utcDate);
-    if (isNaN(timeZoneOffset)) {
-        throw new Error(`Invalid time zone. Time zone: '${timeZone}'`);
-    }
-    return timeZoneOffset;
-};
-export const getMillisecondsInUTCFromTimestamp = (timestamp, timeZone) => {
-    const utcDate = getTimestampAsUTCDateMini(timestamp);
-    const timeZoneOffset = getValidatedTimeZoneOffset(timeZone, utcDate);
-    return utcDate.getTime() - timeZoneOffset;
-};
-export const getMillisecondsInUTCFromDate = (date, timeZone) => {
-    const utcDate = getDateAsUTCDateMini(date);
-    const timeZoneOffset = getValidatedTimeZoneOffset(timeZone, utcDate);
-    return utcDate.getTime() - timeZoneOffset;
-};
+import { toZonedTime } from 'date-fns-tz';
 /**
  * @param timeZone For a list of valid time zones run
  *   `Intl.supportedValuesOf('timeZone')` on your environment.

package/dist/sDate.d.ts

@@ -90,6 +90,16 @@ export declare const getDateFromDate: (date: string | SDate) => number;
  * in the YYYY-MM-DD format.
  */
 export declare const getWeekdayFromDate: (date: string | SDate) => number;
+/**
+ * Returns the number of milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC)
+ * for the given date in the specified time zone.
+ *
+ * @param date The date to convert to UTC milliseconds. It can be an SDate or a string
+ * in the YYYY-MM-DD format.
+ * @param timeZone The time zone to use when converting the date. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
+export declare const getUTCMillisecondsFromDate: (date: string | SDate, timeZone: string) => number;
 /**
  * Returns a native Date adjusted so that the local time of that date matches
  * the local time at the specified time zone.
@@ -181,11 +191,47 @@ export declare const addDaysToDate: (date: string | SDate, days: number) => SDat
  * 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.
  *
+ * When the original date's day exceeds the number of days in the target month,
+ * the function will automatically clamp to the last day of the target month
+ * rather than rolling over to the next month. For example, adding 1 month to
+ * January 31 will result in February 28/29 (depending on leap year), not March 3.
+ *
  * @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.
+ * @param options Additional options for controlling the behavior of the function.
+ * @param options.capToCommonDate When true, if the original date is the 29th,
+ * 30th, or 31st, the result will be capped to the 28th of the month (the last
+ * date common to all months) rather than the last day of the target month.
+ * This ensures consistent date handling across all months.
+ *
+ * @example
+ * ```ts
+ * addMonthsToDate('2023-01-31', 1)
+ * //=> '2023-02-28' (February has fewer days than January)
+ * ```
+ *
+ * @example
+ * ```ts
+ * addMonthsToDate('2023-01-31', 3)
+ * //=> '2023-04-30' (April has 30 days)
+ * ```
+ *
+ * @example
+ * ```ts
+ * addMonthsToDate('2024-01-31', 1)
+ * //=> '2024-02-29' (February in leap year)
+ * ```
+ *
+ * @example
+ * ```ts
+ * addMonthsToDate('2023-01-31', 3, { capToCommonDate: true })
+ * //=> '2023-04-28' (capped to the 28th regardless of month length)
+ * ```
  */
-export declare const addMonthsToDate: (date: string | SDate, months: number) => SDate;
+export declare const addMonthsToDate: (date: string | SDate, months: number, options?: {
+    capToCommonDate?: boolean;
+}) => 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

package/dist/sDate.js

@@ -1,9 +1,11 @@
+import { UTCDateMini } from '@date-fns/utc';
+import { getTimezoneOffset } from 'date-fns-tz';
 import { SDate } from './internal/SDate.js';
 import { DayToWeekday, DaysInWeek, MillisecondsInDay, } from './internal/constants.js';
 import { getDateAsUTCDateMini, getISODateFromISODate, getISODateFromZonedDate, getISOMonthFromISODate, getISOYearFromISODate, } from './internal/date.js';
 import { getAtIndex } from './internal/utils.js';
 import { getIndexForWeekday } from './internal/weekdays.js';
-import { getMillisecondsInUTCFromDate, getTimeZonedDate, } from './internal/zoned.js';
+import { getTimeZonedDate } from './internal/zoned.js';
 /**
  * --- Factory ---
  */
@@ -142,6 +144,24 @@ export const getWeekdayFromDate = (date) => {
     const nativeDate = getDateAsUTCDateMini(sDateValue);
     return getAtIndex(DayToWeekday, nativeDate.getDay());
 };
+/**
+ * Returns the number of milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC)
+ * for the given date in the specified time zone.
+ *
+ * @param date The date to convert to UTC milliseconds. It can be an SDate or a string
+ * in the YYYY-MM-DD format.
+ * @param timeZone The time zone to use when converting the date. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
+export const getUTCMillisecondsFromDate = (date, timeZone) => {
+    const sDateValue = sDate(date);
+    const utcDate = getDateAsUTCDateMini(sDateValue);
+    const timeZoneOffset = getTimezoneOffset(timeZone, utcDate);
+    if (isNaN(timeZoneOffset)) {
+        throw new Error(`Invalid time zone. Time zone: '${timeZone}'`);
+    }
+    return utcDate.getTime() - timeZoneOffset;
+};
 /**
  * Returns a native Date adjusted so that the local time of that date matches
  * the local time at the specified time zone.
@@ -153,7 +173,7 @@ export const getWeekdayFromDate = (date) => {
  */
 export const getTimeZonedDateFromDate = (date, timeZone) => {
     const sDateValue = sDate(date);
-    const milliseconds = getMillisecondsInUTCFromDate(sDateValue, timeZone);
+    const milliseconds = getUTCMillisecondsFromDate(sDateValue, timeZone);
     const zonedTime = getTimeZonedDate(milliseconds, timeZone);
     return zonedTime;
 };
@@ -270,14 +290,63 @@ export const addDaysToDate = (date, days) => {
  * 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.
  *
+ * When the original date's day exceeds the number of days in the target month,
+ * the function will automatically clamp to the last day of the target month
+ * rather than rolling over to the next month. For example, adding 1 month to
+ * January 31 will result in February 28/29 (depending on leap year), not March 3.
+ *
  * @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.
+ * @param options Additional options for controlling the behavior of the function.
+ * @param options.capToCommonDate When true, if the original date is the 29th,
+ * 30th, or 31st, the result will be capped to the 28th of the month (the last
+ * date common to all months) rather than the last day of the target month.
+ * This ensures consistent date handling across all months.
+ *
+ * @example
+ * ```ts
+ * addMonthsToDate('2023-01-31', 1)
+ * //=> '2023-02-28' (February has fewer days than January)
+ * ```
+ *
+ * @example
+ * ```ts
+ * addMonthsToDate('2023-01-31', 3)
+ * //=> '2023-04-30' (April has 30 days)
+ * ```
+ *
+ * @example
+ * ```ts
+ * addMonthsToDate('2024-01-31', 1)
+ * //=> '2024-02-29' (February in leap year)
+ * ```
+ *
+ * @example
+ * ```ts
+ * addMonthsToDate('2023-01-31', 3, { capToCommonDate: true })
+ * //=> '2023-04-28' (capped to the 28th regardless of month length)
+ * ```
  */
-export const addMonthsToDate = (date, months) => {
+export const addMonthsToDate = (date, months, options) => {
     const sDateValue = sDate(date);
     const nativeDate = getDateAsUTCDateMini(sDateValue);
-    nativeDate.setMonth(nativeDate.getMonth() + months);
+    const currentDay = nativeDate.getDate();
+    const currentMonth = nativeDate.getMonth();
+    // First set day to 1 to avoid month overflow
+    nativeDate.setDate(1);
+    // Then set the new month
+    nativeDate.setMonth(currentMonth + months);
+    // If capToCommonDate is true and the original day is greater than 28, cap to 28
+    if (options?.capToCommonDate && currentDay > 28) {
+        nativeDate.setDate(28);
+    }
+    else {
+        // Get the last day of the target month
+        const lastDayOfMonth = new UTCDateMini(nativeDate.getFullYear(), nativeDate.getMonth() + 1, 0).getDate();
+        // Set the day, clamping to the last day of the month if necessary
+        nativeDate.setDate(Math.min(currentDay, lastDayOfMonth));
+    }
     return sDate(getISODateFromZonedDate(nativeDate));
 };
 /**

package/dist/sTimestamp.d.ts

@@ -49,6 +49,16 @@ export declare const getTimestampFromDateAndTime: (date: string | SDate, time: s
 /**
  * --- Getters ---
  */
+/**
+ * Returns the number of milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC)
+ * for the given timestamp in the specified time zone.
+ *
+ * @param timestamp The timestamp to convert to UTC milliseconds. It can be an STimestamp
+ * or a string in the YYYY-MM-DDTHH:MM format.
+ * @param timeZone The time zone to use when converting the timestamp. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
+export declare const getUTCMillisecondsFromTimestamp: (timestamp: string | STimestamp, timeZone: string) => number;
 /**
  * Returns a native Date adjusted so that the local time of that date matches
  * the local timestamp at the specified time zone.
@@ -197,10 +207,10 @@ export declare const addDaysToTimestamp: (timestamp: string | STimestamp, days:
  *
  * 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.)
+ * 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

package/dist/sTimestamp.js

@@ -1,7 +1,8 @@
+import { getTimezoneOffset } from 'date-fns-tz';
 import { STimestamp } from './internal/STimestamp.js';
 import { MillisecondsInMinute, MillisecondsInSecond, } from './internal/constants.js';
 import { getISODateFromISOTimestamp, getISOTimeFromISOTimestamp, getISOTimestampFromZonedDate, getTimestampAsUTCDateMini, } from './internal/timestamp.js';
-import { getMillisecondsInUTCFromTimestamp, getTimeZonedDate, } from './internal/zoned.js';
+import { getTimeZonedDate } from './internal/zoned.js';
 import { getShortDateString, sDate } from './sDate.js';
 import { get12HourTimeString, sTime } from './sTime.js';
 /**
@@ -62,6 +63,24 @@ export const getTimestampFromDateAndTime = (date, time) => {
 /**
  * --- Getters ---
  */
+/**
+ * Returns the number of milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC)
+ * for the given timestamp in the specified time zone.
+ *
+ * @param timestamp The timestamp to convert to UTC milliseconds. It can be an STimestamp
+ * or a string in the YYYY-MM-DDTHH:MM format.
+ * @param timeZone The time zone to use when converting the timestamp. See
+ * `Intl.supportedValuesOf('timeZone')` for a list of valid time zones.
+ */
+export const getUTCMillisecondsFromTimestamp = (timestamp, timeZone) => {
+    const sTimestampValue = sTimestamp(timestamp);
+    const utcDate = getTimestampAsUTCDateMini(sTimestampValue);
+    const timeZoneOffset = getTimezoneOffset(timeZone, utcDate);
+    if (isNaN(timeZoneOffset)) {
+        throw new Error(`Invalid time zone. Time zone: '${timeZone}'`);
+    }
+    return utcDate.getTime() - timeZoneOffset;
+};
 /**
  * Returns a native Date adjusted so that the local time of that date matches
  * the local timestamp at the specified time zone.
@@ -73,7 +92,7 @@ export const getTimestampFromDateAndTime = (date, time) => {
  */
 export const getTimeZonedDateFromTimestamp = (timestamp, timeZone) => {
     const sTimestampValue = sTimestamp(timestamp);
-    const dateInUTCMilliseconds = getMillisecondsInUTCFromTimestamp(sTimestampValue, timeZone);
+    const dateInUTCMilliseconds = getUTCMillisecondsFromTimestamp(sTimestampValue, timeZone);
     return getTimeZonedDate(dateInUTCMilliseconds, timeZone);
 };
 /**
@@ -130,7 +149,7 @@ export const getTimeZonedDateFromTimestamp = (timestamp, timeZone) => {
 export const getSecondsToTimestamp = (timestamp, timeZone) => {
     const sTimestampValue = sTimestamp(timestamp);
     const millisecondsNow = Date.now();
-    const millisecondsAtTimestamp = getMillisecondsInUTCFromTimestamp(sTimestampValue, timeZone);
+    const millisecondsAtTimestamp = getUTCMillisecondsFromTimestamp(sTimestampValue, timeZone);
     return Math.floor((millisecondsAtTimestamp - millisecondsNow) / MillisecondsInSecond);
 };
 /**
@@ -240,10 +259,10 @@ export const addDaysToTimestamp = (timestamp, days) => {
  *
  * 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.)
+ * 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
@@ -278,7 +297,7 @@ export const addDaysToTimestamp = (timestamp, days) => {
  */
 export const addMinutesToTimestamp = (timestamp, minutes, timeZone) => {
     const sTimestampValue = sTimestamp(timestamp);
-    const newMillisecondsInUTC = getMillisecondsInUTCFromTimestamp(sTimestampValue, timeZone) +
+    const newMillisecondsInUTC = getUTCMillisecondsFromTimestamp(sTimestampValue, timeZone) +
         minutes * MillisecondsInMinute;
     const newTimestamp = getTimestampFromUTCMilliseconds(newMillisecondsInUTC, timeZone);
     return newTimestamp;

package/dist/sWeekdays.js

@@ -62,7 +62,7 @@ export const sWeekdays = (weekdays) => {
  * ```
  */
 export const getWeekdaysFromWeekdayFlags = (weekdays) => {
-    const newWeekdays = [...AllWeekdaysIncludedMask];
+    const newWeekdays = Array.from(AllWeekdaysIncludedMask);
     for (let i = 0; i < DayToWeekday.length; i++) {
         const weekday = getAtIndex(DayToWeekday, i);
         if (!hasFlag(weekdays, weekday)) {
@@ -102,7 +102,7 @@ export const getWeekdaysWithNoneIncluded = () => {
  */
 export const shiftWeekdaysForward = (weekdays) => {
     const sWeekdaysInstance = sWeekdays(weekdays);
-    const after = [...NoWeekdaysIncluded];
+    const after = Array.from(NoWeekdaysIncluded);
     const DayShift = 1;
     for (let i = 0; i < WeekdaysCount; i++) {
         const prevDayIndex = (WeekdaysCount - DayShift + i) % WeekdaysCount;
@@ -163,7 +163,7 @@ export const filterWeekdaysForDates = (weekdays, fromDate, toDate) => {
  */
 export const addWeekdayToWeekdays = (weekdays, weekdayToAdd) => {
     const sWeekdaysInstance = sWeekdays(weekdays);
-    const newWeekdays = [...sWeekdaysInstance.weekdays];
+    const newWeekdays = Array.from(sWeekdaysInstance.weekdays);
     const weekdayIndex = getIndexForWeekday(weekdayToAdd);
     newWeekdays[weekdayIndex] = getAtIndex(AllWeekdaysIncludedMask, weekdayIndex);
     return sWeekdays(newWeekdays.join(''));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scdate",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "type": "module",
   "exports": {
     ".": "./dist/index.js"
@@ -23,9 +23,8 @@
     "test:watch": "vitest",
     "test:utc:watch": "TZ=Etc/Universal yarn test:watch",
     "smoke": "yarn build && yarn lint && yarn test:utc",
-    "docs": "typedoc && prettier --ignore-unknown --write docs/",
     "-- PRE-COMMIT HOOKS --": "",
-    "localAfterInstall": "is-ci || husky || true",
+    "localAfterInstall": "husky || true",
     "prepublishOnly": "pinst --disable",
     "postpublish": "pinst --enable"
   },
@@ -35,21 +34,18 @@
     "date-fns-tz": "^3.2.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.11.1",
+    "@eslint/js": "^9.25.0",
     "@tsconfig/strictest": "^2.0.5",
-    "@types/node": "^22.7.4",
-    "eslint": "^9.11.1",
-    "husky": "^9.1.6",
-    "is-ci": "^3.0.1",
-    "lint-staged": "^15.2.10",
+    "@types/node": "^22.14.1",
+    "eslint": "^9.25.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.1",
     "pinst": "^3.0.0",
-    "prettier": "^3.3.3",
+    "prettier": "^3.5.3",
     "rimraf": "^6.0.1",
-    "typedoc": "^0.26.7",
-    "typedoc-plugin-markdown": "^4.2.8",
-    "typescript": "^5.6.2",
-    "typescript-eslint": "^8.8.0",
-    "vitest": "^2.1.1"
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.30.1",
+    "vitest": "^3.1.2"
   },
   "prettier": {
     "tabWidth": 2,
@@ -74,5 +70,5 @@
     "*.{ts,tsx,mjs}": "eslint --cache",
     "*": "prettier --ignore-unknown --write"
   },
-  "packageManager": "yarn@4.3.0"
+  "packageManager": "yarn@4.9.1"
 }