Merge pull request #566 from rescript-association/optional-record-fields

docs for optional record fields

Author: zth

pages/docs/manual/latest/record.mdx

@@ -20,7 +20,7 @@ A record needs a mandatory type declaration:
 ```res prelude
 type person = {
   age: int,
-  name: string
+  name: string,
 }
 ```
 ```js
@@ -157,9 +157,247 @@ Fields not marked with `mutable` in the type declaration cannot be mutated.
 
 ReScript records compile to straightforward JavaScript objects; see the various JS output tabs above.
 
+## Optional Record Fields
+ReScript [`v10`](/blog/release-10-0-0#experimental-optional-record-fields) introduced optional record fields. This means that you can define fields that can be omitted when creating the record. It looks like this:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res prelude
+type person = {
+  age: int,
+  name?: string
+}
+```
+```js
+// Empty output
+```
+
+</CodeTab>
+
+Notice how `name` has a suffixed `?`. That means that the field itself is _optional_.
+
+### Creation
+You can omit any optional fields when creating a record. Not setting an optional field will default the field's value to `None`:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res prelude
+type person = {
+  age: int,
+  name?: string
+}
+
+let me = {
+  age: 5,
+  name: "Big ReScript"
+}
+
+let friend = {
+  age: 7
+}
+```
+```js
+var me = {
+  age: 5,
+  name: "Big ReScript"
+};
+
+var friend = {
+  age: 7
+};
+```
+
+</CodeTab>
+
+This has consequences for pattern matching, which we'll expand a bit on soon.
+
+## Immutable Update
+Updating an optional field via an immutable update above lets you set that field value without needing to care whether it's optional or not.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+type person = {
+  age: int,
+  name?: string
+}
+
+let me = {
+  age: 123,
+  name: "Hello"
+}
+
+let withoutName = {
+  ...me,
+  name: "New Name"
+}
+```
+```js
+import * as Caml_obj from "./stdlib/caml_obj.js";
+
+var me = {
+  age: 123,
+  name: "Hello"
+};
+
+var newrecord = Caml_obj.obj_dup(me);
+
+newrecord.name = "New Name";
+
+var withoutName = newrecord;
+```
+
+</CodeTab>
+
+
+However, if you want to set the field to an optional value, you prefix that value with `?`:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+type person = {
+  age: int,
+  name?: string
+}
+
+let me = {
+  age: 123,
+  name: "Hello"
+}
+
+let maybeName = Some("My Name")
+
+let withoutName = {
+  ...me,
+  name: ?maybeName
+}
+```
+```js
+import * as Caml_obj from "./stdlib/caml_obj.js";
+
+var me = {
+  age: 123,
+  name: "Hello"
+};
+
+var maybeName = "My Name";
+
+var newrecord = Caml_obj.obj_dup(me);
+
+newrecord.name = maybeName;
+
+var withoutName = newrecord;
+```
+
+</CodeTab>
+
+You can unset an optional field's value via that same mechanism by setting it to `?None`.
+
+### Pattern Matching on Optional Fields
+[Pattern matching](pattern-matching-destructuring), one of ReScript's most important features, has two caveats when you deal with optional fields.
+
+When matching on the value directly, it's an `option`. Example:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+type person = {
+  age: int,
+  name?: string,
+}
+
+let me = {
+  age: 123,
+  name: "Hello",
+}
+
+let isRescript = switch me.name {
+| Some("ReScript") => true
+| Some(_) | None => false
+}
+```
+```js
+var isRescript;
+
+isRescript = "Hello" === "ReScript" ? true : false;
+
+var me = {
+  age: 123,
+  name: "Hello"
+};
+```
+
+</CodeTab>
+
+But, when matching on the field as part of the general record structure, it's treated as the underlying, non-optional value:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+type person = {
+  age: int,
+  name?: string,
+}
+
+let me = {
+  age: 123,
+  name: "Hello",
+}
+
+let isRescript = switch me {
+| {name: "ReScript"} => true
+| _ => false
+}
+
+```
+```js
+var isRescript;
+
+isRescript = "Hello" === "ReScript" ? true : false;
+
+var me = {
+  age: 123,
+  name: "Hello"
+};
+```
+
+</CodeTab>
+
+Sometimes you _do_ want to know whether the field was set or not. You can tell the pattern matching engine about that by prefixing your option match with `?`, like this:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+type person = {
+  age: int,
+  name?: string,
+}
+
+let me = {
+  age: 123,
+  name: "Hello",
+}
+
+let nameWasSet = switch me {
+| {name: ?None} => false
+| {name: ?Some(_)} => true
+}
+```
+```js
+var nameWasSet = false;
+
+var me = {
+  age: 123,
+  name: "Hello"
+};
+```
+
+</CodeTab>
+
 ## Tips & Tricks
 
-**Record Types Are Found By Field Name**. With records, you **cannot** say "I'd like this function to take any record type, as long as they have the field `age`". The following **won't work as intended**:
+### Record Types Are Found By Field Name
+With records, you **cannot** say "I'd like this function to take any record type, as long as they have the field `age`". The following **won't work as intended**:
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
@@ -189,6 +427,11 @@ getAge(me) // type error!
 
 The type system will complain that `me` is a `person`, and that `getAge` only works on `monster`. If you need such capability, use ReScript objects, described [here](object.md).
 
+### Optional Fields in Records Can Be Useful for Bindings
+Many JavaScript APIs tend to have large configuration objects that can be a bit annoying to model as records, since you previously always needed to specify all record fields when creating a record. 
+
+Optional record fields, introduced in [`v10`](/blog/release-10-0-0#experimental-optional-record-fields), is intended to help with this. Optional fields will let you avoid having to specify all fields, and let you just specify the one's you care about. A significant improvement in ergonomics for bindings and other APIs with for example large configuration objects.
+
 ## Design Decisions
 
 After reading the constraints in the previous sections, and if you're coming from a dynamic language background, you might be wondering why one would bother with record in the first place instead of straight using object, since the former needs explicit typing and doesn't allow different records with the same field name to be passed to the same function, etc.