Your First App: Node.js

The first edition of this book simply asked readers to "install Node.js" and pointed to nodejs.org. I didn’t see this as a problem at the time because Node.js has been pretty good about being backward compatible. Don’t worry, it’s still backward compatible in that you can write the same JavaScript code today as you could 3 or 4 years ago.

In 2015, a couple years after I began writing the first edition of this book, Node.js decided to integrate the excellent work of a Node.js fork called io.js. The problem was that Node.js was on version 0.12 while io.js was version 3.0, so the Node.js Foundation had to resolve version differences for both communities. The result: Node.js 4.0 was the release following Node.js 0.12.^[2]

I was conflicted for a while in regards to how I’d account for these version differences. The aim of this book is to walk you as a reader through the entire development process, gaining skills that I feel are often overlooked in tutorials or even in higher education. On the other hand, a reader will be less likely to read a book targeting Node.js 0.12 when the current stable version (as of June 2017) is v6.11.0 LTS. Right?

Technology is ever changing. I contributed a bug fix in the beginning of 2013 to Node.js which landed in version 0.9.10, and by the time I had finished writing the first edition of this book on Leanpub we were on version 0.12. By September 2015, we were at v4.0.0. By March 2016, we were on v4.4.0. These quick releases may appear to indicate that applications written in older versions of the library are outdated. This isn’t necessarily the case. Many of the commits which warrant a bump in versions are related to documentation and tooling. There are plenty of bugfixes and performance improvements as well. After v4.0.0, there has been a lot of effort to support ES6 and ES7 language features. Few of these changes, if any, will have any impact to the techniques you’ll learn in this book.

There are times that Node.js APIs will change, and these are referred to as "breaking changes". As an example, a breaking change in Node.js v4.0.0 makes ChildProcess.prototype.send() execute asynchronously across all platforms. If you were to naively upgrade from v0.12 to v4.0.0, you may experence numerous issues if you haven’t read through the breaking changes (don’t worry, we’ll cover a similar scenario later in the book). This was my conundrum; upgrading to the newest version of Node.js would be no small feat as the changelog between these versions is enormous.

I decided to use nvm, a node version manager utility, to reduce any confusion or complexity for current and future readers. This will solve almost all problems, excluding unforeseen silliness.

First, install the current stable version of Node.js. This can be downloaded directly from nodejs.org. While there may be other options for installing Node.js on your operating system, these may cause conflicts with the official installers so I don’t recommend them.

When installation completes, you’ll want to verify that the node binary is installed and available on your path:

Now install nvm. Instructions are taken from nvm’s README:

Reload your shell or execute source ~/.bashrc to consume the necessary changes in your terminal session.

This is the only way to install nvm. If you’re familiar with node and npm, you may attempt to install nvm as a global node module. If you’ve done this, you’ll receive a warning stating "This is not the package you are looking for: please go to http://nvm.sh".

Now, you’re free to install any version of Node.js through nvm and your terminal session will use that version only. This has the added benefit of installing modules and plugins to a sandboxed location for that specific version of node. This means that none of the commands in this text will interfere with your system installation of Node.js if you’re already using it for other projects.

Install Node.js v0.12.0:

Now check the list of installed Node.js binaries:

The top arrow (->) indicates the current selected version. You can verify this by executing node --version again. If your terminal supports colors, you’ll notice the last three lines have colored the N/A text in red. This means those binaries are not installed. You can install these either by name or version. For example, I tend to use unstable versions of Node.js, so I don’t have 6.11.0 installed. I can install it either by name:

or version number:

You can switch between versions with nvm use, and because nvm installed bash completions, you can TAB complete your installed versions.

To uinstall a version of node’s binaries, you’ll need to nvm use a different version first.

If you want to drop back to the system-installed binaries, you can run nvm unload or nvm deactivate to remove nvm’s orceshtration from your current shell.

I recommend setting your system binary as the default:

Lastly, as you work through this book, you can tell nvm to use v0.12.0 for this project using a .nvmrc file. I realize you may not have a directory or code setup for the book at the moment, but be sure to revisit this section for details. From your project’s root directory:

Now, when you enter the project’s directory you can run nvm use and it will automatically select the correct version.

That’s a lot of information. Here’s a short terminal session demonstrating the use of nvmrc:

A lot of people with a classical language background seem struggle with JavaScript or Node.js. A classical language is one in which a class can derive from another class. An instantiation of that class chain is called an object. In a classical language, the class constructor(s) or the object itself maintain all behavioral logic of the object. In a prototypal language^[4], objects inherit from other objects. This means that an object can contain not only the behaviors of other objects, but essentially derive from another fully constructed object. You might think this sounds complex (or even insane), but prototypal inheritance opens the door for fun features. It also allows for some annoying bugs if implemented improperly. This forces the community to create standards and patterns to help us avoid those bugs. If you’re not familiar with prototypal languages, be sure to read the Wikipedia article^[5] on the subject for a basic understanding.

In JavaScript, pretty much everything is an object. Even literals (e.g. var x = 100;) are special types of objects. Functions are also special types of invokable objects.

An object in JavaScript is just an associative array (or a map, if you prefer). It is a collection of keys in which each point to a value. This is often forgotten by newer members of the community because of the helpful dot-notation. For example, look at the following object literal which assigns a value to a key in dot notation:

Now, consider that an object is just a container of key,value pairs. If you wanted to store the result of n², you may do so like this:

Realize, however, that using non-contiguous and non-alphanumeric text for keys can make the usage of your object difficult. For a more detailed explanation of objects in JavaScript, check out MDN: Working with Objects.

JavaScript has the concept of equality (==) and strict equality (===). The standard equality operator (==) applies some oddly complex type coercion rules to each side of the equals signs. For example, look at the following Node.js REPL output:

If you’re not familiar with a REPL environment (REPL stands for read-eval-print-loop), the first line executes node, and subsequent lines either begin with a > to indicate user input or no preceding character to indicate an evaluated result. If you are annoyed by the above results, check out the following results using strict equality:

Better, right?

In short, I recommend always using the strict equality (===) operator unless you are 100% certain the coerced value is what you intend and there is a comment in code to indicate this intention.

I’ve known engineers who would gladly argue all day long about whether scope and context are the same thing. Rather than attempt to define these two somewhat loaded broader terms, I’ll discuss functional scope and execution context.

The JavaScript environment we’ll be using is based on ECMAScript 262, Edition 5. There are newer specifications for more recent additions to the language, but we focus on this version because it’s easier to consume.

An execution context maintains three things: variable environment, lexical environment, and the binding to this.

The specification later explains that there is an internal property called [[Scope]] which refers to the lexical environment of the execution context. This scope property is defined in Table-9 of the document:

Whenever a function executes, it does so in a certain context. This context defines the variables (functions and objects) it creates internally as well as the variables it has access to externally (as a result of being nested within other functions). Resolution of variables propagates all the way up to the global environment. This is how I define functional scope.

One gotcha is that functions are lexically scoped, meaning this variable resolution order is determined by where a function is declared and not by where a function is invoked. This is the basis for closures; we can define a function which is returned from another function and encapsulate any variables from the enclosing or outer function privately.

When people refer to context, I don’t think they’re talking about execution context as much as they are talking about the value of this in the current execution context. Consider the following example which demonstrates the value of x in different contexts.

In this code example, you may be wondering how the context has changed between functions a, b and c. To demonstrate, I created a variable x in each lexical environment for a given function. Notice how the value 5 is never displayed.

In function a, the reference bound to this is the object named example.

In function b, we indirectly change the bound context by returning a function from within a function which in turn changes the encapsulating object (e.g. scope) of the final function. You may expect this resulting function to print 5, but the x variable is susceptible to the same rules here as it is in function a: the encapsulating context’s this is actually bound to the global execution environment (node, in our case).

When we see a output 9999, we are using the special function .call() which allows us to manipulate the bound this context. Rather than relying on the example object as context, we can easily pass in a literal object with any value we want! Usually, when I say something is changing context, this is what I’m talking about. There are two special functions which can change the value of this at the point of invocation: call() and apply().

Funcion c demonstrates a third way to modify the this bound context. The interesting thing about this approach to contextual modification is that bound functions can not have their context changed at runtime after being bound. On line 21, var execB = this.b().bind(other);, the .bind(other) protects function b's context from being modified after this line. You’ll see this in the output if you run the example. If we attempt to use call() as we did on function a, the context is not changed at all. This allows us to essentially lock down function context when working with or creating our own modules.

A special case for the scope and context discussion is the use of constructor functions. A constructor function is a function which creates an object and, as we saw in the example object above, a new execution context. The community standard for differentiating constructor functions from normal functions is to format normal function names in camel case (likeThis) and constructor functions in pascal/title case (LikeThis). Unfortunately, the visual hint of beginning with a capital letter is only a hint.

To actually execute a constructor function as a constructor, you must call it with the new operator, such as var x = new FunctionName();. Take a look at what happens when you call a constructor function without the new operator:

In this example, we’re getting a reference to this and assigning it to self so we can access the cunstructor function instance from within the look method.

If you run the above example using node, you’ll see a lot of output you probably didn’t expect:

We’re printing the value of x, then dumping the full structure of each object. How did object B get all that extra stuff in it? For starters, I’ve cheated a bit on the last line of the constructor function. If a constructor function doesn’t return a value, the default behavior is to either return the bound this object. Using the new operator creates a new this context, while skipping the new operator causes this to be bound to the global object. That is, when you call a constructor function without the new operator, you’re just calling a function within the current execution context. In the above output, the execution context is the node global space (sometimes referred to as the global context). Had I skipped line 11, object A would have worked exactly as it had before but object B would have been undefined. Some people try to avoid this issue by using a constructor guard or marking the function itself with 'use strict';.

The problem with the constructor guard is that it can cause issues or complexities with prototypal inheritance. The 'use strict'; directive prevents accidentally leaking the internals of your object to the global scope; the value of this is undefined when the constructor is called without the new operator.

If you still have questions or concerns regarding constructor functions, read about it further on the Mozilla Developer Network.

Node.js is a server-side JavaScript environment which provides evented asynchronous I/O and a minimalistic set of core features. In the beginning, Node.js combined v8 with libev. Unfortunately, libev is an evented I/O library for Unix-based systems only. Eventually, libev was replaced with a higher-level abstraction library called libuv which allows Node.js to run on Unix-based systems and Windows. In 2011, Microsoft began contributing to Node.js to bring it to the Windows platform. More recently, libuv removed libev as a dependency which helped with bringing Node.js to Windows.

The key concept for Node.js is evented I/O (mostly network-based) operations. This is handled via an event loop. Although understanding the implementation details of event loops can be pretty complicated, the idea is fairly simple. Let’s analogize.

Try to think about an application as a fast food restaurant. A cashier is patiently waiting at the register. A customer walks up to the register and places an order. The cashier hands the order off to the kitchen and maybe fulfills the customer’s drink order before returning to the register. Another customer arrives and places an order, initiating the same scenario as before. A third customer is walking to the register, but just before the customer reaches the register a cook dings a bell and the cashier steps away to grab the first order and hand it to the first customer. The cashier then begins taking the third customer’s order. Midway through the order, the second customer’s order is ready. Because the cashier is not rude (maybe this is in Canada?), the third order must be completed before the second customer’s order can be handed to the second customer. But, the cashier can easily hand over the second customer’s order before filling the third customer’s drink order. Eventually, the third customer’s order is fulfilled and there are no more customers. The cashier waits patiently.

It may sound strange, but the above scenario is a simplification of an event loop. We see things like this every day. New Node.js developers may have a hard time conceptualizing the event loop or understanding where it comes from, so I 'll show a few concrete examples in Node.js. For instance:

There’s a little more here than the obligatory printing of "Hello, world!" I’ve wrapped the output line in a function called main and subsequently called that function. If you run this file, you’ll see that it prints out "Hello, world!" and exits. For our purposes there is no event loop because we haven’t told the runtime to listen to or emit any events.

There are a couple ways we can initiate an event loop. Possibly the easiest way to visualize this is to use the standard JavaScript setInterval function to cause our application to write out "Hello, world!" every 250ms. To kill this application, you’d need to press CTRL-C.

The above example is technically an event loop, thanks to the setInterval function. Another way to initiate an event loop is to bind to or set up any event which interacts in some way with a file handle. In Unix, nearly everything is considered a file, so this would mean binding to a socket, file descriptor, or event screen input:

In the above example, process.stdin.resume() causes Node.js to continually monitor the readable standard input stream for data. Binding a listener to watch for SIGINT does not cause node to create an event loop on its own. Play around with this last example to get an idea of how the event loop works. When you’re done, type CTRL+C to exit (this sends SIGINT to the process). If you’re interested in how libuv creates and maintains an event loop, there is a free uvbook^[7] available which dives into the internals of libuv.

The Node.js library is meant to be very low-level. Rather than a traditional web server with plugins, modules and other froofiness, there are servers specializing in tcp, udp, and http connectivity. Instead of giving you modules for interacting with a variety of file types (PNG, JPEG, etc.), there are readable and writable streams. This can be intimidating. Luckily, the Node.js community produces and shares a large repository of open source modular code, called npm.

The npm project provides Node Packaged Modules and is bundled together with Node.js in recent versions (recent means v0.6.3 or higher).

We won’t go in depth on npm. All you need to know to get started is that npm handles package management via a package.json file and that you can install modules locally (within your project) or globally (accessible to your entire system). If you’ve used other package managers like bundler, bower, NuGet, or any others, you’ll pick up on npm quickly.

Facebook maintains another Node.js package manager called yarn. I personally prefer using yarn because it’s a little faster and does sane things ()like creating a version lockfile) by default. I don’t cover yarn because it would just be an extra thing to learn in this book, and it offers marginal value over npm.

Don’t be put-off by the low-level nature of Node.js core libraries. Many of the modules in the npm repository are production-ready and allow you to build applications and modules atop a very customizable software stack.