DEV Community: Jan Hesters

JavaScript Promises Explained, But On A Senior-Level

Jan Hesters — Fri, 13 Jun 2025 12:21:10 +0000

If you've been coding in JavaScript for a while, you've probably encountered promises.

But do you truly understand them at a senior-level? If not, you might encounter random bugs that take a long time to find the root cause, or you may not know how to compose promises with functional patterns.

Whether you're a beginner or an experienced developer eager to learn some senior secrets, this article is packed with code examples and best practices to help you master promises.

So let's start with ...

What Is A Promise?

A promise is an object representing the eventual completion or failure of an asynchronous operation. Think of it as a placeholder for a future value. Instead of immediately returning the final value, an asynchronous method returns a promise to supply the value at some point in the future.

Promise Constructor

You can create a promise using the Promise constructor, which requires an executor function. This executor function takes two arguments:

resolve: A function to call when the promise is fulfilled.
reject: A function to call when the promise is rejected.

Here's how you create a resolving promise:

const resolvingPromise = new Promise(resolve => {
  resolve('Hello, world!');
});

You use the new keyword to create a promise. The constructor takes a callback, called the executor function. This executor function's first parameter is the resolve function. You pass to it the value that the promise should resolve to when the operation completed successfully, in this case 'Hello, world!'.

It's crucial to differentiate between the promise constructor and the promise instance. The promise constructor refers to the Promise class (after the new keyword), whereas a promise instance is an object created using the Promise constructor, here resolvingPromise.

And here's a rejecting promise:

const rejectingPromise = new Promise((_, reject) => {
  reject(new Error('Something went wrong'));
});

In the rejectingPromise, you create a new promise that immediately rejects with an error message. By passing (_, reject) to the executor function, you focus on the reject function, which you call with an error object. You use an underscore _ to ignore the resolve parameter in the rejecting promise since you don't need it.

Promise Chaining

Promises are chainable, allowing you to handle sequences of asynchronous operations in a readable manner. The Promise object provides three main methods:

then: Attaches callbacks for the resolution or rejection of the Promise. It returns a new promise, allowing for further chaining.
catch: Attaches a callback for handling any errors or rejections in the promise chain. It also returns a new promise.
finally: Attaches a callback that will be executed regardless of the promise's fate (resolved or rejected). It is used for cleanup actions and also returns a new promise.

`then`

The then method is used to handle the resolved value of a Promise. It takes in a callback function that receives the resolved value as an argument.

const resolvingPromise = new Promise(resolve => resolve('Hello, world!'));

myPromise.then(result => {
  console.log(result); // Output: Hello, world!
});

Create a promise that immediately resolves with 'Hello, world!'. Next, attach a then handler to the promise. The then method receives the resolved value and logs it to the console.

You can also handle rejected promises with then by using the second parameter.

const rejectingPromise = new Promise((_, reject) =>
  reject(new Error('Something went wrong')),
);

rejectingPromise.then(null, error => {
  console.error(error); // Output: Error: Something went wrong
});

Create a rejecting promise again.

Now when you call then, the first parameter is null because you don't have a fulfillment handler. The second parameter is also a callback function and receives the rejection reason as an argument.

This allows you to handle both fulfillment and rejection in the same then method.

Since the then method is a higher-order function, you can pass in arguments in point-free style.

const resolvingPromise = new Promise(resolve => resolve('Hello, world!'));

resolvingPromise.then(console.log); // Output: Hello, world!

Create a promise that resolves immediately.

Attach a then handler to the promise. By passing console.log directly to then, you're using point-free style. The resolved value is automatically passed as an argument to console.log.

`catch`

The catch method is specifically for handling rejected Promises, making your code cleaner and more readable.

const rejectingPromise = new Promise((_, reject) =>
  reject(new Error('Something went wrong')),
);

rejectingPromise.catch(error => {
  console.error(error); // Output: Error: Something went wrong
});

Create a rejecting promise and attach a catch handler to rejectingPromise. The callback function receives the error object and logs it to the console. This is a more straightforward way to handle errors compared to using the second parameter of then.

`finally`

The finally method executes a callback regardless of whether the Promise was fulfilled or rejected, which is useful for cleanup tasks.

const resolvingPromise = new Promise(resolve => resolve('Hello, world!'));

resolvingPromise
  .then((result) => {
    console.log(result);
  })
  .finally(() => {
    console.log('Promise settled');
  });

Create a resolving promise.

Attach a then handler to the promise. The callback function receives the resolved value and logs it to the console.

Next, attach a finally handler to the promise. The finally block runs after the promise settles, regardless of the outcome.

Complex Promise Chaining Examples

When you chain promises, there are a few behaviors you should be aware of.

Errors in then Handlers: Throwing an error in a then handler causes the promise to be rejected, skipping subsequent then handlers until a catch is found.
Catching Errors: You can catch errors using a catch handler or the second parameter of then.
Continuing the Chain: After handling an error, you can continue chaining then handlers.
Modifying Values: You can modify the value passed through the chain at any point.

Let's explore how promise chaining behaves with some examples.

```javascript title="first-chain-example.js"
const trace = message => value => {
console.log(message, value);
return value;
};

new Promise(resolve => resolve(1))
.then(trace('first'))
.then(trace('second'));




Define a curried `trace` function that takes a `message` and returns another function. This returned function takes a `value`, logs the message and value, and then returns the value.

Next, create a promise that immediately resolves with `1`. Attach two `then` handlers to the promise. Each `then` receives the resolved value `1`, logs it along with a message, and passes it to the next handler.

When you run this code, you'll see:



```sh
$ node first-chain-example.js
first 1
second 1

Now, let's see what happens if you throw an error in one of the then handlers.

```javascript title="second-chain-example.js"
const trace = message => value => {
console.log(message, value);
return value;
};

const throwError = error => {
throw new Error(error);
};

new Promise(resolve => resolve(2))
.then(throwError)
.then(trace('never gets logged out'))
.catch(trace('caught'));




Define the `trace` function again and a `throwError` function that takes a value and throws a new `Error` with that value.

Create a promise that resolves immediately with `2`. Attach a `then` handler that calls `throwError`, which throws an error, causing the promise to be rejected. The next `then` handler is skipped because the promise is now in a rejected state. The control moves to the nearest `catch` handler.

When you run this code, you'll see:



```sh
$ node second-chain-example.js
caught Error: 2

The second then handler doesn't execute because errors cause the promise chain to skip directly to the next catch.

After catching an error, you can continue chaining then handlers.

```javascript title="third-chain-example.js"
const trace = message => value => {
console.log(message, value);
return value;
};

new Promise((_, reject) => reject(3))
.then(trace('never gets logged out'))
.catch(x => trace('caught')(x + 1))
.catch(trace('previous catch handles this - nothing gets logged out'))
.then(trace('gets the result from catch'));




Start with a promise that rejects with `3`. Then attach in succession a `then` handler, two `catch` handlers, and finally another `then` handler.

When you run this code, you'll see:



```sh
$ node third-chain-example.js
caught 4
gets the result from catch 4

The initial then handler is skipped because the promise is rejected. The first catch handler receives the rejection reason 3, increments it by 1, logs it, and returns the new value 4. The promise is now resolved with 4.

Any subsequent catch handlers are skipped since the promise is resolved. The next then handler receives the value 4.

Notice that you can modify the value passed through the chain in any then or catch handler, as you did here by incrementing the value by 1.

Now, let's do one last complex example with multiple rejections.

```javascript title="fourth-chain-example.js"
const trace = message => value => {
console.log(message, value);
return value;
};

const throwError = error => {
throw new Error(error);
};

new Promise(resolve => resolve(4))
.then(trace('first'))
.catch(trace('nothing to catch - never gets logged out'))
.then(trace('second'))
.then(x => x + 1)
.then(trace("keep in mind you can change what's being passed through"))
.then(throwError)
.then(null, error => trace('caught through second parameter')(error))
.catch(trace('previous .then handles this - nothing gets logged out'))
.then(trace('this is the end'));




Resolve a promise with `4`. Then attach a `then` handler to it, a `catch` handler, 5 more `then` handlers, the last of which uses the second parameter of `then` to catch any errors, another `catch` handler and finally another `then` handler.

When you run this code, you'll see:



```sh
$ node fourth-chain-example.js
first 4
second 4
keep in mind you can change what's being passed through 5
caught through second parameter Error: 5
this is the end 5

Here's what's happening step by step:

Promise resolves with 4: The chain starts with a resolved promise with the value 4.
First then: Logs 'first 4' and returns 4.
First catch: Skipped because there is no error.
Second then: Logs 'second 4' and returns 4.
Increment value: The next then increments the value to 5.
Log changed value: The following then logs "keep in mind you can change what's being passed through 5" and returns 5.
Throw error: The next then throws an error with the value 5.
Error handling in then: The subsequent then catches the error using the second parameter, logs 'caught through second parameter Error: 5', and returns 5.
Second catch: Skipped because the error has been handled.
Final then: Logs 'this is the end 5'.

Promise States

A promise exists in one of three states:

Pending: This is the initial state of a promise. At this stage, the promise is neither fulfilled nor rejected, indicating that the asynchronous operation is still in progress.
Fulfilled: A promise reaches this state if the asynchronous operation completes successfully. This triggers the execution of the onFulfilled() function, typically associated with a resolve() call in the promise's handling code.
Rejected: If the asynchronous operation fails or encounters an error, the promise is rejected. This state triggers the onRejected() function, which is generally tied to a reject() call.

Once a promise changes from pending to either fulfilled or rejected, it becomes settled. This means it has been resolved (either fulfilled or rejected) and will not change states again. Any further attempts to resolve or reject a settled promise will have no effect, preserving its immutability.

There is no property that tells you the internal promise state. You can only observe the states of a promise indirectly by using the Promise constructor and inspecting the promise object.

const pendingPromise = new Promise((resolve, reject) => {
  console.log('Promise state:', pendingPromise); // Output: Promise { <pending> }
  setTimeout(() => {
    resolve('Fulfilled!');
    console.log('Promise state after resolve:', pendingPromise); // Output: Promise { 'Fulfilled!' }
  }, 1000);
});

pendingPromise.then(value => {
  console.log('Resolved with:', value); // Output: Resolved with: Fulfilled!
});

Create pendingPromise, which is initially in the "pending" state.

Next, log pendingPromise immediately, which shows Promise { <pending> }. After 1 second, you resolve the promise with 'Fulfilled!'.

When you now log pendingPromise using then, it shows Promise { 'Fulfilled!' } after 1 second.

Example: `waitFor`

You can tie what you've learned together and create a waitFor function.

const waitFor = (value, ms) =>
  new Promise((resolve, reject) => {
    setTimeout(() => {
      if (value) {
        return resolve(value);
      }

      return reject(new Error('Value is falsy'));
    }, timeout);
  });

waitFor(true, 1000).then(() => console.log('Done!'));

This waitFor function takes in a value and a timeout. It waits for the timeout. Then, if the value is truthy, the promise resolves. Otherwise, it rejects.

Important: Always use return before resolve and reject inside your if and else blocks. Without return, the function might continue executing and potentially call both resolve and reject, leading to unexpected behavior.

Lazy vs. Eager

Promises are eager. Eager describes the evaluation behavior of operations. There are two different evaluation strategies: eager and lazy.

Eager evaluation computes values as soon as they are assigned. Lazy evaluation delays the computation until the value is needed.

Here is what that means for promises:

console.log("Before promise");

const myPromise = new Promise(resolve => {
  console.log("Inside promise");
  resolve("Promise resolved");
});

console.log("After promise");

myPromise.then(console.log);

If you run this code, you'll see the following output:

Before promise
Inside promise
After promise
Promise resolved

Notice that "Inside promise" is logged right after "Before promise", even before we attach a then handler. This demonstrates the eager nature of Promises.

If you want to see an example for lazy evaluation, check out "JavaScript Generators Explained, But On A Senior-Level".

Promise Methods

JavaScript provides several static methods on the Promise object to handle multiple Promises and other scenarios.

`Promise.resolve`

There is another way to create a promise without a function. You can use two static methods on the Promise object.

The first one is Promise.resolve, which you can use to create a promise that immediately resolves with a given value.

const promise1 = new Promise(resolve => resolve('Hello, world!'));
const promise2 = Promise.resolve('Hello, world!');

promise2.then((message) => {
  console.log(message); // Output: Hello, world!
});

Here, promise1 and promise2 are equivalent.

`Promise.reject`

There is also Promise.reject, which allows you to create a promise that immediately rejects with a given reason.

const promise3 = new Promise(
  (_, reject) => reject(new Error('Something went wrong'))
);
const promise4 = Promise.reject(new Error('Something went wrong'));

promise4.catch(error => {
  console.error(error); // Output: Error: Something went wrong
});

Since the promise rejects now, you need to use catch (or the second parameter of then) to get the result. Again, promise3 and promise4 are equivalent.

`Promise.all`

Waits for all Promises in an iterable to be resolved and returns a new Promise that resolves to an array of their results.

const wait = (ms, value) =>
  new Promise(resolve => setTimeout(() => resolve(value), ms));

const promises = [wait(2000, 'Hello'), wait(1000, 'World')];

Promise.all(promises).then(results => {
  console.log(results); // Output: ['Hello', 'World']
});

Create a helper function wait that takes a value and a timeout. It returns a promise that resolves after the timeout.

Next, create an array promises with two promises. One resolves after 2 seconds and the other after 1 second.

Then, you call Promise.all with promises. It returns a new promise that resolves when all promises in the array have resolved. The resolved value is an array of the results of the input promises, in this case ['Hello', 'World']. Since the first promise is slower and resolves after 2 seconds, it takes two seconds until the promise returned from Promise.all resolves with the array.

`Promise.allSettled`

The Promise.allSettled method waits until all promises have settled, meaning they've either fulfilled or rejected. It returns a new promise that resolves with an array of objects describing the outcome of each promise.

const promise1 = Promise.resolve('Success');
const promise2 = Promise.reject('Error');

Promise.allSettled([promise1, promise2]).then((results) => {
  results.forEach((result) => console.log(result));
});
// Output:
// { status: 'fulfilled', value: 'Success' }
// { status: 'rejected', reason: 'Error' }

Create two promises: one that resolves and one that rejects. When you use Promise.allSettled, it waits for both promises to settle and then logs an array with the results. Each result object contains a status property indicating whether the promise was fulfilled or rejected, and either a value or a reason property with the result.

This method is useful when you want to handle multiple promises and process all outcomes, regardless of whether they succeeded or failed.

`Promise.any`

The Promise.any method returns a promise that fulfills as soon as any of the promises in the iterable fulfills. If all promises reject, it rejects with an AggregateError.

const promise1 = Promise.reject('Error 1');
const promise2 = new Promise((resolve) => setTimeout(resolve, 100, 'Success'));
const promise3 = Promise.reject('Error 3');

Promise.any([promise1, promise2, promise3])
  .then((value) => {
    console.log(value); // Output: Success
  })
  .catch((error) => {
    console.error(error);
  });

Create two rejecting promises and one that resolves after 100 milliseconds. Promise.any waits for the first promise to fulfill. Since promise2 fulfills after 100 milliseconds, the then handler logs 'Success'. If you modify the code so that all promises reject, the catch block will handle an AggregateError, indicating that all promises were rejected.

`Promise.race`

The Promise.race method takes in an array of promises and returns a promise that settles as soon as any of the promises in the iterable settles (fulfilled or rejected).

const promise1 = new Promise((resolve) => setTimeout(resolve, 500, 'First'));
const promise2 = new Promise((resolve) => setTimeout(resolve, 100, 'Second'));
const promise3 = new Promise((_, reject) => setTimeout(reject, 50, 'Error'));

Promise.race([promise1, promise2, promise3])
  .then((value) => {
    console.log('Resolved with:', value);
  })
  .catch((error) => {
    console.error('Rejected with:', error); // Output after 50ms: Rejected with: Error
  });

Create two promises that resolve after different timeouts and one that rejects after 50 milliseconds. Since promise3 rejects the fastest, Promise.race settles immediately with that rejection.

You can adjust the timeouts to see how Promise.race behaves when the first settled promise fulfills instead.

const promise1 = new Promise((resolve) => setTimeout(resolve, 50, 'First'));
const promise2 = new Promise((resolve) => setTimeout(resolve, 500, 'Second'));
const promise3 = new Promise((_, reject) => setTimeout(reject, 100, 'Error'));

Promise.race([promise1, promise2, promise3])
  .then((value) => {
    console.log('Resolved with:', value);
  })
  .catch((error) => {
    console.error('Rejected with:', error); // Output after 50ms: Rejected with: Error
  });

Change the timeouts so that promise1 resolves after 50 milliseconds and promise2 after 500 milliseconds. And promise3 rejects now after 100 milliseconds. Since promise1 fulfills the fastest, Promise.race resolves with 'First'. promise3 still rejects, but using Promise.race that doesn't matter.

`async` / `await`

The async and await keywords provide a more readable and synchronous-looking way to work with Promises.

async: Declares an asynchronous function that returns a Promise.
await: Pauses the execution of an async function until a Promise is settled.

You can make any function declaration asynchronous by writing the async keyword before the function keyword. And you can make arrow functions asynchronous by writing the async keyword before the parentheses of the parameter list.

const fetchData = async () => {
  const response = await fetch('https://api.example.com/data');
  const data = await response.json();
  return data;
};

fetchData().then((data) => {
  console.log(data);
});

Define an async function fetchData that fetches data from an API. Using await, you pause execution until the fetch promise resolves. You do the same for the response.json() call. When you call fetchData, you can use .then to handle the returned data because the async keyword makes the function return a promise.

Top-Level `await`

Usually you need to declare functions as async in order to be able to use await inside them. But some JavaScript environments allow you to use await in non-async functions. This feature is called "top-level await".

const result = await Promise.resolve('Hello, world!');

console.log(result); // Output: Hello, world!

With top-level await, you can await promises directly. So in this case, you don't need to use then to log out the result.

Awaiting Synchronous Values

You can await synchronous values like strings, numbers, booleans, and arrays.

async function awaitSynchronous() {
  const result = await 'Hello, world!';
  return result;
}

awaitSynchronous().then(console.log); // Output: Hello, world!

Write a function awaitSynchronous that awaits a string. Since you're using the async keyword, the function becomes a promise returning function.

Then you await the string, which does nothing because all "non-promise" values behave the same as they usually do in synchronous code.

`try...catch`

When using async / await, you can handle errors using try...catch, making your asynchronous code cleaner.

const fetchData = async () => {
  throw new Error('Network error');
};

const getData = async () => {
  try {
    const data = await fetchData();
    console.log(data);
  } catch (error) {
    console.error('Error:', error.message); // Output: Error: Network error
  }

  return 'No error'
};

getData().then(console.log); // Output: No error

Define a function fetchData that throws a new error. Now you can use getData in another function called getData, which wraps the execution of fetchData in a try...catch block to handle any potential errors. When you now call getData, it will still resolve, but log out the error from the catch block in the console before logging out the resolved value through the then method.

Special Case: `return await`

In async functions, you might see return await before a potentially rejecting promise. While the function would work without await, using it can help with error handling.

const getNumberWithAwait = async () => {
  try {
    return await Promise.reject(new Error('Oops!'));
  } catch (error) {
    console.error('Caught in getNumberWithAwait:', error.message);
  }
};

const getNumberWithoutAwait = async () => {
  try {
    return Promise.reject(new Error('Oops!'));
  } catch (error) {
    console.error('Caught in getNumberWithoutAwait:', error.message);
  }
};

getNumberWithAwait().then((number) => {
  console.log('Result with await:', number); // Output: Result with await: undefined
});

getNumberWithoutAwait().then((number) => {
  console.log('Result without await:', number);
}).catch((error) => {
  console.error('Caught outside:', error.message); // Output: Caught outside: Oops!
});

You define two functions, which both reject with an error.

First, getNumberWithAwait, which uses await before the return keyword.

And second, getNumberWithoutAwait, which doesn't use await before the return keyword.

When you now call both, you'll see that getNumberWithAwait resolves, while getNumberWithoutAwait rejects. Using await before the return ensures that any errors are caught within the try...catch block.

The Three Ways To Create A Promise Returning Functions

Therefore, when you deal with promise returning functions, you can see that there are three ways to create a promise.

const asyncInc1 = x => new Promise(resolve => resolve(x + 1));
const asyncInc2 = x => Promise.resolve(x + 1);
const asyncInc3 = async x => x + 1;

Manual Resolution Promise: asyncInc1 manually constructs a new Promise and resolves it using resolve.
Immediate Resolution Promise: asyncInc2 uses Promise.resolve for a more concise and immediate resolution.
Async Function Promise: asyncInc3 defines an async function, which implicitly returns a promise resolving to the result.

The three asyncInc functions are equivalent in terms of their behavior and return values. They all return a promise that resolves with x incremented by 1.

Notice that asyncInc3 does not use await inside the function. It still returns a promise because of the async keyword. As mentioned earlier, the await keyword has no effect on synchronous values.

Unwrapping

The then method unwraps the value of a promise. This means that if you return a promise from within a then callback, it will be unwrapped so that the next then in the chain receives the resolved value, not the promise itself.

const inc = x => x + 1;
const asyncInc = async x => x + 1;

Promise.resolve(20).then(inc).then(console.log); // Output: 21
Promise.resolve(20).then(asyncInc).then(console.log); // Output: 21

Define two functions inc and asyncInc.

Whether you call the then method with a normal function inc or a "promise lifting" function asyncInc, which lifts its result into the promise context, the value is unwrapped and passed on to the next then in the chain. Without this unwrapping you'd expect the second example to return Promise { <pending> }.

The await keyword works the same way.

async function example() {
  const result = await Promise.resolve(20).then(inc);
  return result;
}

example().then(console.log); // Output: 21

Promise.resolve(20).then(inc) returns a promise that resolves to 21. The await keyword then unwraps that value so that example returns 21.

Promises Cannot Be Aborted Or Cancelled

Promises themselves do not have a built-in way to be cancelled once initiated.

Some people try to abuse the Promise.race method as a cancellation mechanism. This looks something like this:

function fetchData() {
  const fetchPromise = fetch('https://api.example.com/data').then(response =>
    response.json(),
  );

  const timeoutPromise = new Promise((_, reject) =>
    setTimeout(() => reject(new Error('Timeout after 5 seconds')), 5000),
  );

  return Promise.race([fetchPromise, timeoutPromise]);
}

fetchData()
  .then(data => console.log(data))
  .catch(error => console.error(error));

Promise.race() is used to race the fetchPromise against a timeoutPromise. If the fetch operation does not complete within 5 seconds, the timeoutPromise rejects, effectively canceling the fetch.

This approach is problematic because it shifts cancellation control away from the function that initially created the promise. This function is typically the ideal place for cleanup tasks like stopping timeouts or releasing memory resources. When cancellation control is external, these important cleanup activities might not be performed properly.

In the code example for aborting promises with race, if the timeout triggers first, there's no way to actually stop the fetch operation from continuing in the background, potentially wasting resources.

However, you can control the underlying asynchronous operations of promises even though promises themselves lack a built-in cancellation mechanism. For example, you can use an AbortController to abort a fetch request to a server.

const controller = new AbortController();
const signal = controller.signal;

const fetchData = () => {
  return fetch('https://api.example.com/data', { signal })
    .then((response) => response.json());
};

const dataPromise = fetchData();

setTimeout(() => {
  controller.abort();
}, 100);

dataPromise
  .then((data) => {
    console.log('Data:', data);
  })
  .catch((error) => {
    if (error.name === 'AbortError') {
      console.error('Fetch aborted');
    } else {
      console.error('Fetch error:', error);
    }
  });

Create an abort controller and a signal.

Use AbortController to cancel the fetch request after 100 milliseconds, which makes it likely that the server hasn't responded yet. While the promise itself isn't cancelled, the underlying operation is aborted, and the promise rejects with an AbortError. You can handle this error to know that the operation was intentionally cancelled.

Why Do You Need Promises?

Before Promises, handling asynchronous code often meant dealing with callback hell - nested callbacks that made code hard to read and maintain. Promises provide a cleaner, more robust way to handle asynchronous operations.

function getUser(userId, callback) {
  setTimeout(() => {
    if (!userId) return callback('Invalid user ID');
    callback(null, { id: userId, name: 'John Doe' });
  }, 100);
}

function getPosts(user, callback) {
  setTimeout(() => {
    if (!user) return callback('User not found');
    callback(null, [{ id: 1, title: 'Post 1' }]);
  }, 100);
}

function getComments(post, callback) {
  setTimeout(() => {
    if (!post) return callback('Post not found');
    callback(null, ['Comment 1', 'Comment 2']);
  }, 100);
}

getUser(userId, (error, user) => {
  if (error) {
    console.error('Error fetching user:', error);
    return;
  }
  getPosts(user, (error, posts) => {
    if (error) {
      console.error('Error fetching posts:', error);
      return;
    }
    getComments(posts[0], (error, comments) => {
      if (error) {
        console.error('Error fetching comments:', error);
        return;
      }
      console.log('First comment:', comments[0]);
    });
  });
});

Create three functions getUser, getPosts, and getComments that simulate asynchronous operations with callbacks.

Now, in order to fetch the data, you have to nest the callbacks. This code becomes messy and hard to follow due to the nested callbacks and repetitive error handling. Developers called this "callback hell" for a reason.

You can clean this up using promises to chain the asynchronous operations in a flat and readable manner.

// ... original callback-based functions ...

const promisify =
  fn =>
  (...args) =>
    new Promise((resolve, reject) => {
      fn(...args, (error, result) => {
        if (error) {
          return reject(error);
        }

        resolve(result);
      });
    });

const getUserAsync = promisify(getUser);
const getPostsAsync = promisify(getPosts);
const getCommentsAsync = promisify(getComments);

getUserAsync(userId)
  .then(user => getPostsAsync(user))
  .then(posts => getCommentsAsync(posts[0]))
  .then(comments => {
    console.log('First comment:', comments[0]);
  })
  .catch(error => {
    console.error('Error:', error);
  });

First, write a promisify function to convert callback-based functions into promise-returning functions.

Then, use the promisify function to convert your callback-based functions into promise-returning functions. This allows you to chain them using then, leading to cleaner and more maintainable code. Error handling is simplified with a single catch block at the end.

Promise Composition With `asyncPipe`

If you've read "Unleash JavaScript's Potential With Functional Programming", you know that you can compose functions together. If not, you want to read that article before continuing with the rest of this article because it assumes you are familiar with function composition.

In that article, you learn about the pipe function that composes functions in reverse mathematical order.

const pipe = (...fns) => x => fns.reduce((y, f) => f(y), x);

This pipe function can not be used with promise because promises need the then method.

But you can write an asyncPipe function that can compose promises.

const asyncPipe = (...fns) => x => fns.reduce((y, f) => y.then(f), Promise.resolve(x));

const asyncInc = async x => x + 1;
const asyncDouble = async x => x * 2;

const incrementAndDouble = asyncPipe(asyncInc, asyncDouble);

incrementAndDouble(20).then(console.log); // 42

Write a function asyncPipe that composes multiple promise-returning functions. It takes a list of promise-returning functions and returns a new function that applies them in sequence. When you call incrementAndDouble(20), it first increments 20 to 21 and then doubles it to 42.

But this version of asyncPipe only works with functions that return promises. What if you also want to compose regular functions together with asynchronous functions?

You can write asyncPipe using async / await.

const asyncPipe = (...fns) => x => fns.reduce(async (y, f) => f(await y), x);

const asyncInc = async x => x + 1;
const double = x => x * 2;
const asyncSquare = async x => x * x;

const incrementAndDouble = asyncPipe(asyncInc, double, asyncSquare);

incrementAndDouble(20).then(console.log); // 1764

Let's break down the steps in asyncPipe.

Step	Accumulator `y`	Current Function `f`	Explanation
1	`x` is `20`, so `y` is `20`	`asyncInc`	• You `await y`, which is `await 20`. Since `20` is not a promise, `await 20` returns `20`. • You then call `f(y)`, which is `asyncInc(20)`. This returns a promise because `asyncInc` is an async function. • Note: Even if `asyncInc` was synchronous (`inc`), since the reducer function uses `async` it always returns a promise. • The accumulator now holds a pending promise from `asyncInc(20)`.
2	Pending promise from `asyncInc(20)`	`double`	• You `await y`, which is `await asyncInc(20)`, resolving the promise to `21`. • You then call `f(y)`, which is `double(21)`, resulting in `42`. • Although `double` is synchronous, the reducer function uses `async`, so the accumulator holds a pending promise of `42`.
3	Pending promise of `42`	`asyncSquare`	• You `await y`, resolving the promise to `42`. • You then call `f(y)`, which is `asyncSquare(42)`. This returns a promise because `asyncSquare` is an async function. • The accumulator now holds a pending promise from `asyncSquare(42)`.
Final	Pending Promise from `asyncSquare(42)`	-	The `.then` handler causes the promise to resolve and logs `1764` to the console.

You might be asking yourself why you use await y instead of await f(y) in the reducer function inside asyncPipe. If you refactor asyncPipe to use await f(y), it won't work and the code example above returns NaN.

The reason for that is that because of async the accumulator y always returns a pending promise, so you need to await it. If you don't await it, the first step works because it would return await (asyncInc(20)), which is 21. But because of the async keyword in the reducer function, the accumulator would be a pending promise of 21. Then in the second step you would call await double(Promise.resolve(21)), which is NaN because Promise.resolve(21) * 2 would try to multiply an object - the promise - by two.

Composing promises allows you to chain asynchronous operations in a clean and maintainable way reaping all the benefits of functional programming.

Master Redux Action Best Practices & Make Debugging Easy

Jan Hesters — Tue, 11 Feb 2025 17:58:43 +0000

I recently released the first articles and videos on my YouTube channel as part of a series about Redux.

When I talked to my mentees, some of them struggled with getting their actions right. To be fair, even though actions seem simple, small mistakes can compound and lead to significant tech debt.

So, I wanted to write this bonus micro-lesson for you to lay out the best practices for actions in detail. Everything you're about to learn applies to any action design - whether you use vanilla Redux, Redux Toolkit, or React's built-in useReducer hook.

Before we jump into it, if you haven't read part one, "What Is Redux? (Get A Senior Understanding Of How Redux Works)" and part two, "Redux Saga Is Hard Until You Look Under The Hood", open them in a new tab and read them first. Then come back. This article assumes you know Redux's six building blocks and the basics of Redux Saga.

As a quick recap, Redux actions are objects with a type and an optional payload.

const loginClicked = {
  type: 'LOGIN_CLICKED',  payload: { email: 'jan@reactsquad.io', password: '5ub5cr1b3' },};

These actions usually come from action creators, which are functions that return action objects.

const loginClicked = (email, password) => ({
  type: 'LOGIN_CLICKED',  payload: { email, password },});

Descriptive Names

The first best practice is that your actions should have descriptive names. These names should describe what happened in your app rather than what the action does. This helps with debugging. Most people name their actions after what the action does, which makes it harder to understand their role in the context of your app.

Let me give you a real-world example that came up with one of my mentees. He wanted to practice what he had learned in the Redux videos and built a typing trainer game. In that game, the user types certain strings containing many special characters. With each keystroke, the game checks whether the user typed the correct characters, and if that user got everything right, it saves the level.

In the beginning, he designed his state with a single setInputString action.

export const setInputString = payload => ({
  type: 'SET_INPUT_STRING',  payload,});export const sliceName = 'typeTrainer';const initialState = {
  inputString: '',  levelString: '{}/^%*#!)@(',};export const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case setInputString().type: {
      return { ...state, inputString: payload };    }
    default: {
      return state;    }
  }
};export const selectTypeTrainerSlice = state => state[sliceName];export const selectInputString = state =>  selectTypeTrainerSlice(state).inputString;export const selectLevelString = state =>  selectTypeTrainerSlice(state).levelString;

He created a setInputString action that was dispatched whenever the user typed in the input field.

The state contained the current input string and the level string. The level string represented the text the user had to type correctly for each level.

In the reducer, he updated the state with the new input string.

Furthermore, he had selectors to read both the current input string and the level string.

This state is highly simplified because I only want to illustrate the importance of descriptive action names.

He also had a saga that listened for all changes to the input string and checked whether the user typed the correct characters.

import { put, takeLeading } from 'redux-saga/effects';import {
  selectInputString,  selectLevelString,  setInputString,} from './type-trainer-reducer';export function* handleInputString() {
  const inputString = yield select(selectInputString);  const levelString = yield select(selectLevelString);  if (inputString === levelString) {
    // Perform side effects like showing confetti or recording CPM.    // Example: yield put(showConfetti);    // Example: yield call(recordCharactersPerMinute);    // Reset the input string.    yield put(setInputString(''));  }
}
export function* watchInputString() {
  yield takeLeading(setInputString.type, handleSetInputString);}

The saga would listen to all changes in the input string and check whether the user typed the correct characters. If the user typed the correct characters, he used the setInputString action in the saga to reset the input string. In reality, the action was even used a third time to reset the input when the user made a mistake.

Now, here's how this example illustrates the problem with non-descriptive action names:

If there is a bug in the code, it's hard to trace where it came from. As a result, the sagas are also difficult to put into context. Right now, it looks like these sagas should run whenever the input string changes, even when triggered by themselves - such as during a reset.

To fix this issue, you should give the action a descriptive name that explains what just happened, rather than what the action does.

export const userTyped = payload => ({ type: 'USER_TYPED', payload });export const userSucceeded = () => ({ type: 'USER_SUCCEEDED' });export const sliceName = 'typeTrainer';const initialState = {
  inputString: '',  levelString: '{}/^%*#!)@(',};export const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case userTyped().type: {
      return { ...state, inputString: payload };    }
    case userSucceeded().type: {
      return { ...state, levelString: '' };    }
    default: {
      return state;    }
  }
};// ... selectors

Now, the action userTyped describes what happened. Additionally, you add a second action, userSucceeded, to describe what happened when the user typed the correct characters.

You can now use these actions in your saga.

import { put, takeLeading } from 'redux-saga/effects';import {
  selectInputString,  selectLevelString,  userSucceeded,  userTyped,} from './type-trainer-reducer';export function* handleUserTyped() {
  const inputString = yield select(selectInputString);  const levelString = yield select(selectLevelString);  if (inputString === levelString) {
    // Perform side effects like showing confetti or recording CPM.    // Example: yield put(showConfetti);    // Example: yield call(recordCharactersPerMinute);    // Reset the input string.    yield put(userSucceeded());  }
}
export function* watchUserTyped() {
  yield takeLeading(userTyped.type, handleUserTyped);}

Now you can see that the saga only listens to the userTyped action. When the user types the correct characters, the userSucceeded action is dispatched instead. This clearly communicates what the saga is doing within the app's functionality rather than just describing what the action does programmatically.

Named Parameters

Some action creators take multiple values in their payload.

const loginClicked = (email, password) => ({
  type: 'LOGIN_CLICKED',  payload: { email, password },});

You can make action creators easier to read by using named parameters.

If you've never heard of named parameters, they allow you to specify function arguments by explicitly naming each parameter and assigning it a value when calling the function. This makes it clear which value corresponds to which parameter and allows arguments to be provided in any order.

Technically, JavaScript doesn't support named parameters, so here is an example in Python, which does support named parameters.

def login(email, password):
    # TODO: Implement the login functionality    passlogin(email="user@example.com", password="securepassword123")

As mentioned above, you can call the function with the parameters in any order. So, both of these calls are equivalent:

login(email="user@example.com", password="securepassword123")
login(password="securepassword123", email="user@example.com")

In JavaScript, you can emulate named parameters by using an object as the parameter.

const loginClicked = ({ email, password }) => ({
  type: 'LOGIN_CLICKED',  payload: { email, password },});

When you now use the action, you are forced to name the arguments explicitly.

loginClicked({ email: 'jan@reactsquad.io', password: '5ub5cr1b3' });

This makes it obvious what each argument means.

Default Values

Using named parameters via an object is also a good way to set default values for the action.

const saveProfileAvatarImage = ({ image, alt = 'Your profile avatar' }) => ({
  type: 'SAVE_PROFILE_AVATAR_IMAGE',  payload: { image, alt },});

In this example, the alt parameter is optional. If you don't provide it, it will default to 'Your profile avatar'. This also gives you type inference for the action and your editor knows that the alt property should be a string.

Data Transformations

Action creators can transform data. For example, if you receive a date object that isn't serializable, you can convert it to a string.

const saveDate = date => ({
  type: 'SAVE_DATE',  payload: date.toISOString(),});

As long as the action creator remains a pure function, you can freely perform data transformations and even use array methods like .map(), .filter(), .reduce(), and others. This also applies to the action handlers in your reducer's cases. And you usually perform complex transformations in your reducer case handlers. However, I wanted to point out that, in theory, you can also perform pure data transformations within your action creator.

Named Properties On Payloads

In this previous example, you saw that the action creator returns the date directly as the payload. Therefore, when you debug your Redux app, you only see that there is a date string on the object, but you don't know what it means.

action SAVE_DATE @ 12:34:56.789
  prev state  { ...previousState }
  action      {
    type: 'SAVE_DATE',
    payload: '2024-12-14T00:00:00.000Z'
  }
  next state  { ...nextState }

You can make it possible for people to understand what the date means, by giving the payload a named property.

const saveDate = date => ({
  type: 'SAVE_DATE',  payload: { currentBackupDate: date.toISOString() },});

When you log out the action, you see that the payload contains a currentBackupDate property.

action SAVE_DATE @ 12:34:56.789
  prev state  { ...previousState }
  action      {
    type: 'SAVE_DATE',
    payload: { currentBackupDate: '2024-12-14T00:00:00.000Z' }
  }
  next state  { ...nextState }

This lets your coworkers - or your future self - know that the date in the payload is when the backup was created.

You can combine this with named properties for your arguments to make your actions even more expressive.

const saveDate = ({ currentBackupDate }) => ({
  type: 'SAVE_DATE',  payload: { currentBackupDate: currentBackupDate.toISOString() },});

While this doesn't change the logging output, it makes it easier to understand what the arguments mean when you see the action in your code.

Actions Can Have Multiple Effects

Another mentee of mine created a login flow in Redux. It consisted of four actions: loginClicked, userFetched, showToast and finishLogin. He set loading when login started, set the user when fetched, and finished the login when done. He also showed a toast.

He had a reducer that would handle the login state and the user profile.

export const loginClicked = ({ email, password }) => ({
  type: 'LOGIN_CLICKED',  payload: { email, password },});export const userFetched = () => ({ type: 'USER_FETCHED' });export const finishLogin = () => ({ type: 'FINISH_LOGIN' });const initialState = {
  email: '',  password: '',  isLoading: false,  user: null,};export const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case loginClicked().type: {
      return { ...state, isLoading: true };    }
    case userFetched().type: {
      return { ...state, user: payload };    }
    case finishLogin().type: {
      return { ...state, isLoading: false };    }
    default: {
      return state;    }
  }
};

This reducer was responsible for three actions: loginClicked, userFetched, and finishLogin.

When the login was clicked, he set the loading state to true. When the user was fetched, he set the user profile. And when the login was finished, he set the loading state to false.

He also had a toast reducer that would display a toast message, for example, when the login was successful.

export const showToast = message => ({ type: 'SHOW_TOAST', payload: message });const initialState = {
  message: '',};export const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case showToast().type: {
      return { ...state, message: payload };    }
    default: {
      return state;    }
  }
};

Again, I'm simplifying the code in all of these examples to illustrate the point.

He used all of these actions in his saga.

import { call, put, takeLeading } from 'redux-saga/effects';import { showToast } from './toast-reducer';import { login } from './user-authentication-api';import {
  finishLogin,  loginClicked,  userFetched,} from './user-authentication-reducer';function* handleLoginClicked({ payload: { email, password } }) {
  const user = yield call(login, email, password);  yield put(userFetched(user));  yield put(finishLogin());  yield put(showToast('Login successful'));}
export function* watchLoginClicked() {
  yield takeLeading(loginClicked().type, handleLoginClicked);}

If you paid attention, you'll notice that he already did many things right. He named some actions descriptively, which also led to well-named sagas. He was also reusing the same actions in multiple places—for example, the loginClicked action both modified the state and started the handleLoginClicked saga. However, he structured his code in a way that required dispatching too many actions.

When the login succeeds, the only meaningful event is that the login was successful. There's no need to design the consequences so granularly.

He fixed this by creating a single action, loginSucceeded, which is dispatched when the login is successful.

export const loginClicked = ({ email, password }) => ({
  type: 'LOGIN_CLICKED',  payload: { email, password },});export const loginSucceeded = user => ({
  type: 'LOGIN_SUCCEEDED',  payload: { user },});const initialState = {
  email: '',  password: '',  isLoading: false,  user: null,};export const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case loginClicked().type: {
      return { ...state, isLoading: true };    }
    case loginSucceeded().type: {
      return { ...state, isLoading: false, user: payload.user };    }
    default: {
      return state;    }
  }
};

Notice how he designed the loginSucceeded action with named properties to take the user as an argument while still including it in the payload as a key-value pair in an object. As you learned earlier, this approach makes it easier to see what the payload contains when using logging middleware or Redux DevTools.

Now, you can use the action in the saga to consolidate two dispatch calls into one.

import { call, put, takeLeading } from 'redux-saga/effects';import { showToast } from './toast-reducer';import { login } from './user-authentication-api';import { loginClicked, loginSucceeded } from './user-authentication-reducer';function* handleLoginClicked({ payload: { email, password } }) {
  const user = yield call(login, email, password);  yield put(loginSucceeded(user));  yield put(showToast('Login successful'));}
export function* watchLoginClicked() {
  yield takeLeading(loginClicked().type, handleLoginClicked);}

Multiple Reducers Can Handle The Same Action

You might have noticed that a separate action, showToast, is still being dispatched in the saga.

Another important best practice for actions is that it's okay for multiple reducers to handle the same action. Instead of dispatching showToast, let the toast reducer also respond to loginSucceeded:

import { loginSucceeded } from './user-authentication-reducer';export const showToast = message => ({ type: 'SHOW_TOAST', payload: message });const initialState = {
  message: '',};export const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case showToast().type: {
      return { ...state, message: payload };    }
    case loginSucceeded().type: {
      return { ...state, message: 'Login successful' };    }
    default: {
      return state;    }
  }
};

You import the loginSucceeded action from user-authentication-reducer.js and create a case for it in toast-reducer.js.

The handler for the loginSucceeded action ignores the payload. You don’t need to pass a message as the payload because the toast message is always the same when login succeeds.

Now, you can remove the showToast action from the saga because loginSucceeded implicitly shows the toast.

import { call, put, takeLeading } from 'redux-saga/effects';import { login } from './user-authentication-api';import { loginClicked, loginSucceeded } from './user-authentication-reducer';function* handleLoginClicked({ payload: { email, password } }) {
  const user = yield call(login, email, password);  yield put(loginSucceeded(user));}
export function* watchLoginClicked() {
  yield takeLeading(loginClicked().type, handleLoginClicked);}

Dispatching The Same Action In Multiple Places

When we refactored his code like this during a mentoring session, the mentee asked:

“What if the loginSucceeded action is used in multiple places? For example, if there are different sagas for different login strategies (e.g., Google, email/password, etc.)?”

The answer is that if the reducers' behavior should be the same, you can use the same action. If they are different, you should use distinct actions that describe exactly what happened differently. Instead of loginSucceeded, you could have loginSucceededWithGoogle and loginSucceededWithEmailPassword, and so on. This ties back to the first point about using descriptive action names. You will see code for this in the next section.

In conclusion, one action can either be dispatched in multiple sagas or on clicks in different places in your app. And this one action can be handled in the case of different reducers and simultaneously trigger different sagas.

Multiple Actions Causing The Same State Update (With State Update Helpers)

Going back to the example from above with different login strategies, assume that there is an email and a Google login strategy. Both should cause the same user authentication state updates (flip the boolean, set the user), but they should show different toast messages.

Here is how the reducer looks like:

export const loginWithEmailClicked = ({ email, password }) => ({
  type: 'LOGIN_WITH_EMAIL_CLICKED',  payload: { email, password },});export const loginWithGoogleClicked = () => ({
  type: 'LOGIN_WITH_GOOGLE_CLICKED',});export const loginSucceededWithEmail = user => ({
  type: 'LOGIN_SUCCEEDED_WITH_EMAIL',  payload: { user },});export const loginSucceededWithGoogle = user => ({
  type: 'LOGIN_SUCCEEDED_WITH_GOOGLE',  payload: { user },});const initialState = {
  email: '',  password: '',  isLoading: false,  user: null,};const startAuthentication = state => ({ ...state, isLoading: true });const loginSucceeded = (state, { user }) => ({
  ...state,  isLoading: false,  user,});export const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case loginWithEmailClicked().type: {
      return startAuthentication(state);    }
    case loginWithGoogleClicked().type: {
      return startAuthentication(state);    }
    case loginSucceededWithEmail().type: {
      return loginSucceeded(state, payload);    }
    case loginSucceededWithGoogle().type: {
      return loginSucceeded(state, payload);    }
    default: {
      return state;    }
  }
};

There are two different actions depending on which strategy the user selected. Additionally, two actions are dispatched when either of the login strategies succeeds.

Since they trigger the same state update, the state updates can be abstracted into helper functions - startAuthentication and loginSucceeded - which are then used in the respective cases.

Here's how the sagas would use these actions.

import { call, put, takeLeading } from 'redux-saga/effects';import { loginWithEmail, loginWithGoogle } from './user-authentication-api';import {
  loginSucceededWithEmail,  loginSucceededWithGoogle,  loginWithEmailClicked,  loginWithGoogleClicked,} from './user-authentication-reducer';/*Email login*/function* handleLoginWithEmailClicked({ payload: { email, password } }) {
  const user = yield call(loginWithEmail, email, password);  yield put(loginSucceededWithEmail(user));}
export function* watchLoginWithEmailClicked() {
  yield takeLeading(loginWithEmailClicked().type, handleLoginWithEmailClicked);}
/*Google login*/function* handleLoginWithGoogleClicked() {
  const user = yield call(loginWithGoogle);  yield put(loginSucceededWithGoogle(user));}
export function* watchLoginWithGoogleClicked() {
  yield takeLeading(
    loginWithGoogleClicked().type,    handleLoginWithGoogleClicked,  );}

You create two sagas that listen for the respective actions and dispatch the corresponding login success actions.

You also need to add a case to the toast reducer for each strategy because they should display different toast messages.

import {
  loginSucceededWithEmail,  loginSucceededWithGoogle,} from './user-authentication-reducer';export const showToast = message => ({ type: 'SHOW_TOAST', payload: message });const initialState = {
  message: '',};export const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case showToast().type: {
      return { ...state, message: payload };    }
    case loginSucceededWithEmail().type: {
      return { ...state, message: 'Email login successful' };    }
    case loginSucceededWithGoogle().type: {
      return { ...state, message: 'Google login successful' };    }
    default: {
      return state;    }
  }
};

In this example, you saw that the loginWithEmailClicked and loginWithGoogleClicked actions cause the same state update. And the loginSucceededWithEmail and loginSucceededWithGoogle actions cause the same state update in one reducer, but different state updates in another reducer.

Attaching `type` as a Static Property

The last point that confused people was encountering actions with a static type property, used like this:

// ... in some-reducer.jsconst reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case someAction.type: {
      // Handle action    }
  }
};// ... in some-saga.jsfunction* watchSomeAction() {
  yield takeEvery(someAction.type, handleSomeAction);}

This pattern sometimes appears, especially with Redux Toolkit's createAction, which your learn in the third article of this series.

When creating actions manually, some developers like to attach the type as a static property to the action:

const someAction = payload => ({ type: someAction.type, payload });someAction.type = 'SOME_ACTION';const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case someAction.type: {
      return { ...state, message: payload };    }
    // ...  }
};function* watchSomeAction() {
  yield takeEvery(someAction.type, handleSomeAction);}

This pattern has two main benefits:

It avoids creating unnecessary action objects when calling the action to determine the type for the case or when hooking up sagas.
If you have actions with transformations that require data, you can't call them without arguments, like we did above in cases and when hooking up sagas.

const explodeWithoutArgs = data => ({
  type: explodeWithoutArgs.type,  payload: data.toUpperCase(), // This will throw if data is undefined});explodeWithoutArgs.type = 'EXPLODE_WITHOUT_ARGS';const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case explodeWithoutArgs.type: {
      return { ...state, message: payload };    }
    case explodeWithoutArgs().type: { // This would crash ❌      return { ...state, message: payload };    }
    // ...  }
};

Of course, you can avoid this, if you instead transform the data in the respective cases action handler instead.

This difference is small and stylistic. It comes down to preference.

Redux Toolkit

Everything you learned in this article also applies when creating slices with createSlice from Redux Toolkit (RTK).

My recent articles on Redux received some negative feedback because I'm showing Redux without RTK, and many people prefer using RTK. But I believe many fundamentals are easier to understand with vanilla Redux because learning RTK then becomes just a matter of learning the new API syntax.

Anyway, here's how the toast reducer would look with RTK. (Note: You might want to open this article in another tab and compare the two versions of the toast reducer side by side.)

import type { PayloadAction } from '@reduxjs/toolkit';import { createSlice } from '@reduxjs/toolkit';import {
  loginSucceededWithEmail,  loginSucceededWithGoogle,} from './user-authentication-reducer';export const {
  actions: { showToast },  reducer,} = createSlice({
  name: 'auth',  initialState: {
    message: '',  },  reducers: {
    showToast(state, action: PayloadAction<string>) {
      state.message = action.payload;    },  },  extraReducers: builder => {
    builder
      .addCase(loginSucceededWithEmail, state => {
        state.message = 'Email login successful';      })
      .addCase(loginSucceededWithGoogle, state => {
        state.message = 'Google login successful';      });  },});

You can use the createSlice function to create your reducers.

You define the showToast action creator in the reducers object.

And you react to the loginSucceededWithEmail and loginSucceededWithGoogle actions in the extraReducers object.

The syntax of Redux Toolkit is explained in depth in the third article of this series on Redux, so go read that one next.

Redux Saga Is Hard Until You Look Under The Hood

Jan Hesters — Tue, 11 Feb 2025 17:16:12 +0000

Redux Saga has a reputation for being hard to understand and is often seen as overkill.

The Redux team even recommends to use their data fetching and caching library, RTK Query, instead of Redux Saga.

However, when you master Redux Saga, it actually gives a reliable way to break down any problem - no matter how complex - and tame it into deterministic and side effect-free code.

I wanted to write this article about sagas for you because:

Sagas are still used in many old projects and can help you land more jobs,
the philosophy of isolating side effects that sagas teach you will change how you think about your code and help you to write cleaner code, and
I love sagas.

This article is part 2 of a 5-part series on Redux that will elevate your understanding to the highest level, preparing you for any interview question involving Redux and enabling you to contribute to any Redux-based codebase. By the way, the third article in this series also covers how to use RTK Query.

The first part of the series covers Redux on a senior level. In that article, you learn how Redux works by implementing it from scratch, and then how to write the cleanest Redux code possible using function composition. If you feel stuck at any point in this article, read part one first.

Why Redux Saga?

Let's start with the basic question:

“Why do you want to use Redux Saga?”

Isolate asynchronous effects - Manage your side effects separately from your main application logic. Your components don't need to know that side effects exist.

Deterministic testing of I/O related logic - When you test code with side effects, you're frequently forced to mock, especially when you’re unsure of what you’re doing. But Redux Saga makes it trivial to write tests for your API calls, database operations and other I/O tasks.

If you want to, you can code along with this tutorial. If not, then skip to "What Is Redux Saga?" below.

This article will show the basic setup of your Redux store very quickly because it's covered in detail in the first article of this series.

Create a new Next.js project and choose "yes" for everything except TypeScript.

$ npx create-next-app@latest
✔ **What is your project named?** … 2024-08-20-redux-saga
✔ **Would you like to use** **TypeScript****?** … No / Yes
No✔ **Would you like to use** **ESLint****?** … No / Yes
Yes✔ **Would you like to use** **Tailwind CSS****?** … No / Yes
Yes✔ **Would you like to use** **`src/` directory****?** … No / Yes
Yes✔ **Would you like to use** **App Router****? (recommended)** … No / Yes
Yes✔ **Would you like to customize the default** **import alias** **(@/*)?** … No / Yes
No

The third article in this series explains Redux with TypeScript.

Now install Redux, React Redux, and Ramda.

npm i redux react-redux ramda

Create a file in src/features/example/example-reducer.js to hold your example slice.

import { pipe, prop } from 'ramda';// slice (the name of the example-substate)export const slice = 'example';// action creatorsexport const increment = () => ({ type: `${slice}/increment` });export const incrementBy = payload => ({
  type: `${slice}/incrementBy`,  payload,});const initialState = {
  count: 0,};// example reducer using the action creators, taking in state and actionsexport const reducer = (state = initialState, { type, payload } = {}) => {
  switch (type) {
    case increment().type: {
      return { ...state, count: state.count + 1 }; // "action handler"    }
    case incrementBy().type: {
      return { ...state, count: state.count + payload };    }
    default: {
      return state;    }
  }
};// composed selector(s)const selectExampleState = prop(slice);export const selectCount = pipe(selectExampleState, prop('count'));

Import pipe and prop from Ramda, which you'll use for your selectors.

Then export the slice name and create an increment , an incrementBy and an init action creator.

Your initial state should have a count key which is 0. Then you define your example reducer, which can handle the increment and the incrementBy action.

Then create a selector that returns the example slice and export a selector that returns the count.

Create your rootReducer in src/redux/root-reducer.js.

import { combineReducers } from 'redux';import {
  reducer as exampleReducer,  slice as exampleSlice,} from '../../features/example/example-reducer';export const rootReducer = combineReducers({
  [exampleSlice]: exampleReducer,});

You only have the example slice, so you'll only need to configure that one slice.

Then create your makeStore function in src/redux/store.js to wrap the creation of your Redux store.

import { legacy_createStore as createStore } from 'redux';import { rootReducer } from './root-reducer';export const makeStore = () => {
  return createStore(rootReducer, rootReducer());};

You can call your root reducer without arguments to get the initial state.

Now create your store provider in src/redux/store-provider.js.

'use client'; // The Redux provider is only available client side because// it uses the context API under the hood.import { useRef } from 'react';import { Provider } from 'react-redux';import { makeStore } from '../redux/store';export function StoreProvider({ children }) {
  const storeRef = useRef();  if (!storeRef.current) {
    storeRef.current = makeStore();  }
  return <Provider store={storeRef.current}>{children}</Provider>;}

Import the makeStore function and use useRef so your store only gets created once. Then pass your store to the provider from React Redux.

import { useDispatch, useSelector, useStore } from 'react-redux';export const useAppDispatch = useDispatch.withTypes();export const useAppSelector = useSelector.withTypes();export const useAppStore = useStore.withTypes();

Also set up the hooks for dispatching actions and grabbing data from the store.

Then import your StoreProvider in your root layout in src/app/layout.js and wrap the StoreProvider around your RootLayout.

import './globals.css';import { Inter } from 'next/font/google';import { StoreProvider } from './store-provider';const inter = Inter({ subsets: ['latin'] });export const metadata = {
  title: 'Jan Hesters Sagas Tutorial',  description: 'Part two of five to master Redux.',};export default function RootLayout({ children }) {
  return (
    <StoreProvider>      <html lang="en">        <body className={inter.className}>{children}</body>      </html>    </StoreProvider>  );}

You can now access store values via selectors and manipulate them using dispatch from any child component of the StoreProvider.

What Is Redux Saga?

Redux Saga is a middleware that uses generators to:

manage side effects and manipulate actions,
decouple your code, and
define complex logic flows, sequences and data processes.

Sagas typically transform impure functions - like database calls or API requests - into pure, deterministic ones by isolating side effects through delaying their computation.

"Decoupling code" means to slice your app into small, independent blocks, so that your app's components depend less on each other. When components are decoupled, you can work on them without the risk of breaking anything else. If components are coupled, changing one might unintentionally break something else.

With Redux Saga you can decouple your code because you can define complex sequences of asynchronous operations in a way that keeps them separate from your UI and state management logic. For example, sagas can replace complex sequences in useEffect with easy to implement and decoupled logic.

Have a look at the following saga.

import { call, put, select, take } from 'redux-saga/effects';import { increment, incrementBy, selectCount, slice } from './example-reducer';export const init = () => ({ type: `${slice}/init` });const fetchUser = async id => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/users/${id}`,  );  return await response.json();};export function* exampleSaga() {
  yield take(init().type);  yield put(increment());  const currentCount = yield select(selectCount);  const user = yield call(fetchUser, currentCount);  yield put(incrementBy(user.name.length));}

Relax if you don't understand this, yet. This article will break everything down for you.

All dispatched actions anywhere in your app run though all sagas, and if the action corresponds to the condition of a saga, the saga triggers. When the init action is dispatched, this saga starts running.

Then this saga dispatches the put action, grabs the latest count from the store, and fetches a user whose ID is equal to the current count. Finally, it increments the count by the user's name's length.

The logic that handles all of these effects will be shown to you and explained later in the saga middleware chapter.

If you log out what this saga does, you get this output.

dispatching { "type": "example/init" }
next state { "example": { "count": 0 } }
dispatching { "type": "example/increment" }
next state { "example": { "count": 1 } }
dispatching { "type": "example/incrementBy", "payload": 13 }
next state { "example": { "count": 14 } }

First, the init action is dispatched somewhere in your app triggering your saga. And then you see the incrementation of the count by 1 and then the incrementation by 13 because the user with ID 1 is named "Leanne Graham".

If you tried to write this flow without sagas as a React component, you might write something that uses useEffects and various other hooks. Just to give you an idea, here is what it could look like:

import { useEffect, useRef } from 'react';import { increment, incrementBy, init, selectCount } from './example-reducer';import { useAppDispatch, useAppSelector } from './hooks';async function fetchUser(id) {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/users/${id}`,  );  return await response.json();}
export function MyComponent() {
  const dispatch = useAppDispatch();  const currentCount = useAppSelector(selectCount);  const hasFetched = useRef(false);  useEffect(() => {
    dispatch(init());    dispatch(increment());  }, [dispatch]);  useEffect(() => {
    const fetchAndIncrement = async () => {
      try {
        const user = await fetchUser(currentCount);        dispatch(incrementBy(user.name.length));        hasFetched.current = true;      } catch (error) {
        console.error('Failed to fetch user:', error);      }
    };    if (currentCount > 0 && !hasFetched.current) {
      fetchAndIncrement();    }
  }, [currentCount, dispatch]);  return <p>Current Count: {currentCount}</p>;}

I'll spare you the details, but as you can see, writing this logic as a React component is already more complex and is not providing all of the logic we want and get from sagas.

"I actually want to know the details."

Sure, here you go:

In the first article of this series, you learned how to use hooks to access dispatch and the store's state.

Now, when the component runs, it dispatches init and increment. After incrementing the count, it fetches the user and increments the count by the length of the user's name. You use useRef to prevent infinite loops since incrementing the count would cause the second useEffect to run again.

The logic of this React component is actually different from the saga you saw earlier. The saga starts when init is dispatched. But to replicate that behavior with hooks, you'd need to create a condition in the store's state, which is set to "true" when init is dispatched, and then react to it inside useEffect. So you can already see, how implementing complex sequences is easier with sagas than with React components and hooks.

I know this was a lot, but now you have a big-picture overview, so you can learn all the details easier.

What Are Redux Saga's Components?

Redux Saga consists of three components:

Effects - Effects are action creators that describe future actions.
Sagas - Sagas are generator functions that manage side effects.
Middleware - The middleware, which contains effect handlers, manages the execution of the sagas and the corresponding effects.

Effects

Redux Saga uses special kinds of action creators called "effects". Effects are instructions for the handlers in the saga middleware. These effect handlers execute the actual mechanism of the effect.

This article will cover the most important effects. Once you finished reading this article, you'll find it easy to look up and understand the less common effects in the Redux Saga documentation.

You're going to start with the take effect.

Here is what happens when you import the take effect, call it, and log it out.

import { take } from 'redux-saga/effects';console.log(take('increment'));

It logs out an object to the console.

{  '@@redux-saga/IO': true,
  combinator: false,
  type: 'TAKE',
  payload: { pattern: 'increment' }
}

As you can see, since all effects are action creators, they include a type and payload property.

But there are also two additional properties.

@@redux-saga/IO: This property shows that the object is a Redux-Saga effect. Redux-Saga middleware recognizes and processes only actions with this property, but ignores any other action. This way the middleware only processes actions it is meant to process.
combinator: This property indicates whether the effect is a combinatorial effect, which is used to run multiple effects in parallel or sequentially. Since take is a simple effect to pause a saga, this property is false.

`take`

What is special about the take effect? Or in other words, what is take used for?

The take effect is used to pause a saga until a specific action is dispatched to the Redux store. When the specified action type arrives, the saga continues execution.

As you explore the different effects, create them in a file at src/redux/effects.js.

export const take = pattern => ({
  '@@redux-saga/IO': true,  type: 'TAKE',  payload: { pattern },});

pattern is an action type. It's the type of the action that needs to be dispatched to cause the saga to continue. (If a take effect was yielded in your saga, the pattern on its payload tells the effect handlers in the saga middleware what type of action should resume the saga.)

You can leave out the combinator property in your own actions since implementing that behavior is complex and unnecessary for a deep understanding of sagas. If you're curious, you can explore the Redux Saga source code later.

`put`

Take a look at another effect called put.

import { put } from 'redux-saga/effects';console.log(put({ type: 'increment' }));

Like any effect, when you call it and log it out, it also returns an action.

{  '@@redux-saga/IO': true,
  combinator: false,
  type: 'PUT',
  payload: { channel: undefined, action: { type: 'increment' } }
}

The put effect describes an action to be dispatched by the effect handlers once the saga iteration triggers the invocation of this effect. (TODO: record this)

The action has a similar shape as the returned object from the take effect, but the payload contains a channel and an action.

Channels in Redux-Saga can be used for more complex communication patterns, but for standard put effects dispatching actions to the store, this remains undefined.

The action property contains the action object that will be dispatched. In your example, it is { type: 'increment' }.

Add put to your custom effects.

export const take = pattern => ({
  '@@redux-saga/IO': true,  type: 'TAKE',  payload: { pattern },});export const put = action => ({
  '@@redux-saga/IO': true,  type: 'PUT',  payload: { action },});

As mentioned earlier, you can omit the channel property because it's undefined anyway for simple put effects.

Sagas

The term "saga" in Redux Saga comes from a 1987 paper by Hector Garcia-Molina and Kenneth Salem. Their work describes a way to handle long-lived database transactions by breaking them into smaller parts with backup plans if something goes wrong.

Redux Saga adapts this idea to manage complex asynchronous tasks and side effects in app state management using generator functions. The name "saga" reflects the long-running, intricate processes this middleware handles, much like the complex stories found in historical sagas.

If you're unfamiliar with generators, read "JavaScript Generators Explained, But On A Senior-Level". That article will give you all the foundational knowledge you need to understand sagas.

It's time to use your custom effects in a saga generator in src/features/example/example-sagas.js.

import { put, take } from '../../redux/effects';import { increment, slice } from './example-reducer';export const init = () => ({ type: `${slice}/init` });export function* exampleSaga() {
  yield take(init().type);  yield put(increment());}

Import the increment action creator and your custom effects.

Then, create an init action creator that you will use to trigger your saga. This action only needs a type property to start the saga once it is dispatched for the first time anywhere in your app.

In your saga, use the take effect to wait for the init action to be dispatched, then use the put effect to dispatch the increment action.

import { put, take } from '../../redux/effects';import { increment, slice } from './example-reducer';export const init = () => ({ type: `${slice}/init` });export function* exampleSaga() {
  const action = yield take(init().type);  console.log('action', action);  yield put(increment());}
// In reality, this call 👇 happens inside of the middleware (covered later).const iterator = exampleSaga();
 // Start the saga and log the first yield.console.log('First next(): ', iterator.next()); // Simulate receiving the init action and log the second yield.console.log('Second next(): ', iterator.next(init())); // Complete the saga.console.log('Third next(): ', iterator.next());

Now, create a generator object using your saga. Then call .next() three times. When you call .next() for the second time, pass the init action creator to the .next() method, which simulates what the saga middleware would do behind the scenes.

$ npx tsx src/features/example/example-sagas.js
First next():  { value: { '@@redux-saga/IO': true, type: 'TAKE', payload: { pattern: 'example/init' } }, done: false }
action { type: 'example/init' }
Second next():  { value: { '@@redux-saga/IO': true, type: 'PUT', payload: { action: { type: 'example/increment' } } }, done: false }
Third next():  { value: undefined, done: true }

If you run this code, you see the take effect with the "init" pattern. Next, you see the put effect with the increment action. And finally, the generator is done.

As you can see, there is no magic here. The saga is just a generator.

Saga Middleware

The saga "magic" really happens in the middleware. The middleware is responsible for correctly handling the effects and passing them to all your sagas.

Create createSagaMiddleware function in src/redux/saga-middleware.js.

import { put, take } from './effects';export function createSagaMiddleware() {
  let sagas = [];  const middleware = store => next => action => {
    const result = next(action);    sagas.forEach(saga => {
      const sagaIterator = saga();      let effectHandled = false;      const handleEffect = async effect => {
        if (!effect || !effect['@@redux-saga/IO']) {
          effectHandled = true;          return;        }
        switch (effect.type) {
          case take().type: {
            if (effect.payload.pattern === action.type) {
              return action;            } else {
              effectHandled = true;              return;            }
          }
          case put().type: {
            store.dispatch(effect.payload.action);            return;          }
          default: {
            effectHandled = true;            return;          }
        }
      };      const processSaga = async () => {
        let lastValue;        try {
          while (!effectHandled) {
            // lastValue is the return value of the previously handled effect.            const { value, done } = sagaIterator.next(lastValue);            if (done) {
              break;            }
            lastValue = await handleEffect(value);          }
        } catch (error) {
          sagaIterator.throw(error);        }
      };      processSaga();    });    return result;  };  middleware.run = saga => {
    sagas.push(saga);  };  return middleware;}

Import your two custom effects.

Next, define and export a new function called createSagaMiddleware.

It defines an array of sagas in its closure.

Then it defines the middleware with the typical three parameters: store, next and action. Call the next middleware with the action to create a result. It is later returned as the final output after all effects have been processed to keep the middleware chain going.

Now, it iterates through all the sagas.

For each saga, it generates a new iterator. Then, it sets up effectHandled, which it initializes to false.

Now it defines the handleEffect function. The effect argument is the value of the generator objects that your sagas yield.

If the effect is undefined or lacks the @@redux-saga/IO key, it sets effectHandled to true and returns early, so the saga ignores the effect.

Next, it creates a switch statement to handle specific effects.

It starts with a handler for the take effect. If a take effect was yielded in your saga, that means it has a pattern on its payload which tells you the type of action that should resume the saga. If the current action matches this type, the handler returns it. If not, it marks the effect as handled and return.

For the put effect, the handler simply dispatches the action from the effect's payload using store.dispatch.

For any unhandled effect type, the middleware marks the effect as handled, too.

Next, it defines a processSaga function. While the effect is NOT handled, it calls the .next() method on the current saga iterator, passing it the last value. The first .next() is always called without an argument because last value starts as undefined. If the saga is done, it stops the while loop using the break keyword. Then it computes the latest value by using the handleEffect function. This lastValue gets inserted as the argument into the next .next() call. Later, you will see that handleEffect can work with promises, so processSaga needs to await it. If an error happens, it catches it and passes it into the saga using the .throw() method.

Finally, the middleware returns the result as you would with any middleware.

Define a .run() method on your saga middleware. This is the mechanism you use to push new sagas into the array. Finally, createSagaMiddleware returns the created middleware.

This implementation of the saga middleware is simplified for learning purposes. For example, take effects can only be used as the first effect in a saga because each dispatch because calls all saga iterators from scratch through the forEach loop. With the real implementation from the Redux Saga package, you can use take anywhere in the saga. However, this version gives you a solid foundational understanding.

Now modify your makeStore function to use your createSagaMiddleware function.

import { applyMiddleware, legacy_createStore as createStore } from 'redux';import { exampleSaga } from '../features/example/example-sagas';import { rootReducer } from './root-reducer';import { createSagaMiddleware } from './saga-middleware';const logger = store => next => action => {
  console.log('dispatching', action);  let result = next(action);  console.log('next state', store.getState());  return result;};export const makeStore = () => {
  const sagaMiddleware = createSagaMiddleware();  const store = createStore(
    rootReducer,    rootReducer(),    applyMiddleware(logger, sagaMiddleware),  );  sagaMiddleware.run(exampleSaga);  return store;};

Import your exampleSaga and your createSagaMiddleware function.

Then create a logger middleware. You're going to use it to show the behavior of the saga.

Use your createSagaMiddleware function inside of your makeStore function to create your middleware. Then, pass both middleware to Redux's createStore function. Call the .run() method and pass in your exampleSaga.

Now you need to dispatch the init action in your store provider.

'use client';import { useRef } from 'react';import { Provider } from 'react-redux';import { init } from '../features/example/example-sagas';import { makeStore } from '../redux/store';export function StoreProvider({ children }) {
  const storeRef = useRef();  if (!storeRef.current) {
    storeRef.current = makeStore();    storeRef.current.dispatch(init());  }
  return <Provider store={storeRef.current}>{children}</Provider>;}

You only dispatch init from inside your StoreProvider in this tutorial to start your saga. In the real world, you probably wouldn't do this.

If you now run your app and visit http://localhost:3000/, you'll see increment action dispatched after your init action.

dispatching { "type": "example/init" }
next state { "example": { "count": 0 } }
dispatching { "type": "example/increment" }
next state { "example": { "count": 1 } }

This means your exampleSaga works. Your take catches the init action, and then your saga keeps running and dispatches the increment action using the put effect.

`select`

You've learned how to "catch" actions with take and how you can dispatch actions with put in your saga.

What if you want to grab some state using a selector to use it in your saga?

That's where the select effect comes in.

import { select } from 'redux-saga/effects';console.log(select(selectCount, 42, 'foo', true));

If you log it out, it also returns an action.

{  '@@redux-saga/IO': true,
  combinator: false,
  type: 'SELECT',
  payload: { selector: [Function (anonymous)], args: [42, 'foo', true] }
}

The select effect is used for retrieving data from the Redux store. Its payload contains a selector function and optional args.

The args are additional arguments passed to the selector, if needed. This can be useful if you have a selector that selects a specific user by id.

export const take = pattern => ({
  '@@redux-saga/IO': true,  type: 'TAKE',  payload: { pattern },});export const put = action => ({
  '@@redux-saga/IO': true,  type: 'PUT',  payload: { action },});export const select = (selector, ...arguments_) => ({
  '@@redux-saga/IO': true,  type: 'SELECT',  payload: { selector, args: arguments_ },});

Add select to your collection of custom select effects.

import { put, select, take } from '../../redux/effects';import { increment, selectCount, slice } from './example-reducer';export const init = () => ({ type: `${slice}/init` });export function* exampleSaga() {
  yield take(init().type);  yield put(increment());  const currentCount = yield select(selectCount);  console.log('currentCount', currentCount);}

Next, import your selectCount selector and the select effect into your example saga. Use them to grab the current count from your store within the saga.

If you’re coding along, try implementing the handling of the select effect in your saga-middleware on your own.

...

Are you done? Here is the solution.

import { put, select, take } from './effects';export function createSagaMiddleware() {
  let sagas = [];  const middleware = store => next => action => {
    const result = next(action);    sagas.forEach(saga => {
      const sagaIterator = saga();      let effectHandled = false;      const handleEffect = async effect => {
        if (!effect || !effect['@@redux-saga/IO']) {
          effectHandled = true;          return;        }
        switch (effect.type) {
          case take().type: {
            if (effect.payload.pattern === action.type) {
              return action;            } else {
              effectHandled = true;              return;            }
          }
          case put().type: {
            store.dispatch(effect.payload.action);            return;          }
          case select().type: {
            return effect.payload.selector(
              store.getState(),              ...effect.payload.args,            );          }
          default: {
            effectHandled = true;            return;          }
        }
      };      const processSaga = async () => {
        let lastValue;        try {
          while (!effectHandled) {
            const { value, done } = sagaIterator.next(lastValue);            if (done) {
              break;            }
            lastValue = await handleEffect(value);          }
        } catch (error) {
          sagaIterator.throw(error);        }
      };      processSaga();    });    return result;  };  middleware.run = saga => {
    sagas.push(saga);  };  return middleware;}

To support the select effect, switch on its type and then call store.getState() to pass it the current state and spread in the arguments attached to the select effect as the second argument.

dispatching { "type": "example/init" }
next state { "example": { "count": 0 } }
dispatching { "type": "example/increment" }
next state { "example": { "count": 1 } }
currentCount 1

When you now run your code, you should see the current count logged out in your browser console.

`call`

How do you isolate side effects with Redux Saga? You do that using the call effect.

When using Redux saga, similar to how you do it with actions and selectors, you use objects that represent future computations rather than directly triggering computation with I/O. call never actually calls a function. Instead, it returns an object with a reference to a function and its arguments, and the saga middleware calls it for you.

Log out call again to inspect it.

import { call } from 'redux-saga/effects';console.log(call(() => {}));

At this point, the output should look familiar to you.

{  '@@redux-saga/IO': true,
  combinator: false,
  type: 'CALL',
  payload: { context: null, fn: [Function (anonymous)], args: [] }
}

The fn property contains the function that is the first argument of the call effect, and args is the arguments passed to the function. context contains the this context in which the function will be executed, which is null when the function does NOT depend on it.

export const take = pattern => ({
  '@@redux-saga/IO': true,  type: 'TAKE',  payload: { pattern },});export const put = action => ({
  '@@redux-saga/IO': true,  type: 'PUT',  payload: { action },});export const select = (selector, ...arguments_) => ({
  '@@redux-saga/IO': true,  type: 'SELECT',  payload: { selector, args: arguments_ },});export function call(functionOrContextAndFunction, ...arguments_) {
  if (Array.isArray(functionOrContextAndFunction)) {
    const [context, function_] = functionOrContextAndFunction;    return {
      '@@redux-saga/IO': true,      type: 'CALL',      payload: { fn: function_, args: arguments_, context },    };  }
  return {
    '@@redux-saga/IO': true,    type: 'CALL',    payload: {
      fn: functionOrContextAndFunction,      args: arguments_,      context: null,    },  };}

You can use call in two ways. If the first argument is an array, the first element is the context, and the second is the function. If the first argument is a function, the context is null.

Now, use call in your example saga located in src/features/example/example-sagas.js.

import { call, put, select, take } from '../../redux/effects';import { increment, incrementBy, selectCount, slice } from './example-reducer';export const init = () => ({ type: `${slice}/init` });const fetchUser = async id => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/users/${id}`,  );  return await response.json();};export function* exampleSaga() {
  // sagaIterator.next(undefined); 1st  yield take(init().type);  // sagaIterator.next(init()); 2nd  yield put(increment());  // sagaIterator.next(undefined); 3rd  const currentCount = yield select(selectCount);  // sagaIterator.next(1); 4th  const user = yield call(fetchUser, currentCount);  // { type: 'call', payload: { context: null, fn: fetchUser, args: [currentCount] }}  // sagaIterator.next({ name: 'Leane Graham' }); // 5th  yield put(incrementBy(user.name.length));  // sagaIterator.next(undefined);}

To have something to isolate, create a fetchUser function that retrieves a user from a placeholder API using their id.

Then, use call to fetch the user whose ID is equal to the current count. Lastly, dispatch an incrementBy action to increase the count by the length of the user's name.

call is a pure function that takes in a function to call and the arguments to call the function with. It then delays the calling of the function. The invocation of the function is done by the saga middleware at some later point in time. This is how call transforms an impure function, like an API call, or a database call into a pure function by isolating the side effect.

By the way, this saga is nonsense. You're going see real use-cases in article 3, 4, and 5 of this series. The purpose of this example saga is to help you understand how Redux Saga and its effects work.

Next, modify your createSagaMiddleware function to handle the call effect in src/redux/saga-middleware.js. If you'd like, you can try doing it again as an exercise, but be warned - this one is a bit tougher.

import { call, put, select, take } from './effects';export function createSagaMiddleware() {
  let sagas = [];  const middleware = store => next => action => {
    const result = next(action);    sagas.forEach(saga => {
      const sagaIterator = saga();      let effectHandled = false;      const handleEffect = async effect => {
        if (!effect || !effect['@@redux-saga/IO']) {
          effectHandled = true;          return;        }
        switch (effect.type) {
          case take().type: {
            if (effect.payload.pattern === action.type) {
              return action;            } else {
              effectHandled = true;              return;            }
          }
          case put().type: {
            store.dispatch(effect.payload.action);            return;          }
          case select().type: {
            return effect.payload.selector(
              store.getState(),              ...effect.payload.args,            );          }
          case call().type: {
            try {
              const { fn, args, context } = effect.payload;              const functionResult = fn.apply(context, args);              if (functionResult instanceof Promise) {
                return await functionResult;              }
              return functionResult;            } catch (error) {
              effectHandled = true;              return sagaIterator.throw(error);            }
          }
          default: {
            effectHandled = true;            return;          }
        }
      };      const processSaga = async () => {
        let lastValue;        try {
          while (!effectHandled) {
            const { value, done } = sagaIterator.next(lastValue);            if (done) {
              break;            }
            lastValue = await handleEffect(value);          }
        } catch (error) {
          sagaIterator.throw(error);        }
      };      processSaga();    });    return result;  };  middleware.run = saga => {
    sagas.push(saga);  };  return middleware;}

In the effect handler for call, destructure the function, it's arguments and the context from effect's payload.

Then call the function using the apply method. This allows the function to be invoked with the specified context and arguments. Remember, if the function does NOT rely on a specific context, context will be null.

If the executed function returns a promise (i.e., it's an asynchronous operation), await this promise and then return the resolved value. Otherwise return the result directly.

If an error occurs during the execution of the function (either synchronously or within the promise), catch the error. Then use sagaIterator.throw(error) to pass the error back to the saga, allowing the saga to handle it appropriately (e.g., in a try/catch block).

As mentioned above, when you defined processSaga you await handleEffect because through call it can handle promises.

Now run your app again.

dispatching { "type": "example/init" }
next state { "example": { "count": 0 } }
dispatching { "type": "example/increment" }
next state { "example": { "count": 1 } }
dispatching { "type": "example/incrementBy", "payload": 13 }
next state { "example": { "count": 14 } }

Your browser console should now show the incrementBy action being dispatched with a payload of 13, because the user with ID one is named "Leanne Graham."

Redux Saga offers many more effects. You can explore them in the documentation, and be sure to read the next article in this series, where you're going to use more effects and dive into real-world examples.

Redux Saga Package

It's time to replace your custom code with the actual functions from Redux Saga.

Install Redux Saga.

$ npm i redux-saga

Next, replace your custom createSagaMiddleware function in your store with the one provided by Redux Saga.

import { applyMiddleware, legacy_createStore as createStore } from 'redux';import createSagaMiddleware from 'redux-saga';import { exampleSaga } from '../features/example/example-sagas';
import { rootReducer } from './root-reducer';const logger = store => next => action => {
  console.log('dispatching', action);  let result = next(action);  console.log('next state', store.getState());  return result;};export const makeStore = () => {
  const sagaMiddleware = createSagaMiddleware();  const store = createStore(
    rootReducer,    rootReducer(),    applyMiddleware(sagaMiddleware, logger),  );  sagaMiddleware.run(exampleSaga);  return store;};

Now you can replace the custom effects in your example saga with the actual effects from Redux Saga.

import { call, put, select, take } from 'redux-saga/effects';import { increment, incrementBy, selectCount, slice } from './example-reducer';export const init = () => ({ type: `${slice}/init` });const fetchUser = async id => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/users/${id}`,  );  return await response.json();};export function* exampleSaga() {
  yield take(init().type);  yield put(increment());  const currentCount = yield select(selectCount);  const user = yield call(fetchUser, currentCount);  yield put(incrementBy(user.name.length));}

And when you run your app again, you still get the same output in the console of your browser.

dispatching { "type": "example/init" }
next state { "example": { "count": 0 } }
dispatching { "type": "example/increment" }
next state { "example": { "count": 1 } }
dispatching { "type": "example/incrementBy", "payload": 13 }
next state { "example": { "count": 14 } }

In the beginning of this article, you learned that Redux Saga is great for:

isolating asynchronous effects, and
deterministic testing of I/O related logic.

So far, you've only seen the first point in this article. You're going to learn how to use sagas for deterministic testing in the fourth article of this series, where you build a real-world app with Redux.

But before that, you need to learn how to set up Redux for production, which is what the third article covers. So, go read that one next.

How to Set Up Next.js 15 for Production in 2024

Jan Hesters — Tue, 19 Nov 2024 11:11:45 +0000

I've worked on Next.js applications that scaled to over 100k monthly active users and landing pages with millions of monthly visitors. In this article, I'll share all the lessons I've learned through countless iterations.

Whether you're part of a small team of one, two, or three developers, or you work on a massive Next.js project with multiple teams on the same codebase, it's critical to get the foundation of your app right from the start. Even if you're working on an existing project, you will discover some hard-earned insights that you can apply to your app today.

Let me take you by the hand and show you all the steps and packages that you want to set up and explain to you why they're useful, so your app scales smoothly.

Initialize Your Project

Begin by creating a new Next.js project.

npx create-next-app@latest

It may ask you if it can install the latest create-next-app version, just hit yes.

Need to install the following packages:
create-next-app@15.0.0
Ok to proceed? (y)

And then configure your project by hitting yes on everything (TypeScript, Tailwind, app router).

✔ **What is your project named?** … reactsquad-production
✔ **Would you like to use** **TypeScript****?** … No / Yes
Yes
✔ **Would you like to use** **ESLint****?** … No / Yes
Yes
✔ **Would you like to use** **Tailwind CSS****?** … No / Yes
Yes
✔ **Would you like to use** **`src/` directory****?** … No / Yes
Yes
✔ **Would you like to use** **App Router****? (recommended)** … No / Yes
Yes
✔ **Would you like to customize the default** **import alias** **(@/*)?** … No / No

Then change into the directory of your project and open it in your favorite editor.

$ cd nextjs-for-production 
~/dev/nextjs-for-production (main) 🤯
$ cursor .

Run The Development Server

You want to verify that your setup worked.

Run npm run dev to start the development server.
Visit http://localhost:3000 to view your application.

Type Checks With TypeScript

Your project has TypeScript already configured, but you also want to add an explicit command to your package.json that checks all your files for type errors.

"type-check": "tsc -b"

You're going to use this command later together with other automated static analysis checks.

Code Formatting

When you collaborate with a large team on a project, it's important to unify the way that everyone writes code. Discuss choices like using semicolons, quote styles, and tabs versus spaces with your team.

Then use tools to enforce your style guide and format code automatically.

There are two tools for that: Prettier and ESLint.

Prettier

Prettier is an opinionated code formatter that eliminates style discussions during code reviews.

Install Prettier together with its Tailwind plugin.

npm install --save-dev prettier prettier-plugin-tailwindcss

Create a prettier.config.js file with your preferred rules.

module.exports = {
  arrowParens: 'avoid',
  bracketSameLine: false,
  bracketSpacing: true,
  htmlWhitespaceSensitivity: 'css',
  insertPragma: false,
  jsxSingleQuote: false,
  plugins: ['prettier-plugin-tailwindcss'],
  printWidth: 80,
  proseWrap: 'always',
  quoteProps: 'as-needed',
  requirePragma: false,
  semi: true,
  singleQuote: true,
  tabWidth: 2,
  trailingComma: 'all',
  useTabs: false,
};

Add a formatting script to your package.json.

"format": "prettier --write .",

Run the formatter to apply your style.

$ npm run format

> nextjs-for-production@0.1.0 format
> prettier --write .

next.config.mjs 4ms (unchanged)
package-lock.json 54ms (unchanged)
package.json 1ms (unchanged)
postcss.config.mjs 2ms (unchanged)
README.md 20ms (unchanged)
src/app/globals.css 17ms (unchanged)
src/app/layout.tsx 30ms (unchanged)
src/app/page.tsx 11ms (unchanged)
tailwind.config.ts 2ms (unchanged)
tsconfig.json 2ms (unchanged)

Your files are now "prettier", but you also want to use ESLint.

ESLint

ESLint can scan your code for both stylistic and logical issues. Install ESLint and its plugins, like unicorn, playwright and import sort.

npm install --save-dev @typescript-eslint/parser eslint-plugin-unicorn eslint-plugin-import eslint-plugin-playwright eslint-config-prettier eslint-plugin-prettier eslint-plugin-simple-import-sort

Update your .eslintrc.json.

{
  "extends": [
    "next/core-web-vitals",
    "plugin:unicorn/recommended",
    "plugin:import/recommended",
    "plugin:playwright/recommended",
    "plugin:prettier/recommended"
  ],
  "plugins": ["simple-import-sort"],
  "rules": {
    "simple-import-sort/exports": "error",
    "simple-import-sort/imports": "error",
    "unicorn/no-array-callback-reference": "off",
    "unicorn/no-array-for-each": "off",
    "unicorn/no-array-reduce": "off",
    "unicorn/prevent-abbreviations": [
      "error",
      {
        "allowList": {
          "e2e": true
        },
        "replacements": {
          "props": false,
          "ref": false,
          "params": false
        }
      }
    ]
  },
  "overrides": [
    {
      "files": ["*.js"],
      "rules": {
        "unicorn/prefer-module": "off"
      }
    }
  ]
}

This tutorial's plugins offer different functions. For detailed descriptions, visit their respective GitHub pages.

But in short, they enforce coding standards, organize imports, and ensure correct use of modern JavaScript features. Since ESLint and Prettier can conflict, this setup makes them work together smoothly. The plugins also help prevent bugs and keep styles consistent, especially with tools like Vitest and Playwright.

Add a linting script to your package.json.

"lint:fix": "next lint --fix",

Run it to format all files according to your new rules.

$ npm run lint:fix

> nextjs-for-production@0.1.0 lint:fix
> next lint --fix

✔ No ESLint warnings or errors

If you get a TypeScript version warning, you can ignore that.

Note: As of this article's writing, ESLint 9 is available, but this tutorial uses ESLint 8 because many plugins do not yet support the latest version.

Commitlint

When collaborating with a large team, it's also helpful to enforce consistent commit messages to keep the project history clear. By choosing the right standards, you can automate changelog and release generation with correct semantic versioning.

Install Commitlint and its necessary configurations. This includes Husky, which helps manage Git hooks.

npm install --save-dev @commitlint/cli@latest @commitlint/config-conventional@latest husky@latest

Initialize Husky in your project to set up the basic configuration.

npx husky-init && npm install

Add hooks to automate linting and type checking before each commit, and customize your commit message workflow.

npx husky add .husky/pre-commit 'npm run lint && npm run type-check'
npx husky add .husky/prepare-commit-msg 'exec < /dev/tty && npx cz --hook || true'

The pre-commit hook runs after git commit, but before the commit message is finalized and runs linting and type-checking on your code.

The prepare-commit-msg hook runs after git commit is initiated but before the commit message editor opens. It runs commitizen CLI to let you craft conventional commit messages. You'll learn how to use this hook in a bit.

Remove the line that says npm test from .husky/_/pre-commit.

Make sure these scripts are executable.

chmod a+x .husky/pre-commit
chmod a+x .husky/prepare-commit-msg

Here, chmod stands for "change mode." This command allows you to change the access permissions or modes of a file or directory in Unix and Unix-like operating systems. The argument a+x adds execute permissions for all users.

Install Commitizen, which provides a CLI for crafting conventional commit messages.

npm install --save-dev commitizen cz-conventional-changelog

Configure Commitizen in your package.json to use the conventional changelog standard.

"config": {
  "commitizen": {
    "path": "cz-conventional-changelog"
  }
},

The conventional changeloge standard is a specification for adding human and machine-readable meaning to commit messages. It is designed to automate the producing of changelogs and releases based on the Git history of your project.

A future article will explain this standard in detail. It's included in this tutorial because getting it right from the start is important. You can use it and benefit from it without needing an in-depth understanding.

Create your commitlint.config.cjs file with rules that suit your team's needs. This setup ensures your commit messages are consistent and relevant to the changes made.

const config = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'references-empty': [1, 'never'],
    'footer-max-line-length': [0, 'always'],
    'body-max-line-length': [0, 'always'],
  },
};

module.exports = config;

Run the following command to start crafting your commit messages using a guided CLI.

$ git add --all
$ npx cz
cz-cli@4.3.0, cz-conventional-changelog@3.3.0

? Select the type of change that you're 
committing: (Use arrow keys)
❯ feat:     A new feature 
  fix:      A bug fix 
  docs:     Documentation only changes 
  style:    Changes that do not affect the 
meaning of the code (white-space, formatting, 
missing semi-colons, etc)

The cz command asks a series of questions and then writes your commit message for you.

? Select the type of change that you\'re committing: feat:     A new feature
? What is the scope of this change (e.g. component or file name): (press enter to skip)
? Write a short, imperative tense description of the change (max 63 chars):
 (61) set up TS type checks, ESLint, Prettier, Commitlint and Husky
? Provide a longer description of the change: (press enter to skip)
 Sets up package.json script to do TS type checks. Sets up Prettier and ESLint with good rules. Configures Husky and sets up Commitizen using the conventional commit standard.
? Are there any breaking changes? No
? Does this change affect any open issues? No
[main eb69ccd] feat(set up static analysis checks): set up TS type checks, ESLint, Prettier, Commitlint and Husky
 7 files changed, 3108 insertions(+), 159 deletions(-)
 create mode 100755 .husky/pre-commit
 create mode 100755 .husky/prepare-commit-msg
 create mode 100644 commitlint.config.cjs

As you answer all questions, the Husky hooks will automatically run TypeScript type checks and linting.

Folder structure

There are usually two popular ways to organize your code: grouping by type or grouping by feature.

Group by type looks like this:

.  
├── components  
│ ├── todos  
│ └── user  
├── reducers  
│ ├── todos  
│ └── user  
└── tests  
    ├── todos  
    └── user

And grouping by feature looks like this:

.  
├── todos  
│ ├── component  
│ ├── reducer  
│ └── test  
└── user  
    ├── component  
    ├── reducer  
    └── test

Grouping files by feature in a project organizes all related components, reducers, and tests together, making it easier to manage and modify each feature. It has the following benefits:

Scalability: Large applications are easier to scale and maintain because each feature acts like a mini-application. You avoid scrolling up and down in your file list to find all the files you need.
Collaboration: Developers can focus on specific features without disrupting others’ work.
Onboarding: New developers understand the project structure faster, as all files for a feature are in one place.
Refactoring: Updating a feature is streamlined since all its elements are grouped together.
Modularity: Features can be reused, shared, or turned into standalone packages more easily.
Micro-frontends: If your application ever grows to 30 or more engineers, it is easy to refactor to micro-frontends.

Here is a more concrete example.

src/
├── app/
│   ├── ...
│   ├── (group)/
│   │   ├── about/
│   │   │   └── page.tsx
│   │   ├── settings/
│   │   │   └── page.tsx
│   │   └── layout.tsx
│   ├── dashboard/
│   │   ├── page.tsx
│   │   └── layout.tsx
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── ...
│   └── header/
│       ├── header-component.tsx
│       ├── header-component.test.ts
│       └── header.module.css
├── features/
│   ├── ...
│   ├── todos/
│   │   ├── ...
│   │   ├── todos-component.tsx
│   │   ├── todos-component.test.ts
│   │   ├── todos-container.ts
│   │   ├── todos-reducer.ts
│   │   ├── todos-reducer.test.ts
│   │   └── todos-styles.ts
│   └── user/
│       ├── ...
│       ├── user-reducer.ts
│       └── user-reducer.test.ts
├── hocs/
│   ├── ...
│   └── with-layout.tsx
├── hooks/
├── redux/
│   ├── root-reducer.ts
│   ├── root-saga.ts
│   └── store.ts
├── ...
└── middleware.ts

This example shows you how you can organize your src/ directory. Generally, everything is grouped by feature. Tests files live next to their respective implementation files. But anything that is shared by multiple features is then grouped in general folders, such as components/ or HOCs/ or hooks/. Shared setup for state management - in this example for Redux - lives in a redux/ folder.

Some people also like to group by feature within the app/ folder. Here is how that would look like.

src/
├── app/
│   ├── ...
│   ├── (group)/
│   ├── dashboard/
│   │   ├── components/
│   │   │   ├── dashboard-header.tsx
│   │   │   ├── dashboard-header.test.ts
│   │   │   ├── dashboard-widgets.tsx
│   │   │   └── dashboard-widgets.test.ts
│   │   ├── services/
│   │   │   ├── fetch-data.ts
│   │   │   ├── fetch-data.test.ts
│   │   │   ├── auth-service.ts
│   │   │   └── auth-service.test.ts
│   │   ├── page.tsx
│   │   └── layout.ts
│   ├── layout.tsx
│   └── page.tsx
├── ...
└── middleware.ts

In this tutorial, you're going to group files by feature in the first way.

Vitest

If you want to avoid bugs and prevent regressions, you need to write tests. Vitest is a great choice because it has the same API as the most popular framework, which is Jest, but it runs faster.

Install Vitest.

npm install -D vitest

And configure a testing command in your package.json.

"test": "vitest --reporter=verbose",

Then create an example.test.ts file and write a short test to check to check Vitest works.

import { describe, expect, test } from 'vitest';

describe('example', () => {
  test('given a passing test: passes', () => {
    expect(1).toStrictEqual(1);
  });
});

It should pass.

$ npm test

> nextjs-for-production@0.1.0 test
> vitest --reporter=verbose


 DEV  v2.0.5 /Users/jan/dev/nextjs-for-production

 ✓ src/example.test.ts (1)
   ✓ example (1)
     ✓ given a passing test: passes

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  14:06:24
   Duration  203ms (transform 20ms, setup 0ms, collect 17ms, tests 1ms, environment 0ms, prepare 56ms)


 PASS  Waiting for file changes...
       press h to show help, press q to quit

If you want to learn how you can write better tests, check out this article that teaches you 12 evergreen testing principles that every senior developer should know.

React Testing Library

You also want to write tests for your React components. For that, you can use the React Testing Library, often abbreviated as RTL.

npm install --save-dev @testing-library/react @testing-library/dom @testing-library/jest-dom @testing-library/user-event @types/react @types/react-dom happy-dom @vitejs/plugin-react vite-tsconfig-paths

Then, create a vitest.config.ts file.

import react from '@vitejs/plugin-react';
import tsconfigPaths from 'vite-tsconfig-paths';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  server: {
    port: 3000,
  },
  test: {
    environment: 'happy-dom',
    globals: true,
    setupFiles: ['./src/tests/setup-test-environment.ts'],
    include: ['./src/**/*.{spec,test}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
    watch: {
      ignored: [
        String.raw`.*\/node_modules\/.*`,
        String.raw`.*\/build\/.*`,
        String.raw`.*\/postgres-data\/.*`,
      ],
    },
    coverage: {
      reporter: ['text', 'json', 'html'],
    },
  },
});

It sets up the development server, specifies testing parameters like that the environment is happy-dom and file paths, and defines coverage report formats.

And create a file called src/tests/setup-test-environment.ts to set up your test environment.

import '@testing-library/jest-dom/vitest';

// See https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#configuring-your-testing-environment.

// @ts-ignore
globalThis.IS_REACT_ACT_ENVIRONMENT = true;

The first line imports additional assertions, which extend Vitest's built-in assertions, allowing you to more easily test DOM nodes. For example, you can check if an element is visible, has a certain text content, or includes specific attributes.

The global environment flag ensures that tests involving state updates work as expected without timing issues.

Next, you want to set up a custom render method src/tests/react-test-utils.tsx.

/* eslint-disable import/export */
import type { RenderOptions } from '@testing-library/react';
import { render } from '@testing-library/react';
import type { ReactElement } from 'react';

const customRender = (
  ui: ReactElement,
  options?: Omit<RenderOptions, 'queries'>,
) =>
  render(ui, {
    wrapper: ({ children }) => <>{children}</>,
    ...options,
  });

// re-export everything
export * from '@testing-library/react';

// override render method
export { customRender as render };
export { default as userEvent } from '@testing-library/user-event';

You can use this to wrap your code in providers, for example, when using Redux, or adding layouts and styling.

Make sure your configuration worked by writing a test for a React component.

import { describe, expect, test } from 'vitest';

import { render, screen } from '@/tests/react-test-utils';

function MyReactComponent() {
  return <div>My React Component</div>;
}

describe('MyReactComponent', () => {
  test('given no props: renders a text', () => {
    render(<MyReactComponent />);

    expect(screen.getByText('My React Component')).toBeInTheDocument();
  });
});

You import render and screen from your test utils file instead of from RTL directly.

toBeInTheDocument() is one of those special assertions that you configured earlier in your test environment setup file.

It should pass, too.

 ✓ src/features/example.test.tsx (1)
   ✓ MyReactComponent (1)
     ✓ given no props: renders a text

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  09:33:32
   Duration  402ms (transform 24ms, setup 55ms, collect 87ms, tests 9ms, environment 80ms, prepare 45ms)


 PASS  Waiting for file changes...
       press h to show help, press q to quit

Styling

Now let's talk about styling. The two most important aspects to get right are accessibility and maintainability. One of the most popular libraries out there that nails both of these aspects is Shadcn. It uses Tailwind for streamlined style management and Radix for enhanced accessibility.

Initialize Shadcn in your project.

$ npx shadcn@latest init

✔ **Which** **style** **would you like to use?** › New York
✔ **Which color would you like to use as** **base color****?** › Slate
✔ **Would you like to use** **CSS variables** **for colors?** … no / yes

✔ Writing components.json...
✔ Initializing project...
✔ Installing dependencies...

Success! Project initialization completed. You may now add components.

Now, if you need a card or any other component, you can easily add it to your project using the Shadcn command line interface.

npx shadcn@latest add card

Internationalization

As your app scales, you want to translate it to multiple languages, so it can reach more users.

And adding internationalization - or i18n - in a later cycle of an app, can be a pain because you'll have to find all hardcoded strings and replace them with translation function calls.

Install negotiator and a locale matcher.

npm install negotiator @formatjs/intl-localematcher

The @formatjs/intl-localematcher package selects the best language for your app's content based on a user's language preferences. The negotiator package helps your app to figure out what type of content (like language or format) your user's browser can handle best, based on the information the browser sends.

You'll also need to install the TypeScript types for the negotiator package.

npm install --save-dev @types/negotiator

Then, create your i18n config in a new file at src/features/internationalization/i18n-config.ts.

export const i18n = {
  defaultLocale: 'en-US',
  locales: ['en-US'],
} as const;

export type Locale = (typeof i18n)['locales'][number];

Use that i18n config, in your localization-middleware at
src/features/internationalization/localization-middleware.ts.

import { match } from '@formatjs/intl-localematcher';
import Negotiator from 'negotiator';
import { type NextRequest, NextResponse } from 'next/server';

import { i18n } from './i18n-config';

function getLocale(request: NextRequest) {
  const headers = {
    'accept-language': request.headers.get('accept-language') ?? '',
  };
  const languages = new Negotiator({ headers }).languages();
  return match(languages, i18n.locales, i18n.defaultLocale);
}

export function localizationMiddleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const pathnameHasLocale = i18n.locales.some(
    locale => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`,
  );

  if (pathnameHasLocale) {
    return;
  }

  const locale = getLocale(request);
  request.nextUrl.pathname = `/${locale}${pathname}`;
  return NextResponse.redirect(request.nextUrl);
}

The purpose of this middleware is to automatically detect and redirect your users to the appropriate language version of the website based on their browser language preferences.

Then create a middleware file src/middleware.ts in the root of your project, and use your localization middleware there.

import { NextRequest } from 'next/server';

import { localizationMiddleware } from './features/internationalization/localization-middleware';

// Matcher ignoring `/_next/` and `/api/` and svg files.
export const config = { matcher: ['/((?!api|_next|.*.svg$).*)'] };

export function middleware(request: NextRequest) {
  return localizationMiddleware(request);
}

It's time to add your translations. Create a json dictionary for your English translations at src/features/internationalization/dictionaries/en-us.json.

{
  "counter": {
    "decrement": "Decrement",
    "increment": "Increment"
  },
  "landing": {
    "welcome": "Welcome"
  }
}

And then, create a file src/features/internationalization/get-dictionaries.ts for your getDictionary function.

import "server-only";
import type { Locale } from "./i18n-config";

// We enumerate all dictionaries here for better linting and typescript support.
// We also get the default import for cleaner types.
const dictionaries = {
  "en-US": () => import("./dictionaries/en-US.json").then((module) => module.default),
};

export const getDictionary = async (locale: Locale) =>
  dictionaries[locale]?.() ?? dictionaries["en-US"]();

It takes in a locale and then returns the respective dictionary.

If you want to add a hook that lets your users pick their language, it can look like this.

import { usePathname } from 'next/navigation';

import { Locale } from './i18n-config';

export function useSwitchLocaleHref() {
  const pathName = usePathname();

  const getSwitchLocaleHref = (locale: Locale) => {
    if (!pathName) return '/';
    const segments = pathName.split('/');
    segments[1] = locale;
    return segments.join('/');
  };

  return getSwitchLocaleHref;
}

And then you can use that hook in a component, and use it's return value in a <Link /> like this.

<Link href={getSwitchLocaleHref(locale)}>{locale}</Link>

Change your URL structure to support i18n. Create a new folder [lang] in your app/ folder, which creates a dynamic segment for the language.

Move your page.tsx and layout.tsx files into that folder, and modify the layout to set the correct language on the <html /> tag.

import '../globals.css';

import type { Metadata } from 'next';
import { Inter } from 'next/font/google';

import { Locale } from '@/features/internationalization/i18n-config';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: "Jan Hesters' Next.js for production tutorial",
  description: 'Brought to you by ReactSquad.io',
};

export default function RootLayout({
  children,
  params,
}: Readonly<{
  children: React.ReactNode;
  params: { lang: Locale };
}>) {
  return (
    <html lang={params.lang}>
      <body className={inter.className}>{children}</body>
    </html>
  );
}

Going forward, you can use the getDictionary function in any server component.

import { getDictionary } from '@/features/internationalization/get-dictionaries';
import { Locale } from '@/features/internationalization/i18n-config';

import { CounterComponent } from './counter-component';

export default async function IndexPage({
  params: { lang },
}: {
  params: { lang: Locale };
}) {
  const dictionary = await getDictionary(lang);

  return (
    <div>
      <p>Current locale: {lang}</p>
      <p>This text is rendered on the server: {dictionary.landing.welcome}</p>
      <CounterComponent dictionary={dictionary.counter} />
    </div>
  );
}

For client components, you'll want to pass in the respective dictionary instead.

'use client';

import { useState } from 'react';

import type { getDictionary } from '@/features/internationalization/get-dictionaries';

export function CounterComponent({
  dictionary,
}: {
  dictionary: Awaited<ReturnType<typeof getDictionary>>['counter'];
}) {
  const [count, setCount] = useState(0);

  return (
    <p>
      This component is rendered on the client:
      <button onClick={() => setCount(n => n - 1)}>
        {dictionary.decrement}
      </button>
      {count}
      <button onClick={() => setCount(n => n + 1)}>
        {dictionary.increment}
      </button>
    </p>
  );
}

Database

This tutorial is going to use Postgres for its database because it is well battle-tested, but you're going to use the Prisma ORM to abstract away the database layer. This gives you the flexibility to use a variety of databases, and simplifies the API that you use to interact with it.

npm install prisma --save-dev

You'll also need to install the Prisma client.

npm install @prisma/client

Initialize Prisma.

npx prisma init

This auto-generates your prisma/schema.prisma file.

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  // Uses connection pooling
  url = env("DATABASE_URL")
}

model UserProfile {
  id                         String   @id @default(cuid())
  createdAt                  DateTime @default(now())
  updatedAt                  DateTime @updatedAt
  email                      String   @unique
  name                       String   @default("")
  acceptedTermsAndConditions Boolean  @default(false)
}

Add a aUserProfile model to it, which has an email and a name and a boolean whether they accepted your terms and conditions.

If you ran npx prisma init, rename your .env file to .env.local, otherwise create it and make sure it contains the credentials for your Prisma database.

DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"

Now create a src/lib/prisma.ts file, which will contain your Prisma client connection.

import { PrismaClient } from '@prisma/client';

declare global {
  var __database__: PrismaClient;
}

let prisma: PrismaClient;

if (process.env.NODE_ENV === 'production') {
  prisma = new PrismaClient();
} else {
  if (!global.__database__) {
    global.__database__ = new PrismaClient();
  }
  prisma = global.__database__;
}

export default prisma;

The re-assignment ensures that in a non-production environment (like during development or testing), only one instance of the Prisma client is created and reused across the entire application. This approach prevents the overhead of repeatedly initializing new connections to the database every time a module that needs database access is imported.

Modify your package.json to include the following helper commands for Prisma.

"prisma:deploy": "npx prisma migrate deploy && npx prisma generate",
"prisma:migrate": "npx prisma migrate dev --name",
"prisma:push": "npx prisma db push && npx prisma generate",
"prisma:reset-dev": "run-s prisma:wipe prisma:seed dev",
"prisma:seed": "tsx ./prisma/seed.ts",
"prisma:setup": "prisma generate && prisma migrate deploy && prisma db push",
"prisma:studio": "npx prisma studio",
"prisma:wipe": "npx prisma migrate reset --force && npx prisma db push",

Some of these commands use the run-s, tsx and dotenv packages, which you'll need to install.

npm install --save-dev npm-run-all tsx dotenv

Here’s an explanation of each Prisma command:

"prisma:deploy": Deploys database migrations and generates Prisma Client. It runs migrations on production databases and updates the client API.
"prisma:migrate": Creates a new migration from changes in the Prisma schema, applying it in the development environment. You must specify a name for the migration after the command.
"prisma:push": Pushes the schema changes directly to the database and updates the Prisma Client. Useful for prototyping without creating migration files.
"prisma:reset-dev": Resets the development database by wiping it, re-seeding it, and applying migrations in development mode.
"prisma:seed": Runs a TypeScript seed script to populate the database with initial data.
"prisma:setup": Generates the Prisma Client, deploys migrations to the database, and pushes the schema to the database.
"prisma:studio": Opens Prisma Studio, a GUI for viewing and editing the database records.
"prisma:wipe": Resets the database by forcefully dropping all data and migrations and then pushes the schema changes.

npm run prisma:setup

If your Prisma doesn't recognize your .env.local file, set your environment variable manually in your terminal. On Mac, this can be done using the export command.

export DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"

Create a prisma/seed.ts file. You can use it to seed your database with data for development.

import { exit } from 'node:process';

import { PrismaClient } from '@prisma/client';
import dotenv from 'dotenv';

dotenv.config({ path: '.env.local' });

const prisma = new PrismaClient();

const prettyPrint = (object: any) =>
  console.log(JSON.stringify(object, undefined, 2));

async function seed() {
  const user = await prisma.userProfile.create({
    data: {
      email: 'jan@reactsquad.io',
      name: 'Jan Hesters',
      acceptedTermsAndConditions: true,
    },
  });

  console.log('========= 🌱 result of seed: =========');
  prettyPrint({ user });
}

seed()
  .then(async () => {
    await prisma.$disconnect();
  })
  // eslint-disable-next-line unicorn/prefer-top-level-await
  .catch(async error => {
    console.error(error);
    await prisma.$disconnect();
    exit(1);
  });

If you run it, it'll create your user.

$ npm run prisma:seed

> reactsquad-production@0.1.0 prisma:seed
> tsx ./prisma/seed.ts

========= 🌱 result of seed: =========
{
  "user": {
    "id": "clzekb5sp0000ock9gsp72p33",
    "createdAt": "2024-08-03T20:04:27.289Z",
    "updatedAt": "2024-08-03T20:04:27.289Z",
    "email": "jan@reactsquad.io",
    "name": "Jan Hesters",
    "acceptedTermsAndConditions": true
  }
}

In your server components, you can use prisma to fetch any data.

import prisma from '@/lib/prisma';
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';

export default async function Dashboard() {
  const user = await prisma.userProfile.findUnique({
    where: { email: 'jan@reactsquad.io' },
  });

  return (
    <Card className="max-w-md mx-auto">
      <CardHeader>
        <CardTitle>User Profile</Card.Title>
      </CardHeader>
      <CardContent>
        {user ? (
          <ul>
            <li>Name: {user.name}</li>
            <li>Email: {user.email}</li>
          </ul>
        ) : (
          <p>User not found.</p>
        )}
      </CardContent>
    </Card>
  );
}

Use Facades

It's a good idea to abstract away your database calls using facades. A facade is a design pattern where you provide a simplified interface to a complex subsystem.

Create a file that contains all facades related to your user profile model features/user-profile/user-profile-model.ts.

import { UserProfile } from '@prisma/client';

import prisma from '@/lib/prisma';

export async function retrieveUserProfileFromDatabaseByEmail(
  email: UserProfile['email'],
) {
  return await prisma.userProfile.findUnique({ where: { email } });
}

There are two main reasons for using facades.

Increase vendor resistance - You can switch third-party providers easily. For example, you might switch from Firebase to Supabase or vice versa. Instead of updating your whole codebase to reflect the change, you only update the facade.
Simplify your code - A facade can reduce the code you need to write in your application because it reduces the API to your specific application needs. Simultaneously, it makes your code easier to understand because you can give the facade descriptive names.

Then use your facade in your server component.

import { retrieveUserProfileFromDatabaseByEmail } from '@/features/user-profiles/user-profiles-model';
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';

export default async function Dashboard() {
  const user =
    await retrieveUserProfileFromDatabaseByEmail('jan@reactsquad.io');

  return (
    <Card className="max-w-md mx-auto">
      <CardHeader>
        <CardTitle>User Profile</Card.Title>
      </CardHeader>

      <CardContent>
        {user ? (
          <ul>
            <li>Name: {user.name}</li>
            <li>Email: {user.email}</li>
          </ul>
        ) : (
          <p>User not found.</p>
        )}
      </CardContent>
    </Card>
  );
}

Vercel Postgres

You can use Vercel Postgres for your production deployment. They have an easy to follow guide, which you can check out in the Vercel documentation. But here are the steps real quick for your convenience.

To set up a database in your Vercel project, follow these steps:

Go to the Storage tab and click the Create Database button.
When the Browse Storage modal opens, choose Postgres and click Continue.

For creating a new database:

In the dialog box, type sample_postgres_db (or a name you prefer) in the Store Name field. Ensure the name has only alphanumeric characters, "_" or "-", and does not exceed 32 characters.
Choose a region. For lower latency, select a region close to your function region, which is US East by default.
Click Create.

Then you'll need to add POSTGRES_URL_NON_POOLING to the datasource in your Prisma schema.

datasource db {
  provider  = "postgresql"
  // Uses connection pooling
  url       = env("DATABASE_URL")
  // Uses direct connection, ⚠️ make sure to keep this to `POSTGRES_URL_NON_POOLING`
  // or you'll have dangling databases from migrations
  directUrl = env("POSTGRES_URL_NON_POOLING")
}

Vercel uses connection poolers, which manage a pool of database connections that can be reused by different parts of an application, rather than establishing a new connection for each database request. The directUrl property is used to ensure operations requiring direct database access, such as migrations, can bypass the connection pooler for reliable execution.

You can get the environment variables for your Vercel database by pulling them from Vercel.

vercel env pull .env

Playwright

You also want to use E2E tests because E2E tests give you the most confidence that your app works as intended. E2E tests are skipped far too often, but you really should make it a habit to write them. The benefits are compounding.

Initialize Playwright.

$ npm init playwright@latest
Getting started with writing end-to-end tests with Playwright:
Initializing project in '.'
✔ Where to put your end-to-end tests? · playwright
✔ Add a GitHub Actions workflow? (y/N) · false
✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n) · true

If this is your first time using Playwright, you can have a look through the test-examples/ folder that the initialization script creates, and then deleted it because you won't need it.

Modify the webServer key in your playwright.config.ts file.

webServer: {
  command: process.env.CI ? 'npm run build && npm run start' : 'npm run dev',
  port: 3000,
},

Add two scripts for your E2E tests to your package.json.

"test:e2e": "npx playwright test",
"test:e2e:ui": "npx playwright test --ui",

The first one runs your Playwright test in headless mode, while the second one runs your test in UI mode, which gives you time travel debugging, watch mode and more.

import { expect, test } from '@playwright/test';

test.describe('landing page', () => {
  test('given any user: shows the test user', async ({ page }) => {
    await page.goto('/');

    await expect(page.getByText('Jan Hesters')).toBeVisible();
    await expect(page.getByText('jan@reactsquad.io')).toBeVisible();
  });
});

Run your tests to check that your Playwright setup worked.

$ npm run test:e2e

> reactsquad-production@0.1.0 test:e2e
> npx playwright test


Running 3 tests using 3 workers
  3 passed (3.9s)

It ran three tests because by default Playwright is configured to run in Chrome, Safari, and Firefox.

GitHub Actions

It's good practice to run your app with CI/CD. CI/CD stands for continuous delivery and continuous deployment.

Add a secret for your database URL to your repository's settings in GitHub.

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/testdb"

Then create your GitHub Actions YAML configuration in a .github/workflows/pull-request.yml file for a comprehensive CI/CD pipeline including linting, type checking, testing, and more.

name: Pull Request

on: [pull_request]

jobs:
  lint:
    name: ⬣ ESLint
    runs-on: ubuntu-latest
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3

      - name: ⎔ Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: 📥 Download deps
        uses: bahmutov/npm-install@v1

      - name: 🔬 Lint
        run: npm run lint

  type-check:
    name: ʦ TypeScript
    runs-on: ubuntu-latest
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3

      - name: ⎔ Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: 📥 Download deps
        uses: bahmutov/npm-install@v1

      - name: 🔎 Type check
        run: npm run type-check --if-present

  commitlint:
    name: ⚙️ commitlint
    runs-on: ubuntu-latest
    if: github.actor != 'dependabot[bot]'
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: ⚙️ commitlint
        uses: wagoid/commitlint-github-action@v4

  vitest:
    name: ⚡ Vitest
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:12
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3

      - name: ⎔ Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: 📥 Download deps
        uses: bahmutov/npm-install@v1

      - name: 🛠 Setup Database
        run: npm run prisma:wipe
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/testdb

      - name: ⚡ Run vitest
        run: npm run test -- --coverage
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/testdb

  playwright:
    name: 🎭 Playwright
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:12
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3

      - name: ⎔ Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: 📥 Download deps
        uses: bahmutov/npm-install@v1

      - name: 🌐 Install Playwright Browsers
        run: npx playwright install --with-deps

      - name: 🛠 Setup Database
        run: npm run prisma:wipe
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/testdb

      - name: 🎭 Playwright Run
        run: npx playwright test
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/testdb

      - name: 📸 Playwright Screenshots
        uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

Now every time you make a pull request to your app, it automatically runs your tests to ensure it works, runs TypeScript type checks and lints it, so that everyone contributes code with the same formatting.

What is Memoization? (In JavaScript & TypeScript)

Jan Hesters — Thu, 07 Nov 2024 10:47:04 +0000

Memoization and caching are foundational concepts in programming.

You want to understand memoization, so you can understand concepts that build upon memoization. For example, the memo higher-order component in React, useCallback and useMemo hooks in React, selectors in Redux and much more.

In this article and video, you're going to get a detailed look into memoization with examples in JavaScript and TypeScript.

What Is Memoization?

Memoization is a way to speed up performance by reducing computations.

When you first calculate a result, you save it. If you need the result for the same arguments again, you use the saved result instead of recalculating.

And there are two ways that you can implement memoization:

Implicit Caching
Decorator Functions

Implicit Caching

Implicit caching is when you manually implement caching logic within functions.

Let's say you have a simple add function and you want to memoize it.

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

You can rewrite this add function, so that it memoizes its results.

If you want to code along with this article, initialize a new npm project.

npm init --y

Then write a function called memoizeAdd().

function memoizeAdd() {
  const cache = {};

  return function memoizedAdd(a, b) {
    const key = `${a},${b}`;

    if (key in cache) {
      return cache[key];
    } else {
      const result = a + b;

      cache[key] = result;

      return result;
    }
  };
}

const memoizedAdd = memoizeAdd();

console.log(memoizedAdd(3, 4));  // Computes and caches the result.
console.log(memoizedAdd(3, 4));  // Retrieves the result from cache.
console.log(memoizedAdd(5, 6));  // Computes and caches a new result.
console.log(memoizedAdd(3, 4));  // Still retrieves the result from cache.

Let's break down what's happening here.

In memoizeAdd() you create a cache, which is typically a hash table or an object, where you store the results of function calls. Each entry uses the function's input as the key and the output as the value.

const cache = {
  '3,1': 4,
  '9001,2012': 11_013,
};

Next, you return the memoizedAdd function, which takes in two numbers a and b.

Each unique combination of arguments corresponds to a key.

Before executing the main logic, the function checks the cache using the current input as the key. If the input is in the cache, it returns the cached result.

If the input is missing in the cache, the function computes the result, stores it in the cache, and then returns the result.

When you call the memoizedAdd function, the result is stored together with its parameters. If you call it again with the same parameters, the result comes from the cache. If the parameters are new, the function computes the result again.

When you run this code, you get the following output.

$ node implicit-caching.js
7
7
11
7

Decorator Functions For Memoization

In languages that support higher-order functions, you can use decorators to add memoization without changing the function's core logic.

Higher-order functions are functions that take in functions and return functions.

If this concept is new to you, you might want to read "Unleash JavaScript's Potential with Functional Programming". This article explains higher-order functions and much more from first principles.

Now, check out this simple example of a decorator function for memoization.

function memoize(fn) {
  const cache = new Map();

  return function(...args) {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key);
    }

    const result = fn.apply(this, args);
    cache.set(key, result);

    return result;
  };
}

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

const memoizedAdd = memoize(add);

console.log(memoizedAdd(3, 4));  // Calculates and caches the result.
console.log(memoizedAdd(3, 4));  // Returns the cached result.
console.log(memoizedAdd(5, 6));  // Computes and caches a new result.
console.log(memoizedAdd(3, 4));  // Still retrieves the result from cache.

Let's go through this code step by step, too.

First, you create a memoize function that takes another function, fn, as its argument.

It starts by initializing a cache using a Map. This cache will store the results of the function calls. A Map is used instead of an object because it can handle a wider variety of key types.

const cache = new Map();

// Use numbers as key for cache.
map.set('[3,1]', 4);
// Use functions as key for cache.
map.set('[function increment(), function double()]', 42);

The returned function accepts any number of arguments. It serializes these arguments into a string to use as a key for the cache.

Before executing the original function, the wrapper checks if the key already exists in the cache. If it does, the function returns the cached result.

If the key is missing in the cache, the wrapper calls the original function using fn.apply(this, args). It stores the result in the cache and returns it.

You can now memoize your add function by passing it to the memoize function.

The memoizedAdd function will work just like in the implicit caching example.

And running your code yields the same result.

$ node decorator-function.js
7
7
11
7

Recursion And The Fibonacci Sequence

The add function is computationally cheap.

To experience the benefits of memoization, you need to memoize an expensive function.

A classic example is the fibonacci function. Outside of memoization, learning about this function is useful because it's a common topic in coding interviews.

The Fibonacci sequence is a series of numbers where each number is the sum of the two preceding ones. It usually starts with 0 and 1. Here's how it begins:

0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...

In mathematical terms, you can express this as:

Here's what the fibonacci function looks like in JavaScript.

function fibonacci(n) {
  if (n <= 1) {
    return n;
  }

  return fibonacci(n - 1) + fibonacci(n - 2);
}

If n is 0 or 1, the function returns n directly. These are the first two numbers in the Fibonacci sequence.

For values of n greater than 1, the function calls itself twice: once for fibonacci(n - 1) and once for fibonacci(n - 2), and adds the results of these two calls.

Here's a table showing how the function computes fibonacci(4):

Call	n	Calculation	End Result
`fibonacci(4)`	4	`fibonacci(3) + fibonacci(2)`	3 + 2 = 5
`fibonacci(3)`	3	`fibonacci(2) + fibonacci(1)`	2 + 1 = 3
`fibonacci(2)`	2	`fibonacci(1) + fibonacci(0)`	1 + 0 = 1
`fibonacci(1)`	1	1	1
`fibonacci(0)`	0	0	0
`fibonacci(2)`	2	`fibonacci(1) + fibonacci(0)`	1 + 0 = 1
`fibonacci(1)`	1	1	1
`fibonacci(0)`	0	0	0

You can see that fibonacci(2) is calculated twice when calling fibonacci(4): once directly from fibonacci(4) and again from fibonacci(3).

The negative performance impacts of these redundant calculations compound as the input to the fibonacci function increases. You want to read this article until the end to learn how memoization can make this computation lightning fast.

Stack Tracing

Before memoizing your fibonacci function, add a name property to your memoized function. This makes stack tracing easier if your function throws an error.

function memoize(fn) {
  const cache = new Map();

  function memoizedFunction(...args) {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key);
    }

    const result = fn.apply(this, args);
    cache.set(key, result);

    return result;
  }

  Object.defineProperty(memoizedFunction, 'name', {
    value: `memoized_${fn.name}`,
    configurable: true
  });

  return memoizedFunction;
}

Use Object.defineProperty to set the name property of the memoizedFunction to a more descriptive value, like memoized_${fn.name}, where fn.name is the name of the original function. By setting this property to be configurable, you allow further modifications or deletion of the property if necessary.

Measuring Memoization Performance

Now you’re ready to measure the impact of memoization. Memoize your fibonacci function and time how long it takes to calculate large numbers.

function memoize(fn) {
  const cache = new Map();

  function memoizedFunction(...args) {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key);
    }

    const result = fn.apply(this, args);
    cache.set(key, result);

    return result;
  }

  Object.defineProperty(memoizedFunction, 'name', {
    value: `memoized_${fn.name}`,
    configurable: true
  });

  return memoizedFunction;
}

function fibonacci(n) {
  if (n <= 1) {
    return n;
  }

  return fibonacci(n - 1) + fibonacci(n - 2);
}

const memoizedFibonacci = memoize(fibonacci);

function measurePerformance(func, arg) {
  const startTime = process.hrtime.bigint();
  const result = func(arg);
  const endTime = process.hrtime.bigint();
  // Convert nanoseconds to milliseconds.
  const duration = (endTime - startTime) / BigInt(1000000);
  console.log(`${func.name}(${arg}) = ${result}, Time: ${duration}ms`);
}

const n = 42;

console.log("Starting performance measurement:");
measurePerformance(fibonacci, n);
measurePerformance(memoizedFibonacci, n);
// Second call to show caching effect.
measurePerformance(memoizedFibonacci, n);

The measurePerformance function evaluates and reports the execution time of a given function by capturing start and end times with process.hrtime.bigint(), which provides precise timestamps in nanoseconds. After executing the function with a given argument, it calculates the duration in milliseconds by subtracting the start time from the end time and converting the result from nanoseconds. It then logs the function name, argument, output, and execution duration to the console.

Using measurePerformance, you can compare the performance of the standard Fibonacci function with the memoized version.

Here are the results for the performance measurements.

$ node fibonacci.js
Starting performance measurement:
fibonacci(42) = 267914296, Time: 2405ms
memoized_fibonacci(42) = 267914296, Time: 2394ms
memoized_fibonacci(42) = 267914296, Time: 0ms

As you can see, running the memoized version the second time is instant because the result is retrieved from the cache.

Clearing Cache

When you use memoization, you want to implement .clear() method to manage your application's resources and performance. Here's why:

Memory management: It frees up resources by allowing you to manually purge the cache.
Data freshness: It ensures cached results stay accurate by removing outdated or incorrect data.
Control over cache behavior: It gives you the ability to reset the cache in response to events or conditions that affect data processing.
Testing and debugging: It allows you to operate your functions in a known state, without interference from cached data, which is important for reliable testing.
Performance optimization: It maintains cache efficiency by allowing periodic resets to manage size and lookup costs.

Now, add the ability to clear the cache.

function memoize(fn) {
  const cache = new Map();

  function memoizedFunction(...args) {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key);
    }

    const result = fn.apply(this, args);
    cache.set(key, result);

    return result;
  }

  memoizedFunction.clear = function clear() {
    cache.clear();
  };

  Object.defineProperty(memoizedFunction, 'name', {
    value: `memoized_${fn.name}`,
    configurable: true
  });

  return memoizedFunction;
}

function fibonacci(n) {
  if (n <= 1) {
    return n;
  }

  return fibonacci(n - 1) + fibonacci(n - 2);
}

const memoizedFibonacci = memoize(fibonacci);

function measurePerformance(func, arg) {
  const startTime = process.hrtime.bigint();
  const result = func(arg);
  const endTime = process.hrtime.bigint();
  // Convert nanoseconds to milliseconds.
  const duration = (endTime - startTime) / BigInt(1000000);
  console.log(`${func.name}(${arg}) = ${result}, Time: ${duration}ms`);
}

const n = 42;

// Measure memoized Fibonacci.
measurePerformance(memoizedFibonacci, n);

// Measure memoized Fibonacci second call.
measurePerformance(memoizedFibonacci, n);

// Clear cache and measure again.
console.log('Clearing cache and measuring again:');
memoizedFibonacci.clear();
measurePerformance(memoizedFibonacci, n);

Then modify your usage example to include a call of the .clear() method after the result has already been memoized successfully.

$ node fibonacci.js
memoized_fibonacci(42) = 267914296, Time: 2456ms
memoized_fibonacci(42) = 267914296, Time: 0ms
Clearing cache and measuring again:
memoized_fibonacci(42) = 267914296, Time: 2484ms

As you can see, clearing the cache causes the function to compute its result again.

Memoization In TypeScript

So far, all code has been written in JavaScript. Now you will translate the code examples into TypeScript.

Install TypeScript and the node types.

$ npm i --save-dev typescript @types/node

added 3 packages, and audited 4 packages in 1s

found 0 vulnerabilities

Then initialize a new TypeScript project.

$  npx tsc --init

Created a new tsconfig.json with:
                                                                      TS
  target: es2016
  module: commonjs
  strict: true
  esModuleInterop: true
  skipLibCheck: true
  forceConsistentCasingInFileNames: true

You can learn more at <https://aka.ms/tsconfig>

Now you can write your memoize function in TypeScript.

type AnyFunction = (...args: any[]) => any;

interface MemoizedFunction<T extends AnyFunction> extends CallableFunction {
  (...args: Parameters<T>): ReturnType<T>;
  clear: () => void;
}

function memoize<T extends AnyFunction>(fn: T): MemoizedFunction<T> {
  const cache = new Map<string, ReturnType<T>>();

  const memoizedFunction = function(...args: Parameters<T>): ReturnType<T> {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key)!;
    }

    const result = fn(...args);
    cache.set(key, result);

    return result;
  } as MemoizedFunction<T>;

  memoizedFunction.clear = function clear() {
    cache.clear();
  };

  Object.defineProperty(memoizedFunction, 'name', {
    value: `memoized_${fn.name}`,
    configurable: true
  });

  return memoizedFunction;
}

function fibonacci(n: number): number {
  if (n <= 1) {
    return n;
  }

  return fibonacci(n - 1) + fibonacci(n - 2);
}

const memoizedFibonacci = memoize(fibonacci);

function measurePerformance(func: MemoizedFunction<typeof fibonacci>, arg: number) {
  const startTime = process.hrtime.bigint();
  const result = func(arg);
  const endTime = process.hrtime.bigint();
  // Convert nanoseconds to milliseconds.
  const duration = (endTime - startTime) / BigInt(1000000);
  console.log(`${func.name}(${arg}) = ${result}, Time: ${duration}ms`);
}

const n = 42;

// Measure memoized Fibonacci.
measurePerformance(memoizedFibonacci, n);

// Measure memoized Fibonacci second call.
measurePerformance(memoizedFibonacci, n);

// Clear cache and measure again.
memoizedFibonacci.clear();
measurePerformance(memoizedFibonacci, n);

Here, you create an AnyFunction type, which represents a generic function type in TypeScript. This type is flexible and allows for any function that takes an arbitrary number of arguments of any type and returns any type.

Next, you define a generic MemoizedFunction interface that extends the built-in CallableFunction interface and introduces a clear method. Here, T is a generic type parameter constrained to any function that matches the AnyFunction type. The interface ensures that your memoized function behaves like the original function in terms of accepting the same parameters and returning the same type and additionally exposes the clear method.

You can now implement your memoize function so that it returns the MemoizedFunction interface. Using the as keyword, you can let TypeScript know that the returned function is a MemoizedFunction.

Now when you hover over memoizedFibonacci, TypeScript knows the correct type of the function.

const memoizedFibonacci: MemoizedFunction<(n: number) => number>

And TypeScript also knows about the .clear() method on the memoized function.

(property) MemoizedFunction<(n: number) => number>.clear: () => void

Recursion With Memoization

Your function still has a shortcoming. Currently, the memoization only caches the results of the full function call for each argument, but does NOT cache the results of the intermediate recursive calls.

What is a potential drawback of using recursion without memoization for solving certain problems?

It is the significant increase in computational time and resource usage due to redundant calculations.

Call the function with a big number n and then with n + 1.

// ... previous code stays the same.

const n = 42;

measurePerformance(memoizedFibonacci, n);
measurePerformance(memoizedFibonacci, n + 1);

Then run your code to see the difference in performance between 42 and 43.

$ npx tsx example-5.ts
memoized_fibonacci(42) = 267914296, Time: 2442ms
memoized_fibonacci(43) = 433494437, Time: 3975ms

As you can see, fibonacci(43) takes much longer because it recalculates fibonacci(42) from scratch, even though the result is already cached. The same problem occurs with every other intermediate recursive call.

You can fix this by using memoization in the implementation of the fibonacci function.

// ... `memoize` is the same as above.

function fibonacci(n: number): number {
  if (n <= 1) {
    return n;
  }

  return memoizedFibonacci(n - 1) + memoizedFibonacci(n - 2);
}

const memoizedFibonacci = memoize(fibonacci);

function measurePerformance(func: MemoizedFunction<typeof fibonacci>, arg: number) {
  const startTime = process.hrtime.bigint();
  const result = func(arg);
  const endTime = process.hrtime.bigint();
  // Convert nanoseconds to milliseconds.
  const duration = (endTime - startTime) / BigInt(1000000);
  console.log(`${func.name}(${arg}) = ${result}, Time: ${duration}ms`);
}

const numbers = [10, 20, 30, 40, 42, 43, 500];

numbers.forEach(n => {
  measurePerformance(memoizedFibonacci, n);
});

When you define the fibonacci function, use its memoized version to calculate the next number.

Now, run the function on various large numbers.

$ npx tsx fibonacci.ts
memoized_fibonacci(10) = 55, Time: 0ms
memoized_fibonacci(20) = 6765, Time: 0ms
memoized_fibonacci(30) = 832040, Time: 0ms
memoized_fibonacci(40) = 102334155, Time: 0ms
memoized_fibonacci(42) = 267914296, Time: 0ms
memoized_fibonacci(43) = 433494437, Time: 0ms
memoized_fibonacci(500) = 1.394232245616977e+104, Time: 0ms

The calculation is now virtually instant for every function call no matter how large.

So when you memoize, ask yourself: "What do you want to memoize?" Do you want to memoize only the outer function, or do you want to also memoize intermediary results in the implementation?

Why Memoize? (Use Cases)

When do you want to use memoization?

Memoization is useful in:

Recursive algorithms: As shown with the Fibonacci sequence, recursive functions that repeat the same calculations can benefit greatly from memoization by avoiding redundant operations.
Database queries: You can cache results from expensive database queries.
Data fetching: In web development, memoization can cache responses from API calls. This reduces network traffic and speeds up response times by serving cached data for repeated requests with the same parameters.
Data transformation: You can cache results of transformations that are costly in processing time.
Preventing component rendering: In frontend frameworks like React, memoization can prevent unnecessary re-renders of components as long as their their props stay the same.

Memoization Trade-Offs

As you've learned, memoization improves performance by reducing time complexity of operations and lowering the load on compute resources by avoiding repeated calculations.

But memoization also comes with drawbacks.

Memory usage: Memoization increases memory consumption by storing function call results, which can be a problem in environments with limited memory.
Complexity: Adding memoization introduces complexity to your codebase, and requires careful cache management to avoid bugs and maintainability issues.
Cache management: You must implement strategies for cache eviction and invalidation to prevent outdated or incorrect data, which can be challenging.
side-effects: Functions with side-effects are can be problematic for memoization because the side-effects might need to occur with each function call. Memoization should primarily be used with pure functions.
Concurrency issues: In multi-threaded applications, memoization must be handled carefully to avoid race conditions and ensure thread safety when accessing the cache.

Subscribe to my YouTube channel for more great JavaScript and TypeScript tutorials!

Unleash JavaScript's Potential with Functional Programming

Jan Hesters — Wed, 02 Oct 2024 10:54:31 +0000

Too many JavaScript developers have no idea what JavaScript is capable of.

This article will transform the way you write code and unleash your potential as a programmer.

By the end of this article, and the video below, you will be able to read, understand and write code like this:

const curry =
 (f, array = []) =>
 (...args) =>
 (a => (a.length >= f.length ? f(...a) : curry(f, a)))([
 ...array,
 ...args,
 ]);
const add = curry((a, b) => a + b);
const inc = add(1);
const pipe = (...fns) => x => fns.reduce((y, f) => f(y), x);
const doubleInc = pipe(x => x * 2, inc);

JavaScript is a two paradigm programming language because it supports OOP and FP.
This article is your "step-by-step with no steps skipped" guide to functional programming, so you can use
the language to its full capabilities and write more modular, deterministic and testable code.
It literally goes from primitives all the way to advanced function composition.

Definition

If you look up functional programming you might get lost in academic lingo.
If you're lucky you will find some kind of simple definition like this:

“Functional programming is the process of building software by composing functions. Functional programming is declarative rather than imperative. Side-effects are isolated. And application state usually flows through pure functions.”

You can relax because this article will explain all of these terms and more. Starting at Primitives.

Primitives

Primitives are all datatypes that can hold only one value at a time. JavaScript has 7 primitive data types.

string: Represents text.
number: Represents numerical values.
boolean: Represents true or false.
undefined: Indicates a variable has not been assigned a value.
null: Represents an intentional absence of any object value.
Symbol: Creates unique identifiers.
BigInt: Handles numbers larger than the standard number type can.

// primitives.js
const string = "ReactSquad.io";
const number = 9001;
const boolean = true;
const notThere = undefined;
const weirdUndefined = null;
const noOneUsesThis = Symbol('🤯 ');
const bigInt = 1n;

Composite data types

Composite data types can store collections or combinations of values.

Object: A structure that can hold multiple values as named properties.
Array: A list-like structure that holds values in a specific order.
Map: A collection of keyed data items, similar to an object but with keys of any type and maintains the order of insertions.
Set: A collection of unique values. Like an array, but each value can only occur once.

// composite.js
const obj = { key: "value" };
const array = [1, 2, 3, 4, 5];

A Map in JavaScript is a collection of keyed data items that maintains the order of insertions and allows keys of any type.

// map.js
// Creating a new Map
const map = new Map();

// Setting key-value pairs in the Map
map.set('name', 'John');
map.set('age', 30);
map.set(1, 'one');

console.log(map);
// Output: Map(3) {'name' => 'John', 'age' => 30, 1 => 'one'}

// Retrieving a value by key.
console.log(map.get('name')); // Output: John

// Checking if a key exists.
console.log(map.has('age')); // Output: true

// Size of the Map.
console.log(map.size); // Output: 3
Unleash JavaScript's Potential With Functional Programming Article.md 2024-09-30
3 / 29

// Removing a key-value pair.
map.delete(1);

// Clearing all entries.
map.clear();

A Set in JavaScript is a collection of unique values, ensuring that each value appears only once.

// set.js
// Creating a new Set.
const set = new Set();

// Adding values to the Set.
set.add('apple');
set.add('banana');
set.add('apple'); // This will not be added again.

console.log(set);
// Output: Set(2) {'apple', 'banana'}
// Reminder: Sets delete duplicates.

// Checking if a value exists.
console.log(set.has('banana')); // Output: true

// Size of the Set.
console.log(set.size); // Output: 2

// Deleting a value.
set.delete('apple');

// Iterating over Set values.
set.forEach(value => {
 console.log(value);
});

// Clearing all values.
set.clear();

Functions

function sumDeclaration(a, b) {
 return a + b;
}
const sumArrow = (a, b) => a + b;

A function is a process that can take inputs, called parameters, and can produce some output called return value.

Parameters vs. Arguments

Parameters are variables defined in the function declaration. They act as placeholders for the values that a function will operate on.
Arguments are the actual values or data passed to the function when it is called. These values replace the parameters during the function's execution.
An application happens when the arguments are used to replace the function's parameters. This allows the function to perform its task using the provided arguments.

function myFunction(parameter) {
 return parameter;
}
const myArgument = "Some value";
myFunction(myArgument); // Output: "Some value";

A function can be a mapping, a procedure or handle I/O operations.

Mapping: Produce some output based on given inputs. A function maps input values to output values. (So the examples you saw earlier are mappings.)

const square = x => x * x;
square(7); // 49

Procedure: A function executes some steps in a sequence. The sequence is known as a procedure, and programming in this style is known as procedural programming.

function prepareTea(teaType) {
 let steps = [];
 steps.push("Boil water");
 steps.push("Add " + teaType);
 steps.push("Steep for 5 minutes");
 steps.push("Serve hot");
 return steps.join("\n");
}

console.log(prepareTea("green tea"));
// Output: Boil water
// Add green tea
// Steep for 5 minutes
// Serve hot

function calculateCircleArea(radius) {
 if (radius <= 0) {
 return "Error: Radius must be greater than zero.";
 }

 const pi = Math.PI; // Use Math.PI for more accuracy
 const squaredRadius = radius * radius;
 const area = pi * squaredRadius;
 const roundedArea = Math.round(area * 100) / 100; // Round to 2 decimal
places
 return "Calculated area: " + roundedArea;
}

console.log(calculateCircleArea(5));
// Output: Calculated area: 78.54

console.log(calculateCircleArea(-1));
// Output: Error: Radius must be greater than zero.

I/O operations: I/O is short for input and output. Functions may handle interactions with system components like the screen, storage, logs, or network.

async function fetchData(url) {
 const response = await fetch(url);
 const data = await response.json();
 return data;
}

fetchData('https://jsonplaceholder.typicode.com/todos/1')
 .then(data => console.log(data));
// {
// "userId": 1,
// "id": 1,
// "title": "delectus aut autem",
// "completed": false
// }

Methods

Methods are functions attached to objects. They allow you to perform operations on the object's data. In JavaScript, methods are commonly used with objects, arrays, and other built-in types.

const person = {
 name: 'John',
 greet: function() {
 console.log('Hello, ' + this.name);
 }
};

// Calling the greet method.
person.greet(); // Output: Hello, John

Earlier in this article, you saw how to use methods of the Map and Set objects.

Primitives also have methods because under the hood everything in JavaScript is an object.

const greeting = 'Hello, world';

// Changing case.
console.log(greeting.toUpperCase()); // Output: HELLO, WORLD

// Replacing part of the string.
console.log(greeting.replace('Hello', 'Goodbye')); // Output: Goodbye,
world

// Checking if it includes a substring.
console.log(greeting.includes('world')); // Output: true

Noop

A "noop" stands for "no operation." It describes a function, operation, or command that does nothing. This can be useful for placeholders in code or to intentionally have no effect.

In JavaScript, a noop function looks like this:

function noop() {}
const noop = () => {};

Pure functions

A function is a pure function, if:

given the same inputs, it always returns the same output, and
it has no side-effects.

You've seen pure functions already. For example, both sum functions and the square function are pure.

Pure functions are deterministic. This is captured by the first property. A pure function will always produce the same output for the same set of inputs, no matter when or how many times it is called. This predictability is a key property of pure functions and is essential for reliable and testable code.

Here is an example for a function that violates the first rule.

/**
 * Generates a random integer between the start and end values, both
inclusive.
 *
 * @param {number} start - The starting value.
 * @param {number} end - The ending value.
 * @returns {number} - A random integer between the start and end.
 */
export const generateRandomInt = (start, end) =>
 Math.round(Math.random() * (end - start) + start);

generateRandomInt can be called with the same start and end values, but it produces different results because it uses Math.random().

And here is a example, which violates the second rule.

let externalArray = [];
function sideEffectingFunction(x) {
 externalArray.push(x); // Modifies external array
 return x;
}

console.log(sideEffectingFunction(5)); // 5, modifies externalArray
console.log(sideEffectingFunction(10)); // 10, modifies externalArray, too
console.log(externalArray); // Output: [5, 10]

Even though sideEffectingFunction returns something, it pushes code as a side-effect to an array and you can meaningfully call it without using it's return value.

“A dead giveaway that a function is impure is if it makes sense to call it without using its return value. For pure functions, that's a noop.” - Eric Elliott

Idempotence

Another concept you need to know is idempotence.

Idempotence is a property of certain operations in which no matter how many times you perform the operation, the result remains the same after the first application. For example, setting a value to 5 is idempotent because no matter how often you do it, the value remains 5.

let number = 5;
number = 5; // still 5
number = 5; // no change, still 5

All pure functions are idempotent, but not all idempotent functions are pure functions.
An idempotent function can cause idempotent side-effects.
A pure function cannot.
Deleting a record in a database by ID is idempotent, because the row of the table stays deleted after subsequent calls. Additional calls do nothing.

Here is a synchronous example.

const uniqueItems = new Set();
// This custom addItem function is idempotent because ...
function addItem(item) {
 uniqueItems.add(item);
 console.log(`Added item: ${item}`);
 return uniqueItems.size;
}

addItem("apple"); // Outputs "Added item: apple", returns 1
// ... calling addItem with the same item twice leaves the set unchanged.
addItem("apple"); // Outputs "Added item: apple", returns 1
addItem("banana"); // Outputs "Added item: banana", returns 2

Referential Transparency

Idempotent functions without side-effects have a feature known as referential transparency.

That means that if you have a function call:

const result = square(7);

You could replace that function call with the result of square(7) without changing the meaning of the program. So, for example if the result of square(7) is 49. Therefore, you could change the code above to:

const result = 49;

and your program would still work the same.

Functional Programming Prerequisites

A language needs three features to support functional programming, and JavaScript has all three:

First-class functions (and therefore higher-order functions),
closures, and
anonymous functions and concise lambda syntax.

First class functions

In JavaScript, functions are treated as first-class citizens. This means that functions can be stored in variables. Therefore, you can use functions as:

arguments to other functions,
return values from functions,
values to an objectʼs keys

// Storing a function in a variable.
const greet = function() {
 return "Hello, World!";
}

// Passing a function as an argument (callback).
function shout(fn) {
 const message = fn();
 console.log(message.toUpperCase());
}

shout(greet); // Output: "HELLO, WORLD!"

// Returning a function from another function.
function multiply(multiplicand) {
 return function (multiplier) {
 return multiplicand * multiplier;
 }
}

const double = multiply(2);
console.log(double(5)); // Output: 10

If you want to learn what first-class functions enable in React check out this article about higher-order components, link is in the description below.

Higher-order functions

The last example multiply that you saw is called a "higher-order function" because when you call it for the first time with a number, it returns a function.

Any function that takes in or returns a function is called a higher order function.

function greet() {
 return "Hello World!"
}

const identity = x => x; // Same as myFunction from earlier ❗
identity(greet)(); // "Hello World!"

Closure

The multiply function from earlier hid another key concept: Closure.

A closure happens when a function is bundled together with it's lexical scope. In other words, a closure gives you access to an outer functionʼs scope from an inner function. Closures in JavaScript are created whenever a function is created, at function creation time.

To use a closure, define a function inside another function and expose it by returning the inner function or passing it to another function.
The inner function can access variables in the outer function's scope, even after the outer function has returned.

function multiply(multiplicand) {
 return function(multiplier) {
 return multiplicand * multiplier;
 }
}

// Multiplicand of 2 gets captured in the closure because the inner
// returned function has access to it, even though the outer `multiply`
// function already ran to completion.
const double = multiply(2);
console.log(double(5)); // Output: 10

Closures serve three purposes:

They provide data privacy for objects.
In functional programming, they enable partial application and currying.
They act as parameters for callback or higher-order functions like map, reduce, and filter.

You're going to see 2.) and 3.) later in this article, so let's take a look at the concept of data privacy.

const createCounter = () => {
 let count = 0;
 return function increment() {
 count = count + 1;
 return count;
 }
}

const counter1 = createCounter();
const counter2 = createCounter();
counter1(); // 1
counter1(); // 2
counter2(); // 1
let capturedCount = counter1(); // 3
capturedCount = capturedCount + 39; // 42
counter1(); // 4

No external influence can manipulate the count value of counter1. You need to call counter1 to increment it.

This matters because some applications require private state. A common pattern is to prefix the private key with __.

const user = {
 __secretKey: 'abcj'
}

However, junior developers might not know that __ signals: "Do NOT change this key.", so they mutate it. And senior developers sometimes think it's okay to change it because they believe they know better.

Closures give you a reliable way to enforce data privacy for everyone.

Imperative vs Declarative

As you learned at the start of this article, functional programming is declarative. But what does that mean?

Imperative code describes "how" to do things. The code contains the specific steps needed to achieve your desired result.

Declarative code describes "what" to do. The "how" gets abstracted away.
In other words, imperative programming is about defining the process to reach an outcome. This is known as flow control, where you dictate each step of the computation.

Declarative programming, on the other hand, is about defining the outcome, known as data flow. Here, you describe what you want, and the system determines how to achieve it.

Here is an example for imperative code.

let numbers = [1, 2, 3, 4, 5];
let doubled = [];
for (let i = 0; i < numbers.length; i++) {
 doubled.push(numbers[i] * 2);
}
console.log(doubled); // Output: [2, 4, 6, 8, 10]

And here is another example of imperative code, but this time with a custom function.

function filterEvens(numbers) {
 let index = 0;

 while (index < numbers.length) {
 if (numbers[index] % 2 !== 0) {
 // Removes the item at the current index if it's odd.
 numbers.splice(index, 1);
 } else {
 // Only move to the next index if the current item was not removed
 // because the current index gets taken by the value after the
 // deleted one.
 index++;
 }
 }
}

let numbers = [1, 2, 3, 4, 5];
filterEvens(numbers);
console.log(numbers); // Output: [2, 4]

Before you look at declarative code, you need to understand immutability and abstraction.

Immutability

Immutability in programming means that an object or value cannot be modified after it is created; instead, any changes result in a new object or value.

const originalArray = [1, 2, 3];
// Creates a new array by spreading the original and adding a new element.
const newArray = [...originalArray, 4];

console.log(originalArray); // Output: [1, 2, 3]
console.log(newArray); // Output: [1, 2, 3, 4]

Similarly, mutable state is state that can be modified after you created it.

const array = [1, 2, 3];
array.push(4); // Modifies the original array by adding a new element.

console.log(array); // Output: [1, 2, 3, 4]

Immutability is a central concept of functional programming because with it, the data flow in your program is preserved. State history is maintained, and it helps prevent strange bugs from creeping into your software.

“non-determinism = parallel processing + mutable state” - Martin Odersky

You want determinism to make your programs easy to reason about, and parallel processing to keep your apps performant, so you have to get rid of mutable state.

Generally speaking, when you write your code using functional programming it becomes more
deterministic, easier to reason about, easier to maintain, more modular and more testable.

Abstraction

Abstraction is a fundamental concept in programming that involves hiding the complex reality while exposing only the necessary parts of an object or a system.

There are two types of abstraction: generalization and specialization.

Generalization is when you create a more universal form of something for use in multiple contexts. This process identifies common features among different components and develops a single model to represent all variations.

This is what most people think of when they hear "abstraction" and what Eric Elliott refers to when he says:

“Junior developers think they have to write a lot of code to produce a lot of value.
Senior developers understand the value of the code that nobody needed to write.” - Eric Elliott

Specialization is when you apply the abstraction to a specific use-case and add what makes the current situation different.

The hard part is knowing when to generalize and when to specialize. Unfortunately, there is no good rule of thumb for this - you develop a feel for both with experience.

And what you're going to find is:
Abstraction is the key to simplicity.

“Simplicity is about subtracting the obvious and adding the meaningful.” - John Maeda

Using the functional programming paradigm you can create the most beautiful abstractions.

At this point you're probably starving for examples and you're going to see some soon.

Now, it's time to look at declarative code, which will also show you more immutability and some abstraction.

Array methods

Remember, declarative programming is about "what" to do.

The perfect example of declarative code in JavaScript are the native array methods. You're going to see the three most common ones: map, filter and reduce.

`map`

Take a look at the map function first. It does exactly what we did earlier with the for loop, but the code is a lot more concise.

const numbers = [1, 2, 3, 4, 5];
const doubled = numbers.map(n => n * 2); // Output: [2, 4, 6, 8, 10]

The map method is a perfect example of abstraction.

map removes the obvious: iterating over the array and changing each value. Since it takes in a function, the map method is a higher-order function.

You only supply the meaningful: the function that doubles a number, which map applies to every number in the array. This double function is an anonymous function using the concise lamda syntax.

In general, a concise lambda is a simplified way to write a function with minimal syntax. In JavaScript it refers to the arrow function syntax.

map is also immutable because it returns a new array. numbers and doubled are two distinct arrays and the numbers array still contains the numbers 1 through 5. You can verify this by mapping using the identity function that returns its input.

const numbers = [1, 2, 3, 4, 5];
const clone = numbers.map(x => x);
console.log(numbers === clone); // false

Even though numbers and clone are both an array with the numbers 1 through 5, they are different array instances.

You might be asking yourself: "Isn't that generating tons of data that no one uses?"
Well kinda, but compared to what modern laptops are capable of the data amount is tiny, and JavaScript has garbage collection which clears up the stale memory.

`filter`

const fruits = ['apple', 'banana', 'citrus'];
const containsA = fruits.filter(fruit => fruit.includes('a'));
// Output: ['apple', 'banana'];

The filter method takes in a special function called the "predicate". A predicate is a function that always returns only a boolean. It tests each element in the array. If it returns true, the element is included in the resulting array.

filter also returns a new array aka. it's immutable.

`reduce`

The reduce method in JavaScript processes an array to produce a single output value. It takes a reducer function and an optional initial value. The reducer function itself accepts two parameters: an accumulator (which holds the accumulated result) and the currentValue from the array. The reduce method is also immutable.

Here is an example where you can use reduce on an array of numbers from 1 to 4, summing them together.

const numbers = [1, 2, 3, 4];

const sumReducer = (accumulator, currentValue) => accumulator +
currentValue;

const total = numbers.reduce(sumReducer, 0); console.log(total); //
Output: 10

In this example, reduce is called on the numbers array. The sumReducer function is used to add each number to a running total, starting from 0. Here's what happens at each step:

Step	Accumulator	Current Value	Operation	New Accumulator Value
1	0	1	0+1	1
2	1	2	1+2	3
3	3	3	3+3	6
4	6	4	6+4	10

Details of the Process:

Step 1: The accumulator starts at 0 (the initial value). The current value is the first element of the array, which is 1. They are added together to make the new accumulator value 1.
Step 2: The accumulator is now 1. The current value is the next element in the array, 2. Adding these gives 3.
Step 3: The accumulator is now 3, and the current value is 3. Adding these gives 6.
Step 4: The accumulator is now 6, and the current value is the last element, 4. Adding these gives the final result of 10.

At the end of the process, the reduce method returns 10, which is the sum of all elements in the array. This demonstrates how reduce can be used to transform an array into a single value through repeated application of a function.

reduce is the most powerful method because you can implement map and filter with reduce, but neither filter nor reduce with map and neither map or reduce with filter.

You can implement map with reduce like this:

const mapUsingReduce = (array, mapFunction) =>
 array.reduce(
 (accumulator, current) => [...accumulator, mapFunction(current)],
 [],
 );

const numbers = [1, 2, 3, 4];

const doubled = mapUsingReduce(numbers, x => x * 2);
console.log(doubled); // Output: [2, 4, 6, 8]

You can implement filter with reduce like this:

const filterUsingReduce = (array, filterFunction) =>
 array.reduce(
 (accumulator, current) =>
 filterFunction(current) ? [...accumulator, current] : accumulator,
 [],
 );

const numbers = [1, 2, 3, 4];

const evens = filterUsingReduce(numbers, x => x % 2 === 0);
console.log(evens); // Output [2, 4]

Expressions over Statements

In functional programming, you'll see many expressions and few statements. Expressions avoid
intermediate variables, while statements often bring side-effects and mutable state.

Statements

Imperative code frequently utilizes statements. A statement is a piece of code that performs an action.

Loops - for, while, etc.

// Loops:
// A for loop that logs numbers 0 to 4.
for (let i = 0; i < 5; i++) {
 console.log(i);
}
// A while loop that decrements x and logs it until x is no longer greater
than 0.
while (x > 0) {
 x--;
 console.log(x);
}

Control flow - if, switch, etc.

// An if...else statement that logs if x is positive or not.
if (x > 0) {
 console.log("x is positive");
} else {
 console.log("x is zero or negative"); 
}
// A switch statement that handles different color cases.
switch (color) {
 case "red":
 console.log("Color is red");
 break;
 case "blue":
 console.log("Color is blue");
 break;
 default:
 console.log("Color is not red or blue");
}

Error handling - try...catch, throw, etc.

// A try...catch block that handles errors from riskyFunction.
try {
 let result = riskyFunction();
} catch (error) {
 console.error(error);
}
throw new Error("Something went wrong"); // Throws a new error with a
message.

Except for functions, if it's a keyword with curly braces, you're likely dealing with a statement. (❗)

Expressions

Declarative code favors expressions. An expression evaluates to a value.

Literal expressions

42; // The number 42 is a literal expression.
"Hello"; // The string "Hello" is a literal expression.

Arithmetic expressions

5 + 3; // Evaluates to 8.
x * y; // Evaluates to the product of x and y.

Logical expressions

true && false; // Evaluates to false.
x || y; // Evaluates to x if x is true, otherwise y.

Function expressions

const funcExpr = function() { return 42; }; // Defines a function
expression.
const arrowFunc = () => 42; // Defines an arrow function expression.

Object and array initializers

{ name: "John", age: 30 }; // Object initializer expression.
[1, 2, 3]; // Array initializer expression.

Property access expressions

obj.name; // Accesses the "name" property of obj.
array[0]; // Accesses the first element of array.

Function calls

square(7); // Evaluates to 49.
Math.max(4, 3, 2); // Evaluates to 4.

Function composition

You’re about to unlock a new understanding of code and gain superpowers, so "lock-in".

“All software development is composition: The act of breaking a complex problem down to smaller parts, and then composing those smaller solutions together to form your application.” - Eric Elliot

Whenever you use functions together, you're "composing" them.

const increment = n => n + 1;
const double = n => n * 2;
function doubleInc(n) {
 const doubled = double(n);
 const incremented = increment(doubled);
 return incremented;
}

doubleInc(5); // 11

But with anything in life, you can do it better if you do it consciously. The code above is actually NOT the ideal way to write it because:

The more code you write, the higher the surface area for bugs to hide in.

less code = less surface area for bugs = less bugs

The obvious exception is clear naming and documentation. It's fine if you give a function a longer name and supply doc strings to make it easier for your readers to understand your code.

You can reduce the surface area for bugs by avoiding the capturing of the intermediary results in variables.

const increment = n => n + 1;
const double = n => n * 2;

const doubleInc = n => inc(double(n));
doubleInc(5); // 11

In mathematics, function composition is taking two functions f and g and applying one function to the result of another function: h(x) = (f ∘ g)(x) = f(g(x)). Note: The hollow dot ∘ is called the composition operator.

In mathematical notation, if you have two functions f and g, and their composition is written as (f ∘ g)(x), this means you first apply g to x and then apply f to the result of g(x). For your example, f(n) = n1 and g(n) = 2n, the composition h(n) = f(g(n)) calculates 2n + 1.

Note: Generally mathematicians use x (or y or z etc.) to represent any variable, but in the code example above n is used to subtly hint at the parameter to be a number. The different name has no impact on the result.

You can abstract away the composition operator ∘ into a function called compose2 which takes two functions and composes them in mathematical order.

const compose2 = (f, g) => x => f(g(x)); // ∘ operator

const increment = n => n + 1; // f(n)
const double = n => n * 2; // g(n)

const doubleInc = compose2(increment, double); // h(n)
doubleInc(5); // 11

compose2 only works for two functions at a time.

But get ready, because this is where it gets powerful.

If you want to compose an arbitrary amount of functions, you can write a generalized compose.

const compose = (...fns) => x => fns.reduceRight((y, f) => f(y), x);
// reduceRight works like reduce, but iterates the array from
// the last item to the first item.

const increment = n => n + 1;
const double = n => n * 2;
const square = n => n * n;

const incDoubleSquare = compose(square, double, increment);
incDoubleSquare(3); // 64

The compose function here is written using the mathematical variable names. If you want to take the names that you might be used to from reduce, then you'd write it like this:

const compose =
 (...functions) =>
 initialValue =>
 functions.reduceRight(
 (accumulator, currentFunction) => currentFunction(accumulator),
 initialValue,
 );

const increment = n => n + 1;
const double = n => n * 2;
const square = n => n * n;

const incDoubleSquare = compose(square, double, increment);
incDoubleSquare(3); // 64

compose takes multiple functions as its arguments, and collects them into an array fns via the rest syntax.

It then returns a child function that takes in the initialValue x and returns the array fns with the
reduceRight method applied to it. The reduceRight method then takes in a callback function and the initialValue x.

That callback function is the heart of compose. It takes in the accumulator y (starting from x) and the currentValue f, which is a function from the array fns. It then returns that function f - called with the accumulator y.

The result of that function call, then becomes the accumulator y for the next iteration. Here the next function f from fns get called with that new accumulator value. This repeats until the initialValue x has been passed and transformed through all functions from the array fns.

Function Call	Accumulator `y`	currentValue `f`	Operation	New Accumulator
Initial value	3	-	-	3
increment	3	`increment`	increment(3) = 3 + 1	4
double	4	`double`	double(4) = 4 * 2	8
square	8	`square`	square(8) = 8 * 8	64

Many people who are used to reading texts from left to right find it unintuitive to compose functions in mathematical order. Many functional programming packages provide another function called commonly pipe, which composes function from left to right in reverse mathematical order.

const pipe = (...fns) => x => fns.reduce((y, f) => f(y), x);

const increment = n => n + 1;
const double = n => n * 2;
const square = n => n * n;

const incDoubleSquare = pipe(increment, double, square);
incDoubleSquare(3); // 64

`trace`

You might be asking right now. "But way, what if you want to debug your code? Then you need to capture the intermediate results in variables, right?"

You actually do not. You only need a helper higher-order function called trace.

const trace = msg => x => {
 console.log(msg, x);
 return x;
}

And here is how you can use it.

const pipe = (...fns) => x => fns.reduce((y, f) => f(y), x);
const trace = msg => x => {
 console.log(msg, x);
 return x;
}

const increment = n => n + 1;
const double = n => n * 2;
const square = n => n * n;

const incDoubleSquare = pipe(
 increment,
 trace('before double'),
 double,
 trace('after double'),
 square
);
incDoubleSquare(3); // 64
// Also logs out:
// before double 4
// after double 8

Currying

You saw another technique being used called currying.

Currying is a transformation of functions that translates a function from callable as f(a, b, c) into callable as f(a)(b)(c). In other words, a function is curried if it can take in each of it's parameters one at a time.

function addUncurried(a, b) {
 return a + b;
}

function addCurried(a) {
 return function(b) {
 return a + b;
 }
}

addUncurried(41, 1); // 42
addCurried(41)(1); // 42

With arrow functions, these definitions can become one-liners by leveraging their implicit returns.

const addUncurried = (a, b) => a + b;

const addCurried = a => b => a + b;

addUncurried(41, 1); // 42
addCurried(41)(1); // 42

Here a addCurried is a function that takes in a number a and returns a function b => a + b. You can read it like this:

const addCurried = (a => (b => a + b));

You can curry any function. For example, you can create custom map and reduce functions.

const map = fn => arr => arr.map(fn);
const reduce = fn => x => arr => arr.reduce(fn, x);

Map takes in two parameters and reduce takes in three. The number of parameters a function expects in its definition is called arity.

There are shorthand terms for functions that take in 1, 2 and 3 parameters.

Unary function: Takes one argument, e.g. square.
Binary function: Takes two arguments, e.g. map.
Ternary function: Takes three arguments, e.g. reduce.

In the context of currying, understanding arity is important because each step in a curried function reduces the arity by one until all expected arguments have been received and the final operation can be performed.

Additionally, the first function of a composition can have any arity, but ever following function needs to be unary.

const add3 = (a, b, c) => a + b + ; // Ternary
const double = n => n * 2; // Unary

const addThenDouble = pipe(add3, double);
addThenDouble(6, 7, 8); // 42

Exercise: create your own custom filter function that is curried and takes in a predicate pred and then an array arr and then filters the array based on the predicate.

Wouldn't it be nice if you had a function that can curry any function?

const addUncurried = (a, b) => a + b;

const curry = /* ... magic? ... */

const addCurried = curry(addUncurried);

Well there it is.

const addUncurried = (a, b) => a + b;

const curry = (f, array = []) =>
 (...args) =>
 (a => (a.length >= f.length ? f(...a) : curry(f, a)))([
 ...array,
 ...args,
 ]);

// NOTE: because of f.length, this implementation of `curry` fails with
// functions that use default parameters.
const addCurried = curry(addUncurried);

const increment = addCurried(1);
increment(4); // 5
addCurried(1, 4); // 5
addCurried(1)(4); // 5

The previous example used the mathematical names for the variables .If you want to name the variables more descriptively to understand curry now, you can write the function like this:

const curry =
 (targetFunction, collectedArguments = []) =>
 (...currentArguments) =>
 (allArguments =>
 allArguments.length >= targetFunction.length
 ? targetFunction(...allArguments)
 : curry(targetFunction, allArguments))([
 ...collectedArguments,
 ...currentArguments,
 ]);

curry uses recursion, which is when a function calls itself for the purpose of iteration. Let's break it down:

f or targetFunction: The original function you want to curry.
array or collectedArguments: An array to collect the arguments of all currying calls. Each cycle (except for the last) new arguments get added.
args or currentArguments: An array of the arguments taken in with the current invocation of the curried function (in this case: addCurried).
a or allArguments: An array of arguments concatenated from the currentArguments and the collectedArguments from the previous calls.

When we call addCurried with one or more arguments, these current arguments get taken in as args in the child function of curry. This child function returns another function (grand-child function of curry).

The grand-child function immediately invokes itself with an array concatenated from the collected arguments array and the current arguments args, receiving these values from its grand-parent and parent closure. It takes this new array as the all arguments a and checks if the all arguments a contains the same or higher amount of arguments as the target function f is declared with.

If yes, this means all necessary currying calls have been performed: It returns a final call of the target function f invoked with the all arguments a. If not, it recursively invokes curry once again with the target function f and the new all arguments a, which then get taken in as the new collected arguments array.
This repeats until the a.length condition is met.

Side notes:

During the first call, the all arguments a and the current arguments args are the same value, as the collected arguments array has nothing added to it yet.
The grand-child function's immediate invocation happens before its parent function completes.

Partial Application

As you learned earlier, an application happens when the arguments are used to replace the function's parameters. This allows the function to perform its task using the provided arguments.

const add = (a, b) => a + b;
const inc = n => add(1, n);

A partial application is the process of applying a function to some, but not all, of its arguments. This creates a new function, which you can store in a variable for later use. The new function needs fewer arguments to execute because it only takes the remaining parameters as arguments.

Partial applications are useful for specialization when you want to reuse a function with common
parameters.

const add = a => b => a + b;
const inc = add(1); // point-free
const incPointed = n => add(1)(n); // pointed

Point-Free Style
inc is defined in point-free style, which is when you write a function without mentioning the parameters.

inc uses closure because the argument 1 is captured in the closure of add as a.
There are two requirements for your code to be composable: "data last" and the data needs to line up.

Data First vs. Data Last

"data last" means the data your functions operate on should be their last parameter.
For the add and multiply functions you saw earlier the order of arguments is irrelevant because they are commutative.

const add = a => b => a + b;
const otherAdd = b => a => a + b;

const a = 41;
const b = 1;
console.log(add(41, 1) === otherAdd(41, 1)); // true

But division is NOT, so you're going to learn the importance of the "data last" principle using a divide function.

const divideDataLast = (y) => (x) => x / y;
const divideDataFirst = (x) => (y) => x / y;

Let's say you want to specialize and create a halve function that takes in a number and divides it by two.

Using the "data first" function, it's impossible for you to define a halve function in point-free style.

const divideDataLast = (y) => (x) => x / y;

const divideDataFirst = (x) => (y) => x / y;

const halve = divideDataLast(2);
// const halveFail = divideDataFirst(2); 🚫 fails
const halvePointed = (n) => divideDataFirst(n)(2);

halfFail captures 2 in the closure of divideDataFirst. It is a function that takes in a number and when called divides 2 by that supplied number.

In general, you need to write your functions using the "data last" principle to enable partial application.

BTW, the best library for functional programming in the "data last" paradigm is Ramda. Here is an outlook what you can do with Ramda. You can understand this in-depth some time in the future.

import { assoc, curry, keys, length, pipe, reduce, values } from 'ramda';

const size = pipe(values, length);

size({ name: 'Bob', age: 42 }); // 2
size(['a', 'b', 'c', 'd']); // 4

const renameKeys = curry((keyReplacements, object) =>
 reduce(
 (accumulator, key) =>
 assoc(keyReplacements[key] || key, object[key], accumulator),
 {},
 keys(object),
 ),
);

const input = { firstName: 'Elisia', age: 22, type: 'human' };
const keyReplacements = { firstName: 'name', type: 'kind', foo: 'bar' };

renameKeys(keyReplacements)(input);
// Output: { name: 'Elisia', age: 22, kind: 'human' }

size is a function that can take in objects or arrays and returns how many properties or elements it has.

Remember, functional programming is meant to improve your code by making it more bug-free, modular, testable, refactorable, understandable and deterministic. So, if you mix imperative and declarative code, like in the definition for renameKeys that is totally fine. Relax if you need some time to understand implementations like this. As you play around with this new paradigm, go with what's easiest for you to write. There is no need to force functional programming.

You can call renameKeys with keyReplacements and an input to return a new object with it's keys renamed according to the keyReplacements.

Data Needs to Line Up

Similarly, only with "data last" can you compose functions effectively because the types of the arguments and return values of functions have to line up to compose them. For example, you can't compose a function that accepts an object and returns a string with a function that receives an array and returns a number.

// (number, number) => number[]
const echo = (value, times) => Array(times).fill(value);
// number[] => number[]
const doubleMap = array => array.map(x => x * 2);

// Correct composition. ✅
const echoAndDoubleMap = compose(doubleMap, echo);

// Reminder, the first function in a composition does NOT need to
// be unary, and echo is binary.
// echoAndDoubleMap starts binary and ends unary.
console.log(echoAndDoubleMap(3, 4)); // [6, 6, 6, 6]

// Incorrect composition that will throw an error. ❌
const wrongOrder = compose(echo, doubleMap);

try {
 // This will fail because doubleMap expects an array,
 // instead of two numbers.
 console.log(wrongOrder(3, 4));
} catch (error) {
 console.error("Error:", error.message); // Error: array.map is not a
function
}

Mozart

Now it's your turn. Try the following exercise to practice what you've learned from this article. If you get stuck, you can always scroll up and read it again. If you prefer not to do the exercise, just read the solution and follow along.

Create a function that takes in an array of numbers and filters all the even numbers (so it rejects the odd numbers), then doubles all the even numbers and lastly, sums up the result. Break down your functions to their most basic abstractions then compose them point-free. (Hint: You'll need to look up the modulo operator % to check if a number is even.)

const curry =
 (f, array = []) =>
 (...args) =>
 (a => (a.length >= f.length ? f(...a) : curry(f, a)))([
 ...array,
 ...args,
 ]);

const add = curry((a, b) => a + b);
const multiply = a => b => a * b;

const inc = add(1);
const double = multiply(2);
const isEven = n => n % 2 === 0;

const map = fn => arr => arr.map(fn);
const filter = pred => arr => arr.filter(pred);
const reduce = curry((fn, acc, arr) => arr.reduce(fn, acc));

const doubleMap = map(double);
const filterEvens = filter(isEven);
const sum = reduce(add, 0);

const pipe = (...fns) => x => fns.reduce((y, f) => f(y), x);

const mozart = pipe(filterEvens, doubleMap, sum);

mozart([1, 2, 3, 4, 5]); // 12

Lastly, is this more complicated than simply writing the following?

const mozart = numbers =>
 numbers
 .filter(n => n % 2 === 0)
 .map(n => n * 2)
 .reduce((a, b) => a + b, 0);
mozart([1, 2, 3, 4, 5]); // 12

Yes, absolutely! You should always use the simplest implementation for your requirements, also known as KISS (Keep It Simple, Stupid), or YAGNI (You Ain't Going To Need It).

Functional programming shines as your app grows and you need to generalize and specialize your code so it scales well and stays maintainable. This way your code is more modular, and way easier to test, to reuse and to refactor. Future articles will show you real-world examples how to use these techniques.

You now know the 20% of functional programming that gives you 80% of the result.

Higher Order Components are Misunderstood in React

Jan Hesters — Thu, 12 Sep 2024 11:28:58 +0000

When you interview 100s of "senior" React developers, you'd be surprised how many fail to answer this simple question:

"What is a higher-order component?"

And even less can answer the follow-up question: "Why do higher-order components in React exist?"

In other words: "Did any React team member consciously create higher-order components as a concept and put them into React?"

In this article, you'll find out the correct answers to these questions, and learn everything you need to know about HOCs.

Note: Make sure you understand arrow functions and the basics of React.

Abstract

You're first going to see the formal definition of HOCs and through the rest of this article you’ll understand the theory behind it.

A Higher-Order component is a function that takes a component and returns a new component.

The React docs further state:

"A higher-order component (HOC) is an advanced technique in React for reusing component logic. HOCs are not part of the React API, per se. They are a pattern that emerges from React’s compositional nature."

The theory behind HOCs comes from ...

Function Composition

In mathematics, function composition is the act of combining functions to form a new function or a result, by applying one function to the result of another.

In JavaScript, this looks this:

const inc = n => n + 1; // f
const double = n => n * 2; // g

// h(x) = (f ∘ g)(x) = f(g(x))

const doubleThenInc = x => inc(double(x)); // h

Notice how you assign the combined functions to a new variable called doubleThenInc, which you can do because JavaScript has first-class functions.

You can learn more about first-class functions in this article, which also explains the difference between useCallback and useMemo.

A programming language has first-class functions if it allows you to assign functions to variables.

You can abstract the composition to combine any two functions:

const compose2 = (f, g) => x => f(g(x));

const doubleThenInc2 = compose2(inc, double);

You omit the argument x in the definition of doubleThenInc2. This means doubleThenInc2 is defined point-free, which is when you define a function without mentioning its arguments.

const doubleThenInc = x => inc(double(x)); // mentions X 👉 pointed
const doubleThenInc2 = compose2(inc, double); // point-free

If you want to compose an arbitrary amount of functions, you need to generalize the composition function.

const compose = (...fns) => x => fns.reduceRight((y, f) => f(y), x);

const square = n => n * n;

const doubleThenInc3 = compose(inc, double);
const doulbeThenIncThenSquare = compose(square, inc, double);

More sophisticated versions of the compose function are frequently exposed by libraries that leverage HOCs such as Redux and Apollo.

The arguments and return values of functions have to line up to compose them. For example, you can't compose a function that accepts an object and returns a string with a function that receives an array and returns a number.

// (number, number) => number[]
const echo = (value, times) => Array(times).fill(value);
// number[] => number[]
const doubleMap = array => array.map(x => x * 2);

// Correct composition. ✅
const echoAndDoubleMap = compose(doubleMap, echo);

console.log(echoAndDoubleMap(3, 4)); // [6, 6, 6, 6]

// Incorrect composition that will throw an error. ❌
const wrongOrder = compose(echo, doubleMap);

try {
  // This will fail because doubleMap expects an array,
  // instead of two numbers.
  console.log(wrongOrder(3, 4));
} catch (error) {
  console.error("Error:", error.message); // Error: array.map is not a function
}

Since inc and double both take and return numbers, you can compose them in any order.

// Composition that doubles then increments. ✅
const doubleThenInc = compose(inc, double);
console.log(doubleThenInc(3)); // 7

// Composition that increments then doubles. ✅
const incThenDouble = compose(double, inc);
console.log(incThenDouble(3)); 8

Additionally, compose2 and compose are higher-order functions.

A higher-order function is a function that either receives or returns a function or does both.

const multiply = multiplier => multiplicant => multiplier * multiplicant;
const double = multiply(2);

const map = f => arr => arr.map(f);

const doubleMap = map(double);

const numbers = [1, 2, 3];

doubleMap(numbers); // [2, 4, 6]

multiply IS a higher-order function because it takes in a number and returns a function.
double IS NOT a higher-order function because it neither receives nor returns a function. It is defined point-free.
map IS a higher-order function because it both accepts and returns a function.
doubleMap IS NOT a higher-order function because it neither receives nor returns a function. It is defined point-free.

React components can either be functions or classes.

import { Component } from 'react'

function MyFunctionComponent() {
  return <div>Function</div>
}

class MyClassComponent extends Component {
  render() {
    return <div>Class</div>
  }
}

In JavaScript, the class keyword is essentially a wrapper for the function keyword and handles prototypal inheritance. In other words, classes compile to constructor functions.

Therefore, since all components are functions in React and JavaScript has higher-order functions, you get HOCs for free. That is what the docs mean when they say HOCs "are a pattern that emerges from React’s compositional nature."

Now you should understand the basic definition of HOCs:

A Higher-Order component is a function that takes a component and returns a new component.

Any function whose input and output is a React component is a HOC.

HOCs by Example

You probably want to see what a higher-order component looks like. Follow the rest of this tutorial to write your own using TDD. You're going to use Vitest with React Testing Library to write the tests.

You can deduce two requirements from the definition of a higher-order component:

HOCs are functions.
HOCs take a component and return a component.

You can capture these requirements in a unit test.

import { render, screen } from '@testing-library/react';
import { describe, expect, test } from 'vitest';

import myHOC from './my-hoc';

function MyComponent({ title = 'Hello' }) {
  return <p>{title}</p>;
}

describe('myHOC', () => {
  test('given a component: returns the component with a default title', () => {
    const WrappedComponent = myHOC(MyComponent);

    render(<WrappedComponent />);

    expect(screen.getByText('Hello')).toHaveTextContent('Hello');
  });
});

The test checks both requirements because when this test passes, you can logically deduce that your HOC is a function and that it returns a component without spelling out those requirements explicitly. If the HOC were not a function and you tried to call it, it would throw, and your unit test would fail with a clear stack trace. Likewise, the test renders the return value of the HOC, which ensures it is a React component.

Notice how you did NOT test for typeof function here. Unit tests which only test types are an anti-pattern. It's redundant with simply calling the function and checking its output value. In general, type checks are redundant with well-written unit tests. This is why unit tests can catch most type errors, without the need for additional measures like type annotations (though annotations and type inference can still be useful to enable IDE tooling).

You can get the test to pass by making your HOC the identity function.

export default Component => Component;

Your test result should now look like this.

 ✓ app/my-hoc.test.jsx (1)
   ✓ myHOC (1)
     ✓ given a component: returns the component with a default title

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  16:07:11
   Duration  128ms

 PASS  Waiting for file changes...
       press h to show help, press q to quit

Why HOCs?

Your current HOC does nothing. And you're going to change that, soon.

In general, HOCs excel at abstracting logic or styling. They allow you to avoid unnecessary code duplication. If you find yourself repeating certain JSX or logic patterns in your component, you might be able to abstract them away using HOCs.

For example, if you have a page for your web site or a screen for your React Native app, most pages or screens have the same layout. They all share elements such as headers, footers or formatting containers.

Making Your HOC Useful

You can add styling abilities to our HOC and call it withLayout instead of MyHOC.

Start by adding a test that verifies that your HOC adds a layout to your component.

import { render, screen } from '@testing-library/react';
import { describe, expect, test } from 'vitest';

import withLayout from './with-layout';

function MyComponent({ title = 'Hello' }) {
  return <p>{title}</p>;
}

describe('withLayout', () => {
  test('given a component: returns the component with a default title', () => {
    const WrappedComponent = withLayout(MyComponent);

    render(<WrappedComponent />);

    expect(screen.getByText('Hello')).toHaveTextContent('Hello');
  });

  test('given a component: renders the layout around the component', () => {
    const WrappedComponent = withLayout(MyComponent);

    render(<WrappedComponent />);

    expect(screen.getByRole('heading')).toHaveTextContent(/some title/i);
    expect(screen.getByRole('main')).toContainElement(screen.getByText('Hello'));
    expect(screen.getByRole('contentinfo')).toHaveTextContent(/some footer/i);
  });
});

Watch your test fail, then create a layout component.

export function Layout({ children }) {
  return (
    <div>
      <header>
        <h1>Some Title</h1>
      </header>

      <main>
        {children}
      </main>

      <footer>
        <p>Some footer</p>
      </footer>
    </div>
  );
}

Layouts can vary depending on the app and framework that you're using. In React Native app, you find yourself writing similar layout HOCs using React Navigation's <SafeAreaView />. In a Remix app, you won't need a layout HOC because you can export a layout component from your root.tsx file.

Now, make your test pass by using the Layout component in your HOC.

import { Layout } from './layout';

export default Component => () => (
  <Layout>
    <Component />
  </Layout>
);

Your tests should both pass now.

 ✓ app/with-layout.test.jsx (2)
   ✓ withLayout (2)
     ✓ given a component: returns the component with a default title
     ✓ given a component: renders the layout around the component

 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  16:05:39
   Duration  128ms

 PASS  Waiting for file changes...
       press h to show help, press q to quit

Notice how the withLayout HOC now takes in a component and then returns a function because before this change it actually was NOT a higher-order component.

This also shows the most common misconception about HOCs. Many developers answer the question of "What is a higher-order component" with "it's a component that takes in a React component and returns it".

They probably think of something like this.

// Wrong! ❌
function NotAHigherOrderComponent({ Component }) {
  return (
    <div>
      <h1>Header added by NotAHigherOrderComponent</h1>
      <Component />
    </div>
  );
}

function MyComponent() {
  return <p>Hello, I am a regular component.</p>;
}

function App() {
  return (
    <div>
      <NotAHigherOrderComponent Component={MyComponent} />
    </div>
  );
}

What you see above is a React component that takes in another React component as a prop.

But that's is NOT a higher-order component because HOCs are functions and NOT components. You can NOT render a HOC.

Looking back at the your withLayout HOC, it contains a bug. Can you spot it?

If not, that is okay. You can write the following test to expose the error.

describe('withLayout', () => {
  // ... your other tests

  test('given props for the wrapped component: passes on the props to the wrapped component', () => {
    const WrappedComponent = withLayout(MyComponent);
    const customTitle = 'Custom Title';

    render(<WrappedComponent title={customTitle} />);

    expect(screen.getByText(customTitle)).toHaveTextContent(customTitle);
  });
});

The new test fails.

 ❯ app/with-layout.test.jsx (3)
   ❯ withLayout (3)
     ✓ given a component: returns the component with a default title
     ✓ given a component: renders the layout around the component
     × given props for the wrapped component: passes on the props to the wrapped component

The test exposes the problem: You fail to pass props to the wrapped component. You can make the test pass by passing on the props the HOC receives.

import { Layout } from './layout';

export default Component => props => (
  <Layout>
    <Component {...props} />
  </Layout>
);

Now your tests pass because your HOC correctly passes on the props to the wrapped component.

 ✓ app/with-layout.test.jsx (3)
   ✓ withLayout (3)
     ✓ given a component: returns the component with a default title
     ✓ given a component: renders the layout around the component
     ✓ given props for the wrapped component: passes on the props to the wrapped component

 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  16:55:45
   Duration  139ms

 PASS  Waiting for file changes...
       press h to show help, press q to quit

However, the abstraction capabilities of HOCs wouldn't be as useful if they didn't have another key feature. Eric Elliott describes it like this:

"The primary benefit of HOCs is not what they enable (there are other ways to do it); it's how they compose together at the page root level."

In other words, the key to using HOCs well is to know how and when you want to compose them. You you write a test to demonstrate the "how". Spoiler: it is fundamentally function composition.

Here is a test that shows how you compose HOCs.

import { render, screen } from '@testing-library/react';
import { describe, expect, test } from 'vitest';

import withLayout from './with-layout';

function MyComponent({ title }) {
  return <p>{title}</p>;
}

describe('withLayout', () => {
  // ... your other tests

  test('given used in composition with other HOCs: passes on the props of the other HOCs', () => {
    const compose = (...fns) => x => fns.reduceRight((y, f) => f(y), x);
    const withTitle = Component => props => (
      <Component title="foo" {...props} />
    );
    const ComposedComponent = compose(
      withLayout,
      withTitle
    )(MyComponent);

    render(<ComposedComponent />);

    expect(screen.getByText('foo')).toHaveTextContent('foo');
  });
});

This test already passes.

You compose withLayout with withTitle. withTitle is a HOC that injects a title prop to a component.

Configuring HOCs

It is common for HOCs to accept configuration objects. You probably encounter this when using React Redux' connect with mapStateToProps. (In fact, it accepts two more arguments: mapDispatchToProps and mergeProps.)

Assume that some pages should render without the header, so you modify your layout component to take in a prop that let's you show and hide the header.

export function Layout({ children, showHeader = true }) {
  return (
    <div>
      {showHeader && (
        <header>
          <h1>Some Title</h1>
        </header>
      )}

      <main>{children}</main>

      <footer>
        <p>Some footer</p>
      </footer>
    </div>
  );
}

Now write a test that allows you to modify your HOC. You'll also need to modify your existing tests to accommodate the fact that your HOC now takes in a configuration object.

import { render, screen } from '@testing-library/react';
import { describe, expect, test } from 'vitest';

import withLayout from './with-layout';

function MyComponent({ title = 'Hello' }) {
  return <p>{title}</p>;
}

describe('withLayout', () => {
  test('given a component: returns the component with a default title', () => {
    const WrappedComponent = withLayout()(MyComponent);

    render(<WrappedComponent />);

    expect(screen.getByText('Hello')).toHaveTextContent('Hello');
  });

  test('given a component: renders the layout around the component', () => {
    const WrappedComponent = withLayout()(MyComponent);

    render(<WrappedComponent />);

    expect(screen.getByRole('heading')).toHaveTextContent(/some title/i);
    expect(screen.getByRole('main')).toContainElement(
      screen.getByText('Hello'),
    );
    expect(screen.getByRole('contentinfo')).toHaveTextContent(/some footer/i);
  });

  test('given props for the wrapped component: passes on the props to the wrapped component', () => {
    const WrappedComponent = withLayout()(MyComponent);
    const customTitle = 'Custom Title';

    render(<WrappedComponent title={customTitle} />);

    expect(screen.getByText(customTitle)).toHaveTextContent(customTitle);
  });

  test('given used in composition with other HOCs: passes on the props of the other HOCs', () => {
    const compose =
      (...fns) =>
      x =>
        fns.reduceRight((y, f) => f(y), x);
    const withTitle = Component => props => (
      <Component title="foo" {...props} />
    );
    const ComposedComponent = compose(withLayout(), withTitle)(MyComponent);

    render(<ComposedComponent />);

    expect(screen.getByText('foo')).toHaveTextContent('foo');
  });

  test('given a component and NOT rendering the header: does NOT render the header', () => {
    const WrappedComponent = withLayout({ showHeader: false })(MyComponent);

    render(<WrappedComponent />);

    expect(screen.queryByRole('heading')).toBeNull();
  });
});

Watch all your tests fail because your component still lacks the configuration object. Add it to make them pass.

import { Layout } from './layout';

export default ({ showHeader = true } = {}) =>
  Component =>
  props => (
    <Layout showHeader={showHeader}>
      <Component {...props} />
    </Layout>
  );

To answer the question of when to use composition for HOCs, remember what I told you learned earlier. HOCs are excellent if you want to abstract away common logic between many components. You chose to give your function a layout functionality because that is one area that most screens of your application will share. Using compose you can define a HOC that you can use to wrap all your pages with.

Real-World Example

Here is a real-world example of a SignInForm container component. See if you understand it, then read the explanation to check if you were correct.

import { withFormik } from 'formik';
import compose from 'ramda/src/compose.js';
import { connect } from 'react-redux';
import { withRouter } from 'react-router';
import SignInComponent from './sign-in-form-component.js';
import { isAuthenticating, signIn } from './user-authentication-reducer.js';
import { signInValidationSchema } from './validation-schema.js';

const initialFormValues = { email: '', password: '' };

const mapStateToProps = state => ({ loading: isAuthenticating(state) });

const formikConfig = {
  handleSubmit: ({ email, password }, { props: { signIn } }) => {
    signIn({ email, password });
  },
  mapPropsToValues: () => initialFormValues,
  validationSchema: signInValidationSchema,
};

export default compose(
  withRouter,
  connect(
    mapStateToProps,
    { signIn }
  ),
  withFormik(formikConfig),
)(SignInComponent);

In the example above, you composed 3 different HOCs.

withRouter is a HOC from React Router DOM. It injects the history object, which you can use to navigate to the password reset screen, when the user clicks the "Forgot Password" button.
connect is a HOC from React Redux. You use it to connect your component to your Redux store. You inject the loading prop and the signIn action creator.
withFormik is a HOC from Formik. Formik let's you control local form state and handles form validation for you.

Sometimes you need to copy over static properties such as propTypes, defaultProps and getStaticProps (if you are using Next.js) from the inner component to the resulting component. Here is a Higher-Order HOC (a function that returns a HOC), which does this for you.

import hoistNonReactStatics from 'hoist-non-react-statics';

const hoistStatics = higherOrderComponent => Component => {
    const WrappedComponent = higherOrderComponent(Component);
    hoistNonReactStatics(WrappedComponent, Component);
    return WrappedComponent;
};

BTW: When using HOCs you need to treat refs special, too. If you need to pass refs through a component hierarchy, you should probably be using a hook for the ref instead of a HOC.

HOC Composition

You know from function composition that you can only compose functions whose types line up. Similarly, you need to pay attention to the order in which you compose your HOCs. One HOC can inject props that another might depend on. If the one that depends on the props gets injected before the prop injecting HOC, your app might break.

const formatTitleProp = ({ title, ...otherProps }) => ({
  title: title.toUpperCase(),
  ...otherProps,
});

const withTitle = Component => props => <Component title="Hello" {...props} />;

const withFormattedTitle = Component => props => (
  <Component {...formatTitleProp(props)} />
);

const breakingApp = compose(withFormattedTitle, withTitle)(App); // 🔴 Breaks!

const workingApp = compose(withTitle, withFormattedTitle)(App); // ✅ Correct order!

If you switch the order of HOCs in the real-world example above, it will break, too. withFormik(formikConfig) depends on signIn being defined, and transformProps depends on both history and the formikBag props.

HOCs with implicit dependencies on each other may be a code smell. In some cases, it may be better to make those dependencies explicit, by importing the shared functionality into the components that need them, or taking the dependency as a configuration parameter of the HOC. It's probably ok to implicitly depend on something that's pretty universal to all your pages, such as your store provider.

Now you can confidently:

Identify HOCs in your codebase.
Write your own HOCs to abstract common logic and styling across components.
Compose multiple HOCs to achieve more complex functionalities.

For a deeper dive into React, check out my YouTube channel!

12 Keys to Write Senior-Level Tests (Test Desiderata in JavaScript)

Jan Hesters — Thu, 05 Sep 2024 09:27:58 +0000

"Desiderata" is derived from the Latin word for "things desired."

Kent Beck wrote an article called "Test Desiderata". And together with Kelly Sutton, they created a YouTube playlist about that article that explains the desirable properties of automated tests. Some of these properties are trade-offs and not every test needs to have them.

The examples Kent and Kelly give are in Ruby. Consider this article a TL;DW with some additions and a translation into JavaScript.

The examples in this tutorial use RITEway because of its genius API that forces you to write good tests. It also uses Jest once, where RITEway prohibits you from writing bad tests. You should really watch Ken's and Kelly's playlist in addition to reading this article - even if you, like me, don't know Ruby. Their explanations are fun and enlightening.

Obviously you should also learn Jest and Vitest because they are the most popular testing frameworks in JavaScript. But that's a topic for another article.

Let's dive into the principles.

Behavioral-Sensitive

Tests should be sensitive to the behavior of your code.

const calculateSF = (hours, rate) => hours * Math.max(rate, 15);

const calculate = (hours, rate, zipCode = null) => {
  if (zipCode === '94103') {
    return calculateSF(hours, rate);
  } else {
    return hours * rate;
  }
};

describe('calculate', async assert => {
  const hours = 40;

  {
    const rate = 8;

    assert({
      given: 'your hours and your rate',
      should: 'return the total hourly wage',
      actual: calculate(hours, rate),
      expected: 320,
    });
  }

  {
    const rate = 14;
    const zipCode = '94103';

    assert({
      given:
        'your hours, your rate below $15 and your zip code is in San Francisco',
      should:
        'return the total hourly wage calculated with the minimum wage of $15',
      actual: calculate(hours, rate, zipCode),
      expected: 600,
    });
  }

  {
    const rate = 16;
    const zipCode = '94103';

    assert({
      given:
        'your hours, your rate above $15 and your zip code is in San Francisco',
      should:
        'return the total hourly wage calculated with your actual rate',
      actual: calculate(hours, rate, zipCode),
      expected: 640,
    });
  }
});

If you change the behavior of the code, the results of the tests should change, too. If you change the minimum wage in calculateSF to 150 dollars, the tests for the San Francisco zip code fail.

Structure-Insensitive

Tests should be insensitive to the internals of your code's structure.

RITEway makes it nearly impossible to write structure sensitive tests because there is no mocking API like mock functions, spies or module mocks.

So the next example uses Jest to write structure-sensitive code by using spyOn. You need to create an hourlyWageCalculator object to be able to use spyOn.

const hourlyWageCalculator = {
  calculateSF(hours, rate) {
    return hours * Math.max(rate, 15);
  },
  calculate(hours, rate, zipCode = null) {
    if (zipCode === '94103') {
      return this.calculateSF(hours, rate);
    } else {
      return hours * rate;
    }
  },
};

describe('calculate', () => {
  const hours = 40;

  describe('given your hours, your rate below $15 and your zip code in San Francisco', () => {
    it('should return the total hourly wage calculated with the minimum wage of $15', () => {
      const rate = 14;
      const zipCode = '94103';
      const spy = jest.spyOn(hourlyWageCalculator, 'calculateSF');

      hourlyWageCalculator.calculate(rate, hours, zipCode);

      expect(spy).toHaveBeenCalledWith(rate, hours);

      spy.mockRestore();
    });
  });

  describe('given your hours, your rate above $15 and your zip code in San Francisco', () => {
    it('should return the total hourly wage calculated with your actual rate', () => {
      const rate = 16;
      const zipCode = '94103';
      const spy = jest.spyOn(hourlyWageCalculator, 'calculateSF');

      hourlyWageCalculator.calculate(rate, hours, zipCode);

      expect(spy).toHaveBeenCalledWith(rate, hours);

      spy.mockRestore();
    });
  });
});

Here we made the assumption that calculateSF exists and that we are using it. If we refactor the code to inline the San Francisco calculation, the tests fail because they are structure sensitive.

const hourlyWageCalculator = {
  calculate(hours, rate, zipCode = null) {
    if (zipCode === '94103') {
      return hours * Math.max(rate, 15);
    } else {
      return hours * rate;
    }
  },
};

If you refactor code without changing its behavior, the test results should stay the same. The RITEway tests from the behavior section above are invariant to the structure of the code. You might now this property as "avoid testing implementation details".

Readable

"Tests, like code, are read more than written." - Kent Beck
Some things that make code more readable actually reduce the readability of tests.

const defaultHours = 40;

describe('calculate', async assert => {
  const hours = defaultHours;

You might see how most people work 40 hours per week and therefore create a defaultHours constant and re-use it in your test setups. But, drying up your tests often makes them less readable.

Avoid writing a test that is a few lines, but incomprehensible and impossible to understand without reading a lot of other lines of shared setup code.

"You're not supposed to repeat yourself, unless you're supposed to repeat yourself." - Kent Beck
Tests should be self-contained and therefore tests can be verbose. The reader must be able to extract the motivation for the test and what happens in the test.

(Obviously, there are trade-offs and there are occasions where you want to generalize your tests setup.)

Writable

Tests should be easy to write. If the tests for your code are hard to write, it indicates your code has a bad API, is too tightly coupled or you lack good setup functions.

const calculate = employee => employee.weeklyHours * employee.hourlyRate;

const createEmployee = ({
  firstName = '',
  lastName = '',
  address = '',
  weeklyHours = 0,
  hourlyRate = 0,
}) => ({
  firstName,
  lastName,
  address,
  weeklyHours,
  hourlyRate,
});

describe('calculate', async assert => {
  {
    const employee = createEmployee({
      firstName: 'Kent',
      lastName: 'Beck',
      address: '1 Main St., Berkeley, CA, 94701',
      weeklyHours: 40,
      hourlyRate: 8,
    });

    assert({
      given: 'an employee',
      should: 'calculate the total hourly wages',
      actual: calculate(employee),
      expected: 320,
    });
  }

  {
    const employee = createEmployee({
      firstName: 'Kelly',
      lastName: 'Sutton',
      address: '1 Main St., San Francisco, CA, 94103',
      weeklyHours: 40,
      hourlyRate: 7,
    });

    assert({
      given: 'an employee',
      should: 'calculate the total hourly wages',
      actual: calculate(employee),
      expected: 280,
    });
  }
});

In these tests, firstName, lastName and address could be deleted and are irrelevant for calculate. Its the fault of the system that the tests are expensive relative to the code under test.

If you need dozens or hundreds of lines of test setup to test a few lines of code, that's a design problem, not a test problem. For example, your tests might use a lot of mocks because your code is too tightly coupled and has many side-effects.

"If you're unable to test it, you designed it wrong." - Kent Beck

Fast

Tests should run quickly.

On average it takes your brain 23 minutes to re-focus on a task after it gets distracted. And those distractions can happen within seconds. Good tests help you stay in flow because they run fast.

const delay = seconds =>
  new Promise(resolve => {
    setTimeout(() => {
      resolve();
    }, seconds * 1000);
  });

Add this delay function before each assert in the tests.

await delay(5);

assert({
  given: // ...

Now run your tests and see how you feel. Watch how your mind drifts off while you wait for those tests to finish ...

You can run your unit tests in under a second by isolating side-effects and composing your code from pure functions. Your CI / CD pipeline (including your integration and functional tests) should run in under 10 minutes.

Avoid interrupting flow to keep your engineering team productive.

Automated

Machines should do the testing, not humans.

Avoid Q&A teams having to manually test your release candidates for regressions. This is what automated tests are for.

The benefits of automated tests compound. Initially, it might be faster and cheaper to click through your app and writing the test takes longer.

However as your app grows, not investing into automated tests causes compounding debt.

It gets harder to add tests.
Manually going through your program's flow takes longer than a machine clicking through it.
Machines have better memory than humans. Once a test is written, the machine doesn't forget the test case and prevents regressions.
You pay a computer less per hour than an engineer.
While the automation (CI / CD pipeline) runs, you can work on new features.
Automated tests guarantee program correctness (- when your tests are good).

Isolated

Isolated tests can run in any order and in parallel. Whether one test passes or not should have no effect on whether another test passes. To achieve this, the state needs to be the same before and after each test.

let numberOfCalculations = 0;
const calculate = (hours, rate) => ++numberOfCalculations * hours * rate;

describe('calculate', async assert => {
  const hours = 40;

  {
    const rate = 8;

    assert({
      given: 'your hours and your rate',
      should: 'return the total hourly wage',
      actual: calculate(hours, rate),
      expected: 320,
    });
  }

  {
    const rate = 10;

    assert({
      given: 'your hours and your rate',
      should: 'return the total hourly wage',
      actual: calculate(hours, rate),
      expected: 560,
    });
  }
});

If you change the order of the tests, they both fail, even though the code is the same. If the code was right before, the tests should still pass and if it was wrong before, the tests should still fail.

In these tests the order matters because they both share mutable state. Tests should have no shared state and they should be isolated from their environment (e.g. DOM, database, scope etc.).

The tests depending on the order they run in points to a flaw in the code's design. Prefer to write code where you initialize the state locally (in the scope of the test). If your code is correct and must change the state, you should restore the initial state after each test.

Composable

"The confidence provided by one test should combine with the confidence provided by other tests." - Kent Beck

const inc = n => n + 1;
const double = n => n * 2;
const incDouble = n => double(inc(n));

describe('inc', async assert => {
  assert({
    given: 'a number',
    should: 'increment it by 1',
    actual: inc(41),
    expected: 42,
  });
});

describe('double', async assert => {
  assert({
    given: 'a number',
    should: 'return the number doubled',
    actual: double(21),
    expected: 42,
  });
});

describe('incDouble', async assert => {
  assert({
    given: 'a number',
    should: 'increment it by 1 and double the result',
    actual: incDouble(20),
    expected: 42,
  });
});

We ensure the correctness of inc and double and then ensure the correctness of the composed function incDouble. The calculation of inc is isolated from double and vice versa and both are isolated from incDouble.

To make your tests composable, your code needs to be composable, too.

Specific

A failing test should point you to the cause of failure.

If you break incDouble by changing the order in the function composition, your test points you to the failure.

const incDouble = n => inc(double(n)); // 🚫

incDouble
  ✖  Given a number: should increment it by 1 and double the result
  ------------------------------------------------------------------
      operator: deepEqual
      diff: "42" => "41"
      source: ...

The stack trace (given by RITEway in the source key) tells us exactly which test failed and therefore which component broke.

If you restore incDouble and break inc by having it add 2 to your number, two tests break.

const inc = n => n + 2; // 🚫

inc
  ✖  Given a number: should increment it by 1
  --------------------------------------------
      operator: deepEqual
      diff: "42" => "43"
      source: ...

double
  ✔  Given a number: should return the number doubled

incDouble
  ✖  Given a number: should increment it by 1 and double the result
  ------------------------------------------------------------------
      operator: deepEqual
      diff: "42" => "44"
      source: ...

Using the stack trace you can find the test that points you to the cause of both errors. When you encounter multiple errors in your stack, the leafs are likely the source of the error.

Deterministic

Given the same code, tests should produce the same results.

A few years ago, I helped with a project that had a flaky test.

const slice = 'userAuthentication';

const getExpirationDate = ({ [slice]: { expirationDate } }) => expirationDate;
const THIRTY_MINUTES = 30 * 60 * 1000;

const getShouldUpdateToken = state => {
  const now = new Date().getTime();
  const expirationDate = getExpirationDate(state);
  return now > expirationDate - THIRTY_MINUTES;
};

describe('user authentication reducer', async assert => {
  // ... more tests

  {
    const now = new Date().getTime();
    const state = { auth: { expirationDate: now + THIRTY_MINUTES } };

    assert({
      given:
        'an expiration date 30 minutes into the future and a get should update token selector',
      should: 'return false',
      actual: getShouldUpdateToken(state),
      expected: false,
    });
  }

  // ... more tests
});

What made this test flaky, was the side effect in getShouldUpdateToken. The selector creates a new Date object. Occasionally, this would happen a millisecond after the test setup and the test would fail.

You can make this test deterministic by making the unit under test a pure function and explicitly passing the arguments to the function in the test.

const getShouldUpdateToken = (state, now) => {
  const expirationDate = getExpirationDate(state);
  return now > expirationDate - THIRTY_MINUTES;
};

Tests shouldn't be flaky (even though some test frameworks accommodated for unreliable tests). They should be independent of random number generations, times, dates, locations, language settings, operating systems etc.

BTW, the example that Kent and Kelly give in their video in Ruby excellently visualizes the problem for E2E tests.

Predictive

Passing tests should give you confidence to deploy to production.

Some environments and conditions are only created in production environments. Sometimes you can't know a condition is going to exist and even if you know about it, it's hard or impossible to replicate it.

If you find an error in production, you can write a test for it when you fix it and prevent the bug from resurfacing.

100% predictability can rarely be achieved in the real world.

To maximize predictability, aim for 100% case coverage instead of 100% code coverage by using unit tests and integration tests. You can have 100% of your code covered by unit tests, but your application is still broken.

Inspiring

Tests should give you that feeling of confidence.

Tests should make a difference to team productivity. Your team should be faster and merge more often. Good tests serve as documentation, help with onboarding and aid in understanding code that someone else wrote. (That someone else might be your past you.) They should allow you to increase your deploy frequency while decreasing your deploy risk. Tests make you relax. Tests allow you to rewrite or delete code.

"And finally, tests are a way to liberate energy, to move from worry to hope, creativity, and empathy, to demonstrate trustworthiness.
Passing tests should feel good." - Kent Beck

Use These 12 Keys to Write Senior-Level Tests (Test Desiderata in JavaScript)

Jan Hesters — Wed, 04 Sep 2024 17:11:59 +0000

In this article, you'll learn 12 testing best practices that every senior developer should know. You will see real-world JavaScript examples for Kent Beck’s article "Test Desiderata" because his are in Ruby.

These properties are designed to help you write better tests. Knowing them can also help you ace your next job interview.

If you want to improve your JavaScript testing skills, and write better tests, this guide has everything you covered. The testing skills you learn in this tutorial are also applicable for TypeScript.

https://www.reactsquad.io/blog/testing-desiderata-in-javascript