document spreads in the syntax lookup

Author: zth

misc_docs/syntax/language_spreads.mdx

@@ -0,0 +1,95 @@
+---
+id: "spreads"
+keywords: ["spread", "record", "variant", "partial"]
+name: "..."
+summary: "This is the `...` syntax."
+category: "languageconstructs"
+---
+
+A `spread` is three dots in a row: `...`. Spreads have many different uses in ReScript depending on in which context it is used.
+## Record definitions
+> Available in v10+
+
+Spreads can be used to copy fields from one record definition into another. 
+
+```res
+type a = {
+  id: string,
+  name: string,
+}
+
+type b = {
+  age: int
+}
+
+type c = {
+  ...a,
+  ...b,
+  active: bool
+}
+```
+
+Read more about [record type spreads here](record.md#record-type-spread).
+
+## Record immutable update
+Spreads can be used for immutable updates of records:
+
+```res
+let meNextYear = {...me, age: me.age + 1}
+```
+
+Read more about [record immutable updates here](record.md#immutable-update).
+
+## Variant definitions
+> Available in v11+
+
+Spreads can be used to copy constructors from one variant definition to another.
+
+```res
+type a = One | Two | Three
+type b = | ...a | Four | Five
+// b is now One | Two | Three | Four | Five
+```
+
+Read more about [variant type spreads](variant.md#variant-type-spreads) here.
+
+## Variant pattern matching
+> Available in v12+
+
+You can refine the type of a variant by spreading compatible a variant when pattern matching:
+```res
+type pets = Cat | Dog
+type fish = Cod | Salmon
+type animals = | ...pets | ...fish
+
+let isPet = (animal: animals) => {
+  switch animal {
+  | ...dog => Console.log("A dog!")
+  | _ => Console.log("Not a dog...")
+  }
+}
+
+```
+
+Read more about [variant type spreads in pattern matching](pattern-matching-destructuring.md#match-on-subtype-variants).
+
+## Partial application of functions
+> Available in v11+ (uncurried mode)
+
+You can partially apply a function using the spread syntax. Partially applying a function will return a new function taking only the arguments that wasn't applied partially.
+
+```res
+let add = (a, b) => a + b
+let addFive = add(5, ...)
+```
+
+Read more about [partial application of functions](function.md#partial-application).
+
+### References
+
+* [Record type spreads](record.md#record-type-spread)
+* [Record immutable updates](record.md#immutable-update)
+* [Variant type spreads](variant.md#variant-type-spreads)
+* [Variant type spreads in pattern matching](pattern-matching-destructuring.md#match-on-subtype-variants)
+* [Partial application of functions](function.md#partial-application)
+