Doc: Adding guide on Timers

doc/guides/timers-in-node.md

@@ -0,0 +1,114 @@
+---
+title: Timers in node.js
+layout: docs.hbs
+---
+
+# Timers in node.js and beyond
+
+Timers are a collection of global functions in node.js that allow you to execute code after a set period of time. To fully understand when timer functions will be executed, it's a good idea to read up on the the node [Event Loop](https://nodesource.com/blog/understanding-the-nodejs-event-loop/).
+
+## Code Time Machine
+
+The node API provides several ways to schedule your code to execute at some point after the present moment.
+
+### "When I say so" Execution ~ *setTimeout()*
+
+Using `setTimeout()`, you can schedule code to execute after a designated amount of milliseconds. You may already be familiar with this function, as it is a part of V8 and thus part of the browser JavaScript API.
+
+`setTimeout()` accepts the code to execute as its first argument and the millisecond delay defined as a number literal as the second argument. Here is an example of that:
+
+```javascript
+function myFunc () {
+  console.log('funky');
+}
+
+setTimeout(myFunc, 1500);
+```
+
+The above function `myFunc()` will execute after approximately 1500 milliseconds (or 1.5 seconds) due to the call of `setTimeout()`.
+
+The timeout interval that is set cannot be relied upon to execute after that *exact* number of milliseconds. This is because executing code that blocks or holds onto the event loop will push the execution of your timeout back. You *can* guarantee that your timeout will not execute *sooner* than the declared timeout.
+
+### "Right after this" Execution ~ *setImmediate()*
+
+`setImmediate()` allows you to execute code at the beginning of the next event loop cycle. This code will execute *before* any timers or IO operations. I like to think of this code execution as happening "right after this", meaning any code following the `setImmediate()` function call will execute before the `setImmediate()` function argument. Here's an example:
+
+```javascript
+let order = 'before immediate\n';
+
+setImmediate(() => {
+  order += 'executing immediate\n';
+});
+
+order += 'after immediate\n';
+
+console.log(order);
+```
+
+The above function passed to `setImmediate()` will execute after all runnable code has executed, and the console output will be:
+
+```shell
+before immediate
+after immediate
+executing immediate
+```
+
+Note: `process.nextTick()` is very similar to `setImmediate()`. The two major differences are that `process.nextTick()` will run *before* any immediates that are set. The second is that `process.nextTick()` is non-clearable, meaning once you've scheduled code to execute with `process.nextTick()` you cannot stop that code, unlike with `setImmediate()`.
+
+### "Deja vu" Execution ~ *setInterval()*
+
+If there is a block of code that you want to execute multiple times, you can use `setInterval()` to execute that code. `setInterval()` takes a function argument that will run and infinite number of times with a given millisecond delay. Just like `setTimeout()`, the delay cannot be guaranteed because of operations that may hold on to the event loop, and therefore should be treated as an approximate delay. See the below example:
+
+```javascript
+function intervalFunc () {
+  console.log('Cant stop me now!');
+}
+
+setInterval(intervalFunc, 1500);
+```
+In the above example, `intervalFunc()` will execute every 1500 milliseconds, or 1.5 seconds, until it is stopped (see below).
+
+## Master of the Timerverse
+
+What would a Code Time Machine be without the ability to turn it off? `setTimeout()`, `setImmediate()`, and `setInterval()` return a timer object that can be used to reference the set timeout, immediate, or interval object. By passing said objective into the respective `clear` function, execution of that object will be halted completely. The respective functions are `clearTimeout()`, `clearImmediate()`, and `clearInterval()`. See the example below for an example of each:
+
+```javascript
+let timeoutObj = setTimeout(() => {
+  console.log('timeout beyond time');
+}, 1500);
+
+let immediateObj = setImmediate(() => {
+  console.log('immediately executing immediate');
+});
+
+let intervalObj = setInterval(() => {
+  console.log('interviewing the interval');
+}, 500);
+
+clearTimeout(timeoutObj);
+clearImmediate(immediateObj);
+clearInterval(intervalObj);
+```
+
+## Last Train to Nowhere
+
+The node Timer API provides two functions intended to augment timer behavior with `unref()` and `ref()`. If you have a timer object scheduled using a `set` function, you can call `unref()` on that object. This will change the behavior slightly, and not call the timer object *if it is the last code to execute*. Instead, it will let the program exit cleanly.
+
+In similar fashion, a timer object that has had `unref()` called on it can remove that behavior by calling `ref()` on that same timer object, which will then ensure its execution. See below for examples of both:
+
+```javascript
+let timerObj = setTimeout(() => {
+  console.log('will i run?');
+});
+
+// if left alone, this statement will keep the above
+// timeout from running, since the timeout will be the only
+// thing keeping the program from exiting
+timerObj.unref();
+
+// we can bring it back to life by calling ref() inside
+// an immediate
+setImmediate(() => {
+  timerObj.ref();
+});
+```