10.1 The Module Concept

A module provides features (classes, functions, or other values) for programmers, called the exported features. Any features that are not exported are private to the module.

A module also specifies on which other modules it depends. When a module is needed, the JavaScript runtime loads it together with its dependent modules.

Modules manage name conflicts. Since the private features of a module are hidden from the public, it does not matter what they are called. They will never clash with any names outside the module. When you use a public feature, you can rename it so that it has a unique name.

It is important to understand that a module is different from a class. A class can have many instances, but a module doesn’t have instances. It is just a container for classes, functions, or values.

10.2 ECMAScript Modules

Consider a JavaScript developer who wants to make features available to other programmers. The developer places those features into a file. The programmers who use the features include the file in their project.

Now suppose a programmer includes such files from multiple developers. There is a good chance that some of those feature names will conflict with each other. More ominously, each file contains quite a few helper functions and variables whose names give rise to further conflicts.

Clearly, there needs to be some way of hiding implementation details. For many years, JavaScript developers have simulated modules through closures, placing helper functions and classes inside a wrapper function. This is similar to the “hard objects” technique from Chapter 3. They also developed ad-hoc ways of publishing exported features and dependencies.

Node.js implements a module system (called Common.js) that manages module dependencies. When a module is needed, it and its dependencies are loaded. That loading happens synchronously, as soon as the demand for a module occurs.

The AMD (Asynchronous Module Definition) standard defines a system for loading modules asynchronously, which is better suited for browser-based applications.

ECMAScript modules improve on both of these systems. They are parsed to quickly establish their dependencies and exports, without having to execute their bodies first. This allows asynchronous loading and circular dependencies. Nowadays, the JavaScript world is transitioning to the ECMAScript module system.

10.3 Default Imports

Only a few programmers write modules; many more programmers consume them. Let us therefore start with the most common activity: importing features from an existing module.

Most commonly, you import functions and classes. But you can also import objects, arrays, and primitive values.

A module implementor can tag one feature (presumably the most useful one) as the default. The import syntax makes it particularly easy to import the default feature. Consider this example where we import a class from a module that provides an encryption service:

Click here to view code image

import CaesarCipher from './modules/caesar.mjs'

This statement specifies the name that you choose to give to the default feature, followed by the file that contains the module implementation. For more details on specifying module locations, see Section 10.7, “Packaging Modules” (page 217).

The choice of the feature name in your program is entirely yours. If you prefer, you can give it a shorter name:

import CC from './modules/caesar.mjs'

If you work with modules that provide their services as a default feature, that is all you need to know about the ECMAScript module system.

10.4 Named Imports

A module can export named features in addition to, or instead of, the default. The module implementor gives a name to each nondefault feature. You can import as many of these named features as you like.

Here we import two functions that the module calls encrypt and decrypt:

Click here to view code image

import { encrypt, decrypt } from './modules/caesar.mjs'

Of course, there is a potential pitfall. What if you want to import encryption functions from two modules, and they both call it encrypt? Fortunately, you can rename the imported features:

Click here to view code image

import { encrypt as caesarEncrypt, decrypt as caesarDecrypt }
  from './modules/caesar.mjs'

In this way, you can always avoid name clashes.

If you want to import both the default feature and one or more named features, combine the two syntax elements:

Click here to view code image

import CaesarCipher, { encrypt, decrypt } from './modules/caesar.mjs'

or

Click here to view code image

import CaesarCipher, { encrypt as caesarEncrypt, decrypt as caesarDecrypt} . . .

import { encrypt } from './modules/caesar.mjs'

If a module exports many names, then it would be tedious to name each of them in the import statement. Instead, you can pour all exported features into an object:

Click here to view code image

import * as CaesarCipherTools from './modules/caesar.mjs'

You then use the imported functions as CaesarCipherTools.encrypt and CaesarCipherTools.decrypt. If there is a default feature, it is accessible as CaesarCipherTools.default. You can also name it:

Click here to view code image

import CaesarCipher, * as CaesarCipherTools . . .

You can use the import statement without importing anything:

import './app/init.mjs'

Then the statements in the file are executed but nothing is imported. This is not common.

10.5 Dynamic Imports

A stage 4 proposal allows you to import a module whose location is not fixed. Loading a module on demand can be useful to reduce the start-up cost and footprint of an application.

For dynamic import, use the import keyword as if it were a function with the module location as argument:

import(`./plugins/${action}.mjs`)

The dynamic import statement loads the module asynchronously. The statement yields a promise for an object containing all exported features. The promise is fulfilled when the module is loaded. You can then use its features:

Click here to view code image

import(`./plugins/${action}.mjs`)
  .then(module => {
    module.default()
    module.namedFeature(args)
    . . .
  })

Of course you can use the async/await notation:

Click here to view code image

async load(action) {
  const module = await import(`./plugins/${action}.mjs`)
  module.default()
  module.namedFeature(args)
  . . .
}

When you use a dynamic import, you do not import features by name, and there is no syntax for renaming features.

10.6 Exports

Now that you have seen how to import features from modules, let us switch to the module implementor’s perspective.

export function encrypt(str, key) { . . . }
export class Cipher { . . . }
export const DEFAULT_KEY = 3

function encrypt(str, key) { . . . }
class Cipher { . . . }
const DEFAULT_KEY = 3
. . .
export { encrypt, Cipher, DEFAULT_KEY }

export { encrypt as caesarEncrypt, Cipher, DEFAULT_KEY }

export default class Cipher { . . . }

export default 3 // OK
export default const DEFAULT_KEY = 3
  // Error—export default not valid with const/let/var

export default { encrypt, Cipher, DEFAULT_KEY }

export default (s, key) => { . . . } // No need to name this function

export default class { // No need to name this class
  encrypt(key) { . . . }
  decrypt(key) { . . . }
}

export { Cipher as default }

export const Level = { FINE: 1, INFO: 2, WARN: 3, ERROR: 4 }
export let currentLevel = Level.INFO
export const setLevel = level => { currentLevel = level }

import * as logging from './modules/logging.mjs'

logging.setLevel(logging.Level.WARN)

logging.currentLevel = logging.Level.WARN
  // Error—cannot assign to imported variable

export { randInt, randDouble } from './modules/random.mjs'

export { randInt as randomInteger } from './modules/random.mjs'

export { default } from './modules/stringutil.mjs'
export { default as StringUtil } from './modules/stringutil.mjs'

export { Random as default } from './modules/random.mjs'

export * from './modules/random.mjs'

10.7 Packaging Modules

Modules are different from plain “scripts”:

• The code inside a module always executes in strict mode.

• Each module has its own top-level scope that is distinct from the global scope of the JavaScript runtime.

• A module is only processed once even if it is loaded multiple times.

• A module is processed asynchronously.

• A module can contain import and export statements.

When the JavaScript runtime reads the module content, it must know that it is processing a module and not a plain script.

In a browser, you load a module with a script tag whose type attribute is module.

Click here to view code image

<script type="module" src="./modules/caesar.mjs"></script>

In Node.js, you can use the file extension .mjs to indicate that a file is a module. If you want to use a plain .js extension, you need to mark modules in the package.json configuration file. When invoking the node executable in interactive mode, use the command-line option --input-type=module.

It seems simplest to always use the .mjs extension for modules. All runtimes and build tools recognize that extension.

Exercises

1. Find a JavaScript library for statistical computation (such as https://github.com/simple-statistics/simple-statistics). Write a program that imports the library as an ECMAScript module and computes the mean and standard deviation of a data set.

2. Find a JavaScript library for encryption (such as https://github.com/brix/crypto-js). Write a program that imports the library as an ECMAScript module and encrypts a message, then decrypts it.

3. Implement a simple logging module that supports logging messages whose log level exceeds a given threshold. Export a log function, constants for the log level, and a function to set the threshold.

4. Repeat the preceding exercise, but export a single class as a default feature.

5. Implement a simple encryption module that uses the Caesar cipher (adding a constant to each code point). Use the logging module from one of the preceding exercises to log all calls to decrypt.

6. As an example of a circular dependency between modules, repeat the preceding exercise, but provide an option to encrypt the logs in the logging module.

7. Implement a simple module that provides random integers, arrays of random integers, and random strings. Use as many different forms of the export syntax as you can.

8. What is the difference between

   Click here to view code image

   import Cipher from './modules/caesar.mjs'

   and

   Click here to view code image

   import { Cipher } from './modules/caesar.mjs'

9. Explain the difference between

   Click here to view code image

   export { encrypt, Cipher, DEFAULT_KEY }

   and

   Click here to view code image

   export default { encrypt, Cipher, DEFAULT_KEY }

10. Which of the following are valid JavaScript?

    Click here to view code image

    export function default(s, key) { . . . }
    export default function (s, key) { . . . }
    export const default = (s, key) => { . . . }
    export default (s, key) => { . . . }

11. Trees have two kinds of nodes: those with children (parents) and those without (leaves). Let’s model that with inheritance:

    Click here to view code image

    class Node {
      static from(value, ...children) {
        return children.length === 0 ? new Leaf(value)
          : new Parent(value, children)
      }
    }
    
    class Parent extends Node {
      constructor(value, children) {
        super()
        this.value = value
        this.children = children
      }
      depth() {
        return 1 + Math.max(...this.children.map(c => c.depth()))
      }
    }
    
    class Leaf extends Node {
      constructor(value) {
        super()
        this.value = value
      }
      depth() {
        return 1
      }
    }

    Now a module-happy developer wants to put each class into a separate module. Do that and try it out with a demo program:

    Click here to view code image

    import { Node } from './node.mjs'
    
    const myTree = Node.from('Adam',
      Node.from('Cain', Node.from('Enoch')),
      Node.from('Abel'),
      Node.from('Seth', Node.from('Enos')))
    console.log(myTree.depth())

    What happens? Why?

12. Of course, the issue in the preceding exercise could have been easily avoided by not using inheritance, or by placing all classes into one module. In a larger system, those alternatives may not be feasible. In this exercise, keep each class in its own module and provide a façade module tree.mjs that reexports all three modules. In all modules, import from './tree.mjs', not the individual modules. Why does this solve the issue?