UNPKG

11 kBTypeScriptView Raw
1import type {
2 Day,
3 Era,
4 FirstWeekContainsDateOptions,
5 LocalizedOptions,
6 Month,
7 Quarter,
8 WeekOptions,
9} from "../types.js";
10/**
11 * The locale object with all functions and data needed to parse and format
12 * dates. This is what each locale implements and exports.
13 */
14export interface Locale {
15 /** The locale code (ISO 639-1 + optional country code) */
16 code: string;
17 /** The function to format distance */
18 formatDistance: FormatDistanceFn;
19 /** The function to relative time */
20 formatRelative: FormatRelativeFn;
21 /** The object with functions used to localize various values */
22 localize: Localize;
23 /** The object with functions that return localized formats */
24 formatLong: FormatLong;
25 /** The object with functions used to match and parse various localized values */
26 match: Match;
27 /** An object with locale options */
28 options?: LocaleOptions;
29}
30/**
31 * The locale options.
32 */
33export interface LocaleOptions
34 extends WeekOptions,
35 FirstWeekContainsDateOptions {}
36/**
37 * The function that takes a token (i.e. halfAMinute) passed by `formatDistance`
38 * or `formatDistanceStrict` and payload, and returns localized distance.
39 *
40 * @param token - The token to localize
41 * @param count - The distance number
42 * @param options - The object with options
43 *
44 * @returns The localized distance in words
45 */
46export type FormatDistanceFn = (
47 token: FormatDistanceToken,
48 count: number,
49 options?: FormatDistanceFnOptions,
50) => string;
51/**
52 * The {@link FormatDistanceFn} function options.
53 */
54export interface FormatDistanceFnOptions {
55 /** Add "X ago"/"in X" in the locale language */
56 addSuffix?: boolean;
57 /** The distance vector. -1 represents past and 1 future. Tells which suffix
58 * to use. */
59 comparison?: -1 | 0 | 1;
60}
61/**
62 * The function used inside the {@link FormatDistanceFn} function, implementing
63 * formatting for a particular token.
64 */
65export type FormatDistanceTokenFn = (
66 /** The distance as number to format */
67 count: number,
68 /** The object with options */
69 options?: FormatDistanceFnOptions,
70) => string;
71/**
72 * The tokens map to string templates used in the format distance function.
73 * It looks like this:
74 *
75 * const formatDistanceLocale: FormatDistanceLocale<FormatDistanceTokenValue> = {
76 * lessThanXSeconds: 'តិចជាង {{count}} វិនាទី',
77 * xSeconds: '{{count}} វិនាទី',
78 * // ...
79 * }
80 *
81 * @typeParam Template - The property value type.
82 */
83export type FormatDistanceLocale<Template> = {
84 [Token in FormatDistanceToken]: Template;
85};
86/**
87 * The token used in the format distance function. Represents the distance unit
88 * with prespecified precision.
89 */
90export type FormatDistanceToken =
91 | "lessThanXSeconds"
92 | "xSeconds"
93 | "halfAMinute"
94 | "lessThanXMinutes"
95 | "xMinutes"
96 | "aboutXHours"
97 | "xHours"
98 | "xDays"
99 | "aboutXWeeks"
100 | "xWeeks"
101 | "aboutXMonths"
102 | "xMonths"
103 | "aboutXYears"
104 | "xYears"
105 | "overXYears"
106 | "almostXYears";
107/**
108 * The locale function that does the work for the `formatRelative` function.
109 *
110 * @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).
111 *
112 * @param token - The token to localize
113 * @param date - The date to format
114 * @param baseDate - The date to compare with
115 * @param options - The object with options
116 *
117 * @returns The localized relative date format
118 */
119export type FormatRelativeFn = <DateType extends Date>(
120 token: FormatRelativeToken,
121 date: DateType,
122 baseDate: DateType,
123 options?: FormatRelativeFnOptions,
124) => string;
125/**
126 * The {@link FormatRelativeFn} function options.
127 */
128export interface FormatRelativeFnOptions
129 extends WeekOptions,
130 LocalizedOptions<"options" | "formatRelative"> {}
131/**
132 * The locale function used inside the {@link FormatRelativeFn} function
133 * implementing formatting for a particular token.
134 *
135 * @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).
136 *
137 * @param date - The date to format
138 * @param baseDate - The date to compare with
139 * @param options - The object with options
140 */
141export type FormatRelativeTokenFn = <DateType extends Date>(
142 date: DateType | number | string,
143 baseDate: DateType | number | string,
144 options?: FormatRelativeTokenFnOptions,
145) => string;
146/**
147 * The {@link FormatRelativeTokenFn} function options.
148 */
149export interface FormatRelativeTokenFnOptions extends WeekOptions {}
150/**
151 * The token used in format relative function. Represents the time unit.
152 */
153export type FormatRelativeToken =
154 | "lastWeek"
155 | "yesterday"
156 | "today"
157 | "tomorrow"
158 | "nextWeek"
159 | "other";
160/**
161 * A format part that represents a token or string literal, used by format parser/tokenizer
162 */
163export interface FormatPart {
164 /** If the part is a format token. */
165 isToken: boolean;
166 /** The format part value (i.e. `"do"`). */
167 value: string;
168}
169/**
170 * The object with functions used to localize various values. Part of the public
171 * locale API.
172 */
173export interface Localize {
174 /** The function that localizes an ordinal number */
175 ordinalNumber: LocalizeFn<number>;
176 /** The function that localized the era */
177 era: LocalizeFn<Era>;
178 /** The function that localizes the quarter */
179 quarter: LocalizeFn<Quarter>;
180 /** The function that localizes the month */
181 month: LocalizeFn<Month>;
182 /** The function that localizes the day of the week */
183 day: LocalizeFn<Day>;
184 /** The function that localizes the day period */
185 dayPeriod: LocalizeFn<LocaleDayPeriod>;
186 /** The function that can preprocess parts/tokens **/
187 preprocessor?: <DateType extends Date>(
188 date: DateType,
189 parts: FormatPart[],
190 ) => FormatPart[];
191}
192/**
193 * Individual localize function. Part of {@link Localize}.
194 *
195 * @typeParam Value - The value type to localize.
196 *
197 * @param value - The value to localize
198 * @param options - The object with options
199 *
200 * @returns The localized string
201 */
202export type LocalizeFn<Value extends LocaleUnitValue | number> = (
203 value: Value,
204 options?: LocalizeFnOptions,
205) => string;
206/**
207 * The {@link LocalizeFn} function options.
208 */
209export interface LocalizeFnOptions {
210 /** The width to use formatting the value, defines how short or long
211 * the formatted string might be. */
212 width?: LocaleWidth;
213 /** The context where the formatted value is used - standalone: the result
214 * should make grammatical sense as is and formatting: the result is a part
215 * of the formatted string. See: https://date-fns.org/docs/I18n-Contribution-Guide */
216 context?: "formatting" | "standalone";
217 /** The unit to format */
218 unit?: LocaleUnit;
219}
220/**
221 * The object with functions used to match and parse various localized values.
222 */
223export interface Match {
224 /** The function that parses a localized ordinal number. */
225 ordinalNumber: MatchFn<
226 number,
227 {
228 unit: LocaleUnit;
229 }
230 >;
231 /** The function that parses a localized era. */
232 era: MatchFn<Era>;
233 /** The function that parses a localized quarter. */
234 quarter: MatchFn<Quarter>;
235 /** The function that parses a localized month. */
236 month: MatchFn<Month>;
237 /** The function that parses a localized day of the week. */
238 day: MatchFn<Day>;
239 /** The function that parses a localized time of the day. */
240 dayPeriod: MatchFn<LocaleDayPeriod>;
241}
242/**
243 * The match function. Part of {@link Match}. Implements matcher for particular
244 * unit type.
245 *
246 * @typeParam Result - The matched value type.
247 * @typeParam ExtraOptions - The the extra options type.
248 *
249 * @param str - The string to match
250 * @param options - The object with options
251 *
252 * @returns The match result or null if match failed
253 */
254export type MatchFn<Result, ExtraOptions = Record<string, unknown>> = (
255 str: string,
256 options?: MatchFnOptions<Result> & ExtraOptions,
257) => MatchFnResult<Result> | null;
258/**
259 * The {@link MatchFn} function options.
260 *
261 * @typeParam Result - The matched value type.
262 */
263export interface MatchFnOptions<Result> {
264 /** The width to use matching the value, defines how short or long
265 * the matched string might be. */
266 width?: LocaleWidth;
267 /**
268 * @deprecated Map the value manually instead.
269 * @example
270 * const matchResult = locale.match.ordinalNumber('1st')
271 * if (matchResult) {
272 * matchResult.value = valueCallback(matchResult.value)
273 * }
274 */
275 valueCallback?: MatchValueCallback<string, Result>;
276}
277/**
278 * The function that allows to map the matched value to the actual type.
279 *
280 * @typeParam Arg - The argument type.
281 * @typeParam Result - The matched value type.
282 *
283 * @param arg - The value to match
284 *
285 * @returns The matched value
286 */
287export type MatchValueCallback<Arg, Result> = (value: Arg) => Result;
288/**
289 * The {@link MatchFn} function result.
290 *
291 * @typeParam Result - The matched value type.
292 */
293export interface MatchFnResult<Result> {
294 /** The matched value parsed as the corresponding unit type */
295 value: Result;
296 /** The remaining string after parsing */
297 rest: string;
298}
299/**
300 * The object with functions that return localized formats. Long stands for
301 * sequence of tokens (i.e. PPpp) that allows to define how format both date
302 * and time at once. Part of the public locale API.
303 */
304export interface FormatLong {
305 /** The function that returns a localized long date format */
306 date: FormatLongFn;
307 /** The function that returns a localized long time format */
308 time: FormatLongFn;
309 /** The function that returns a localized format of date and time combined */
310 dateTime: FormatLongFn;
311}
312/**
313 * The format long function. Formats date, time or both.
314 *
315 * @param options - The object with options
316 *
317 * @returns The localized string
318 */
319export type FormatLongFn = (options: FormatLongFnOptions) => string;
320/**
321 * The {@link FormatLongFn} function options.
322 */
323export interface FormatLongFnOptions {
324 /** Format width to set */
325 width?: FormatLongWidth;
326}
327/**
328 * The format long width token, defines how short or long the formnatted value
329 * might be. The actual result length is defined by the locale.
330 */
331export type FormatLongWidth = "full" | "long" | "medium" | "short" | "any";
332/**
333 * The formatting unit value, represents the raw value that can be formatted.
334 */
335export type LocaleUnitValue = Era | Quarter | Month | Day | LocaleDayPeriod;
336/**
337 * The format width. Defines how short or long the formatted string might be.
338 * The actaul result length depends on the locale.
339 */
340export type LocaleWidth = "narrow" | "short" | "abbreviated" | "wide" | "any";
341/**
342 * Token representing particular period of the day.
343 */
344export type LocaleDayPeriod =
345 | "am"
346 | "pm"
347 | "midnight"
348 | "noon"
349 | "morning"
350 | "afternoon"
351 | "evening"
352 | "night";
353/**
354 * The units commonly used in the date formatting or parsing.
355 */
356export type LocaleUnit =
357 | "second"
358 | "minute"
359 | "hour"
360 | "day"
361 | "dayOfYear"
362 | "date"
363 | "week"
364 | "month"
365 | "quarter"
366 | "year";