[flow][enums] Add Enum type, which can represet any Flow Enum

Summary:
Changelog: [feature] Added a new global type `Enum<>`, which represents all Flow Enums (this is a complement to the new `EnumValue` type). You can constrain the enums to ones which have a particular enum value, e.g. `Enum<>` is the same as `Enum<EnumValue<>>`, and the type of all enums with string representation types is `Enum<EnumValue<string>>`. These "abstract enums" have no know members, so you can't access members or exhaustively check them, but you can use methods such as `.members()`, `.cast()`, etc.

The `Enum` type uses the `EnumType` type destructor, which uses the `GetEnumT` use_t.

Reviewed By: SamChou19815

Differential Revision: D55536911

fbshipit-source-id: bbe5c1498add6a9e5c0c06222c4b4f597de78473

Author: gkz

lib/core.js

@@ -2838,3 +2838,12 @@ type $EnumValueProto<TEnumObject, TRepresentationType> = {|
   valueOf(this: TEnumObject): TRepresentationType,
   __proto__: null,
 |};
+
+/**
+ * Represents a generic Flow Enum - the enum itself rather than its values.
+ * You can supply a type argument to restrict to Flow Enums with a certain
+ * enum value (take a look at the `EnumValue` type for more).
+ * You can use the Flow Enum methods like `.cast` and `.members` on a value
+ * of this type, but it does not have any specific members which you can access.
+ */
+type Enum<+TEnumValue: EnumValue<> = EnumValue<>> = $Enum<TEnumValue>;

src/common/ty/ty.ml

@@ -267,6 +267,7 @@ and utility =
   | Diff of t * t
   | Rest of t * t
   | ElementType of t * t
+  | Enum of t
   | NonMaybeType of t
   | ObjMap of t * t
   | ObjMapi of t * t
@@ -677,6 +678,7 @@ class ['A] comparator_ty =
       | Required _ -> 24
       | ObjMapConst _ -> 25
       | ReactCheckComponentRef _ -> 26
+      | Enum _ -> 27
 
     method tag_of_polarity _ =
       function
@@ -830,6 +832,7 @@ let string_of_utility_ctor = function
   | Partial _ -> "Partial"
   | Required _ -> "Required"
   | Exact _ -> "$Exact"
+  | Enum _ -> "Enum"
   | Diff _ -> "$Diff"
   | Rest _ -> "$Rest"
   | ElementType _ -> "$ElementType"
@@ -857,6 +860,7 @@ let types_of_utility = function
   | Diff (t1, t2) -> Some [t1; t2]
   | Rest (t1, t2) -> Some [t1; t2]
   | ElementType (t1, t2) -> Some [t1; t2]
+  | Enum t -> Some [t]
   | NonMaybeType t -> Some [t]
   | ObjMap (t1, t2) -> Some [t1; t2]
   | ObjMapi (t1, t2) -> Some [t1; t2]

src/parser_utils/type_sig/type_sig.ml

@@ -531,6 +531,7 @@ type ('loc, 'a) annot =
       elem: 'a;
     }
   | EnumValue of 'loc * 'a
+  | Enum of 'loc * 'a
   | OptionalIndexedAccessNonMaybeType of {
       loc: 'loc;
       obj: 'a;

src/parser_utils/type_sig/type_sig_parse.ml

@@ -2330,6 +2330,13 @@ and maybe_special_unqualified_generic opts scope tbls xs loc targs ref_loc =
       Annot (EnumValue (loc, t))
     | _ -> Err (loc, CheckError)
   end
+  | "$Enum" -> begin
+    match targs with
+    | Some (_, { arguments = [t]; _ }) ->
+      let t = annot opts scope tbls xs t in
+      Annot (Enum (loc, t))
+    | _ -> Err (loc, CheckError)
+  end
   | "$NonMaybeType" -> begin
     match targs with
     | Some (_, { arguments = [t]; _ }) ->

src/typing/annotation_inference.ml

@@ -39,6 +39,7 @@ let object_like_op = function
   | Annot_ObjKeyMirror _
   | Annot_ObjMapConst _
   | Annot_GetKeysT _
+  | Annot_GetEnumT _
   | Annot_DeepReadOnlyT _
   | Annot_ToStringT _
   | Annot__Future_added_value__ _ ->
@@ -500,6 +501,9 @@ module rec ConsGen : S = struct
     | (EvalT (t, TypeDestructorT (use_op, reason, ElementType { index_type }), _), _) ->
       let t = elab_t cx t (Annot_GetElemT (reason, use_op, index_type)) in
       elab_t cx t op
+    | (EvalT (t, TypeDestructorT (_, reason, EnumType), _), _) ->
+      let t = elab_t cx t (Annot_GetEnumT reason) in
+      elab_t cx t op
     | (EvalT (_, TypeDestructorT (_, _, TypeMap (ObjectMap _)), _), _) ->
       error_unsupported ~suggestion:"$ObjMapConst" cx t op
     | (EvalT (_, TypeDestructorT (_, _, TypeMap (ObjectMapi _)), _), _) ->
@@ -575,9 +579,9 @@ module rec ConsGen : S = struct
       (* a component syntax value annotation becomes an element of that component *)
       get_builtin_typeapp cx reason "React$Element" [l]
     | (DefT (_, TypeT (_, l)), Annot_UseT_TypeT _) -> l
-    | (DefT (lreason, EnumObjectT enum_info), Annot_UseT_TypeT _) ->
-      (* an enum object value annotation becomes the enum type *)
-      mk_enum_type lreason enum_info
+    | (DefT (_, EnumObjectT { enum_value_t; _ }), Annot_UseT_TypeT _) ->
+      (* an enum object value annotation becomes the enum value type *)
+      enum_value_t
     | (DefT (enum_reason, EnumValueT _), Annot_UseT_TypeT (reason, _)) ->
       Flow_js_utils.add_output cx Error_message.(EEnumMemberUsedAsType { reason; enum_reason });
       AnyT.error reason
@@ -1101,6 +1105,8 @@ module rec ConsGen : S = struct
       Flow_js_utils.obj_key_mirror cx o reason_op
     | (DefT (_, ObjT o), Annot_ObjMapConst (reason_op, target)) ->
       Flow_js_utils.obj_map_const cx o reason_op target
+    | (DefT (_, EnumValueT enum_info), Annot_GetEnumT reason) ->
+      DefT (reason, EnumObjectT { enum_value_t = t; enum_info })
     (***********************)
     (* Opaque types (pt 2) *)
     (***********************)
@@ -1138,11 +1144,10 @@ module rec ConsGen : S = struct
     (*********)
     (* Enums *)
     (*********)
-    | ( DefT (enum_reason, EnumObjectT enum_info),
+    | ( DefT (enum_reason, EnumObjectT { enum_value_t; enum_info = ConcreteEnum enum_info }),
         Annot_GetPropT (access_reason, use_op, Named { reason = prop_reason; name; _ })
       ) ->
       let access = (use_op, access_reason, None, (prop_reason, name)) in
-      let enum_value_t = mk_enum_type enum_reason enum_info in
       GetPropTKit.on_EnumObjectT
         cx
         dummy_trace

src/typing/debug_js.ml

@@ -36,6 +36,7 @@ let string_of_destructor = function
   | NonMaybeType -> "NonMaybeType"
   | PropertyType { name; _ } -> spf "PropertyType %s" (display_string_of_name name)
   | ElementType _ -> "ElementType"
+  | EnumType -> "EnumType"
   | OptionalIndexedAccessNonMaybeType _ -> "OptionalIndexedAccessNonMaybeType"
   | OptionalIndexedAccessResultType _ -> "OptionalIndexedAccessResultType"
   | ReadOnlyType -> "ReadOnly"
@@ -270,7 +271,8 @@ let rec dump_t_ (depth, tvars) cx t =
     | DefT (_, InstanceT inst_t) -> p ~extra:(instance_t inst_t) t
     | DefT (_, TypeT (kind, arg)) ->
       p ~extra:(spf "%s, %s" (string_of_type_t_kind kind) (kid arg)) t
-    | DefT (_, EnumValueT (AbstractEnum { representation_t })) ->
+    | DefT (_, EnumValueT (AbstractEnum { representation_t }))
+    | DefT (_, EnumObjectT { enum_info = AbstractEnum { representation_t }; _ }) ->
       p ~extra:(spf "abstract: %s" (kid representation_t)) t
     | DefT
         ( _,
@@ -282,7 +284,12 @@ let rec dump_t_ (depth, tvars) cx t =
     | DefT
         ( _,
           EnumObjectT
-            { enum_name; enum_id; members = _; representation_t = _; has_unknown_members = _ }
+            {
+              enum_info =
+                ConcreteEnum
+                  { enum_name; enum_id; members = _; representation_t = _; has_unknown_members = _ };
+              _;
+            }
         ) ->
       p ~extra:(spf "enum concrete: %s #%s" enum_name (ALoc.debug_to_string (enum_id :> ALoc.t))) t
     | AnnotT (_, arg, use_desc) -> p ~extra:(spf "use_desc=%b, %s" use_desc (kid arg)) t
@@ -975,6 +982,13 @@ and dump_use_t_ (depth, tvars) cx t =
         | EnumExhaustiveCheckInvalid _ -> "EnumExhaustiveCheckInvalid"
       in
       p ~extra:check_str t
+    | GetEnumT { kind; _ } ->
+      p
+        ~extra:
+          (match kind with
+          | `GetEnumObject -> "get enum object"
+          | `GetEnumValue -> "get enum value")
+        t
     | FilterOptionalT (_, arg) -> p ~reason:false ~extra:(kid arg) t
     | FilterMaybeT (_, arg) -> p ~reason:false ~extra:(kid arg) t
     | DeepReadOnlyT ((_, tv), _, _) -> p ~extra:(tvar tv) t
@@ -1862,6 +1876,8 @@ let dump_error_message =
         | `ConcreteEnum -> "concrete"
         | `AbstractEnum -> "abstract")
         (Base.Option.value ~default:"<None>" representation_type)
+    | EEnumInvalidAbstractUse { reason; enum_reason } ->
+      spf "EEnumInvalidAbstractUse (%s) (%s)" (dump_reason cx reason) (dump_reason cx enum_reason)
     | EAssignConstLikeBinding { loc; definition; binding_kind } ->
       spf
         "EAssignConstLikeBinding (%s) (%s) (%s)"

src/typing/default_resolve.ml

@@ -202,6 +202,7 @@ let rec default_resolve_touts ~flow ?resolve_callee cx loc u =
   | DestructuringT (_, _, _, tvar, _) -> resolve_tvar tvar
   | ResolveUnionT { upper; _ } -> default_resolve_touts ~flow cx loc upper
   | TypeCastT (_, t) -> resolve t
+  | GetEnumT { tout; _ } -> resolve tout
   | EnumCastT _
   | EnumExhaustiveCheckT _ ->
     ()

src/typing/env_resolution.ml

@@ -1052,8 +1052,9 @@ let resolve_declare_namespace cx loc ns =
 
 let resolve_enum cx id_loc enum_reason enum_loc name enum =
   if Context.enable_enums cx then
-    let enum_info = Statement.mk_enum cx ~enum_reason id_loc name enum in
-    (DefT (enum_reason, EnumObjectT enum_info), unknown_use)
+    let enum_info = ConcreteEnum (Statement.mk_enum cx ~enum_reason id_loc name enum) in
+    let t = mk_enum_object_type enum_reason enum_info in
+    (t, unknown_use)
   else (
     Flow_js_utils.add_output cx (Error_message.EEnumsNotEnabled enum_loc);
     (AnyT.error enum_reason, unknown_use)

src/typing/errors/error_message.ml

@@ -570,6 +570,10 @@ and 'loc t' =
       representation_type: string option;
       casting_syntax: Options.CastingSyntax.t;
     }
+  | EEnumInvalidAbstractUse of {
+      reason: 'loc virtual_reason;
+      enum_reason: 'loc virtual_reason;
+    }
   (* end enum error messages *)
   | EAssignConstLikeBinding of {
       loc: 'loc;
@@ -1362,6 +1366,8 @@ let rec map_loc_of_error_message (f : 'a -> 'b) : 'a t' -> 'b t' =
         representation_type;
         casting_syntax;
       }
+  | EEnumInvalidAbstractUse { reason; enum_reason } ->
+    EEnumInvalidAbstractUse { reason = map_reason reason; enum_reason = map_reason enum_reason }
   | EAssignConstLikeBinding { loc; definition; binding_kind } ->
     EAssignConstLikeBinding { loc = f loc; definition = map_reason definition; binding_kind }
   | ECannotResolveOpenTvar { use_op; reason; blame_reasons } ->
@@ -1740,6 +1746,7 @@ let util_use_op_of_msg nope util = function
   | EEnumAllMembersAlreadyChecked _
   | EEnumNotAllChecked _
   | EEnumUnknownNotChecked _
+  | EEnumInvalidAbstractUse _
   | EEnumInvalidCheck _
   | EEnumMemberUsedAsType _
   | EAssignConstLikeBinding _
@@ -1835,6 +1842,7 @@ let loc_of_msg : 'loc t' -> 'loc option = function
   | EEnumAllMembersAlreadyChecked { reason; _ }
   | EEnumNotAllChecked { reason; _ }
   | EEnumUnknownNotChecked { reason; _ }
+  | EEnumInvalidAbstractUse { reason; _ }
   | EEnumInvalidCheck { reason; _ }
   | EEnumMemberUsedAsType { reason; _ }
   | EEnumInvalidMemberAccess { reason; _ }
@@ -4699,6 +4707,17 @@ let friendly_message_of_msg loc_of_aloc msg =
       | _ -> None
     in
     IncompatibleEnum { reason_lower; reason_upper; use_op; suggestion }
+  | EEnumInvalidAbstractUse { reason; enum_reason } ->
+    let features =
+      [
+        text "Cannot exhaustively check ";
+        desc reason;
+        text " because ";
+        ref enum_reason;
+        text " is an abstract enum value, so has no members.";
+      ]
+    in
+    Normal { features }
   | EAssignConstLikeBinding { definition; binding_kind; _ } ->
     let features =
       [
@@ -5851,6 +5870,7 @@ let error_code_of_message err : error_code option =
   end
   | EDuplicateModuleProvider _ -> Some DuplicateModule
   | EEnumAllMembersAlreadyChecked _ -> Some InvalidExhaustiveCheck
+  | EEnumInvalidAbstractUse _ -> Some InvalidExhaustiveCheck
   | EEnumInvalidCheck _ -> Some InvalidExhaustiveCheck
   | EEnumInvalidMemberAccess _ -> Some InvalidEnumAccess
   | EEnumInvalidObjectUtilType _ -> Some NotAnObject

src/typing/flow_js.ml

@@ -5319,7 +5319,7 @@ struct
         (*********)
         (* enums *)
         (*********)
-        | ( DefT (enum_reason, EnumObjectT enum_info),
+        | ( DefT (enum_reason, EnumObjectT { enum_value_t; enum_info = ConcreteEnum enum_info }),
             GetPropT
               {
                 use_op;
@@ -5332,7 +5332,6 @@ struct
               }
           ) ->
           let access = (use_op, access_reason, None, (prop_reason, member_name)) in
-          let enum_value_t = mk_enum_type enum_reason enum_info in
           GetPropTKit.on_EnumObjectT
             cx
             trace
@@ -5359,13 +5358,17 @@ struct
                   hint;
                 }
             )
-        | ( DefT (enum_reason, EnumObjectT enum_info),
+        | ( DefT (_, EnumObjectT { enum_value_t; enum_info }),
             MethodT (use_op, call_reason, lookup_reason, (Named _ as propref), action)
           ) ->
           let t =
             Tvar.mk_no_wrap_where cx lookup_reason (fun tout ->
-                let enum_value_t = mk_enum_type enum_reason enum_info in
-                let { representation_t; _ } = enum_info in
+                let representation_t =
+                  match enum_info with
+                  | ConcreteEnum { representation_t; _ }
+                  | AbstractEnum { representation_t } ->
+                    representation_t
+                in
                 rec_flow
                   cx
                   trace
@@ -5560,6 +5563,25 @@ struct
           continue cx trace (GenericT { reason; id; name; bound = l; no_infer }) cont
         | (GenericT { reason; bound; _ }, _) ->
           rec_flow cx trace (reposition_reason cx reason bound, u)
+        (************)
+        (* GetEnumT *)
+        (************)
+        | ( DefT (enum_reason, EnumValueT enum_info),
+            GetEnumT { use_op; orig_t; kind = `GetEnumObject; tout; _ }
+          ) ->
+          let enum_value_t = Base.Option.value ~default:l orig_t in
+          rec_flow
+            cx
+            trace
+            (DefT (enum_reason, EnumObjectT { enum_value_t; enum_info }), UseT (use_op, tout))
+        | (_, GetEnumT { use_op; kind = `GetEnumObject; tout; _ }) ->
+          rec_flow cx trace (l, UseT (use_op, tout))
+        | ( DefT (_, EnumObjectT { enum_value_t; _ }),
+            GetEnumT { use_op; kind = `GetEnumValue; tout; _ }
+          ) ->
+          rec_flow cx trace (enum_value_t, UseT (use_op, tout))
+        | (_, GetEnumT { use_op; kind = `GetEnumValue; tout; _ }) ->
+          rec_flow cx trace (l, UseT (use_op, tout))
         (**********************************)
         (* Flow Enums exhaustive checking *)
         (**********************************)
@@ -5586,6 +5608,8 @@ struct
             ~default_case
             ~incomplete_out
             ~discriminant_after_check
+        | (DefT (enum_reason, EnumValueT (AbstractEnum _)), EnumExhaustiveCheckT { reason; _ }) ->
+          add_output cx (Error_message.EEnumInvalidAbstractUse { reason; enum_reason })
         (* Resolving the case tests. *)
         | ( _,
             EnumExhaustiveCheckT
@@ -5607,7 +5631,7 @@ struct
           let { enum_id = enum_id_discriminant; members; _ } = discriminant_enum in
           let checks =
             match l with
-            | DefT (_, EnumObjectT { enum_id = enum_id_check; _ })
+            | DefT (_, EnumObjectT { enum_info = ConcreteEnum { enum_id = enum_id_check; _ }; _ })
               when ALoc.equal_id enum_id_discriminant enum_id_check && SMap.mem member_name members
               ->
               check :: checks
@@ -5626,7 +5650,7 @@ struct
             ~default_case
             ~incomplete_out
             ~discriminant_after_check
-        | ( DefT (enum_reason, EnumValueT (ConcreteEnum { members; _ })),
+        | ( DefT (enum_reason, EnumValueT enum_info),
             EnumExhaustiveCheckT
               {
                 reason;
@@ -5635,7 +5659,11 @@ struct
                 discriminant_after_check = _;
               }
           ) ->
-          let example_member = SMap.choose_opt members |> Base.Option.map ~f:fst in
+          let example_member =
+            match enum_info with
+            | ConcreteEnum { members; _ } -> SMap.choose_opt members |> Base.Option.map ~f:fst
+            | AbstractEnum _ -> None
+          in
           List.iter
             (fun reason ->
               add_output cx (Error_message.EEnumInvalidCheck { reason; enum_reason; example_member }))
@@ -6812,6 +6840,7 @@ struct
     | AssertExportIsTypeT _
     | ImplicitVoidReturnT _
     | GetElemT _
+    | GetEnumT _
     | GetKeysT _
     | GetPrivatePropT _
     | GetPropT _
@@ -7883,6 +7912,8 @@ struct
                     OpenT tout
                   )
               )
+            | EnumType ->
+              GetEnumT { use_op; reason; orig_t = Some t; kind = `GetEnumObject; tout = OpenT tout }
           ))
 
   and eagerly_eval_destructor_if_resolved cx ~trace use_op reason t d tvar =