DEV Community: Manuel Spigolon

Managing Request-Scoped Data in Fastify

Manuel Spigolon — Fri, 11 Apr 2025 15:29:16 +0000

I was looking at the Fastify plugin listand found myself asking, "What is this @fastify/request-context plugin?"

So, I checked it out, and here I am, writing a post about it to share what it is and how it can be useful for you!

What is AsyncLocalStorage?

Managing state across asynchronous operations has always been a challenge in Node.js.

Traditional methods like passing context objects through function parameters or using global variables are the easiest way to share data across functions. However, they can quickly become unmanageable, especially in large applications with deeply nested asynchronous calls, making the code difficult to test.

This is where AsyncLocalStorage,a core module introduced in Node.js 13, comes in handy.

It provides a way to store and retrieve data that persists through an asynchronous execution context.Unlike global variables, which are shared across all requests, AsyncLocalStorage allows developersto maintain request-scoped data , meaning each incoming request gets its own isolated storage.

This feature seems to overlap with Fastify's Decorators, but it's not the same. Let's see why!

How It Works

The basic idea behind AsyncLocalStorage is that it creates an execution context that is preservedthroughout asynchronous operations, even across setTimeout or database queries.

Heres a simple example with comments:

import { AsyncLocalStorage } from "async_hooks";

// Create a new instance of AsyncLocalStorage that will be unique per application
const appAsyncLocalStorage = new AsyncLocalStorage();

// Simulate an incoming request every 2 seconds
setInterval(() => {
  // Generate a random request ID that will be unique per request
  const requestId = Math.random().toString(36).substring(7);

  // Run the `reqHandler` function in the AsyncLocalStorage context
  // This creates the context and binds the `store` object to it
  const store = { requestId };
  appAsyncLocalStorage.run(store, function reqHandler() {
    logWithRequestId("Processing request...");
    setTimeout(() => logWithRequestId("Finished processing."), 3_000);
  });
}, 2_000);

// Main business logic function
// Through `appAsyncLocalStorage.getStore()`, we can access the `store` object
// that was bound to the AsyncLocalStorage context in `reqHandler`
function logWithRequestId(message) {
  const store = appAsyncLocalStorage.getStore();
  const requestId = store?.requestId || "unknown";
  console.log(`[Request ${requestId}]: ${message}`);
}

The above code snippet provides the requestId to the logWithRequestId function without passing it as a parameter!

It still requires access to the appAsyncLocalStorage instance to retrieve the store object,but with a single variable, we can access everything we need throughout the request context.

Why Is This Important?

Without AsyncLocalStorage, you would need to manually pass the requestId to every function that requires it,which can be cumbersome and error-prone.

With AsyncLocalStorage, the context is automatically preserved throughout the request lifecycle,making it much easier to track request-specific data.

Think about all the times you've had to pass a logging or config object to every function.

Or when you manually tracked the start and end of a request.

Or even when you implemented a tracing system to follow requests through multiple services.

With AsyncLocalStorage, you can forget about that spaghetti code and focus on the request context's store!

How to Use the `@fastify/request-context` Plugin

Fastify already solves multiple problems with its decorators:

It provides logging through the request.log object.
It provides configuration through the fastify.config object, thanks to the @fastify/env plugin.
It supports Diagnostic Channels to track the request lifecycle.

The @fastify/request-context plugin takes thingsfurther by offering a structured way to manage request-scoped data without the hassle of manual context management.

Quick Start

After installing the plugin, you can register it in your Fastify application.

Lets see a real-world example:

import Fastify from "fastify";
import fastifyRequestContext from "@fastify/request-context";

const app = Fastify({ logger: true });

app.register(fastifyRequestContext, {
  defaultStoreValues() {
    return {
      logicStep: [],
    };
  },
});

app.get("/", async function longHandler(req, reply) {
  const debugBusiness = req.requestContext.get("logicStep");

  // Simulate some business logic
  debugBusiness.push("Called external service 1");
  // Do something...
  debugBusiness.push("Processed external service 2");

  // Simulate an error
  throw new Error("Something went wrong 😱");
});

app.setErrorHandler(function (err, request, reply) {
  const debugBusiness = request.requestContext.get("logicStep");

  this.log.error({ err, debugBusiness }, "An error occurred");
  reply.status(500).send("Internal Server Error");
});

app.inject("/");

In this example, we have a Fastify application with a single route that simulates a complex business logic flow.

Thanks to the @fastify/request-context plugin, we can store the logicStep array in the request context and access itin every part of the application by accessing the request object.

The real power of this plugin is that you can access the logicStep array inthe error handler without passing it through function parameters.

This allows you to push trace information across the entire application and log it when an error occurs,helping you understand what happened before the failure.

Manually passing request-specific data through function arguments makes the code messy and difficult to maintain.

With this plugin, you can access context-specific data anywhere in the request lifecycle without modifying function signatures.

`@fastify/request-context` vs Decorators

Why use the @fastify/request-context plugin and AsyncLocalStorage instead of Fastify's Request and Reply decorators?

Aren't they achieving the same goal?

Not exactly.

To understand the difference, lets briefly look at how Fastify decorators work.

Fastify decorators mutate the Request and Reply prototypes, adding new properties to them.

Every time an HTTP request is received, Fastify creates new Request and Reply objects using these modified prototypes,automatically making decorators available.

Sounds great, right? But theres a catch!

If you add reference-type objects (arrays or JSON objects) to the Request or Reply object,they will be shared across all requests.

If one request modifies them, it will affect all other requests!

This can lead to unexpected behavior and hard-to-track bugs.

Due to this, the Fastify team discouraged using reference-type objects in decoratorsstarting from v5.

You can still use decorators for reference-type objects, but it becomes more complex and error-prone.

Heres an example requiring two decorators and a lazy-loading approach :

app.decorateRequest('logicStepValue', null)
app.decorateRequest('logicStep', {
  getter () {
    this.logicStepValue ??= [];
    return this.logicStepValue;
  },
})

This is where the @fastify/request-context plugin shines.

It provides a structured , safe , and isolated way to manage request-specificdata without the risk of data leakage across requests!

Summary

The @fastify/request-context plugin offers a structured, efficient way to manage request-scoped data in Fastify applications.

It simplifies code, improves maintainability, enhances logging, and makes debugging significantly easier.

By leveraging this plugin, you ensure that request-specific dataremains consistent and accessible throughout the request lifecycle without unnecessary complexity.

If you enjoyed this article, you might like "Accelerating Server-Side Development with Fastify".

Comment, share, and follow me on X/Twitter!

Announcing the Fastify Mini Course

Manuel Spigolon — Thu, 06 Mar 2025 14:35:35 +0000

Dear Backend.cafe readers, I have something special for you!If you've ever wanted to master Fastify , the lightning-fast Node.js framework, you're in for a treat.Today, Im launching Fastify Mini Course a free resource designed to help you build high-performance APIs efficiently.

🚀 Why Fastify?

If you're a backend developer, you've probably worked with the http module. But have you considered switching to Fastify?Heres why you should:

Blazing Fast : Up to 4x faster than the most popular Node.js frameworks.
Low Overhead : Optimized for performance and scalability.
Schema-Based Validation : First-class TypeScript support and JSON schema validation.
Modern Features : Built-in async/await, hooks, decorators, and powerful plugin system.

Whether you're an http pro or new to backend development, this mini-course will help you level up your skills!

📖 Whats Inside the Mini Course?

This course is bite-sized but powerful. Youll learn:

How to set up a Fastify project from scratch.
Routing, request validation, and response serialization.
Working with middleware, hooks, and decorators.
Optimizing Fastify for production-ready performance.
Real-world best practices.

The course is designed for maximum efficiency , so you can complete it in just a few hours and walk away with practical Fastify skills.You will get one email per day, each containing a short lesson and a hands-on exercise.

🎯 Who Is This For?

Developers who want to learn Fastify from scratch.
Anyone interested in improving API performance and scalability.
Engineers looking for a quick and structured way to learn Fastify.

📅 How to Get Access

It is available publicly at FastifyMiniCourse.com.

🚀 Get Ready to Build Faster APIs!

I cant wait for you to try it out! If you have any questions or feedback, lets discuss them in the comments.

Happy coding! 🎯

If you enjoyed this article, comment, share and follow me on X!

Master Node.js with the 5th Edition Cookbook

Manuel Spigolon — Mon, 11 Nov 2024 14:04:30 +0000

We are excited to announce that the Node.js Cookbook, 5th Edition is set to be released on November 15th, 2024!

This latest edition, authored by Bethany Griggs, is the ultimate guide for developers who want to master the Node.js v22 API and build scalable, high-performance applications.

The Node.js Cookbook is a trusted resource for new and experienced developers alike, packed with practical recipes and solutions to common Node.js challenges. Whether you're just starting your Node.js journey or looking to refine your skills, this book covers all the core topics, including asynchronous programming, file handling, HTTP servers, and much more.

As a special contribution, Manuel Spigolon had the pleasure of writing a chapter dedicated to the latest Fastify v5. Fastify is one of the fastest Node.js web frameworks, and in this chapter, you'll learn how to use it to build robust APIs effortlessly.

If you're eager to dive into Node.js or explore Fastify v5, you can preorder the book today at https://packt.link/0mNGV.

Dont miss it!

Resume data replication in Postgres and Node.js

Manuel Spigolon — Mon, 11 Nov 2024 14:03:59 +0000

How to resume replication from the point where the Node.js application was stopped

This article is a continuation of Real-time data Replication in Postgres and Node.js. Before reading this article, I recommend you read the previous one because it provides essential context to the points I cover.

In our previous article, we discussed how to replicate data from a Postgres database to a Node.js application in real-time using logical replication. However, if the Node.js application crashes or stops for some reason, the replication will cease, and we risk losing the data that our system produces in the meantime via another microservice or application.

In this article, I discuss how to resume replication from the last point where the Node.js application stopped
by using a persistent replication slot in the Postgres database. This ensures that our application doesn't lose events produced by other microservices or applications during downtime.

Creating a replication slot

To resume replication, we need to create a replication slot in the Postgres database. A replication slot is a logical entity that keeps track of changes happening in the database and sends them to the subscriber. The postgres package we used in the previous article automatically created a replication slot for us, but it was not persistent, it was a TEMPORARY replication slot that was removed when the subscriber disconnected.

Since we want to resume replication from the last point where the Node.js application was stopped, we need to create a persistent replication slot. Let's create one in a new setup-replication.js file:

import pg from 'pg'
const { Client } = pg

const client = new Client({ user: 'postgres', password: 'foopsw' })
await client.connect()

await createReplicationSlotIfNotExists('foo_slot')

await client.end()

async function createReplicationSlotIfNotExists (slotName) {
  const slots = await client.query('SELECT * FROM pg_replication_slots WHERE slot_name = $1', [slotName])

  if (!slots.rows.length) {
    const newSlot = await client.query("SELECT * FROM pg_create_logical_replication_slot($1, 'pgoutput')", [slotName])
    console.log('Created replication slot', newSlot.rows[0])
  } else {
    console.log('Slot already exists', slots.rows[0])
  }
}

We are using the pg_replication_slots view to check whether a replication slot with the given name already exists. If it doesn't exist then we create a new replication slot using the pg_create_logical_replication_slot function.

Note that we specified the pgoutput plugin in the function to decode the changes in the replication slot. This is the default plugin for logical replication, and it ships with Postgres.
Be aware that there are other plugins, such as:

test_decoding plugin is the simplest plugin that ships with Postgres to start building your own custom plugin.
wal2json, which must be installed separately in the Postgres database, allowing you to use them in the pg_create_logical_replication_slot function.

Note that each plugin has its own advantages and disadvantages, so choose the one that best fits your use case.
The biggest difference if you try to use test_decoding versus pgoutput is that the former does not accept a publication name
as a parameter while the latter does. This means that you can use pgoutput to filter the changes you want to replicate, while test_decoding will replicate all changes in the database without filtering them!

Now, run the setup-replication.js file to create a replication slot!

Configuring the consumer

In the previous article, we already created the setup-consumer.js that creates the publications that
our application is interested in. So, we can reuse the same file and just run it — if we haven't already.

As a reminder: you will first need to start the Postgres server and create the foo database.

Resuming the replication

We are ready to create a new consumer-resume.js file that will resume replication from the last point where the Node.js application was stopped, so let's jump into it:

import { LogicalReplicationService, PgoutputPlugin } from 'pg-logical-replication'

const client = new LogicalReplicationService({
  user: 'postgres',
  password: 'foopsw'
}, { acknowledge: { auto: false } })

client.on('data', async (lsn, log) => {
  if (log.tag === 'insert') {
    console.log(`${lsn}) Received insert: ${log.relation.schema}.${log.relation.name} ${log.new.id}`)
  } else if (log.relation) {
    console.log(`${lsn}) Received log: ${log.relation.schema}.${log.relation.name} ${log.tag}`)
  }

  await client.acknowledge(lsn)
})

const eventDecoder = new PgoutputPlugin({
  // Get a complete list of available options at:
  // https://www.postgresql.org/docs/16/protocol-logical-replication.html
  protoVersion: 4,
  binary: true,
  publicationNames: [
    'foo_odd',
    'foo_update_only'
  ]
})

console.log('Listening for changes...')
process.on('SIGINT', async () => {
  console.log('Stopping client...')
  await client.stop()
})

await client.subscribe(eventDecoder, 'foo_slot')

This time, we are using the pg-logical-replication package to demonstrate the resuming of replication. Its low-level API provides us more control over the replication process,
otherwise we would not be able to configure the Plugin to receive only the changes we are interested in.

The code can be explained as follows:

We are creating a new LogicalReplicationService instance and passing the connection options to it. Note that we are setting the acknowledge.auto option to false to manually acknowledge the changes; otherwise, they would be automatically acknowledged. By setting this option to false, we gain even more control over the process.
We are listening to the data event to receive changes from the replication slot.
- At this point, you should process the log and apply your business logic. In this case, we're just logging the changes to the console.
- After processing the changes, you must acknowledge them using the acknowledge method; otherwise, the slot will not advance. The lsn (Log Sequence Number) is the unique identifier for each change in the database and is used to track changes in the replication slot.
We are creating a new PgoutputPlugin instance and passing it to the subscribe method to establish a connection with the replication slot.

To start the application, run the node consumer-resume.js file, and it will begin receiving changes from the replication slot. If we did all the steps correctly, you can start the node producer.js file that we
wrote in the previous article to produce changes in the database and see the changes in the consumer application.

If you stop the consumer application by pressing Ctrl+C, the replication will stop, and the slot will not move forward. However, if you start the consumer-resume.js application again, it will resume replication from the last point where it was stopped! 🎉

Moreover, we can see that the output shows only the changes from the foo_odd and foo_update_only publications, which we configured in the PgoutputPlugin instance so we will see updates and inserts with odd id numbers only:

0/15648E0) Received insert: public.foo 18
0/15649A0) Received log: public.foo update
0/1564AF0) Received log: public.foo update
0/1564B80) Received insert: public.foo 20
0/1564C40) Received log: public.foo update
0/1564D90) Received log: public.foo update
0/1564E20) Received insert: public.foo 22
0/1564EE0) Received log: public.foo update
0/1565030) Received log: public.foo update
0/15650C0) Received insert: public.foo 24

Conclusion

In this article, we discussed how to resume replication from the last point where the Node.js application was stopped.

We created a persistent replication slot in the Postgres database and used the pg-logical-replication package to demonstrate resuming replication. This ensures that our application doesn't lose data produced by other microservices or applications during downtime.

In doing so, we did not change the producer.js file, which means that the producer can continue to produce changes in the database without any issues and the previous Publications setup is still valid: we just configured manually the
replication slot and the new consumer.

Remember, the replication slot retains changes in the database until the slot is dropped or the changes are acknowledged by the subscriber. If not managed properly, this can lead to high disk usage because Postgres will keep the changes in the WAL logs indefinitely instead of removing them.

I hope you enjoyed this article and learned something new!
Does it deserve a comment and a share? 🚀

Real-time data replication in Postgres and Node.js

Manuel Spigolon — Wed, 18 Sep 2024 14:47:24 +0000

In today's fast-paced digital landscape, businesses rely heavily on data to drive decision-making processes. Real-time data replication has emerged as a critical capability for organisations seeking to stay ahead of the curve, enabling them to synchronise data across multiple databases seamlessly. To make a few practical examples, real-time data replication is essential for scenarios such as:

Keeping different databases in sync, which is a typical scenario when a company acquires another company and needs to merge the data.
Relying on a database to trigger events in other systems; for example, when a new user is created in the database, a welcome email is sent without modifying existing code or introducing new architecture components like message queues.
Keeping an application's in-memory cache in sync with the database to improve the performance of read queries.
For high availability and disaster recovery scenarios.

As you can see, real-time data replication is a powerful tool that can be used in various scenarios to improve the performance, reliability and scalability of your applications.

In this blog post, we'll explore the power of Postgres replication management, to understand how to do a real-time data replication in Postgres with Node.js.

You will need to run some Docker commands to set up a Postgres instance with logical replication enabled, but it is a copy-paste operation.

Introduction to Postgres replication management

PostgreSQL is a powerful open-source relational database system known for its robust features and extensibility. One of its standout capabilities is replication management , allowing you to replicate data from one database to another in real-time. This feature is invaluable to organisations that require characteristics such as:

High availability: the primary database fails, and a standby server takes over seamlessly.
Load balancing: distributing read queries across multiple replicas to improve performance.
Data distribution: synchronising data across geographically distributed systems.

Postgres offers various mechanisms to support the listed scenarios where each solution has its strengths and use cases. To list a few:

Synchronous multimaster replication: a query must be committed on all nodes before returning to the client. Very high availability and data consistency but with a performance cost.
Write-ahead Log Shipping (WAL): the primary server sends WAL segments to standby servers, which replay them to stay in sync. It's a simple and reliable solution but with a potential for data loss.
Logical Replication: replicates individual changes (inserts, updates, deletes) rather than entire WAL segments. It's suitable for scenarios such as data warehousing, data distribution and selective replication. Moreover, it allows for more granular control over which tables and changes are replicated and it is possible to replicate data between different versions of Postgres or multiple sources!

The complete list of replication mechanisms can be found in the Postgres documentation.

In this blog post, we'll focus on Logical Replication mechanism.

The WAL file

The Write-ahead Log (WAL) is a fundamental concept in Postgres replication and we mentioned it in the previous section. The WAL is a file that stores all changes made to the database, such as inserts, updates and deletes, in a sequential manner. We could say that the WAL is our source of truth, and this file is handled by Postgres to guarantee data consistency and durability in case of a crash or disk failure.

We must discuss the WAL because it is the foundation of Postgres replication. We can configure Postgres to handle the WAL file, and we can use it to replicate data across multiple databases. So we must understand the wal_level configuration parameter. This parameter defines how much information is written to the WAL file. The possible values are:

minimal: only the information needed to recover from a crash is written to the WAL file.
replica: the default value, it writes enough information to support WAL archiving and replication.
logical: it stores the same information as replica and additional information needed for logical replication, so this configuration requires more disk space.

Developing a real-time data replication system with Node.js

To develop a real-time data replication system with Node.js, we must follow these steps:

Initialise the Postgres database.
Create a data producer we want to replicate.
Create a data consumer that replicates the data through the Postgres replication mechanism.

So let's start!

Setting up Postgres

We can start our journey into Postgres replication management by starting a Postgres instance and configuring it to support logical replication. Let's use Docker for this task:

docker run \
  --name demo-postgres \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=foopsw \
  postgres:16 \
  postgres -c "wal_level=logical"

This command will start a Postgres instance with logical replication enabled, and you can connect to it using the following command:

docker exec -it demo-postgres psql -U postgres

Now, from the Postgres shell, we can create a database and a table to work with:

CREATE TABLE IF NOT EXISTS foo (
  id SERIAL PRIMARY KEY,
  col1 VARCHAR,
  col2 INT
);

To check if the table was created successfully, the following command lists the user's tables in the database:

\dt

Creating a data producer

Now that we have our Postgres instance set up, let's create a Node.js application that acts as a data producer. This application will insert data into the foo table we created earlier and represent the source of data replication. It could be a web application, an IoT device, or any other data source you may have.

Let's create a producer.js file and implement the following logic:

It connects to the Postgres database.
Every second, it inserts a new row into the foo table or updates the last inserted row alternatively.
It listens for a SIGINT signal to gracefully close the connection.

import pg from 'pg' // ℹ️ npm install pg
const { Client } = pg

const client = new Client({
  user: 'postgres',
  password: 'foopsw'
})

await client.connect()

let counter = 0
let lastId = 0
const fakeUserInteraction = setInterval(async () => {
  if (counter % 2 === 0) {
    const res = await client.query('INSERT INTO foo (col1, col2) VALUES ($1, $2) RETURNING id', ['Hello world!', counter])
    lastId = res.rows[0].id
    console.log(`Inserted new row: ${lastId}`)
  } else {
    await client.query('UPDATE foo SET col1 = $1, col2 = $2 WHERE id = $3', ['Hello world!!!', 42, lastId])
    console.log(`Updated row ${lastId}`)
  }

  counter++
}, 1000)

process.on('SIGINT', async () => {
  clearInterval(fakeUserInteraction)
  await client.end()
})

To run this code the node producer.js command is enough.

Creating a data consumer

The data consumer is the other side of the replication process. It can be another Postgres instance, or even a different a different database engine. Postgres allows us to replicate the data seamlessly across different versions of the Postgres database just by configuring them accordingly (not the topic of this blog post, but there are good video tutorials for this use case).

Our use case is to replicate the data to a Node.js application! This application will connect to the Postgres database and listen for changes in the foo table using the logical replication mechanism.

Setting up the data consumer

To set up the data consumer, we must introduce some new Postgres concepts:

Publication: A publication defines a set of tables and changes to be replicated. We must create a publication to specify which tables and changes are replicated.
Subscription: A subscription defines the source of replication (e.g., primary server) and the target replica(s). We must create a subscription to subscribe to changes happening in the foo table.
Replication slot: A replication slot is like a bookmark in the WAL file that keeps track of the last WAL segment read by a client. It forces the primary server to retain the WAL segments required by any client that is using the replication slot.

We need to create all these objects in the Postgres database before we can start listening for changes. Let's do it programmatically with Node.js by creating a setup-consumer.js file:

import pg from 'pg'
const { Client } = pg

const client = new Client({ user: 'postgres', password: 'foopsw' })
await client.connect()

await createPublicationIfNotExists('foo_even', 'TABLE foo WHERE (id % 2 = 0);')
await createPublicationIfNotExists('foo_update_only', "TABLE foo WITH (publish = 'update');")

await client.end()

async function createPublicationIfNotExists (pubName, condition) {
  const pub = await client.query('SELECT * FROM pg_publication WHERE pubname = $1', [pubName])

  if (!pub.rows.length) {
    await client.query(`CREATE PUBLICATION ${pubName} FOR ${condition}`)
    console.log(`Created publication ${pubName}`)
  } else {
    await client.query(`ALTER PUBLICATION ${pubName} SET ${condition}`)
    console.log(`Updated publication ${pubName}`)
  }
}

The code shows how to create and update a publication. When a publication is created, it specifies:

Which tables and columns are included in the replication process?

If no columns are specified, all columns are included.
It is possible to list multiple tables or set FOR ALL TABLES; to include all tables in the replication process.

Which operations are included in the replication process?

The default is to include all operations (inserts, updates, deletes).
It is possible to specify only inserts, only updates, or only deletes.

We have created two publications in the code snippet above:

foo_even: it includes only rows where the id is an even number.
foo_update_only: it includes only updates.

As shown, the publications are very flexible and can be tailored to specific use cases.

Subscribing to changes

Finally, we are ready to create the consumer.js file to listen for changes in the foo table. To do so, we will use the postgres module because it provides a simple way to consume the logical replication data changes or we should implement the logical replication protocol ourselves. Alternatively, you can use the pg-logical-replication library it depends on your preference.

To create the consumer.js file, we can use the following code snippet. So first we must connect to the Postgres database and list all the publications we want to subscribe to:

import postgres from 'postgres'

const sql = postgres({
  debug: true,
  user: 'postgres',
  password: 'foopsw',
  publications: [
    'foo_even',
    'foo_update_only'
  ]
})

Then we can subscribe to the changes happening in the foo table:

const eventPattern = '*:foo'
const { unsubscribe } = await sql.subscribe(
  eventPattern,
  (row, { command, relation, key, old }) => {
    console.log({
      command,
      row
    })
  },

  function onConnect () {
    // Callback on initial connect and potential reconnects
    console.log('Connected to the publication')
  }
)

process.on('SIGINT', async () => {
  await unsubscribe()
  process.exit()
})

If we run the node consumer.js command, we will see the console.log output every time the producer.js:

Insert a row with an even ID in the foo table.
Update a row in the foo table.

Note that the eventPattern is just a feature of the postgres module that allows us to filter the changes we are getting from the database. The main driver is and will always be the Postgres publication we created earlier with the setup-consumer.js script.

So far we did not create the Replication Slot, but the postgres module will do it for us by calling the CREATE_REPLICATION_SLOT command creating a TEMPORARY slot. Every subscription needs a Replication Slot to track the changes that they are consuming.

Note that the Replication Slot MUST be deleted or consumed by the client, otherwise if it isn't then the WAL file in the primary server will not be truncated and the disk space will grow indefinitely! Luckily, the postgres module creates a temporary replication slot that is automatically deleted when the connection is closed.

Now our Node.js application is ready to listen for changes in the foo table and replicate them in real-time!

Conclusion

PostgreSQL's replication capabilities are a cornerstone of its reliability and scalability. We just scratched the surface of what is possible with Postgres replication management, but we have seen how to set up a real-time data replication system using Node.js and Postgres logical replication.

Another interesting use case is to use the logical replication mechanism to read all the changes happening in the database while the Node.js application was offline. This is possible by handling the Replication Slot manually and it can be done with the pg-logical-replication module's API, but this will be the topic of another blog post!

We hope this blog post has given you a good starting point to explore Postgres replication management further. Here are some resources to deepen your knowledge:

Comment and share if you enjoyed this article!

How to implement video streaming with Fastify

Manuel Spigolon — Sat, 31 Aug 2024 05:00:10 +0000

In April 2021, I tweeted about a quick experiment where I streamed a large GoPro video using Fastify.

That initial experiment sparked some interest, and just a few months ago, a user reached out with an intriguing question: how could they modify the code to support stream segmentation? Specifically, they wanted users to be able to jump to different parts of the video, effectively allowing timeline scrubbing during playback. I considered this a fascinating challenge and decided to turn it into a blog post.

In this article, we'll explore how to implement video streaming with Fastify, focusing on handling range requests. This will enable smooth playback even with large video files, allowing users to seek through the video timeline effortlessly.

By the end of this post, you'll understand the key concepts behind video streaming in Node.js, how to use Fastify to serve video content efficiently, and how to handle range requests to enhance the user experience with precise control over video playback.

Setting up the project

Before we dive into the code, let's set up our project environment. We'll be using Node.js 20 and Fastify v4 for this tutorial. Additionally, you'll need a large video file to stream I'll be using a GoPro video I filmed while riding a jet ski with my fiance 😄

Here's how you can create and set up the project. I've also included some additional plugins we'll need to complete the exercise:

# Create a new directory for the project
mkdir fastify-video-streaming
cd fastify-video-streaming

# Initialize a new Node.js project with ES6 module support
npm init es6 --yes

# Install Fastify and necessary plugins
npm install fastify@4 fastify-range@1

With the project initialised and dependencies installed, we're ready to start building the video streaming server.

Getting ready to stream

With our project set up, it's time to start coding. We'll begin by initialising the Fastify application and setting up a basic route to serve an HTML page containing a video tag. This HTML page will be the frontend interface for our video streaming where users can play and seek through the video content.

First, create a new file named app.js in your project directory. Now, let's write the code to initialise the Fastify server and set up the root route to serve the HTML page:

import Fastify from 'fastify'
import * as fs from 'node:fs'

// Initialize the Fastify application with logging enabled
const app = Fastify({ logger: true })

// Set up a route to serve the HTML page
app.get('/', async () => {
  // Serve the index.html file from the project directory
  return fs.createReadStream('./index.html')
})

// Start the server and listen on port 8080
await app.listen({ port: 8080 })

Next, create an index.html file in the same directory to define the structure of our frontend and add the following basic code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Video Streaming with Fastify</title>
</head>
<body>
    <h1>Fastify Video Streaming</h1>
    <video controls width="600">
        <source src="/video-streaming" type="video/mp4">
        Your browser does not support the video tag.
    </video>
</body>
</html>

This simple HTML page includes a video element that will request the video stream from our server via the /video-streaming route, which we'll implement next.

At this point, your Fastify server is set up to serve an HTML page that will act as the frontend for our video streaming application.

By running the node --watch app.js command in your terminal, you can start the server and access the page at http://localhost:8080 in your browser. You should see a basic page with a video player ready to stream content.

Streaming video content

With the basic setup in place, it's time to implement the core functionality of our streaming server: handling video content with support for range requests. This is what allows users to seek through the video timeline, providing a smooth and responsive playback experience.

Understanding range requests

The Range HTTP header is essential for streaming large files like videos. It allows the client (in this case, the browser) to request specific portions of a file rather than downloading the entire file in one go. This functionality is particularly useful for video streaming, as it lets users jump to different parts of the video without having to load the entire file.

The range request feature is defined by RFC 7233. When a browser sends a request for a video, it typically includes a Range header specifying the byte range it wants.

An example of a Range header might look like this:

Range: bytes=0-

The client is asking for the video file starting from byte 0 to the end. If the server supports range requests, it responds with a 206 Partial Content status and includes the requested byte range in the Content-Range header. Here's an example of the response headers:

Content-Range: bytes 0-1000000/2257069623

This header indicates that the server is sending bytes 0 to 1 MB of a total of 2.257.069.623 (>2GB!) bytes in the video file.

Now the browser knows how much of the video it has received, and it can request additional segments as needed without buffering the entire video. So, only when needed, the browser will request the next segment of the video such asking for bytes from 1MB:

Range: bytes=1000001-

Note that the Range header is typically used to request byte-ranges, but it can also be used to implement a pagination-like system where the range is a slice of a list of items such as a range of users because the specification allows custom units! This was an interesting topic on StackOverflow, and I am mentioning it because it can be an interesting exercise for the mind to compare and contrast different ideas between developers!

Implementing the `/video-streaming` route

Lets add the /video-streaming route to our Fastify application to handle these range requests.

First, we must use the fastify-range plugin to easily parse the range header and extract the requested byte range. This plugin will add a request decorator to help us handle the range requests efficiently.

import fastifyRange from 'fastify-range'

// ...
app.register(fastifyRange)
// ...

Now we can focus on the /video-streaming route implementation. Note that the route name was defined in the src attribute of the <source> tag in the index.html file.

app.get('/video-streaming', async (request, reply) => {
  const videoPath = '/path/to/your/video.mp4'
  const videoSize = fs.statSync(videoPath).size

  // Extract the range from the request headers
  const range = request.range(videoSize)
  request.log.info({ range })
  if (!range) {
    // If no valid range is found, throw a 416 error
    // as indicated by the RFC 7233
    const error = new Error('Range Not Satisfiable')
    error.statusCode = 416
    throw error
  }

  // Handle only the first range requested
  const singleRange = range.ranges[0]

  // Define the size of the chunk to send
  const chunkSize = 1 * 1e6 // 1MB
  const { start } = singleRange
  const end = Math.min(start + chunkSize, videoSize - 1)
  const contentLength = end - start + 1

  // Set the appropriate headers for range requests
  reply.headers({
    'Accept-Ranges': 'bytes',
    'Content-Range': `bytes ${start}-${end}/${videoSize}`,
    'Content-Length': contentLength
  })

  // Send a 206 Partial Content status code
  reply.code(206)
  reply.type('video/mp4')

  // Stream the requested chunk of the video file
  return fs.createReadStream(videoPath, { start, end })
})

The code above does the following:

Extracting the range: When the browser requests the video, it sends a Range header indicating the portion of the file it wants to download. We extract this range using the request.range(videoSize) method, which is provided by the fastify-range plugin. Note that we need to know the total size of the video file to validate the range because the browser might request a range that exceeds the file size.
Validating the range: If no valid range is provided or the range is unsatisfiable, the server responds with a 416 Range Not Satisfiable error. This indicates that the server cannot fulfil the request as specified.
Chunk size and byte ranges: We calculate the size of the chunk to send based on the requested range. In this case, weve set the chunk size to 1MB and it is up to the server implementation to choose the appropriate size. You may implement a more complex logic to determine the chunk size based on the client's bandwidth or device. The start and end variables define the exact byte range that will be streamed back to the client.
Setting headers: The server responds with a 206 Partial Content status and includes headers like Content-Range and Content-Length to inform the client of the specific byte range being sent.
Streaming the video: Finally, the server streams the requested portion of the video file using fs.createReadStream(videoPath, { start, end }). This allows the video player in the browser to play the video while additional portions are requested as needed.

With this implementation, our Fastify server is now capable of streaming video content efficiently, handling range requests to provide a seamless playback experience for users.

The HTML <video> tag in our index.html file automatically handles range requests when a user interacts with the video's timeline controls. For instance, if a user clicks ahead to a different part of the video, the browser sends a new request with an updated Range header, prompting the server to deliver the corresponding video segment.

This mechanism ensures smooth playback and efficient use of bandwidth, as only the necessary parts of the video are loaded and played.

By implementing this route, weve enabled our server to stream large video files efficiently, providing users with the ability to navigate through the video timeline seamlessly.

Conclusion

In this tutorial, we explored how to build a video streaming server using Fastify and Node.js. We implemented a Fastify application capable of serving large video files with support for range requests. This approach allows users to interact with the video timeline, seamlessly streaming only the necessary parts of the video. The source code for this project is available on GitHub.

I want to point out that this implementation is a basic example to get you started with video streaming in Fastify. In a real-world scenario, we should consider additional features like caching, security, and performance optimisations to ensure a robust and reliable video streaming service, but now you have the tools to implement video streaming in your own projects, allowing users to enjoy a smooth and interactive video experience.

If you enjoyed this article, comment, share and follow me on Twitter!

Streaming PostgreSQL data with Fastify

Manuel Spigolon — Tue, 20 Aug 2024 14:58:40 +0000

In recent years, we have been surrounded by cool, interactive data visualizations. These visualizations are powered by datasets stored in databases and made available through APIs.

Clients can then query the API and get the data they need to render the visualization.

But what happens when the dataset is enormous? And what if the query to access the data is complex and slow?

You may be used to adding a 'cool' loading animation to your visualization and waiting for the data to be loaded but this is not the best user experience.

So, we will see how to stream a massive amount of data from a PostgreSQL database to a Reactjs client!

Build the dataset

I will go fast here because this is not the main topic of this article, and the code is available on GitHub.

We will create two tables that represent our huge dataset:

Table	Rows	Description
`desks`	200,000	200 thousand desks in a building
`items`	10,000,000	10 million items on the desks

The query we are going to analyze is the following:

  WITH start_time AS (SELECT pg_sleep(1) AS start_time)
  SELECT items.id, desks.name, row_number() OVER (ORDER BY items.id) AS row_number
  FROM items
  INNER JOIN desks ON desks.id = items.desk_id
  CROSS JOIN start_time

It reads all the items and the desks they are on and returns the result with a row number.

Since the query is not too slow, we need to slow it down to simulate a real-world scenario with multiple joins and aggregations. The pg_sleep(1) forces PostgreSQL to wait for 1 second before returning the result.

Now we can start the PostgreSQL server with a quick Docker command:

docker run --rm -p 5432:5432 --name fastify-postgres -e POSTGRES_PASSWORD=postgres -d postgres:15-alpine

Finally, we can seed the database with the tables and the data with the node seed.js script on GitHub. It will take a few minutes to complete, but we will have a huge dataset to play with at the end!

Build the API

We are going to use Fastify to build the API, it has everything we need to build a fast and scalable API in no time 🎉.

But, before writing the code, we need to think about the API we want to build. Since we want to return a huge amount of data, we can't run the query and return the result in one shot: whatever server we use, it will run out of memory!

So we need to stream the result of the query to the client by using different techniques:

Batching : we can run the query in batches and return the result in chunks.
Streaming : we can stream the result of the query to the client as soon as we get the data.

The Batching approach can be implemented using the SQL language's LIMIT and OFFSET clauses. So we don't need any external library to implement it.

The Streaming approach is more complex, but it is more efficient and allows us to return the data as soon as we get it. A quick Google search will show you that a few libraries can help us with this task:

Both libraries are great, but the pg-query-stream has a better API, so we will use it.

Note

I tested both pg- libraries before noticing that pg-query-stream uses pg-cursor under the hood 😅 The performance of the two libraries is the same, so we will discuss pg-query-stream only.

Now that we know what to do, we can start writing the code!

Project setup

We will create a quick project setup. It is important to note that the code is not optimized for production use. This is to keep it as simple as possible.

If you want to learn more about Fastify, you may find the Fastify book helpful!

So, let's start creating a new project from scratch with the following commands:

# Create the project
mkdir fastify-postgres-high-volume
cd fastify-postgres-high-volume
npm init -y

# Install Fastify
npm install fastify @fastify/postgres

# Install the PostgreSQL driver and utilities
npm install pg pg-query-stream JSONStream

Create the app.js file with the following content:

const fs = require('fs').promises

// Create the Fastify server
const app = require('fastify')({ logger: true })

// A simple route to serve the Reactjs application
app.get('/', async function serveUi (request, reply) {
  reply.type('text/html')
  return fs.readFile('./index.html')
})

// Register the PostgreSQL plugin to connect to the database
app.register(require('@fastify/postgres'), {
  host: 'localhost',
  port: 5432,
  database: 'postgres',
  user: 'postgres',
  password: 'postgres',
  max: 20
})

// Register some plugins to implement the API - we will see them later
app.register(require('./lib/batch'))
app.register(require('./lib/stream'))

// Start the server
app.listen({ port: 8080, host: '0.0.0.0' })

It is time to scaffold the lib/batch.js plugin:

module.exports = async function (app, opts) {
  app.get('/api/batch', queryBatch)
}

async function queryBatch (request, reply) {
  const notImplemented = new Error('Not implemented')
  notImplemented.statusCode = 501
  throw notImplemented
}

Let's scaffold the lib/stream.js plugin too:

module.exports = async function (app, opts) {
  app.get('/api/stream', queryStream)
}

async function queryStream (request, reply) {
  const notImplemented = new Error('Not implemented')
  notImplemented.statusCode = 501
  throw notImplemented
}

We are going to implement the two plugins in the next sections.

The last thing we need to do is to create the index.html file that will be served by the server. I have created a simple Reactjs application in a single HTML file. You can find it on GitHub. The code is not important for this article, so I will not discuss it here; moreover, we need the API to be up and running to test the client, so we will explore it later.

At this point, we can start the server with the following command:

node app.js

💡 Node.js Tip

If you are running Node.js 20 or newer, you can use the node --watch app.js flag to reload the server when the code changes! It doesn't require any external library and is very useful during development.

Once the server is up and running, we can open the browser and navigate to http://localhost:8080 and we should see the index.html application!

We can now implement the API's business logic!

Implementing the Batching approach

The Batching approach is the most common one to implement since it is used broadly in the industry to paginate the results of a query. The idea is to run the query in batches and return the data chunks, so we need two inputs from the client:

limit: the number of rows to return in each chunk.
offset: the number of rows to skip before returning the batch result.

We can get these two values in the request.query object by adding a JSON schema to the route that validates the input:

app.get('/api/batch', {
  schema: {
    query: {
      type: 'object',
      properties: {
        offset: { type: 'number', default: 0 },
        limit: { type: 'number', default: 50_000 }
      }
    }
  }
}, queryBatch)

The queryBatch implementation will look like this:

async function queryBatch (request, reply) {
  // Get the input from the client
  const offset = request.query.offset
  const batchSize = request.query.limit

  // The slow query we want to run
  const slowQuery = `
    WITH start_time AS (SELECT pg_sleep(1) AS start_time)
    SELECT items.id, desks.name, row_number() OVER (ORDER BY items.id) AS row_number
    FROM items
    INNER JOIN desks ON desks.id = items.desk_id
    CROSS JOIN start_time

    OFFSET $1
    LIMIT $2;
  `

  // Run the query and return the result
  const result = await this.pg.query(slowQuery, [offset, batchSize])
  return result.rows
}

When the client calls the /api/batch route, the server will run the slowQuery and return the result.

The this.pg object is an Application Decorator injected by the @fastify/postgres plugin, and it is a PostgreSQL pool!

We can now test the API by running the following command:

curl http://localhost:8080/api/batch?offset=0&limit=10000

The server should return the first 10,000 rows of the result of the slowQuery! Note that the response will pop up in the terminal after 1 second at the latest 🐌.

Implementing the Streaming approach

The Streaming approach could be more complex to implement. However, thanks to the pg-query-stream library, it is not .

The idea is to stream the result of the query to the client as soon as we get the data. So we need to create a stream that reads the result of the query and pipe it to the client. The input we need from the client is the limit only because we are going to stream the result and don't need to skip anything.

We can read the limit input from the request.query object by adding a JSON schema to the route that validates the input:

app.get('/api/stream', {
  schema: {
    query: {
      type: 'object',
      properties: {
        limit: { type: 'number', default: 50_000 }
      }
    }
  }
}, queryStream)

Now we can implement the queryStream function:

const QueryStream = require('pg-query-stream')
const JSONStream = require('JSONStream')

async function queryStream (request, reply) {
  // Get the PostgreSQL client from the pool
  const client = await this.pg.connect()

  // The slow query we want to run
  const slowQuery = `
    WITH start_time AS (SELECT pg_sleep(1) AS start_time)
    SELECT items.id, desks.name, row_number() OVER (ORDER BY items.id) AS row_number
    FROM items
    INNER JOIN desks ON desks.id = items.desk_id
    CROSS JOIN start_time

    LIMIT $1;
  `

  // Create a new stream that runs the query
  const query = new QueryStream(slowQuery, [request.query.limit], {
    highWaterMark: 500
  })

  // Run the query and return the stream
  const stream = client.query(query)
  stream.on('end', () => { client.release() })
  return stream.pipe(JSONStream.stringify())
}

Let's analyze the code:

We create a new PostgreSQL client by calling this.pg.connect() that returns an available client from the pool.
We create a new QueryStream that will run the same slowQuery as the batch implementation except for the OFFSET clause:
- It is important to note that we need to set the highWaterMark option to read a good amount of rows from the database. The default value is 16, which is too low for our use case!
We create a new stream by calling client.query(query) that will execute the query.
We must remember to listen for the end event of the stream to release the client back to the pool.
We return the stream piped to a JSONStream that will convert the result to a JSON string. Fastify will automatically manage the stream and send the result to the client!

We can now test the API by running the following command:

curl http://localhost:8080/api/stream?limit=10000

The server should return the first 10,000 rows of the result of the slowQuery!

You should see the result being streamed to the terminal as soon as the server gets the data from the database! There is no delay between the rows, so the client can start to render the data as soon as it gets it! The pop-up effect is gone! 🚀

Build the client

Now that we have the API up and running, we can build the client to test the API and see the effect of the two approaches. Since I like minimalism 🤣 and don't want to spend too much time on the client, I will use the Reactjs application I have created before.

It is a simple application with the following features:

An input to set globally for the application how many rows we must fetch from the API calls.
A button to call the /api/batch route and show the time it takes to get the result.
- An input to set the maximum number of rows to get for each batch: we can't get all the rows in one shot, or the server will run out of memory!
A button to call the /api/stream route and show the time it takes to get the result.

Here is a screenshot of the application:

Now, let's press the buttons and see what happens!

Results

If we press the buttons with the default values, we will get the following results:

It must be noted that the results include the time it takes to parse the data in the browser.

Before analyzing the results, let's try to play with the inputs to see how the results change.

What happens if we increase the batch size to 350,000?

The batch approach is much faster than before, and it beats the streaming method!

Let's analyze the results:

Total Rows	Batch Size	Batch Result Time (sec)	Stream Result Time (sec)	Number of Batches
500,000	50,000	~14	~7 🥇	10
500,000	350,000	~5 🥇	~7	2
1,000,000	350,000	~8 🥇	~15	3
3,000,000	350,000	~30 🥈	~30 🥈	9
3,500,000	350,000	~36	~34 🥇	10
5,000,000	350,000	~63	~53 🥇	15

Each test result is the best of 3 tests after refreshing the web page and clearing the cache. The Fastify server runs locally on a MacBook Pro 2019 and is never restarted during the tests.

The results are exciting! The streaming approach is faster than the batch approach when the number of batches (calculated by totalRows / batchSize) is higher or equal to 10.

Is this a general rule? Let's answer this question by doing some investigating!

Watch this video taken from the Chrome DevTools's Network tab about the 2nd test result:

the application UI results

We can see that the batch approach makes two requests to the server, while the streaming approach makes only one request. But the Content Download time is much higher for the streaming approach.

Could we improve it? Yes, of course!! Let's try to increase the highWaterMark option of the QueryStream to 5MB!

const query = new QueryStream(slowQuery, [request.query.limit], {
  highWaterMark: 5e6
})

Let's rerun the tests, and you should see that the total time takes ~4/5 seconds for the streaming approach (body parsing included)! The Content Download time is now ~2 seconds, so by increasing the highWaterMark, we speed up the download of the data x2!

Now, if we rerun the 3rd test with the new highWaterMark, the streaming approach ends in ~10 seconds, so we cut down the time by 1/3!

This means that the 10 batches rule is not a general rule to defeat the streaming approach, but it depends on how we configure our stream.

So the speed relation of the two approaches is the following:

Batching : If we have a small number of batches, the batch approach is faster to implement and run. But we can't increase the batch size too much to reduce the number of batches. The 350,000 rows batch size fetched ~30 MB of data; that's way too much for a single set but was helpful for our understanding.
Streaming : It is not always the fastest approach if we don't configure the stream properly. However, it is the most efficient approach because it doesn't require loading all the data in memory before sending it to the client. Moreover, it is the more stable approach in the long run because it doesn't require changing the batch size when the dataset grows, and it lets us build more responsive UI applications.

Summary

In this article, we have seen how to stream a massive amount of data from a PostgreSQL database to a Reactjs client! We explored two different approaches, and we have seen how to implement them with Fastify and the pg-query-stream library.

The performance of the two approaches has been compared, and we have seen that the streaming approach is the most efficient and stable in the long run even if it is not always the fastest.

We analyzed the results and found a relation between each approach and its performance. Now you can choose the best approach for your use case by knowing the pros and cons of each approach!

If you enjoyed this article, comment, share and follow me on Twitter!

The Fastify book is out!

Manuel Spigolon — Fri, 09 Feb 2024 16:06:10 +0000

Are you a mid/expert back-end engineer looking to build highly scalable and maintainable API servers? Are you already familiar with Node.js and other back-end frameworks? If so, then "Accelerating Server-Side Development with Fastify" is the book you've been waiting for!

About the Authors: Meet the team behind this comprehensive guide - Manuel Spigolon, a Senior Backend Developer at NeaForm, with expertise in Backend Software Development for IT Services; Maksim Sinik, a Senior Engineering Manager at TrustLayer Inc. in the Insurtech, Healthcare, and Logistics industries, specializing in Node.js Backend Scalability; and Matteo Collina, Co-Founder & CTO of Platformatic, a renowned Open Source author and core maintainer of Fastify.

Who is this Book For? This book targets mid/expert back-end engineers with prior experience in Node.js and other back-end frameworks. It assumes you are familiar with JavaScript and HTTP protocol but are looking to understand the unique selling points of Fastify. Whether you are developing a monolithic application or planning to transition to microservices, this guide will show you how to leverage Fastify's features for optimal results.

Why Choose "Accelerating Server-Side Development with Fastify"? While there are other books on Fastify, they often touch on various aspects of development without diving deep into creating scalable and maintainable applications. This book focuses solely on Fastify and delves into its core logic and features, helping you avoid common pitfalls and build highly responsive applications.

Learning Outcomes Throughout this book, you'll learn the following essential skills:

Understand encapsulation techniques implemented by Fastify.
Become proficient in using Fastify's unique features compared to other frameworks.
Learn to organize project structures and implement architectures for transitioning to microservices.
Develop a real-world project to put theory into practice.
Deploy, monitor, and handle errors in a running Fastify instance effectively.

Book Structure The book is divided into three parts, each addressing different aspects of Fastify development:

Part One: Fastify Basics

What is Fastify?
The Plugin System and the Boot Process
Working with Routes
Exploring Hooks
Exploring Validation and Serialization

Part Two: Building a Real-World Project

Project Structure and Configuration Management
Building a RESTful API
Authentication, Authorization, and Files Handling
Application Testing
Deployment and Process Monitoring for a Healthy Application
Meaningful Application Logging

Part Three: Advanced Topics

From a Monolith to Microservices
Performance Assessment and Improvement
Developing a GraphQL API
Type-Safe Fastify

If you're ready to accelerate your server-side development with Fastify, this comprehensive guide is a must-have for your toolkit!

For more updates and technical discussions, follow the authors on Twitter:

Maksim Sinik: @maksimsinik
Manuel Spigolon: @manueomm
Matteo Collina: @matteocollina

Or subscribe to this blog!

Get your copy of "Accelerating Server-Side Development with Fastify" today and embark on a journey towards building scalable and maintainable backend applications!

Validate the Fastify input with Joi

Manuel Spigolon — Mon, 29 Jan 2024 17:07:47 +0000

If you are an hapi developer, you may know the joi library. It is a powerful validation library that allows you to define programmatic schemas for your data and validate them with ease.

One of the hardest things about migrating from hapi to fastify is the complexity thats involved for you to be able to keep using joi for the route's input validation.

But now, thanks to the joi-compiler library, you can use joi with fastify without any problem!

Note If you have been afraid to use it because it has very few downloads, don't worry it is a new library and I'm the author. And, if you don't know me, I'm a Fastify core maintainer and I'm the co-author of the Fastify book too!

The joi-compiler module replaces the default ajv schema compiler with a joi-based one and allows you to use joi schemas to validate your data. Let's see how to use it!

Integrate `joi` with `fastify`

After you have installed the latest fastify@4 and joi-compiler module:

mkdir fastify-joi
cd fastify-joi
npm init -y
npm install --save fastify@4 joi-compiler

We can create a simple index.js file with the following content:

const fastify = require('fastify')
const JoiCompiler = require('joi-compiler')

// Instantiate the compiler
const joiCompilerInstance = JoiCompiler()

// Install it to Fastify
const app = fastify({
  schemaController: {
    bucket: joiCompilerInstance.bucket,
    compilersFactory: {
      buildValidator: joiCompilerInstance.buildValidator
    }
  }
})

// Use it!
const joiSchema = joiCompilerInstance.joi.object({
  foo: joiCompilerInstance.joi.string().required()
})

app.get('/', {
  handler: () => 'Hello World!',
  schema: {
    headers: joiSchema
  }
})

app.listen({ port: 3000 })

If you run this code, you will be able to test the joi validation with the following command:

curl -X GET http://localhost:3000/
# {"statusCode":400,"error":"Bad Request","message":"\"foo\" is required"}

curl -X GET http://localhost:3000/ -H "foo: bar"
# Hello World!

As you can see, the joi schema is working as expected! In a few lines of code, we have integrated joi with fastify and we are able to use it to validate the input of your application routes.

How it works

The joi-compiler module is a Fastify schema compiler, it is used by Fastify to build the components during the startup to guarantee the encapsulated feature.

For this reason, the joi-compiler can be configured in the schemaController option during the Fastify application creation.

Note

How the Fastify Schema Controller works is out of the scope of this article. But if you want to know more about it, you can read the Fastify book!

How to configure the `joi-compiler`

The JoiCompiler accepts an optional configuration object to customize the joi instance.

The default configuration is:

const joiCompilerInstance = JoiCompiler({
  // optionally: provide all the JOI options you need
  // Here is all the possible options: https://joi.dev/api/?v=17.9.1#anyvalidatevalue-options
  prefs: {
    stripUnknown: true
  },

  // optionally: an array with custom JOI extensions such as `@joi/date`
  extensions: [
  ],

  // optionally: if you want to use the async validation. Default: false
  asyncValidation: false
})

When you instantiate the joiCompilerInstance, the returned object has the following properties:

buildValidator: The function to pass to the schemaController option of Fastify.
bucket: The joi bucket that contains the schemas when you call the app.addSchema(joiSchema) method. You can omit this option if you don't use app.addSchema.
joi: A customized joi instance that contains the installed extensions, if there are any. It is a good practice to use this instance to build your schemas.

How to use `ajv` and `joi` together!

The power of Fastify is that you can use different schema compilers at the same time! Here is an example of how you can learn from the Fastify book:

const joiCompilerInstance = JoiCompiler()
const app = fastify()

app.post('/ajv', {
  handler: (request) => request.body,
  schema: {
    body: {
      type: 'object',
      properties: {
        toX: { const: 42 },
        toY: { const: 50 }
      }
    }
  }
})

app.register(async function pluginJoi (app, opts) {
  // Install the joi compiler into this encapsulated context!
  app.setSchemaController({
    bucket: joiCompilerInstance.bucket,
    compilersFactory: {
      buildValidator: joiCompilerInstance.buildValidator
    }
  })

  // Let's try to use the external schemas!
  app.addSchema({ $id: 'x', $value: 42 })
  app.addSchema({ $id: 'y', $value: 50 })

  app.post('/joi', {
    handler: (request) => request.body,
    schema: {
      body: Joi.object({
        toX: Joi.ref('$x'),
        toY: Joi.ref('$y')
      })
    }
  })
})

app.listen({ port: 3000 })

If you run this code, you will be able to use the ajv and joi validation in the same application! The ajv validation will be used for the /ajv route and the joi validation will be used for the /joi route.

Pretty cool, right?

Summary

The joi-compiler is a powerful tool that allows you to build and manage joi instances for Fastify out of the box in a few lines of code. If you're a joi user, joi-compiler is definitely worth checking out!

If you enjoyed this article comment, please share and follow @ManuEomm on Twitter!

Fastify has a new Application Hook!

Manuel Spigolon — Mon, 18 Sep 2023 06:50:09 +0000

Fastify v4.23.0 has just been released, featuring a brand-new onListen Application hook. In this article, we'll explore what it is and how you can leverage it in your Fastify applications.

Understanding Fastify hooks

Fastify's hooks are a fundamental aspect of its design. Hooks are functions that get called at specific points in a component's lifecycle. They allow you to inject custom functionality at these crucial moments, thus altering the component's behavior.

Hooks are particularly useful for breaking down your application logic into reusable pieces that can be executed at specific times.

Fastify offers two primary types of hooks:

Application hooks : These consist of 5 hooks that are invoked in a specific order during the application's lifecycle.
Request/Reply hooks : There are a total of 10 hooks that are called in a specific order during the HTTP request lifecycle.

Each hook type serves a distinct purpose and comes with its own API. Before diving into the new onListen hook, let's briefly overview Fastify's hooks.

Application hooks

Application hooks allow you to customize how your Fastify application initializes and closes. These hooks play a crucial role in starting and stopping the application gracefully.

🛫 The application hooks during application startup include:

onRoute: Triggered when a route is registered.
onRegister: Invoked when an encapsulated plugin is registered.
onReady: Called when the application is ready but not yet listening to incoming requests.

If any of these hooks throw an error, the application won't start. These hooks are essential for performing mandatory checks before launching the application, and they execute in the order they are registered.

🛬 The application hooks during application shutdown are:

preClose: Executed before the application is closed, while HTTP requests are still being processed.
onClose: Triggered when the application no longer accepts new requests.

These hooks are handy for performing cleanup tasks before shutting down the application, such as closing a database connection. However, they behave differently when an error is thrown:

preClose hooks are executed in the order they are registered, and if one of them throws an error, subsequent hook functions are not executed. It is likely that you will not use this hook in your application.
onClose hooks are executed in the reverse order they are registered, and if one of them throws an error, the following hook functions are executed regardless.

You can find more details about these hooks in my Fastify book 📙!

The new `onListen` hook

With the release of Fastify v4.23.0, we introduce the sixth application hook: onListen. This hook is called when the application is ready, and the server is actively listening to incoming requests.

The API for the onListen hook is consistent with other application hooks, supporting both async/await and callback styles:

// async/await style
app.addHook('onListen', async function () {
  // Some async code
})

// or callback style
app.addHook('onListen', function (done) {
  // Some code
  const err = null;
  done(err)
})

In the application startup sequence, you can now list this new hook as the final step:

onRoute
onRegister
onReady
onListen: Invoked when the application is ready, and the server is actively handling incoming requests.

It's essential to note that this hook has some differences compared to the others of the same type:

If the onListen hook throws an error, the application will still start anyway, similar to the behavior of the onClose hook.
Since the server is already processing HTTP requests, be cautious of potential race conditions if you attempt to load data needed by your routes.
If you don't call app.listen() in your tests, this hook will not be executed.

So, when should you use the onListen hook?

This hook was added in response to community requests to perform tasks that require the server to be actively listening to incoming requests. A common use case is loading external data from a remote service to populate the application cache.

The power of the onListen hook lies in its ability to load data asynchronously without blocking or delaying the application startup. It's perfect for loading non-mandatory data for your routes. If you need to load data that's essential for a decorator and must be available before the application starts, consider using the onReady hook instead.

Request/Reply hooks

While we won't delve into Request/Reply hooks in this article, you can find comprehensive information in the Fastify documentation or in chapter 4 of the detailed Fastify book 📙!

Summary

In this article, we've introduced the new onListen hook, explained how it works and highlighted its use cases. Fastify continues to evolve in response to the community's needs, and this hook is a prime example of that.

If you found this article helpful, please leave a comment, share it with others, and follow me on Twitter for more updates!

Dynamic GraphQL queries with Mercurius

Manuel Spigolon — Sat, 16 Sep 2023 13:40:25 +0000

If you're using Fastify with Mercurius as your GraphQL adapter, you may be looking for some advanced usages. In this article, we'll explore a real world example with Dynamic GQL queries with Mercurius.

The example we will discuss is only one scenario that you may encounter as Software Engineer at NearForm! If you want to solve these kind of problems, we are hiring!

What are Dynamic GraphQL queries?

A dynamic GraphQL query is a query that is constructed at runtime, based on the needs of the client. This is useful when the client is uncertain of the structure of the data and needs to retrieve specific data based on conditions, or when the client needs to retrieve a subset of data depending on the user's role or permissions.

In our use case, we want to invert the control of query dynamicity from the client to the server. This means that the client will send a standard GQL query and the server will return the data based on:

The client's query
The user's role

It's important to note that we are not talking about returning a subset of a generic GraphQL type, but a completely different GraphQL type.

Defining the schema

When creating a GraphQL server, the first step is to define the schema. The GraphQL specification provides clear guidance on how to accomplish our target by utilizing GraphQL Unions.

Unions in GraphQL allow for multiple types to be returned from a single field, making it a powerful tool for querying related data. This can be especially useful when retrieving data from multiple types in a single query.

To begin, let's define our schema using GraphQL Unions.

type Query {
  searchData: Grid
}

union Grid = AdminGrid | ModeratorGrid | UserGrid

type AdminGrid {
  totalRevenue: Float
}

type ModeratorGrid {
  banHammer: Boolean
}

type UserGrid {
  basicColumn: String
}

As you can see, our schema includes a Query type with a searchData field that returns a Grid union type. This Grid union type can represent one of three possible types: AdminGrid, ModeratorGrid, or UserGrid.

Currently, the client can send a query using inline fragments like this:

query {
  searchData {
    ... on AdminGrid {
      totalRevenue
    }
    ... on ModeratorGrid {
      banHammer
    }
    ... on UserGrid {
      basicColumn
    }
  }
}

While this is a valid query, it is not the desired outcome. We aim to return a different type based on the user's role, so that the client can send a query like this:

query {
  searchData {
    totalRevenue
  }
}

It's important to note that the above query is not valid against the schema defined above, but with some additional implementation, we can make it work!

Implementing the business logic

Let's start building the basic implementation of our server. You can skip this section if you are already familiar with Fastify and Mercurius.

The first step is to install the necessary dependencies.

mkdir graphql-dynamic-queries
cd graphql-dynamic-queries
npm init -y
npm install fastify@4 mercurius@11

Now, copy the schema we defined above in a gql-schema.js file, then you need to create an app.js file where we will write our server:

const Fastify = require('fastify')
const GQL = require('mercurius')
const schema = require('./gql-schema')

// For simplicity, we will start the server only if started with `node app.js run`
if (process.argv[2] === 'run') {
  buildApp()
    .then(app => app.listen({ port: 8080 }))
}

async function buildApp () {
  const app = Fastify({ logger: true })

  await app.register(GQL, {
    schema,
    resolvers: {
      Query: {
        searchData: async function (root, args, context, info) {
          // TODO: implement the business logic
          return {}
        }
      },
      Grid: {
        resolveType (obj, context) {
          return getUserType(context)
        }
      }
    }
  })

  return app
}

module.exports = buildApp

function getUserType (context) {
  switch (context.reply.request.headers['x-user-type']) {
    case 'admin':
      return 'AdminGrid'
    case 'moderator':
      return 'ModeratorGrid'
    default:
      return 'UserGrid'
  }
}

To verify that everything is working, you can start the server running node app.js run and you should see the following output:

Server listening at http://127.0.0.1:8080

Great! Now we must list all the use cases we want to implement by adding some test cases.

Testing our server

We want to test our server with the following use cases:

A user with the admin role should be able to retrieve the totalRevenue field without inline fragments
A user with the moderator role should be able to retrieve the banHammer field without inline fragments
A user with the user role should be able to retrieve the basicColumn field without inline fragments
A user without the admin role should not be able to retrieve the totalRevenue field
A user without the moderator role should not be able to retrieve the banHammer field
A user without the user role should not be able to retrieve the basicColumn field
A user without any role should not be able to retrieve any field

We must install the required dependencies:

npm install tap@15 -D

We can write these tests in a test.js file.

const { test } = require('tap')

const buildApp = require('./app')

test('A user with the `admin` role should be able to retrieve the `totalRevenue` field without inline fragments', async t => {
  const app = await buildApp()
  const res = await doQuery(app, 'admin', `
    query {
      searchData {
        totalRevenue
      }
    }
  `)

  t.same(res.data.searchData, { totalRevenue: 42 })
})

// TODO: add the other tests

async function doQuery (app, userType, query) {
  const res = await app.inject({
    method: 'POST',
    url: '/graphql',
    headers: {
      'x-user-type': userType
    },
    body: {
      query
    }
  })

  return res.json()
}

For the sake of simplicity, we will not list all the tests here, but you can find the complete complete source code in the GitHub repository.

Running the tests with node test.js will fail because we have not implemented the business logic yet. So, let's start writing the code!

Implementing the server-side Dynamic Queries

To implement the business logic, there are these main steps:

Retrieve the user's role from the request headers
Manage the GraphQL query to return the correct type based on the user's role

Let's solve the first point.

How to retrieve the user's role

We can implement the user role retrieval by installing the mercurius-auth plugin.

npm i mercurius-auth@3

Then, we can register the plugin in our app.js file. To understand what the plugin does, you can read its documentation.

In the following example, we will compare the x-user-type HTTP header with the @auth directive we are going to define in the schema. If they match, the user will be authorized to access the field and run the query.

Let's start by defining the @auth directive in the schema:

directive @auth(
  role: String
) on OBJECT

# ..same as before

type AdminGrid @auth(role: "admin") {
  totalRevenue: Float
}

type ModeratorGrid @auth(role: "moderator") {
  banHammer: Boolean
}

type UserGrid @auth(role: "user") {
  basicColumn: String
}

Then, we can register the plugin in our app.js file and implement a simple searchData resolver:

async function buildApp () {
  const app = Fastify() // the same as before

  await app.register(GQL, {
    schema,
    resolvers: {
      Query: {
        searchData: async function (root, args, context, info) {
          switch (getUserType(context)) {
            case 'AdminGrid':
              return { totalRevenue: 42 }

            case 'ModeratorGrid':
              return { banHammer: true }

            default:
              return { basicColumn: 'basic' }
          }
        }
      },
    },
    Grid: {} // the same as before 
  })

  app.register(require('mercurius-auth'), {
    authContext (context) {
      return {
        identity: context.reply.request.headers['x-user-type']
      }
    },
    async applyPolicy (policy, parent, args, context, info) {
      const role = policy.arguments[0].value.value
      app.log.info('Applying policy %s on user %s', role, context.auth.identity)

      // we compare the schema role directive with the user role
      return context.auth.identity === role
    },
    authDirective: 'auth'
  })

  return app
}

Now, the user should be able to retrieve the totalRevenue field only if the x-user-type header is set to admin.

Nevertheless, we can't run the tests yet because we have not implemented the second point.

Implementing the Dynamic Queries

The last step is to implement the dynamic queries. Right now, our tests are failing with the following error:

"Cannot query field 'totalRevenue' on type 'Grid'. Did you mean to use an inline fragment on 'AdminGrid'?

The error is correct because we are not using inline fragments to query a Union type.

To overcome this issue, we can use the mercurius preValidation hook. Let's try to see how it works:

When a client sends a GraphQL query, the server will process the GQL Document in the preValidation hook, before validating the GQL against the GQL Schema.

In this hook, we can modify the GQL Document sent by the user to add the inline fragments. So, after the mercurius-auth plugin registration, we can add the following code:

async function buildApp () {
  const app = Fastify() // the same as before

  await app.register(GQL, {
    // the same as before 
  })

  app.register(require('mercurius-auth'), {
    // the same as before
  })

  app.graphql.addHook('preValidation', async (schema, document, context) => {
    const { visit } = require('graphql')

    const userType = getUserType(context)

    const newDocument = visit(document, {
      enter: (node) => {
        // We check if we must add the inline fragment
        const isMaskedQuery = node.kind === 'Field' &&
                              node.name.value === 'searchData' &&
                              node.selectionSet.selections.length === 1 &&
                              node.selectionSet?.selections.length > 0

        if (isMaskedQuery) {
          // This is the magic, we add a new inline fragment modifying the AST
          const nodeWithInlineFragment = {
            ...node,
            selectionSet: {
              kind: 'SelectionSet',
              selections: [
                {
                  kind: 'InlineFragment',
                  typeCondition: {
                    kind: 'NamedType',
                    name: {
                      kind: 'Name',
                      value: userType
                    }
                  },
                  selectionSet: node.selectionSet
                }
              ]
            }
          }
          return nodeWithInlineFragment
        }
      }
    })

    // We apply the new AST to the GQL Document
    document.definitions = newDocument.definitions
  })

  return app
}

In the previous code, we inspect the GraphQL Document Abstract Syntax Tree (AST) to determine if we need to add the inline fragment programmatically. If we recognize the query as a masked query, we add the inline fragment to the AST and return the modified AST to the GraphQL Document.

By doing this, Mercurius will process the modified GraphQL Document as if the user had sent it with the inline fragment. This means that it will:

Validate the GraphQL Document against the GraphQL Schema
Apply the authentication policy
Resolve the query

With this implementation, when running tests, everything should pass successfully.

Summary

We have seen how versatile Mercurius is and how simple it is to implement features like dynamic queries in a complex scenario. While the goal may seem challenging, this server-side implementation provides several benefits such as:

Avoiding breaking changes on the client side to support new features
Hiding GraphQL Types from the client through disabling schema introspection
Applying query optimizations for the client
Providing a specialized response based on the user type instead of a generic one.

This is just a small example of the possibilities when using Mercurius and manipulating the GraphQL Document.

If you have found this helpful, you may read other articles about Mercurius.

Now jump into the source code on GitHub and start to play with the GraphQL implemented in Fastify.

If you enjoyed this article comment, share and follow me on Twitter!

How to use DataLoader with Mercurius GraphQL

Manuel Spigolon — Sat, 05 Aug 2023 09:29:06 +0000

Solve the N+1 Problem Using DataLoader with Mercurius GraphQL

by Manuel Spigolon

If you are using Fastify with Mercurius as the GraphQL adapter, you are probably looking for a solution to the N+1 problem. This article will show you how to solve it and speed up your GraphQL application.

If you are not using Fastify instead, you can read a Quick Start guidebefore reading this article.

What is the N+1 problem?

I must say that I could not find a TL;DR (Too Long; Didn't Read) explanation of the N+1 problem to suggest for you to read before continuing. So, I will try to explain it with a quick code example that we will fix later in this article.

Let's see the N+1 problem in action.

First of all, we need an application up & running. Create a gql-schema.js file that will contain a simple GQL Schema string:

type Query {
  developers: [Developer]
}

type Developer {
  id: Int
  name: String
  builtProjects: [Project]
}

type Project {
  id: Int
  name: String
}

Let's connect the previous schema to a new app.js file, where we will implement a Fastify + Mercurius application.We will use an in-memory database to store the mock data. You can find the SQL data used for this article in the source code on GitHub.

const Fastify = require('fastify')
const mercurius = require('mercurius')
const gqlSchema = require('./gql-schema')

run()

async function run() {
  const app = Fastify({ logger: true })

  // Initialize an in-memory SQLite database
  await app.register(require('fastify-sqlite'), {
    promiseApi: true,
  })
  // For the sake of the test, we are going to create a table with some data
  await app.sqlite.migrate({ migrationsPath: 'migrations/' })

  const resolvers = {
    Query: {
      // This is the resolver for the Query.developers field
      developers: async function (parent, args, context) {
        const sql = `SELECT * FROM Developers`
        context.app.log.warn('sql: %s', sql)
        return context.app.sqlite.all(sql)
      },
    },
    // This is the resolver for the Developer Typo Object
    Developer: {
      builtProjects: async function (parent, args, context) {
        const sql = `SELECT * FROM Projects WHERE devId = ${parent.id}`
        context.app.log.warn('sql: %s', sql)
        return context.app.sqlite.all(sql)
      },
    },
  }

  app.register(mercurius, {
    schema: gqlSchema,
    graphiql: true,
    resolvers,
  })

  await app.listen({ port: 3001 })
}

Great, we are ready to start our application by running the node app.js command. Thanks to the graphiql: true option, we can open the GraphiQL interface at http://localhost:3001/graphiql.

From the GraphiQL interface, we can run the following query by hitting the Play button:

{
  developers {
    name
    builtProjects {
      name
    }
  }
}

So far, so good! You should see the server's output on the right side of the GraphiQL interface. However, if we look at the server's logs, we can see that the server has executed 4 SQL queries:

{"level":40,"hostname":"Eomm","msg":"sql: SELECT * FROM Developers"}
{"level":40,"hostname":"Eomm","msg":"sql: SELECT * FROM Projects WHERE devId = 1"}
{"level":40,"hostname":"Eomm","msg":"sql: SELECT * FROM Projects WHERE devId = 2"}
{"level":40,"hostname":"Eomm","msg":"sql: SELECT * FROM Projects WHERE devId = 3"}

As you can see, the queries are not optimized because we ran a query to fetch the projects for each developer instead of fetching all the projects in a single query.

Now you have seen the N+1 problem in action:

1 : we run a root query to fetch the first data list
+N : we run a query for each item of the previous list to fetch the related data

So, if we had 100 developers, we would run 101 queries instead of 2! Now that we have seen the problem, let's solve it.

How to solve the N+1 problem?

The most common way to solve the N+1 problem is to use DataLoaders. The DataLoader allows you to batch and cache the results of your queries and reuse them when necessary.

Mercurius offers you two ways to use DataLoader:

Loader: it is a built-in DataLoader-Like solution that is quick to set up and use.
DataLoader: it is the standard solution to N+1 problem.

In this article, we are going to see both solutions and compare them.

Mercurius Loader in action

The loader feature is a built-in DataLoader-Like solution that is quick to set up and use. It replaces Mercurius' resolvers option.

Let's see how to use it by optimizing the previous app.js example:

// ... previous code

const loaders = {
  Developer: {
    builtProjects: async function loader(queries, context) {
      const devIds = queries.map(({ obj }) => obj.id)
      const sql = `SELECT * FROM Projects WHERE devId IN (${devIds.join(',')})`
      context.app.log.warn('sql: %s', sql)

      const projects = await context.app.sqlite.all(sql)
      return queries.map(({ obj }) => {
        return projects.filter((p) => p.devId === obj.id)
      })
    },
  },
}

const resolvers = {
  Query: {
    // ... previous code
  },
  Developer: {
    // Delete the `builtProjects` resolver. It would be ignored in any case
  },
}

// ... previous code

app.register(mercurius, {
  schema: gqlSchema,
  graphiql: true,
  loaders, // add the loaders option
  resolvers,
})

As you can see, we have replaced the resolvers.Developer.builtProjects function with the loaders one. The difference is that the loaders receive an array of queries (results from the parent query) instead of a single parent object. Mercurius will batch the queries and call the loader function only once.

In this new loader function, you can run a single query to fetch all the data you need and then you must return a positionally-matched array of results.

Pros:

It is quick to set up and use.
It is not necessary to pollute the context.
It is managed by Mercurius.
Clear separation of concerns between the resolvers and the loaders.

Cons:

It is not possible to reuse the loader's cache in other resolvers.

DataLoader in action

DataLoader is the standard solution to the N+1 problem. It was originally created by Facebook. Let's see how we can integrate it into our application.

First, you should restore the app.js file removing the loaders configuration. Second, we need to install the dataloader package:

npm install dataloader

Finally, we must instantiate a DataLoader for each request, so we need to extend the context object:

const DataLoader = require('dataloader')
// ... previous code

const resolvers = {
  Query: {
    // ... previous code
  },
  Developer: {
    builtProjects: async function (parent, args, context) {
      return context.projectsDataLoader.load(parent.id)
    },
  },
}

app.register(mercurius, {
  schema: gqlSchema,
  graphiql: true,
  resolvers,
  context: () => {
    // Instantiate a DataLoader for each request
    const projectsDataLoader = new DataLoader(async function (keys) {
      const sql = `SELECT * FROM Projects WHERE devId IN (${keys.join(',')})`
      app.log.warn('sql: %s', sql)
      const projects = await app.sqlite.all(sql)
      return keys.map((id) => projects.filter((p) => p.devId === id))
    })

    // decorate the context with the dataloader
    return {
      projectsDataLoader,
    }
  },
})

In this new example, we have added the new projectsDataLoader object to the Mercurius context. This object is an instance of the DataLoader class that we have imported from the dataloader package.

The DataLoader class accepts a batchLoader function that will be called only once for each batch of queries. It supports different ways to accumulate the queries:

Frame of execution: it is the default behavior. It accumulates the queries until the next tick. It is the same approach used by Mercurius Loader.
Time frame: it accumulates the queries until the specified time frame.

The batchLoader function receives an array of keys as a single argument, and it must return an array of results positionally matching the input array. As you can see, it is the same approach used by Mercurius Loader.

Pros:

It is a standard defacto solution.
Flexibility: it is possible to reuse the loader cache in other resolvers.

Cons:

Requires more code to set up and configure, you need to create your own context to access the database.
The resolvers must be aware and use the DataLoader instance.

Summary

You have now learned how to use DataLoaders with Mercurius by exploring two different solutions to solve the N+1 problem. You may think that mixing the resolvers and the loaders could be a good idea. Surely it is doable, but you must turn off one of the two caches to avoid inconsistencies and it could be a bit confusing to manage.

If you have found this helpful, you may read other articles about Mercurius.

Now jump into the source code on GitHub and start to play with the GraphQL implemented in Fastify.

If you enjoyed this article comment, share and follow me on twitter!

DEV Community: Manuel Spigolon

Managing Request-Scoped Data in Fastify

What is AsyncLocalStorage?

How It Works

Why Is This Important?

How to Use the @fastify/request-context Plugin

Quick Start

@fastify/request-context vs Decorators

Summary

Announcing the Fastify Mini Course

🚀 Why Fastify?

📖 Whats Inside the Mini Course?

🎯 Who Is This For?

📅 How to Get Access

🚀 Get Ready to Build Faster APIs!

Master Node.js with the 5th Edition Cookbook

Resume data replication in Postgres and Node.js

How to resume replication from the point where the Node.js application was stopped

Creating a replication slot

Configuring the consumer

Resuming the replication

Conclusion

Real-time data replication in Postgres and Node.js

Introduction to Postgres replication management

The WAL file

Developing a real-time data replication system with Node.js

Setting up Postgres

Creating a data producer

Creating a data consumer

Setting up the data consumer

Subscribing to changes

Conclusion

How to implement video streaming with Fastify

Setting up the project

Getting ready to stream

Streaming video content

Understanding range requests

Implementing the /video-streaming route

Conclusion

Streaming PostgreSQL data with Fastify

Build the dataset

Build the API

Project setup

Implementing the Batching approach

Implementing the Streaming approach

Build the client

Results

Summary

The Fastify book is out!

Validate the Fastify input with Joi

Integrate joi with fastify

How it works

How to configure the joi-compiler

How to use ajv and joi together!

Summary

Fastify has a new Application Hook!

Understanding Fastify hooks

Application hooks

The new onListen hook

Request/Reply hooks

Summary

Dynamic GraphQL queries with Mercurius

What are Dynamic GraphQL queries?

Defining the schema

Implementing the business logic

Testing our server

Implementing the server-side Dynamic Queries

How to retrieve the user's role

Implementing the Dynamic Queries

Summary

How to use DataLoader with Mercurius GraphQL

Solve the N+1 Problem Using DataLoader with Mercurius GraphQL

What is the N+1 problem?

How to solve the N+1 problem?

Mercurius Loader in action

DataLoader in action

Summary

How to Use the `@fastify/request-context` Plugin

`@fastify/request-context` vs Decorators

Implementing the `/video-streaming` route

Integrate `joi` with `fastify`

How to configure the `joi-compiler`

How to use `ajv` and `joi` together!

The new `onListen` hook