Debian Codegraph @

types-luxon/src/duration.d.ts

raw
1 import { CanBeInvalid, DefaultValidity, IfValid, Invalid, Valid } from "./_util";
2 import { ConversionAccuracy } from "./datetime";
3 import { NumberingSystem } from "./misc";
4
5 export interface DurationOptions {
6 locale?: string | undefined;
7 numberingSystem?: NumberingSystem | undefined;
8 conversionAccuracy?: ConversionAccuracy | undefined;
9 }
10
11 export interface DurationObjectUnits {
12 years?: number | undefined;
13 quarters?: number | undefined;
14 months?: number | undefined;
15 weeks?: number | undefined;
16 days?: number | undefined;
17 hours?: number | undefined;
18 minutes?: number | undefined;
19 seconds?: number | undefined;
20 milliseconds?: number | undefined;
21 }
22
23 export interface DurationLikeObject extends DurationObjectUnits {
24 year?: number | undefined;
25 quarter?: number | undefined;
26 month?: number | undefined;
27 week?: number | undefined;
28 day?: number | undefined;
29 hour?: number | undefined;
30 minute?: number | undefined;
31 second?: number | undefined;
32 millisecond?: number | undefined;
33 }
34
35 export type DurationUnit = keyof DurationLikeObject;
36 export type DurationUnits = DurationUnit | DurationUnit[];
37
38 export type ToISOFormat = "basic" | "extended";
39
40 export interface ToISOTimeDurationOptions {
41 /**
42 * Include the `T` prefix
43 * @default false
44 */
45 includePrefix?: boolean | undefined;
46 /**
47 * Exclude milliseconds from the format if they are 0
48 * @default false
49 */
50 suppressMilliseconds?: boolean | undefined;
51 /**
52 * Exclude seconds from the format if they are 0
53 * @default false
54 */
55 suppressSeconds?: boolean | undefined;
56 /**
57 * Choose between the basic and extended format
58 * @default 'extended'
59 */
60 format?: ToISOFormat | undefined;
61 }
62
63 export interface ToHumanDurationOptions extends Intl.NumberFormatOptions {
64 /**
65 * How to format the merged list.
66 * Corresponds to the `style` property of the options parameter of the native `Intl.ListFormat` constructor.
67 * @default 'narrow'
68 */
69 listStyle?: "long" | "short" | "narrow" | undefined;
70 /**
71 * Show all units previously used by the duration even if they are zero.
72 * @default true
73 */
74 showZeros?: boolean | undefined;
75 }
76
77 /**
78 * Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
79 *
80 * @deprecated Use DurationLike instead.
81 */
82 export type DurationInput = Duration | number | DurationLikeObject;
83
84 /**
85 * Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
86 */
87 export type DurationLike = Duration | DurationLikeObject | number;
88
89 export type DurationMaybeValid = CanBeInvalid extends true ? (Duration<Valid> | Duration<Invalid>) : Duration;
90
91 export interface DurationFormatOptions {
92 /**
93 * Whether or not to floor numerical values.
94 * @default true
95 */
96 floor?: boolean | undefined;
97 /**
98 * How to handle signs
99 * @default 'negative'
100 */
101 signMode?: "negative" | "all" | "negativeLargestOnly" | undefined;
102 }
103
104 /**
105 * A Duration object represents a period of time, like "2 months" or "1 day, 1 hour".
106 * Conceptually, it is just a map of units to their quantities, accompanied by some additional configuration and methods for creating, parsing, interrogating, transforming, and formatting them.
107 * They can be used on their own or in conjunction with other Luxon types; for example, you can use {@link DateTime.plus} to add a Duration object to a DateTime, producing another DateTime.
108 *
109 * Here is a brief overview of commonly used methods and getters in Duration:
110 *
111 * * **Creation** To create a Duration, use {@link Duration.fromMillis}, {@link Duration.fromObject}, or {@link Duration.fromISO}.
112 * * **Unit values** See the {@link Duration#years}, {@link Duration.months}, {@link Duration#weeks}, {@link Duration#days}, {@link Duration#hours}, {@link Duration#minutes},
113 * * {@link Duration#seconds}, {@link Duration#milliseconds} accessors.
114 * * **Configuration** See {@link Duration#locale} and {@link Duration#numberingSystem} accessors.
115 * * **Transformation** To create new Durations out of old ones use {@link Duration#plus}, {@link Duration#minus}, {@link Duration#normalize}, {@link Duration#set}, {@link Duration#reconfigure},
116 * * {@link Duration#shiftTo}, and {@link Duration#negate}.
117 * * **Output** To convert the Duration into other representations, see {@link Duration#as}, {@link Duration#toISO}, {@link Duration#toFormat}, and {@link Duration#toJSON}
118 *
119 * There's are more methods documented below. In addition, for more information on subtler topics like internationalization and validity, see the external documentation.
120 */
121 export class Duration<IsValid extends boolean = DefaultValidity> {
122 /**
123 * Create Duration from a number of milliseconds.
124 *
125 * @param count - of milliseconds
126 * @param opts - options for parsing
127 * @param opts.locale - the locale to use
128 * @param opts.numberingSystem - the numbering system to use
129 * @param opts.conversionAccuracy - the conversion system to use
130 */
131 static fromMillis(count: number, opts?: DurationOptions): Duration<Valid>;
132
133 /**
134 * Create a Duration from a JavaScript object with keys like 'years' and 'hours'.
135 * If this object is empty then a zero milliseconds duration is returned.
136 *
137 * @param obj - the object to create the Duration from
138 * @param obj.years
139 * @param obj.quarters
140 * @param obj.months
141 * @param obj.weeks
142 * @param obj.days
143 * @param obj.hours
144 * @param obj.minutes
145 * @param obj.seconds
146 * @param obj.milliseconds
147 * @param opts - options for creating this Duration. Defaults to {}.
148 * @param opts.locale - the locale to use. Defaults to 'en-US'.
149 * @param opts.numberingSystem - the numbering system to use
150 * @param opts.conversionAccuracy - the conversion system to use. Defaults to 'casual'.
151 */
152 static fromObject(obj: DurationLikeObject, opts?: DurationOptions): Duration<Valid>;
153
154 /**
155 * Create a Duration from DurationLike.
156 *
157 * @param durationLike
158 * Either a Luxon Duration, a number of milliseconds, or the object argument to Duration.fromObject()
159 */
160 static fromDurationLike(durationLike: DurationLike): Duration<Valid>;
161
162 /**
163 * Create a Duration from an ISO 8601 duration string.
164 * @see https://en.wikipedia.org/wiki/ISO_8601#Durations
165 *
166 * @param text - text to parse
167 * @param opts - options for parsing
168 * @param opts.locale - the locale to use. Defaults to 'en-US'.
169 * @param opts.numberingSystem - the numbering system to use
170 * @param opts.conversionAccuracy - the conversion system to use. Defaults to 'casual'.
171 *
172 * @example
173 * Duration.fromISO('P3Y6M1W4DT12H30M5S').toObject() //=> { years: 3, months: 6, weeks: 1, days: 4, hours: 12, minutes: 30, seconds: 5 }
174 * @example
175 * Duration.fromISO('PT23H').toObject() //=> { hours: 23 }
176 * @example
177 * Duration.fromISO('P5Y3M').toObject() //=> { years: 5, months: 3 }
178 */
179 static fromISO(text: string, opts?: DurationOptions): DurationMaybeValid;
180
181 /**
182 * Create a Duration from an ISO 8601 time string.
183 * @see https://en.wikipedia.org/wiki/ISO_8601#Times
184 *
185 * @param text - text to parse
186 * @param opts - options for parsing
187 * @param opts.locale - the locale to use. Defaults to 'en-US'.
188 * @param opts.numberingSystem - the numbering system to use
189 * @param opts.conversionAccuracy - the conversion system to use. Defaults to 'casual'.
190 *
191 * @example
192 * Duration.fromISOTime('11:22:33.444').toObject() //=> { hours: 11, minutes: 22, seconds: 33, milliseconds: 444 }
193 * @example
194 * Duration.fromISOTime('11:00').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
195 * @example
196 * Duration.fromISOTime('T11:00').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
197 * @example
198 * Duration.fromISOTime('1100').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
199 * @example
200 * Duration.fromISOTime('T1100').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
201 */
202 static fromISOTime(text: string, opts?: DurationOptions): DurationMaybeValid;
203
204 /**
205 * Create an invalid Duration.
206 *
207 * @param reason - simple string of why this datetime is invalid. Should not contain parameters or anything else data-dependent
208 * @param explanation - longer explanation, may include parameters and other useful debugging information. Defaults to null.
209 */
210 static invalid(reason: string, explanation?: string): Duration<Invalid>;
211
212 /**
213 * Check if an object is a Duration. Works across context boundaries
214 *
215 * @param o
216 */
217 static isDuration(o: unknown): o is DurationMaybeValid;
218
219 private constructor(config: unknown);
220
221 /**
222 * Get the locale of a Duration, such as 'en-GB'
223 */
224 get locale(): IfValid<string, null, IsValid>;
225
226 /**
227 * Get the numbering system of a Duration, such as 'beng'. The numbering system is used when formatting the Duration
228 */
229 get numberingSystem(): IfValid<string, null, IsValid>;
230
231 /**
232 * Returns a string representation of this Duration formatted according to the specified format string. You may use these tokens:
233 * * `S` for milliseconds
234 * * `s` for seconds
235 * * `m` for minutes
236 * * `h` for hours
237 * * `d` for days
238 * * `M` for months
239 * * `y` for years
240 * Notes:
241 * * Add padding by repeating the token, e.g. "yy" pads the years to two digits, "hhhh" pads the hours out to four digits
242 * * The duration will be converted to the set of units in the format string using {@link Duration.shiftTo} and the Duration's conversion accuracy setting.
243 *
244 * @example
245 * Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("y d s") //=> "1 6 2"
246 * @example
247 * Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("yy dd sss") //=> "01 06 002"
248 * @example
249 * Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("M S") //=> "12 518402000"
250 * @example
251 * Duration.fromObject({ days: 6, seconds: 2 }).toFormat("d s", { signMode: "all" }) //=> "+6 +2"
252 * @example
253 * Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", { signMode: "all" }) //=> "-6 -2"
254 * @example
255 * Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", { signMode: "negativeLargestOnly" }) //=> "-6 2"
256 */
257 toFormat(fmt: string, opts?: DurationFormatOptions): IfValid<string, "Invalid Duration", IsValid>;
258
259 /**
260 * Returns a string representation of a Duration with all units included
261 * To modify its behavior use the `listStyle` and any Intl.NumberFormat option, though `unitDisplay` is especially relevant. See {@link Intl.NumberFormat}.
262 *
263 * @example
264 * ```js
265 * var dur = Duration.fromObject({ months: 1, weeks: 0, hours: 5, minutes: 6 })
266 * dur.toHuman() //=> '1 month, 0 weeks, 5 hours, 6 minutes'
267 * dur.toHuman({ listStyle: "long" }) //=> '1 month, 0 weeks, 5 hours, and 6 minutes'
268 * dur.toHuman({ unitDisplay: "short" }) //=> '1 mth, 0 wks, 5 hr, 6 min'
269 * dur.toHuman({ showZeros: false }) //=> '1 month, 5 hours, 6 minutes'
270 * ```
271 */
272 toHuman(opts?: ToHumanDurationOptions): string;
273
274 /**
275 * Returns a JavaScript object with this Duration's values.
276 *
277 * @example
278 * Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toObject() //=> { years: 1, days: 6, seconds: 2 }
279 */
280 toObject(): DurationObjectUnits;
281
282 /**
283 * Returns an ISO 8601-compliant string representation of this Duration.
284 * @see https://en.wikipedia.org/wiki/ISO_8601#Durations
285 *
286 * @example
287 * Duration.fromObject({ years: 3, seconds: 45 }).toISO() //=> 'P3YT45S'
288 * @example
289 * Duration.fromObject({ months: 4, seconds: 45 }).toISO() //=> 'P4MT45S'
290 * @example
291 * Duration.fromObject({ months: 5 }).toISO() //=> 'P5M'
292 * @example
293 * Duration.fromObject({ minutes: 5 }).toISO() //=> 'PT5M'
294 * @example
295 * Duration.fromObject({ milliseconds: 6 }).toISO() //=> 'PT0.006S'
296 */
297 toISO(): IfValid<string, null, IsValid>;
298
299 /**
300 * Returns an ISO 8601-compliant string representation of this Duration, formatted as a time of day.
301 * @see https://en.wikipedia.org/wiki/ISO_8601#Times
302 *
303 * @param opts - options
304 * @param opts.suppressMilliseconds - exclude milliseconds from the format if they are 0. Defaults to false.
305 * @param opts.suppressSeconds - exclude seconds from the format if they're 0. Defaults to false.
306 * @param opts.includePrefix - include the `T` prefix. Defaults to false.
307 * @param opts.format - choose between the basic and extended format. Defaults to 'extended'.
308 *
309 * @example
310 * Duration.fromObject({ hours: 11 }).toISOTime() //=> '11:00:00.000'
311 * @example
312 * Duration.fromObject({ hours: 11 }).toISOTime({ suppressMilliseconds: true }) //=> '11:00:00'
313 * @example
314 * Duration.fromObject({ hours: 11 }).toISOTime({ suppressSeconds: true }) //=> '11:00'
315 * @example
316 * Duration.fromObject({ hours: 11 }).toISOTime({ includePrefix: true }) //=> 'T11:00:00.000'
317 * @example
318 * Duration.fromObject({ hours: 11 }).toISOTime({ format: 'basic' }) //=> '110000.000'
319 */
320 toISOTime(opts?: ToISOTimeDurationOptions): IfValid<string, null, IsValid>;
321
322 /**
323 * Returns an ISO 8601 representation of this Duration appropriate for use in JSON.
324 */
325 toJSON(): IfValid<string, null, IsValid>;
326
327 /**
328 * Returns an ISO 8601 representation of this Duration appropriate for use in debugging.
329 */
330 toString(): IfValid<string, null, IsValid>;
331
332 /**
333 * Returns a millisecond value of this Duration.
334 */
335 toMillis(): IfValid<number, typeof NaN, IsValid>;
336
337 /**
338 * Returns a millisecond value of this Duration. Alias of {@link toMillis}
339 */
340 valueOf(): IfValid<number, typeof NaN, IsValid>;
341
342 /**
343 * Make this Duration longer by the specified amount. Return a newly-constructed Duration.
344 *
345 * @param duration - The amount to add. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
346 */
347 plus(duration: DurationLike): this;
348
349 /**
350 * Make this Duration shorter by the specified amount. Return a newly-constructed Duration.
351 *
352 * @param duration - The amount to subtract. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
353 */
354 minus(duration: DurationLike): this;
355
356 /**
357 * Scale this Duration by the specified amount. Return a newly-constructed Duration.
358 *
359 * @example
360 * Duration.fromObject({ hours: 1, minutes: 30 }).mapUnit(x => x * 2) //=> { hours: 2, minutes: 60 }
361 * @example
362 * Duration.fromObject({ hours: 1, minutes: 30 }).mapUnit((x, u) => u === "hour" ? x * 2 : x) //=> { hours: 2, minutes: 30 }
363 */
364 mapUnits(fn: (x: number, u?: DurationUnit) => number): this;
365
366 /**
367 * Get the value of unit.
368 *
369 * @param unit - a unit such as 'minute' or 'day'
370 *
371 * @example
372 * Duration.fromObject({years: 2, days: 3}).get('years') //=> 2
373 * @example
374 * Duration.fromObject({years: 2, days: 3}).get('months') //=> 0
375 * @example
376 * Duration.fromObject({years: 2, days: 3}).get('days') //=> 3
377 */
378 get(unit: DurationUnit): IfValid<number, typeof NaN, IsValid>;
379
380 /**
381 * "Set" the values of specified units. Return a newly-constructed Duration.
382 *
383 * @param values - a mapping of units to numbers
384 *
385 * @example
386 * dur.set({ years: 2017 })
387 * @example
388 * dur.set({ hours: 8, minutes: 30 })
389 */
390 set(values: DurationLikeObject): this;
391
392 /**
393 * "Set" the locale and/or numberingSystem. Returns a newly-constructed Duration.
394 *
395 * @example
396 * dur.reconfigure({ locale: 'en-GB' })
397 */
398 reconfigure(opts?: DurationOptions): this;
399
400 /**
401 * Return the length of the duration in the specified unit.
402 *
403 * @param unit - a unit such as 'minutes' or 'days'
404 *
405 * @example
406 * Duration.fromObject({years: 1}).as('days') //=> 365
407 * @example
408 * Duration.fromObject({years: 1}).as('months') //=> 12
409 * @example
410 * Duration.fromObject({hours: 60}).as('days') //=> 2.5
411 */
412 as(unit: DurationUnit): IfValid<number, typeof NaN, IsValid>;
413
414 /**
415 * Reduce this Duration to its canonical representation in its current units.
416 *
417 * @example
418 * Duration.fromObject({ years: 2, days: 5000 }).normalize().toObject() //=> { years: 15, days: 255 }
419 * @example
420 * Duration.fromObject({ hours: 12, minutes: -45 }).normalize().toObject() //=> { hours: 11, minutes: 15 }
421 */
422 normalize(): this;
423
424 /**
425 * Rescale units to its largest representation.
426 *
427 * @example
428 * Duration.fromObject({ milliseconds: 90000 }).rescale().toObject() //=> { minutes: 1, seconds: 30 }
429 */
430 rescale(): this;
431
432 /**
433 * Convert this Duration into its representation in a different set of units.
434 *
435 * @example
436 * Duration.fromObject({ hours: 1, seconds: 30 }).shiftTo('minutes', 'milliseconds').toObject() //=> { minutes: 60, milliseconds: 30000 }
437 */
438 shiftTo(...units: DurationUnit[]): this;
439
440 /**
441 * Shift this Duration to all available units.
442 * Same as shiftTo("years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds")
443 */
444 shiftToAll(): this;
445
446 /**
447 * Return the negative of this Duration.
448 *
449 * @example
450 * Duration.fromObject({ hours: 1, seconds: 30 }).negate().toObject() //=> { hours: -1, seconds: -30 }
451 */
452 negate(): this;
453
454 /**
455 * Removes all units with values equal to 0 from this Duration.
456 *
457 * @example
458 * Duration.fromObject({ years: 2, days: 0, hours: 0, minutes: 0 }).removeZeros().toObject() //=> { years: 2 }
459 */
460 removeZeros(): this;
461
462 /**
463 * Get the years.
464 */
465 get years(): IfValid<number, typeof NaN, IsValid>;
466
467 /**
468 * Get the quarters.
469 */
470 get quarters(): IfValid<number, typeof NaN, IsValid>;
471
472 /**
473 * Get the months.
474 */
475 get months(): IfValid<number, typeof NaN, IsValid>;
476
477 /**
478 * Get the weeks
479 */
480 get weeks(): IfValid<number, typeof NaN, IsValid>;
481
482 /**
483 * Get the days.
484 */
485 get days(): IfValid<number, typeof NaN, IsValid>;
486
487 /**
488 * Get the hours.
489 */
490 get hours(): IfValid<number, typeof NaN, IsValid>;
491
492 /**
493 * Get the minutes.
494 */
495 get minutes(): IfValid<number, typeof NaN, IsValid>;
496
497 /**
498 * Get the seconds.
499 */
500 get seconds(): IfValid<number, typeof NaN, IsValid>;
501
502 /**
503 * Get the milliseconds.
504 */
505 get milliseconds(): IfValid<number, typeof NaN, IsValid>;
506
507 /**
508 * Returns whether the Duration is invalid.
509 * Diff operations on invalid DateTimes or Intervals return invalid Durations.
510 */
511 get isValid(): IfValid<true, false, IsValid>;
512
513 /**
514 * Returns an error code if this Duration became invalid, or null if the Duration is valid
515 */
516 get invalidReason(): IfValid<null, string, IsValid>;
517
518 /**
519 * Returns an explanation of why this Duration became invalid, or null if the Duration is valid
520 */
521 get invalidExplanation(): IfValid<null, string | null, IsValid>;
522
523 /**
524 * Equality check
525 * Two Durations are equal iff they have the same units and the same values for each unit.
526 */
527 equals(other: Duration): IfValid<boolean, false, IsValid>;
528 }