Mastering JavaScript Event Systems: Build a Production-Grade File Watcher from Scratch

Mastering JavaScript Event Systems: Build a Production-Grade File Watcher from Scratch

EventEmitter is the backbone of Node.js streams, Express middleware, browser DOM events, and React's synthetic event system. Building one from scratch makes every async pattern click. You'll understand why removeEventListener requires the same function reference, why event order matters, and how memory leaks from undisposed listeners happen.

Here's what this covers:

Concept	What it does
Listener registry	A Map storing event names to arrays of listener functions
on(event, fn)	Registers a listener for an event
off(event, fn)	Removes a specific listener by its reference
emit(event, ...args)	Calls every registered listener synchronously, in order
once(event, fn)	Wraps fn in a self-removing wrapper that fires exactly once

Three ideas the whole system rests on

Before writing any code, it helps to nail down the concepts. The implementation will make a lot more sense once these feel obvious.

The data structure: a Map of arrays

listeners = {
  'change' → [fn1, fn2, fn3],
  'error'  → [fn4],
  'close'  → []
}

That's it. Every method (on, off, emit, once) just reads or writes this single Map. The reason to use Map instead of a plain object is that plain objects carry prototype baggage:

const obj = {}
obj['constructor'] // Already exists. Prototype collision.
obj['__proto__']   // Silently breaks things.

const map = new Map<string, Listener[]>()
map.get('constructor') // undefined, no surprises

Reference equality: the rule that governs everything

JavaScript compares functions by memory address, not by their code. Two arrow functions with identical bodies are different objects at different addresses:

const a = () => console.log('hello')
const b = () => console.log('hello') // identical body, different object

a === b // false
a === a // true

This is why off(event, fn) requires the exact same function object that was passed to on(). A look-alike won't match:

// Never removes the listener. Different arrow function each time.
emitter.on('change', () => doSomething())
emitter.off('change', () => doSomething())

// Works. Same reference.
const handler = () => doSomething()
emitter.on('change', handler)
emitter.off('change', handler)

Synchronous emission

Listeners fire one by one in registration order, with no async gaps:

emitter.on('data', () => console.log('A'))
emitter.on('data', () => console.log('B'))
emitter.on('data', () => console.log('C'))

emitter.emit('data')
// A
// B
// C

Building the EventEmitter

on(): registering a listener

type Listener = (...args: unknown[]) => void

class EventEmitter {
  private listeners = new Map<string, Listener[]>()

  on(event: string, fn: Listener): this {
    const existing = this.listeners.get(event) ?? []

    // Spread instead of push. Creates a fresh array rather than mutating.
    // If emit() is iterating while on() runs in a callback, mutation causes bugs.
    this.listeners.set(event, [...existing, fn])

    return this // enables chaining: ee.on('a', fn1).on('b', fn2)
  }
}

off(): removing a listener

  off(event: string, fn: Listener): this {
    const existing = this.listeners.get(event)
    if (!existing) return this

    const updated = existing.filter(l => l !== fn)

    // Delete the key entirely when no listeners remain.
    // Leaving empty arrays in the Map is a slow memory leak in long-running servers.
    if (updated.length === 0) {
      this.listeners.delete(event)
    } else {
      this.listeners.set(event, updated)
    }

    return this
  }

emit(): calling all listeners

  emit(event: string, ...args: unknown[]): boolean {
    const fns = this.listeners.get(event)
    if (!fns || fns.length === 0) return false

    // Snapshot the array before iterating.
    // A listener can call off() on itself during the loop and mutate the array.
    // The snapshot keeps iteration stable regardless of what listeners do.
    fns.slice().forEach(fn => fn(...args))

    return true
  }

Without the snapshot, once() wrappers cause skipped listeners:

// Without snapshot
const listeners = [A, B, C]
// B calls off() inside its handler, listeners becomes [A, C]
// forEach skips C because the index shifted

// With snapshot
const snapshot = [A, B, C] // copied before the loop
// B calls off(), original becomes [A, C]
// snapshot is still [A, B, C], so C fires correctly

once(): the self-removing listener

This is the trickiest part. The goal is a listener that fires exactly once, then removes itself, including if off(originalFn) is called before it ever fires.

The problem is that once() can't register fn directly. It has to register a wrapper that calls fn then removes itself. But that means fn is never in the Map, so off(fn) won't find anything:

What we want to register:   ee.once('data', myFn)
What actually goes in the Map: wrapper (not myFn)

listeners['data'] = [wrapper]

The fix is a second Map that bridges the original function to its wrapper:

Map 1: listeners  →  event → [wrapper, ...]
Map 2: wrappers   →  myFn  → wrapper

off(event, myFn)
  → wrappers.get(myFn) finds wrapper
  → removes wrapper from listeners ✅

  private wrappers = new Map<Listener, Listener>()

  once(event: string, fn: Listener): this {
    const wrapper: Listener = (...args) => {
      fn(...args)              // call the original handler
      this.off(event, wrapper) // remove wrapper from listeners
      this.wrappers.delete(fn) // clean up the bridge to prevent memory leak
    }

    this.wrappers.set(fn, wrapper) // register the bridge
    return this.on(event, wrapper) // store wrapper, not fn
  }

  // Updated off() that resolves originalFn to wrapper automatically
  off(event: string, fn: Listener): this {
    const target = this.wrappers.get(fn) ?? fn

    const existing = this.listeners.get(event)
    if (!existing) return this

    const updated = existing.filter(l => l !== target)
    if (updated.length === 0) this.listeners.delete(event)
    else this.listeners.set(event, updated)

    this.wrappers.delete(fn)
    return this
  }

Full call flow:

1. ee.once('data', myFn)
   wrappers:  { myFn → wrapper }
   listeners: { 'data' → [wrapper] }

2a. Event fires
    wrapper runs → calls myFn → removes wrapper → cleans bridge
    wrappers:  {}
    listeners: {}

2b. Early removal: ee.off('data', myFn)
    off resolves myFn to wrapper via wrappers Map
    removes wrapper from listeners
    wrappers:  {}
    listeners: {}

The complete EventEmitter

type Listener = (...args: unknown[]) => void

export class EventEmitter {
  private listeners = new Map<string, Listener[]>()
  private wrappers  = new Map<Listener, Listener>()

  on(event: string, fn: Listener): this {
    const existing = this.listeners.get(event) ?? []
    this.listeners.set(event, [...existing, fn])
    return this
  }

  off(event: string, fn: Listener): this {
    const target   = this.wrappers.get(fn) ?? fn
    const existing = this.listeners.get(event)
    if (!existing) return this
    const updated = existing.filter(l => l !== target)
    if (updated.length === 0) this.listeners.delete(event)
    else this.listeners.set(event, updated)
    this.wrappers.delete(fn)
    return this
  }

  emit(event: string, ...args: unknown[]): boolean {
    const fns = this.listeners.get(event)
    if (!fns || fns.length === 0) return false
    fns.slice().forEach(fn => fn(...args))
    return true
  }

  once(event: string, fn: Listener): this {
    const wrapper: Listener = (...args) => {
      fn(...args)
      this.off(event, wrapper)
      this.wrappers.delete(fn)
    }
    this.wrappers.set(fn, wrapper)
    return this.on(event, wrapper)
  }

  removeAllListeners(event?: string): this {
    if (event !== undefined) {
      this.listeners.delete(event)
    } else {
      this.listeners.clear()
      this.wrappers.clear() // must clear both, wrappers holds references too
    }
    return this
  }

  listenerCount(event: string): number {
    return this.listeners.get(event)?.length ?? 0
  }
}

Quick smoke test:

const ee = new EventEmitter()

ee.on('ping', (id) => console.log(`pong ${id}`))
  .once('hello', ()  => console.log('hello, once!'))

ee.emit('ping', 1)   // pong 1
ee.emit('hello')     // hello, once!
ee.emit('hello')     // (nothing, removed after first fire)
ee.emit('ping', 2)   // pong 2

The project: mini-nodemon

Now we wire the EventEmitter into something real. A CLI file watcher that restarts a child process whenever your source files change, using the same architecture as nodemon itself.

mini-nodemon/
├── src/
│   ├── core/
│   │   └── event-emitter.ts     ← EventEmitter we just built
│   ├── watcher/
│   │   ├── glob-matcher.ts      ← converts src/**/*.ts to regex
│   │   └── file-watcher.ts      ← fs.watch + glob filter, emits 'change'
│   ├── runner/
│   │   ├── debounce.ts          ← delays a call until input stops
│   │   └── process-runner.ts   ← spawns child process, restarts on 'change'
│   └── cli/
│       ├── config.ts            ← reads .nodemonrc.json
│       └── index.ts             ← wires everything together
└── tests/
    └── integration.test.ts

How the pieces connect:

fs.watch (OS)
    │  raw change events (fires 2-3x per save)
    ▼
FileWatcher (extends EventEmitter)
    │  emits 'change' (glob-filtered)
    ▼
ProcessRunner
    │  debounced restart (fires once per save)
    ▼
child_process.spawn
    │  runs your command
    ▼
terminal output

GlobMatcher: pattern to regex

src/**/*.ts is glob syntax. The OS doesn't understand it, so we convert it to a regex:

export function globToRegex(pattern: string): RegExp {
  const escaped = pattern
    // Escape regex special chars first, before adding our own
    .replace(/[.+^${}()|[\]\\]/g, '\\$&')

    // Hide ** temporarily so the next step doesn't touch it
    .replace(/\*\*/g, '<<<DOUBLE>>>')

    // * matches anything within one segment (not /)
    .replace(/\*/g, '[^/]*')

    // ** matches any number of segments including /
    .replace(/<<<DOUBLE>>>/g, '.*')

    // ? matches exactly one character (not /)
    .replace(/\?/g, '[^/]')

  return new RegExp(`^${escaped}$`)
}

// globToRegex('src/**/*.ts') → /^src\/.*\/[^/]*\.ts$/
// globToRegex('*.json')      → /^[^/]*\.json$/

The placeholder trick for ** is necessary because replacing * first would turn ** into [^/]*[^/]*, which is technically valid but semantically wrong.

export class GlobMatcher {
  private patterns: RegExp[]

  constructor(globs: string[]) {
    this.patterns = globs.map(globToRegex)
  }

  matches(filePath: string): boolean {
    return this.patterns.some(re => re.test(filePath))
  }
}

FileWatcher: OS events to filtered EventEmitter events

import fs   from 'fs'
import path from 'path'
import { EventEmitter } from '../core/event-emitter'
import { GlobMatcher  } from './glob-matcher'

export class FileWatcher extends EventEmitter {
  private matcher: GlobMatcher
  private dir: string
  private watcher: fs.FSWatcher | null = null

  constructor({ patterns, dir }: { patterns: string[], dir: string }) {
    super()
    this.matcher = new GlobMatcher(patterns)
    this.dir     = path.resolve(dir)
  }

  async start(): Promise<void> {
    this.watcher = fs.watch(
      this.dir,
      { recursive: true }, // watches all subdirectories
      (eventType, filename) => {
        if (!filename) return

        // Normalize Windows backslashes before matching
        const rel = filename.replace(/\\/g, '/')

        if (this.matcher.matches(rel)) {
          this.emit('change', path.join(this.dir, rel))
        }
      }
    )
  }

  async stop(): Promise<void> {
    this.watcher?.close()
    this.watcher = null
  }
}

FileWatcher extends EventEmitter rather than containing one so consumers call watcher.on('change', fn) directly. Containing one would require watcher.emitter.on(...), which is an unnecessary extra layer.

Debounce: collapse rapid events into one

fs.watch fires 2 to 4 events per single file save. Without debouncing, your process restarts multiple times per keystroke:

export function debounce<T extends (...args: unknown[]) => void>(fn: T, ms: number): T {
  let timer: ReturnType<typeof setTimeout> | null = null

  return ((...args: unknown[]) => {
    if (timer) clearTimeout(timer) // every call resets the clock
    timer = setTimeout(() => {
      fn(...args)
      timer = null
    }, ms) // only executes after ms of silence
  }) as T
}

Timeline for a single file save with delay = 300ms:

t=0ms   fs.watch fires (event 1)  → timer set for t=300ms
t=10ms  fs.watch fires (event 2)  → timer reset for t=310ms
t=20ms  fs.watch fires (event 3)  → timer reset for t=320ms
t=320ms silence                   → fn() runs once ✅

ProcessRunner: subscribe to changes, manage child process

import { spawn, ChildProcess } from 'child_process'
import { debounce            } from './debounce'
import type { FileWatcher    } from '../watcher/file-watcher'

export class ProcessRunner {
  private child:        ChildProcess | null = null
  private restartCount: number = 0
  private command:      string
  private watcher:      FileWatcher
  private delay:        number

  constructor({ command, watcher, delay = 300 }: {
    command: string
    watcher: FileWatcher
    delay?: number
  }) {
    this.command = command
    this.watcher = watcher
    this.delay   = delay
  }

  start(): void {
    this.spawn()

    const debouncedRestart = debounce(() => this.restart(), this.delay)

    this.watcher.on('change', (filePath: unknown) => {
      console.log(`\x1b[33m[mini-nodemon]\x1b[0m Change detected: ${filePath}`)
      debouncedRestart()
    })
  }

  private spawn(): void {
    this.child = spawn(this.command, {
      shell: true,     // allows full shell commands like 'node dist/index.js --port=3000'
      stdio: 'inherit' // child stdout/stderr goes directly to your terminal
    })

    this.child.on('exit', (code) => {
      if (code !== null && code !== 0) {
        console.log(`\x1b[31m[mini-nodemon]\x1b[0m Process exited with code ${code}`)
      }
    })
  }

  private restart(): void {
    this.restartCount++
    console.log(`\x1b[32m[mini-nodemon]\x1b[0m Restarting... (restart #${this.restartCount})`)

    // Kill first, then spawn. If you spawn first, two instances run simultaneously.
    this.child?.kill('SIGTERM')
    this.spawn()
  }

  stop(): void {
    this.child?.kill('SIGTERM')
    this.watcher.stop()
  }
}

ANSI color reference:

Code	Color	Used for
\x1b[31m	Red	Exit errors
\x1b[32m	Green	Restarts
\x1b[33m	Yellow	Change detection
\x1b[36m	Cyan	Startup messages
\x1b[0m	Reset	End of color

Config and CLI entry point

// src/cli/config.ts
import fs   from 'fs'
import path from 'path'

interface NodaemonConfig {
  watch?:    string[]
  patterns?: string[]
  delay?:    number
  ignore?:   string[]
}

export function loadConfig(cwd: string): NodaemonConfig {
  const configPath = path.join(cwd, '.nodemonrc.json')
  if (!fs.existsSync(configPath)) return {}
  try {
    return JSON.parse(fs.readFileSync(configPath, 'utf8')) as NodaemonConfig
  } catch {
    return {} // malformed JSON, fall back to defaults silently
  }
}

// src/cli/index.ts
import { FileWatcher   } from '../watcher/file-watcher'
import { ProcessRunner } from '../runner/process-runner'
import { loadConfig    } from './config'

// argv: ['node', 'mini-nodemon', './src', 'node dist/index.js', '--delay=500']
const args     = process.argv.slice(2)
const watchDir = args[0] ?? './'
const command  = args[1] ?? 'node index.js'

const delayArg = args.find(a => a.startsWith('--delay='))
const delay    = delayArg ? parseInt(delayArg.split('=')[1]) : undefined

// CLI args take precedence over file config
const config     = loadConfig(process.cwd())
const patterns   = config.patterns ?? ['**/*.ts', '**/*.js', '**/*.json']
const finalDelay = delay ?? config.delay ?? 300

const watcher = new FileWatcher({ patterns, dir: watchDir })
const runner  = new ProcessRunner({ command, watcher, delay: finalDelay })

console.log(`\x1b[36m[mini-nodemon]\x1b[0m Watching ${watchDir} for changes...`)
console.log(`\x1b[36m[mini-nodemon]\x1b[0m Running: ${command}`)

// Watcher must start before runner to avoid missing events during startup
watcher.start().then(() => runner.start())

// Ctrl+C: graceful shutdown so the child process isn't orphaned
process.on('SIGINT', () => {
  console.log('\n\x1b[33m[mini-nodemon]\x1b[0m Shutting down...')
  runner.stop()
  process.exit(0)
})

.nodemonrc.json example:

{
  "patterns": ["**/*.ts", "**/*.env"],
  "delay": 500,
  "ignore": ["node_modules/**", "dist/**"]
}

Integration tests

The tests use a real temp directory and real fs.watch with no mocks, verifying the full pipeline end-to-end:

import { FileWatcher } from '../src/watcher/file-watcher'
import { debounce    } from '../src/runner/debounce'
import fs   from 'fs'
import os   from 'os'
import path from 'path'

// Converts emitter.once() into a Promise with a timeout.
// Rejects if the event doesn't fire within timeoutMs.
async function waitForEvent(
  emitter: FileWatcher,
  event: string,
  timeoutMs = 1000
): Promise<unknown> {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(
      () => reject(new Error(`Timeout: '${event}' never fired`)),
      timeoutMs
    )
    emitter.once(event, (data: unknown) => {
      clearTimeout(timer)
      resolve(data)
    })
  })
}

async function runTests() {
  // Test 1: matching file triggers 'change'
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nodemon-test-'))
  const watcher = new FileWatcher({ patterns: ['**/*.ts'], dir: tmpDir })
  await watcher.start()

  // fs.watch needs a short moment to initialize before detecting events
  await new Promise(r => setTimeout(r, 50))

  const changePromise = waitForEvent(watcher, 'change')
  fs.writeFileSync(path.join(tmpDir, 'test.ts'), 'const x = 1')
  const changedPath = await changePromise as string

  console.assert(changedPath.endsWith('test.ts'), `Got: ${changedPath}`)
  console.log('✓ FileWatcher emits change for matching files')

  // Test 2: non-matching files are ignored
  let jsChangeFired = false
  watcher.on('change', (p: unknown) => {
    if (String(p).endsWith('.js')) jsChangeFired = true
  })
  fs.writeFileSync(path.join(tmpDir, 'test.js'), 'const y = 2')
  await new Promise(r => setTimeout(r, 200))

  console.assert(!jsChangeFired, 'Should not emit for .js when pattern is **/*.ts')
  console.log('✓ GlobMatcher filters out non-matching files')

  // Test 3: debounce fires once on rapid calls
  let callCount = 0
  const debounced = debounce(() => callCount++, 50)
  debounced(); debounced(); debounced()
  await new Promise(r => setTimeout(r, 200))

  console.assert(callCount === 1, `Expected 1 call, got ${callCount}`)
  console.log('✓ debounce fires exactly once on rapid calls')

  await watcher.stop()
  fs.rmSync(tmpDir, { recursive: true })
  console.log('\n✅ All tests passed!')
}

runTests().catch(err => { console.error(err); process.exit(1) })

Run with: npx ts-node tests/integration.test.ts

Test your knowledge

Q1: Why does off(event, fn) require the exact function reference?

• [ ] JavaScript compares functions by their string source code
• [ ] Two function objects are only equal if they share the same memory reference
• [ ] TypeScript enforces reference equality for listener removal
• [ ] The Map uses structural comparison for function keys

Q2: What is the purpose of snapshotting the listener array before iterating in emit()?

• [ ] To improve performance by avoiding repeated Map lookups
• [ ] To allow listeners to safely call off() on themselves during emission without causing array mutation bugs
• [ ] To create a deep copy of function references
• [ ] To enforce FIFO ordering of listeners

Q3: A once() listener and a regular on() listener for the same event will fire in emission order, with the listener registered first firing first. True or false?

Q4: Which data structure is most appropriate for the listener registry in a high-performance EventEmitter?

• [ ] Plain object {}
• [ ] Map<string, Listener[]>
• [ ] Set<[string, Listener]>
• [ ] Array of {event, fn} tuples

Answers

A1: Two function objects are only equal if they share the same memory reference. JavaScript's === for objects (including functions) is reference equality. Two arrow functions with identical bodies are different objects at different memory addresses. This is why addEventListener paired with removeEventListener using an anonymous function never actually removes the listener.

A2: To allow listeners to safely call off() on themselves during emission without causing array mutation bugs. If a listener calls this.off(event, fn) during the loop, as once() wrappers do, it mutates the array being iterated. Snapshotting with .slice() before the loop prevents skipping or double-calling other listeners.

A3: True. Both on() and once() push to the same listener array. Emission iterates in insertion order and the type of registration has no effect on ordering.

A4: Map<string, Listener[]>. It provides O(1) amortized get/set/delete and handles any string key without prototype collision risk. With plain objects, keys like 'constructor' or '__proto__' can silently conflict with existing properties.

Key takeaways

An EventEmitter is a telephone switchboard. on() plugs in a phone. off() unplugs it. emit() calls every phone on the line simultaneously. once() is a phone that self-destructs after one call. The switchboard knows which phones are on which lines, but you must keep the exact same phone reference to unplug it.

Rule	Why it matters
EventEmitter = Map<string, Listener[]>	Single data structure, four operations
off() requires reference equality	Anonymous functions can never be removed
once() needs a wrapper and a reverse Map	So off(originalFn) still works before first fire
Snapshot before emit() iteration	once() wrappers mutate the array mid-loop
Delete empty event keys	Prevents silent memory leaks in long-lived emitters
Debounce fs.watch events	The OS fires 2 to 4 events per save, collapse them to one restart