DEV Community: Joe Shindelar

Use Module.exports to Keep Node.js Code Organized

Joe Shindelar — Thu, 20 Dec 2018 16:55:21 +0000

Use Module.exports to Keep Node.js Code Organized

Written by Jon Church and Joe Shindelar. Originally published on Medium.

Node doesn’t care if we write our entire project in one huge index.js file. But if you want people to be able to read your code, you need to organize it in a way that makes sense and is easy to maintain. Enter Node’s module system!

What exactly is a module? Modules organize related functions together into a file, that we can import later when we need to use them. A module encapsulates related code into a single unit, usually stored in a file. Every file in Node can be considered a module, and each has its own module global object available in the file that we will use to expose code for importing in another file.

In this tutorial we’ll:

Learn about module.exports
Export helper functions from a file
Include our helper functions in another file using require

By the end of this tutorial you should be able to use Node’s module system to create your own modules so you can reuse code in your project.

Goal

Import helper functions from helpers.js in another file, index.js.

What is module.exports?

To export code from a file, we assign values to the file's module.exports object. Each JavaScript file in Node has a module.exports object in its global scope that represents that specific file. That object will hold any code that we want to export from the file. We can assign an object, a single function, or any value to module.exports to be used again in another file.

This is part of the module system in Node. Each file has a global object in its scope called module , which holds information about that specific file. We can expose code from that file by assigning it to module.exports.

What is `require`?

Require helps us load modules. To import code from a file, we must pass the file’s path to require: require('./filepath'). Calling require on a JavaScript file will run the code in the file, and return the value of module.exports.

This is actually very similar to what happens when you require an npm module. Except in this instance, we are passing require a path to a file instead of the name of a package. When you require an npm package, the same thing is happening behind the scenes in your node_modules/ folder, where the package is installed to.

Here we export a string from a file called testModule.js:

// testModule.js
module.exports = "This is a test!"

// index.js
const test = require('./testModule.js')
console.log(test) // => "This is a test!"

In any given file, we can assign things to module.exports to allow us to import them in another file using a require statement.

When the require is called with a file path, the code in that file will be evaluated and module.exports will be returned.

// helpers.js
console.log('I got required!)
module.exports = "Exported!"
// index.js
const exportedValue = require('./helpers.js')

The above code will output “I got required!” to the console, and exportedValue will be equal to “Exported!” .

If we rerun the require statement (after the first instance), we would still get the exported value of module.exports, but the console.log would not run again. This is because require statements are cached; they are run once, and then calling them again will just return the value of module.exports.

You might also see ES6 code like this at some point:

// helpers.js
export default = "I'm an export!"

// index.js
import helpers from './helpers.js'

This uses ES6 module syntax, and currently no Node engine supports this by default. You can use this style if working with something like Babel that transpiles your code for you. But for now, know that we are talking about the CommonJS syntax of exports, module.exports .

Creating a Helpers File

So let’s use module.exports to export some functions from a helpers.js file to do some simple math, and then use them in another file, index.js, with the help of require.
One option is to export a single anonymous function from a file.

Let’s export a single function that multiplies a number by 2 and use it in our index.js file:

// helpers.js
module.exports = function(x) {
    return x * 2
}

// index.js
const helpers = require('./helpers.js')
helpers(4) // => 8

We set the value of module.exports to the function we want to import, and require it in index.js.
Handy, but what if you want to export several functions at once? Well, we can export an object literal that holds several functions, then access the functions by their names. This is also called Named Exports, because we can choose to later import only the properties we want by name.

// helpers.js
module.exports = {
    multiplyByTwo: function(x) { return x *2 },
    divideByTwo: function(x) { return x / 2}
}

// index.js
const helpers = require('./helpers.js')
helpers.multiplyByTwo(10) // => 5
// or, you can import just the named property you need
const divideByTwo = require('./helpers.js').divideByTwo
divideByTwo(18) // => 9

Requiring the file returns the object we exported with module.exports . You can also import only the property you need, by using dot syntax after the require statement.

Instead of having to declare the functions all in one place, we can make use of a different syntax. Here, we directly export a named property on the module.exports object.

// helpers.js
module.exports.multiplyByTwo = function(x) { return x * 2 }
module.exports.divideByTwo = function(x) { return x / 2 }
function nonExportedFunction(x) {
    return x * 3
}
// index.js
const helpers = require('./helpers.js/)
const divideByTwo = require('./helpers.js').divideByTwo

In the code above, module.exports will look the same as the object we exported in the previous example. Both will be an object with two keys, multiplyByTwo and divideByTwo. The only difference is that we assigned them one at a time.

Note: Make sure you don’t mix the above syntax with exporting an object directly. If you assign something to module.exports later in your file, it will overwrite anything you had already exported.

// helpers.js
module.exports.multiplyByTwo = function(x) { return x * 2 }
module.exports.divideByTwo = function(x) { return x / 2 }
module.exports = "I just overwrote all my exports! Don't mix these styles!"

Passing arguments to a module

We can have a little fun with our math helpers by using some currying. Currying is a concept from functional programming: you call a function with a variable and get another function back that has that variable baked in already. It’s a sort of configuration, if you will. That’s a simple way to put it, but it can be very powerful.

Let’s make our math functions center around a single number to do operations with. We can pass in that number when requiring the file, and get back functions that multiply, divide, or add with the number we initially passed to our curry function.

// curryHelpers.js
module.exports = function(x) {
    return {
    multiply: function(y) { return y * x },
    divide: function(y) { return y / x },
    add: function(y) { return y + x }
    }
}

// index.js
const byTwo = require('./curryHelpers.js')(2)
const byTen = require('./curryHelpers.js')(10)

byTwo.multiply(5) // => 10
byTwo.divide(14) // => 7
byTwo.add(9) // => 11

byTen.multiply(5) // => 50

This is an example of passing a variable into a file’s scope using require and module.exports. We passed the number 2 into the curryHelpers file’s scope by calling the function returned by require. The object of functions we exported are now configured to multiply, divide, and add any number passed to it by the initial number we passed in, 2. We did the same thing with the number 10, and got back an object of functions configured with the number 10.

`exports` as shorthand for `module.exports`

Finally, a shorthand for module.exports can be used. The exports object is globally available as well, and points to the same object as module.exports.

So the following code is equivalent:

// assigning named exports
module.exports.pizza = true
exports.pizza = true

// exporting an object
module.exports = {}
exports = {}

Wrapping up

Node is a very modular language, and you can take advantage of that yourself by using module.exports to help export and reuse code in your project. Using require, you can import that code in any other file in your project. The idea of importing modules is very common in Node and understanding module.exports will help you navigate that modular approach.

I hope you’re able to use some of these patterns in your code!

If you want to learn more about module.exports and how it works, you could learn about module scope and the CommonJS module system.

Lullabot Education is ramping up our Node.js training. Sign up for our newsletter and learn about upcoming guides and tutorials — and help shape the future of Node.js education.

Read/Write JSON Files with Node.js

Joe Shindelar — Tue, 18 Dec 2018 17:15:57 +0000

Read/Write JSON Files with NodeJS

Written by Jon Church and Joe Shindelar. Originally published on Medium.

When you want to store data between server restarts with Node, JSON files are a simple and convenient choice. Whether you are reading a config file or persisting data for your application, Node has some built in utilities that make it easy to read and write JSON files.

Using JSON files in your app can be a useful way to persist data. We will look at a few different methods for working with JSON files.

In this tutorial we will:

Read JSON data from disk
Learn to use fs module to interact with the filesystem
Persist data to a JSON file
Use JSON.parse and JSON.stringify to convert data to and from JSON format

By the end of this tutorial you should be able to work with JSON files using Node’s built in fs module.

Goal

Say you have a customer.json file saved to disk that holds a record for a customer in your store.
As part of your store app, you want to access the customer's address, and then update the order count after an order is placed.

In this tutorial, we are going to look at how to read and write to our customer.json file.

// customer.json
{
    "name": "Mega Corp.",
    "order_count": 83,
    "address": "Infinity Loop Drive",
}

Work with files with `fs`

Accessing files in Node is done with the native module [fs](https://nodejs.org/api/fs.html), which gives you functions to watch, read, and write files along with many other tools to work with the filesystem. Because it's a native module, we can require it in our code without installing it. Just call const fs = require('fs').
The fs module gives us the option of synchronous or asynchronous versions of many of its functions. The synchronous versions block execution of other code until they are done accessing the filesystem, reading, or writing data. An async function will run without blocking other code. You can learn more about sync/async behavior here.

This synchronous behavior can be useful in some places, like at startup when reading a config file before any other code is run, but becomes a big issue when used in a webserver where all incoming requests would be blocked while a synchronous file read is running. For this reason, you generally want to use the async versions of fs functions in your code. We will focus on async operations, but will also show the synchronous equivalent.

To read and write files asynchronously with fs we will use fs.readFile and fs.writeFile.
We also will use the global JSON helper to convert objects to JSON strings, and JSON strings to objects.

Reading a JSON file
The simplest way to read a JSON file is to require it. Passing require() with the path to a JSON file will synchronously read and parse the data into a JavaScript object.

const config = require('./config.json')

But reading JSON files with require has its downsides. The file will only be read once; requiring it again returns the cached data from the first time require was run. This is fine for loading static data on startup (like config data). But for reading a file that changes on disk, like our customer.json might, we need to manually read the file using the asynchronous fs.readFile.

Reading a file with **fs.readFile**
To access the customer's address, we need to:

read the JSON data from the file
parse the JSON string into a JavaScript object

To load the data from customer.json file, we will use fs.readFile, passing it the path to our file, an optional encoding type, and a callback to receive the file data.

If the file is successfully read, the contents will be passed to the callback.

const fs = require('fs')

fs.readFile('./customer.json', 'utf8', (err, jsonString) => {
    if (err) {
        console.log("File read failed:", err)
        return
    }
    console.log('File data:', jsonString) 
})

'./config.json' is the relative path to the the file
'utf8' is an optional parameter for the encoding of the file we are reading, this can be left out
(err, jsonString) => {} is the callback function that runs after the file has been read

Now we have the contents of the file as a JSON string, but we need to turn the string into an object.

Before we can use the data from the callback in our code, we must turn it into an object. JSON.parse takes JSON data as input and returns a new JavaScript object. Otherwise, we would just have a string of data with properties we can't access.

**JSON.parse** can throw exception errors and crash our program if passed an invalid JSON string. To prevent crashing we wrap **JSON.parse** in a **try catch** statement to gracefully catch any errors.

This example shows reading and parsing a JSON file:

const fs = require('fs')

fs.readFile('./customer.json', 'utf8', (err, jsonString) => {
    if (err) {
        console.log("Error reading file from disk:", err)
        return
    }
    try {
        const customer = JSON.parse(jsonString)
        console.log("Customer address is:", customer.address) 
                // => "Customer address is: Infinity Loop Drive"

    } catch(err) {
        console.log('Error parsing JSON string:', err)
    }
})

Using the jsonString from reading customer.json, we create an object, and can access the address property. If JSON.parse throws an error, we handle it in the catch block.
Now we have an object representation of the data in our customer.json file!

We can also read the file synchronously using fs.readFileSync. Instead of taking a callback, readFileSync returns the file content after reading the file.

try {
    const jsonString = fs.readFileSync('./customer.json')
    const customer = JSON.parse(jsonString)
} catch(err) {
    console.log(err)
    return
}

console.log(customer.address) // => "Infinity Loop Drive"

We can use this knowledge to create a reusable helper function to read and parse a JSON file.
Here we create a function called jsonReader that will read and parse a JSON file for us. It takes the path to the file and a callback to receive the parsed object and any errors. It will catch any errors thrown by JSON.parse for us.

const fs = require('fs')

function jsonReader(filePath, cb) {
    fs.readFile(filePath, (err, fileData) => {
        if (err) {
            return cb && cb(err)
        }
        try {
            const object = JSON.parse(fileData)
            return cb && cb(null, object)
        } catch(err) {
            return cb && cb(err)
        }
    })
}

jsonReader('./customer.json', (err, customer) => {
    if (err) {
        console.log(err)
        return
    }
    console.log(customer.address) // => "Infinity Loop Drive"
})

Writing to a file with `fs.writeFile`

Writing JSON to the filesystem is similar to reading it. We will use fs.writeFile to asynchronously write data to a newCustomer.json file.
First, to write data to a JSON file, we must create a JSON string of the data with JSON.stringify. This returns a JSON string representation of a JavaScript object, which can be written to a file. Similar to parsing data into an object when reading a file, we must turn our data into a string to be able to write it to a file.

So we create a customer object with our data below, and turn it into a string.

const customer = {
    name: "Newbie Corp.",
    order_count: 0,
    address: "Po Box City",
}

const jsonString = JSON.stringify(customer)
console.log(jsonString) 
    // => "{"name":"Newbie Co.","address":"Po Box City","order_count":0}"

If you try to write an object to a file without stringifying it, your file will be empty and look like this:

[object, object]

Once the data is stringified, we can use fs.writeFile to create a new customer file.
We pass fs.writeFile the filepath, our customer data to write, and a callback that will be excecuted after the file is written. If the newCustomer.json file doesn't already exist, it will be created; if it does exist, it will be overwritten!

Here is an example of writing a JSON file with **fs.writeFile**:

const fs = require('fs')

const customer = {
    name: "Newbie Co.",
    order_count: 0,
    address: "Po Box City",
}

const jsonString = JSON.stringify(customer)

fs.writeFile('./newCustomer.json', jsonString, err => {
    if (err) {
        console.log('Error writing file', err)
    } else {
        console.log('Successfully wrote file')
    }
})

And that's it! Once the callback runs, the file has been written to disk. Note: we are only passed an error object; the filedata we wrote isn't passed to the callback.

We can also write a file synchronously in the same way using fs.writeFileSync:

const jsonString = JSON.stringify(customer)

fs.writeFileSync('./newCustomer.json', jsonString)

After your file is finished writing, it will look something like this:

{"name":"Newbie Co.","address":"Po Box City","order_count":0}

Stringifying by default puts your data all on a single line. Optionally, you can make the output file human-readable by passing the number of spaces to indent by to JSON.stringify:

const jsonString = JSON.stringify(customer, null, 2)

Above, we told stringify to indent the data with 2 spaces.

Now your output file should look like this:

{
    "name": "Newbie Co.",
    "address": "Po Box City",
    "order_count": 0
}

Updating JSON files
Now that we are able to read and write our customer files, we can use them as a simple kind of database. If we want to update the data in the JSON file, we can read the contents, change the data, and then write the new data back to the file:

jsonReader('./customer.json', (err, customer) => {
    if (err) {
        console.log('Error reading file:',err)
        return
    }

    // increase customer order count by 1
    customer.order_count += 1

    fs.writeFile('./customer.json', JSON.stringify(customer), (err) => {
        if (err) console.log('Error writing file:', err)
    })
})

Definitely not the most efficient database you could choose, but working with JSON files like this is a simple way to persist data in your project.

Wrapping up
JSON is one of the most common types of data you'll work with in Node, and being able to read and write JSON files is very useful. You've learned how to use fs.readFile and fs.writeFile to asynchronously work with the filesystem, as well as how to parse data to and from JSON format, and catch errors from JSON.parse.

You can use require to read a JSON file at startup to synchronously parse a JSON file in one line. And now you can use a simple JSON file as a data store.

If you want to learn more, you can read up on what JSON actually is, and find out more about synchronous vs asynchronous code.

Lullabot Education is ramping up our Node.js training. Sign up for our newsletter and learn about upcoming guides and tutorials — and help shape the future of Node.js education.

DEV Community: Joe Shindelar

Use Module.exports to Keep Node.js Code Organized

Use Module.exports to Keep Node.js Code Organized

Goal

What is module.exports?

What is require?

Creating a Helpers File

Passing arguments to a module

exports as shorthand for module.exports

Wrapping up

Read/Write JSON Files with Node.js

Read/Write JSON Files with NodeJS

Goal

Work with files with fs

Writing to a file with fs.writeFile

What is `require`?

`exports` as shorthand for `module.exports`

Work with files with `fs`

Writing to a file with `fs.writeFile`