comments and changelog

Author: zth

CHANGELOG.md

@@ -20,6 +20,7 @@
 
 - Use FORCE_COLOR environmental variable to force colorized output https://github.com/rescript-lang/rescript-compiler/pull/7033
 - Allow spreads of variants in patterns (`| ...someVariant as v => `) when the variant spread is a subtype of the variant matched on. https://github.com/rescript-lang/rescript-compiler/pull/6721
+- Allow pattern matching on dicts. `switch someDict { | dict{"one": 1} => Js.log("one is one") }` https://github.com/rescript-lang/rescript-compiler/pull/7059
 
 #### :bug: Bug fix
 

jscomp/ml/dict_type_helpers.ml

@@ -1,3 +1,33 @@
+(*
+  An overview of the implementation of dicts in ReScript:
+  ### What is a dict?
+  Dicts are effectively an object with unknown fields, but a single known type of the values it holds.
+
+  ### How are they implemented?
+  Dicts in ReScript are implemented as predefined record type, with a single (magic) field that holds 
+  the type of the dict's values. This field is called `dictValuesType`, and is just an implementation
+  detail - it's never actually exposed to the user, just used internally. 
+
+  The compiler will route any label lookup on the dict record type to the magic field, which creates a 
+  record with unknown keys, but of a single type.
+
+  The reason for this seemingly convoluted implementation is that it allows us to piggyback on the 
+  existing record pattern matching mechanism, which means we get pattern matching on dicts for free.
+
+  ### Modifications to the type checker
+  We've made a few smaller modifications to the type checker to support this implementation:
+
+  - We've added a new predefined type `dict` that is a record with a single field called `dictValuesType`.
+    This type is used to represent the type of the values in a dict.
+  - We've modified the type checker to recognize `dict` patterns, and route them to the predefined `dict` type.
+    This allows us to get full inference for dicts in patterns. 
+    
+  ### Syntax
+  There's first class syntax support for dicts, both as expressions and as patterns.
+  A dict pattern is treated as a record pattern in the compiler and syntax, with an attriubute `@res.dictPattern`
+  attached to it. This attribute is used to tell the compiler that the pattern is a dict pattern, and is what
+  triggers the compiler to treat the dict record type differently to regular record types.
+  *)
 let dict_magic_field_name = "dictValuesType"
 
 let has_dict_pattern_attribute attrs =

jscomp/ml/predef.ml

@@ -220,11 +220,14 @@ let common_initial_env add_type add_extension empty_env =
      type_variance = [Variance.covariant; Variance.covariant]}
   and decl_dict =
     let tvar = newgenvar() in
-    (* Dicts are implented as a as a single "magic" field record. This magic field
-       is then leveraged to be able to piggy back on the existing record pattern
-       matching mechanism. So, this definition is import for the dict pattern
-       matching functionality, but not something intended to be exposed to the
-       user. *) 
+    (* Dicts are implemented as a single "magic" field record. This magic field
+       is the medium through which we can piggy back on the existing record pattern
+       matching mechanism. We do this by letting the compiler route any label lookup
+       for the dict record type to the magic field, which has the type of the values
+       of the dict.
+
+       So, this definition is important for the dict pattern matching functionality, 
+       but not something intended to be exposed to the user. *) 
     {decl_abstr with
       type_attributes = [Dict_type_helpers.dict_attr];
       type_params = [tvar];

jscomp/ml/typecore.ml

@@ -806,7 +806,7 @@ end) = struct
     Env.mark_type_used env (Path.last tpath) (Env.find_type tpath env);
     let is_dict = Path.same tpath Predef.path_dict in
     if is_dict then (
-      (* [dict] Dicts are implented as a record with a single "magic" field. This magic field is 
+      (* [dict] Dicts are implemented as a record with a single "magic" field. This magic field is 
          used to track the dict value type, and any label lookup on the dict record type 
          will give that single value type back. This is how we can piggy back on the record 
          pattern matching mechanism.