intlFormatDistance.mjs
8.02 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
import {
secondsInDay,
secondsInHour,
secondsInMinute,
secondsInMonth,
secondsInQuarter,
secondsInWeek,
secondsInYear,
} from "./constants.mjs";
import { differenceInCalendarDays } from "./differenceInCalendarDays.mjs";
import { differenceInCalendarMonths } from "./differenceInCalendarMonths.mjs";
import { differenceInCalendarQuarters } from "./differenceInCalendarQuarters.mjs";
import { differenceInCalendarWeeks } from "./differenceInCalendarWeeks.mjs";
import { differenceInCalendarYears } from "./differenceInCalendarYears.mjs";
import { differenceInHours } from "./differenceInHours.mjs";
import { differenceInMinutes } from "./differenceInMinutes.mjs";
import { differenceInSeconds } from "./differenceInSeconds.mjs";
import { toDate } from "./toDate.mjs";
/**
* The {@link intlFormatDistance} function options.
*/
/**
* The unit used to format the distance in {@link intlFormatDistance}.
*/
/**
* @name intlFormatDistance
* @category Common Helpers
* @summary Formats distance between two dates in a human-readable format
* @description
* The function calculates the difference between two dates and formats it as a human-readable string.
*
* The function will pick the most appropriate unit depending on the distance between dates. For example, if the distance is a few hours, it might return `x hours`. If the distance is a few months, it might return `x months`.
*
* You can also specify a unit to force using it regardless of the distance to get a result like `123456 hours`.
*
* See the table below for the unit picking logic:
*
* | Distance between dates | Result (past) | Result (future) |
* | ---------------------- | -------------- | --------------- |
* | 0 seconds | now | now |
* | 1-59 seconds | X seconds ago | in X seconds |
* | 1-59 minutes | X minutes ago | in X minutes |
* | 1-23 hours | X hours ago | in X hours |
* | 1 day | yesterday | tomorrow |
* | 2-6 days | X days ago | in X days |
* | 7 days | last week | next week |
* | 8 days-1 month | X weeks ago | in X weeks |
* | 1 month | last month | next month |
* | 2-3 months | X months ago | in X months |
* | 1 quarter | last quarter | next quarter |
* | 2-3 quarters | X quarters ago | in X quarters |
* | 1 year | last year | next year |
* | 2+ years | X years ago | in X years |
*
* @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
*
* @param date - The date
* @param baseDate - The date to compare with.
* @param options - An object with options.
* See MDN for details [Locale identification and negotiation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation)
* The narrow one could be similar to the short one for some locales.
*
* @returns The distance in words according to language-sensitive relative time formatting.
*
* @throws `date` must not be Invalid Date
* @throws `baseDate` must not be Invalid Date
* @throws `options.unit` must not be invalid Unit
* @throws `options.locale` must not be invalid locale
* @throws `options.localeMatcher` must not be invalid localeMatcher
* @throws `options.numeric` must not be invalid numeric
* @throws `options.style` must not be invalid style
*
* @example
* // What is the distance between the dates when the fist date is after the second?
* intlFormatDistance(
* new Date(1986, 3, 4, 11, 30, 0),
* new Date(1986, 3, 4, 10, 30, 0)
* )
* //=> 'in 1 hour'
*
* // What is the distance between the dates when the fist date is before the second?
* intlFormatDistance(
* new Date(1986, 3, 4, 10, 30, 0),
* new Date(1986, 3, 4, 11, 30, 0)
* )
* //=> '1 hour ago'
*
* @example
* // Use the unit option to force the function to output the result in quarters. Without setting it, the example would return "next year"
* intlFormatDistance(
* new Date(1987, 6, 4, 10, 30, 0),
* new Date(1986, 3, 4, 10, 30, 0),
* { unit: 'quarter' }
* )
* //=> 'in 5 quarters'
*
* @example
* // Use the locale option to get the result in Spanish. Without setting it, the example would return "in 1 hour".
* intlFormatDistance(
* new Date(1986, 3, 4, 11, 30, 0),
* new Date(1986, 3, 4, 10, 30, 0),
* { locale: 'es' }
* )
* //=> 'dentro de 1 hora'
*
* @example
* // Use the numeric option to force the function to use numeric values. Without setting it, the example would return "tomorrow".
* intlFormatDistance(
* new Date(1986, 3, 5, 11, 30, 0),
* new Date(1986, 3, 4, 11, 30, 0),
* { numeric: 'always' }
* )
* //=> 'in 1 day'
*
* @example
* // Use the style option to force the function to use short values. Without setting it, the example would return "in 2 years".
* intlFormatDistance(
* new Date(1988, 3, 4, 11, 30, 0),
* new Date(1986, 3, 4, 11, 30, 0),
* { style: 'short' }
* )
* //=> 'in 2 yr'
*/
export function intlFormatDistance(date, baseDate, options) {
let value = 0;
let unit;
const dateLeft = toDate(date);
const dateRight = toDate(baseDate);
if (!options?.unit) {
// Get the unit based on diffInSeconds calculations if no unit is specified
const diffInSeconds = differenceInSeconds(dateLeft, dateRight); // The smallest unit
if (Math.abs(diffInSeconds) < secondsInMinute) {
value = differenceInSeconds(dateLeft, dateRight);
unit = "second";
} else if (Math.abs(diffInSeconds) < secondsInHour) {
value = differenceInMinutes(dateLeft, dateRight);
unit = "minute";
} else if (
Math.abs(diffInSeconds) < secondsInDay &&
Math.abs(differenceInCalendarDays(dateLeft, dateRight)) < 1
) {
value = differenceInHours(dateLeft, dateRight);
unit = "hour";
} else if (
Math.abs(diffInSeconds) < secondsInWeek &&
(value = differenceInCalendarDays(dateLeft, dateRight)) &&
Math.abs(value) < 7
) {
unit = "day";
} else if (Math.abs(diffInSeconds) < secondsInMonth) {
value = differenceInCalendarWeeks(dateLeft, dateRight);
unit = "week";
} else if (Math.abs(diffInSeconds) < secondsInQuarter) {
value = differenceInCalendarMonths(dateLeft, dateRight);
unit = "month";
} else if (Math.abs(diffInSeconds) < secondsInYear) {
if (differenceInCalendarQuarters(dateLeft, dateRight) < 4) {
// To filter out cases that are less than a year but match 4 quarters
value = differenceInCalendarQuarters(dateLeft, dateRight);
unit = "quarter";
} else {
value = differenceInCalendarYears(dateLeft, dateRight);
unit = "year";
}
} else {
value = differenceInCalendarYears(dateLeft, dateRight);
unit = "year";
}
} else {
// Get the value if unit is specified
unit = options?.unit;
if (unit === "second") {
value = differenceInSeconds(dateLeft, dateRight);
} else if (unit === "minute") {
value = differenceInMinutes(dateLeft, dateRight);
} else if (unit === "hour") {
value = differenceInHours(dateLeft, dateRight);
} else if (unit === "day") {
value = differenceInCalendarDays(dateLeft, dateRight);
} else if (unit === "week") {
value = differenceInCalendarWeeks(dateLeft, dateRight);
} else if (unit === "month") {
value = differenceInCalendarMonths(dateLeft, dateRight);
} else if (unit === "quarter") {
value = differenceInCalendarQuarters(dateLeft, dateRight);
} else if (unit === "year") {
value = differenceInCalendarYears(dateLeft, dateRight);
}
}
const rtf = new Intl.RelativeTimeFormat(options?.locale, {
localeMatcher: options?.localeMatcher,
numeric: options?.numeric || "auto",
style: options?.style,
});
return rtf.format(value, unit);
}
// Fallback for modularized imports:
export default intlFormatDistance;