Merge pull request #4 from jjmax75/events

Events examples

Author: readikus

cheatsheet/index.md

@@ -0,0 +1,17 @@
+# Node Cheat Sheet
+
+# <a name="Events"></a>Events
+
+Class: events.EventEmitter
+
+```
+emitter.addListener(event, listener)
+emitter.on(event, listener)
+emitter.once(event, listener)
+emitter.removeListener(event, listener)
+emitter.removeAllListeners([event])
+emitter.setMaxListeners(n)
+emitter.listeners(event)
+emitter.emit(event, [arg1], [arg2], [...])
+Event: 'newListener'
+```

events/READEME.md

@@ -0,0 +1,50 @@
+// import the base? class, EventEmitter from the events module
+const { EventEmitter } = require('events')
+
+// create some listener functions to handle when the events occur.
+// `foo` is expecting two parameters to be passed in.
+const foo = function foo(baz, qux) {
+  console.log(`foo executed. baz: ${baz}, qux: ${qux}`)
+}
+
+const bar = function bar() {
+  console.log('bar executed.')
+}
+
+const errorProne = function foo(obj) {
+  this.emit('error', 'I am just not going to work')
+}
+
+// create an emitter and bind some events to it
+const eventEmitter = new EventEmitter()
+
+// Bind the connection event with the listner1 function
+eventEmitter.addListener('foo', foo)
+
+// N.B. `addListener` is the same as `on`.
+
+// Bind the connection event with the listner2 function - 
+// IMPORTANT!! Listeners are called synchronously in the order in which they were added.
+// - i.e. `foo` will be called, and `bar` will be called once `foo` has completed.
+// This is to prevent race conditions and logic errors.
+// They can switch to an async mode using `setImmediate`.
+ 
+eventEmitter.once('bar', bar)
+eventEmitter.once('liveDangerously', errorProne)
+
+// handle errors in one of the listeners handlers
+eventEmitter.on('error', (err) => {
+  console.error('There was an error!')
+})
+
+for(let i = 0; i < 3; i++ ) {
+  eventEmitter.emit('foo', 'value1', 'value2')
+  eventEmitter.emit('bar')
+  eventEmitter.emit('liveDangerously')
+}
+
+const eventListeners = EventEmitter.listenerCount(eventEmitter, 'foo')
+
+console.log(EventEmitter.listenerCount(eventEmitter, 'connection') + " Listner(s) listening to connection event")
+console.log(eventListeners + " Listner(s) listening to connection event")
+console.log('end of file...')

events/example-advanced.js

@@ -0,0 +1,16 @@
+// import the class EventEmitter from the events module
+const { EventEmitter } = require('events')
+
+// create a listener function. These can be arrow functions, but will
+// loose `this` refering to the EventEmitter object
+const foo = function foo() {
+  console.log('foo executed.', this)
+}
+
+// create an emitter and bind some events to it
+const eventEmitter = new EventEmitter()
+
+// Bind the connection event with the listner1 function
+eventEmitter.on('foo', foo)
+
+eventEmitter.emit('foo')

events/example-simple.js

@@ -0,0 +1,12 @@
+const { EventEmitter } = require('events')
+
+const foo = function foo(bar) {
+  console.log(`foo has been passed ${bar}`)
+}
+  
+// create an emitter and bind some events to it
+const eventEmitter = new EventEmitter()
+
+eventEmitter.on('foo', foo)
+
+eventEmitter.emit('foo', 'bar')

events/example-with-param.js

@@ -0,0 +1,7 @@
+module.exports = class Emailer {
+
+    send (to, body) {
+        console.log(`Sending email to ${to} with body '${body}'`)
+    }
+
+}

events/exercise/emailer.js

@@ -0,0 +1,15 @@
+
+const Emailer = require('./emailer')
+const { EventEmitter } = require('events')
+
+const emailer = new Emailer()
+
+const userEvents = new EventEmitter()
+
+const sendWelcomeEmail = function sendWelcomeEmail(emailAddress) {
+    emailer.send(emailAddress, `Welcome to our app!`)
+}
+
+userEvents.on('newUser', sendWelcomeEmail)
+
+userEvents.emit('newUser', 'example@example.com')

events/exercise/solution.js

@@ -3,4 +3,65 @@ layout: default.njk
 title: Events
 ---
 
-I've seen things you people wouldn't believe. Attack ships on fire off the shoulder of Orion. I watched C-beams glitter in the dark near the Tannhäuser Gate. All those moments will be lost in time, like control flow.
+# Events
+
+The Node.js core API is built around the idea of events being "emitted" and "listened" to. Objects called "emitters" emit _named_ events, that are picked up by "listener" functions.
+
+Objects that emit events extend the `EventEmitter` class. These objects expose an `on` method that allows one or more functions to be attached to named events emitted by the object.
+
+When the EventEmitter object emits an event, all of the functions attached to that specific event are called _synchronously_, in the order they were added. This is to prevent race conditions and logic errors. They can switch to an async mode using `setImmediate`.
+
+## A Simple Example
+
+This example creates an event listener for `foo` events, and an event emitter to fire these events.
+
+```
+const { EventEmitter } = require('events');
+
+// create a listener function. These can be arrow functions, but will
+// loose `this` refering to the EventEmitter object
+const foo = function foo() {
+  console.log('foo executed.', this)
+}
+
+// create an emitter and bind some events to it
+const eventEmitter = new EventEmitter()
+
+// Bind the connection event with the listner1 function
+eventEmitter.on('foo', foo)
+
+// fire the event
+eventEmitter.emit('foo')
+```
+
+## Passing parameters
+
+When an event is emitted using the `emit` method, the subsequent arguments are passed through to the listeners.
+
+For example:
+
+```
+const foo = function foo(bar) {
+  console.log(`foo has been passed ${bar}`)
+}
+
+// Bind the connection event with the listner1 function
+eventEmitter.on('foo', foo)
+
+// fire the event
+eventEmitter.emit('foo', 'bar')
+```
+
+## Summary
+
+Listeners _listen_ for events, that are _emitted_ from emitters.
+
+Take me to [cheat sheet](../cheatsheet/#events)
+
+## Exercise
+
+Imagine we are building a SaaS that does a number of things when a user creates an account. When a user record
+is created, we want to emit a `userCreated` event. One of the listeners for this will email a confirmation
+email to that user.
+
+Build an event emitter to simulate the `userCreated` event, and an event listener that sends a confirmation email. There is a mock emailer class in the folder that has a method `send`, which expects an email address and a message body as the parameters.

events/index.md

@@ -9,3 +9,6 @@ TODO:
 
 - Set out the purpose here and list the sections with links
 - Styling and update the default template
+
+
+[Events](/events)