DEV Community: Alessandro Magionami

ShipWithAI #9 — Validate Your Side Project Idea in 30 Minutes

Alessandro Magionami — Mon, 06 Oct 2025 07:44:52 +0000

Make sure your next AI side project is worth building before you write a single line of code.

Steps:
• Write down your idea — even one sentence is enough.
• Score it across 10 factors: urgency, market size, pricing, CAC, delivery cost, uniqueness, speed to market, upfront investment, upsell potential, and evergreen potential.
• Let AI generate scores and short explanations for each factor.
• Review the total score (out of 100) and read the AI’s summary.
• Compare several ideas using the same framework to spot your strongest one.
• Use the results to decide: pivot, refine, or start building.

Gotchas:
• Don’t skip evaluation and jump straight into coding — it wastes time.
• Don’t rely on gut feeling alone; structured scoring gives clarity.

Do this today:
• Pick one idea you’ve been thinking about.
• Run it through the 10-factor evaluation prompt.
• Use the total score to decide if it’s worth pursuing.

Full guide →

ShipWithAI #8 — Ship a One-Feature MVP in 1 Week

Alessandro Magionami — Wed, 24 Sep 2025 17:18:10 +0000

Build and validate a one-feature MVP fast. This is for solo devs using AI to move from idea to proof without overbuilding.

Steps:
• Pick one job story with a clear success metric
• Use AI to draft a one-page spec (journey, UI, API, tests, not-doing list)
• Slice to essentials: one screen, two endpoints, three tests, one metric
• Test with real users or fake doors for quick signal
• Assess the metric: pass → add one adjacent feature; fail → tighten flow and retry
• Run the loop again until you hit the metric

Gotchas:
• Don’t waste time on auth, dashboards, or settings before value is proven
• Don’t validate based on vibes—only on your metric

Do this today:
• Write a job story using the “When / I want to / so I can” format
• Define one numeric success metric
• Run the AI one-pager prompt and trim it to one screen

Full guide →

Build AI Features That Work in 4 Steps

Alessandro Magionami — Thu, 18 Sep 2025 14:04:14 +0000

Stop wrestling with bloated AI prompts and build features users actually want.
Steps:
• Build the MVP: Create core functionality with basic data models and CRUD operations
• Enhance with validation: Add input checks, error handling, and user experience improvements
• Expand capabilities: Add related features like editing, deleting, or notifications within the same scope
• Refine the polish: Improve UI/UX, mobile responsiveness, and visual consistency for production

Gotchas:
• Don't try to build everything at once—AI works best with focused, incremental tasks
• Avoid expanding beyond one feature per cycle or you'll break unrelated code

Do this today:
• Pick one feature idea and write down the core user scenario in one sentence
• Define the absolute minimum version (just the essential action)
• Create a simple data model with 3-4 fields maximum

Full guide

5 lessons I learned as a GraphQL developer

Alessandro Magionami — Tue, 23 Jan 2024 09:32:02 +0000

GraphQL is a very powerful and versatile tool, but it's very easy to use it wrong.

1. GraphQL is not REST

GraphQL allows clients to request specific data in a single request, while REST uses a fixed set of endpoints with predefined data.

GraphQL queries are very different from REST endpoints. Expose your data to the client by creating generic queries, allowing the client to compose the request as they need. Decouple your API from the application.

Avoid creating situation-specific queries.

2. Use Resolvers as functions

Resolvers can be functions; that's the real deal.

Use them as functions; don't limit your data to what's in the database. Decouple the DB structure from the shape you want to expose to the client. Use resolvers to manipulate data and connect entities.

Make resolvers your strength; they are the reason why GraphQL is so powerful.

3. Create Custom Scalars

Create custom types in GraphQL, as it is a typed system.

You should create custom scalars for structures that don't fall into GraphQL standard scalar types. Custom scalars can be used to validate input and output data, as well as to parse and serialize values in specific ways.

Make your types safe and modular by using and reusing custom scalars.

4. Cache data using Dataloaders

The same data may be requested more than once in the same query.

Entities in GraphQL may be connected in different ways because GraphQL is a graph. Dataloaders ensure that the entity is only loaded the first time and cached every other time when this occurs.

Using dataloaders to cache data will greatly improve your performance.

5. Decompose queries using Fragments

Fragments are a way to make your GraphQL queries modular on the client.

Having one giant query on a single component on the client is not ideal. It is way better to split the query into multiple components where each component only requests the data it needs. Don't worry about multiple requests, several GraphQL frameworks will merge those queries automatically.

Make queries modular using Fragments.

Why Factory method in Node?

Alessandro Magionami — Tue, 14 Jul 2020 11:55:20 +0000

Introduction

So here we are for part 4 of our Node Design Patterns series.

I took a little brake from the series to write another little article about file watchers and hot reload (Implement your own hot-reload).

But now, here I am to to try explaining another design pattern.
The pattern I'm talking about is the Factory Pattern. One the most common patterns in every language probably.

We have several examples of very famous libraries which make wide use of this pattern:

JQuery, just writing $('#my_element_id') we are invoking a function called '$' which creates a JQuery object. - Node itself uses Factory Pattern in its 'http' module, for example, when we use http.createServer() we are, in fact, creating a Server object.

In this post I will focus more on the "why" instead of the "how" simply because I believe this pattern is pretty easy to understand and there are several implementations while the main thing to understand is, in my opinion, the reason why such pattern is so useful.

Note

This pattern is simple to implement and one of the more documented, so in this post I tried to focus more on the reason behind this pattern and when it is particularly useful instead of the implementation itself.

Let's start with the explanation.

The idea

Imagine you want a logger for your application.

For this example let's just use our good old friend the console's log.

It is not uncommon to log something different basing on your current environment.

For example if you are in development environment you might want to log some debug informations, but, in production, these informations might be useless or even dangerous for security reasons.

So, to achieve this goal, what you can do something like this:

// index.js

// some code

if (process.env.NODE_ENV === 'development') {
  console.log('hello')
}

// other code

And yes, it works.

While in development mode you'll see your detailed logs, in production, instead, you will not.

So, where is the problem?

Let me ask you something: do you really want this if statements all around your code?

Probably you don't.

So, how can we create a logger which behaves differently in development and production environments?

First of all let's separate our logger from the rest of our code by simply creating a service for it:

// logger.js

class Logger {
  constructor () {
    this.debug = console.log
    this.info = console.info
    this.warn = console.warn
    this.error = console.error
  }
}

module.exports = Logger

As you can see I created different type of logs, nothing too fancy, just wrapping the usual console functions.

The important thing to understand is that probably you want to have all these log functions both in development and in production, except for the debug one.

So, our application might look like this:

// index.js
const Logger = require('./logger')

const logger = new Logger()

// some code

logger.info('Informations')

// some other code

if (err) {
  logger.error(err)
}

// more code

if (process.env.NODE_ENV === 'development') {
  logger.debug('debug')
}

Well nothing changed, we still have the same if statement we would like to get rid of.

A possible way to handle this is to move the logic inside the logger itself:

// logger.js

class Logger {
  constructor () {
    this.debug = process.env.NODE_ENV === 'development' ? console.log : () => {}
    this.info = console.info
    this.warn = console.warn
    this.error = console.error
  }
}

module.exports = Logger

This way in our application we don't need to add the if statement since it is already been made when the logger is created.

The last line of index.js will look like this:

// index.js
logger.debug('debug')

And we don't need to worry about the environment since that function will be an empty one in production.

Done right?

No more if around our code, all the logic of the logger is centralized in the Logger itself.

Well, in the constructor actually... is that ok?

The constructor is a function that should initialize a new instance of a class, a new object basically.

But, as good programmers, we know the Single Responsibility Principle, so our constructor should just initialize a new object. Nothing else.

Having that logic inside our constructor is a side effect, something that, in more complicated scenarios, might introduce bugs or behaviors hard to understand without looking at the implementation of the Logger.

Our Logger service should not contain logic related to the application where it is used, it should only do its job: logging informations at different levels.

Logger's constructor should look like this:

// logger.js

class Logger {
  constructor (debug, info, warn, error) {
    this.debug = debug
    this.info = info
    this.warn = warn
    this.error = error
  }
}

module.exports = Logger

This way the constructor is no more responsible for the behavior of any of the logger's methods, it just takes them as parameters and initializes a new Logger using them.

So, who should be responsible to define the debug function basing on the environment? The Factory function.

The Factory Pattern

The Factory Pattern just means that, when creating a new instance of an object, we won't use the constructor directly but we will use, instead, a create function.

This way we can separate the structure of such object (defined in the constructor) and some logic which might depend on the environment or some other events.

Our logger service will look like this:

// logger.js

function Logger () {
  this.debug = console.log
  this.info = console.info
  this.warn = console.warn
  this.error = console.error
}

module.exports = {
  create: function () {
    const debug = process.env.NODE_ENV === 'development' ? console.log : () => {}
    return new Logger(debug, console.info, console.warn, console.error)
  }
}

While in our index file we will have:

// index.js

const LoggerFactory = require('./logger')

// process.env.NODE_ENV = 'production'
process.env.NODE_ENV = 'development'

const logger = LoggerFactory.create()

logger.debug('debug')
logger.info('info')
logger.warn('warn')
logger.error('error')

That's it!

I told you the implementation was simple.

But please just focus on some important things:

the service does not export the constructor method, so the only way to create a new logger it by using the create function. This is important because you may have a third party library which does not expose a constructor method sometimes and using a Factory to wrap that dependency is a very clean way to locate the relationship between your code and the dependency, so, if one day you want to replace it, you only need to modify the Factory
it is very simple and clean, if necessary, to modify the Factory function to create a Singleton of a service
the structure of the Logger service is completely separated from its behavior in different environments

Conclusion

The Factory Pattern is probably one the most common, I used it several times in my fulltime job and in my side projects in different languages.

As I said in the Introduction it is simple to implement but the reasons why it is so important are a bit tricky to get.

I think I did not realize the real meaning of this pattern since I read it in the book Node Design Patterns.

I really hope you find this post useful and if you have any question don't hesitate to comment below or send me a DM.

Implement your own hot-reload

Alessandro Magionami — Tue, 03 Mar 2020 12:03:44 +0000

Introduction

Recently I worked to add a Typescript scaffold to the fastify-cli and I noticed that it provide, by using its 'start' command, the hot-reload for your application.

I kept looking at how the watcher works and found out that it uses a library which is, essentially, a wrapper around the 'watch' function of the Node module 'fs'.

I started thinking about it and, looking into the official Node doc, I started diving deeper and deeper trying to figure out how watchers work in Node.

After a few days here I am to let you implement a very simple hot-reload module and trying to explain what I understood about the 'watch' function of Node and how it is even possible for Javascript code to know when a file is changed.

But, before that, let me just introduce what hot-reload is for those of you who are not familiar with the term.

What is hot-reload?

When working on an application it is possible to make that application restart or reload every time we edit the code.

Let me explain this with an example:

// app.js

console.log('Hello world!')

To execute this file all I need to do is to run this script in my command line:

$ node app.js

// output
Hello world!

Now, if I want to change the message, for example, and print it again all I need to do is to run the script again.

// app.js

console.log('Hello universe!')

$ node app.js

// output
Hello universe!

Wouldn't be great if I could have something watching at my 'index' file and re-launching the script for me as soon as the code is changed?

Well, this is what hot-reload means.

Implementation

Let's take the first example's file as our target:

// app.js

console.log('Hello world!')

Node provides a really useful function to watch file changes in its 'fs' module which is called 'watch'.

This function takes a filename as first parameter and return an object called 'FSWatcher'.

FSWatcher extends EventEmitter class it will emit some events we can listen.

Note

If you don't know how EventEmitter class works in Node you can take a look at the official doc or you could consider this post I published.

Here is how our 'watcher' looks like:

// watcher.js
const fs = require('fs')

const watcher = fs.watch('app.js')

fs.on('change', () => console.log('changed'))

Running it:

$ node watcher.js

You will notice that the process doesn't stop until you stop it. This is because, off course, the 'watch' function keeps watching at the file until we say it to stop or we kill the process.

Now, while watcher is running, just try to edit the message in your 'app.js' file and look that 'changed' happens in your terminal.

Note

Seeing the 'changed' message appear twice for every change might be related on your system.

So now we have a 'watcher' which tells us when our application in modified.

Not so useful honestly, it would be better if it would reload our application immediately.

What we want is this:

$ node watcher.js

// output
Hello world!

// changing the message to 'Hello universe!'

//output
Hello universe!

One possible way to achieve this goal is to use the 'child_process' module provided by Node (for doc click here).

Let's start with the code:

const fs = require('fs')
const child = require('child_process')

// watch the target file
const watcher = fs.watch('app.js')
// create a child process for the target application
let currentChild = child.fork('app.js')

watcher.on('change', () => {
  // we assure we have only one child process at time
  if (currentChild) {
    currentChild.kill()
  }
  // reset the child process
  currentChild = child.fork('app.js')
})

So, what is happening here is:

we spawn a new process which is child of the current process we are in using fork ('currentChild')
every time we receive a 'change' event we kill the 'currentChild' and create another fork process

Consider this is not the only way to achieve the goal and, probably, not the best, but it is, in my opinion, the easiest to understand.

For a more in depth explanation of how 'process' module works please refer to the official doc.

Now, by executing our watcher in a shell:

$ node watcher.js

// output
Hello world!

// after editing the message inside app.js
Hello universe!

Under the hood

Now we have our simple implementation of an hot-reload module.

But how is it possible for the 'watch' function to know when the file changes?

First thing you may think is polling. You may think that Node takes somehow a screenshot of the current state of a file and, after some milliseconds, it compares with the current state of the file.

Well, this is what happens if you decide to use the watchFile function of 'fs' module.

But it's not our case.

Reading the documentation about the 'watch' function you'll encounter a paragraph titled Availability.

In this paragraph you can find that the operating system is able to notify filesystem changes.

This notifications, off course, are different basing on the OS we are using.

What I will try to do from now on is to follow this notifications (events) emitted by the operating system until we reach the 'JS land' where we can listen to them using Node's functions.

inotify

Let's consider we are using Linux for example.

As you can see, reading the Node official documentation, when Linux is the OS filesystem events are notified by inotify. The API provided by inotify provides a mechanism to monitor both files and directories. It can emit several events depending on what is happening:

IN_ACCESS
IN_ATTRIB
IN_CLOSE_WRITE
IN_CLOSE_NOWRITE
IN_CREATE
IN_DELETE
IN_DELETE_SELF
IN_MODIFY
IN_MOVE_SELF
IN_MOVED_FROM
IN_MOVED_TO
IN_OPEN

Since we are trying to watch when a file is edited we may consider the IN_MODIFY event.

If we keep reading until the 'Examples' section we can have the confirm which we took the correct event:

write(fd, buf, count);
  Generates IN_MODIFY events for both dir and dir/myfile.

So essentially the IN_MODIFY event is generated when the file is written.

But we are still far away from the moment when we can use our JS code to listen to the event, so let's keep going with the next step.

If you are familiar with Node you should have heard of libuv.

libuv is the library Node uses for a lot of things, one of those things is filesystem.

Next step is looking for the event IN_MODIFY emitted by inotify inside libuv's source code.

libuv

Going into the GitHub repository of libuv and searching for IN_MODIFY will produce a single result in a file located at src/unix/linux-inotify.c, sounds familiar?

Yep, correct, this is the part of libuv which is responsible for the interaction with inotify and, in facf, scrolling down the file we can find this lines:

  if (e->mask & (IN_ATTRIB|IN_MODIFY))
          events |= UV_CHANGE;
  if (e->mask & ~(IN_ATTRIB|IN_MODIFY))
    events |= UV_RENAME;

It looks like our event IN_MODIFY is mapped to UV_CHANGE or UV_RENAME in libuv.

This sounds reasonable, so libuv maps different events coming from the OS (with different names) to the same events, this way Node and any other system using libuv will have to look for UV_CHANGE without considering the system it is running on.

What we finally have to do is to look for these 2 events in Node finally.

Node... finally

Events related to the filesystem are controlled by a module named FSEvent, this module can monitor a given path for changes and emit events basing on what happened:

UV_CHANGE
UV_RENAME

So, these 2 events are emitted by libuv when a certain path/file is changed or renamed.

The only thing we still need to see know is where Node takes these events to emit Javascript events we can listen to.
To answer this question what we can do is simply go into the Node source code.

So, let's go to the Node repository (here) and just use the GitHub search to look for UV_CHANGE inside the repository.

The first result of our search will bring us to a file called fs_event_wrap and, scrolling down this file, we will find what we were looking for in this comment where, basically, it is explained that libuv can set both UV_CHANGE and UV_RENAME at one time but the Node API allows only one event at time to be passed to the "JS land" so, if a UV_RENAME occurs, the UV_CHANGE will be ignored basically.
Finally we found where the libuv filesystem events handler is wrapped in Node.

But still no Javascript.

After a little more searching we can find lib/internal/fs/watchers.js file (a JS file) where we can notice a significant require instruction:

const { FSEvent } = internalBinding('fs_event_wrap');

Our answer might be in that 'internalBinding' function.

This function is in a file located at lib/internal/bootstrap/loaders.js.
This file (as explained in the comment at the beginning of the file itself) is compiled before the actual Node bootstrap and it is used to create, among other stuff, 'internalBinding' which is the private internal loader of C++ code.

So, the strange require instruction where 'internalBinding' is used should be now clear.

We can think 'internalBinding' as a 'require' for the C++ code in Node.

Going back to our lib/internal/fs/watchers.js and following the 'FSEvent' we reach line:

  this._handle = new FSEvent();

and finally:

  this.emit('change', eventType, filename);

which is exactly what we were looking for.

Conclusion

I hope you enjoyed my explanation but, please, consider I am note a professional Node developer and my goal is not to provide a production-ready implementation of a watcher off course.

My goal is just to, possibly, tease your curiosity, like mine have been writing this post, and suggest you to go deeper into things you think you are not fully understanding.

Please let me know if you think there are things that could be explained better (there should be) and, if you want, comment below with questions too and I'll do my best to answer.

Node Parallel Execution

Alessandro Magionami — Thu, 13 Feb 2020 16:09:20 +0000

Introduction

So, we reached out part 3 of our journey through some Node design patterns. In the first two parts we focused on Observer Pattern (one of the most important design pattern not only in Node but in all Javascript applications) and Sequential Iterator (useful to handle some tasks we want to be sure are executed in a certain order).

In this post we will analyze a new pattern which has some parts in common with Sequential Iterator but it is very important to understand the differences between the two.

Again, as explained in part 2, I'll assume you have a good knowledge of Javascript and event loop in particular, if you don't feel comfortable with asynchronous code i suggested a good resource on part 2 of this series.

Finally, be ready to code, because in this post we will write a lot of code!

The idea

In this case the idea is very similar to part 2, with only one difference: we want to execute some asynchronous tasks in parallel.

Why should I execute tasks in parallel instead on sequentially?

Well, the answer is pretty simple: performance.

Imagine you have a certain number of tasks, 3 for example, and you want to execute them in any order.

You might think to execute them one after the other... and you'll be right!

Everything will be fine, but, if you want to move a little bit forward and try to make your code a bit more optimized you might consider executing those tasks at the same time, or at least make them start as soon as possible (I'll explain this later).

Note

Important! Tasks should be unrelated, which means that you won't have any control on which one will finish before the others. So, if you need to complete one or more tasks before the others please consider using another pattern.

You may find this code familiar:

// index.js

function task1 () {
  setTimeout(() => {
    console.log('task 1')
  }, 3000)
}

function task2 () {
  setTimeout(() => {
    console.log('task 2')
  }, 2000)
}

function task3 () {
  setTimeout(() => {
    console.log('task 3')
  }, 1000)
}

In this example timers don't matter so feel free to change them as you like.

So the idea is: we want to execute any number of tasks without a specific order and (why not?) being notified when all tasks are completed.

Let's dive into the pattern!

Parallel Execution

The Parallel Execution pattern doesn't execute tasks at the same time... yeah, i'm not crazy but let me explain what it means.

What we will do, in fact, is simply execute each task like this:

// index.js

function execute (tasks) {

  let completed = 0 

  for (let task of tasks) {
    task(() => {
      /*Only the last task will make this condition be true and so we will
       have notified when the last task finishes*/
      if (++completed === tasks.length) {
        console.log('All tasks have been completed')
      }
    })
  }

}


$ node index.js

// output
task 3
task 2
task 1
All tasks have been completed

In Node, or in general in Javascript, you don't have a way to execute at the same time multiple tasks.

What you can do, instead, is you can execute the synchronous part of each task and "push" the asynchronous part of them to the event loop.

To fully understand what is happening inside our code let's make a little change to our tasks:

// index.js

function task1 () {
  console.log('sync task 1')

  setTimeout(() => {
    console.log('task 1')
  }, 3000)
}

function task2 () {
  console.log('sync task 2')

  setTimeout(() => {
    console.log('task 2')
  }, 2000)
}

function task3 () {
  console.log('sync task 3')

  setTimeout(() => {
    console.log('task 3')
  }, 1000)
}

Each task will now log its synchronous part separately:


$ node index.js

// output
sync task 1
sync task 2
sync task 3
task 3
task 2
task 1
All tasks have been completed

As you will notice the sync parts will be printed almost immediately while the async ones will appear after, respectively, 1, 2 or 3 seconds.
So here is a step by step explanation of what is happening:

in the for loop we are executing each task one by one
the sync part of each task is completed immediately like if you were doing this:

  for (let i = 1; i <= tasks.length; i++) {
    console.log(`task ${i}`)
  }

after executing the sync part the remaining part of a task still remains what's inside the setTimeout, which is the async part. This part cannot be execute immediately, because it is asynchronous. So it is sent in the event loop.
after the established amount of time set in the setTimeout function each task will be put in a queue
at every clock, the event loop will look into the queue and, if present, will find an instruction (our tasks) and execute it

Note

This is a really simple explanation of what is happening, but, again, it is not the purpose of this post to explain how the event loop works.

Using Promises

Promises have a really useful function called 'Promise.all' we can use:

// index.js

const TASKS = [ task1, task2, task3 ]

function execute (tasks) {
  return Promise.all(tasks.map((task) => task()))
    .then(() => console.log('All tasks have been completed'))
}

function task1 () {
  return Promise.resolve()
    .then(() => console.log('task 1'))
}

function task2 () {
  return Promise.resolve()
    .then(() => console.log('task 2'))
}

function task3 () {
  return Promise.resolve()
    .then(() => console.log('task 3'))
}

execute(TASKS)

This function returns a promise which resolves if all the promises in the array parameter resolve.

Limited Parallel Execution

Imagine you have more than 3 tasks, like 100 or 1000.

Now, consider this tasks being, for example, api calls.

Using one of the previous algorithms might cause some troubles like being blocked by the api because making too many requests.

Even without any kind of limit from the target api it is a good practice to limit the number of tasks you want to run at the same time.

Here it comes an improved version of the Parallel Execution pattern called Limited Parallel Execution.

Let's start with the callback version:

//index.js

/* Here I added more tasks to make it clear in the output which one is being executed */
const TASKS = [ task1, task2, task3, task4, task5, task6 ]
const MAX_EXECUTION_TASKS = 2

function execute (tasks) {

  let completed = 0
  let running = 0
  let index = 0

  function run () {
    /* If it was the last one print the message */
    if (++completed === tasks.length) {
      console.log('All tasks have been completed')
    }
    while (running < MAX_EXECUTION_TASKS && index < tasks.length) {
      /* Execute tasks until you rich the limit on max running tasks */
      tasks[index++](() => {
        /* The task is completed */
        completed++, running--
        run()
      })
      running++
    }
  }

  run()
}

Basically what is happening is:

the first time we execute the function we start task1 and task2 (running = 2, completed = 0, index = 1)
as soon as one the tasks (for example task1) completes we go inside its callback (completed = 1, running = 1, index = 1) and run is executed again
this time we are starting just task3 because running is equal to 1, so, after that, we will have: running = 2, completed = 1, index = 2

The execution will continue like this until it reaches the end of the last task (notice that we cannot be sure the last task to be completed is task6, changing timers will change the order of the output off course).

Limited Parallel Execution Promise version

Promise version of this pattern, again, is similar to the callback one:

//index.js

const TASKS = [ task1, task2, task3, task4, task5, task6 ]
const MAX_EXECUTION_TASKS = 2

function execute (tasks) {

  let completed = 0
  let running = 0
  let index = 0

  function run () {
    if (completed === tasks.length) {
      return console.log('All tasks have been completed')
    }
    while (running < MAX_EXECUTION_TASKS && index < tasks.length) {
      tasks[index++]().then(() => {
        running--, completed++
        run()
      })
      running++
    }
  }

  return run()
}

Note

This implementation is different from the one proposed in the book the series is inspired to. I preferred keeping the algorithm more similar to the callback one without introducing other services.

Once again, using 'then' instead of callbacks will do the magic.

Conclusion

Understanding how this pattern works is, in my opinion, a good way to clarify how asynchronous code works in Javascript and why is useful to have asynchronous code, why some instructions are not executed directly but, instead, their execution is demanded to the event loop.

Try to change timers to get different results.

Node Sequential Iterator Pattern

Alessandro Magionami — Sat, 01 Feb 2020 08:55:20 +0000

Introduction

To understand some of the concepts explained in this post you should know have a good knowledge of the event loop and how asynchronous programming works in Javascript, for brevity i will not cover these arguments in detail here so, if you want to a great explanation of how event loop works watch this video.

The idea

Imagine we have a series of tasks (functions) we want to execute in a certain order:

// index.js

function task1 () {
  console.log('task 1')
}

function task2 () {
  console.log('task 2')
}

function task3 () {
  console.log('task 3')
}

In our index file we have a function 'execute' which is responsible for the execution of all our tasks:

// index.js

function execute () {
  task1()
  task2()
  task3()
}

execute()

Can you figure out what's the output in a shell?

$ node index.js

// output
task 1
task 2
task 3

Easy right?

But what would happen with asynchronous tasks?

// index.js

function task1 () {
  setTimeout(() => {
    console.log('task 1')
  }, 3000)
}

function task2 () {
  setTimeout(() => {
    console.log('task 2')
  }, 2000)
}

function task3 () {
  setTimeout(() => {
    console.log('task 3')
  }, 1000)
}

In general we could need to wait for user input, wait for an API response, execute some database queries etc.

We cannot know in advance how long these tasks take.

In the example above the timeout simulates the time necessary for our operations to complete and, in our scenario, the output would be:

$ node index.js

// output
task 3
task 2
task 1

This, off course, is not what we want. We want the same output we had in the first example.

We need to assure that our tasks are executed in the correct order even if the first one is the slowest.

To achieve this goal a possible solution is to make each task responsible for the execution of the next one.

This way when a task is completed it can call the next one:

// index.js

function task1 () {
  setTimeout(() => {
    console.log('task 1')
    task2()
  }, 3000)
}

function task2 () {
  setTimeout(() => {
    console.log('task 2')
    task3()
  }, 2000)
}

function task3 () {
  setTimeout(() => {
    console.log('task 3')
  }, 1000)
}

function execute () {
  task1()
}

execute()

If we execute our program:

$ node index.js

// output
task 1
task 2
task 3

You can try to change the timers as you want and you will notice that the output will not change.

Mission accomplished!

Well not exactly.

This pattern is very specific to this case, but, in general, we could have any number of tasks and we would like to be able to easily change the order of the tasks and maybe add a new task in a certain position without changing the body of the tasks.

Sequential Iterator

The Sequential Iterator pattern solves exactly the problem explained before:

we have a list of asynchronous tasks
we want to execute our tasks in a certain order

Our task list will look like this:

// index.js

const TASKS = [task1, task2, task3]

The Sequential Iterator pattern consists of a new recursive function we will put inside our 'execute' function:

// index.js

function execute (tasks) {

  function iterate (index) {
    // tasks are finished
    if (index === tasks.length) {
      return
    }

    // set the current task
    const task = tasks[index]

    /* executes the current task passing the 'iterate' function as a callback, it will be called by the task itself */
    task(() => iterate(index + 1))
  }

  return iterate(0)

}

Now, the last thing to do is to make our tasks 'iterable':


function task1 (callback) {
  setTimeout(() => {
    console.log('task 1')
    callback()
  }, 3000)
}

function task2 (callback) {
  setTimeout(() => {
    console.log('task 2')
    callback()
  }, 2000)
}

function task3 (callback) {
  setTimeout(() => {
    console.log('task 3')
    callback()
  }, 1000)
}

As you can see each task now takes a callback as parameter and, when it finishes, it executes that callback (our 'iterate' function passing it the next index).

Now we only need to invoke our 'execute' function passing 'TASKS' as argument and, as always, execute the 'index.js' script on a shell:


$ node index.js

// output
task 1
task 2
task 3

Note

This pattern is made for asynchronous functions and, even if it works with synchronous functions too, it might execute the 'iterate' function recursively a lot of times exceeding the call stack in that case. So, please, if you have synchronous tasks, consider using something more appropriate (like a for loop).

Using Promises

In case our tasks would return a promise we can adjust our pattern to handle promises instead of callbacks.

Here is how our index file would be using promises:

// index.js

const TASKS = [ task1, task2, task3 ]

function execute (tasks) {
  return tasks.reduce((prev, task) => prev.then(task), Promise.resolve())
}

function task1 () {
  return Promise.resolve()
    .then(() => console.log('task 1'))
}

function task2 () {
  return Promise.resolve()
    .then(() => console.log('task 2'))
}

function task3 () {
  return Promise.resolve()
    .then(() => console.log('task 3'))
}

execute(TASKS)

What is happening in the 'execute' function?

Well, we are taking a starting point ('Promise.resolve()') and concatenating promises after that until we finish our tasks.

I used the 'reduce' method but you could achieve the same goal by using a 'forEach'.

The most important thing to notice in this case is that our tasks don't need a 'callback' parameter anymore. This is because, using promises, we don't need to invoke the next task inside the previous one, but we simply use the 'then' function to concatenate tasks (promises).

Conclusion

In real world applications there are many cases where you have to create an elegant way to execute a sequence of tasks. Usually you start with one task, then, after some time, you need to add a second one... and a third and so on, until, finally, you are creating a pipeline. Here is where Sequential Iterator comes in.

I don't like to refactor my code until I feel it is necessary, preemptive optimization is, in my opinion, a good way to create bad code.

But, when you have more then 2 tasks you may consider refactoring your code using this pattern.

A very common place where this pattern might be useful is when you create a development seed for your application (a simple command which gives you application a populated database for development).

Node Observer Pattern

Alessandro Magionami — Mon, 20 Jan 2020 12:04:38 +0000

Before you start

This post is the first of a series of posts where we will explore some of the most used design patterns in Node.

I am not a professional Node developer, I am doing this series to improve my knowledge of Node and, possibly, to understand a bit more how it works under the hood.

This series is widely inspired by the book 'Node.js Design Patterns' by Mario Casciaro and Luciano Mammino, so I strongly recommend you to read the book to dive deeper into all the patterns we will focus on.

The idea

Let's say we have a single service with a single method 'init'.

This service can do a lot of things, but for this example we don't need to know what exactly.

The only thing we need to know is that this service should print 3 things:

the moment it starts
if an error occurred (when we pass the string 'error' as argument in this example)
the moment it ends

// myService.js
class MyService {
  init (arg) {
    console.log('start')

    if (arg !== 'error') {
      console.log('error')
    }

    // more actions

    console.log('end')
  }
}

module.exports = new MyService()

a simple index file to try it:

// index.js
const myService = require('./myService')

myService.init('hello')

To test our code we simply run this command in a shell:

$ node index.js 

// output
start
end

To make it a bit more configurable we can do something like this:

// index.js
const myService = require('./myService')

myService.init(process.argv[2])

so the first argument passed to the command will be the parameter of the 'init' function:

$ node index.js hello

// output
start
end

or, if we want to trigger an error

$ node index.js error 

// output
start
error
end

If your are debugging your service printing this 3 events might be useful, but in a real world application, probably, you could need to perform different kind of actions depending on the event.
You may need to notify another service when one or more of those events occur.

So what we actually want is our service to simply be able to notify the 3 events:

start
error
end

And we want to be able to react when these events occur all around our application.

It would be great if we could do this without adding more complexity to our service off course.

The Observer Pattern

The Observer pattern solves exactly this problem.

It is composed by 2 parts:

subject: an element capable of notifying when its state changes
observers: some elements which can listen to the subject notifications

In Node to make an element 'observable' (our subject) we need it to extend the 'EventEmitter' class.
This way, our service, will get exactly the methods it needs:

emit(eventName[, arg1, arg2, ...]): to emit an event named 'eventName' with some optional arguments
on(eventName, callback): to listen to an event and react with a callback which will get event's arguments if any.

So, let's change our previous example to use the Observer pattern:

// myService.js

const EventEmitter = require('events').EventEmitter

class MyService extends EventEmitter {
  init (arg) {
    this.emit('start')

    if(arg === 'error') {
      this.emit('error')
    }

    // more actions

    this.emit('end')
  }
}

module.exports = new MyService()

// index.js

const myService = require('./myService')

myService.on('start', () => console.log('start'))
myService.on('error', () => console.log('error'))
myService.on('end', () => console.log('end'))

Let's try it:

$ node index.js hello

// output
start
end

As you can see the output is the same as in the first example, but in the index file we could have pass any callback instead of just 'console.log' actions.

Same for the error:

$ node index.js error 

// output
start
error
end

Note

This is not the only way to implement Observer pattern in Node but it is, in my opinion, the more natural and a very clean one and it is the same used inside Node.

About the error event

EventEmitter class cannot just throw an Error because, if it occurs asynchronously, it would be lost in the event loop.
So the convention used by Node is to emit a special event named 'error' and to pass to the 'emit' function an instance of the 'Error' class as second argument.
Because of this we can change our index file like this:

// index.js
const myService = require('./myService')

myService.on('start', () => console.log('start'))
myService.on('end', () => console.log('end'))

try {
  myService.init(process.argv[2])
} catch(err) {
  console.error('error')
}

$ node index.js error 

// output
start
error

The 'end' event wont happen because we are throwing the error so the execution is stopped.

Conclusion

Observer pattern is, in my opinion, a good way to keep track of what is happening in your application. All you have to do is to look at when an event is emitted and who is listening for that event.Even a simple search on your IDE by event name will do the trick.
Javascript allows this pattern to be really clean and natural on both frontend and backend applications. In large codebase sometimes it's easier to keep track of events instead of method function calls.
A lot of frameworks and libraries make large use of this pattern so it is probably one the most important one we need to know.