module

Modules: `node:module` API

Introduction

What are Modules?
- Modules are like building blocks in Node.js that allow you to separate your code into different files. This makes it easier to manage and reuse code, like putting different toys in different boxes.
- Each file can have its own module, and you can choose which toys (functions and variables) to share with other modules.

Loading Modules

require() Function:
- This function is used to load a module. It takes the file path (name) of the module as its argument. For example, you can load the 'math' module like this:

const math = require('math');

Exports

Exports Object:
- Each module has an 'exports' object. This object contains the parts of the module that you want to share with other modules.
- To add something to the exports object, you can assign it to the 'exports' property. For example, to export the 'add' function from the 'math' module, you would do:

exports.add = function(a, b) { return a + b; };

Modules as Caches

Module Caching:
- When you load a module, it is cached in memory. This means that the next time you load the same module, Node.js will use the cached version instead of loading it again.
- This improves performance, as it saves time and resources.

Real-World Applications

Organizing Code:
- You can use modules to organize your code into logical units, making it easier to find and manage.
Reusing Code:
- You can share code between multiple modules, reducing duplication and promoting maintainability.
Extending Node.js:
- You can create your own modules to extend the functionality of Node.js, adding additional features and capabilities.

Example: Calculator Module

calculator.js

// calculator.js: Calculator module
exports.add = function(a, b) { return a + b; };
exports.subtract = function(a, b) { return a - b; };
exports.multiply = function(a, b) { return a * b; };
exports.divide = function(a, b) { return a / b; };

main.js (Usage)

// main.js: Using the calculator module
const calc = require('./calculator');
console.log(calc.add(2, 3)); // 5
console.log(calc.subtract(5, 2)); // 3

Potential Application:
- Here, we create a calculator module with 'add', 'subtract', 'multiply', and 'divide' functions. This module can be reused in other applications that need basic arithmetic operations.

The Module Object

The Module object provides helpful methods for working with JavaScript modules.

Accessing the Module Object

You can access the Module object by importing or requiring it:

import module from 'node:module';

const module = require('node:module');

Methods of the Module Object

Here are some methods of the Module object:

module.createRequire(filename): Creates a function that can be used to require modules relative to the specified filename.
module.createRequireFromPath(path): Creates a function that can be used to require modules relative to the specified path.
module.syncBuiltinESMExports(name): Makes the builtin ESM exports of the specified module available to the current module.
module.isBuiltin(name): Checks if the specified name is a builtin module.
module.builtinModules: An array of all the builtin modules.

Real-World Applications

Dynamically loading modules: You can use the createRequire method to dynamically load modules based on user input or other factors.
Creating custom module loaders: You can use the createRequireFromPath method to create your own custom module loaders that can load modules from non-standard locations.
Accessing builtin ESM exports: You can use the syncBuiltinESMExports method to access the builtin ESM exports of other modules in your current module.

Potential Applications

Plugin systems: The Module object can be used to create plugin systems that allow users to extend or modify the functionality of a program.
Module bundlers: The Module object can be used to create module bundlers that combine multiple modules into a single file.
Sandbox environments: The Module object can be used to create sandbox environments where modules can be executed in isolation.

`module.builtinModules`

Simplified Explanation:

Imagine your computer is like a big toy box with many different toys (modules). Some toys come with the toy box (built-in modules), while others are added later by you (third-party modules).

module.builtinModules gives you a list of all the toys that came with the toy box (Node.js). This helps you know if a toy is special (built-in) or not (third-party).

In Code:

// List of built-in modules
const builtins = require("node:module").builtinModules;

// Check if a module is built-in
if (builtins.includes("fs")) {
  console.log("fs is a built-in module");
}

Real-World Applications:

Security: Verifying if a module is built-in can help you trust it more, as built-in modules are part of Node.js and have been thoroughly tested.
Customization: Knowing which modules are built-in allows you to customize your Node.js environment by adding third-party modules to extend its functionality.

`module.createRequire(filename)`

Simplified Explanation:

Imagine you have a big box called "your module". Inside the box, you have a bunch of stuff, like your code, some data, and even other boxes ("require"d modules).

module.createRequire(filename) is like having a secret door in your module. It lets you peek into other boxes and see what's inside them. For example, if you have a secret door to the "sibling-module" box, you can use it to access the stuff inside that box, even though it's a different box.

Detailed Explanation:

Purpose:

module.createRequire(filename) creates a require function that can be used to load external modules by providing a filename or URL. This function has the same behavior as the built-in require function, but it allows you to specify a specific filename or URL from which to load the module.

Parameters:

filename: Specifies the filename or URL of the module to load.

Return Value:

require: Returns a require function that can be used to load modules from the specified filename or URL.

Real-World Example:

Suppose you have a module named main.mjs that needs to load a sibling module named sibling.mjs. You can use module.createRequire() to create a require function that loads modules from the same directory as main.mjs.

// main.mjs

import { createRequire } from "node:module";
const require = createRequire(import.meta.url);

// Load the sibling module.
const siblingModule = require("./sibling.mjs");

In this example, createRequire(import.meta.url) creates a require function that loads modules from the same directory as main.mjs. This allows main.mjs to easily load and use the sibling.mjs module.

Potential Applications:

Loading modules from specific locations: You can use module.createRequire() to load modules from specific locations, such as a local file system or a remote server.
Creating encapsulated modules: By using module.createRequire(), you can create modules that are encapsulated and isolated from other parts of your codebase.

Module.isBuiltin

Simplified Explanation:

Imagine that Node.js is a big store with different aisles for different types of modules. Some aisles are for special modules that are built into Node.js, like the fs aisle for working with files. Other aisles are for custom modules that you can install on your own.

The module.isBuiltin function helps you check if a module is from the special aisles (built-in modules) or the custom aisles (installed modules).

Code Snippet:

import { isBuiltin } from "node:module";

// Check if the `fs` module is built-in
isBuiltin("fs"); // true

Real-World Example:

You want to create a script that reads data from a file. You can use the fs module, which is a built-in module, to do this. isBuiltin helps you confirm that fs is available.

import { isBuiltin } from "node:module";
import { readFile } from "fs";

// Check if the `fs` module is built-in
isBuiltin("fs"); // true

readFile("data.txt", "utf8", (err, data) => {
  if (err) throw err;
  console.log(data);
});

Module Registration in Node.js

Node.js allows you to create customized modules that can change how other modules are found and loaded. You can register such modules using the module.register() function.

Parameters:

specifier: The name or path of the module you want to register.
parentURL (optional): The URL of the parent module that is registering the new module.
options (optional): Additional options for the registration, including:
- parentURL: Same as the second parameter.
- data: Any value you want to pass to the new module's initialize() hook.
- transferList: A list of objects that can be transferred to the new module's initialize() hook.

How it Works:

When you register a module, you are telling Node.js that this module contains special hooks that can customize the loading process. These hooks can do things like:

Find modules in different locations
Load modules in a different order
Modify the contents of modules before loading them

Real-World Applications:

There are many potential applications for module registration in Node.js. For example, you could use it to:

Create a module that loads modules from a custom file system
Create a module that logs all module loading events
Create a module that intercepts and modifies requests for HTTP modules

Complete Code Example:

// Register a module that logs module loading events
module.register("my-logger", function initialize(data) {
  console.log("Loading module:", data.path);
});

// Import the module (this will trigger the 'initialize' hook)
import("my-logger");

Potential Applications:

Debugging: You could use a module registration hook to log module loading events and help identify performance issues.
Security: You could use a hook to intercept and modify requests for external modules, preventing the loading of malicious code.
Customization: You could use hooks to create custom module loading strategies, such as loading modules from a CDN or a remote server.

`module.syncBuiltinESMExports()`

Simplified Explanation:

Imagine you have two boxes filled with items. One box is labeled "ES Modules" and the other is labeled "CommonJS." The "ES Modules" box contains the latest versions of items. The "CommonJS" box contains older versions of the same items.

The module.syncBuiltinESMExports() method makes sure that the items in the "ES Modules" box match the items in the "CommonJS" box. It does this by updating the "ES Modules" box with the latest versions of the items. However, it does not remove or add any items from either box.

Code Snippet:

const fs = require("node:fs");
const { syncBuiltinESMExports } = require("node:module");

fs.readFile = newAPI; // Update the readFile property with a new function

syncBuiltinESMExports(); // Sync the ES Module exports with the CommonJS exports

import { readFile } from "node:fs"; // Import the ES Module

// The readFile property now points to the newAPI function
console.log(readFile === newAPI); // true

Real-World Application:

Suppose you have a Node.js application that uses both ES Modules and CommonJS modules. You want to ensure that all the modules use the latest versions of the built-in functions. You can use the module.syncBuiltinESMExports() method to automatically update the ES Module exports with the latest versions.

Potential Applications:

Updating legacy applications: You can use module.syncBuiltinESMExports() to update older Node.js applications to use the latest versions of built-in functions.
Synchronizing ES Modules and CommonJS modules: You can use module.syncBuiltinESMExports() to ensure that the exports from ES Modules and CommonJS modules match, making it easier to mix and match modules in your applications.

Customization Hooks

Customization hooks allow you to modify certain aspects of the module loading process.

Resolve hook: Used to change how modules are resolved. For example, you could use it to load a different version of a module or to load a module from a different location.
Load hook: Used to change how modules are loaded. For example, you could use it to load a module using a different loader or to load a module dynamically.
Transform hook: Used to change the source code of a module before it is executed. For example, you could use it to add type checking or to transform code from one language to another.

Real-World Applications

Here are some real-world applications of customization hooks:

Resolve hook: Webpack uses a resolve hook to load modules from different directories depending on the environment. For example, it can load modules from node_modules in development mode and from a CDN in production mode.
Load hook: Babel uses a load hook to transform code from ES6 to ES5 before it is executed. This allows you to use modern JavaScript features in browsers that do not support them.

Code Examples

Here are some code examples that demonstrate how to use customization hooks:

// Resolve hook
module.exports = function (request, options) {
  // Change the request to load a different version of the module
  request = request.replace(/@1.0.0/, "@2.0.0");

  // Return the modified request
  return request;
};

// Load hook
module.exports = function (source, filename, options) {
  // Change the source code to add type checking
  source = source.replace("const foo = ", "const foo: string = ");

  // Return the modified source code
  return source;
};

// Transform hook
module.exports = function (source, filename, options) {
  // Transform the code from ES6 to ES5
  const transformedSource = babel.transform(source, options).code;

  // Return the transformed source code
  return transformedSource;
};

Enabling Module Hooks:

Imagine you have a bookshelf filled with books. You want to add some special features to the bookshelf, like sorting books by color or adding a secret compartment. To do this, you need to create a set of rules, or "hooks," that the bookshelf follows when it loads new books.

In Node.js, you can create these hooks using the register() method from the module module. You can think of register() as a command that says, "Hey bookshelf, use these special rules to load books."

To use register(), you need to write a JavaScript file that contains your hooks. This file can be named anything you want, but it's common to call it "hooks.mjs" or "hooks.js."

Here's an example of a simple hooks file:

// hooks.mjs
export function resolve(specifier, parentURL) {
  // This hook will be called whenever the bookshelf tries to load a book.
  // It can decide where to find the book, like on your local computer or on a website.
  console.log("Resolving", specifier, "from", parentURL);
}

export function load(url) {
  // This hook will be called when the bookshelf wants to actually read a book.
  // It can read the book from the file system or from a network connection.
  console.log("Loading", url);
}

Once you have your hooks file, you can tell Node.js to use it by passing the --import flag when you run your program. This flag tells Node.js to execute your hooks before it starts loading your main program.

node --import ./hooks.mjs ./my-app.js

Real-World Applications:

Module hooks can be used to customize how Node.js loads modules in a variety of ways. Here are a few examples:

HTTP to HTTPS: You can use hooks to redirect all HTTP requests to HTTPS, which is a more secure protocol.
Caching: You can use hooks to cache frequently used modules in memory, which can speed up your program.
Code Transpilation: You can use hooks to convert code written in a new language to JavaScript that Node.js can understand.

Complete Code Implementations:

Here's a complete example of how to use module hooks to implement the HTTP to HTTPS redirect:

// hooks.mjs
export function resolve(specifier, parentURL) {
  if (specifier.startsWith("http://")) {
    return `https://${specifier.slice(7)}`;
  }
  return specifier;
}

node --import ./hooks.mjs ./my-app.js

Potential Applications:

Module hooks can be used in a wide variety of applications, including:

Security: You can use hooks to protect your program from malicious code.
Performance: You can use hooks to improve the performance of your program.
Extensibility: You can use hooks to extend the functionality of Node.js in new and innovative ways.

Chaining Hooks

Imagine you have a toy train set with different wagons. You can connect the wagons together to form a train. In Node.js, you can do something similar with something called "module hooks."

Module hooks are like add-ons that can customize how Node.js finds and loads code. You can "register" hooks by telling Node.js about them using the register function.

How Chaining Works

When you register multiple hooks, they form a "chain." Just like wagons in a train, each hook is called in the order it was registered.

For example, let's say you have two wagons called "Red" and "Blue." If you connect Red to the train first, then connect Blue, the train will look like this:

- Red Wagon
- Blue Wagon
- Engine

When you tell the train to move, the Red Wagon will move first, followed by the Blue Wagon, and finally the engine.

In Node.js, it's the same thing with module hooks. If you register a hook called "Red Hook" first, then register a hook called "Blue Hook," the hooks will be called in this order:

- Red Hook
- Blue Hook
- Module Loading

Real-World Example

Imagine you have a Node.js app that needs some special logic when loading modules. You could write a custom module hook that does this.

To use your hook, you would register it first:

register('./my-custom-hook.mjs', import.meta.url);

Then, when your app loads other modules, the my-custom-hook.mjs hook would run before the other modules are loaded. This gives you a chance to modify how the modules are loaded or found.

Potential Applications

Transpiling non-JavaScript languages: You could write a hook that transpiles code from TypeScript or CoffeeScript into JavaScript before loading it.
Caching modules: You could write a hook that caches modules so they don't have to be loaded every time.
Enhancing security: You could write a hook that checks for potential security issues in the code before loading it.

Simplified Explanation:

Imagine you have a computer with two people inside: one is you (the main thread), and the other is a helper (the hook thread).

The helper thread runs in a separate room and can't see what you're doing. But you can communicate with the helper by sending messages through a special channel.

Topic 1: Registering Hooks

When you want to use the helper thread, you tell it what to do by "registering" it. You can give the helper some information, like a number or a channel to use for communication.

Code Example:

const { port1, port2 } = new MessageChannel(); // Create a channel for sending messages

register("./my-hooks.mjs", {
  data: { number: 1, port: port2 }, // Information to send to the helper
  transferList: [port2], // The channel to use for communication
});

Topic 2: Communicating with Hooks

Once you've registered the helper, you can send messages to it through the channel. The helper will listen for these messages and respond appropriately.

Code Example:

// In the main thread
port1.on("message", (msg) => {
  // Listen for messages from the helper
  console.log(msg); // Print the message
});

// In the helper thread
port2.postMessage({ hello: "world" }); // Send a message back to the main thread

Potential Applications:

Background tasks: You can use hooks to perform tasks in the background while your main program continues running.
Data processing: You can use hooks to process large amounts of data in parallel, speeding up your application.
Error handling: You can use hooks to handle errors and exceptions separately from your main program, ensuring stability.

Hooks

Imagine your code as a car driving through a highway. Hooks are like toll booths that the car passes through along the way. Each toll booth (hook) can check the car's information (code) and decide what to do next.

Register a toll booth (hook)

You can build your own toll booth (hook) by creating a code file that exports three special functions:

initialize: This function is like the welcome sign at the toll booth. It gets called first and can give you some information about the car (code).
resolve: This function is like the main inspector at the toll booth. It takes the car's destination (import specifier) and tries to figure out where the car should go next (URL).
load: This function is like the final guard at the toll booth. It takes the car's destination URL and loads the car's cargo (source code).

Here's an example of a code file that exports these functions:

export async function initialize({ number, port }) {
  // Do something with the car's information (e.g., check if it's a sports car)
}

export async function resolve(specifier, context, nextResolve) {
  // Find out where the car should go next (e.g., highway 101)
  const url = await nextResolve(specifier, context);
  return url;
}

export async function load(url, context, nextLoad) {
  // Load the car's cargo (e.g., music)
  const sourceCode = await nextLoad(url, context);
  return sourceCode;
}

Potential applications in real world

Hooks can be useful for:

Changing how Node.js resolves and loads modules, e.g., using a custom module resolver to find modules in a specific directory.
Loading modules from different sources, e.g., loading a module from a remote server or from a CDN.
Modifying the source code of modules before they are loaded, e.g., to optimize the code or to add additional functionality.

`initialize()` Hook

What is it?

The initialize() hook is a special function that runs when the module containing it is loaded. It allows you to perform custom actions when this happens.

How does it work?

When a module is loaded, the JavaScript engine searches for a function named initialize() in the module. If it finds one, it runs that function before executing the rest of the module's code.

What can I do with it?

You can use the initialize() hook to:

Initialize any variables or data structures that your module needs
Perform setup tasks that should happen before the module is used
Send messages to other threads or processes
Anything else you can do in a JavaScript function!

Code Example

Here's an example of how to use the initialize() hook:

// my-module.js

export async function initialize() {
  console.log("My module is initializing!");
}

When you load this module, you'll see the following message in the console:

My module is initializing!

Real-World Applications

The initialize() hook can be used for a variety of purposes, such as:

Preloading data from a database or API
Setting up event listeners or timers
Establishing connections to other services
Anything else that needs to be done before your module can be used

Potential Use Cases

In a web application, you could use the initialize() hook to preload the page's data from a server. This would improve the user experience by reducing the amount of time it takes for the page to load.
In a command-line tool, you could use the initialize() hook to set up command-line arguments and options. This would make it easier for users to use your tool.
In a library or framework, you could use the initialize() hook to perform any necessary setup tasks. This would make it easier for developers to use your library or framework.

`resolve(specifier, context, nextResolve)`

Imagine you're in a library and you want to find a particular book. The library has a system of shelves, and each shelf has a specific type of book, like children's books, history books, etc.

To find the book you want, you first need to know which shelf to look on. The resolve function is like the librarian who helps you figure out which shelf to look on.

The specifier is the name of the book you're looking for. The context tells the resolve function some extra information, like which section of the library you're in or if you're looking for a specific book series. The nextResolve function is like the next librarian you go to if the first one can't find your book.

The resolve function returns information about where to find the book, including:

The format of the book (like a physical book or an ebook)
The importAttributes (like the book's author or ISBN number)
The url of the book (where to find it on the shelf)

Here's an example:

const book = 'The Very Hungry Caterpillar';
const section = 'Children's Books';

const resolvedBook = resolve(book, { section });

console.log(resolvedBook);
// {
//   format: 'book',
//   importAttributes: { author: 'Eric Carle' },
//   url: 'https://www.amazon.com/Very-Hungry-Caterpillar/dp/0399226950'
// }

In this example, the resolve function found the book on the Children's Books shelf, with the author Eric Carle. It also returned the URL where you can buy the book online.

Real-world applications

The resolve function is used by Node.js to find and load modules when you import them. For example, if you have a module called my-module in your Node.js project, the resolve function will be used to find the file where that module is located.

Another application of the resolve function is creating custom module loaders. For example, you could create a module loader that loads modules from a remote server or from a different file system.

`load(url, context, nextLoad)`

The load hook lets you control how a URL is interpreted, fetched, and parsed. It's like a custom tool for loading different types of files.

Here's how it works:

url: The address of the file you want to load, like "https://example.com/myfile.js" or "file:///home/user/myfile.js".
context: Some information about the file you're loading, like what type of file it is (e.g., CommonJS, JSON, etc.).
nextLoad: The next load hook in the chain. If there are no more hooks, this will be the Node.js default load hook.

What can you do with the `load` hook?

Define custom loading methods: You can create your own rules for how to fetch and parse different types of files.
Validate import assertions: Make sure the file you're loading matches the import assertion specified in the import statement.
Map unrecognized formats to supported ones: Turn files in strange formats into something the Node.js loader understands.

How do I use the `load` hook?

export async function load(url, context, nextLoad) {
  // Your custom loading logic goes here

  // Return an object with these properties:
  return {
    format: "", // Type of file (e.g., 'commonjs', 'json', etc.)
    source: "", // Contents of the file
  };
}

Real-world examples

Example 1: Loading a file from a custom location

Imagine you have a special server that stores your files. You can create a load hook to load files from that server:

export async function load(url, context, nextLoad) {
  if (url.startsWith("https://my-special-server.com/")) {
    // Fetch the file from your custom server
    const response = await fetch(url);
    const source = await response.text();

    return {
      format: "commonjs",
      source: source,
    };
  }

  // If the URL doesn't start with your custom server address, pass it to the next `load` hook
  return nextLoad(url, context);
}

Example 2: Transforming an unsupported format to a supported one

Suppose you want to load a YAML file, but the Node.js loader doesn't support YAML. You can write a load hook to convert YAML to JSON:

import yaml from "yaml";

export async function load(url, context, nextLoad) {
  if (context.format === "yaml") {
    // Fetch the YAML file
    const response = await fetch(url);
    const yamlSource = await response.text();

    // Convert the YAML to JSON
    const jsonSource = yaml.parse(yamlSource);

    return {
      format: "json",
      source: jsonSource,
    };
  }

  // If the file is not in YAML format, pass it to the next `load` hook
  return nextLoad(url, context);
}

Module Customization Hooks

Imagine your computer as a big playground with lots of different toys (modules) that you can play with. Modules are like building blocks that help you build different apps or games.

Sometimes, you might want to change how some of these toys (modules) work to make your game more fun. This is where module customization hooks come in. They're like special buttons that you can press to make some changes.

Types of Customization Hooks

There are different types of customization hooks:

loader: This hook lets you change how modules are loaded into your playground (computer).
require: This hook lets you change how modules are called and used in your game.
wrap: This hook lets you wrap or cover modules with a special layer, like a magic blanket.

How to Use Customization Hooks

Using customization hooks is like following a recipe. Here's a simplified recipe for using the loader hook:

1. Import the 'module' module.
2. Create a new loader function.
3. Tell the module module to use your new loader function.
4. Enjoy your customized module loading experience!

Real-World Applications

Customization hooks can be used for a variety of purposes:

Lazy loading: Load modules only when they're needed, making your game faster.
Security: Wrap modules in a special layer to protect your game from bad guys.
Caching: Store frequently used modules in a special box to make your game run smoother.

Example: Lazy Loading

Imagine you're building a game where players can choose different characters. You don't want to load all the character modules at once, because that would make your game too slow. Instead, you can use the loader hook to load the character modules only when the player chooses a character. Here's how:

// Create a new loader function
const myLoader = (modulePath) => {
  // Load the module only when it's needed
  if (!moduleCache[modulePath]) {
    moduleCache[modulePath] = require(modulePath);
  }
  return moduleCache[modulePath];
};

// Tell the module module to use your new loader function
module.loader = myLoader;

Potential Applications

Games: Optimize performance by lazy loading game assets.
Security: Protect your app from malicious code by wrapping modules in a sandbox.
Development tools: Enhance debugging capabilities by customizing module evaluation.

Importing Modules from HTTPS URLs

What is Node.js?

Imagine Node.js as a super-fast robot that can understand and run JavaScript code. It's like a special helper that makes it easy to build websites, games, and other cool things.

Import from HTTPS URLs

Node.js can usually only import modules that are stored on your computer. But with a special trick, we can tell Node.js to import modules from the internet using HTTPS URLs.

HTTPS-Hooks Module

Think of the HTTPS-Hooks module as a secret code that unlocks the ability to import modules from the internet. It's like a special key that opens a door.

Real-World Example

Let's say you want to use a special library called "CoffeeScript" in your Node.js program. You can use the HTTPS-Hooks module to import it from the internet:

// main.js
import { VERSION } from "https://coffeescript.org/browser-compiler-modern/coffeescript.js";

console.log(VERSION);

When you run this script, it will print the current version of CoffeeScript.

Potential Applications

Importing modules from HTTPS URLs is useful when you want to use libraries that are not available on your computer or that are constantly updated. For example, you could import the latest version of a popular game engine or a data analysis library.

Limitations

Be aware that importing modules from HTTPS URLs is slower than importing them from your computer. Also, the module will be loaded each time you run your script, instead of being saved in cache.

Transpilation

In programming, sometimes you have code written in a different language that you need to run in a different language. For example, you might have some code written in CoffeeScript that you want to run in JavaScript.

Transpiling is the process of converting code from one language to another.

Node.js is a runtime environment for JavaScript that you can use to run JavaScript code on your computer.

Load hooks are a way to tell Node.js how to load certain types of files.

The load hook is used to tell Node.js how to load files with .coffee, .litcoffee, or .coffee.md extensions.

Example

Here's an example of a load hook that can be used to transpile CoffeeScript code into JavaScript:

// coffeescript-hooks.mjs
import { readFile } from "node:fs/promises";
import { dirname, extname, resolve as resolvePath } from "node:path";
import { cwd } from "node:process";
import { fileURLToPath, pathToFileURL } from "node:url";
import coffeescript from "coffeescript";

const extensionsRegex = /\.(coffee|litcoffee|coffee\.md)$/;

export async function load(url, context, nextLoad) {
  if (extensionsRegex.test(url)) {
    // CoffeeScript files can be either CommonJS or ES modules, so we want any
    // CoffeeScript file to be treated by Node.js the same as a .js file at the
    // same location. To determine how Node.js would interpret an arbitrary .js
    // file, search up the file system for the nearest parent package.json file
    // and read its "type" field.
    const format = await getPackageType(url);

    const { source: rawSource } = await nextLoad(url, { ...context, format });
    // This hook converts CoffeeScript source code into JavaScript source code
    // for all imported CoffeeScript files.
    const transformedSource = coffeescript.compile(rawSource.toString(), url);

    return {
      format,
      shortCircuit: true,
      source: transformedSource,
    };
  }

  // Let Node.js handle all other URLs.
  return nextLoad(url);
}

async function getPackageType(url) {
  // `url` is only a file path during the first iteration when passed the
  // resolved url from the load() hook
  // an actual file path from load() will contain a file extension as it's
  // required by the spec
  // this simple truthy check for whether `url` contains a file extension will
  // work for most projects but does not cover some edge-cases (such as
  // extensionless files or a url ending in a trailing space)
  const isFilePath = !!extname(url);
  // If it is a file path, get the directory it's in
  const dir = isFilePath ? dirname(fileURLToPath(url)) : url;
  // Compose a file path to a package.json in the same directory,
  // which may or may not exist
  const packagePath = resolvePath(dir, "package.json");
  // Try to read the possibly nonexistent package.json
  const type = await readFile(packagePath, { encoding: "utf8" })
    .then((filestring) => JSON.parse(filestring).type)
    .catch((err) => {
      if (err?.code !== "ENOENT") console.error(err);
    });
  // If package.json existed and contained a `type` field with a value, voilà
  if (type) return type;
  // Otherwise, (if not at the root) continue checking the next directory up
  // If at the root, stop and return false
  return dir.length > 1 && getPackageType(resolvePath(dir, ".."));
}

This load hook will tell Node.js to transpile all CoffeeScript files into JavaScript before executing them.

Potential applications

Transpilation can be useful in a number of scenarios, such as:

Running code written in a different language. If you have some code written in a different language that you want to run in Node.js, you can use a transpiler to convert it to JavaScript.
Using a different language for development. If you prefer to write your code in a different language but still want to run it in Node.js, you can use a transpiler to convert it to JavaScript.
Using a different language for production. If you want to use a different language for production but still want to be able to develop your code in Node.js, you can use a transpiler to convert it to JavaScript.

Import Maps

Explanation:

Import Maps are like a "map" that tells your JavaScript engine where to find specific modules instead of using their default paths. It's like a special dictionary that says, "When you see this module, go to this other location instead."

Simplified Example:

Imagine you have a toy car called "blue-car" and you want to play with it in your room. But your car is actually in the garage. Instead of going all the way to the garage, you could create an "import map" that says, "When you want to play with blue-car, look for it in the closet." Now, when you want to play with your car, you can just go to the closet and find it there, even though it's really in the garage.

Code Snippet:

{
  "imports": {
    "blue-car": "./closet/blue-car.js"
  }
}

Real-World Applications:

Code sharing: You can share a module with multiple projects by using an import map to point to the shared module.
Module versioning: You can use an import map to specify different versions of a module for different projects.
Experimentation: You can use an import map to experiment with different versions of a module without affecting your production code.

Resolve Hooks

Explanation:

Resolve hooks are like detectives that help your JavaScript engine find modules. They follow clues and search different locations to find the module you're looking for. If they can't find the module in the default location, they can use the import map to look for alternative locations.

Simplified Example:

Imagine you're looking for a missing sock. You usually look under the bed, but it's not there. You could create a "resolve hook" that says, "If you can't find the sock under the bed, check the laundry basket." The resolve hook would then search the laundry basket and tell you if the sock is there.

Code Snippet:

export async function resolve(specifier, context, nextResolve) {
  if (importMap.has(specifier)) {
    return nextResolve(importMap[specifier], context);
  }

  return nextResolve(specifier, context);
}

Real-World Applications:

Custom module loading: You can create your own resolve hooks to load modules from custom locations or using custom algorithms.
Module overrides: You can use resolve hooks to override the default loading behavior for specific modules.
Performance optimizations: You can use resolve hooks to optimize the module loading process by caching frequently used modules.

Complete Code Implementation

// import-map-hooks.js
import fs from "node:fs/promises";

const { imports } = JSON.parse(await fs.readFile("import-map.json"));

export async function resolve(specifier, context, nextResolve) {
  if (Object.hasOwn(imports, specifier)) {
    return nextResolve(imports[specifier], context);
  }

  return nextResolve(specifier, context);
}

// main.js
import "a-module";

// import-map.json
{
  "imports": {
    "a-module": "./some-module.js"
  }
}

// some-module.js
console.log("some module!");

Running the following command should print "some module!":

node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./import-map-hooks.js"));' main.js

Source Maps

Source maps are a way to connect the original source code of a file to the compiled code that is run by the browser or server.

Source Map Parsing

When you run Node.js with the --enable-source-maps flag, or with code coverage enabled, Node.js will parse source maps. This means that it will look for special comments in the file that contain the mapping information and store it in a cache.

Source Map Cache

The source map cache is a collection of all the source maps that have been parsed by Node.js. You can use the findSourceMap() function to search the cache for a source map that matches a given path.

Using Source Maps

Once you have found a source map, you can use it to get the original source code for a given line of the compiled code. This can be useful for debugging or for displaying the original source code to users.

Real-World Applications

Source maps are used in a variety of real-world applications, including:

Debugging: Source maps can be used to debug compiled code by allowing you to see the original source code that generated the error.
Code Coverage: Source maps are used to generate code coverage reports that show which lines of the original source code have been executed.
Development: Source maps can be used to develop and test code in a modular fashion, by allowing you to see the original source code of individual modules.

Code Snippets

Here is a code snippet that shows how to use the findSourceMap() function to search the source map cache:

const { findSourceMap } = require("node:module");

const sourceMap = findSourceMap("/path/to/module.js");

If the source map is found, it will be stored in the sourceMap variable. You can then use the sourceMap object to get the original source code for a given line of the compiled code.

Here is a code snippet that shows how to get the original source code for a given line of the compiled code:

const { findSourceMap } = require("node:module");

const sourceMap = findSourceMap("/path/to/module.js");
const originalSourceCode = sourceMap.getOriginalSource("compiledCode.js", 10);

If the original source code is found, it will be stored in the originalSourceCode variable.

`module.findSourceMap(path)`

Purpose: Given a path to a JavaScript file, this method tries to find the corresponding source map.

Parameters:

path: The resolved path to the JavaScript file.

Return Value:

Returns a module.SourceMap object if a source map is found for the given path, otherwise it returns undefined.

How it Works:

When you write JavaScript code, it gets compiled into a smaller, faster version that can be run by browsers and other JavaScript engines. This compiled version is what you see in your JavaScript files. However, the compiled code is not human-readable, and it can be difficult to debug.

A source map is a file that maps the compiled code back to the original human-readable code. This makes it easier to debug JavaScript code and identify the original source of errors.

The module.findSourceMap() method looks for a source map file with the same name as the JavaScript file, but with the extension .map. For example, if your JavaScript file is called main.js, the source map file will be called main.js.map.

Real-World Example:

Let's say you have a JavaScript file called script.js. You want to use the module.findSourceMap() method to find the corresponding source map file. Here's how you would do it:

const fs = require("fs");
const path = require("path");

// Get the resolved path to the JavaScript file
const scriptPath = path.resolve("script.js");

// Use the module.findSourceMap() method to find the source map file
const sourceMap = module.findSourceMap(scriptPath);

// If the source map was found, read its content
if (sourceMap) {
  const sourceMapContent = fs.readFileSync(sourceMap.path, "utf8");
  // Parse the source map content and use it for debugging
}

This example assumes that the source map file is in the same directory as the JavaScript file. If the source map file is in a different location, you can specify its path in the module.findSourceMap() method.

Potential Applications:

Source maps are useful for debugging JavaScript code in development and production environments. They can also be used to improve the performance of JavaScript code by identifying and fixing bottlenecks.

SourceMap class

The SourceMap class represents a source map, which is a JSON-based format that maps a transformed file back to its original source file. This is useful for debugging and development, as it allows you to see the original source code for a transformed file, even if the source code is not available separately.

Constructor

The SourceMap class constructor takes a single argument, which is a JSON-formatted string representing the source map. The JSON string must be valid, and it must conform to the Source Map specification.

const sourceMap = new SourceMap(
  '{"version": 3, "sources": ["foo.js"], "names": ["a", "b"], "mappings": "AAAA,IAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}'
);

Methods

The SourceMap class has the following methods:

get() - Returns the source code for the specified file and line number.
getLineNumber() - Retuns the line number in the original source code for the specified line number in the transformed file.
getColumnNumber() - Returns the column number in the original source code for the specified column number in the transformed file.
getName() - Returns the name of the function or variable at the specified line and column number in the original source code.
getMappings() - Returns an array of mappings representing the relationship between the transformed file and the original source code.

Properties

The SourceMap class has the following properties:

version - The version of the Source Map specification that the source map conforms to.
sources - An array of strings representing the names of the original source files.
names - An array of strings representing the names of the functions and variables in the original source code.
mappings - An array of mappings representing the relationship between the transformed file and the original source code.

Real-world applications

Source maps are used in a variety of real-world applications, including:

Debugging: Source maps can be used to help debug transformed code by providing a way to view the original source code.
Development: Source maps can be used to help develop transformed code by providing a way to see the relationship between the transformed code and the original source code.
Testing: Source maps can be used to help test transformed code by providing a way to verify that the transformed code produces the same output as the original source code.

Simplified Explanation:

Create a Source Map

Imagine you have a program called "myprogram.js" and it's made up of two other files, "file1.js" and "file2.js." When you combine them and run "myprogram.js," a "source map" is created. This map shows how the combined code relates back to the original files.

What is a Source Map?

A source map is like a roadmap for your program. It helps you see how the original files were combined to create the final program. This is useful for debugging, where you want to pinpoint the exact part of the original files that caused a problem.

Creating a Source Map

To create a source map, you need to provide information about the original files, like their names and the content they contain. You can also include information about the names of variables and functions in your program.

Real-World Applications

Source maps are used in many applications, including:

Web development: When you use tools like Babel to convert modern JavaScript code to older versions, source maps help you debug the original code.
Mobile development: Source maps help you debug code written for React Native or other mobile frameworks.
Optimization: Source maps help you see how code optimization techniques have affected the original code.

Code Snippet:

// Example of creating a source map
const sourceMap = new SourceMap({
  file: "myprogram.js",
  version: 3,
  sources: ["file1.js", "file2.js"],
  sourcesContent: ["// Contents of file1.js", "// Contents of file2.js"],
  names: ["variable1", "function1"],
  mappings: "// Mapping information",
  sourceRoot: "path/to/original/files",
});

Getter: sourceMap.payload

Meaning:

The sourceMap.payload getter in Node.js allows you to access the data that was originally used to create the SourceMap object. This data typically contains information about the source code, its transformations, and the mapping between the transformed and original source.

Example:

const sourceMap = new SourceMap({
  file: "myfile.js",
  sources: ["src/main.js"],
  mappings: "AAAA,IAAM,CAAC,GAAkB,CAAC,CAAC,CAAC,CAAC",
});

const payload = sourceMap.payload;

console.log(payload.file); // myfile.js
console.log(payload.sources); // ['src/main.js']
console.log(payload.mappings); // 'AAAA,IAAM,CAAC,GAAkB,CAAC,CAAC,CAAC,CAAC'

Real-World Applications:

Source maps are often used in development and debugging scenarios. By having access to the source map payload, developers can:

Trace back errors to the original source code: If an error occurs in the transformed code, the source map can be used to pinpoint the exact location in the original source code where the issue originates.
Inspect code coverage: Source map payload can provide information about which parts of the source code have been executed during testing.
Manage code dependencies: The source map payload can contain information about the dependencies of the transformed code, making it easier to manage and update those dependencies.

Simplified explanation:

A SourceMap is like a bridge between your code as it appears in the browser (the "generated" code) and the original code you wrote (the "original" code). It helps map errors in the generated code back to their original locations in the original code, so you can debug your code more easily.

The findEntry method lets you find the range of code in the original file that corresponds to a specific line and column in the generated file. It's like looking up an address in a phone book.

Usage:

const sourceMap = new SourceMap();
const entry = sourceMap.findEntry(lineNumber, columnNumber);

Example:

Let's say your generated code has this error:

Error: Something went wrong at line 10, column 5

And your SourceMap looks like this:

{
  "version": 3,
  "sources": ["original.js"],
  "names": [],
  "mappings": "AAAA"
}

You can use findEntry to find the corresponding range in the original file:

const entry = sourceMap.findEntry(10, 5);

The entry will look something like this:

{
  generatedLine: 10,
  generatedColumn: 5,
  originalSource: "original.js",
  originalLine: 4,
  originalColumn: 12
}

This means that the error actually occurred at line 4, column 12 in the original file.

Real-world application:

SourceMaps are essential for debugging in development environments. They make it much easier to track down the root cause of errors and fix them quickly.

Other notes:

findEntry returns an empty object if no corresponding range is found in the SourceMap.
The line and column numbers used in SourceMaps are 0-indexed, not 1-indexed like in most text editors. This is important to keep in mind when working with SourceMaps.

Finding Source Code Locations from Generated Code using Source Maps

Introduction

When you write code, it's often converted into a smaller, faster version called the "generated code." Unfortunately, this generated code can make it difficult to track down where errors occur in your original code. That's where source maps come in.

What are Source Maps?

Source maps are like a bridge between your original code and the generated code. They contain information that allows you to map locations in the generated code back to the corresponding locations in your original code.

Finding Source Code Locations with sourceMap.findOrigin()

The sourceMap.findOrigin() method helps you locate the original code corresponding to a specific line and column in the generated code. Here's a simplified example:

// Generated code
const generatedLine = 10;
const generatedColumn = 20;

// Source map
const sourceMap = {...}; // Suppose this contains the source map information

// Get original code location
const { fileName, lineNumber, columnNumber } = sourceMap.findOrigin(generatedLine, generatedColumn);

Now, fileName holds the name of the original source file, lineNumber holds the line number in the original file, and columnNumber holds the column number in the original file where the error occurred.

Real-World Applications

Source maps are essential for debugging and optimizing code. By mapping errors back to your original code, you can quickly identify and fix issues, making your code more efficient and reliable.

Additional Notes

If no corresponding location is found in the source map, an empty object is returned.
The sourceMap.findOrigin() method expects 1-indexed line and column numbers, which means they start from 1.
Source maps are typically generated when you compile or transpile your code, so you may not have to manually create them.

Previousinspector Nextmodules

Modules: node:module API

Introduction

Loading Modules

Exports

Modules as Caches

Real-World Applications

Example: Calculator Module

module.builtinModules

module.createRequire(filename)

Simplified Explanation:

Detailed Explanation:

Real-World Example:

Potential Applications:

module.syncBuiltinESMExports()

Customization Hooks

Real-World Applications

Code Examples

initialize() Hook

What is it?

How does it work?

What can I do with it?

Code Example

Real-World Applications

Potential Use Cases

resolve(specifier, context, nextResolve)

Real-world applications

load(url, context, nextLoad)

What can you do with the load hook?

How do I use the load hook?

Real-world examples

Importing Modules from HTTPS URLs

What is Node.js?

Import from HTTPS URLs

HTTPS-Hooks Module

Real-World Example

Potential Applications

Limitations

Import Maps

Resolve Hooks

Complete Code Implementation

module.findSourceMap(path)

SourceMap class

Modules: `node:module` API

`module.builtinModules`

`module.createRequire(filename)`

`module.syncBuiltinESMExports()`

`initialize()` Hook

`resolve(specifier, context, nextResolve)`

`load(url, context, nextLoad)`

What can you do with the `load` hook?

How do I use the `load` hook?

`module.findSourceMap(path)`