DEV Community: Damilola Olatunji

What's New in Ruby on Rails 8

Damilola Olatunji — Thu, 31 Oct 2024 12:08:59 +0000

The first Rails 8 beta has officially been released, bringing an exciting set of features, bug fixes, and improvements. This version builds on the foundation of Rails 7.2, while introducing new features and optimizations to make Rails development even more productive and enjoyable.

Key highlights include an integration with Kamal 2 for hassle-free deployments, the introduction of Propshaft as the new default asset pipeline, and extensive ActiveRecord enhancements. Rails 8 also brings several SQLite integration upgrades that make it a viable option for production use.

Let's dive in and explore everything that Rails 8 has to offer!

Effortless Deployments with Kamal 2 and Thruster

Rails 8 makes deploying your applications simple with Kamal 2 and Thruster.

Kamal 2 reduces the need for reliance on managed cloud services and Platform as a Service (PaaS) platforms by enabling quick and easy deployment to cloud VMs, bare metal servers, or VPS environments in just minutes.

With a single command (kamal setup), you can set up a production-ready Rails environment on a standard Linux box, making deployment both easy and cost-effective.

Kamal 2 also integrates with Thruster, a custom proxy built specifically for Rails that enables zero-downtime deployments, HTTP/2 support, automated SSL with Let's Encrypt, Gzip compression, and easy hosting of multiple apps on a single server — all without complex setup.

With Kamal 2 and Thruster, Rails 8 makes deploying apps easier than ever. And if you prefer a different deployment setup, you can opt out using the --skip-kamal flag to maintain your existing workflows.

Leaner Rails Deployments with Solid Adapters

One of the big improvements in Rails 8 is simpler deployments by reducing the number of additional services needed to implement common web application requirements.

Traditionally, if you required features like job queues, caching, and pub/sub messaging, you'd use a combination of a database like PostgreSQL with Redis for auxiliary functions.

With Rails 8, you can handle all these with just SQLite, thanks to three new database-backed adapters: Solid Cable, Solid Cache, and Solid Queue.

Solid Cable is Rails' new default Action Cable adapter in production and means you can drop the common dependency on Redis. It acts as the pub/sub server, relaying messages between the app and connected clients using fast polling through SQLite. Despite polling, Solid Cable's performance is comparable to Redis in most situations.
Solid Cache replaces the need for Redis by using disk storage instead of RAM for caching. This approach allows for much larger, more cost-effective caches that persist longer and handle more requests without sacrificing performance. It also supports encrypted storage and retention policies to meet privacy requirements.
Solid Queue replaces Redis for Active Job background processing, using the FOR UPDATE SKIP LOCKED mechanism for efficient job handling (compatible with PostgreSQL, MySQL, or SQLite). It includes essential features like concurrency control, retries, and recurring jobs, and has proven itself at HEY, where it now manages 20 million jobs per day.

These three adapters are designed around a simple idea: modern SSDs and NVMe drives are fast enough to handle many tasks that previously required in-memory solutions. By tapping into these speedy drives, Rails cuts out the need for separate RAM-based tools like Redis.

SQLite is Ready for Production

Rails 8 takes SQLite from a lightweight development tool to a reliable choice for production use, thanks to extensive work on the SQLite adapter and Ruby driver.

With the introduction of the solid adapters discussed above, SQLite now has the capability to power Action Cable, Rails.cache, and Active Job effectively, expanding its role beyond just prototyping or testing environments.

Here are some key improvements to the SQLite integration in Rails 8:

Full-text search and virtual tables are now supported using create_virtual_table.
The adapter now allows bulk insert fixtures for enhanced data seeding performance.
Transactions default to IMMEDIATE mode to improve concurrency.
Enhanced error handling by translating SQLite3::BusyException into ActiveRecord::StatementTimeout.

A New Era for the Asset Pipeline with Propshaft

Rails 8 also introduces Propshaft as the new asset pipeline default, replacing the long-standing Sprockets system. Sprockets served Rails developers well for over a decade, but it was designed in a different era — before the explosion of JavaScript build tools and modern browser improvements.

Propshaft reflects a simpler, modern approach to managing assets, built around the core needs of today's developers. Its purpose is straightforward: to provide a clear path for assets and apply digest stamps for caching.

Unlike Sprockets, which took on numerous additional tasks, Propshaft focuses only on what's essential, fitting naturally with the new Rails philosophy of keeping asset pipelines lean (while complex JavaScript handling is left to specialized tools like Esbuild or Vite).

Built-In Authentication Made Simple

Rails has been building the key components of authentication over the years, from has_secure_password in Rails 5 to normalizes, generates_token_for and authenticate_by in Rails 7.1.

With Rails 8, all these components come together to give you a straightforward starting point for building a secure, session-based authentication system.

By running a single command, you can set up all the essentials for an authentication system with database-backed sessions and password reset functionality:

bin/rails generate authentication

This command generates key files, including models, controllers, mailers, and views:

app/models/current.rb
app/models/user.rb
app/models/session.rb
app/controllers/sessions_controller.rb
app/controllers/passwords_controller.rb
app/mailers/passwords_mailer.rb
app/views/sessions/new.html.erb
app/views/passwords/new.html.erb
app/views/passwords/edit.html.erb
app/views/passwords_mailer/reset.html.erb
app/views/passwords_mailer/reset.text.erb
db/migrate/xxxxxxx_create_users.rb
db/migrate/xxxxxxx_create_sessions.rb
test/mailers/previews/passwords_mailer_preview.rb

This effectively puts you on the fast track to secure, production-ready authentication. All that's left is to integrate a user sign-up flow customized to your application's needs.

New Script Folder and Generator

Rails 8 introduces a new script folder dedicated to holding one-off or general-purpose scripts, such as data migrations, cleanup tasks, or other utility operations. This addition helps organize these scripts neatly, keeping them separate from your main application logic.

To make script creation easier, a new script generator is available. You can generate scripts with a simple command:

bin/rails generate script my_script

These commands create the corresponding script files, which you can then execute with:

bundle exec ruby script/my_script.rb

This streamlined approach keeps your application organized and makes handling custom scripts more convenient and maintainable.

A Slew of Active Record Improvements

Active Record has also seen major enhancements in Rails 8 to improve
performance, simplify migrations, improve troubleshooting, and provide better support for complex database use cases.

Below are some of the key changes introduced in this latest version:

Rails 8 now distinguishes between float4 and float8 in PostgreSQL.
drop_table now supports dropping multiple tables at once.
Support for PostgreSQL table inheritance and native partitioning has been added.
Bulk inserts of fixtures are now supported to improve data seeding performance.
Migrating a fresh database now starts by loading the database schema before running the migrations.
create_schema and drop_schema operations are now reversible.
Rails 8 now requires MySQL 5.6.4 or later due to advancements like datetime with precision.
Query log tags are enabled by default in development environments to trace SQL statements back to the application code and identify which database is in use.

Wrapping Up

Rails 8 introduces a range of impactful updates, from easier deployments with Kamal and a modern asset pipeline to significant ActiveRecord enhancements and improved production capabilities for SQLite.

These advancements not only boost developer productivity but also align with modern best practices, allowing you to focus on building your application instead of dealing with infrastructure complexities.

For a detailed list of all the new features, optimizations, and changes, check out the official Rails 8 release notes.

If you want to get involved with contributing to Rails, visit the
Rails GitHub repository to explore open issues and review the contribution guidelines.

Thanks for reading!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Advanced Use Cases of the Node.js Native Test Runner

Damilola Olatunji — Thu, 29 Aug 2024 08:44:36 +0000

Welcome back to our exploration of Node.js' built-in test runner! In the previous article, we laid the groundwork for writing and running basic tests in your projects by exploring a few simple examples.

In this installment, we'll dive into practical examples of how to use mocking, code coverage analysis, test hooks, and strategies for testing HTTP servers. These tools will help you write more comprehensive and reliable tests, ultimately leading to more robust Node.js applications.

Let's get started!

Setting Up and Tearing Down with Test Hooks

In testing, "setup" refers to the actions performed before a test, such as initializing variables or establishing database connections, to prepare an environment. Conversely, "teardown" refers to cleaning up after a test, like resetting data or closing connections, ensuring a pristine state for subsequent tests.

The Node.js test runner simplifies this process with built-in functions called hooks:

before(): Executes once before all tests within a test suite.
after(): Executes once after all tests within a test suite.
beforeEach(): Executes before each individual test in the current suite.
afterEach(): Executes after each individual test in the current suite.

These hooks promote test independence by ensuring each test starts with a clean slate unaffected by previous results. They also neatly encapsulate resource-intensive tasks, preventing unnecessary repetition.

Here's an illustrative example:

import { describe, it, beforeEach, before, after } from "node:test";
import assert from "node:assert/strict";
import sqlite3 from "sqlite3";

const db = new sqlite3.Database(":memory:"); // In-memory database for testing

describe("SQLite Database Operations", () => {
  before(() => {
    db.serialize(() => {
      db.run(
        "CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)"
      );
    });
  });

  beforeEach(() => {
    db.run("DELETE FROM users");
  });

  it("should insert a user", () => {
    db.run("INSERT INTO users (name) VALUES (?)", ["Alice"], function (err) {
      if (err) throw new Error(err); // Handle potential errors

      db.get("SELECT * FROM users WHERE name = 'Alice'", (err, row) => {
        if (err) throw new Error(err);

        assert.strictEqual(row.name, "Alice");
      });
    });
  });

  after(() => {
    db.close();
  });
});

This test imports the sqlite3 module and uses its in-memory function to test SQLite database operations. Here are the key aspects to note:

The before() hook creates the users table before any tests start.
Before each test, all existing records are deleted from the users table through the beforeEach() hook, ensuring a clean state.
The test inserts a user named 'Alice' into the database and retrieves the user by name to assert that it was indeed inserted.
The after() hook closes the database connection once all tests have completed.

Once you install the sqlite3 module and run the tests, you will see that it passes successfully:

▶ SQLite Database Operations
  ✔ should insert a user (0.630894ms)
▶ SQLite Database Operations (1.880435ms)
. . .

Mocking APIs

Mocking is a powerful testing technique where you swap out real dependencies with controlled substitutes (mocks). This allows you to isolate the code you're testing from external factors, so your tests are reliable and focus solely on the logic you're verifying.

Mocking allows you to focus solely on your function's core logic by isolating it from its dependencies, ensuring predictable and consistent responses to prevent flaky tests caused by external factors. It also allows you to verify the correct interaction between your function and its dependencies, such as checking for proper function calls with the right arguments and order.

The node:test module provides a versatile mock object to help you implement mocks in your tests. Let's delve into some practical scenarios where you can leverage mocking to enhance your testing arsenal.

Mocking Async Functions

You can use mocking to simulate the behavior of asynchronous functions in a controlled environment. Using mock.method(), you can replace the actual implementation with a mock function that returns a resolved promise to simulate success, or a rejected promise to simulate an error.

For instance, imagine an email service that you want to mock within your tests. You can use mock.method() to make it always return true (success):

import assert from "node:assert/strict";
import { describe, it, mock } from "node:test";

// Service to be mocked
const emailService = {
  sendEmail: (to, subject, body) => {
    /* implementation */
  },
};

describe("Mocking email sending", () => {
  it("should successfully send a mocked email", async () => {
    const to = "test@example.com";
    const subject = "Hello";
    const body = "This is a test email.";

    // Mock the sendEmail function to return a resolved promise
    mock.method(emailService, "sendEmail", async () => Promise.resolve(true));

    // Call the function with test data
    const result = await emailService.sendEmail(to, subject, body);

    // Assert that the email was "sent" successfully (based on our mock)
    assert.equal(result, true);
  });
});

Conversely, to simulate a failure scenario, you can make the mock function return a rejected promise:

describe("Mocking email sending", () => {
  it("should fail to send an email", async () => {
    const to = "test@example.com";
    const subject = "Hello";
    const body = "This is a test email.";

    mock.method(emailService, "sendEmail", async () =>
      Promise.reject({ error: "network error " })
    );

    await assert.rejects(
      async () => await emailService.sendEmail(to, subject, body)
    );
  });
});

Mocking Built-in APIs

You can also easily mock built-in APIs to ensure they behave predictably in your tests. Here's how to mock the fetch API, for example:

// module.js
async function fetchDataFromAPI() {
  // This makes a real network request to an API
  const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");

  const data = await response.json();

  return data;
}

export { fetchDataFromAPI };

// module.test.js
import { describe, it, mock } from "node:test";
import assert from "node:assert/strict";
import { fetchDataFromAPI } from "./module.js";

describe("fetchDataFromAPI", { only: true }, () => {
  it("should return mocked data", async () => {
    const expectedResponse = {
      userId: 1,
      id: 1,
      title: "Learn JavaScript",
      completed: true,
    };

    // fetch is mocked to always return the `expectedResponse`
    mock.method(global, "fetch", async () => {
      return {
        json: async () => expectedResponse,
      };
    });

    assert.deepStrictEqual(await fetchDataFromAPI(), expectedResponse);
    assert.strictEqual(global.fetch.mock.calls.length, 1);

    mock.reset();
  });
});

Here, mock.method() overrides the global fetch function. This returns a Promise that resolves to an object with a json() method (which also subsequently resolves to the desired object).

The test confirms that calling fetchDataFromAPI() returns the mocked response, and that the mock was called exactly once. This allows you to seamlessly test code that relies on fetch without making actual network calls.

This technique can be applied to other built-in APIs as well, such as the fs module. You can also simulate and control the behavior of timers like setInterval() and setTimeout() without actually waiting for the specified time intervals. Refer to the Node.js documentation on timers for details.

Providing Multiple Implementations

In scenarios where a mocked function is called multiple times within a single test, the mockImplementationOnce() method allows you to customize each invocation's behavior. Let's see how this works:

. . .

describe('fetchDataFromAPI', { only: true }, () => {
  it('should return mocked data', async () => {
    const expectedResponse = {
      userId: 1,
      id: 1,
      title: 'Learn JavaScript',
      completed: true,
    };

    const expectedResponse2 = {
      userId: 2,
      id: 2,
      title: 'Learn Go',
      completed: false,
    };

    // fetch is mocked to always return the `expectedResponse`
    const fetchMock = mock.method(global, 'fetch', async () => {
      return {
        json: async () => expectedResponse,
      };
    });

    // except on the second call, where `expectedResponse2` is used instead
    fetchMock.mock.mockImplementationOnce(async () => {
      return {
        json: async () => expectedResponse2,
      };
    }, 1); // 0 is the first call, 1 is the second, etc

    assert.deepStrictEqual(await fetchDataFromAPI(), expectedResponse);
    assert.deepStrictEqual(await fetchDataFromAPI(), expectedResponse2);
    assert.deepStrictEqual(await fetchDataFromAPI(), expectedResponse);
    assert.strictEqual(global.fetch.mock.calls.length, 3);
  });
});

Here, the mockImplementationOnce() method overrides the default behavior of the fetchMock only in its second call (indicated by the second argument 1).

This means that:

The first call to fetchDataFromAPI() will return expectedResponse, as set by the original mock.
The second call will return expectedResponse2, due to the temporary override.
Subsequent calls will revert back to the original mock's behavior, returning expectedResponse.

This flexibility allows you to simulate a sequence of varying responses from the mocked function, making your tests mirror the complexity of real-world interactions with your dependencies.

Obtaining Code Coverage Reports

Code coverage is a metric in software testing that measures how much of your source code is executed during the course of running your test suite. Often expressed as a percentage, it reveals the extent to which your tests exercise different parts of your codebase.

By pinpointing areas of code untouched by tests, code coverage analysis allows you to evaluate the effectiveness of your existing tests and strategically prioritize future testing efforts. While not an absolute guarantee of bug-free code, higher coverage typically signifies a higher level of confidence in your software's quality and reliability.

The Node.js test runner comes equipped with built-in code coverage reporting. To activate it, include the --experimental-test-coverage flag when executing your tests:

node --test --experimental-test-coverage

A coverage report will be generated that looks like this:

. . .
ℹ start of coverage report
ℹ -----------------------------------------------------------------------------------
ℹ file                       | line % | branch % | funcs % | uncovered lines
ℹ -----------------------------------------------------------------------------------
ℹ list_manager.js            |  71.05 |    83.33 |   57.14 | 18-19 23-27 30-31 34-35
ℹ tests/list_manager.test.js | 100.00 |   100.00 |  100.00 |
ℹ tests/main.test.js         | 100.00 |   100.00 |  100.00 |
ℹ -----------------------------------------------------------------------------------
ℹ all files                  |  90.83 |    91.67 |   72.73 |
ℹ -----------------------------------------------------------------------------------
ℹ end of coverage report

This report shows you:

Branch coverage: The percentage of decision points (e.g., if statements, loops) exercised during testing.
Function coverage: The percentage of functions that were called.
Line coverage: The percentage of lines of code that were executed.
Uncovered lines: Specific line numbers in each file that aren't covered by any tests.

For example, you'll notice that lines 33-45 of the list_manager.js file are currently not covered by any tests. This corresponds to the getAllItems() method:

// list_manager.js
class ListManager {
  . . .

  getAllItems() {
    return this.items;
  }
}

To address this gap, you could add a test specifically targeting this method:

import { describe, it } from 'node:test';
import { ListManager } from '../list_manager.js';
import assert from 'node:assert/strict';

describe('ListManager', () => {
  . . .

  it('should return all items', () => {
    const fruits = new ListManager(5);
    fruits.addItem('apple');
    fruits.addItem('orange');
    fruits.addItem('banana');
    assert.deepStrictEqual(fruits.getAllItems(), ['apple', 'orange', 'banana']);
  });
});

Rerunning the coverage report would then showcase improved metrics across lines, branches, and functions:

node --test --experimental-test-coverage

. . .
ℹ start of coverage report
ℹ -----------------------------------------------------------------------------
ℹ file                       | line % | branch % | funcs % | uncovered lines
ℹ -----------------------------------------------------------------------------
ℹ list_manager.js            |  76.32 |    85.71 |   71.43 | 18-19 23-27 30-31
ℹ tests/list_manager.test.js | 100.00 |   100.00 |  100.00 |
ℹ tests/main.test.js         | 100.00 |   100.00 |  100.00 |
ℹ -----------------------------------------------------------------------------
ℹ all files                  |  92.97 |    92.86 |   83.33 |
ℹ -----------------------------------------------------------------------------
ℹ end of coverage report

While striving for high code coverage is generally beneficial, it's not the sole determinant of a good testing strategy. Well-designed tests that thoroughly check for correct behavior and handle edge cases remain paramount, even if achieving 100% coverage isn't always feasible or necessary.

Customizing Test Reports

Test reporters in Node.js are specialized modules that format the results of your test runs. They provide a bridge between your raw test data and a presentation format that best suits your needs. This is invaluable for integrating test results into CI/CD workflows, enhancing readability in large test suites, and catering to specific reporting needs.

The Node.js test runner defaults to the spec reporter, which offers a colorized, hierarchical view ideal for terminals. However, you can tailor the output format using the --test-reporter flag, choosing from the following built-in reporters:

spec: The default, providing a structured, colorized overview in the terminal.

tap: Generates output in the Test Anything Protocol (TAP) format, ideal for non-terminal environments and further processing by other tools.

dot: Offers a minimalistic representation with dots for passed tests and 'X' for failures.

junit: Produces results in the JUnit XML format, commonly used in CI/CD pipelines and reporting tools.

lcov: Outputs code coverage data in the LCOV format when combined with the --experimental-test-coverage flag.

To illustrate this, let's generate a TAP report using:

node --test --test-reporter=tap

This produces:

TAP version 13
# Subtest: ListManager
    # Subtest: should be initialized to 0 when a maximum capacity is not provided
    ok 1 - should be initialized to 0 when a maximum capacity is not provided
      ---
      duration_ms: 0.569852
      ...
    # Subtest: should have a capacity of 5
    ok 2 - should have a capacity of 5
      ---
      duration_ms: 0.091852
      ...
    # Subtest: should reduce capacity from 5 to 4 when an item is added
    ok 3 - should reduce capacity from 5 to 4 when an item is added
      ---
      duration_ms: 0.127539
      ...
    # Subtest: should return all items in the list
    ok 4 - should return all items in the list
      ---
      duration_ms: 0.417246
      ...
    1..4
ok 1 - ListManager
  ---
  duration_ms: 2.013476
  type: 'suite'
  ...
# Subtest: tests/main.test.js
ok 2 - tests/main.test.js
  ---
  duration_ms: 26.023819
  ...
1..2
# tests 5
# suites 1
# pass 5
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 55.145833

Leverage the --test-reporter-destination flag (or, for TAP format, simple shell redirection) to save the output to a file:

node --test --test-reporter=tap --test-reporter-destination report.txt

node --test > report.txt

Either command produces a report.txt file in the current directory with the TAP formatted output. As mentioned earlier, tap is the default reporter for non-terminal output, so you don't need to explicitly use the --test-reporter and --test-reporter-destination flags if that's the desired format. You can just use shell output redirection to save the test report to a file as shown above.

You can also combine multiple reporters, specifying a destination for each:

node --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=tap --test-reporter-destination=report.txt

This outputs the spec report to the console (stdout) and the tap report to report.txt.

For advanced customization, you can create and utilize custom reporters by tapping into the events emitted by the TestStream object. Refer to the official documentation for more details on TestStream.

Testing HTTP Services

Now that we've explored the core features of Node.js's built-in test runner, let's now apply our knowledge to testing an HTTP server. Consider a simplified bookstore API, offering endpoints to list books (GET /books), place orders (POST /orders), and view existing orders (GET /orders).

We'll be using Fastify in this example, but the concepts also apply to other Node.js web frameworks like Express, Koa, and others.

Clone the GitHub repository to your machine with:

git clone https://github.com/damilolaolatunji/fastify-node-testing

Change into the directory, and install the required dependencies with:

cd fastify-node-testing
npm install

For testing purposes, we've separated the application logic
(app.js) from the server setup (server.js), making it easier to isolate and test the API endpoints. Note that we've omitted some validations and security measures to keep the example concise.

You may now start the server with:

npm start

{"level":30,"time":1715814630918,"pid":682099,"hostname":"fedora","msg":"Server listening at http://[::1]:3000"}
{"level":30,"time":1715814630919,"pid":682099,"hostname":"fedora","msg":"Server listening at http://127.0.0.1:3000"}
{"level":30,"time":1715814630919,"pid":682099,"hostname":"fedora","msg":"Fastify is listening on port: http://[::1]:3000"}

Once the server is ready, make a few requests to confirm that everything works as expected.

Start by fetching all the available books on the shelf with:

curl http://localhost:3000/books

This produces:

[
  {
    "id": 1,
    "title": "The Hitchhiker's Guide to the Galaxy",
    "price": 15
  },
  {
    "id": 2,
    "title": "Pride and Prejudice",
    "price": 10
  },
  {
    "id": 3,
    "title": "The Lord of the Rings",
    "price": 25
  }
]

To see the list of orders (currently empty), use:

curl http://localhost:3000/orders

[]

Finally, to create an order for a book, use:

curl -X POST http://localhost:3000/orders \
    -H "Content-Type: application/json" \
    -d '{"bookId": 1, "quantity": 4}'

This yields a total of $60:

{
  "bookId": 1,
  "quantity": 4,
  "total": 60
}

To see the new list of orders, use:

curl http://localhost:3000/orders

[
  {
    "bookId": 1,
    "quantity": 4,
    "total": 60
  }
]

Once confirmed, open the tests/app.test.js file in your text editor to read the tests for the service.

The beforeEach() hook is used to initialize a fresh instance of the
application before each test to avoid any potential side-effects from previous tests. Consequently, the afterEach() hook closes the server after each test case completes.

The code contains three describe blocks, each focusing on a specific endpoint (/books and /orders with GET and POST methods):

GET /books

This tests if the endpoint returns a list of 3 books with the correct details and JSON content type.

GET /orders

Checks if the endpoint returns an empty list of orders initially.
Creates an order using a POST request, then checks if the GET endpoint returns the newly created order.

POST /orders

Tests successful order creation with the correct response data.
Tests for a "bad request" error when trying to order a non-existent book.

In each test, Fastify's inject method provides an easy way to simulate HTTP requests to the application without actually running a server. However, you can also test the application after starting the server if you prefer (see the
Fastify documentation on testing).

You can execute the test using the Node test runner:

npm test

The following output confirms that the tests pass
successfully:

▶ Application endpoints
  ▶ GET /books
    ✔ should return a list of books (17.612687ms)
  ▶ GET /books (18.132371ms)
  ▶ GET /orders
    ✔ should return an empty list of orders (4.607706ms)
    ✔ should return a list of existing orders (5.17094ms)
  ▶ GET /orders (10.086249ms)
  ▶ POST /orders
    ✔ should create a new order successfully (3.049189ms)
    ✔ should return a bad request for a non-existent book (3.595889ms)
  ▶ POST /orders (6.865771ms)
▶ Application endpoints (35.69981ms)
. . .

And that's it!

Wrapping Up

In this two-part exploration of Node.js's built-in test runner, we've journeyed from basic to advanced testing concepts. You should now be equipped to create comprehensive and reliable tests for your applications without reaching for a third-party library.

Real-world experience from the community suggests that while the Node.js test runner is a promising tool, it does have some growing pains. For example, integrating it with TypeScript might require some creative workarounds, and while it's nice to use a built-in tool, some developers find themselves still reaching for familiar assertion libraries like expect.

However, the potential of the test runner is clear. As it matures, it could become a powerful and seamless part of your Node.js
toolkit.

Thanks for reading!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Exploring the Node.js Native Test Runner

Damilola Olatunji — Wed, 31 Jul 2024 11:20:23 +0000

The inclusion of a stable test runner in Node.js (version 18+) has generated significant debate in the community, given the abundance of established third-party testing frameworks.

While its arrival naturally sparks comparisons to existing tools, this article won't focus on justifying its place in the ecosystem. Instead, we'll embark on a hands-on exploration of the test runner's core capabilities, from writing and executing tests to organization and customization features.

But before diving in headfirst, let's get a clear picture of what testing is all about.

What Is Testing?

Picture yourself as a meticulous cook trying out a new recipe. You wouldn't just toss everything in a pot and hope for the best, would you? Instead, you'd carefully follow instructions, tasting and adjusting along the way.

You should take a similar approach to testing your Node.js applications. You're essentially writing little checks to verify that each program component (including functions and modules) in your application works as intended.

Think of tests as automated safeguards. They run your code, feed it different inputs, and compare the results to what you expect. This way, if something breaks down the road, your trusty tests will raise a red flag.

That's testing in a nutshell.

But why was a test runner recently added to Node, anyway?

Why Was A Test Runner Added to Node.js 18+?

The reasons behind this are summarized below:

The importance of testing software is widely acknowledged. A test runner in the Node.js standard library reinforces the idea that testing should be an integral part of the development process and not merely an afterthought.
Many modern languages and runtimes now favor a "batteries included" approach, providing core tooling out of the box. While Node.js has traditionally maintained a minimalist philosophy, this shift addresses a growing desire for more readily available developer tools.
The npm ecosystem, while incredibly valuable, has been a target of supply chain attacks. As test runners themselves can be intricate pieces of software, streamlining this process by offering a built-in option minimizes potential attack vectors.

Understanding these motivations is key to appreciating the value of the Node.js test runner.

Now let's start exploring the features of the Node.js test runner by writing a simple program.

Prerequisites

Ensure you're running Node.js v22 or later before proceeding, as some of the features and functionalities discussed in this context are exclusive to this version and may not be available in earlier releases.

Setting Up a Demo Program

To demonstrate how the test runner works in Node.js, we'll use a basic program that defines a ListManager class. This class manages an array of items, supporting add, remove, and find operations, while enforcing a capacity limit.

Here's the class implementation:

// list_manager.js
class ListManager {
  #maxItems;

  constructor(max) {
    this.#maxItems = max;
    this.items = [];
  }

  capacity() {
    return this.#maxItems - this.items.length;
  }

  addItem(item) {
    if (this.capacity() > 0) {
      this.items.push(item);
      return;
    }

    throw new Error("Capacity has been reached");
  }

  removeItem(item) {
    const index = this.items.indexOf(item);
    if (index > -1) {
      this.items.splice(index, 1);
    }
  }

  findItem(item) {
    return this.items.includes(item);
  }

  getAllItems() {
    return this.items;
  }
}

export { ListManager };

The ListManager class uses a private #maxItems field to manage the total capacity. It is also exported for use in other modules.

Here's a basic example of how to use it:

// main.js
import { ListManager } from "./list_manager.js";

const listManager = new ListManager(5);

// Add some items
listManager.addItem("Apple");
listManager.addItem("Banana");
listManager.addItem("Cherry");

// Check the capacity
console.log("Remaining capacity:", listManager.capacity()); // 2

// Check if a specific item exists
console.log('Is "Banana" in the list?', listManager.findItem("Banana")); // true

// Remove an item
listManager.removeItem("Banana");

// Check if the item is still there
console.log('Is "Banana" still in the list?', listManager.findItem("Banana")); // false

// List all items
console.log("Current items:", listManager.getAllItems()); // ['Apple', 'Cherry']

Running the above program should yield the following result:

Remaining capacity: 2
Is "Banana" in the list? true
Is "Banana" still in the list? false
Current items: [ 'Apple', 'Cherry' ]

In the next section, you will start writing unit tests to ensure the
ListManager methods work as expected.

Testing Your Node.js Code

Now that you understand the program's logic, it's time to write tests to ensure its correctness. Remember that unit tests involve feeding inputs into a program and checking the resulting output or the altered state of the program.

The test module supports the automated testing of a Node.js program by providing a standardized approach to testing, and output that reports when a test has passed or failed.

For our initial test, we'll use a ListManager instance with a maximum capacity of five, then invoke the addItem() method to add an item to the list. The test will then verify that the capacity has reduced to four.

To start, create a test environment by setting up a directory and a test file:

mkdir tests
code tests/list_manager.test.js

Inside this test file, write your first test to check that adding an item to a ListManager with a maximum capacity of five reduces its capacity to four:

// tests/list_manager.test.js
import { test } from "node:test";
import { ListManager } from "../list_manager.js";
import assert from "node:assert/strict";

test("test capacity after adding item", () => {
  const fruits = new ListManager(5);

  assert.strictEqual(fruits.capacity(), 5);

  fruits.addItem("apple");

  assert.strictEqual(fruits.capacity(), 4);
});

We currently have a single test that verifies that the capacity of the fruits list is reduced from five to four when a new item is added.

The first assertion checks if the initial list capacity is correctly set to five. Afterward, the second assertion checks that the capacity of the list is correctly updated to four after adding a single item.

Overall, this test verifies two things:

That the ListManager instance correctly initializes with the given capacity.
That the capacity() method correctly reports the updated capacity when an item is added to the list.

In the next section, you will learn how to run the test and interpret its result.

What Happens When You Run `node --test`

The node:test module is accompanied by the Node.js test runner which is accessible through the node --test command. This runner automatically locates and executes tests according to the following criteria, as detailed in the Node.js documentation:

File names or glob patterns directly provided as an argument to the command.
Files ending in .test.{js,mjs,cjs}, -test.{js,mjs,cjs}, and _test.{js,mjs,cjs} in any directory.
JavaScript files starting with test- in any directory.
Any .js, .cjs, or .mjs files within a test directory at any level.

Each file that is discovered by the test runner is subsequently executed in a separate child process. A test is considered successful if it completes with an exit code of 0; otherwise, it fails.

Go ahead and execute the test you wrote in the previous section with:

node --test

After the tests conclude, the runner displays a summary that includes the test name, outcome, and duration. Here's what the output might look like:

✔ test capacity after adding item (1.184909ms)
ℹ tests 1
ℹ suites 0
ℹ pass 1
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 53.081303

This summary provides a concise overview of the test results, helping you quickly assess the functionality and reliability of your application.

Dealing with Test Failures

To see how the Node.js test runner manages failing tests, we'll intentionally introduce an error to our test. Modify the second assertion in your list_manager.test.js to expect a capacity of 3 instead of 4:

assert.strictEqual(fruits.capacity(), 3);

This mismatch between expected and actual capacity values will result in a test failure. Running the test again will yield the following output:

✖ test capacity after adding item (1.68598ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:

  4 !== 3

      at TestContext.<anonymous> (file:///home/ayo/dev/demo/nodejs-testing/tests/list_manager.test.js:42:10)
      at Test.runInAsyncScope (node:async_hooks:206:9)
      at Test.run (node:internal/test_runner/test:824:25)
      at Test.processPendingSubtests (node:internal/test_runner/test:533:18)
      at node:internal/test_runner/harness:247:12
      at node:internal/process/task_queues:140:7
      at AsyncResource.runInAsyncScope (node:async_hooks:206:9)
      at AsyncResource.runMicrotask (node:internal/process/task_queues:137:8) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: 4,
    expected: 3,
    operator: 'strictEqual'
  }

ℹ tests 1
ℹ suites 0
ℹ pass 0
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 51.559443

. . .

The AssertionError here indicates a failed equality check, with the output detailing the actual and expected values and the specific assertion that was not met.

To resolve this and see a passing test again, undo the change to the expected value in your test file.

Organizing Test Cases with Subtests

Subtests are a feature in Node.js' testing framework that allows you to organize your tests hierarchically. This is facilitated through the TestContext object, which can be used within the test() function's callback to create nested subtests.

Here's how you can set it up:

// tests/list_manager.test.js
import { test } from "node:test";
import { ListManager } from "../list_manager.js";
import assert from "node:assert/strict";

test("test list capacity", async (t) => {
  await t.test("capacity is initialized to 5", () => {
    const fruits = new ListManager(5);
    assert.strictEqual(fruits.capacity(), 5);
  });

  await t.test("capacity is reduced to 4", () => {
    const fruits = new ListManager(5);
    fruits.addItem("apple");
    assert.strictEqual(fruits.capacity(), 4);
  });
});

In this structure, each subtest is clearly defined with its own name, making it easier to understand what each test aims to verify.

Since the t.test() method returns a promise, you must await each of them so that they run to completion, one after the other. If the top-level test() function exits prematurely, it could fail with an error, indicating that the subtest was canceled before completion:

. . .
✖ failing tests:

test at file:/home/dami/dev/demo/nodejs-testing/list_manager.test.js:12:5
✖ capacity is reduced to four (0.211737ms)
  'test did not finish before its parent and was cancelled'

When you run the test now, you should see the following results:

▶ test list capacity
  ✔ capacity is initialized to 5 (0.10952ms)
  ✔ capacity is reduced to 4 (0.086634ms)
▶ test list capacity (0.575585ms)

. . .

This shows each subtest grouped under the main test name, making the output organized and easy to follow.

Let's add a new subtest that checks the behavior of the ListManager when it is initialized without a maximum value:

test('test list capacity', async (t) => {
  await t.test('capacity is initialized to 0', () => {
    const empty = new ListManager();
    assert.strictEqual(empty.capacity(), 0);
  });

  . . .
});

This test is designed to check that a list without a predefined capacity defaults to zero. Run the test to see if this is indeed the case:

node --test

You will observe that the test fails:

✔ test capacity after adding item (1.012183ms)
▶ test list capacity
  ✖ capacity is initialized to 0 (1.050668ms)
    AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:

    NaN !== 0

        at TestContext.<anonymous> (file:///home/ayo/dev/demo/nodejs-testing/tests/list_manager.test.js:48:12)
        at Test.runInAsyncScope (node:async_hooks:206:9)
        at Test.run (node:internal/test_runner/test:824:25)
        at Test.start (node:internal/test_runner/test:721:17)
        at TestContext.test (node:internal/test_runner/test:279:20)
        at TestContext.<anonymous> (file:///home/ayo/dev/demo/nodejs-testing/tests/list_manager.test.js:46:11)
        at Test.runInAsyncScope (node:async_hooks:206:9)
        at Test.run (node:internal/test_runner/test:824:25)
        at Test.processPendingSubtests (node:internal/test_runner/test:533:18)
        at Test.postRun (node:internal/test_runner/test:923:19) {
      generatedMessage: true,
      code: 'ERR_ASSERTION',
      actual: NaN,
      expected: 0,
      operator: 'strictEqual'
    }

  ✔ capacity is initialized to 5 (0.121557ms)
  ✔ capacity is reduced to 4 (0.120019ms)
▶ test list capacity (1.861563ms)
. . .

Instead of 0, we get NaN, indicating that there's a bug in our code. To fix this issue, update the ListManager constructor to default max to 0 if no value is provided:

// list_manager.js
class ListManager {
  #maxItems;

  constructor(max = 0) {
    this.#maxItems = max;
    this.items = [];
  }

  . . .
}

export { ListManager };

Once corrected, rerun the test to see all subtests pass successfully:

▶ test list capacity
  ✔ capacity is initialized to 0 (0.366646ms)
  ✔ capacity is initialized to 5 (0.074781ms)
  ✔ capacity is reduced to 4 (0.081915ms)
▶ test list capacity (1.895922ms)
. . .

Using the Describe/It Syntax

The describe and it keywords are popularly used in other JavaScript testing frameworks to write and organize unit tests. This style originated in Ruby's Rspec testing library and is commonly known as spec-style testing.

The describe() function groups related tests into a cohesive suite, labeled by a descriptive string that explains what functionality the tests collectively assess. Meanwhile, it() acts as an alias for test(), housing the specific test implementation.

Here's how you can reformat the previously discussed tests using the describe/it syntax:

import { describe, it } from "node:test";
import { ListManager } from "../list_manager.js";
import assert from "node:assert/strict";

describe("ListManager capacity", () => {
  it("should be initialized to 0 when a maximum capacity is not provided", () => {
    const empty = new ListManager();
    assert.strictEqual(empty.capacity(), 0);
  });

  it("should have a capacity of 5", () => {
    const fruits = new ListManager(5);
    assert.strictEqual(fruits.capacity(), 5);
  });

  it("should reduce capacity from 5 to 4 when an item is added", () => {
    const fruits = new ListManager(5);
    fruits.addItem("apple");
    assert.strictEqual(fruits.capacity(), 4);
  });
});

The output is:

▶ ListManager capacity
  ✔ should be initialized to 0 when a maximum capacity is not provided (0.63274ms)
  ✔ should have a capacity of 5 (0.123713ms)
  ✔ should reduce capacity from 5 to 4 when an item is added (0.145275ms)
▶ ListManager capacity (1.8321ms)
. . .

Moving forward, we will continue using the describe/it syntax for its clear, structured approach to organizing tests.

Customizing Test Runs

As mentioned earlier, The node --test command automatically finds and runs tests across various files and directories.

However, let's say you're adding new tests or modifying existing ones. You might only want to run specific tests to save time, especially in large projects with numerous tests. Here are some methods to isolate and run only the tests you need.

Running All Tests In a File

You can execute all the tests in a file by passing a file name as the last argument to the node --test command. Since we currently have just one test file, let's create a dummy test in a new file that always passes:

// tests/main.test.js
import { describe, it } from "node:test";
import assert from "node:assert/strict";

describe("Dummy test suite", () => {
  it("should always pass", () => {
    assert.ok(true, "This assertion will always pass");
  });
});

Run this specific test file with:

node --test tests/main.test.js

This outputs:

▶ Dummy test suite
  ✔ should always pass (0.342366ms)
▶ Dummy test suite (2.274729ms)

ℹ tests 1
ℹ suites 1
ℹ pass 1
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 67.517265

Glob patterns work too (from Node.js v21)! If you want to execute tests across multiple files, try something like:

node --test "tests/**/*.test.js"

Wrap glob patterns in double quotes to prevent shell expansion and
ensure that the command works in different environments.

Filtering Tests by Name

The --test-name-pattern flag allows you to run tests whose names match the provided regular expression patterns. For example, you can run the dummy test alone like this:

node --test --test-name-pattern Dummy

This will run all the test cases in the Dummy test suite alone:

✔ tests/list_manager.test.js (44.956448ms)
▶ Dummy test suite
  ✔ should always pass (0.634768ms)
▶ Dummy test suite (1.480227ms)

. . .

You can also specify a regular expression pattern like this:

node --test --test-name-pattern '/\d+/'

This runs any tests whose names contain a number resulting in:

▶ ListManager capacity
  ✔ should be initialized to 0 when a maximum capacity is not provided (0.630625ms)
  ✔ should have a capacity of 5 (0.111545ms)
  ✔ should reduce capacity from 5 to 4 when an item is added (0.153768ms)
▶ ListManager capacity (1.911211ms)
✔ tests/main.test.js (44.292226ms)

. . .

You can also provide this flag multiple times if you wish to provide multiple patterns:

node --test --test-name-pattern '<pattern_1>' --test-name-pattern '<pattern_2>'

Skipping Tests

If you'd like to exclude certain tests from being executed, you can provide the skip option to a single test (or an entire suite) as follows:

// skip the entire suite
describe('A test suite', { skip: true }, () => {
  . . .
});

describe('A test suite', () => {
  // skip a specific test
  it('should pass', { skip: true }, () => {
    . . .
  });
});

You can also use the skip() method in the same manner:

// skip the entire suite
describe.skip('A test suite', () => {
  . . .
});

describe('A test suite', () => {
  // skip a specific test
  it.skip('should pass', () => {
    . . .
  });
});

The skip option is more handy because it allows you to skip a set of tests depending on the Node.js environment. For example, you may want to skip some tests locally, but run them all in a CI environment:

// skip the entire suite
describe('A test suite', { skip: process.env.NODE_ENV === "development" }, () => {
  . . .
})

A similar option for ultra-focused testing is the only property, which must be combined with the --test-only command-line flag. It skips all the top-level tests, except those marked with only:

// run only this test suite in a CI environment
// must be combined with the `--test-only` flag
describe('A test suite', { only: process.env.NODE_ENV === "ci" }, () => {
  . . .
})

At the subtest level, you can use the it.only() method to specify what tests to run:

// tests/list_manager.test.js
import { describe, it } from "node:test";
import { ListManager } from "../list_manager.js";
import assert from "node:assert/strict";

describe("ListManager capacity", { only: true }, () => {
  it("should be initialized to 0 when a maximum capacity is not provided", () => {
    const empty = new ListManager();
    assert.strictEqual(empty.capacity(), 0);
  });

  it.only("should have a capacity of 5", () => {
    const fruits = new ListManager(5);
    assert.strictEqual(fruits.capacity(), 5);
  });

  it("should reduce capacity from 5 to 4 when an item is added", () => {
    const fruits = new ListManager(5);
    fruits.addItem("apple");
    assert.strictEqual(fruits.capacity(), 4);
  });
});

Executing the tests with:

node --test --test-only

Will produce the output below:

▶ ListManager capacity
  ✔ should have a capacity of 5 (0.862671ms)
▶ ListManager capacity (2.041382ms)
✔ tests/main.test.js (45.39399ms)
. . .

Marking tests as "TODO"

TODO tests are a test runner feature allowing you to mark a test as incomplete or pending. This serves as a handy reminder for tests that still need to be written or fixed.

Here's how to mark a test as "todo":

import { describe, it } from "node:test";
import assert from "node:assert/strict";

describe("Feature X", () => {
  // you can use the todo method like this when you're reminding yourself
  // to write a test
  it.todo("should handle edge case A");

  // or you can provide the `todo` option when you're reminding yourself
  // to fix an existing test that's currently failing
  it("should log errors correctly", { todo: true }, () => {
    // this will still be executed, but it won't fail the test suite
    throw new Error("this does not fail the test");
  });
});

Upon execution, both methods result in tests marked as "# TODO" in the output. Importantly, while a test marked with the todo option still runs, its failure won't impact the overall test suite's success.

▶ Feature X
  ✔ should handle edge case A (0.087529ms) # TODO
  ✖ should log errors correctly (0.228632ms) # TODO
    Error: this does not fail the test
        at TestContext.<anonymous> (file:///home/ayo/dev/demo/nodejs-testing/tests/main.test.js:12:11)
        at Test.runInAsyncScope (node:async_hooks:206:9)
        at Test.run (node:internal/test_runner/test:735:25)
        at Suite.processPendingSubtests (node:internal/test_runner/test:449:18)
        at Test.postRun (node:internal/test_runner/test:842:19)
        at Test.run (node:internal/test_runner/test:777:12)
        at async Suite.processPendingSubtests (node:internal/test_runner/test:449:7)

. . .

To ensure that these TODO tests aren't neglected, you can configure your CI/CD pipeline to fail builds when TODO tests exist, prompting their eventual implementation. This practice fosters a proactive approach to test completion and helps maintain a high level of test coverage.

Wrapping Up

In this article, we covered the essentials of testing with Node.js: setting up a project, writing basic tests, and executing them. These fundamentals equip you to validate that your Node.js applications perform as intended, with every new feature thoroughly tested.

However, we've only scratched the surface of the test runner's capabilities! In the next installment of this series, we'll explore advanced techniques like mocking, code coverage, hooks, and testing HTTP servers.

Thanks for reading!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

What's New in Node.js 22

Damilola Olatunji — Tue, 21 May 2024 14:08:01 +0000

Node.js 22 has been released, offering a compelling upgrade for developers. It takes over the 'Current' release line, while v21 transitions into maintenance mode until its end-of-life in June.

This release delivers advances like a stabilized Watch mode, pattern matching support in the fs module, a default-enabled WebSocket client, and a new --run flag for script execution. It also offers some performance improvements and the usual V8 engine upgrade.

Let's dive in and explore all that Node.js v22 brings to the table!

Watch Mode is Stable

Node.js 18.11.0 introduced an incredibly useful --watch flag that allowed the
Node.js process to automatically restart any time an imported file was changed.

To use this functionality, you execute a command like this:

node --watch server.js

The command would watch your server.js file and restart the process when it detected changes were made to the file or any of its imported modules.

You could also use the companion --watch-path flag (supported on macOS and Windows only) to specify the exact paths that should be monitored for changes, like this:

node --watch-path=./src --watch-path=./tests server.js

However, because watch mode was marked as experimental, the below warning resulted whenever it was used:

(node:1710176) ExperimentalWarning: Watch mode is an experimental feature and might change at any time

With the release of Node.js 22, this feature has been stabilized, so this warning no longer appears. While you could previously use a third-party tool like nodemon, this update removes the need for a dependency by adding it directly to Node.js core.

WebSocket Global Enabled by Default

In the previous Node 21 release, a built-in browser-compatible WebSocket client, as standardized by WHATWG, was added under the --experimental-websocket flag.

// index.js
const socket = new WebSocket("ws://localhost:8080");

socket.addEventListener("open", (event) => {
  socket.send("Hello Server!");
});

socket.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

To use it, you had to run:

node --experimental-websocket index.js

In Node.js 22, you no longer need to use the --experimental-websocket flag as the WebSocket global is now enabled by default. This means you can now open bidirectional communication channels between client and server without installing external dependencies.

Support for Running `package.json` Scripts

This release introduces an experimental --run flag, which provides a faster alternative to npm run for executing scripts defined in package.json files. Assuming you have a test script in your package.json, you can now execute it with:

node --run test

On my machine, this runs twice as fast as npm run test:

hyperfine --warmup 3 'node --run test' 'npm test'

Benchmark 1: node --run test
  Time (mean ± σ):     125.1 ms ±   4.4 ms    [User: 146.5 ms, System: 43.5 ms]
  Range (min … max):   116.7 ms … 134.7 ms    25 runs

Benchmark 2: npm run test
  Time (mean ± σ):     255.1 ms ±   8.5 ms    [User: 285.6 ms, System: 62.4 ms]
  Range (min … max):   245.5 ms … 275.9 ms    12 runs

Summary
  node --run test ran
    2.04 ± 0.10 times faster than npm run test

Note that the goal of --run isn't to match all the behaviors of npm run, but to provide better performance in the most common cases. You can see a summary of its limitations in the Node docs.

Loading ES Modules with `require()`

To improve interoperability between ES Modules and the older CommonJS system, a new --experimental-require-module has been added to import ES Modules through require(). Here's how it works:

// hello.mjs is an ES Module
export default function () {
  console.log("hello world!");
}

// index.js is a CommonJS Module
const hello = require("./hello.mjs").default;
hello();

When you execute the index.js file with the --experimental-require-module:

node --experimental-require-module index.js

You will observe the following output:

hello world!
(node:1738449) ExperimentalWarning: Support for loading ES Module in require() is an experimental feature and might change at any time

For this to work, the following requirements must be met by the imported ES module:

It must be explicitly marked as an ES module through the .mjs extension, or with "type": "module" in the closest package.json file.
It must be fully synchronous, without a top-level await.

The goal is to eventually enable this behavior by default in a future release.

`fs` Module Supports Pattern Matching

Node.js 22 also introduces new APIs to the node:fs module for pattern matching. These are the glob and globSync methods that can be used for matching file paths based on the supplied glob pattern.

You can use it via node:fs or node:fs/promises:

import { glob } from "node:fs";

glob("**/*.js", (err, matches) => {
  if (err) throw err;
  console.log(matches);
});

import { glob } from "node:fs/promises";

for await (const entry of glob("**/*.js")) console.log(entry);

Note that this feature is currently marked as experimental, so you may see the following warning message when the API is used:

(node:1748923) ExperimentalWarning: glob is an experimental feature and might change at any time

`AbortSignal` Performance Improvements

Creating AbortSignal instances is now significantly faster in Node.js 22. This class is used to notify observers when the abortController.abort() method is called. These enhancements directly benefit high-level APIs that utilize this class, such as fetch and the Node.js test runner.

Enhancements to Stream `highWaterMark`

The highWaterMark parameter, which controls the internal buffer size for streams, has been increased from 16KiB to 64KiB in Node.js 22. This change offers potential performance improvements across the board. However, the increase might lead to slightly higher memory consumption. For memory-sensitive applications, explicitly setting the buffer size with setDefaultHighWaterMark is recommended.

V8 Upgraded to v12.4

Node.js 22 ships with a customary upgrade to the V8 JavaScript engine, which brings several enhancements:

WebAssembly Garbage Collection for improved memory management.
Support for new JavaScript features, including Array.fromAsync(), Set methods, and Iterator helpers.
The Maglev compiler is enabled by default for supported architectures, bringing performance boosts for short-lived CLI programs.

Should You Use Node.js 22 in Production?

Node.js 22, as an even-numbered release, is on track to become a Long-Term Support (LTS) version in October. This means guaranteed support and security updates until April 2027. However, until its LTS promotion, it will remain as the 'Current' release.

It's not necessary to upgrade to Node.js 22 in your production environment on day one. However, we advise that you explore the new features and improvements this version offers and its potential impact on your applications before performing the upgrade at a convenient time.

How to Upgrade to Node.js 22

Ready to experience the latest features in Node.js 22? Here's how to upgrade:

Direct Download

Visit the official Node.js download page
Choose the installer that matches your operating system and architecture, and install it as you normally would.

Node.js Version Manager (Recommended)

For greater flexibility in managing multiple versions of Node.js simultaneously, consider a version management tool like Volta:

Install the Volta CLI (refer to the Volta documentation).
Use the following command to install or upgrade to Node.js 22:

volta install node@22

This output confirms the installation is successful:

success: installed and set node@22.0.0 (with npm@10.5.1) as default

Wrapping Up

Node.js v22 introduces numerous improvements in tooling, language features, standard library additions, and performance optimizations. These enhancements further solidify its position as the premier JavaScript runtime for modern web development.

For a complete breakdown of bug fixes, new features, and other changes, refer to the official Node.js v22 release notes.

If you're interested in getting involved with its development, explore Node's open issues and the Node contribution guidelines on GitHub.

Thanks for reading!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Measuring Node.js Performance in Production with Performance Hooks

Damilola Olatunji — Wed, 01 May 2024 11:42:21 +0000

In the first part of this series, we toured performance APIs in Node.js. We discussed the capabilities of APIs and how they can diagnose slowdowns or network issues in your Node application.

Now, in this concluding segment, we will embark on a practical journey, applying these performance hooks in a real-world scenario. You will understand how to effectively use these tools to monitor and enhance your application's performance.

Let's dive in and see these concepts in action!

Prerequisites

Before proceeding with this tutorial, ensure you have a foundational understanding of the Node.js Performance Measurement APIs as outlined in part one of this series.

Continuous Monitoring with Performance Observer for Node

Continuing our exploration of Node.js Performance APIs, we come to the Performance Observer. This API allows you to track new PerformanceEntry instances in real time as they are added to the Performance Timeline. Let's examine how to implement it:

import { performance, PerformanceObserver } from "node:perf_hooks";

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log(entry);
  }
});

observer.observe({ entryTypes: ["resource"] });

With this configuration, every time a PerformanceEntry with the 'resource' entryType is added to the Performance Timeline, it gets logged automatically to the console. To explore all the entry types available for monitoring, you can execute:

console.log(PerformanceObserver.supportedEntryTypes);

This will display a variety of entry types:

[
  "dns",
  "function",
  "gc",
  "http",
  "http2",
  "mark",
  "measure",
  "net",
  "resource",
];

To broaden the scope of monitoring to encompass all these entry types, adjust your observer like so:

observer.observe({ entryTypes: PerformanceObserver.supportedEntryTypes });

A use case for observing the performance timeline is to upload performance measurements to an Application Performance Monitoring (APM) service like AppSignal. This way, you can keep track of how the key metrics you care about are performing and get alerted to any performance degradation.

In the following sections, I'll present a practical example showcasing the use of the Performance Observer in real-world application contexts.

A Practical Example: Monitoring Third-Party API Integrations for Node

To maintain a seamless user experience within your app, you need to track the performance of the external APIs you rely on. Delays in API responses can lead to slower interactions, adversely affecting your application's responsiveness.

To mitigate this, it's advisable to choose API providers that offer response time guarantees. Additionally, you can implement a strategy to switch to a fallback API or use cached resources when experiencing latency spikes.

Let's explore a practical scenario where your Node.js application interacts with multiple third-party APIs. You need to track each request's latency to establish a performance baseline and monitor adherence to Service-Level Agreements (SLAs).

In such cases, you can use the performance measurement APIs to collect the timing data, format it appropriately, and dispatch it periodically to a performance monitoring tool or a logging system.

This ongoing process allows you to understand the typical performance parameters for each API, so you can quickly identify and resolve any anomalies or unexpected delays in API responses.

In the following example, you'll set up monitoring for a Node.js application's API requests using AppSignal. This setup ensures that you can always track an API's response times and get alerted to performance issues automatically.

Let's begin!

Setting up the Demo Repository

To follow through with the example below, clone this repository to your computer with the command below:

git clone https://github.com/damilolaolatunji/nodejs-perf

After cloning, switch to the repository's directory and install the necessary dependencies:

cd nodejs-perf
npm install

Then, open the project in your text editor and navigate to the server.js file. This file includes a basic Fastify server setup with one route:

import Fastify from "fastify";

const fastify = Fastify({
  logger: true,
  disableRequestLogging: true,
});

fastify.get("/", async (_request, reply) => {
  const res1 = await fetch("https://jsonplaceholder.typicode.com/posts/1");
  await res1.json();

  const res2 = await fetch("https://covid-api.com/api/reports/total");
  await res2.json();

  const res3 = await fetch("https://ipinfo.io/json");
  await res3.json();
});

const port = process.env.PORT || 3000;

fastify.listen({ port }, (err, address) => {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }

  fastify.log.info(`Fastify is listening on port: ${address}`);
});

This route performs three GET requests and returns a 200 OK response. While this is a simplistic example, it's perfectly suited to demonstrate how performance hooks can be employed in real-world applications.

To start the server for development on port 3000, run:

npm run start-dev

Verify that the server is functioning correctly by sending a request to the root using curl. The command should execute successfully:

curl http://localhost:3000

In the following section, you'll use the PerformanceObserver API to monitor each API request continuously.

Tracking the API Requests

Since the Fetch API automatically adds resource timing data to the Performance Timeline for each request, you can automatically track the measurements using the PerformanceObserver API as shown below:

// server.js
import Fastify from 'fastify';
import { performance, PerformanceObserver } from 'node:perf_hooks';

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.initiatorType === 'fetch') {
      console.log(entry);
    }
  }

  performance.clearResourceTimings();
});

observer.observe({ entryTypes: ['resource'] });

. . .

In this setup, each time a PerformanceResourceTiming object is added to the timeline, the script checks if the initiator is a fetch request and logs the details to the console. Clearing the resource timings after logging ensures room for new entries.

Once you update the file, the server should restart, and you can repeat the curl command from earlier:

curl http://localhost:3000

The server's console should now display three PerformanceResourceTiming entries sequentially:

PerformanceResourceTiming {
  name: 'https://jsonplaceholder.typicode.com/posts/1',
  entryType: 'resource',
  startTime: 205250.912353009,
  duration: 2046.0582769811153,
  initiatorType: 'fetch',
  nextHopProtocol: undefined,
  workerStart: 0,
  redirectStart: 0,
  redirectEnd: 0,
  fetchStart: 205250.912353009,
  domainLookupStart: undefined,
  domainLookupEnd: undefined,
  connectStart: undefined,
  connectEnd: undefined,
  secureConnectionStart: undefined,
  requestStart: 0,
  responseStart: 0,
  responseEnd: 207296.9706299901,
  transferSize: 300,
  encodedBodySize: 0,
  decodedBodySize: 0
}
PerformanceResourceTiming {
  name: 'https://covid-api.com/api/reports/total',
  entryType: 'resource',
  startTime: 207298.71959400177,
  duration: 4112.256608009338,
  initiatorType: 'fetch',
  nextHopProtocol: undefined,
  workerStart: 0,
  redirectStart: 0,
  redirectEnd: 0,
  fetchStart: 207298.71959400177,
  domainLookupStart: undefined,
  domainLookupEnd: undefined,
  connectStart: undefined,
  connectEnd: undefined,
  secureConnectionStart: undefined,
  requestStart: 0,
  responseStart: 0,
  responseEnd: 211410.9762020111,
  transferSize: 300,
  encodedBodySize: 0,
  decodedBodySize: 0
}
PerformanceResourceTiming {
  name: 'https://ipinfo.io/json',
  entryType: 'resource',
  startTime: 211411.61356300116,
  duration: 2160.16487801075,
  initiatorType: 'fetch',
  nextHopProtocol: undefined,
  workerStart: 0,
  redirectStart: 0,
  redirectEnd: 0,
  fetchStart: 211411.61356300116,
  domainLookupStart: undefined,
  domainLookupEnd: undefined,
  connectStart: undefined,
  connectEnd: undefined,
  secureConnectionStart: undefined,
  requestStart: 0,
  responseStart: 0,
  responseEnd: 213571.7784410119,
  transferSize: 300,
  encodedBodySize: 0,
  decodedBodySize: 0
}

For a more focused output, you can modify the logging to include only the relevant details:

if (entry.initiatorType === "fetch") {
  console.log(entry.name, entry.duration);
}

Resulting in:

https://jsonplaceholder.typicode.com/posts/1 1969.7759200036526
Ghttps://covid-api.com/api/reports/total 3156.867073982954
https://ipinfo.io/json 1885.5162260234356

With the ability to track, format, and log each request's timing, the next phase involves integrating these metrics with a monitoring solution like AppSignal.

Before moving to the next section, sign up for a 30-day free trial of AppSignal.

Tracking Node.js Performance Measurements with AppSignal

Once you've signed into your AppSignal account, create a new application and follow the setup instructions. Copy the Push API Key when prompted or head over to the settings and find the key in the Push & Deploy section.

Back in your project, create a .env file at the root directory and add your AppSignal Push API Key:

// .env
APPSIGNAL_PUSH_API_KEY=<your push api key>

Once saved, return to your server.js file and
initialize your AppSignal configuration
as follows:

// server.js
import 'dotenv/config';
import { Appsignal } from '@appsignal/nodejs';
import Fastify from 'fastify';
import { performance, PerformanceObserver } from 'node:perf_hooks';

new Appsignal({
  active: true,
  name: 'Node.js Perf Demo',
  pushApiKey: process.env.APPSIGNAL_PUSH_API_KEY,
});

. . .

Next, modify the PerformanceObserver to start tracking the timing data in AppSignal:

// server.js
. . .
const meter = Appsignal.client.metrics();

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.initiatorType === 'fetch') {
      meter.addDistributionValue('external_api_request', entry.duration, {
        url: entry.name,
      });
    }
  }

  performance.clearResourceTimings();
});

observer.observe({ entryTypes: ['resource'] });
. . .

The addDistributionValue() method is ideal for tracking metrics over time, allowing you to create graphs based on average values or call counts.

Its first argument is the metric name, and the second is the value to be tracked. It also accepts one or more tags in an optional object, which, in this case, is each third-party integration being tracked in the program.

Save the file and wait for the server to restart. Test the setup by sending requests to the / route every five seconds using this script:

while true; do curl http://localhost:4000; sleep 5; done

With the script running, head back to your AppSignal application and click Add dashboard on the left followed by Create a dashboard on the resulting page. Title your dashboard and click Create dashboard.

Once the dashboard is created, click the Add graph button. Give your graph a title (such as "Request durations") and click the add metric button:

Find the external_api_request metric option and configure the graph as shown below:

Click the Back to overview button, and change the value of the Label of value in Legend field to:

%name% %field% %tag%

Once you're done, click the Create graph button on the bottom right. You will now see a line graph plotting the duration of each API request made by your program.

You can hover on the line graph to view the mean, 90th, and 95th percentile for each request.

Any spikes or unusual patterns in the chart can be investigated to pinpoint the cause of performance issues.

See the AppSignal documentation for more information on metrics and dashboards.

Getting Alerted to Performance Issues

When you've established the normal behavior of an API, you can set up alerts to detect when anomalies occur. AppSignal simplifies this process, allowing you to quickly configure alerts for unusual performance patterns.

Return to your dashboard and find the Anomaly Detection > Triggers section in the lower left. Click the Add a trigger button on the resulting page:

In the New trigger form, click Custom metrics at the bottom of the sidebar. Here, configure the trigger based on your specific requirements. Ensure you select external_api_request as the Metric name and choose an appropriate Comparison operator that suits the alert condition you want to monitor.

To receive email alerts, ensure that the Email notifications option is checked. This will notify you via email whenever the set conditions are met, helping you stay informed about any performance issues in real time. You can also add other alerting integrations like Slack, PagerDuty, Discord, etc., in the application settings.

Once you've set up the trigger conditions and notification settings, click Save trigger. This action will activate the trigger, and AppSignal will start monitoring the specified metric according to the conditions you've set.

And that's it!

Wrapping Up

With this setup in place, you can now track your third-party integrations reliably and get alerted if any performance issues arise.

I hope this has given you an idea of how to use the Node.js performance APIs in tandem with AppSignal to track, monitor, and ultimately improve your Node application's performance.

Cheers, and happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Node.js Performance APIs: An Introduction

Damilola Olatunji — Wed, 27 Mar 2024 13:00:00 +0000

Node.js offers a rich set of performance data through its APIs, similar to how modern web browsers expose performance metrics for webpages.

With tools like the Performance Measurement API and the perf_hooks module in Node.js, you can gain insights into your application's performance from the server's perspective, closely aligning with what the end user experiences.

In this article, the first of a two-part series about performance hooks, we'll explore how to approach performance optimization in Node.js. Along the way, we'll leverage Node's built-in timing APIs to enhance the efficiency of our application.

Let's get going!

Prerequisites

To follow along with this tutorial, you'll need a basic knowledge of Node.js and a recent version installed, preferably the latest LTS.

Understanding Fundamental Node.js Performance API Concepts

Before diving into Node.js performance APIs, it's important to understand some essential terms that frequently appear in discussions and documentation: a monotonic clock, high resolution time API, and performance timeline. Let's look at each of these in turn.

1. A Monotonic Clock

In JavaScript, the Date.now() function generates timestamps based on the system clock, counting from the Unix epoch (1970-01-01T00:00:00Z). However, using these timestamps for precise measurements can be unreliable because they are vulnerable to any alterations in the system clock.

In contrast, a monotonic clock offers a timekeeping mechanism that always progresses forward, without any backward movement. Its key advantage lies in its stability against system clock changes, making it ideal for accurately measuring the time span between events or the duration of specific tasks.

2. High Resolution Time API

The High Resolution Time API provides a JavaScript interface for obtaining highly accurate time measurements. It uses a sub-millisecond monotonic timestamp that remains unaffected by any changes to the system clock.

This API's functionality is encapsulated in the performance.now() method. It returns a timestamp in sub-milliseconds, calculated relative to performance.timeOrigin — a UNIX timestamp denoting the initiation of a current Node.js process.

Here's a quick example to illustrate its usage:

import { performance } from "node:perf_hooks";

console.log(performance.now());

Running this code produces output such as:

26.664009988307953

This means that the console.log statement runs about 26 milliseconds from the initialization of the Node.js process.

Whenever you come across terms like "high resolution" or "high precision timestamp" in JavaScript, this refers to values generated by the performance.now() method.

3. Performance Timeline

The Performance Timeline in Node.js is a structured sequence of timing details and key performance milestones. These are captured both from the Node.js process itself and any code executed within your application.

This timeline consists of PerformanceEntry objects (and subclasses), each offering insights into the type and name of an event, along with precise timestamps indicating both the start and the duration of the event.

Here's an example of such entries:

[
  PerformanceMark {
    name: 'query_start',
    entryType: 'mark',
    startTime: 49.083899974823,
    duration: 0,
    detail: null
  },
  PerformanceMark {
    name: 'query_end',
    entryType: 'mark',
    startTime: 674.0229699611664,
    duration: 0,
    detail: null
  }
]

The Performance Timeline is mainly used to monitor and extract comprehensive performance metrics throughout the entire lifecycle of a Node.js application.

This information is invaluable for real-time performance analysis and can be seamlessly integrated with monitoring systems like AppSignal for Node.js to enhance application performance insights and diagnostics.

Inside the Node.js Performance API

Node.js offers a suite of Performance Measurement APIs within its perf_hooks module that are specifically designed to record Node.js performance data.

These APIs are inspired by, and partially implement, the
Web Performance APIs found in browser environments. However, they are tailored and adapted to suit server-side programming contexts.

In the following sections, we'll dive into some of the key APIs provided by this module:

PerformanceNodeTiming
Performance.now()
Performance.mark()
Performance.getEntries()
Performance.measure()
Performance.clearMarks()
Performance.clearMeasures()
PerformanceResourceTiming

1. `PerformanceNodeTiming`

In any Node.js program, the initial entry in the Performance Timeline is a PerformanceNodeTiming instance. It distinctively captures the timestamps of significant milestones during the startup phase of a process. To access this data, you can print the performance object, as demonstrated below:

import { performance } from "node:perf_hooks";

console.log(performance);

This results in an output like:

Performance {
  nodeTiming: PerformanceNodeTiming {
    name: 'node',
    entryType: 'node',
    startTime: 0,
    duration: 17.71333795785904,
    nodeStart: 0.256866991519928,
    v8Start: 2.246299982070923,
    bootstrapComplete: 9.73558497428894,
    environment: 6.018610000610352,
    loopStart: 13.11082899570465,
    loopExit: -1,
    idleTime: 0.03074
  },
  timeOrigin: 1700776448830.537
}

The nodeTiming object, as part of the Node.js runtime timings, provides a detailed view of various stages in the process lifecycle. Here's a breakdown of its key properties:

name: Identifies the performance entry, which is the Node.js process in this case.
entryType: Specifies the type of performance entry.
startTime: Indicates when the measurement started, with 0 denoting the beginning of the process execution.
duration: Represents the duration from the start of the process to the point when the entry was recorded.
nodeStart: A high resolution timestamp marking the start of the Node.js runtime initialization.
v8Start: The time at which the V8 JavaScript engine began initializing.
bootstrapComplete: The time taken for the Node.js environment to complete setup and get ready to execute user scripts.
environment: The duration required to establish the Node.js environment.
loopStart: The high resolution timestamp marking the start of the event loop.
loopExit: Indicates when the event loop exited; a value of -1 suggests it was still active at the time of recording.
idleTime: The amount of time the event loop spent idle, not engaged in processing tasks.

2. `Performance.now()`

To measure an operation's execution time in Node.js, you can use performance.now() to generate high-resolution timestamps.

By capturing two timestamps — one before the operation starts and another after its completion — and then calculating the difference between them, you can determine an operation's duration.

The following example demonstrates this:

import { performance } from "node:perf_hooks";

const t0 = performance.now();
await fetch("https://jsonplaceholder.typicode.com/todos/1");
const t1 = performance.now();

console.log(`Fetch request took ${t1 - t0} milliseconds.`);

Running this script typically results in an output like:

Fetch request took 682.8348079919815 milliseconds.

While this works for simple cases, there are more flexible methods available, which we'll explore later in this tutorial.

3. `Performance.mark()`

The performance.mark() function is a powerful method for creating and adding named markers to the Performance Timeline. These markers can later be retrieved for performance analysis.

For instance, to track the start and end of an HTTP request, you might use it as follows:

import { performance } from "node:perf_hooks";

const mark1 = performance.mark("mark_fetch_start");
await fetch("https://jsonplaceholder.typicode.com/todos/1");
const mark2 = performance.mark("mark_fetch_end");

console.log(mark1);
console.log(mark2);

This will result in an output similar to:

PerformanceMark {
  name: 'mark_fetch_start',
  entryType: 'mark',
  startTime: 17.95012092590332,
  duration: 0,
  detail: null
}
PerformanceMark {
  name: 'mark_fetch_end',
  entryType: 'mark',
  startTime: 959.4822289943695,
  duration: 0,
  detail: null
}

In this example, the startTime for each PerformanceMark object reflects a high-resolution timestamp, akin to what performance.now() provides. The duration for such objects is always zero since they represent specific moments in time.

You can also enrich these markers with additional information using the detail property:

import { performance } from "node:perf_hooks";

const url = "https://jsonplaceholder.typicode.com/todos/1";
const options = {
  detail: {
    url,
  },
};

const mark1 = performance.mark("mark_fetch_start", options);
await fetch(url);
const mark2 = performance.mark("mark_fetch_end", options);

console.log(mark1);
console.log(mark2);

Resulting in:

// outputs:
PerformanceMark {
  name: 'mark_fetch_start',
  entryType: 'mark',
  startTime: 25.053369998931885,
  duration: 0,
  detail: { url: 'https://jsonplaceholder.typicode.com/todos/1' }
}
PerformanceMark {
  name: 'mark_fetch_end',
  entryType: 'mark',
  startTime: 690.2271919250488,
  duration: 0,
  detail: { url: 'https://jsonplaceholder.typicode.com/todos/1' }
}

By adding the detail property, the performance marks provide not just timing information but also contextual data, enhancing the comprehensiveness of your performance analysis.

4. `Performance.getEntries()`

A PerformanceEntry is a unique entity representing a single performance metric within an application's Performance Timeline. For instance, the PerformanceMark objects we discussed earlier are subclasses of PerformanceEntry, characterized by an entryType of mark.

Use getEntries() to retrieve an array of all the PerformanceEntry objects logged up to a specific moment in your program's execution. Here's an example:

import { performance } from "node:perf_hooks";

performance.mark("mark_fetch_start");
await fetch("https://jsonplaceholder.typicode.com/todos/1");
performance.mark("mark_fetch_end");

console.log(performance.getEntries());

Running this snippet of code produces an array output like this:

[
  PerformanceMark {
    name: 'mark_fetch_start',
    entryType: 'mark',
    startTime: 49.083899974823,
    duration: 0,
    detail: null
  },
  PerformanceMark {
    name: 'mark_fetch_end',
    entryType: 'mark',
    startTime: 674.0229699611664,
    duration: 0,
    detail: null
  }
]

For situations where your Performance Timeline contains numerous entries and you wish to access only specific subsets, Node.js offers getEntriesByName() and getEntriesByType() methods. These methods allow for filtering based on the name and entryType properties of the performance entries:

// get all entries whose name is `mark_fetch_start`
console.log(performance.getEntriesByName("mark_fetch_start"));

// get all entries whose name is `mark_fetch_start` and whose type is `mark`
console.log(performance.getEntriesByName("mark_fetch_start", "mark"));

// get all entries whose entryType is `mark`
console.log(performance.getEntriesByType("mark"));

These methods provide a more focused approach to examining performance data, enabling you to isolate and analyze specific aspects of your application's performance.

5. `Performance.measure()`

The Performance.measure() method creates PerformanceMeasure objects that quantify the duration between two specific points in time (often marked by PerformanceMark objects) within an application's Performance Timeline:

performance.measure(name[, startMarkOrOptions[, endMark]])

If only the name parameter is supplied, it will generate a
PerformanceMeasure object capturing the program's duration up until the call:

console.log(performance.measure("measureProgram"));

This command results in an output like:

PerformanceMeasure {
  name: 'measureProgram',
  entryType: 'measure',
  startTime: 0,
  duration: 936.0637300014496
}

A more practical usage of measure() is calculating the elapsed time between two previously recorded PerformanceMark objects:

import { performance } from "node:perf_hooks";

const url = "https://jsonplaceholder.typicode.com/todos/1";
const mark1 = performance.mark("mark_fetch_start");
await fetch(url);
const mark2 = performance.mark("mark_fetch_end");

console.log(
  performance.measure("measureProgram", "mark_fetch_start", "mark_fetch_end")
);

This will output something similar to the following:

PerformanceMeasure {
  name: 'measureFetch',
  entryType: 'measure',
  startTime: 22.075212001800537,
  duration: 903.0410770177841
}

In this scenario, startTime corresponds to the start time of the first mark (mark_fetch_start), and duration is the difference in time between the two marks.

This effectively measures the time that the HTTP request takes, offering a precise and practical way to assess specific durations within your application's performance timeline.

6. `Performance.clearMarks()`

The performance.clearMarks() function removes PerformanceMark objects from the Performance Timeline. This feature provides flexibility, allowing you to either clear all existing marks or remove specific ones identified by a name.

This is particularly useful for managing and resetting performance data, especially in long-running applications or during repeated testing phases.

The function can be employed as follows:

// Remove all `PerformanceMark` objects
performance.clearMarks();

// Remove only `PerformanceMark` objects named `mark_fetch_start`
performance.clearMarks("mark_fetch_start");

7. `Performance.clearMeasures()`

This function does the same thing as clearMarks() but removes PerformanceMeasure objects instead.

8. `PerformanceResourceTiming`

The PerformanceResourceTiming API is a specialized tool for capturing detailed network timing data, allowing you to track the duration of network requests in your code.

While we've used methods like performance.now(), performance.mark(), and performance.measure() to track the duration of an HTTP request, they are more general-purpose tools.

In practice, the fetch API automatically gathers performance timings for each request, which are then recorded in the Performance Timeline as PerformanceResourceTiming objects.

import { performance } from "node:perf_hooks";

const url = "https://jsonplaceholder.typicode.com/posts/1";
const response = await fetch(url);
await response.json();
console.log(performance.getEntries());

Executing this script will result in an output resembling:

[
  PerformanceResourceTiming {
    name: 'https://jsonplaceholder.typicode.com/posts/1',
    entryType: 'resource',
    startTime: 33.411154985427856,
    duration: 1665.9909150600433,
    initiatorType: 'fetch',
    nextHopProtocol: undefined,
    workerStart: 0,
    redirectStart: 0,
    redirectEnd: 0,
    fetchStart: 33.411154985427856,
    domainLookupStart: undefined,
    domainLookupEnd: undefined,
    connectStart: undefined,
    connectEnd: undefined,
    secureConnectionStart: undefined,
    requestStart: 0,
    responseStart: 0,
    responseEnd: 1699.4020700454712,
    transferSize: 300,
    encodedBodySize: 0,
    decodedBodySize: 0
  }
]

This PerformanceResourceTiming object encapsulates
several measurements for the HTTP request. Key attributes include:

startTime, fetchStart: The high resolution timestamp marking the commencement of the resource fetch.
responseEnd: The high resolution timestamp right after Node.js receives the last byte of the resource (or just before the transport connection closes, whichever occurs first).
duration: The difference between responseEnd and startTime.
transferSize: The total size of the fetched resource, including both response headers and body, measured in octets (commonly the same as bytes).

It's important to note that this data gets recorded in the timeline only when the response is actually used. Omitting the await response.json() line, for instance, would result in an empty array.

Finally, let's take a quick look at how to manage resource buffer sizes.

Managing Resource Buffer Sizes in Node

The Performance Timeline has a default capacity limit for PerformanceResourceTiming objects, set at 250. To adjust this limit, you can utilize the setResourceTimingBufferSize() method:

performance.setResourceTimingBufferSize(500);

This command increases the buffer size, allowing up to 500 PerformanceResourceTiming objects to be stored simultaneously in the Performance Timeline.

If you need to clear all the existing PerformanceResourceTiming objects from the timeline, the clearResourceTimings() method comes in handy:

performance.clearResourceTimings();

You can also listen for the resourcetimingbufferfull event to take actions when the performance resource timing buffer is full. For example, you could increase the buffer capacity or clear the buffer so that new entries can be added:

performance.addEventListener("resourcetimingbufferfull", (event) => {
  if (performance.getEntriesByType("resource").length < 1000) {
    performance.setResourceTimingBufferSize(1000);
  } else {
    performance.clearResourceTimings();
  }
});

And that's it for now!

Up Next: Practical Uses of Node.js Performance APIs

In this blog post, we focused on examining the most important Node.js Performance APIs and their various uses.

In the next and final part of this series, we'll dive into practical implementations of these APIs. I'll demonstrate their real-world value to optimize and resolve performance issues in your Node.js applications.

Stay tuned, and happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Dealing with CPU-bound Tasks in Node.js

Damilola Olatunji — Wed, 31 Jan 2024 11:30:18 +0000

Welcome to part two of our series on profiling and optimizing CPU-bound tasks in Node.js! In the first installment, we discussed the complexities of handling CPU-bound tasks in Node.js, shedding light on their impact on runtime performance and exploring various profiling techniques.

Once you've used profiling to figure out where the bottleneck in your application is, the next step is to choose the right optimization strategy to obtain an acceptable level of performance for your use case.

In this second and final part of our series, we'll explore a few strategies you can adopt to improve the performance of CPU-bound tasks in Node.js. We'll also briefly discuss how to continuously monitor your application in production to maintain its efficiency and responsiveness over time.

Let's get started!

1. Using Worker Threads in Node.js

Since Node.js v10.5.0, using worker threads has been the recommended approach for improving the performance of CPU-bound tasks. Worker threads allow you to perform CPU-bound tasks concurrently, leveraging multiple CPU cores within a single Node.js process.

Each worker thread runs in its isolated context, including its own V8 instance, memory space, and resources. This isolation prevents shared data issues and allows for safer parallel execution.

While worker threads have isolated memory spaces, they can communicate and share data with the main thread or other workers using inter-thread communication mechanisms like postMessage() and onmessage events.

Improve CPU-bound Task Performance with Worker Threads

To see how worker threads can help with improving the performance of CPU-bound tasks, examine the code in the src/worker.js file:

// src/worker.js
import { parentPort, workerData } from "node:worker_threads";
import { calcFiboRecursive } from "./fibonacci.js";

const result = calcFiboRecursive(workerData);
parentPort.postMessage(result);

This file contains code that will be executed in a separate worker thread. The parentPort object is a reference to the communication port between the current worker thread and its parent thread, and it allows bidirectional communication between both threads. Here, once the Fibonacci number is computed, the result is sent to the parent thread through the postMessage() method.

Using `workerData`

The workerData property, on the other hand, allows you to pass any JavaScript value to the worker thread on creation. In this case, the workerData is the Fibonacci number that will be computed.

Return to the server.js file and examine the /fibonacci-worker-thread/:n route:

// src/server.js
import { Worker } from 'node:worker_threads';

. . .

fastify.get('/fibonacci-worker-thread/:n', (request, reply) => {
  const n = parseInt(request.params.n, 10);

  const worker = new Worker(path.join(__dirname, 'worker.js'), {
    workerData: n,
  });

  worker.once('message', (result) => {
    reply.send({ result });
  });

  worker.on('error', (err) => {
    throw err;
  });
});

The Worker class represents an independent JavaScript execution thread. To create a new worker, you must pass the path to the main script of the worker (src/worker.js). Optionally, you can also pass a value to the worker thread through the workerData property. The value will be cloned and made available to the worker script.

Once you've created a worker thread, you must listen for the message event on the worker so that you can act on messages sent from the worker script (using postMessage()). In this case, the expected message is the computation result from the calcFiboRecursive() function.

Uncaught errors from worker threads can also be handled by listening for the error event and handling the error accordingly. In Fastify, uncaught errors in routes are automatically logged, and a 500 response is sent to the client.

The Effect Of Node Worker Threads

Let's see the effect of worker threads on the Fibonacci computation by simulating traffic to the /fibonacci-worker-thread/:n route as follows:

autocannon --renderStatusCodes http://localhost:3000/fibonacci-worker-thread/30

. . .
┌──────┬───────┐
│ Code │ Count │
├──────┼───────┤
│ 200  │ 1341  │
└──────┴───────┘

Req/Bytes counts sampled once per second.
# of samples: 10

1k requests in 10.02s, 252 kB read

You will observe that the performance of the route is practically the same as with the /fibonacci-recursive/:n route. However, since the event loop is no longer being blocked, the server responsiveness should increase tremendously.

You can see this in action by repeating the following test from earlier in the tutorial:

curl http://localhost:3000/fibonacci-worker-thread/50

Then, simulate traffic to the server root while the 50th Fibonacci number is being calculated in a worker thread:

autocannon --renderStatusCodes http://localhost:3000/

. . .
┌──────┬────────┐
│ Code │ Count  │
├──────┼────────┤
│ 200  │ 435375 │
└──────┴────────┘

Req/Bytes counts sampled once per second.
# of samples: 11

435k requests in 11.01s, 84 MB read

On my test machine, the server was able to process about 435k additional requests in 10 seconds while the CPU-bound calculation was running! This is a dramatic improvement over the previous result, where no additional requests could be processed due to the event loop being blocked.

Using a Worker Pool in Your Node.js Production App

There is a lack of a performance boost in the /fibonacci-worker-thread/:n route because a new worker is created for every request. This constant creation and destruction of worker threads for short-lived tasks increases execution latency and negates the performance boost that should come with utilizing workers.

In a production setting, it's advisable to set up a worker pool containing several workers designated for executing tasks. Incoming tasks are added to a queue and assigned to an available worker that subsequently handles the task in a separate thread. After finishing a task, the worker then takes on a new one from the queue, ensuring efficient and continuous processing.

Setting Up The Workerpool Package

The easiest way to implement a worker pool is by using the
workerpool package (already installed in the demo project). Open the src/worker-pool.js file:

// src/worker-pool.js
import workerpool from "workerpool";
import { calcFiboRecursive, calcFiboMatrix } from "./fibonacci.js";

workerpool.worker({
  calcFiboRecursive,
  calcFiboMatrix,
});

The worker() method creates a new worker and registers the
calcFiboRecursive() function as a public method. You can observe how the worker is used in your application by locating the /fibonacci-worker-pool/:n route in your server.js file:

// src/server.js
import workerpool from 'workerpool';

. . .

const pool = workerpool.pool(path.join(__dirname, 'worker-pool.js'));

. . .

fastify.get('/fibonacci-worker-pool/:n', async (request, reply) => {
  const n = parseInt(request.params.n, 10);

  const result = await pool.exec('calcFiboRecursive', [n]);

  reply.send({ result });
});

The pool() method creates a worker pool and the exec() method executes a registered function accordingly. This method returns a promise so you can receive messages from the worker using async/await as demonstrated above.

Load Testing the Route

You can now load test the route to observe the impact on
performance:

autocannon --renderStatusCodes http://localhost:3000/fibonacci-worker-pool/30

You should see a significant improvement in throughput:

. . .
┌──────┬───────┐
│ Code │ Count │
├──────┼───────┤
│ 200  │ 7459  │
└──────┴───────┘

Req/Bytes counts sampled once per second.
# of samples: 10

7k requests in 10.01s, 1.4 MB read

We've made performance 4x faster when calculating the 30th Fibonacci number using a fixed worker pool (set by default to the number of available CPUs minus one) instead of a worker thread per request.

2. Using a More Efficient Algorithm

We've managed to improve the performance of the Fibonacci computation and the server's overall responsiveness through worker pools. But with higher numbers, the recursive Fibonacci algorithm is still prohibitively expensive.

When performing CPU-intensive computations, it's necessary to investigate more efficient algorithms and data structures, as these can often yield a much more significant improvement than throwing more CPU power at the problem.

In this example, we'll adopt the Matrix exponentiation algorithm for calculating Fibonacci numbers as shown below:

// src/fibonacci.js
function multiplyMatrix(matrix1, matrix2) {
  const a = matrix1[0][0];
  const b = matrix1[0][1];
  const c = matrix1[1][0];
  const d = matrix1[1][1];
  const e = matrix2[0][0];
  const f = matrix2[0][1];
  const g = matrix2[1][0];
  const h = matrix2[1][1];
  const result = [
    [a * e + b * g, a * f + b * h],
    [c * e + d * g, c * f + d * h],
  ];
  return result;
}

function power(matrix, n) {
  if (n === 1) {
    return matrix;
  }
  if (n % 2 === 0) {
    const halfPower = power(matrix, n / 2);
    return multiplyMatrix(halfPower, halfPower);
  } else {
    const halfPower = power(matrix, Math.floor(n / 2));
    const multiplied = multiplyMatrix(halfPower, halfPower);
    return multiplyMatrix(matrix, multiplied);
  }
}

function calcFiboMatrix(n) {
  if (n === 0) {
    return 0;
  }
  const baseMatrix = [
    [1, 1],
    [1, 0],
  ];
  const resultMatrix = power(baseMatrix, n - 1);
  return resultMatrix[0][0];
}

Here, the calcFiboMatrix() function calculates the nth Fibonacci number by leveraging matrix exponentiation techniques. It represents Fibonacci numbers as elements of a matrix and efficiently computes the desired number using matrix multiplication and exponentiation, yielding a much faster result for large Fibonacci numbers compared to the recursive approach.

To see the impact of this algorithm on performance, send traffic to the /fibonacci-matrix/:n route as follows:

autocannon --renderStatusCodes http://localhost:3000/fibonacci-matrix/30

. . .
┌──────┬────────┐
│ Code │ Count  │
├──────┼────────┤
│ 200  │ 478176 │
└──────┴────────┘

Req/Bytes counts sampled once per second.
# of samples: 11

478k requests in 11.01s, 89.9 MB read

Improvements in Performance

Performance improves drastically to 47.8k requests per second, nearing the throughput of the root route that does basically no work. Even when finding the 1000th Fibonacci number, the numbers drop only slightly to about 41.4k RPS.

Naturally, you might expect even greater performance if the faster algorithm is executed in a worker pool. However, it actually yields a slower comparative performance due to the overhead of creating workers and message passing:

autocannon --renderStatusCodes http://localhost:3000/fibonacci-worker-matrix/30

. . .
┌──────┬────────┐
│ Code │ Count  │
├──────┼────────┤
│ 200  │ 310678 │
└──────┴────────┘

Req/Bytes counts sampled once per second.
# of samples: 11

311k requests in 11.01s, 58.4 MB read

This result demonstrates the importance of benchmarking your solutions properly when testing performance fixes to ensure that your optimizations don't end up yielding worse performance.

Monitoring Node.js Performance in Production with AppSignal

Identifying and resolving performance issues in your Node.js applications is sure to be an ongoing process. To ensure a good experience for your users, establish a robust monitoring system to quickly detect and help you address issues before they impact your customers.

AppSignal makes proactive performance monitoring for Node.js applications simple and convenient, and you can start monitoring in only a couple of steps.

Simply sign up for a free account (you can do a 30-day free trial, no credit card required), create a new application, then copy the Push API Key under Push & Deploy in the App settings page.

In the demo project, @appsignal/nodejs is already
installed, but you may install it in your own projects like this:

npm install @appsignal/nodejs

Afterwards, create a .env file in the project root and enter the following, replacing the placeholder with the Push API Key you copied:

APPSIGNAL_PUSH_API_KEY=<your_appsignal_push_api_key>

The next step is to uncomment the appsignal.js import in the src/server.js file, which sets up the (minimal) configuration you need to get started:

// src/server.js
import "./appsignal.js";

// src/appsignal.js
import { Appsignal } from "@appsignal/nodejs";

new Appsignal({
  active: true,
  name: "Node.js App",
  pushApiKey: process.env.APPSIGNAL_PUSH_API_KEY,
});

AppSignal automatically integrates with Fastify, Express, and several other libraries and frameworks. You don't need to do any further setup to start collecting performance metrics, errors, and other relevant monitoring data.

Once you restart your application and start sending traffic to the server, you should see the metrics in your Performance
dashboard.

From here, you can monitor the performance of your application in real-time. You can even configure alerts so that you are quickly notified if something goes wrong, e.g., the throughput of your service drops below a configured threshold:

And that's it!

Wrapping Up

In this article, we covered two of the most effective techniques for faster and more responsive Node.js applications when dealing with CPU-intensive tasks:

Using worker threads
Using a more efficient algorithm

By implementing either technique, you can significantly reduce the performance impact of CPU-bound tasks, ensuring a smoother user experience.

We also emphasized the importance of staying vigilant by continuously monitoring your application's performance in a real-world environment. In this way, you can detect new bottlenecks and refine your strategies accordingly.

Happy profiling and optimizing!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

An Introduction to Profiling in Node.js

Damilola Olatunji — Wed, 13 Dec 2023 11:49:19 +0000

CPU-bound tasks can grind your Node.js applications to a standstill, frustrating users and driving them away. You must master the art of profiling your application to pinpoint bottlenecks, and implement effective strategies to resolve any
issues.

In this guide, we'll explore various techniques to help you identify and fix the root causes of your Node.js performance issues.

Let's get started!

Prerequisites

Before proceeding with the article, ensure that you have the most recent LTS of Node.js and npm installed on your computer.

We'll use autocannon to run load tests on various server endpoints, so install it globally on your machine:

npm install -g autocannon

To follow along with the code samples, clone this repository and install the dependencies accordingly:

git clone https://github.com/damilolaolatunji/nodejs-profiling && cd nodejs-profiling
npm install

Node.js Architecture: A Quick Overview

Node.js operates on an event-driven architecture, handling multiple client requests concurrently without creating separate threads for each connection. It achieves this by being non-blocking, allowing I/O operations like file operations and database queries to be processed asynchronously. When events occur, registered callbacks are executed, ensuring efficient handling of various tasks.

However, Node.js isn't suitable for CPU-bound tasks like heavy calculations or image processing. These tasks rely on the speed of a computer's CPU, and Node.js, with its single-threaded event loop, can only execute one JavaScript code at a time. As a result, CPU-bound tasks can block the main thread, causing significant performance problems, as we'll explore further in the next section.

Demonstrating a CPU-bound Task in Node.js

To illustrate a CPU-bound task, let's use the classic example of calculating a Fibonacci number from a specific position in the Fibonacci sequence.

This sequence starts with 0 and 1, where each subsequent number is the sum of the two preceding ones, following the relation F(n) = F(n−1) + F(n−2) with seed values F(0) = 0, F(1) = 1. Here are the first 20 Fibonacci numbers:

0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181

Calculating the nth Fibonacci number using a recursive algorithm is straightforward:

// src/fibonacci.js
function calcFiboRecursive(n) {
  if (n <= 1) return n;
  return calcFiboRecursive(n - 1) + calcFiboRecursive(n - 2);
}

However, this algorithm's time complexity is O(2^n), indicating exponential growth for the input size (n) (meaning that as n increases, the algorithm becomes significantly slower).

Bear in mind that there are much more efficient algorithms for calculating the Fibonacci number. This example only serves to illustrate the problem with CPU-bound tasks in Node.js.

Testing the CPU-bound Task

In the src/server.js file, there's a /fibonacci-recursive/:n route for calculating the Fibonacci number at position n:

// src/server.js
. . .

fastify.get('/fibonacci-recursive/:n', (request, reply) => {
  const n = parseInt(request.params.n, 10);

  const result = calcFiboRecursive(n);

  reply.send({ result });
});

. . .

You can test it by starting the server on port 3000:

npm start

Once the server has started, send a request to find the 30th Fibonacci number. You can prepend the time command to find out approximately how long the request takes:

time curl http://localhost:3000/fibonacci-recursive/30

You should observe the result fairly quickly (on my laptop, it took 10 milliseconds):

{"result":832040}
Executed in   10.34 millis    fish           external
   usr time    1.22 millis  235.00 micros    0.99 millis
   sys time    2.03 millis   52.00 micros    1.98 millis

When the number starts to increase, even only slightly, the response time grows by many orders of magnitude. On my machine, finding the 40th and 45th Fibonacci numbers took 810ms and 9s, respectively.

Impact on the Event Loop

Aside from the fact that the results take a progressively long time to compute, each request also completely blocks the event loop, preventing any other task from executing until its completion.

To establish baseline behavior, use autocannon to send some load to the / route. Ensure that the server isn't processing any other requests before running the command below:

autocannon --renderStatusCodes http://localhost:3000

On my machine, I observed a throughput of almost 49k requests per second:

Running 10s test @ http://localhost:3000
10 connections

┌─────────┬──────┬──────┬───────┬──────┬─────────┬─────────┬───────┐
│ Stat    │ 2.5% │ 50%  │ 97.5% │ 99%  │ Avg     │ Stdev   │ Max   │
├─────────┼──────┼──────┼───────┼──────┼─────────┼─────────┼───────┤
│ Latency │ 0 ms │ 0 ms │ 0 ms  │ 0 ms │ 0.01 ms │ 0.06 ms │ 11 ms │
└─────────┴──────┴──────┴───────┴──────┴─────────┴─────────┴───────┘
┌───────────┬─────────┬─────────┬─────────┬─────────┬──────────┬─────────┬─────────┐
│ Stat      │ 1%      │ 2.5%    │ 50%     │ 97.5%   │ Avg      │ Stdev   │ Min     │
├───────────┼─────────┼─────────┼─────────┼─────────┼──────────┼─────────┼─────────┤
│ Req/Sec   │ 41951   │ 41951   │ 49151   │ 50207   │ 48594.91 │ 2182.35 │ 41931   │
├───────────┼─────────┼─────────┼─────────┼─────────┼──────────┼─────────┼─────────┤
│ Bytes/Sec │ 8.09 MB │ 8.09 MB │ 9.49 MB │ 9.69 MB │ 9.38 MB  │ 422 kB  │ 8.09 MB │
└───────────┴─────────┴─────────┴─────────┴─────────┴──────────┴─────────┴─────────┘
┌──────┬────────┐
│ Code │ Count  │
├──────┼────────┤
│ 200  │ 534515 │
└──────┴────────┘

Req/Bytes counts sampled once per second.
# of samples: 10

535k requests in 10.01s, 103 MB read

Now, block the event loop by calculating the 50th Fibonacci number as follows. This request will take a long time to complete (about 123 seconds on my machine):

curl http://localhost:3000/fibonacci-recursive/50

While the result is computing (and the event loop is blocked), in a different terminal, use autocannon to send load to the / once again:

autocannon --renderStatusCodes http://localhost:3000

You will observe that the throughput drops dramatically to zero requests per second due to the ongoing Fibonacci computation. This clearly demonstrates how devastating blocking the event loop can be to Node.js performance.

. . .
┌──────┬───────┐
│ Code │ Count │
└──────┴───────┘

Req/Bytes counts sampled once per second.
# of samples: 10

20 requests in 10.02s, 0 B read
10 errors (10 timeouts)

Profiling your Node.js Application for Bottlenecks

When your application's performance starts to lag, pinpointing the exact cause of slowdowns can be a challenge. To effectively troubleshoot such issues, the first step is to profile your code and identify bottlenecks.

In this section, we'll explore three main approaches for profiling Node.js applications:

Using the built-in Node.js profiler
Using Chrome DevTools
Using the Inspector module for on-demand profiling in production

1. Using the Built-in Node.js Profiler

The first approach we'll consider requires no external tools or libraries. It involves using the built-in sample-based profiler built into Node.js, which is enabled through the --prof command-line option. Once the profiler is turned on, it records stacks of both JavaScript and C/C++ code into a file in the current working directory.

First, enable the profiler using the --prof command-line option when starting your Node.js server:

node --prof src/server.js

Once the server is running, simulate traffic to the /fibonacci-recursive/:n
route through autocannon as shown below:

autocannon --renderStatusCodes http://localhost:3000/fibonacci-recursive/30

On my machine, the server processed an average of 138.7 requests per second:

. . .

┌──────┬───────┐
│ Code │ Count │
├──────┼───────┤
│ 200  │ 1387  │
└──────┴───────┘

Req/Bytes counts sampled once per second.
# of samples: 10

1k requests in 10.01s, 261 kB read

The profiler records data into a file in your project directory. You will notice a new tick log file named isolate-0x<number>-v8.log. This file is not meant to be consumed by humans, but must be processed further to generate human-readable data.

To process this log data, use the built-in Node.js tick processor:

node --prof-process isolate-0x<number>-v8.log > processed.txt

This creates a new processed.txt file with human-readable profiling data in your project root. You can view its content by opening it up in your text editor. The file is broken up into several sections, each with its own table.

Let's delve into the processed data to identify bottlenecks, starting with the [Summary] section:

// processed.txt
 [Summary]:
   ticks  total  nonlib   name
   8603   84.0%   84.0%  JavaScript
    191    1.9%    1.9%  C++
     28    0.3%    0.3%  GC
      7    0.1%          Shared libraries
   1442   14.1%          Unaccounted

This summary indicates that approximately 84% of the samples occurred in JavaScript code, directing your attention to the JavaScript functions for investigation.

With this in mind, navigate to the [Javascript] section of the file to see which JavaScript functions are taking up the most time:

// processed.txt
 [JavaScript]:
   ticks  total  nonlib   name
   8542   83.4%   83.5%  JS: *calcFiboRecursive file:///home/ayo/dev/demo/nodejs-profiling/src/fibonacci.js:1:27
      9    0.1%    0.1%  JS: *resolve node:path:1095:10
      4    0.0%    0.0%  JS: *readPackageScope node:internal/modules/cjs/loader:377:26
      3    0.0%    0.0%  JS: *clearIncoming node:_http_server:948:23
      2    0.0%    0.0%  JS: ^defaultGenReqId /home/ayo/dev/demo/nodejs-profiling/node_modules/fastify/lib/reqIdGenFactory.js:23:28
. . .

In a real-world application, you might do a lot of processing in several functions to handle user requests. But here, the calcFiboRecursive() function is (predictably) where most time is spent, making it the clear target for optimization.

2. Using Chrome DevTools

A second approach to profiling your Node.js applications is to use Chrome DevTools to collect performance data. You need to start your server using the --inspect flag to get started:

node --inspect src/server.js

Once the server is running, open Google Chrome or any other Chromium-based browser, and type chrome://inspect in the address bar.

Find the inspect link for your Node.js script and click on it to bring up a new DevTools window for debugging your Node.js app. Head over to the Performance tab and click on the record button to start profiling your code.

Head back to your terminal, and run autocannon against the
/fibonacci-recursive/:n route once more:

autocannon --renderStatusCodes http://localhost:3000/fibonacci-recursive/30

Once the command finishes, return to your DevTools window and click the Stop button to finish the profiling. You will immediately observe a detailed performance profile of your program:

The Main section displays a flame chart representing main thread activity in your program. The horizontal axis represents time, while the vertical axis represents the call stack. You can zoom in to get a more detailed view:

In this view, the events on top cause the events below them, and the width of each event indicates its duration (the wider it is, the longer the event runs). The frames under parserOnHeadersComplete encompass routing logic, parameter processing, and, finally, lead to the request handler ((anonymous)). This handler calls the calcFiboRecursive() function multiple times due to its recursive nature, clearly visible in the graph.

Clicking the (anonymous) frame and switching to the Bottom-Up tab below lists the various resulting function calls and orders them according to their duration:

3. Using the Inspector Module for On-Demand Profiling in Production

The two profiling approaches above are useful ways to profile your code in a development environment. However, since performance issues are often first observed in production, it's crucial to set up on-demand profiling in a way that won't affect runtime performance.

The approach we'll discuss here combines the strengths of both methods, using built-in Node.js APIs to capture profiling data and then analyzing the data using Chrome DevTools.

The Inspector API provides the ability to interact with the V8 inspector programmatically. You can use it to collect profiling data from your application like this:

// src/inspector.js
import * as inspector from "node:inspector/promises";
import fs from "node:fs";

const session = new inspector.Session();

async function startCPUProfile() {
  try {
    session.connect();

    await session.post("Profiler.enable");
    await session.post("Profiler.start");
  } catch (err) {
    console.error(err);
  }
}

async function stopCPUProfile() {
  try {
    const { profile } = await session.post("Profiler.stop");
    fs.writeFileSync("./profile.cpuprofile", JSON.stringify(profile));
    session.disconnect();
  } catch (err) {
    console.error(err);
  }
}

process.on("SIGUSR1", startCPUProfile);
process.on("SIGUSR2", stopCPUProfile);

This file sets up an on-demand CPU profiling mechanism for the Node.js application through the following two functions:

startCPUProfile() connects to the inspector session and enables the CPU profiler by sending appropriate commands using the inspector protocol.
stopCPUProfile() stops the CPU profiler, retrieves the profiling data, and writes it to a file named profile.cpuprofile.

The program is also set up to listen for the SIGUSR1 and SIGUSR2 signals. The former triggers the collection of the CPU profile, while the latter stops CPU profiling and saves the profiling data to a file for analysis.

You can restart your server with npm start, then trigger CPU profiling by sending the SIGUSR1 signal to the process through the kill command. Ensure you replace <process_id> with the pid value found in the server startup log:

kill -SIGUSR1 <process_id>

If the above command exits successfully, it indicates that profiling has started. You can now use autocannon to send some load to the /fibonacci-recursive/:n route as before. Once that's done, send the SIGUSR2 signal to stop the profiling and write the data to a file:

kill -SIGUSR2 <process_id>

You should see a new profile.cpuprofile file in your project directory which contains the collected profiling information. To analyze the data, open Chrome DevTools and click the Load profile button in the Performance tab:

Once the file is loaded, you will see the flame graph as before. Analyze it to identify performance bottlenecks, just as described in the previous section.

With this approach, you can trigger CPU profiling on demand, in real-time, without interrupting server operations. In a production environment, consider setting up a different mechanism (e.g., an HTTP endpoint) to trigger profiling and automatically upload the profile data to a secure location for convenient retrieval and analysis.

Wrapping Up

In this article, we explored the challenges associated with managing CPU-bound tasks in Node.js and their substantial influence on runtime efficiency. You also learned several methods to profile your code and identify performance bottlenecks.

In the upcoming and concluding second part, our focus will shift to specific techniques you can employ to enhance the performance of CPU-bound tasks in Node.js.

Until next time, thanks for reading!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

What's New in Node.js 21

Damilola Olatunji — Wed, 01 Nov 2023 12:35:29 +0000

Node.js v21, the latest Node update, is now available as a stable release. It supersedes v20 in the 'Current' release line, which has been promoted to the long-term support (LTS) channel as of 24 October.

This new version stabilizes the fetch and WebStreams API, adds a built-in WebSocket client, improves support for ES modules, and brings some notable performance improvements (as well as a customary update of Node.js dependencies such as V8).

Without further ado, let's jump in and see what Node 21 has in store for us!

Stable Fetch API Status

A browser-compatible implementation of the Fetch API was introduced in Node.js in v17.5.0 through an --experimental-fetch flag, which brought the fetch, Headers, Request, and Response globals. From v18.x to v20.x, the flag was no longer required (but the Fetch API continued to be marked as experimental).

With the release of Node.js 21, the Fetch API is finally promoted to stable status. If you've hesitated to use Fetch due to its experimental nature, you can now confidently adopt it in your applications:

const res = await fetch("https://jsonplaceholder.typicode.com/todos/1");
if (res.ok) {
  const data = await res.json();
  console.log(data);
}

Web Streams API Is Stable

The Fetch API implementation is dependent on the AbortController interface (for aborting fetch requests) and a browser-compatible Web Streams API, which were both added in v15.0.0 and v16.5.0, respectively. While AbortController quickly became stable in v15.4.0, the Web Streams API has only just been stabilized in v21.

import { TextDecoderStream } from "node:stream/web";

async function streamExample() {
  const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");
  const stream = response.body;
  const textStream = stream.pipeThrough(new TextDecoderStream());

  for await (const chunk of textStream) {
    console.log(chunk);
  }
}

streamExample();

Note that the older Node.js streams API hasn't been deprecated or removed. It will co-exist with the new API, and it even provides a way to convert from a web stream and vice versa using the .fromWeb() and .toWeb() methods (both added in Node 17, although both methods still retain their experimental status).

A Built-in WebSocket Client

Node.js continues its trend of implementing standard web platform APIs with the recent addition of the --experimental-websocket flag, introducing a WebSocket
global, as standardized by WHATWG.

This latest effort complements existing web platform APIs such as the aforementioned Fetch and Web Streams APIs, AbortController APIs, the WHATWG URL parser, EventTarget, Web Crypto API, and more.

// index.js
const socket = new WebSocket("ws://localhost:8080");

socket.addEventListener("open", (event) => {
  socket.send("Hello Server!");
});

socket.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

While it's currently not recommended for production use, you can start experimenting with it right away:

node --experimental-websocket index.js

ES Modules Improvements

Node.js 21 introduces a new --experimental-default-type flag that allows you to modify the default behavior for input files not explicitly defined as ES modules or CommonJS. Prior to this update, such input was implicitly interpreted as CommonJS. With --experimental-default-type=module, you can enable a complete ES module implementation in the following scenarios:

String input provided via --eval or STDIN, if --input-type is unspecified.
Files ending in .js or with no extension, if there is no package.json or the nearest parent package.json field lacks a type field (except if in node_modules).

node --experimental-default-type=module index.js

These improvements pave the way to eventually supporting ES module syntax by default with minimal breaking changes.

Test Runner Improvements

Building on its stabilization in Node.js v20, the native test runner undergoes further enhancements in version 21.

It now supports glob expressions, allowing you to easily match multiple test files using custom glob patterns besides the predefined defaults.

node --test **/*.test.js **/*.spec.js

Module Customization Improvements

This release simplifies module customization by removing the confusing globalPreload hook in favor of the register API for sending data from the application thread to the customization hooks, and the initialize hook to establish
communication channels between threads.

llhttp v9.1.2 Strict Mode Enforcement

In the llhttp v9.1.2 update for Node.js, strict mode enforcement was introduced as the default setting, enabling previously included strict mode features for enhanced code reliability and security.

Notable changes include a mandatory \r\n presence after headers and chunks, ensuring consistent data processing, and disallowing data transmission after a message with the Connection: close header, improving protocol adherence and connection handling.

To maintain backward compatibility with older releases, you can use the --insecure-http-parser flag to disable these changes.

Performance Improvements to Key APIs

The Node.js performance team landed a few key improvements in this release:

The Streams API underwent optimizations, achieving approximately a 10% speedup by eliminating redundant checks, utilizing bitmaps, and scheduling callbacks more efficiently.
When uncorking a response, splitting chunked responses into multiple parts is avoided, which helps reduce unnecessary overhead on both the client and server side.

V8 Upgraded to v11.8

The V8 engine has been upgraded to v11.8, which brings improved performance and the following JavaScript features:

Array grouping to combine like data into groups using Object.groupBy() and Map.groupBy().
A new programmatic API (ArrayBuffer.prototype.transfer) for transferring ownership of ArrayBuffers, optimized reallocations, and fixing resizable ArrayBuffers into fixed-length ones.
WebAssembly extended-const expressions.

NPM Upgraded to v10.2.0

Node.js v21 includes npm v10.2.0, which notably introduces a new sbom command that allows you to generate a Software Bill of Materials (SBOM) for the current project. You can read more about the changes in recent NPM releases on GitHub.

Node.js 21 Miscellaneous Updates

Other features and improvements available in this release include the following:

A partial implementation of the global navigator object, allowing access to hardware concurrency information via navigator.hardwareConcurrency.
A flush option is added to the fs.writeFile() family of functions to guarantee that data is flushed to disk at the end of a successful write operation. This prevents redundant data from being read.

Should You Use Node.js v21 in Production?

You probably shouldn't use Node.js v21 in production. As an odd-numbered October release, it will only be supported for one year, unlike the April even-numbered releases (16, 18, 20, etc.), which receive long-term updates for up to three years.

Upgrading to Node.js v21

Should you wish to install or upgrade to Node.js v21, use the relevant link for your operating system and architecture on the Node.js download page.

Alternatively, a better way to manage Node.js releases on your machine is to use an environment management tool like Volta that can install and switch between multiple versions seamlessly.

After installing the Volta CLI, run the command below to install the latest version of Node.js:

volta install node@latest
success: installed and set node@21.0.0 (with npm@10.2.0) as default

Wrapping Up

Node.js v21 introduces numerous improvements in tooling, language features, standard library additions, and performance optimizations, enhancing its position as a robust JavaScript runtime and aligning it more closely with modern alternatives like Deno and Bun.

You can examine the complete list of bug fixes, new features, and other changes in the official Node.js 21 release notes.

To learn more about the Node.js community and how you can contribute, check out the project's open issues and contribution guidelines
on GitHub.

Thanks for reading!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Migrate Your Express Application to Fastify

Damilola Olatunji — Wed, 05 Jul 2023 11:46:03 +0000

Welcome to the final part of our Express to Fastify series. In the previous installments, we explored the unique features and advantages of Fastify over Express. Now, you'll put what you've learned so far into practice by migrating an existing Express application to Fastify.

You'll avoid rewriting an entire application from scratch by gradually transitioning to Fastify. After reading this article, you'll have the skills to confidently migrate your Express applications and enjoy the benefits of the Fastify framework.

Let's get started!

Prerequisites

Before proceeding with the article, ensure that you have a recent version of Node.js and npm installed on your computer. You also need to install MongoDB and ensure that it is running on port 27017.

Setting Up the Demo Project

To illustrate the process of migrating from Express to Fastify, we have prepared a demo application. This application utilizes Express, Mongoose, and Pug to create a URL Shortener app as follows:

After you submit a URL through the form, the application generates a shortened URL that can be copied and used elsewhere.

Go ahead and clone the repository to your computer using the following command:

git clone https://github.com/damilolaolatunji/node-url-shortener

Afterward, cd into the project directory and install the application dependencies with npm:

npm install

Once the process completes, rename the .env.sample file to .env and edit it as follows:

NODE_ENV=development
LOG_LEVEL=debug
PORT=3000
MONGODB_URL=mongodb://127.0.0.1:27017/url_shortener
APPSIGNAL_PUSH_API_KEY=<your_appsignal_push_api_key>

The application is configured to use AppSignal for log management and error tracking, so you can easily monitor and troubleshoot any issues that may occur. AppSignal provides real-time alerts and detailed error reports, allowing you to quickly identify and fix the root cause of errors before they become major problems.

If you want to see this in action, sign up for an AppSignal account (you can do a 30-day free trial, no credit card required), then create a new application and copy the Push API Key under Push & Deploy in the APP SETTINGS page.

Once you've done that, replace the <your_appsignal_push_api_key> placeholder in the .env file. Note that this step is not required to complete the migration to Fastify.

You can then start the development server by executing the command below:

npm run start:dev

The following output indicates that the server started successfully:

[nodemon] starting `node src/index.js`
{"level":"info","message":"Connected to MongoDB","timestamp":"2023-05-03T12:26:07.746Z"}
{"level":"info","message":"URL Shortener is running in development mode → PORT 3000","timestamp":"2023-05-03T12:26:07.753Z"}

You will also observe that your application's logs will start to appear in the logging dashboard in AppSignal:

From here, you can perform all kinds of actions to monitor and troubleshoot your application.

Now head over to http://localhost:3000 to see the application in action!

Examining the Project Structure

The URL Shortener application is composed of several files and directories as shown below:

.
├── package.json
├── package-lock.json
├── README.md
└── src
    ├── app.js
    ├── appsignal.js
    ├── config
    │   ├── config.js
    │   └── logger.js
    ├── controllers
    │   ├── root.controller.js
    │   └── url.controller.js
    ├── index.js
    ├── middleware
    │   ├── error.js
    │   ├── requestLogger.js
    │   └── validator.js
    ├── models
    │   ├── plugins
    │   │   └── toJSON.plugin.js
    │   └── url.model.js
    ├── public
    │   ├── main.js
    │   └── style.css
    ├── routes
    │   └── routes.js
    ├── schemas
    │   └── url.schema.js
    └── views
        ├── default.pug
        └── home.pug

Here's a brief explanation of the most important ones:

src/index.js: The entry point of the application.
src/app.js: Where the Express app is configured.
src/appsignal.js: Initializes AppSignal integration.
src/public/: Contains static CSS and JavaScript files.
src/views/: Contains the Pug templates for the app.
src/routes/routes.js: Configures the application routes.
src/config/: Contains configuration for the Winston logger and environment variables.
src/models/: Has the schema definitions for Mongoose.
src/controllers/: Includes the business logic for the application routes.
src/middleware/: Contains some useful middleware functions.

We'll examine most of these files' content as we migrate our application to Fastify.

In the next section, we'll install Fastify in the project and create a new Fastify application that embeds the original Express app to kickstart our incremental migration.

Migrating from Express to Fastify

As mentioned in part 2 of this series, using the @fastify/express plugin is the quickest way to get your existing Express application working with Fastify. The plugin adds full Express compatibility to Fastify so that you can easily use any Express middleware — or even an entire Express application — with your Fastify instance, and it will just work with no changes required.

Go ahead and install the fastify and @fastify/express packages into your project:

npm install fastify @fastify/express

Once they are both installed, import them at the start of your app.js file as follows:

// app.js
import Fastify from "fastify";
import fastifyExpress from "@fastify/express";

Afterward, create a new Fastify application instance near the bottom of the file and register the fastifyExpress plugin. Also, register the expressApp on the Fastify instance, then change the file export from expressApp to fastifyApp:

// app.js
. . .
expressApp.use(expressErrorHandler());
expressApp.use(errorHandler);

const fastifyApp = Fastify();

await fastifyApp.register(fastifyExpress);
fastifyApp.use(expressApp);

export default fastifyApp;

At this point, app.js exposes a Fastify application that embeds a fully-featured Express application with its own routes, middleware, and plugins.

Before testing your changes, you also need to modify your index.js file as shown below. You only need to change the part of the code that listens for connections on the configured port:

//app.js
. . .

  logger.info('Connected to MongoDB');

  const address = await app.listen({ port: config.port });
  logger.info(
    `URL Shortener is running in ${config.env} mode → PORT ${address}`
  );

. . .

With these changes in place, your application should continue working as before.

Fastify is now being used to start the server, but the entire service functionality remains in the Express application. In the next section, we'll start migrating our routes to Fastify.

Migrating Express Routes to Fastify

The Express router currently does our application routing, but we'll start migrating the routes to Fastify in this section. Open your routes/routes.js file and add the following code:

// routes/routes.js
. . .
export async function fastifyRoutes(fastify) {
}

export default router;

The fastifyRoutes function represents a new plugin context that will contain our application routes. To migrate an Express route to Fastify, you need to:

Remove the route from the express.Router instance.
Register the route on the fastify instance in the plugin function.
Update the route itself so that it conforms to the Fastify API.

Let's follow the above steps for the / route and see how far we get.

First, delete the following line of code in the routes.js file:

// routes/routes.js
router.get("/", rootController.render);

Next, register the / route in fastifyRoutes as follows:

// routes/routes.js
export async function fastifyRoutes(fastify) {
  fastify.get("/", rootController.render);
}

Afterward, open the controllers/root.controller.js and examine its content:

// controller/root.controller.js
function render(req, res) {
  res.render("home");
}

export default { render };

This route renders the src/views/home.pug file and returns the resulting HTML string to the client. In the app.js file, Express is configured to work with Pug templates through the following lines of code:

// app.js
expressApp.set("view engine", "pug");
expressApp.set("views", path.join(__dirname, "views"));

Since we've migrated our only application route that renders templates, the above lines are no longer needed and can be safely deleted. But you now need to configure Fastify to render the Pug template through the @fastify/view plugin. It decorates the Reply interface with a method that we'll then use to render the template.

Go ahead and install the plugin first:

npm install @fastify/view

Then import it into the app.js file shown below. You also need to import pug as well:

// app.js
. . .
import fastifyView from '@fastify/view';
import pug from 'pug';

Below the fastifyApp declaration, add the following lines to register the fastifyView plugin:

// app.js
. . .
const fastifyApp = Fastify();

await fastifyApp.register(fastifyView, {
  engine: {
    pug,
  },
  root: path.join(__dirname, 'views'),
  propertyName: 'render',
  viewExt: 'pug',
});
. . .

At this point, your Fastify application is now ready to work with Pug templates. You only need to register the fastifyRoutes plugin in your fastifyApp instance as shown below:

// app.js
import routes, { fastifyRoutes } from './routes/routes.js';

. . .

await fastifyApp.register(fastifyRoutes);

You can also update the rootController.render method as follows so that it conforms with Fastify's naming convention:

function render(req, reply) {
  reply.render("home");
}

export default { render };

With the above changes in place, the application should
continue working as before. The / route is handled by Fastify, while the other two routes remain routed through Express. In this manner, you can eventually migrate all your Express routes to Fastify.

Migrating the Rest of the Express Routes

In this section, we'll migrate the remaining two Express routes to Fastify. Start by updating the routes.js file as follows:

// routes/routes.js
import urlSchema from "../schemas/url.schema.js";
import urlController from "../controllers/url.controller.js";
import rootController from "../controllers/root.controller.js";

export default async function fastifyRoutes(fastify) {
  fastify.get("/", rootController.render);

  fastify.post(
    "/shorten",
    {
      schema: {
        body: urlSchema,
      },
    },
    urlController.shorten
  );

  fastify.get("/:shortID", urlController.redirect);
}

Since Fastify supports schema validation with Ajv, the validate module is no longer required on the /shorten route, and we can specify the JSON schema directly on the route. The controllers for both routes will largely remain the same, except that the res parameter is renamed to reply as before:

// controllers/url.controller.js
async function shorten(req, reply) {
  const { shortID, destination } = await Url.findOrCreate(req.body.destination);

  logger.debug(`${destination} shortened to ${shortID}`, {
    shortID,
    destination,
  });

  reply.send({ shortID, destination });
}

async function redirect(req, reply) {
  const { shortID } = req.params;

  const { destination } = await Url.findOne({ shortID });

  logger.debug(`redirecting /${shortID} to ${destination}`, {
    shortID,
    destination,
  });

  reply.redirect(destination);
}

export default { shorten, redirect };

Finally, head back to the app.js file and fix the routes import since fastifyRoutes is now the default export:

// app.js
import routes from "./routes/routes.js";

Now all our Express routes have been migrated over to Fastify. You can safely remove these lines:

// app.js
expressApp.use(express.json());
expressApp.use(express.urlencoded({ extended: true }));

. . .
expressApp.use(routes);

Then replace the reference to fastifyRoutes with routes as shown below:

// app.js
await fastifyApp.register(routes);

At this stage, you can test the application once again to confirm that it works just fine as before.

We've now successfully moved all our routes to Fastify without much trouble. In the next section, we will shift our handling of static files from Express to Fastify.

Serving Static Files with Fastify

At the moment, the static JavaScript and CSS files (located in /src/public) are being handled by the express.static middleware, according to this line in app.js:

// app.js
expressApp.use("/static", express.static(path.join(__dirname, "public")));

We can replace this middleware with the @fastify/static plugin, which you can install through the command below:

npm install @fastify/static

Once installed, import it into the file and register it on the fastifyApp instance:

// app.js
import fastifyStatic from '@fastify/static';

. . .

await fastifyApp.register(fastifyStatic, {
  root: path.join(__dirname, 'public'),
  prefix: '/static/',
});

Then remove the reference to express.static, and everything should keep working the same as before (except that Fastify now handles serving static files).

Replacing Express Middleware with Fastify Plugins

We've almost completed the migration to Fastify, but we still have some Express bits to replace before removing the @fastify/express compatibility layer. In this section, we'll replace the following middleware with the corresponding Fastify alternatives:

Install the plugins through the command below:

npm install @fastify/helmet @fastify/cors @fastify/compress

In your app.js file, delete the following lines:

// app.js
import helmet from 'helmet';
import cors from 'cors';
import compression from 'compression';

. . .

expressApp.use(helmet());
expressApp.use(cors());
expressApp.use(compression());

Then add the following lines in the appropriate location:

// app.js
. . .
import fastifyCors from '@fastify/cors';
import fastifyHelmet from '@fastify/helmet';
import fastifyCompress from '@fastify/compress';

. . .

await fastifyApp.register(fastifyCors);
await fastifyApp.register(fastifyHelmet);
await fastifyApp.register(fastifyCompress);
. . .

You can confirm that these work by making a request to the application root and inspecting the response headers through your browser DevTools.

At this point, we've replaced most of the Express middleware with Fastify plugins without affecting application functionality. What if you're unable to find a Fastify alternative to your Express middleware? You can use the techniques discussed in part 2 of this series to continue using the
middleware even when the rest of the application has been migrated to Fastify.

In the next section, we'll turn our attention to the error handling middleware.

Error Handling in Fastify

In Express, error handling is done through middleware functions added to an application's middleware stack. These functions have an additional err parameter denoting the error being handled, and they are called when an error occurs anywhere in the middleware stack or is thrown in a route handler. The error handler for our Express app is located in middleware/error.js:

// middleware/error.js
import { ValidationError } from "express-json-validator-middleware";
import logger from "../config/logger.js";

const errorHandler = (err, req, res, next) => {
  let statusCode = 500;
  let message = "internal server error";

  if (err instanceof ValidationError) {
    statusCode = 400;
    message = "validation error";
  } else {
    logger.error(err);
  }

  const response = {
    code: statusCode,
    message,
  };

  res.status(statusCode).send(response);
};

export default errorHandler;

We also install and import the express-async-errors package so that async errors are caught by this middleware instead of crashing the program.

Finally, we use AppSignal's expressErrorHandler middleware to automatically track unexpected errors:

// app.js
. . .
import 'express-async-errors';
import { expressErrorHandler } from '@appsignal/nodejs';
import errorHandler from './middleware/error.js';

. . .

expressApp.use(expressErrorHandler());
expressApp.use(errorHandler);

Let's begin migrating our error handling to Fastify by removing the above lines in the app.js file. By default, Fastify automatically catches errors from both synchronous and asynchronous routes, so no plugin replacement for express-async-errors is needed. You can customize the default error-handling behavior in Fastify by providing a custom error handler through the setErrorHandler() method on a Fastify instance. The provided handler needs to have the following signature:

function (error, request, reply) {}

Let's modify our existing Express error handler middleware so that it can handle Fastify errors instead:

// middleware/error.js
import logger from "../config/logger.js";
import { sendError } from "@appsignal/nodejs";

function errorHandler(err, req, reply) {
  let statusCode = 500;
  let message = "internal server error";

  if (err.code === "FST_ERR_VALIDATION") {
    statusCode = 400;
    message = "validation error";
    logger.info(err);
  } else {
    sendError(err);
    logger.error(err);
  }

  const response = {
    code: statusCode,
    message,
  };

  reply.code(statusCode).send(response);
}

export default errorHandler;

The code remains mostly the same, except that the function signature has been modified, and schema validation errors are now detected differently. Also, the sendError() method replaces expressErrorHandler as the way to track unexpected application errors in AppSignal.

You may now set this function as the error handler for your routes using the setErrorHandler() method:

// routes/routes.js
. . .
import errorHandler from '../middleware/error.js';

export default async function fastifyRoutes(fastify) {
  . . .

  fastify.setErrorHandler(errorHandler);
}

At this point, any error that occurs in your routes will be caught and processed by the custom errorHandler you provided. They'll also be tracked in AppSignal so that you can be notified quickly of any issues that occur in your Node.js application.

You can learn more about error handling in Fastify's documentation and on AppSignal's error tracking page.

Replacing Winston Logging with Pino

Our Express application uses Winston and Morgan for logging HTTP requests.

Fastify comes with Pino by default, but logging must be enabled for it to work:

// app.js
const fastifyApp = Fastify({
  logger: true,
});

When Fastify logging is enabled, you'll notice that Pino logs appear alongside Winston logs when requests are sent to the server:

{"level":30,"time":1683531253228,"pid":782352,"hostname":"fedora","reqId":"req-2","res":{"statusCode":304},"responseTime":6.965402990579605,"msg":"request completed"}
{"level":30,"time":1683531253229,"pid":782352,"hostname":"fedora","reqId":"req-3","res":{"statusCode":304},"responseTime":4.585820972919464,"msg":"request completed"}
{"content_length":"0","level":"info","message":"GET /static/main.js 304 0 - 2.775 ms","method":"GET","path":"/static/main.js","response_time_ms":"2.775","status_code":304,"timestamp":"2023-05-08T07:34:13.229Z","user_agent":"Mozilla/5.0 (X11; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/113.0"}

At this point, you can remove the requestLogger from the Express application so that only Fastify logs remain. Go ahead and delete the following lines of code from your app.js file:

// app.js
import requestLogger from "./middleware/requestLogger.js";

expressApp.use(requestLogger);

At this stage, we've completely migrated the Express application over to Fastify so you can remove the express and @fastify/express packages as well:

// app.js

import express from 'express';
import fastifyExpress from '@fastify/express';
. . .

const expressApp = express();

. . .
await fastifyApp.register(fastifyExpress);
fastifyApp.use(expressApp);

Head to your config/logger.js file, and replace winston with pino as shown below:

// config/logger.js
import pino from "pino";
import config from "./config.js";

const logger = pino({
  level: config.logLevel,
  formatters: {
    bindings: (bindings) => {
      return { pid: bindings.pid, host: bindings.hostname };
    },

    level: (label) => {
      return { level: label };
    },
  },
  timestamp: pino.stdTimeFunctions.isoTime,
});

export default logger;

Afterward, replace Fastify's default logger instance with the custom Pino logger:

// app.js
import logger from './config/logger.js';

. . .

const fastifyApp = Fastify({
  logger: logger,
});

At this point, all application logs are now produced through the same Pino instance, so the log formatting should be consistent:

{"level":"info","time":"2023-05-08T08:09:43.047Z","pid":920874,"host":"fedora","reqId":"req-1","req":{"method":"POST","url":"/shorten","hostname":"localhost:3000","remoteAddress":"127.0.0.1","remotePort":60582},"msg":"incoming request"}
{"level":"debug","time":"2023-05-08T08:09:43.058Z","pid":920874,"host":"fedora","msg":"https://github.com/nvim-telescope/telescope.nvim#themes shortened to mB5Ke86"}
{"level":"info","time":"2023-05-08T08:09:43.060Z","pid":920874,"host":"fedora","reqId":"req-1","res":{"statusCode":200},"responseTime":12.570792019367218,"msg":"request completed"}

Note that Fastify makes its logger available on the Server and Request types so you can access it directly without importing from config/logger.js. For example:

// controllers/url.controller.js
import Url from "../models/url.model.js";

async function shorten(req, reply) {
  const { shortID, destination } = await Url.findOrCreate(req.body.destination);

  req.log.debug(`${destination} shortened to ${shortID}`);

  reply.send({ shortID, destination });
}

async function redirect(req, reply) {
  const { shortID } = req.params;

  const { destination } = await Url.findOne({ shortID });

  req.log.debug(`redirecting /${shortID} to ${destination}`);

  reply.redirect(destination);
}

export default { shorten, redirect };

Learn more about logging in Fastify and how to customize the Pino logger.

Testing Your Application

We've successfully completed our migration from Express to Fastify! You may now remove all the Express-related packages from your project through the command below:

npm uninstall express body-parser express-async-errors helmet winston cors @fastify/express express-json-validator-middleware ajv-formats compression morgan

You can also remove some of the files that are no longer needed:

rm src/middleware/validator.js src/middleware/requestLogger.js

Afterward, ensure you thoroughly test your application to confirm that it's working as expected, ideally through automated tests that you've previously set up. However, since our application is small and we don't have any automated tests, manual testing will suffice:

Wrapping Up

Thank you for following along with this series on migrating from Express to Fastify. We've covered a lot of ground, and I hope you found it helpful in deciding whether to switch to Fastify and how to approach the migration process.

Fastify offers many additional features that we couldn't cover in this series, so check out the Fastify official documentation to learn more. Also, you can find all the code samples we used in this GitHub repository.

I hope this series has equipped you with the knowledge and skills to start building performant and scalable web applications with Fastify. If you have any questions or feedback, please don't hesitate to reach out.

Until next time, happy coding!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Advanced Fastify: Hooks, Middleware, and Decorators

Damilola Olatunji — Wed, 31 May 2023 12:00:03 +0000

In the first article of this series, we introduced Fastify and compared it to Express, highlighting the benefits of switching to Fastify for high-performance web applications. We also explored Fastify's plugin system in detail, showing you how to extend and customize your web applications with reusable modules.

In this part, we'll dive deeper into some of Fastify's more advanced concepts. Specifically, we'll demonstrate how to use hooks, middleware, decorators, and validation to build more robust web applications. We'll also briefly touch on some viable strategies for migrating an existing Express application to Fastify.

Let's get started!

Hooks and Middleware in Fastify

Hooks in Fastify allow you to listen for specific events in your application's lifecycle and perform specific tasks when those events occur. Hooks are analogous to Express-style middleware functions but are more performant, allowing you to perform tasks such as authentication, logging, routing, data parsing, error handling, and more. There are two types of hooks in Fastify: request/reply hooks and application hooks.

Request/Reply Hooks in Fastify

Request/reply hooks are executed during a server's request/reply cycle, allowing you to perform various tasks before or after an incoming request or outgoing response is processed. These hooks can be applied to all routes or a selection of routes. They are typically used to implement features such as:

Access control
Data validation
Request logging

And more.

Examples of request/reply hooks include preRequest, onSend, onTimeout, and others.

Here's an example that uses the onSend hook to add a Server header to all responses sent from a server:

fastify.addHook("onSend", (request, reply, payload, done) => {
  reply.headers({
    Server: "fastify",
  });

  done();
});

The request and reply objects should be familiar to you by now, and the payload parameter represents the response body. You can modify the response payload here or clear it altogether by setting it to null in the hook function. Finally, the done() callback should be executed to signify the end of the hook so that the request/reply lifecycle continues. It can take up to two arguments: an error (if any), or null, and the updated payload.

With the above code in place, each response will now contain the specified headers:

curl -I http://localhost:3000

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8
server: fastify
content-length: 12
Date: Sun, 12 Feb 2023 18:23:40 GMT
Connection: keep-alive
Keep-Alive: timeout=72

If you want to implement hooks for a subset of routes, you need to create a new encapsulation context and then register the hook on the fastify instance in the plugin. For example, you can create another onSend hook in the health plugin we demonstrated earlier in this tutorial:

// plugin.js
function health(fastify, options, next) {
  fastify.get("/health", (request, reply) => {
    reply.send({ status: "up" });
  });

  fastify.addHook("onSend", (request, reply, payload, done) => {
    const newPlayload = payload.replace("up", "down");
    reply.headers({
      "Cache-Control": "no-store",
      Server: "nodejs",
    });

    done(null, newPlayload);
  });

  next();
}

export default health;

This time, the onSend hook is used to modify the response body for all the routes in the plugin context (just /health, in this case) by changing up to down, and it also overrides the Server response header from the parent context while adding a new Cache-Control header. Hence, requests to the /health route will now produce the following response:

curl -i http://localhost:3000/health

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
cache-control: no-store
server: nodejs
content-length: 17
Date: Sun, 12 Feb 2023 18:54:21 GMT
Connection: keep-alive
Keep-Alive: timeout=72

{"status":"down"}⏎

Note that the onSend hook in the health context will run after all shared onSend hooks. If you want to register a hook on a specific route instead of all the routes in the plugin context, you can add it to the route options as shown below:

function health(fastify, options, next) {
  fastify.get(
    "/health",
    {
      onSend: function (request, reply, payload, done) {
        const newPlayload = payload.replace("up", "down");
        reply.headers({
          "Cache-Control": "no-store",
          Server: "nodejs",
        });

        done(null, newPlayload);
      },
    },
    (request, reply) => {
      reply.send({ status: "up" });
    }
  );

  fastify.get("/health/alwaysUp", (request, reply) => {
    reply.send({ status: "up" });
  });

  next();
}

export default health;

The onSend hook has been moved to the route options for the /health route, so it only affects the request/response cycle for this route. You can observe the difference by making requests to /health and /health/alwaysUp as shown below. Even though they are in the same plugin context with identical handlers, the content of their responses is different.

GET /health:

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
server: nodejs
cache-control: no-store
content-length: 17
Date: Sun, 12 Feb 2023 19:08:37 GMT
Connection: keep-alive
Keep-Alive: timeout=72

{"status":"down"}

GET /health/alwaysUp:

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
server: fastify
content-length: 15
Date: Sun, 12 Feb 2023 19:09:18 GMT
Connection: keep-alive
Keep-Alive: timeout=72

{"status":"up"}

Fastify Application Hooks

Application hooks, on the other hand, are executed outside of the request/reply lifecycle. They are executed upon events emitted by the Fastify instance and can be used to carry out general server or plugin tasks, such as:

Connecting to databases and other resources
Loading or unloading configuration
Closing connections
Persisting data
Flushing logs

And others.

Here's an example that simulates a graceful shutdown using Fastify's onClose application hook. Such a setup is ideal if you are deploying an update or your server needs to restart for other reasons.

fastify.addHook("onClose", (instance, done) => {
  instance.log.info("Server is shutting down...");
  // Perform any necessary cleanup tasks here
  done();
});

process.on("SIGINT", () => {
  fastify.close(() => {
    fastify.log.info("Server has been shut down");
    process.exit(0);
  });
});

In this example, the onClose hook is registered on the server's root context, and the callback is executed before the server is shut down. The hook function has access to the current Fastify instance and a done callback, which should be called when the hook is finished.

In addition, the process.on() function listens for the SIGINT signal, which is sent to the process when you press CTRL+C or the system shuts down. When the signal is received, the fastify.close() function is called to shut down the server, and a record of the server closure is logged to the console.

After adding the above code to your program, start the server and press Ctrl-C to shut down the process. You will observe the following logs in the console:

{"level":30,"time":1676240333903,"pid":615734,"hostname":"fedora","msg":"Server is shutting down..."}
{"level":30,"time":1676240333903,"pid":615734,"hostname":"fedora","msg":"Server has been shut down"}

Middleware in Fastify

Fastify also supports Express-style middleware but it requires you to install an external plugin such as @fastify/express or @fastify/middie. This eases migration from Express to Fastify, but it should not be used in greenfield projects in favor of hooks. Note that in many cases, you can find a native Fastify plugin that provides the same functionality as Express middleware.

The example below demonstrates how to use a standard Express middleware such as cookie-parser in Fastify, but you should prefer native alternatives — such as @fastify/cookie — where possible, since they are better optimized for use in Fastify.

import Fastify from "fastify";
import middie from "@fastify/middie";
import cookieParser from "cookie-parser";

const fastify = Fastify({
  logger: true,
});

await fastify.register(middie);

fastify.use(cookieParser());

fastify.get("/", function (request, reply) {
  console.log("Cookies: ", request.raw.cookies);
  reply.send("Hello world!");
});

const port = process.env.PORT || 3000;

fastify.listen({ port }, function (err, address) {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }

  fastify.log.info(`Fastify is listening on port: ${address}`);
});

Once the @fastify/middie plugin is imported and registered, you can begin to use Express middleware via the use() method provided on the Fastify instance, and it should just work as shown above. Note that every single middleware applied in this manner will be executed on the onRequest hook phase.

Decorators in Fastify

Decorators are a feature that allow you to customize core objects with any type of JavaScript property, such as functions, objects, or any primitive type. For example, you can use decorators to store custom data or register a new method in the Fastify, Request, or Reply objects through the decorate(), decorateRequest(), and decorateReply() methods, respectively.

This example demonstrates using Fastify's decorators to add
functionality to a web application:

import Fastify from 'fastify';
import fastifyCookie from '@fastify/cookie';

const fastify = Fastify({
  logger: true,
});

await fastify.register(fastifyCookie, {
  secret: 'secret',
});

fastify.decorate('authorize', authorize);
fastify.decorate('getUser', getUser);
fastify.decorateRequest('user', null);

async function getUser(token) {
  // imagine the token is used to retrieve a user
  return {
    id: 1234,
    name: 'John Doe',
    email: 'john@example.com',
  };
}

async function authorize(request, reply) {
  const { user_token } = request.cookies;
  if (!user_token) {
    throw new Error('unauthorized: missing session cookie');
  }

  const cookie = request.unsignCookie(user_token);
  if (!cookie.valid) {
    throw new Error('unauthorized: invalid cookie signature');
  }

  let user;
  try {
    user = await fastify.getUser(cookie.value);
  } catch (err) {
    request.log.warn(err);
    throw err;
  }

  request.user = user;
}

fastify.get('/', async function (request, reply) {
  await this.authorize(request, reply);

  reply.send(`Hello ${request.user.name}!`);
});

. . .

The above snippet of code decorates two functions on the fastify instance. The first one is getUser() — it takes a token as a parameter and returns a user object (hardcoded in this example).

The authorize() function is defined next. It checks whether the user_token cookie is present in the request and validates it. If the cookie is invalid or missing, an error is thrown. Otherwise, the cookie value is used to retrieve the corresponding user with the getUser() function, and the result is stored in a user property on the request object. If an error occurs while retrieving the user, the error is logged and re-thrown.

While you can add any property to Fastify, Request, or Reply objects, you need to declare them in advance with decorators. This helps the underlying JavaScript engine to optimize handling of these objects.

curl --cookie "user_token=yes.Y7pzW5FUVuoPD5yXLV8joDdR35gNiZJzITWeURHF5Tg" http://127.0.0.1:3000/

Hello John Doe!

Data Validation in Fastify

Data validation is an essential feature of any web application that relies on client data, as it helps to prevent security vulnerabilities caused by malicious payloads and improves the reliability and robustness of an application.

Fastify uses JSON schema to define the validation rules for each route's input payload, which includes the request body, query string, parameters, and headers. The JSON schema is a standard format for defining the structure and constraints of JSON data, and Fastify uses Ajv, one of the fastest and most efficient JSON schema validators available.

To use JSON validation in Fastify, you need to define a schema for each route that expects a payload. You can specify the schema using the standard JSON schema format or the Fastify JSON schema format, which is a more concise and expressive way of expressing the schema.

Here's an example of how to define a JSON schema for a route in Fastify:

const bodySchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    age: { type: "number" },
    email: { type: "string", format: "email" },
  },
  required: ["name", "email"],
};

fastify.post(
  "/users",
  {
    schema: {
      body: bodySchema,
    },
  },
  async (request, reply) => {
    const { name, age, email } = request.body;
    reply.send({
      name,
      age,
      email,
    });
  }
);

In this example, we define a schema that expects an object with three properties: name, age, and email. The name property should be a string, the age property should be a number, and the email property should be a string in email format. We also specify that name and email are required properties.

When a client sends a POST request to /users with an invalid payload, Fastify automatically returns a '400 Bad Request' response with an error message indicating which property failed the validation. However, if the payload adheres to the schema, the route handler function will be executed with the parsed payload as request.body.

Here's an example of a request with an invalid payload (the email key is in the wrong format):

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"name":"John","age": 44,"email":"john@example"}' \
  http://localhost:3000/users

And here's the response produced by Fastify:

{"statusCode":400,"error":"Bad Request","message":"body/email must match format \"email\""}⏎

See the docs to learn more about validation in Fastify and how to customize its behavior to suit your needs.

Planning an Incremental Migration from Express to Fastify

Incremental migration is an excellent strategy for those who want to switch to a new framework but cannot afford to make the change all at once. By adopting an incremental approach, you can gradually introduce Fastify into your project while still using Express, giving you time to make any necessary changes and ensure a smooth transition.

The first step is to identify the parts of your project that would benefit most from Fastify's features, such as its built-in support for validation and logging, and improved performance over Express. Once you have identified those areas, you can introduce Fastify alongside your existing Express code.

This might involve setting up a separate server instance that handles certain routes or endpoints using Fastify while still using Express for the rest of an application. But you'll probably find it easier to use the @fastify/express plugin to add full Express compatibility to Fastify so that you can use Express middleware and applications as if they are Fastify plugins.

To use the @fastify/express plugin, you can install it via npm and register it with your Fastify instance:

import Fastify from "fastify";
import expressPlugin from "@fastify/express";

const fastify = Fastify({
  logger: true,
});

await fastify.register(expressPlugin);

You can then use Express middleware or applications just like in an Express application. For example:

import express from "express";
const expressApp = express();

expressApp.use((req, res, next) => {
  console.log("This is an Express middleware");
  next();
});

expressApp.get("/express", (req, res) => {
  res.json({ body: "hello from express" });
});

fastify.use(expressApp);

curl http://localhost:3000/express

{ "body": "hello from express" }

As you become more comfortable with Fastify, you can start to migrate more and more of your code over, eventually replacing all of your Express-specific code with Fastify. By taking the time to plan and execute a thoughtful migration strategy, you can ensure a smooth transition and ultimately end up with a more efficient, high-performing application.

Up Next: Migrate to Fastify from Express

We've covered a lot of ground in this tutorial. We hope you've gained a deeper understanding of how Fastify's novel features like hooks and decorators can help you customize and extend your applications more than Express.

In the next and final part of this series, we'll provide a practical guide for migrating to Fastify from Express. We'll cover common migration scenarios, provide tips for optimizing performance and improving security, and share some best practices along the way.

Thanks for reading, and see you next time!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

Getting Started with Fastify for Node.js

Damilola Olatunji — Fri, 05 May 2023 10:35:27 +0000

Chances are high that you've previously worked with Express, as it's been the go-to web framework for Node.js developers since its release in 2010. However, in recent years, newer web frameworks have emerged, and Express's development has slowed down significantly.

Fastify is a relatively new player on the scene, but it's quickly gaining popularity due to its speed and unique features.

If you're still using Express, you might wonder if it's worth switching to Fastify. We've created this three-part series to explore the benefits of switching from Express to Fastify, as well as the potential challenges you might encounter. It'll also provide a hands-on guide for migrating your existing Express applications to Fastify.

In this part, we'll focus on why you might consider Fastify over Express for your next Node.js project and explore some of Fastify's core concepts in detail.

So let's dive in and see what Fastify has to offer!

Prerequisites

This tutorial assumes that you have a recent version of Node.js installed on your computer, such as the latest LTS release (v18.x at the time of writing). Its code samples use top-level await and the ES module syntax instead of CommonJS. We also assume you have a basic knowledge of building Node.js-backed APIs using Express or other web frameworks.

Why Switch from Express to Fastify for Node.js?

Before delving into the inner workings of Fastify, it is important to understand why you may want to consider using it for your next Node.js project. This section covers a few of the benefits that Fastify offers when compared to Express, at the time of writing:

1. Faster Performance

Fastify was designed to be fast from the ground up and use fewer system resources, so it handles more requests per second compared to Express and other Node.js web frameworks.

Although Express is a more mature framework with a larger community and a more comprehensive ecosystem of third-party packages, it is not as optimized for performance as Fastify.

2. Plugin Architecture

Fastify boasts a powerful plugin system that can easily add custom functionality to your application. Many official plugins handle things like authentication, validation, security, database connections, serverless compatibility, and rate-limiting. There's also a growing ecosystem of third-party plugins that can be integrated into your application, and you can easily create your own plugins.

Express is extensible through middleware functions injected into the request/response processing pipeline to modify an application's behavior. Still, they are tightly coupled into the framework and less flexible or modular than Fastify's approach. Plugins in Fastify are also encapsulated by default, so you don't experience issues caused by cross-dependencies.

3. Safer by Default

Security is a critical consideration when building web applications, and Fastify provides a number of built-in security features, such as:

automatically escaping output
input validation
preventing content sniffing attacks
protecting against malicious header injection

Its plugin system also makes it easy to apply additional security measures to your application.

On the other hand, Express relies more heavily on middleware to handle security concerns. It does not have built-in validation or schema-based request handling, although several third-party packages can be utilized for this purpose.

4. Modern JavaScript Features

Fastify has built-in support for modern JavaScript features, such as async/await and Promises. It also automatically catches uncaught rejected promises that occur in route handlers, making it easier to write safe asynchronous code.

Express doesn't support async/await handlers, though you can add these with a package like express-async-errors. Note that this feature will be supported natively in Express 5 when it comes out of beta.

app.get("/", async function (request, reply) {
  var data = await getData();
  var processed = await processData(data);
  return processed;
});

5. Built-in JSON Schema Validation

In Fastify, JSON schema validation is a built-in feature that allows you to validate the payload of incoming requests before the handler function is executed. This ensures that incoming data is in the expected format and meets the required criteria for your business logic. Fastify's JSON schema validation is powered by the Ajv library, a fast and efficient JSON schema validator.

const bodySchema = {
  type: "object",
  properties: {
    first_name: { type: "string" },
    last_name: { type: "string" },
    email: { type: "string", format: "email" },
    phone: { type: "number" },
  },
  required: ["first_name", "last_name", "email"],
};

fastify.post(
  "/create-user",
  {
    schema: {
      body: bodySchema,
    },
  },
  async (request, reply) => {
    const { first_name, last_name, age, email } = request.body;
    reply.send({ first_name, last_name, age, email });
  }
);

In contrast, Express does not provide built-in support for JSON schema validation. However, you can use third-party libraries like Joi or the aforementioned Ajv package to validate JSON payloads in Express applications (this requires additional setup and configuration).

6. TypeScript Support

Fastify has excellent TypeScript support and is built with TypeScript in mind. Its type definitions are included in the package, and it supports using TypeScript to define types for route handlers, schemas, and plugins.

From v3.x, the Fastify type system heavily relies on generic properties for accurate type checking.

Express also supports TypeScript (through the @types/express package), but its support is less comprehensive than Fastify.

7. A Built-in Logger

Fastify provides a built-in logging mechanism based on Pino that allows you to capture various events in your applications. Once enabled, Fastify logs all incoming requests to the server and errors that occur while processing said requests. It also provides a convenient way to log custom messages through the log() method on the Fastify instance or the request object.

const app = require("fastify")({
  logger: true,
});

app.get("/", function (request, reply) {
  request.log.info("something happened");
  reply.send("Hello, world!");
});

Express does not provide a built-in logger. Instead, you need to use third-party logging libraries like Morgan, Pino, or Winston to log HTTP requests and responses. While these libraries are highly configurable, they require additional setup and configuration.

Fastify Offers More than Express

As you can see, Fastify offers numerous advantages over Express, making it a compelling option for building Node.js web applications. In the following sections, we will dive deeper into Fastify's core features and demonstrate how to create web servers and routes.

We will also explore how Fastify's extensibility and plugin system allows for greater flexibility in application development.

By the end, you will better understand why Fastify is a great option for building high-performance and scalable Node.js applications.

Getting Started with Fastify for Your Node.js Application

Before you can utilize Fastify in your project, you need to install it first:

npm install fastify

Once it's installed, you can import it into your project and instantiate a new Fastify server instance, as shown below:

import Fastify from "fastify";

const fastify = Fastify();

The Fastify function accepts an options object that customizes the server's behavior. For example, you can enable its built-in logging feature and specify a timeout value for incoming client requests through the snippet below:

. . .
const fastify = Fastify({
  logger: true,
  requestTimeout: 30000, // 30 seconds
});

After configuring your preferred options, you can add your first route as follows:

. . .
fastify.get('/', function (request, reply) {
  reply.send("Hello world!")
})

This route accepts GET requests made to the server root and responds with "Hello world!". You can then proceed to start the server by listening on your preferred localhost port:

. . .
const port = process.env.PORT || 3000;

fastify.listen({ port }, function (err, address) {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }

  fastify.log.info(`Fastify is listening on port: ${address}`);
});

Start the server by executing the entry file. You will observe some JSON log output in the console:

{"level":30,"time":1675958171939,"pid":391638,"hostname":"fedora","msg":"Server listening at http://127.0.0.1:3000"}
{"level":30,"time":1675958171940,"pid":391638,"hostname":"fedora","msg":"Server listening at http://[::1]:3000"}
{"level":30,"time":1675958171940,"pid":391638,"hostname":"fedora","msg":"Fastify is listening on port: http://127.0.0.1:3000"}

You can use the pino-pretty package to make your application logs easier to read in development.

After installing the package, pipe your program's output to the CLI as follows:

node server.js | pino-pretty

You'll get a colored output that looks like this:

Enabling the logger is particularly helpful as it logs all incoming requests to the server in the following manner:

curl "http://localhost:3000"

{
  "level": 30,
  "time": 1675961032671,
  "pid": 450514,
  "hostname": "fedora",
  "reqId": "req-1",
  "res": { "statusCode": 200 },
  "responseTime": 3.1204520016908646,
  "msg": "request completed"
}

Notice how you get a timestamp, request ID, response status code, and response time (in milliseconds) in the log. This is a step up from Express where you get no such functionality until you integrate Pino (or other logging frameworks) yourself.

Creating Routes in Fastify

Creating endpoints in Fastify is easy using several helper methods in the framework. The fastify.get() method (seen in the previous section) creates endpoints that accept HTTP GET requests. Similar methods also exist for HEAD, POST, PUT, DELETE, PATCH, and OPTIONS requests:

fastify.get(path, [options], handler);
fastify.head(path, [options], handler);
fastify.post(path, [options], handler);
fastify.put(path, [options], handler);
fastify.delete(path, [options], handler);
fastify.options(path, [options], handler);
fastify.patch(path, [options], handler);

If you'd like to use the same handler for all supported HTTP request methods on a specific route, you can use the fastify.all() method:

fastify.all(path, [options], handler);

As you can see from the above signatures, the options argument is optional, but you can use it to specify a myriad of configuration settings per route. See the Fastify docs for the full list of available options.

The path argument can be static (like /about or /settings/profile) or dynamic (like /article/:id, /foo*, or /:userID/repos/:projectID). URL parameters in dynamic URLs are accessible in the handler function through the request.params object:

fastify.get("/:userID/repos/:projectID", function (request, reply) {
  const { userID, projectID } = request.params;
  // rest of your code``
});

Fastify handlers have the following signature, where request represents the HTTP request received by the server, and reply represents the response from an HTTP request.

function (request, reply) {}

If the handler function for a route is asynchronous, you can send a response by returning from the function:

fastify.get("/", async function (request, reply) {
  // do some work
  return { body: true };
});

If you're using reply in an async handler, await reply or return reply to avoid race conditions:

fastify.get("/", async function (request, reply) {
  // do some work
  return reply.send({ body: true });
});

One neat aspect of Fastify routes is that they automatically catch uncaught exceptions or promise rejections. When such exceptions occur, the default error handler is executed to provide a generic '500 Internal Server Error' response.

fastify.get("/", function (request, reply) {
  throw new Error("Uncaught exception");
});

Here's the JSON response you get when you use curl to send a request to the endpoint above:

{"statusCode":500,"error":"Internal Server Error","message":"Uncaught exception"}⏎

You can modify the default error-handling behavior through the
fastify.setErrorHandler() function.

Plugins in Fastify

Fastify is designed to be extensible through plugins. Plugins are essentially self-contained, encapsulated, and reusable modules that add custom logic and behavior to a Fastify server instance. They can be used for a variety of purposes, such as integrating with a protocol, framework, database, or an API, handling authentication, and much more.

At the time of writing, there are over 250 plugins available for Fastify. Some are maintained by the core team, but the community provides most of them. When you find a plugin you'd like to use, you must install it first, then register it on the Fastify instance.

For example, let's use the @fastify/formbody plugin to add support for x-www-form-urlencoded bodies to Fastify:

npm install @fasitfy/formbody

// import the plugin
import formBody from '@fastify/formbody';

. . .

// register it on your Fastify instance
await fastify.register(formBody);

fastify.post('/form', function (request, reply) {
  reply.send(request.body);
});

. . .

With this plugin installed and registered, you'll be able to access x-www-form-urlencoded form bodies as an object. For example, the following request:

curl -d "param1=value1&param2=value2" -X POST 'http://localhost:3000/form'

Should produce the output below:

{"param1":"value1","param2":"value2"}⏎

You can also create a custom Fastify plugin quite easily. All you need to do is export a function that has the following signature:

function (fastify, opts, next) {}

The first parameter is the Fastify instance that the plugin is being registered to, the second is an options object, and the third is a callback function that must be called when the plugin is ready.

Below is an example of a simple Fastify plugin that adds a new health check route to the server:

// plugin.js
function health(fastify, options, done) {
  fastify.get("/health", (request, reply) => {
    reply.send({ status: "up" });
  });

  done();
}

export default health;

// server.js
import health from "./plugin.js";

const fastify = Fastify({ logger: true });
await fastify.register(health);

At this point, requests to http://localhost:3000/health will yield the following response:

{ "status": "up" }

How Plugins in Fastify Work

Plugins in Fastify create a new encapsulation context isolated from all other contexts in the application by default. This allows you to modify the fastify instance within the plugin's context without affecting the state of any other contexts. There is always only one root context in a Fastify application, but you can have as many child contexts as you want.

Here's a code snippet illustrating how contexts work in Fastify:

// `root` is the root context.
const root = Fastify({
  logger: true,
});

root.register(function pluginA(contextA, opts, done) {
  // `contextA` is a child of the `root` context.
  contextA.register(function pluginB(contextB, opts, done) {
    // `contextB` is a child of `contextA`
    done();
  });

  done();
});

root.register(function pluginC(contextC, opts, done) {
  // `contextC` is a child of the `root` context.
  contextC.register(function pluginD(contextD, opts, done) {
    // `contextD` is a child of `contextC`
    done();
  });

  done();
});

The snippet above describes a Fastify application with five different encapsulation contexts. root is the parent of two contexts (contextA and contextC), and each one has its own child context (contextB and contextD, respectively).

Every context (or plugin) in Fastify has its own state, which includes decorators, hooks, routes, or plugins. While child contexts can access the state of the parent, the reverse is not true (at least by default).

Here's an example that uses decorators (we'll further discuss decorators in part two of this series) to attach some custom properties to each context:

const root = Fastify({
  logger: true,
});

root.decorate("answerToLifeTheUniverseAndEverything", 42);

await root.register(async function pluginA(contextA, opts, done) {
  contextA.decorate("speedOfLight", "299,792,458 m/s");

  console.log(
    "contextA -> root =",
    contextA.answerToLifeTheUniverseAndEverything
  );
  await contextA.register(function pluginB(contextB, opts, done) {
    contextB.decorate("someAPIKey", "3493203890");

    console.log(
      "contextB -> root =",
      contextB.answerToLifeTheUniverseAndEverything
    );
    console.log("contextB -> contextA =", contextB.speedOfLight);
    done();
  });

  console.log("contextA -> contextB =", contextA.someAPIKey);

  done();
});

console.log("root -> contextA =", root.speedOfLight);
console.log("root -> contextB =", root.someAPIKey);

In the snippet above, the root context is decorated with the custom property answerToLifeTheUniverseAndEverything, which yields 42. Similarly, contextA and contextB are decorated with their own custom properties. When you execute the code, you will observe the following results in the console:

contextA -> root = 42
contextB -> root = 42
contextB -> contextA = 299,792,458 m/s
contextA -> contextB = undefined
root -> contextA = undefined
root -> contextB = undefined

Notice that the root's custom property is accessible directly on the contextA and contextB objects since they are both descendants of the root context. Similarly, contextB can access the speedOfLight property added to contextA for the same reason.

However, since parents cannot access the state of their nested contexts, accessing contextA.someAPIKey, root.speedOfLight, and root.someAPIKey produces undefined.

Sharing Context in Fastify for Node.js

There is a way to break Fastify's encapsulation mechanism so that parents can also access the state of their child contexts. This is done by wrapping the plugin function with the fastify-plugin module:

// import the plugin
import fp from "fastify-plugin";

await root.register(
  // wrap the plugin function
  fp(async function pluginA(contextA, opts, done) {
    // . . .
  })
);

With this in place, you'll observe the following output:

contextA -> root = 42
contextB -> root = 42
contextB -> contextA = 299,792,458 m/s
contextA -> contextB = undefined
root -> contextA = 299,792,458 m/s
root -> contextB = undefined

Notice that the speedOfLight property decorated on contextA is now accessible in the root context. However, someAPIKey remains inaccessible because the pluginB function isn't wrapped with the fastify-plugin module.

Here's the solution if you also intend to access contextB's state in a parent context:

// import the plugin
import fp from "fastify-plugin";

await root.register(
  // wrap the plugin function
  fp(async function pluginA(contextA, opts, done) {
    // . . .

    await contextA.register(
      fp(function pluginB(contextB, opts, done) {
        // . . .
      })
    );
  })
);

contextB's state is now also accessible in all of its ancestors:

contextA -> root = 42
contextB -> root = 42
contextB -> contextA = 299,792,458 m/s
contextA -> contextB = 3493203890
root -> contextA = 299,792,458 m/s
root -> contextB = 3493203890

You'll see a more practical example of the plugin encapsulation context in the next part of this series, where we'll tackle hooks and middleware.

Coming Up Next: Hooks, Middleware, Decorators, and Validation

In this article, we introduced the Fastify web framework, exploring its convenience, speed, and low overhead, which makes it a popular choice for building highly performant and scalable web applications. We compared Fastify to Express and highlighted why you might want to consider switching.

We also discussed Fastify's extensibility and plugin system, which allow you to customize and extend its functionality.

In part two of this series, we will dive deeper into some of the more advanced concepts of Fastify, such as hooks, middleware, decorators, and validation.

Until next time, thanks for reading!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.

DEV Community: Damilola Olatunji

What's New in Ruby on Rails 8

Effortless Deployments with Kamal 2 and Thruster

Leaner Rails Deployments with Solid Adapters

SQLite is Ready for Production

A New Era for the Asset Pipeline with Propshaft

Built-In Authentication Made Simple

New Script Folder and Generator

A Slew of Active Record Improvements

Wrapping Up

Advanced Use Cases of the Node.js Native Test Runner

Setting Up and Tearing Down with Test Hooks

Mocking APIs

Mocking Async Functions

Mocking Built-in APIs

Providing Multiple Implementations

Obtaining Code Coverage Reports

Customizing Test Reports

Testing HTTP Services

Wrapping Up

Exploring the Node.js Native Test Runner

What Is Testing?

Why Was A Test Runner Added to Node.js 18+?

Prerequisites

Setting Up a Demo Program

Testing Your Node.js Code

What Happens When You Run node --test

Dealing with Test Failures

Organizing Test Cases with Subtests

Using the Describe/It Syntax

Customizing Test Runs

Running All Tests In a File

Filtering Tests by Name

Skipping Tests

Marking tests as "TODO"

Wrapping Up

What's New in Node.js 22

Watch Mode is Stable

WebSocket Global Enabled by Default

Support for Running package.json Scripts

Loading ES Modules with require()

fs Module Supports Pattern Matching

AbortSignal Performance Improvements

Enhancements to Stream highWaterMark

V8 Upgraded to v12.4

Should You Use Node.js 22 in Production?

How to Upgrade to Node.js 22

Direct Download

Node.js Version Manager (Recommended)

Wrapping Up

Measuring Node.js Performance in Production with Performance Hooks

Prerequisites

Continuous Monitoring with Performance Observer for Node

A Practical Example: Monitoring Third-Party API Integrations for Node

Setting up the Demo Repository

Tracking the API Requests

Tracking Node.js Performance Measurements with AppSignal

Getting Alerted to Performance Issues

Wrapping Up

Node.js Performance APIs: An Introduction

Prerequisites

Understanding Fundamental Node.js Performance API Concepts

1. A Monotonic Clock

2. High Resolution Time API

3. Performance Timeline

Inside the Node.js Performance API

1. PerformanceNodeTiming

2. Performance.now()

3. Performance.mark()

4. Performance.getEntries()

5. Performance.measure()

6. Performance.clearMarks()

7. Performance.clearMeasures()

8. PerformanceResourceTiming

Managing Resource Buffer Sizes in Node

Up Next: Practical Uses of Node.js Performance APIs

Dealing with CPU-bound Tasks in Node.js

1. Using Worker Threads in Node.js

Improve CPU-bound Task Performance with Worker Threads

Using workerData

What Happens When You Run `node --test`

Support for Running `package.json` Scripts

Loading ES Modules with `require()`

`fs` Module Supports Pattern Matching

`AbortSignal` Performance Improvements

Enhancements to Stream `highWaterMark`

1. `PerformanceNodeTiming`

2. `Performance.now()`

3. `Performance.mark()`

4. `Performance.getEntries()`

5. `Performance.measure()`

6. `Performance.clearMarks()`

7. `Performance.clearMeasures()`

8. `PerformanceResourceTiming`

Using `workerData`