The return value will be an object. The properties of this object will vary, depending on what is loaded. We will cover module.exports next, which is what module designers and even you can use to set the value of this return value.

The require() function is used to load the module at a path, where the path can be a core module (a module packaged with Node.js), directory, file, or module (a project that you or someone else has built). As a result, it is very versatile. The require() function will try to resolve the passed-in path in this order: the core module, the directory or file if the path begins with "./", "/", "../", and then the module, take a look at the following description for more information. You then need to check the require function in different locations for all of this to work:

As a quick summary, here is the order that require will use:

Here are some examples of how the require function is used to load core modules, files, or modules:

var http = require('http'); //loads a core module

As you can see from the comment, this example will load the HTTP core module:

var data = require('./data'); //loads a directory

This example shows you how to load a directory:

var dataModels = require('./data/models'); //loads the file models.js

This one will load a file:

var redis = require('redis'); //loads a module

Finally, this one will load a module.

Every Node.js project will use require many times, so knowing how and where it will load is important.

Here is a simple example that demonstrates require and how it works with module.exports.

Here is the file that will be loaded with require, requireTest.js, and it will be loaded from a relative path:

module.exports = 'This value is from requireTest';

Here is how to load this value in a Node.js script:

var requireTest = require('./requireTest');
console.log(requireTest);

The module.exports property is the return value from the module. This can seem misleading though. We will not return module.exports. It is the object or properties set at module.exports that are available from this module.

The module.exports property is the link from the current file into the scope of the calling file. Any variables defined in the current file will not be in the scope of file that calls it. To make the variables available, you must either set them as the value of module.exports or as properties of module.exports. This functionality is the mechanism that Node.js uses with require. Exports can be set to any type: string, integer, function, object, and many others. Functions allow us to either pass in values or create a constructor() function. Objects can be created and then used to overwrite the exports object or can be added to the exports object as properties. We have all of JavaScript's function- and object-creation tricks at our disposal.

Examples of the constructor() function being used are shown here:

An example of how the os.hostname() function is used is shown here. In this case, it will return the hostname of the current computer used. It will not return the domain suffix of the computer:

os.hostname();

We will get an array of objects that map to each CPU. The objects will have the model, speed, and times:

This information can be used, most of the time, to find out how many CPUs the machine has. It is good to know this information, as Node.js is single threaded and we can launch multiple processes in a cluster for each CPU.

Here is an example of getting the number of CPUs on a computer:

var cpus = os.cpus().length;

This will be an object that contains all the network interfaces. Each property maps to an interface and it will have an array of all the IP addresses (IPv4 and IPv6).

As an example, this is how you can get the object that has all the interfaces for a computer:

var network = os.networkInterfaces();

This is the stream that will connect to stdout. Note that streams will be covered later in this chapter under Utilites. If we are running Node.js as a console application, this is where we could write to stdout if needed. Most streams in Node are non-blocking, but writes to stdout and stderr are blocking.

We also can use stdout to find out whether Node.js is running in TTY. We can access process.stdout.isTTY. This is a Boolean value.

The example here will show us how to write a message to the stdout stream. By default, this will be sent to the process.stdout.write console. This will write to stdout.

This is similar to stdout, with the key difference being it writes to stderr. This is very useful for console applications as we can write to the console what is happening.

As an example, this writes to the stderr stream. By default this will write to the console.

process.stderr.write("Something seems to have gone wrong.");

This maps to the standard stream, stdin, in the same way stdout and stderr map to the stderr streams. The difference is that the stdin object is readable, while the others are writable. Anything that is piped into this process can be read out using process.stdin. To read from a readable stream, we will have to listen for two possible events that let us know how we can retrieve data. The first is readable, and the other is data. We will cover this more in depth when we get to the stream section.

For instance, this example takes the data that is sent in through stdin and sends it to stdout using the readable event:

process.stdin.on('readable', function() {
  var data = process.stdin.read();
  if(data !== null) process.stdout.write(data);
});

The argv commands will be an array of all the arguments passed into this script. Arguments are split by spaces. This means that debug=true (which has no spaces) will be one argument, and debug = true (a space between each word) will be three. This is an important distinction to keep in mind if you want to pass values in arguments. Arguments 0 and 1 will always be the node and the path and filename of the current script.

Here is an example:

process.argv.forEach(function(val){ if(val === 'debug'){ debug(); } });

All of the POSIX signals, except SIGKILL and SIGSTOP, can be listened for. In addition to these signals, you can also listen for some Windows signals. Here is the list of signals:

Here is an example of listening for SIGINT, which recognizes that Ctrl + C was pressed:

process.on('SIGINT', function(){
  //ctrl+c was pressed
});

The process.env object is a simple JavaScript object that contains all the environment variables. Each property will be a string.

A great place to put configuration settings is in the environment when building an extensible application. The process.env object can then be used to check whether the current environment is in production or even to just store the configuration settings.

Here is an example of checking for environment and setting a value from the environment:

if(process.env.NODE_ENV !== 'production')
  //do test stuff
var redisHost = process.env.REDIS_HOST;

This will send any of the signal events that are defined in the signal events section, which that we covered earlier. This is essentially running the POSIX kill command.

We can use this kill command to send the current process a signal, using process.pid, or to send another process that we have a reference to the kill signal.

Here is an example of killing the specific process ID 4634:

process.kill(4634, 'SIGTERM');

It is the pid (process ID) of the process.

This is an example of process.kill and process.pid used together:

process.kill(process.pid, 'SIGTERM');

The __filename command returns the current filename. This can be different, depending on which file is being executed. A module that is being executed will return its filename instead of the main entry point.

Here is an example of logging the current filename to the console:

console.log(__filename);

Much like __filename, this will return the currently executing file's directory. The __dirname command is used many times when a relative path needs to be created.

This example assumes Express has been loaded as express:

//express is loaded
app.use(express.static(__dirname + '/static'));

The stat variable gets the the data that would be returned after running stat() on the operating system. The stat object is an instance of fs.Stats. This object gives us useful functions such as isFile() and isDirectory(). In addition to this, fs.Stats has many properties. We can see the modified time, access time, and file size.

There are more functions and properties, but these are the most likely used.

The fs.lstat() and fs.fstat() functions will both return an fs.Stats object when pointed to a file. The difference is that lstat will run against a link instead of following the link to the file or directory. The fstat runs against a file descriptor instead of a path.

Here is an example that loads a file named test.txt in the same directory as the code file and logs the fs.Stats object:

fs.stat(__dirname + '	est.txt', function(err, stats){
  console.log(stats);
});

This will open a file in the path passed in. There are many flags that can be passed. They are described here:

The flags allow you to open, read, and write a file, whether it exists or not. This means that most of the time, a call to fs.exists is not required as one of the flags will give you the answer you need.

The mode parameter is the permissions that are used if a file is created. It defaults to 0666.

Finally, the callback returns a file descriptor. With this, data can be read or written using fs.read or fs.write.

This is an example of opening the file test.txt:

fs.open(__dirname + 'file.txt', 'r', function(err, fd){
  //fd is available to be read from
});

The read() function takes a lot of parameters to run. We need a file descriptor, which we get from open, a buffer, and the size of the file. In the example, we used fs.stat to get the file size.

Here is a full example of opening a file and reading from it:

fs.stat(__dirname + '/test.txt', function(error, stats) {
  fs.open(__dirname + '/test.txt', 'r', function(err, fd){
    var buffer = new Buffer(stats.size);
    fs.read(fd, buffer, 0, stats.size, null, function(err, bytesRead, buffer){
      console.log(buffer.toString('utf8'));
    });
  });
});

The readFile() function greatly simplifies the process of reading a file in Node.js. In the previous function, fs.read, we needed to set everything up before we tried to read the file. The readFile() function allows us to just pass a filename and get a buffer back of what is in the file.

The optional options object takes a flag and an encoding property. The flag property is the same as the flag from fs.open, so any of them can be used. The encoding is used for the buffer that is returned in the callback.

Here is an example that demonstrates how much easier it is to load a file with readFile. The example is also using the optional options parameter:

var filename = __dirname + '/test.txt';

fs.readFile(filename, {flag: 'r', encoding: 'utf8'}, function(err, data){
  console.log(data.toString('utf8'));
});

It is important to close any files that we open in our scripts. If we get a file descriptor from fs.open, we will need to call fs.close on that file descriptor at some point.

This is an example of closing a file descriptor:

fs.close(fd, function(err){
  //handle err here
});

The write() function takes a file descriptor and buffer to write to a file. Much like read, we have to pass in quite a few parameters to make this work.

In the following example, we are reading a file into a buffer and then writing that buffer back out to another file. The offset and length are both integers that we need to pass in. The position can be an integer, but it can also be null. Null will start writing at the current position in the file.

Just like read, write can be complex. Here is a full example of reading from one file and writing to another:

var fs = require('fs');
var filename = __dirname + '/test.txt';
var writeFile = __dirname + '/test2.txt';

fs.stat(filename, function(error, stats) {
  fs.open(filename, 'r', function(err, fd) {
    var buffer = new Buffer(stats.size);
    fs.read(fd, buffer, 0, stats.size, null, function(err, bytesRead, buffer) {
      fs.open(writeFile, 'w', function(err, writeFD) {
        //will create a file named test2.txt with the contents from test.txt
        fs.write(writeFD, buffer, 0, buffer.length, null, function(err, bytesWritten, writeBuffer) {
          console.log(writeBuffer.toString('utf8'));
        });
      });
    });
  });
});

Exactly like the difference between read and readFile, writeFile is a simplified version of write. We just pass in a filename and a string or buffer, and it will write the file.

The callback only returns an error when it occurs.

readFile and writeFile seem like the best choices in most cases, and in fact, this is most likely true. The main thing that you give up using these functions is control. You can only read an entire file or write an entire file.

Here is an example of writeFile:

var filename = __dirname + '/write.txt';
var buffer = new Buffer('Write this to a file.', 'utf8');
fs.writeFile(filename, buffer, {encoding: 'utf8', flag: 'w'}, function(err){
  if(null !== null){
    //do something
  }
});

appendFile exists because writeFile will only write an entire file. So, we need another function to add to a file. This is where giving up some control for ease comes in. If we were using a file descriptor and write, then we could choose to start writing at the end of the file. This is effectively appending the file:

Here is an example of appendFile:

var filename = __dirname + '/write.txt';
var buffer = new Buffer('Append this to a file.', 'utf8');
fs.appendFile(filename, buffer, {encoding: 'utf8', flag: 'w'}, function(err){
  if(null !== null){
    //do something
  }
});

Normalize will fix many problems associated with reading paths. A great example of this is the difference between Windows and Unix paths. Unix uses forward slashes, and Windows uses backslashes. Normalize will return the correct slashes based on the system it is executed on.

In addition to this, normalize will also remove the current directory and parent directory shortcuts, (. and .. respectively). It will also remove double slashes from a directory. It normalizes any paths passed in.

Here is an example of using Unix slashes on a Windows system. This example will change all the slashes to backslashes:

var pathString = "/unix/style/path/separators";
console.log(path.normalize(pathString));

Join makes it easy to create a path from partial paths. This seems like something that can be done with concatenation, but it is easy to forget about path separators. Join will make sure that the path separators will all be in the correct spots.

Here is an example of join. The example will take all the parameters and join them together with the correct slash for your system:

console.log(path.join('path', 'separators', 'added'));

This can be viewed as the cd command executed for each parameter. The paths passed in can be relative or full paths. A relative path will add to the returned path, and a full path will be used whole.

Here are two examples:

The path returned can be used with cd to change to the new directory.

Here is an example that will return ../../brian/node, because you must go up two parent folders and over to brian/node to get from one to the other:

var from = '/home/josh/node';
var to = '/home/brian/node';
console.log(path.relative(from, to));

This will either return the filename or directory depending on what path is passed in. The optional ext parameter will remove that portion from the return value if it exists.

Here are two examples, one involving a file and the other a directory:

The main way REPL will be used is by calling it directly. This can be done by executing Node.js without a file to serve, by running just node. Once node has returned with a prompt, we can add commands and see what happens when we run them. This is perfect to test a few lines of code.

Here is a quick example of logging in to the console; first run node to get a prompt and then run the command:

node
//wait for >
console.log('hey this REPL!');