Moved questions to README.md

Author: JoelCodes

01-making-promises/README.md

@@ -0,0 +1,37 @@
+# Making Promises
+
+Soooooo.....
+
+This is the first set of exercises on promises.  A Promise is a mechanism frequently used in JavaScript to handle asynchronous processes; that is, promises are how we reason about the business of waiting.
+
+From a somewhat mechanical perspective, promises are simple state machines with three possible states:
+
+* Pending
+* Resolved
+* Rejected
+
+Resolved and rejected are *final* states, which means that once a promise gets to one of these states, it absolutely cannot go to any other state. Pending can go either way.  A promise that is either resolved or rejected may also have a *payload*, a value that it carries.  It's a little like an array that can only contain one value.  It's entirely possible that that value will be `undefined`, but that's still a value.
+
+How we access these values is the subject of a future chapter of exercises.  For now, we're going to focus on the mechanisms for making promises.
+
+## Exercise 1
+
+Use [Promise.resolve(value)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve) to create a promise that will resolve with the value 3.
+
+## Exercise 2
+
+Use [Promise.reject(error)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject) to create a promise that will reject with the string "Boo!"
+
+
+## Exercise 3
+
+You have the outline of a function `makePromiseWithConstructor(itShouldResolve)`
+
+Use the [Promise constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to create a promise that will:
+
+* resolve if itShouldResolve is truthy
+* reject if itShouldResolve is falsy
+
+## Exercise 4
+
+This is a common use of the Promise constructor. If you want to simulate waiting for a value, a common technique is to create a function like the following.  It simply accepts a value, and a delayInMs, then returns a promise that will resolve with that value after that delay.

answers/making-promises.js renamed to 01-making-promises/answers.js

@@ -3,10 +3,6 @@
  * 
  * EXERCISE 1
  * 
- * Use Promise.resolve(val) to create a promise that will resolve with the value 3
- * 
- * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve
- * 
  * @returns {Promise<3>}
  */
 function makePromiseResolveWith3(){
@@ -17,9 +13,6 @@ function makePromiseResolveWith3(){
  * 
  * EXERCISE 2
  * 
- * Use Promise.reject to create a promise that will reject with the string "Boo!" 
- * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject
- * 
  * @returns {Promise<,"Boo!">}
  */
 function makePromiseRejectWithBoo(){
@@ -30,11 +23,6 @@ function makePromiseRejectWithBoo(){
  * 
  * EXERCISE 3
  * 
- * Use a Promise constructor to create a promise that will:
- *   - resolve if itShouldResolve is truthy
- *   - reject if itShouldResolve is falsy
- * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
- * 
  * @param {boolean} itShouldResolve - Whether the promise should resolve or reject
  * @returns {Promise<undefined, undefined>}
  */
@@ -49,9 +37,7 @@ function makePromiseWithConstructor(itShouldResolve){
 /**
  * 
  * EXERCISE 4
- * 
- * This is a common use of the Promise constructor. If you want to simulate waiting for a value, a common technique is to create a function like the following.  It simply accepts a value, and a delayInMs, then returns a promise that will resolve with that value after that delay.
- * 
+ *
  * @param {any} value 
  * @param {number} delayInMs 
  * @return {Promise<any>} - A promise that will resolve with the value after delayInMs milliseconds

test/making-promises.test.js renamed to 01-making-promises/test.js

@@ -5,7 +5,7 @@ const {
   makePromiseRejectWithBoo,
   makePromiseWithConstructor,
   makeDelayPromise,
-} = require('../answers/making-promises');
+} = require('./answers');
 describe('Promise.resolve: (val:T) => Promise<T>', () => {
   describe('#makePromiseResolveWith3:() => Promise<number>', () => {
     it('creates a resolving promise', () => {

02-consuming-promises/README.md

@@ -0,0 +1,11 @@
+# Consuming Promises
+
+The following exercises will focus on using the .then and .catch methods of promises.  These are very important methods, not only for consuming values or handling errors, but also for transforming and combining promises.
+
+## Exercise 1
+
+This is a simple exercise in just waiting for a promise to be done before performing an action.  The promise will resolve after a certain number of milliseconds.
+
+## Exercise 2
+
+In this exercise, we will use then and catch for their most basic use: to consume the result of a successful async process, or to handle the error of a failed async process.  We will be given a promise, a consumer, and a handler.  Set it up so that, if the promise resolves, the consumer will be called with the result, and if the promise rejects, the handler will be called with the error.

02-consuming-promises/answers.js

@@ -0,0 +1,31 @@
+/**
+ * 
+ * EXERCISE 1
+ * 
+ * @param {Promise} promise
+ * @param {thunk} action
+ * 
+ */
+function waitForPromise(promise, action){
+  /* IMPLEMENT ME */
+}
+/**
+ * 
+ * EXERCISE 2
+ * 
+ * @param {Promise} promise 
+ * @param {consumer} consumer 
+ * @param {handler} handler 
+ */
+function consumePromise(promise, consumer, handler){
+  /* IMPLEMENT ME! */
+}
+
+/**
+ * @callback thunk
+ * @returns {void}
+ */
+module.exports = {
+  waitForPromise,
+  consumePromise,
+};

test/consuming-promises.test.js renamed to 02-consuming-promises/test.js

@@ -3,7 +3,7 @@ const assert = require('assert');
 const {
   waitForPromise,
   consumePromise,
-} = require('../answers/consuming-promises');
+} = require('./answers');
 
 describe('Consuming Promises with .then(cb) and .catch(cb)', () => {
   describe('#waitForPromise(promise, action) => void', () => {

03-transforming-promises/README.md

@@ -0,0 +1,84 @@
+# Transforming Promises
+
+## Exercise 1
+
+In this exercise, we'll create a function that can take in a promise and a transformer function and return a new transformed promise.
+
+In the previous exercise, we used `.then(cb)` in an imperative way, responding to its resolution by triggering a side effect.  But what if we want to create a new promise based on that resolution, but one that changed the value somehow?
+
+It's similar to arrays in this way: sometimes we use `.then(cb)` the way we would use `.forEach(cb)`, which helps us perform some action, some side effect based on the value.  For instance:
+
+```js
+const result = [2, 5, 3].forEach((num) => {
+  console.log(num);
+});
+```
+
+will print "2", "5", and "3" to the terminal, but result will be undefined.  We did some stuff, and nothing was returned.  Classic imperative code.
+
+But what if we wanted a new array with all these number squared?  We could write the following, of course:
+
+```js
+const squares = [];
+[2, 5, 3].forEach((num) => {
+  squares.push(num * num);
+});
+```
+
+But there's already a common array function that does just this: `.map(cb)`, which lets us write that as a one-liner:
+
+```js
+const squares = [2, 5, 3].map(num => num * num)
+```
+
+The squares array now contains `[4, 25, 9]`.  But why discuss arrays?  Because promises are similar.  Sometimes, you want to perform a side effect when that resolves, but sometimes, you'd like that result to be formatted in some different way.
+
+So, we're going to create a function that does just that to promises.  It's called `mapPromise`. it takes in a promise and a transformer callback, and returns a new promise that follows these rules:
+
+* If the first promise rejects with an error, the new promise rejects with that error.
+* If the first promise resolves with a result, it calls the transformer with the value as an argument.
+  * If the transformer returns with a value, the new promise resolves with that value.
+  * If the transformer throws an error, the new promise rejects with that error.
+
+## Exercise 2
+
+I have good news about the function above: it already exists!  In fact, you've been using it this whole time!  It's `.then(cb)`!
+
+In the previous exercise, we used `.then(cb)` in an *imperative* way, performing some action on the resolved value, but delayed.  But we can also use `.then(cb)` *declaratively*, returning a new promise that will resolve with a transformed value.
+
+In this exercise, we'll be passing a promise that resolves with a number or a string.  We want to return with a promise such that:
+
+* If the input promise resolves with a number, the output promise resolves with the square of that number.
+* If the input promise resolves with a string that we can turn into a number (like "1234"), the output promise resolves with the square of that number (1522756 in this example)
+* If the input promise resolves with a string that we cannot turn into a number (like "asdf"), then we reject with a message like "Cannot convert 'asdf' to a number!"
+* If the input promise rejects with an error, the output promise rejects with the same error
+
+## Exercise 3
+
+In the same way that we can use `.then(cb)` to transform a promise when it resolves, we can also use `.catch(cb)` to transform a promise when it rejects.  If we return a value from a `.catch(cb)`, we create a new promise that will resolve.  Likewise, if we throw an error in a `.catch`, the new promise will reject with that new error.
+
+We're going to refactor the above promise so that it either resolves with the square of the number if it can, or it resolves with zero.
+
+## Exercise 4
+
+One interesting feature of the `.then(cb)` function is that it can actually take in two callbacks, one for success and one for failure.  In most cases, running
+
+```js
+somePromise
+  .then(successCb)
+  .catch(failureCb)
+```
+
+is equivalent to
+
+```js
+somePromise
+  .then(successCb, failureCb)
+```
+
+But there's one noteworthy exception.  In the first code, the `.then(cb)` returns a new promise to which we attach the `.catch`.  That means that it's possible for the first promise to resolve, and the second to reject, which means that the catch could be catching failures from the first promise OR the second promise.  When we pass in the failureCb *with* the successCb, we guarantee that our failureCb is ONLY catching the rejection of the first promise.
+
+We can examine this by making a function called "switcheroo".  It'll take in a promise and return a promise such that:
+
+* If the input promise rejects with an error, the output promise will resolve with that error.
+* If the input promise resolves with a value, the output promise will reject with that value.

03-transforming-promises/answers.js

@@ -0,0 +1,63 @@
+/**
+ * 
+ * EXERCISE 1
+ * 
+ * @param {*} promise 
+ * @param {*} transformer 
+ * @returns {Promise}
+ */
+function mapPromise(promise, transformer){
+  return new Promise((resolve, reject) => {
+    /* IMPLEMENT ME!! */
+  });
+}
+
+/**
+ * 
+ * EXERCISE 2
+ * 
+ * @param {Promise<number | string>} numberPromise 
+ * @returns {Promise<number>}
+ */
+function squarePromise(numberPromise){
+  return numberPromise
+    .then(/* IMPLEMENT ME! */);
+}
+
+/**
+ * EXERCISE 3
+ * 
+ * @param {Promise<number | string>} numberPromise 
+ * @returns {Promise<number>}
+ */
+function squarePromiseOrZero(promise){
+  return squarePromise(promise)
+    .catch(/* IMPLEMENT ME! */);
+}
+
+/**
+ * EXERCISE 4
+ * 
+ * @param {Promise} promise 
+ * @returns {Promise}
+ */
+function switcheroo(promise){
+  return promise.then(/* IMPLEMENT ME */);
+}
+
+/**
+ * @callback consumer
+ * @param {*} value
+ */
+
+/**
+ * @callback handler
+ * @param {*} error
+ */
+
+module.exports = {
+  mapPromise,
+  squarePromise,
+  squarePromiseOrZero,
+  switcheroo,
+};

test/transforming-promises.test.js renamed to 03-transforming-promises/test.js

@@ -5,7 +5,7 @@ const {
   squarePromise,
   squarePromiseOrZero,
   switcheroo,
-} = require('../answers/transforming-promises');
+} = require('./answers');
 
 describe('Transforming Promises with .then(cb) and .catch(cb)', () => {
   describe('#mapPromise(promise, transformer) => Promise', () => {

04-chaining-promises/README.md

@@ -0,0 +1,62 @@
+# Chaining Promises
+
+## Exercise 1
+
+Just as we did with mapPromise, we want to envision a new way of transforming promises: chaining them.  We want to be able to have one promise resolve, then when it's done, use its value to start a second async process that returns a promise.
+
+WE DON'T WANT TO START THAT SECOND PROCESS UNTIL AFTER THAT FIRST PROCESS RESOLVES!  In this way, we can imagine that we may need some artifact from the first process before we can start the second.  For instance, we may want to create a User object in a database, get an id back, and then use that UserId to create a series of, say, services that this user can access.
+
+This chaining is a common problem in async, so let's create a function to do this.
+
+## Exercise 2
+
+I'm sure you're already a few steps ahead of me here, but just like with transforming promises with synchronous promises, we have a method to do this: `.then(cb)`!
+
+If you return a promise from your callback to .then, you won't have a promise of a promise of some value.  It'll just kinda smoosh them together, so a promise of a promise of a promise of an array just becomes a promise of an array.
+
+Let's practice that!  You're going to create an example like the one above, which will use `.then(cb)` to transform the value of a promise using another async process.  It's a little hairy.
+
+## Exercise 3
+
+The most common point of this scenario is to chain two async processes, especially when the some result of the first one is needed before we can start the second.  This is a very common technique, and we're going to use it to implement a somewhat more "real-world" scenario.
+
+Our situation is that we have two api calls, one that gets a user object by id, and one that gets an organization object by id.  The user object might look like this:
+
+```js
+{
+  id: 'u001',
+  name: 'Mike',
+  email: 'mike@mike.mike',
+  organizationId: 'o001'
+}
+```
+
+The organization object might look like this:
+
+```js
+{
+  id: 'o001',
+  name: 'Research and Development'
+}
+```
+
+We want to make a function that combines these two calls into one, making an object that looks like the following:
+
+```js
+{
+  id: 'u001',
+  name: 'Mike',
+  email: 'mike@mike.mike',
+  organizationId: 'o001'
+  organization: {
+    id: 'o001',
+    name: 'Research and Development'
+  }
+}
+```
+
+We can't get the organization object until we have the user object and the organization id.  That means that we have to request the user, wait until we have it, then request the organization, wait for it to return, and return a combined object.
+
+It's also worth noting that the getUserById function will resolve with undefined if no user is found with that id.  Then we don't have to request the organization at all!
+
+For this example, the test creates the getUserById and getOrganizationById functions, then passes them to a function that itself returns the function we want to build: one which takes in a userId and returns a combined object.