EventEmitter

แกนหลักของ event-driven model ของ Node

EventEmitter (จาก node:events) คือ class ที่ขับเคลื่อนแทบทุก I/O object ใน Node.js HTTP server, TCP socket, file stream, child process และไลบรารีบุคคลที่สามจำนวนมากล้วน extend EventEmitter การเข้าใจมันคือการเข้าใจว่า Node สื่อสารระหว่าง component ต่าง ๆ อย่างไร

การใช้งานพื้นฐาน: on, emit, removeListener

Node.js

import { EventEmitter } from 'node:events';

var emitter = new EventEmitter();

// Register a listener
emitter.on('greet', function(name) {
  console.log('Hello, ' + name + '!');
});

// Emit the event — listener runs synchronously
emitter.emit('greet', 'Alice');
emitter.emit('greet', 'Bob');

// Remove the listener
var handler = function(msg) {
  console.log('message:', msg);
};
emitter.on('message', handler);
emitter.emit('message', 'first');
emitter.removeListener('message', handler);
emitter.emit('message', 'second'); // no output — listener removed

Output (verified on Node 24)

Hello, Alice!
Hello, Bob!
message: first

once — ยิงแค่ครั้งเดียว

once ลงทะเบียน listener ที่ลบตัวเองอัตโนมัติหลังจากการ emit ครั้งแรก

Node.js

import { EventEmitter } from 'node:events';

var emitter = new EventEmitter();

emitter.once('connect', function() {
  console.log('Connected! (fires once only)');
});

emitter.emit('connect'); // prints "Connected!"
emitter.emit('connect'); // nothing — listener already removed
emitter.emit('connect'); // nothing

console.log('listener count:', emitter.listenerCount('connect')); // 0

Output (verified on Node 24)

Connected! (fires once only)
listener count: 0

การสร้าง custom EventEmitter class

extend EventEmitter เพื่อให้ class ของคุณเองมีความสามารถแบบ event-driven

Node.js

import { EventEmitter } from 'node:events';

class DataLoader extends EventEmitter {
  constructor() {
    super();
    this._items = [];
  }

  load(item) {
    this._items.push(item);
    this.emit('data', item);
    if (this._items.length >= 3) {
      this.emit('done', this._items);
    }
  }
}

var loader = new DataLoader();

loader.on('data', function(item) {
  console.log('loaded item:', item);
});

loader.once('done', function(all) {
  console.log('all done! total:', all.length, 'items');
  console.log('items:', all.join(', '));
});

loader.load('alpha');
loader.load('beta');
loader.load('gamma');

Output (verified on Node 24)

loaded item: alpha
loaded item: beta
loaded item: gamma
all done! total: 3 items
items: alpha, beta, gamma

Listener count และ off()

off เป็น alias ของ removeListener ที่เพิ่มเข้ามาใน Node 10 listenerCount ช่วยให้ตรวจสอบได้ว่ามี listener ลงทะเบียนไว้กี่ตัวสำหรับ event หนึ่ง — มีประโยชน์สำหรับตรวจจับ memory leak ที่อาจเกิดขึ้น

Node.js

import { EventEmitter } from 'node:events';

var ee = new EventEmitter();

var handler1 = function() { console.log('handler1'); };
var handler2 = function() { console.log('handler2'); };

ee.on('event', handler1);
ee.on('event', handler2);
console.log('count before off:', ee.listenerCount('event')); // 2

ee.off('event', handler1);
console.log('count after off:', ee.listenerCount('event'));  // 1

ee.emit('event'); // only handler2 runs

Output (verified on Node 24)

count before off: 2
count after off: 1
handler2

คำเตือน listener leak

EventEmitter มีค่าดีฟอลต์เป็น สูงสุด 10 listener ต่อหนึ่ง event (defaultMaxListeners) นี่ไม่ใช่ hard limit — มันคือ heuristic tripwire: บั๊ก EventEmitter อันดับ 1 ใน AI-generated code คือ listener ที่ถูกลงทะเบียน ภายใน loop, request handler หรือ re-render สไตล์ React ซึ่งจะเพิ่ม listener ใหม่แบบเงียบ ๆ ทุกครั้งที่เรียกแทนที่จะใช้ซ้ำตัวเดิม ถ้าไม่สังเกตเห็น นั่นคือ memory leak ที่ไม่มีขอบเขต

เมื่อจำนวนเกิน max Node จะ emit process warning — ปกติจะพิมพ์ไปที่ stderr เท่านั้น เพื่อให้เห็นใน output ของ script เอง (และจัดการมันแบบ programmatic ได้ เช่น ส่งไปยัง log) ให้ listen process.on('warning', ...):

Node.js

const { EventEmitter } = require('node:events');

process.on('warning', function(warning) {
  console.log('warning name:', warning.name);
  console.log('warning message:', warning.message);
});

var emitter = new EventEmitter();
console.log('default max listeners:', emitter.getMaxListeners());

// Adding more listeners than the default max (10) for the same event is
// almost always a bug -- usually a listener registered inside a loop or on
// every request instead of once at startup.
for (var i = 0; i < 11; i++) {
  emitter.on('data', function() {});
}
console.log('listener count:', emitter.listenerCount('data'));

Output (verified on Node 24)

default max listeners: 10
listener count: 11
warning name: MaxListenersExceededWarning
warning message: Possible EventEmitter memory leak detected. 11 data listeners added to [EventEmitter]. MaxListeners is 10. Use emitter.setMaxListeners() to increase limit

ถ้า 10 listener น้อยเกินไปจริง ๆ สำหรับ use case ที่ชอบธรรม (เช่น shared event bus ที่มีผู้ subscribe อิสระจำนวนมาก) ให้เพิ่ม limit อย่างชัดเจนด้วย emitter.setMaxListeners(n) — นั่นคือการบันทึกการตัดสินใจไว้แทนที่จะปล่อยให้เกินดีฟอลต์แบบเงียบ ๆ

events.on() และ events.once() — async iteration และ promise

events.once(emitter, name) คืนค่า Promise ที่ resolve ด้วย argument ของ event เมื่อมีการ emit ครั้งแรก — ทางเลือกแบบครั้งเดียวของ emitter.once() ที่ใช้ callback events.on(emitter, name) คืนค่า async iterable ที่ yield ทุกการ emit เพื่อใช้กับ for await:

Node.js

const { EventEmitter, on, once } = require('node:events');

async function main() {
  var emitter = new EventEmitter();

  // once() as a promise -- resolves with the event's args on first emission
  var readyPromise = once(emitter, 'ready');
  emitter.emit('ready', 'server');
  var readyArgs = await readyPromise;
  console.log('once() resolved with:', readyArgs);

  // events.on() -- async-iterate every emission of an event
  setImmediate(function() {
    emitter.emit('tick', 1);
    emitter.emit('tick', 2);
    emitter.emit('tick', 3);
    emitter.emit('done');
  });

  for await (const [n] of on(emitter, 'tick')) {
    console.log('tick:', n);
    if (n === 3) break; // must break manually -- on() never ends on its own
  }
  console.log('finished iterating ticks');
}

main();

Output (verified on Node 24)

once() resolved with: [ 'server' ]
tick: 1
tick: 2
tick: 3
finished iterating ticks

captureRejections — ส่ง error ของ async listener ไปที่ ‘error’

listener แบบ async ที่ throw จะสร้าง rejected promise ที่ EventEmitter ไม่ await — โดยดีฟอลต์มันจะกลายเป็น unhandled rejection ซึ่งทำให้ process crash บน Node สมัยใหม่ (ดีฟอลต์ --unhandled-rejections=throw) การส่ง captureRejections: true ให้ constructor จะส่ง rejection นั้นไปที่ event 'error' ของ emitter แทน ซึ่งคุณจัดการมันได้เหมือน error ทั่วไป:

Node.js

import { EventEmitter } from 'node:events';

// Without captureRejections, a listener that returns a rejected promise
// produces an unhandled rejection that crashes the process (Node >= 15).
// With captureRejections: true, the rejection is routed to an 'error' event
// on the emitter instead, which you can handle like any other error.
var emitter = new EventEmitter({ captureRejections: true });

emitter.on('error', function(err) {
  console.log('caught via error event:', err.message);
});

emitter.on('work', async function() {
  throw new Error('async listener failed');
});

emitter.emit('work');
console.log('emit() returned -- the throw happens later, on the microtask queue');

// Give the rejection a turn to be routed before the process exits
await new Promise(function(resolve) { setImmediate(resolve); });
console.log('done');

Output (verified on Node 24)

emit() returned -- the throw happens later, on the microtask queue
caught via error event: async listener failed
done

event ‘error’ ที่ไม่มี listener จะ throw

'error' เป็นชื่อ event พิเศษใน EventEmitter: ถ้ามันถูก emit และ ไม่มี listener ลงทะเบียนไว้เลย Node จะ throw error แทนที่จะทิ้งมันไปเงียบ ๆ ทำให้ process crash นี่เป็นความตั้งใจ — มันคือ event เดียวที่คุณไม่ได้รับอนุญาตให้เผลอมองข้าม

Node.js

// @expect-throw
const { EventEmitter } = require('node:events');

var emitter = new EventEmitter();
// No 'error' listener registered.
console.log('about to emit error with no listener...');
emitter.emit('error', new Error('boom'));
console.log('this line never runs');

Output (verified on Node 24)

about to emit error with no listener...

Mental Model

flowchart TB
  Loop["listener registered inside a loop / request handler"] -->|"each call adds a NEW listener"| Count["listenerCount keeps growing"]
  Count -->|"exceeds getMaxListeners() (default 10)"| Warn["MaxListenersExceededWarning"]
  Emit["emitter.emit('error', err)"] -->|"listener registered?"| Handled["'error' handler runs — process keeps going"]
  Emit -->|"no listener registered"| Crash["Node throws — process crashes"]
  Async["async listener throws"] -->|"captureRejections: false (default)"| Unhandled["unhandled rejection — crash"]
  Async -->|"captureRejections: true"| Handled

listener count ที่โตขึ้นเรื่อย ๆ ทำให้เกิด warning; event 'error' ที่ไม่มี listener ทำให้ process crash; captureRejections ส่ง error ของ async listener ไปในทางเดียวกัน

Trade-offs

ทางเลือก	ข้อดี	ต้นทุน
callback style `emitter.on()`	ใช้ได้ทุกที่ ไม่มี dependency ทำงานแบบ synchronous และคาดเดาได้	รั่วง่าย — ลงทะเบียนซ้ำภายใน loop/handler เป็นบั๊กที่เงียบ
`events.once(emitter, name)` (promise)	อ่านเหมือน call ที่ await ทั่วไป ประกอบกับ `Promise.race`/`AbortSignal` ได้	ยิงแค่ครั้งเดียว — ไม่ใช่ตัวแทนของ listener `on()` ที่เกิดซ้ำ
`events.on(emitter, name)` (async iterator)	`for await` อ่านจากบนลงล่างเหมือน stream เป็นมิตรกับ backpressure	ไม่มีจุดจบอัตโนมัติ — คุณต้อง `break` เองหรือพึ่ง event `'end'`/`'close'`
`captureRejections: true`	error ของ async listener กลายเป็น event `'error'` ธรรมดาแทนที่จะ crash	ปิดโดยดีฟอลต์ — emitter ทุกตัวที่คุณสร้างต้อง opt-in เอง

Common Misconceptions

“listener ของ EventEmitter ทำงานแบบ asynchronous เหมือน DOM event” — ความจริง: .emit() เรียกทุก listener แบบ synchronous ตามลำดับการลงทะเบียน ก่อนที่ emit() จะ return
“MaxListenersExceededWarning แปลว่ามีอะไรพัง” — ความจริง: มันเป็น heuristic warning ไม่ใช่ error — code ยังทำงานต่อ แต่มันชี้บั๊ก EventEmitter ที่พบบ่อยที่สุดได้อย่างถูกต้อง: listener ที่ถูกเพิ่มทุกครั้งที่เรียก function แทนที่จะเพิ่มครั้งเดียว
“event 'error' ที่ไม่มี listener จะถูกละเว้นไปเฉย ๆ เหมือน event อื่นที่ไม่มีใครฟัง” — ความจริง: 'error' ถูกจัดการเป็นกรณีพิเศษ — ถ้าไม่มี listener เลยมันจะถูก throw ทำให้ process crash
“error ที่ถูก throw จาก async listener จะถูกจับโดย emitter.on('error', ...) โดยอัตโนมัติ” — ความจริง: จะเกิดขึ้นก็ต่อเมื่อ emitter ถูกสร้างด้วย captureRejections: true เท่านั้น ไม่งั้น rejection จะ unhandled และทำให้ process crash โดยไม่เกี่ยวกับ listener 'error' เลย

อ่านโค้ดที่ AI เขียน

.on() ถูกเรียกภายใน loop, request handler, class constructor ที่ถูกเรียกต่อ request หรือ re-render path — ที่ไหนก็ตามที่รันมากกว่าหนึ่งครั้งต่ออายุของ process หรือเปล่า? แต่ละครั้งที่เรียกจะเพิ่ม listener ใหม่เอี่ยมที่ไม่เคยถูกลบ
มีอะไรที่ extend หรือห่อ EventEmitter (custom class, socket, stream) ที่ไม่มี listener 'error' เลยตลอด call chain หรือเปล่า? การ emit 'error' ที่ไม่มีคนจับแค่ครั้งเดียวทำให้ทั้ง process crash
มี async function ถูกส่งตรงเข้า .on() โดยไม่มี captureRejections: true บน emitter และไม่มี try/catch ภายในหรือเปล่า? error ที่มันโยนออกมาจะกลายเป็น unhandled rejection ไม่ใช่ error ที่ถูกจับ
code เรียก events.on(emitter, name) แล้ว iterate ด้วย for await แต่ไม่เคย break หรือพึ่งเงื่อนไขจบเลยหรือเปล่า? นั่นคือ listener ที่ไม่เคยถูกเคลียร์ เป็น leak แบบเดียวกับการลืม removeListener

🐛 หา bug ในโค้ดนี้

const { EventEmitter } = require('node:events');
const http = require('node:http');

var bus = new EventEmitter();

var server = http.createServer(function(req, res) {
// registers a new listener on every single request
bus.on('request-logged', function(url) {
  console.log('logged:', url);
});
bus.emit('request-logged', req.url);
res.end('ok');
});

เฉลย

bus.on('request-logged', ...) ถูกเรียกภายใน request handler ดังนั้น listener ใหม่เอี่ยมจะถูกลงทะเบียนทุก request ที่เข้ามาและไม่เคยถูกลบ หลังจาก 10 request Node จะพิมพ์ MaxListenersExceededWarning; หลังจากหลายพัน request process จะรั่วไหลหน่วยความจำ — closure ของ listener ทุกตัวยังมีชีวิตอยู่ และทุก emit('request-logged', ...) ในอนาคตจะรันทั้งหมดนั้น เพิ่มงานต่อ request ทวีคูณขึ้นเรื่อย ๆ วิธีแก้คือลงทะเบียน listener ครั้งเดียว นอก request handler ก่อนที่ server.listen() จะถูกเรียก — handler ควรเรียกแค่ bus.emit(...) ไม่ใช่ bus.on(...)