kcommons 18.26.5 → 18.26.6

package/build/utils/calculateTimeDifferenceInSecs.util.d.ts

@@ -8,18 +8,18 @@
  */
 type TimeInput = Date | string;
 /**
- * Calculates the difference in seconds between two times.
+ * Calculates the absolute difference in seconds between two times. The
+ * result is never negative, so the order of `start` and `end` does not
+ * matter.
  *
  * The behaviour depends on the input types:
  *
- * - **Both `Date` objects** — the signed full date-time difference
- *   (`end - start`) is returned via `date-fns` `differenceInSeconds`, so
- *   differences across days are included and the result is negative if `end`
- *   is before `start`. Fractional seconds are truncated.
+ * - **Both `Date` objects** — the full date-time difference is used (via
+ *   `date-fns` `differenceInSeconds`), so differences across days are
+ *   included. Fractional seconds are truncated.
  * - **Any `string` input (or a mix of `Date` and `string`)** — only the time
- *   of day is compared, and the **absolute** difference is returned. The
- *   calendar date of any `Date` is ignored, and its local
- *   hours/minutes/seconds are used.
+ *   of day is compared. The calendar date of any `Date` is ignored, and its
+ *   local hours/minutes/seconds are used.
  *
  * The time-of-day result is **not** wrapped around midnight: `"22:00"` →
  * `"02:00"` gives `72000` (the gap between the two times of day), not the
@@ -28,9 +28,8 @@ type TimeInput = Date | string;
  *
  * @param start - The start time: a `Date` or an `HH:MM` (24-hour) string.
  * @param end - The end time: a `Date` or an `HH:MM` (24-hour) string.
- * @returns For two `Date`s, the signed number of seconds from `start` to
- *   `end`. Otherwise, the absolute number of seconds between the two times
- *   of day (never negative).
+ * @returns The absolute number of seconds between `start` and `end`
+ *   (never negative).
  * @throws {Error} If a string input is not in `HH:MM` format, or a `Date`
  *   input is invalid (in the time-of-day comparison path).
  *
@@ -38,7 +37,7 @@ type TimeInput = Date | string;
  * calculateTimeDifferenceInSeconds("09:00", "17:30"); // 30600
  *
  * @example
- * // Order does not matter for time-of-day comparisons
+ * // Order does not matter
  * calculateTimeDifferenceInSeconds("18:00", "09:00"); // 32400
  *
  * @example

package/build/utils/calculateTimeDifferenceInSecs.util.js

@@ -30,18 +30,18 @@ function toSeconds(input) {
     return hours * 3600 + minutes * 60;
 }
 /**
- * Calculates the difference in seconds between two times.
+ * Calculates the absolute difference in seconds between two times. The
+ * result is never negative, so the order of `start` and `end` does not
+ * matter.
  *
  * The behaviour depends on the input types:
  *
- * - **Both `Date` objects** — the signed full date-time difference
- *   (`end - start`) is returned via `date-fns` `differenceInSeconds`, so
- *   differences across days are included and the result is negative if `end`
- *   is before `start`. Fractional seconds are truncated.
+ * - **Both `Date` objects** — the full date-time difference is used (via
+ *   `date-fns` `differenceInSeconds`), so differences across days are
+ *   included. Fractional seconds are truncated.
  * - **Any `string` input (or a mix of `Date` and `string`)** — only the time
- *   of day is compared, and the **absolute** difference is returned. The
- *   calendar date of any `Date` is ignored, and its local
- *   hours/minutes/seconds are used.
+ *   of day is compared. The calendar date of any `Date` is ignored, and its
+ *   local hours/minutes/seconds are used.
  *
  * The time-of-day result is **not** wrapped around midnight: `"22:00"` →
  * `"02:00"` gives `72000` (the gap between the two times of day), not the
@@ -50,9 +50,8 @@ function toSeconds(input) {
  *
  * @param start - The start time: a `Date` or an `HH:MM` (24-hour) string.
  * @param end - The end time: a `Date` or an `HH:MM` (24-hour) string.
- * @returns For two `Date`s, the signed number of seconds from `start` to
- *   `end`. Otherwise, the absolute number of seconds between the two times
- *   of day (never negative).
+ * @returns The absolute number of seconds between `start` and `end`
+ *   (never negative).
  * @throws {Error} If a string input is not in `HH:MM` format, or a `Date`
  *   input is invalid (in the time-of-day comparison path).
  *
@@ -60,7 +59,7 @@ function toSeconds(input) {
  * calculateTimeDifferenceInSeconds("09:00", "17:30"); // 30600
  *
  * @example
- * // Order does not matter for time-of-day comparisons
+ * // Order does not matter
  * calculateTimeDifferenceInSeconds("18:00", "09:00"); // 32400
  *
  * @example
@@ -76,7 +75,7 @@ function toSeconds(input) {
  */
 function calculateTimeDifferenceInSeconds(start, end) {
     if (start instanceof Date && end instanceof Date) {
-        return (0, date_fns_1.differenceInSeconds)(end, start);
+        return Math.abs((0, date_fns_1.differenceInSeconds)(end, start));
     }
     return Math.abs(toSeconds(end) - toSeconds(start));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcommons",
-  "version": "18.26.5",
+  "version": "18.26.6",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",