Make moment's typings for parsing stricter and also allow them to accept union types.

This commit was adapted from 1ec036686e70ad0d837ed2443684d54bca13af01 in DefinitelyTyped.
See https://github.com/DefinitelyTyped/DefinitelyTyped/pull/8765 for context. The original
body of the commit message follows.

These changes do two things.

1. Replace very lax typings like `any[]` with stricter, more-correct versions. In particular,
the ISO_8601 constant, while /technically/ a void function, is actually an opaque sentinel
that a consumer should not know anything about it. The function type was replaced with a
sentinel type using the principle of "brands" that can be seen in the Typescript compiler:
https://github.com/Microsoft/TypeScript/blob/413d9a639f933df7539070b236c1677de8302a93/src/compiler/types.ts#L9

2. Replace the many overloads of the parsing methods with a smaller representative set that
uses union types instead. Aside from succinctness, this allows callers to provide a union
type as the argument, as long as it matches, which was not possible before (Typescript does
not explode the union type to see if overloads cover all the possibilities).

diff --git a/moment.d.ts b/moment.d.ts
index 618d96c9bb593c71ca8a7bf1b57e61041381b52a..560317b478bc978265066f88ee566c9b11c3f9b4 100644 (file)
--- a/moment.d.ts
+++ b/moment.d.ts
@@ -1,14 +1,8 @@
 declare function moment(): moment.Moment;
 declare function moment(date: number): moment.Moment;
 declare function moment(date: number[]): moment.Moment;
-declare function moment(date: string, format?: string, strict?: boolean): moment.Moment;
-declare function moment(date: string, format?: string, language?: string, strict?: boolean): moment.Moment;
-declare function moment(date: string, formats: string[], strict?: boolean): moment.Moment;
-declare function moment(date: string, formats: string[], language?: string, strict?: boolean): moment.Moment;
-declare function moment(date: string, specialFormat: () => void, strict?: boolean): moment.Moment;
-declare function moment(date: string, specialFormat: () => void, language?: string, strict?: boolean): moment.Moment;
-declare function moment(date: string, formatsIncludingSpecial: any[], strict?: boolean): moment.Moment;
-declare function moment(date: string, formatsIncludingSpecial: any[], language?: string, strict?: boolean): moment.Moment;
+declare function moment(date: string, format?: moment.MomentFormatSpecification, strict?: boolean): moment.Moment;
+declare function moment(date: string, format?: moment.MomentFormatSpecification, language?: string, strict?: boolean): moment.Moment;
 declare function moment(date: Date): moment.Moment;
 declare function moment(date: moment.Moment): moment.Moment;
 declare function moment(date: Object): moment.Moment;
@@ -177,18 +171,18 @@ declare namespace moment {
   }
 
   interface MomentParsingFlags {
-     empty: boolean;
-     unusedTokens: string[];
-     unusedInput: string[];
-     overflow: number;
-     charsLeftOver: number;
-     nullInput: boolean;
-     invalidMonth?: string;
-     invalidFormat: boolean;
-     userInvalidated: boolean;
-     iso: boolean;
-     parsedDateParts: any[];
-     meridiem?: string;
+    empty: boolean;
+    unusedTokens: string[];
+    unusedInput: string[];
+    overflow: number;
+    charsLeftOver: number;
+    nullInput: boolean;
+    invalidMonth?: string;
+    invalidFormat: boolean;
+    userInvalidated: boolean;
+    iso: boolean;
+    parsedDateParts: any[];
+    meridiem?: string;
   }
 
   interface BaseMomentLanguage {
@@ -209,10 +203,16 @@ declare namespace moment {
   }
 
   interface MomentLanguageWeek {
-      dow?: number;
-      doy?: number;
+    dow?: number;
+    doy?: number;
   }
 
+  interface MomentBuiltinFormat {
+    __momentBuiltinFormatBrand: any;
+  }
+
+  type MomentFormatSpecification = string | MomentBuiltinFormat | (string | MomentBuiltinFormat)[];
+
   type UnitOfTime = ("year" | "years" | "y" |
               "quarter" | "quarters" | "Q" |
               "month" | "months" | "M" |
@@ -548,7 +548,7 @@ declare namespace moment {
   /**
   * Constant used to enable explicit ISO_8601 format parsing.
   */
-  export function ISO_8601(): void;
+  export var ISO_8601: MomentBuiltinFormat;
 
   export var defaultFormat: string;
 }