Events and Listeners

AdonisJS is a robust Node.js MVC (Model-View-Controller) framework that offers a stable ecosystem for building server-side web applications. It's highly valued for its simple yet powerful toolset. In Node.js we use event-driven, non-blocking I/O model that makes it excellent for designing scalable and real-time applications. One of the essential features that AdonisJS includes is an event listener system. Throughout this chapter, we will get to discover what events are, how to use event listeners, and what they provide for AdonisJS applications.

Let's get started with the explanation of what an Event is. Mathematically interpreted, an Event is something that happens as part of the system flow. In our context as developers working with AdonisJS, an event can be defined as actions or occurrences in your application. These occurrences can be anything from a user signing up to a failure of some data request.

Events are essential as they allow us to trigger necessary actions based on what is happening in the system. They bring out the meaningfulness of cause-and-effect in programming.

In AdonisJS, it's super easy to create your Event. Remember to consider that the event name should be related to the event that is taking place. Let's imagine a scenario in a film club web application where someone signs up to watch a movie. We can name the event that gets triggered in this scenario as 'movie:watched'. To create this event, navigate to the terminal and type the following command.

adonis make:event MovieWatched

Executing the above command creates an Event inside 'app/Events/MovieWatched.js'. Inside of this created file, you can define what data to be passed when the event is fired.

const Event = use('Event')

Event.on('movie:watched', 'MovieWatched.fire')

The code above depicts how to fire an event. MovieWatched.fire is a method which you have to define in 'app/Events/MovieWatched.js'.

class MovieWatched {
  
  * fire (movie) {
    console.log(`Someone just watched ${movie.name}`)
  }
}

module.exports = MovieWatched

The movie variable is the data attached when the event is fired. In our scenario, it is the details of the movie watched.

Event Listeners, on the other hand, are those blocks of code that run each time an event is fired. To create a Listener for our event, we run the command:

adonis make:listener SendMovieWatchedEmail

After running the command, a Listeners directory is generated in our app folder with our file 'SendMovieWatchedEmail.js'. We then modify the file, so it looks something like this:

class SendMovieWatchedEmail {

  * handle (movie) {
    console.log(`Email regarding ${movie.name} being watched is sent.`)
  }
}

module.exports = SendMovieWatchedEmail

The handle function is where the action takes place each time the 'movie:watched' event is fired. In our case, it simulates the action of sending an email.

To connect the event with the listener, we need to edit the 'start/events.js' file as follows:

const Event = use('Event')

Event.when('movie:watched', 'SendMovieWatchedEmail.handle')

The Event.when method connects our event 'movie:watched' with the listener.

And that's it! We have successfully created an event, and a listener in AdonisJS. To trigger the event, you can call it in your controller or routes.

Route.get('/movie', function * (request, response) {
  const movie = {name: 'Inception', genre: 'Sci-Fi'}
  Event.fire('movie:watched', movie)
  response.send('Event Fired')
})

Whenever our /movie route is hit, it fires the 'movie:watched' event, and our listener SendMovieWatchedEmail is informed. A console log message as defined in our listener is then displayed.

Handling events are asynchronous in AdonisJS. This implies that firing an event will not stop the execution flow of your application.

In conclusion, Events and Listeners in AdonisJS give an organized way to perform actions based on occurrences within your application. It is an excellent tool for creating a maintainable, scalable, and robust codebase. Events represent a great way to decouple application components and have them communicate with each other without having direct dependencies among themselves. As we saw from our Movie-Watching scenario, a simple event brought about simplifying data transfer triggered by an event occurrence. This is just a starting point, and there's much more to explore and implement with the AdonisJS event system!