feat: make "trunc" the default rounding mode

BREAKING CHANGE: "trunc" logic is very different from `Math.round`, and
will produce different results compared to the previous versions of the
package. To use the rounding logic of `Math.round`, use the "halfCeil"
rounding mode, which ties towards positive infinity, compared to
"trunc", which always rounds towards zero.

src/index.ts

@@ -195,13 +195,9 @@ export interface FormatOptions extends FormatRelativeTimeOptions {
    * - `halfEven` — round values at half-increment towards the nearest even value,
    *   values above it away from 0, and values below it towards 0.
    *
-   * Value of `null` will use `Math.round`. This value is only kept for backward
-   * compatibility, and will be removed in the next major release, in which
-   * `"trunc"` will be made a new default.
-   *
-   * @default null // Use `Math.round` (deprecated)
+   * @default 'trunc'
    */
-  roundingMode?: RoundingMode | null
+  roundingMode?: RoundingMode
 
   /**
    * Whether to round to the nearest unit if the rounded duration goes above the
@@ -370,8 +366,7 @@ function calculateBoundaries(
 }
 
 function getRoundingMethod({ roundingMode }: FormatOptions) {
-  roundingMode ??= null
-  if (roundingMode === null) return Math.round
+  roundingMode ??= 'trunc'
   if (!Object.hasOwn(roundingModesImpls, roundingMode)) {
     throwRangeError('roundingMode', roundingMode)
   }

test/index.test.ts

@@ -139,38 +139,53 @@ test('formatTimeDifference (all units excluded)', () => {
   ).toBe('1 січня 2023 р. о 00:00')
 })
 
-test('formatTimeDifference (trunc rounding method)', () => {
+test('formatTimeDifference (halfCeil rounding method)', () => {
   const twoSthnYearsInPast = now - year * 2.7
   const twoSthnYearsInFuture = now + year * 2.7
 
-  expect(ago(twoSthnYearsInPast)).toMatchInlineSnapshot('"3 роки тому"')
-  expect(ago(twoSthnYearsInFuture)).toMatchInlineSnapshot('"через 3 роки"')
+  expect(ago(twoSthnYearsInPast)).toMatchInlineSnapshot('"2 роки тому"')
+
+  expect(ago(twoSthnYearsInFuture)).toMatchInlineSnapshot('"через 2 роки"')
 
   expect(
-    ago(twoSthnYearsInPast, { roundingMode: 'trunc' }),
-  ).toMatchInlineSnapshot('"2 роки тому"')
+    ago(twoSthnYearsInPast, { roundingMode: 'halfCeil' }),
+  ).toMatchInlineSnapshot('"3 роки тому"')
 
   expect(
-    ago(twoSthnYearsInFuture, { roundingMode: 'trunc' }),
-  ).toMatchInlineSnapshot('"через 2 роки"')
+    ago(twoSthnYearsInFuture, { roundingMode: 'halfCeil' }),
+  ).toMatchInlineSnapshot('"через 3 роки"')
 })
 
 test('formatTimeDifference (with unitRounding)', () => {
   const fiftyNineSthnMinutesAgo = now - 59.6 * minute
   const twentyThreeSthnHoursInFuture = now + 23.5 * hour
 
-  expect(ago(fiftyNineSthnMinutesAgo)).toMatchInlineSnapshot('"60 хвилин тому"')
+  expect(
+    ago(fiftyNineSthnMinutesAgo, {
+      roundingMode: 'halfExpand',
+      unitRounding: false,
+    }),
+  ).toMatchInlineSnapshot('"60 хвилин тому"')
 
-  expect(ago(twentyThreeSthnHoursInFuture)).toMatchInlineSnapshot(
-    '"через 24 години"',
-  )
+  expect(
+    ago(twentyThreeSthnHoursInFuture, {
+      roundingMode: 'halfExpand',
+      unitRounding: false,
+    }),
+  ).toMatchInlineSnapshot('"через 24 години"')
 
   expect(
-    ago(fiftyNineSthnMinutesAgo, { unitRounding: true }),
+    ago(fiftyNineSthnMinutesAgo, {
+      roundingMode: 'halfExpand',
+      unitRounding: true,
+    }),
   ).toMatchInlineSnapshot('"1 годину тому"')
 
   expect(
-    ago(twentyThreeSthnHoursInFuture, { unitRounding: true }),
+    ago(twentyThreeSthnHoursInFuture, {
+      roundingMode: 'halfExpand',
+      unitRounding: true,
+    }),
   ).toMatchInlineSnapshot('"завтра"')
 })