ReScriptify genType supported-types docs

Author: ryyppy

pages/docs/gentype/latest/supported-types.mdx

@@ -2,54 +2,54 @@
 
 <Intro>
 
-Some types and values in Reason do not map directly to JavaScript and need to be converted whenever a value crosses the boundary. This document gives an overview on how `genType`'s convertion works on different types.
+Some types and values in ReScript do not map directly to JavaScript and need to be converted whenever a value crosses the boundary. This document gives an overview on how `genType`'s convertion works on different types.
 
 </Intro>
 
 ## Int
 
-Reason values e.g. `1`, `2`, `3` are unchanged. So they are exported to JS values of type `number`.
+ReScript values e.g. `1`, `2`, `3` are unchanged. So they are exported to JS values of type `number`.
 
 ## Float
 
-Reason values e.g. `1.0`, `2.0`, `3.0` are unchanged. So they are exported to JS values of type `number`.
+ReScript values e.g. `1.0`, `2.0`, `3.0` are unchanged. So they are exported to JS values of type `number`.
 
 ## String
 
-Reason values e.g. `"a"`, `"b"`, `"c"` are unchanged. So they are exported to JS values of type `string`.
+ReScript values e.g. `"a"`, `"b"`, `"c"` are unchanged. So they are exported to JS values of type `string`.
 
 ## Optionals
 
-Reason values of type e.g. `option(int)`, such as `None`, `Some(0)`, `Some(1)`, `Some(2)`, are exported to JS values `null`, `undefined`, `0`, `1`, `2`.
+ReScript values of type e.g. `option(int)`, such as `None`, `Some(0)`, `Some(1)`, `Some(2)`, are exported to JS values `null`, `undefined`, `0`, `1`, `2`.
 The JS values are unboxed, and `null`/`undefined` are conflated.
 So the option type is exported to JS type `null` or `undefined` or `number`.
 
 ## Nullables
 
-Reason values of type e.g. `Js.Nullable.t(int)`, such as `Js.Nullable.null`, `Js.Nullable.undefined`, `Js.Nullable.return(0)`, `Js.Nullable.return(1)`, `Js.Nullable.return(2)`, are exported to JS values `null`, `undefined`, `0`, `1`, `2`.
+ReScript values of type e.g. `Js.Nullable.t(int)`, such as `Js.Nullable.null`, `Js.Nullable.undefined`, `Js.Nullable.return(0)`, `Js.Nullable.return(1)`, `Js.Nullable.return(2)`, are exported to JS values `null`, `undefined`, `0`, `1`, `2`.
 The JS values are identical: there is no conversion unless the argument type needs conversion.
 
 ## Records
 
-Reason record values of type e.g. `{x:int}` such as `{x:0}`, `{x:1}`, `{x:2}`, are exported to JS object values `{x:0}`, `{x:1}`, `{x:2}`. This requires a change of runtime representation from arrays to objects.
+ReScript record values of type e.g. `{x:int}` such as `{x:0}`, `{x:1}`, `{x:2}`, are exported to JS object values `{x:0}`, `{x:1}`, `{x:2}`. This requires a change of runtime representation from arrays to objects.
 So they are exported to JS values of type `{x:number}`.
 
-Since records are immutable by default, their fields will be exported to readonly property types in Flow/TS. Mutable fields are specified in Reason by e.g. `{mutable mutableField: string}`.
+Since records are immutable by default, their fields will be exported to readonly property types in Flow/TS. Mutable fields are specified in ReScript by e.g. `{mutable mutableField: string}`.
 
 The `@genType.as` annotation can be used to change the name of a field on the JS side of things. So e.g. `{[@genType.as "y"] x:int}` is exported as JS type `{y:int}`.
 
-If one field of the Reason record has option type, this is exported to an optional JS field. So for example Reason type `{x: option(int)}` is exported as JS type `{x?: number}`.
+If one field of the ReScript record has option type, this is exported to an optional JS field. So for example ReScript type `{x: option(int)}` is exported as JS type `{x?: number}`.
 
 ## Objects
 
-Reason object values of type e.g. `{. "x":int}` such as `{"x": 0}`, `{"x": 1}`, `{"x": 2}`, are exported as identical JS object values `{x:0}`, `{x:1}`, `{x:2}`. This requires no conversion. So they are exported to JS values of type `{x:number}`.
+ReScript object values of type e.g. `{. "x":int}` such as `{"x": 0}`, `{"x": 1}`, `{"x": 2}`, are exported as identical JS object values `{x:0}`, `{x:1}`, `{x:2}`. This requires no conversion. So they are exported to JS values of type `{x:number}`.
 A conversion is required only when the type of some field requires conversions.
 
-Since objects are immutable by default, their fields will be exported to readonly property types in Flow/TS. Mutable fields are specified in Reason by e.g. `{. [@bs.set] "mutableField": string }`.
+Since objects are immutable by default, their fields will be exported to readonly property types in Flow/TS. Mutable fields are specified in ReScript by e.g. `{. [@bs.set] "mutableField": string }`.
 
-It is possible to mix object and option types, so for example the Reason type `{. "x":int, "y":option(string)}` exports to JS type `{x:number, ?y: string}`, requires no conversion, and allows option pattern matching on the Reason side.
+It is possible to mix object and option types, so for example the ReScript type `{. "x":int, "y":option(string)}` exports to JS type `{x:number, ?y: string}`, requires no conversion, and allows option pattern matching on the ReScript side.
 
-Object field names follow bucklescript's mangling convention (so e.g. `_type` in Reason represents `type` in JS):
+Object field names follow ReScript's mangling convention (so e.g. `_type` in ReScript represents `type` in JS):
 
 ```
 Remove trailing "__" if present.
@@ -58,8 +58,8 @@ Otherwise remove leading "_" when followed by an uppercase letter, or keyword.
 
 ## Tuples
 
-Reason tuple values of type e.g. `(int, string)` are exported as identical JS values of type `[number, string]`. This requires no conversion, unless one of types of the tuple items does.
-While the type of Reason tuples is immutable, there's currently no mature enforcement in TS/Flow, so they're currenty exported to mutable tuples.
+ReScript tuple values of type e.g. `(int, string)` are exported as identical JS values of type `[number, string]`. This requires no conversion, unless one of types of the tuple items does.
+While the type of ReScript tuples is immutable, there's currently no mature enforcement in TS/Flow, so they're currenty exported to mutable tuples.
 
 ## Variants
 
@@ -82,9 +82,9 @@ Note that this unboxed representation does not use the label `"Named"` of the va
 If there is more than one case with payload, or if the single payload has not type object, a boxed representation is used. The boxed representation has shape ```{tag: "someTag", value: someValue}```.
 For example, type ```| A | B(int) | C(string)``` has values such as ```"A"``` and
 ```{tag: "B", value: 42}``` and ```{tag: "C", value: "hello"}```.
-Polymorhphic variants are treated similarly. Notice that payloads for polymorphic variants are always unary: ``` `Pair(int,int) ``` has a single payload of type `(int,int)`. Instead, ordinary variants distinguish between unary ``` Pair((int,int)) ``` and binary ``` Pair(int,int) ``` payloads. All those cases are represented in JS as ```{tag: "Pair", value: [3, 4]}```, and the conversion functions take care of the different Reason representations.
+Polymorhphic variants are treated similarly. Notice that payloads for polymorphic variants are always unary: ``` `Pair(int,int) ``` has a single payload of type `(int,int)`. Instead, ordinary variants distinguish between unary ``` Pair((int,int)) ``` and binary ``` Pair(int,int) ``` payloads. All those cases are represented in JS as ```{tag: "Pair", value: [3, 4]}```, and the conversion functions take care of the different ReScript representations.
 
-The `@genType.as` annotation can be used to modify the name emitted for a variant case on the JS side. So e.g. ``` | [@genType.as "Arenamed"] A``` exports Reason value `` A `` to JS value `"Arenamed"`.
+The `@genType.as` annotation can be used to modify the name emitted for a variant case on the JS side. So e.g. ``` | [@genType.as "Arenamed"] A``` exports ReScript value `` A `` to JS value `"Arenamed"`.
 Boolean/integer/float constants can be expressed as ``` | [@genType.as true] True ``` and ``` | [@genType.as 20] Twenty ``` and ``` | [@genType.as 0.5] Half ```. Similarly for polymorphic variants.
 The `@genType.as` annotation can also be used on variants with payloads to determine what appears in `{ tag: ... }`.
 
@@ -94,18 +94,18 @@ For more examples, see [Variants.res](examples/typescript-react-example/src/Vari
 
 ## Arrays
 
-Arrays with elements of Reason type `t` are exported to JS arrays with elements of the corresponding JS type. If a conversion is required, a copy of the array is performed.
+Arrays with elements of ReScript type `t` are exported to JS arrays with elements of the corresponding JS type. If a conversion is required, a copy of the array is performed.
 
-Immutable arrays are supported with the additional Reason library
+Immutable arrays are supported with the additional ReScript library
 [ImmutableArray.res/.resi](examples/typescript-react-example/src/ImmutableArray.resi), which currently needs to be added to your project.
 The type `ImmutableArray.t(+'a)` is covariant, and is mapped to readonly array types in TS/Flow. As opposed to TS/Flow, `ImmutableArray.t` does not allow casting in either direction with normal arrays. Instead, a copy must be performed using `fromArray` and `toArray`.
 
 ## Functions and Function Components
 
-Reason functions are exported as JS functions of the corresponding type.
-So for example a Reason function `foo : int => int` is exported as a JS function from numbers to numbers.
+ReScript functions are exported as JS functions of the corresponding type.
+So for example a ReScript function `foo : int => int` is exported as a JS function from numbers to numbers.
 
-If named arguments are present in the Reason type, they are grouped and exported as JS objects. For example `foo : (~x:int, ~y:int) => int` is exported as a JS function from objects of type `{x:number, y:number}` to numbers.
+If named arguments are present in the ReScript type, they are grouped and exported as JS objects. For example `foo : (~x:int, ~y:int) => int` is exported as a JS function from objects of type `{x:number, y:number}` to numbers.
 
 In case of mixed named and unnamed arguments, consecutive named arguments form separate groups. So e.g. `foo : (int, ~x:int, ~y:int, int, ~z:int) => int` is exported to a JS function of type `(number, {x:number, y:number}, number, {z:number}) => number`.
 
@@ -117,7 +117,7 @@ Function components are exported and imported exactly like normal functions. For
 let make = (~name) => React.string(name);
 ```
 
-For renaming, named arguments follow bucklescript's mangling convention:
+For renaming, named arguments follow ReScript's mangling convention:
 
 ```
 Remove trailing "__" if present.
@@ -126,23 +126,23 @@ Otherwise remove leading "_" when followed by an uppercase letter, or keyword.
 
 For example:
 
-```reason
-[@genType]
-let exampleFunction = (~_type) => "type: " ++ _type;
+```res
+@genType
+let exampleFunction = (~_type) => "type: " ++ _type
 ```
 
 ## Record Components
 
-ReasonReact record components with props of Reason types `t1`, `t2`, `t3` are exported as reactjs components with props of the JS types corresponding to `t1`, `t2`, `t3`. The annotation is on the `make` function: `[@genType] let make ...`.
+ReasonReact record components with props of ReScript types `t1`, `t2`, `t3` are exported as reactjs components with props of the JS types corresponding to `t1`, `t2`, `t3`. The annotation is on the `make` function: `[@genType] let make ...`.
 
 A file can export many components by defining them in sub-modules. The toplevel component is also exported as default.
 
 ## Imported Types
 
-It's possible to import an existing TS/Flow type as an opaque type in Reason. For example,
+It's possible to import an existing TS/Flow type as an opaque type in ReScript. For example,
 
-```reason
-[@genType.import "./SomeFlowTypes"] type weekday;
+```res
+@genType.import("./SomeFlowTypes") type weekday
 ```
 
 defines a type which maps to `weekday` in `SomeFlowTypes.js`.
@@ -156,36 +156,42 @@ See for example [Types.res](examples/typescript-react-example/src/nested/Types.r
 
 ## First Class Modules
 
-Reason first class modules are converted from their array Reason runtime representation to JS Object types.
+ReScript first class modules are converted from their array ReScript runtime representation to JS Object types.
 For example,
 
-```reason
-module type MT = { let x: int; let y: string; };
-module M = { let y = "abc"; let x = 42; };
-[@genType] let firstClassModule: module MT = (module M);
+```res
+module type MT = {
+  let x: int
+  let y: string
+}
+module M = {
+  let y = "abc"
+  let x = 42
+}
+export firstClassModule: module(MT) = module(M)
 ```
 
 is exported as a JS object of type
 
-```reason
-{x: number, y: string}
+```res
+{"x": number, "y": string}
 ```
 
 Notice how the order of elements in the exported JS object is determined by the module type `MT` and not the module implementation `M`.
 
 ## Polymorphic Types
 
-If a Reason type contains a type variable, the corresponding value is not converted. In other words, the conversion is the identity function. For example, a Reason function of type `{payload: 'a} => 'a` must treat the value of the payload as a black box, as a consequence of parametric polymorphism. If a typed back-end is used, the reason type is converted to the corresponding generic type.
+If a ReScript type contains a type variable, the corresponding value is not converted. In other words, the conversion is the identity function. For example, a ReScript function of type `{payload: 'a} => 'a` must treat the value of the payload as a black box, as a consequence of parametric polymorphism. If a typed back-end is used, the ReScript type is converted to the corresponding generic type.
 
 ### Exporting Values from Polymorphic Types with Hidden Type Variables
 
 For cases when a value that contains a hidden type variable needs to be converted, a function can be used to produce the appropriate output:
 
 **Doesn't work**
 
-```reason
-[@genType]
-let none = None;
+```res
+@genType
+let none = None
 ```
 
 ```js
@@ -194,9 +200,9 @@ export const none: ?T1 = OptionBS.none; // Errors out as T1 is not defined
 
 **Works**
 
-```reason
-[@genType]
-let none = () => None;
+```res
+@genType
+let none = () => None
 ```
 
 ```js