scdate 1.1.0 → 2.0.2

package/README.md

@@ -78,6 +78,11 @@ const weekday = getWeekdayFromDate(date1) // Get weekday (0-6)
 const nextTuesday = getNextDateByWeekday(date1, Weekday.Tue)
 const prevFriday = getPreviousDateByWeekday(date1, Weekday.Fri)
 
+// Date calculations
+const daysBetween = getDaysBetweenDates(date1, date2) // Days between dates (positive if date2 is later)
+const utcMs = getUTCMillisecondsFromDate(date1, 'America/Puerto_Rico') // Convert to UTC milliseconds
+const zonedDate = getTimeZonedDateFromDate(date1, 'America/Puerto_Rico') // Get timezone-adjusted Date
+
 // Date comparison
 const isEqual = isSameDate(date1, date2)
 const isBefore = isBeforeDate(date1, date2)
@@ -85,6 +90,10 @@ const isAfter = isAfterDate(date1, date2)
 const isSameOrBefore = isSameDateOrBefore(date1, date2)
 const isSameOrAfter = isSameDateOrAfter(date1, date2)
 const isToday = isDateToday(date1, 'America/Puerto_Rico')
+const isSameMonth = areDatesInSameMonth(date1, date2) // Check if dates are in same month & year
+const isSameYear = areDatesInSameYear(date1, date2) // Check if dates are in same year
+const isCurrentMonth = isDateInCurrentMonth(date1, 'America/Puerto_Rico') // Check if in current month
+const isCurrentYear = isDateInCurrentYear(date1, 'America/Puerto_Rico') // Check if in current year
 
 // Date formatting
 const fullDateStr = getFullDateString(date1, 'en-US')
@@ -104,10 +113,23 @@ const shortDateStr = getShortDateString(date1, 'America/Puerto_Rico', 'en-US', {
 
 - **`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)`**: Handles month overflow correctly. For example, adding one month to January 31 will result in either February 28 or 29 (depending on leap year), not March 3.
+- **`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.
 
+- **`getDaysBetweenDates(date1, date2)`**: Returns the number of calendar days between two dates. The result is positive if date2 is after date1, negative if before. This accounts for calendar days rather than full 24-hour periods.
+
+- **`getUTCMillisecondsFromDate(date, timeZone)`**: Converts a date to UTC milliseconds since the Unix epoch, accounting for the specified time zone offset.
+
+- **`getTimeZonedDateFromDate(date, timeZone)`**: Returns a native Date object adjusted so that its local time matches the local time at the specified time zone.
+
+- **`areDatesInSameMonth(date1, date2)` / `areDatesInSameYear(date1, date2)`**: Check if two dates fall within the same month/year. For months, both the month and year must match.
+
+- **`isDateInCurrentMonth(date, timeZone)` / `isDateInCurrentYear(date, timeZone)`**: Check if a date falls within the current month or year in the specified time zone.
+
 ### Time Operations (`STime`)
 
 `STime` represents a time in the ISO 8601 format (`HH:MM`).
@@ -129,6 +151,8 @@ const totalMinutes = getTimeInMinutes(time1) // Get total minutes since midnight
 
 // Time formatting
 const timeString = get12HourTimeString(time1) // e.g., "2:30 PM"
+const hoursString = get12HoursHoursStringFromTime(time1) // Get hours in 12-hour format (e.g., "2")
+const minutesString = getMinutesStringFromTime(time1) // Get minutes as 2-digit string (e.g., "30")
 
 // Time comparison
 const isEqual = isSameTime(time1, time2)
@@ -147,6 +171,10 @@ const isPM = isTimePM(time1)
 
 - **`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.
 
+- **`get12HoursHoursStringFromTime(time)`**: Returns the hours component in 12-hour format as a string (1-12).
+
+- **`getMinutesStringFromTime(time)`**: Returns the minutes component as a zero-padded 2-digit string (00-59).
+
 ### Timestamp Operations (`STimestamp`)
 
 `STimestamp` combines a date and time in the ISO 8601 format (`YYYY-MM-DDTHH:MM`).

package/dist/sDate.d.ts

@@ -191,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,3 +1,4 @@
+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';
@@ -289,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scdate",
-  "version": "1.1.0",
+  "version": "2.0.2",
   "type": "module",
   "exports": {
     ".": "./dist/index.js"
@@ -24,28 +24,28 @@
     "test:utc:watch": "TZ=Etc/Universal yarn test:watch",
     "smoke": "yarn build && yarn lint && yarn test:utc",
     "-- PRE-COMMIT HOOKS --": "",
-    "localAfterInstall": "is-ci || husky || true",
+    "localAfterInstall": "husky || true",
     "prepublishOnly": "pinst --disable",
     "postpublish": "pinst --enable"
   },
   "dependencies": {
-    "@date-fns/utc": "^2.1.0",
+    "@date-fns/utc": "^2.1.1",
     "date-fns": "^4.1.0",
     "date-fns-tz": "^3.2.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.25.0",
+    "@eslint/js": "^9.33.0",
     "@tsconfig/strictest": "^2.0.5",
-    "@types/node": "^22.14.1",
-    "eslint": "^9.25.0",
+    "@types/node": "^24.3.0",
+    "eslint": "^9.33.0",
     "husky": "^9.1.7",
-    "lint-staged": "^15.5.1",
+    "lint-staged": "^16.1.5",
     "pinst": "^3.0.0",
-    "prettier": "^3.5.3",
+    "prettier": "^3.6.2",
     "rimraf": "^6.0.1",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.30.1",
-    "vitest": "^3.1.1"
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.40.0",
+    "vitest": "^3.2.4"
   },
   "prettier": {
     "tabWidth": 2,
@@ -54,7 +54,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ericvera/scdate"
+    "url": "git+https://github.com/ericvera/scdate.git"
   },
   "keywords": [
     "date",
@@ -70,5 +70,5 @@
     "*.{ts,tsx,mjs}": "eslint --cache",
     "*": "prettier --ignore-unknown --write"
   },
-  "packageManager": "yarn@4.9.1"
+  "packageManager": "yarn@4.9.2"
 }