Skip to content

Commit d9965cc

Browse files
CarsonFCarsonF
authored
🤖 Merge PR DefinitelyTyped#72377 [Luxon] Small refactor & docs polish by @CarsonF 
1 parent c32d133 commit d9965cc

File tree

1 file changed

+122
-44
lines changed

1 file changed

+122
-44
lines changed

‎types/luxon/src/datetime.d.ts‎

Lines changed: 122 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -406,6 +406,86 @@ export interface TokenParser {
406406
[tokenParserBrand]: true;
407407
}
408408

409+
type ManyDateTimes = Array<DateTime<boolean>>;
410+
411+
export type PickedDateTime<Values extends ManyDateTimes> = Values extends [] ? undefined
412+
:
413+
| (Values extends Array<DateTime<infer AllValues>> ?
414+
| (AllValues extends true ? DateTime<Valid> : never)
415+
| (AllValues extends false ? DateTime<Invalid> : never)
416+
: never)
417+
| ([] extends Values ? undefined : never);
418+
419+
/**
420+
* # Table of tokens
421+
*
422+
* (The example values below come from this time `2014-08-06T13:07:04.054`
423+
* considered as a local time in America/New_York).
424+
*
425+
* Note that many tokens supported by the formatter are **not** supported by the parser.
426+
*
427+
* | Standalone token | Format token | Description | Example |
428+
* | ---------------- | ------------ | ----------------------------------------------------------------- | --------------------------- |
429+
* | S | | millisecond, no padding | `54` |
430+
* | SSS | | millisecond, padded to 3 | `054` |
431+
* | u | | fractional seconds, (5 is a half second, 54 is slightly more) | `54` |
432+
* | uu | | fractional seconds, (one or two digits) | `05` |
433+
* | uuu | | fractional seconds, (only one digit) | `5` |
434+
* | s | | second, no padding | `4` |
435+
* | ss | | second, padded to 2 padding | `04` |
436+
* | m | | minute, no padding | `7` |
437+
* | mm | | minute, padded to 2 | `07` |
438+
* | h | | hour in 12-hour time, no padding | `1` |
439+
* | hh | | hour in 12-hour time, padded to 2 | `01` |
440+
* | H | | hour in 24-hour time, no padding | `13` |
441+
* | HH | | hour in 24-hour time, padded to 2 | `13` |
442+
* | Z | | narrow offset | `+5` |
443+
* | ZZ | | short offset | `+05:00` |
444+
* | ZZZ | | techie offset | `+0500` |
445+
* | z | | IANA zone | `America/New_York` |
446+
* | a | | meridiem | `AM` |
447+
* | d | | day of the month, no padding | `6` |
448+
* | dd | | day of the month, padded to 2 | `06` |
449+
* | E | c | day of the week, as number from 1-7 (Monday is 1, Sunday is 7) | `3` |
450+
* | EEE | ccc | day of the week, as an abbreviate localized string | `Wed` |
451+
* | EEEE | cccc | day of the week, as an unabbreviated localized string | `Wednesday` |
452+
* | M | L | month as an unpadded number | `8` |
453+
* | MM | LL | month as an padded number | `08` |
454+
* | MMM | LLL | month as an abbreviated localized string | `Aug` |
455+
* | MMMM | LLLL | month as an unabbreviated localized string | `August` |
456+
* | y | | year, 1-6 digits, very literally | `2014` |
457+
* | yy | | two-digit year, interpreted as > 1960 by default (also accepts 4) | `14` |
458+
* | yyyy | | four-digit year | `2014` |
459+
* | yyyyy | | four- to six-digit years | `10340` |
460+
* | yyyyyy | | six-digit years | `010340` |
461+
* | G | | abbreviated localized era | `AD` |
462+
* | GG | | unabbreviated localized era | `Anno Domini` |
463+
* | GGGGG | | one-letter localized era | `A` |
464+
* | kk | | ISO week year, unpadded | `17` |
465+
* | kkkk | | ISO week year, padded to 4 | `2014` |
466+
* | W | | ISO week number, unpadded | `32` |
467+
* | WW | | ISO week number, padded to 2 | `32` |
468+
* | o | | ordinal (day of year), unpadded | `218` |
469+
* | ooo | | ordinal (day of year), padded to 3 | `218` |
470+
* | q | | quarter, no padding | `3` |
471+
* | D | | localized numeric date | `9/6/2014` |
472+
* | DD | | localized date with abbreviated month | `Aug 6, 2014` |
473+
* | DDD | | localized date with full month | `August 6, 2014` |
474+
* | DDDD | | localized date with full month and weekday | `Wednesday, August 6, 2014` |
475+
* | t | | localized time | `1:07 AM` |
476+
* | tt | | localized time with seconds | `1:07:04 PM` |
477+
* | T | | localized 24-hour time | `13:07` |
478+
* | TT | | localized 24-hour time with seconds | `13:07:04` |
479+
* | f | | short localized date and time | `8/6/2014, 1:07 PM` |
480+
* | ff | | less short localized date and time | `Aug 6, 2014, 1:07 PM` |
481+
* | F | | short localized date and time with seconds | `8/6/2014, 1:07:04 PM` |
482+
* | FF | | less short localized date and time with seconds | `Aug 6, 2014, 1:07:04 PM` |
483+
* | ' | | literal start/end, characters between are not tokenized | `'T'` |
484+
*
485+
* Sourced from [here](https://moment.github.io/luxon/#/parsing?id=table-of-tokens).
486+
*/
487+
type Tokens = string;
488+
409489
/**
410490
* A DateTime is an immutable data structure representing a specific date and time and accompanying methods.
411491
* It contains class and instance methods for creating, parsing, interrogating, transforming, and formatting them.
@@ -720,24 +800,33 @@ export class DateTime<IsValid extends boolean = DefaultValidity> {
720800

721801
/**
722802
* Create a DateTime from an input string and format string.
723-
* Defaults to en-US if no locale has been specified, regardless of the system's locale. For a table of tokens and their interpretations,
803+
*
804+
* Defaults to en-US if no locale has been specified, regardless of the system's locale.
805+
*
806+
* For a table of tokens and their interpretations,
724807
* see [here](https://moment.github.io/luxon/#/parsing?id=table-of-tokens).
725808
*
726809
* @param text - the string to parse
727-
* @param fmt - the format the string is expected to be in (see the link below for the formats)
810+
* @param format - the format the string is expected to be in (see the link below for the formats)
728811
* @param opts - options to affect the creation
729-
* @param opts.zone - use this zone if no offset is specified in the input string itself. Will also convert the DateTime to this zone. Defaults to 'local'.
730-
* @param opts.setZone - override the zone with a zone specified in the string itself, if it specifies one. Defaults to false.
731-
* @param opts.locale - a locale string to use when parsing. Will also set the DateTime to this locale. Defaults to 'en-US'.
732-
* @param opts.numberingSystem - the numbering system to use when parsing. Will also set the resulting DateTime to this numbering system
812+
* @param opts.zone - use this zone if no offset is specified in the input string itself.
813+
* Will also convert the DateTime to this zone.
814+
* Defaults to 'local'.
815+
* @param opts.setZone - override the zone with a zone specified in the string itself, if it specifies one.
816+
* Defaults to false.
817+
* @param opts.locale - a locale string to use when parsing.
818+
* Will also set the DateTime to this locale.
819+
* Defaults to 'en-US'.
820+
* @param opts.numberingSystem - the numbering system to use when parsing.
821+
* Will also set the resulting DateTime to this numbering system
733822
* @param opts.outputCalendar - the output calendar to set on the resulting DateTime instance
734823
*/
735-
static fromFormat(text: string, fmt: string, opts?: DateTimeOptions): DateTimeMaybeValid;
824+
static fromFormat(text: string, format: Tokens, opts?: DateTimeOptions): DateTimeMaybeValid;
736825

737826
/**
738827
* @deprecated use fromFormat instead
739828
*/
740-
static fromString(text: string, format: string, options?: DateTimeOptions): DateTimeMaybeValid;
829+
static fromString(text: string, format: Tokens, options?: DateTimeOptions): DateTimeMaybeValid;
741830

742831
/**
743832
* Create a DateTime from a SQL date, time, or datetime
@@ -798,11 +887,13 @@ export class DateTime<IsValid extends boolean = DefaultValidity> {
798887

799888
/**
800889
* Produce the fully expanded format token for the locale
890+
*
801891
* Does NOT quote characters, so quoted tokens will not round trip correctly
802-
* @param fmt - the format string
803-
* @param localeOpts - Opts to override the configuration options on this DateTime
892+
*
893+
* @param format - the format string - see {@link Tokens}
894+
* @param localeOptions - Options to override the configuration options on this DateTime
804895
*/
805-
static expandFormat(fmt: string, localeOpts?: LocaleOptions): string;
896+
static expandFormat(format: Tokens, localeOptions?: LocaleOptions): string;
806897

807898
private constructor(config: unknown);
808899

@@ -1260,8 +1351,8 @@ export class DateTime<IsValid extends boolean = DefaultValidity> {
12601351
* see [here](https://moment.github.io/luxon/#/formatting?id=table-of-tokens).
12611352
* Defaults to en-US if no locale has been specified, regardless of the system's locale.
12621353
*
1263-
* @param fmt - the format string
1264-
* @param opts - opts to override the configuration options on this DateTime
1354+
* @param format - the format string - see {@link Tokens}
1355+
* @param options - opts to override the configuration options on this DateTime
12651356
*
12661357
* @example
12671358
* DateTime.now().toFormat('yyyy LLL dd') //=> '2017 Apr 22'
@@ -1272,7 +1363,7 @@ export class DateTime<IsValid extends boolean = DefaultValidity> {
12721363
* @example
12731364
* DateTime.now().toFormat("HH 'hours and' mm 'minutes'") //=> '20 hours and 55 minutes'
12741365
*/
1275-
toFormat(fmt: string, opts?: LocaleOptions): IfValid<string, "Invalid DateTime", IsValid>;
1366+
toFormat(format: Tokens, options?: LocaleOptions): IfValid<string, "Invalid DateTime", IsValid>;
12761367

12771368
/**
12781369
* Returns a localized string representing this date. Accepts the same options as the Intl.DateTimeFormat constructor and any presets defined by Luxon,
@@ -1596,65 +1687,52 @@ export class DateTime<IsValid extends boolean = DefaultValidity> {
15961687
*
15971688
* @param dateTimes - the DateTimes from which to choose the minimum
15981689
*/
1599-
static min<Values extends Array<DateTime<boolean>>>(
1600-
...dateTimes: Values
1601-
): Values extends [] ? undefined
1602-
:
1603-
| (Values extends Array<DateTime<infer AllValues>> ? AllValues extends true ? DateTime<Valid> : never
1604-
: never)
1605-
| (Values extends Array<DateTime<infer AllValues>> ? AllValues extends false ? DateTime<Invalid> : never
1606-
: never)
1607-
| ([] extends Values ? undefined : never);
1690+
static min<Values extends ManyDateTimes>(...dateTimes: Values): PickedDateTime<Values>;
16081691

16091692
/**
16101693
* Return the max of several date times
16111694
*
16121695
* @param dateTimes - the DateTimes from which to choose the maximum
16131696
*/
1614-
static max<Values extends Array<DateTime<boolean>>>(
1615-
...dateTimes: Values
1616-
): Values extends [] ? undefined
1617-
:
1618-
| (Values extends Array<DateTime<infer AllValues>> ? AllValues extends true ? DateTime<Valid> : never
1619-
: never)
1620-
| (Values extends Array<DateTime<infer AllValues>> ? AllValues extends false ? DateTime<Invalid> : never
1621-
: never)
1622-
| ([] extends Values ? undefined : never);
1697+
static max<Values extends ManyDateTimes>(...dateTimes: Values): PickedDateTime<Values>;
16231698

16241699
// MISC
16251700

16261701
/**
1627-
* Explain how a string would be parsed by fromFormat()
1702+
* Explain how a string would be parsed by {@link fromFormat}
16281703
*
16291704
* @param text - the string to parse
1630-
* @param fmt - the format the string is expected to be in (see description)
1631-
* @param options - options taken by fromFormat()
1705+
* @param format - the format the string is expected to be in - see {@link Tokens}
1706+
* @param options - options taken by {@link fromFormat}
16321707
*/
1633-
static fromFormatExplain(text: string, fmt: string, options?: DateTimeOptions): ExplainedFormat;
1708+
static fromFormatExplain(text: string, format: Tokens, options?: DateTimeOptions): ExplainedFormat;
16341709

16351710
/**
1636-
* @deprecated use fromFormatExplain instead
1711+
* @deprecated use {@link fromFormatExplain} instead
16371712
*/
1638-
static fromStringExplain(text: string, fmt: string, options?: DateTimeOptions): ExplainedFormat;
1713+
static fromStringExplain(text: string, format: Tokens, options?: DateTimeOptions): ExplainedFormat;
16391714

16401715
/**
1641-
* Build a parser for fmt using the given locale. This parser can be passed to {@link DateTime.fromFormatParser} to a parse a date in this format. This can be used to optimize cases where many dates need to be parsed in a specific format.
1716+
* Build a parser for a given format using the given locale.
1717+
*
1718+
* This parser can be passed to {@link fromFormatParser} to a parse a date in this format.
1719+
* This can be used to optimize cases where many dates need to be parsed in a specific format.
16421720
*
1643-
* @param fmt - the format the string is expected to be in (see description)
1721+
* @param format - the format the string is expected to be in - see {@link Tokens}
16441722
* @param options - the Locale options
16451723
*/
1646-
static buildFormatParser(fmt: string, options?: LocaleOptions): TokenParser;
1724+
static buildFormatParser(format: Tokens, options?: LocaleOptions): TokenParser;
16471725

16481726
/**
16491727
* Create a DateTime from an input string and format parser.
16501728
*
16511729
* The format parser must have been created with the same locale as this call.
16521730
*
16531731
* @param text the string to parse
1654-
* @param formatParser - parser from {@link DateTime.buildFormatParser}
1655-
* @param opts options taken by fromFormat()
1732+
* @param parser - parser from {@link buildFormatParser}
1733+
* @param options options taken by {@link fromFormat}
16561734
*/
1657-
static fromFormatParser(text: string, formatParser: TokenParser, opts?: DateTimeOptions): DateTimeMaybeValid;
1735+
static fromFormatParser(text: string, parser: TokenParser, options?: DateTimeOptions): DateTimeMaybeValid;
16581736

16591737
// FORMAT PRESETS
16601738

0 commit comments

Comments
 (0)