scdate 1.1.0 → 2.0.0

package/README.md

@@ -104,7 +104,11 @@ 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.
 

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.0",
   "type": "module",
   "exports": {
     ".": "./dist/index.js"
@@ -24,7 +24,7 @@
     "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"
   },
@@ -45,7 +45,7 @@
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.30.1",
-    "vitest": "^3.1.1"
+    "vitest": "^3.1.2"
   },
   "prettier": {
     "tabWidth": 2,