add object spread and object rest docs 🌹

Author: Basarat Ali Syed

SUMMARY.md

@@ -15,10 +15,10 @@
  * [let](docs/let.md)
  * [const](docs/const.md)
  * [Destructuring](docs/destructuring.md)
+ * [Spread Operator](docs/spread-operator.md)
  * [for...of](docs/for...of.md)
  * [Iterators](docs/iterators.md)
  * [Template Strings](docs/template-strings.md)
- * [Spread Operator](docs/spread-operator.md)
  * [Promise](docs/promise.md)
  * [Generators](docs/generators.md)
  * [Async Await](docs/async-await.md)

docs/destructuring.md

@@ -50,6 +50,28 @@ var foo = { bar: { bas: 123 } };
 var {bar: {bas}} = foo; // Effectively `var bas = foo.bar.bas;`
 ```
 
+#### Object Destructuring with rest
+You can pick up any number of elements from the an object and get *an object* of the remaining elements using object destructuring with rest.
+
+```ts
+var {w, x, ...remaining} = {w: 1, x: 2, y: 3, z: 4};
+console.log(w, x, remaining); // 1, 2, {y:3,z:4}
+```
+A common use case is also to ignore certain properties. For example:
+```ts
+// Example function
+function goto(point2D: {x: number, y: number}) {
+ // Imagine some code that might break
+ // if you pass in an object
+ // with more items than desired
+}
+// Some point you get from somewhere
+const point3D = {x: 1, y: 2, z: 3};
+/** A nifty use of rest to remove extra properties */
+const { z, ...point2D } = point3D;
+goto(point2D);
+```
+
 #### Array Destructuring
 A common programming question: "How to swap two variables without using a third one?". The TypeScript solution:
 

docs/spread-operator.md

@@ -1,6 +1,6 @@
 ### Spread Operator
 
-The main objective of the spread operator is to *spread* the objects of an array. This is best explained with examples.
+The main objective of the spread operator is to *spread* the elements of an array or object. This is best explained with examples.
 
 #### Apply
 A common use case is to spread an array into the function arguments. Previously you would need to use `Function.prototype.apply`:
@@ -39,6 +39,24 @@ list = [...list, 3, 4];
 console.log(list); // [1,2,3,4]
 ```
 
+#### Object spread
+You can also spread an object into another object. A common use case is to simply add a property to an object without mutating the original:
+
+```ts
+const point2d = {x: 1, y: 2};
+/** Create a new object by using all the point2D props along with z */
+const point3D = {...point2D, z: 3};
+```
+
+Another common use case is a simple shallow extend:
+
+```ts
+const foo = {a: 1, b: 2};
+const bar = {c: 1, d: 2};
+/** Merge foo and bar */
+const fooBar = {...foo, ...bar};
+```
+
 #### Summary
 `apply` is something that you would inevitably do in JavaScript, so it's good to have a better syntax where you don't have that ugly `null` for the `this` argument. Also having a dedicated syntax for moving arrays out of (destructuring) or into (assignment) other arrays provides neat syntax for when you are doing array processing on partial arrays.