From: Sean Kelley <seansfkelley@gmail.com>
Date: Sun, 24 Jul 2016 09:45:09 +0000 (+0200)
Subject: Make moment's typings for parsing stricter and also allow them to accept union types.
X-Git-Tag: 2.15.0~5^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0866ff94f3cf02f1a7b885daec2b4ad2e045301a;p=thirdparty%2Fmoment.git

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 618d96c9b..560317b47 100644
--- 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;
 }