What You'll Learn
- An EventEmitter maintains a map of event names to arrays of listener functions
- on(event, fn) registers a listener; off(event, fn) removes it by reference
- emit(event, ...args) synchronously calls every registered listener in registration order
- once(event, fn) wraps fn in a self-removing wrapper so it fires exactly one time
Why it matters: 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.
Listener Registry Pattern
The core data structure is a Map from event name to an array of listener functions. This gives O(1) lookup per event name and preserves insertion order for emission. All four public methods — on, off, emit, once — operate on this single Map.
// Listener Registry Pattern
type Listener = (...args: unknown[]) => void
class EventEmitter {
private listeners = new Map<string, Listener[]>() // event name → fns array
on(event: string, fn: Listener): this {
const existing = this.listeners.get(event) ?? []
this.listeners.set(event, [...existing, fn]) // append, don't mutate
return this // fluent API
}
off(event: string, fn: Listener): this {
const existing = this.listeners.get(event) ?? []
this.listeners.set(event, existing.filter(l => l !== fn)) // reference equality
return this
}
emit(event: string, ...args: unknown[]): boolean {
const fns = this.listeners.get(event)
if (!fns || fns.length === 0) return false
fns.forEach(fn => fn(...args)) // fires all listeners in order
return true
}
}
The once() Wrapper Pattern
once() must call the listener exactly once then remove itself. The trick is a wrapper function that (1) calls the original fn, (2) calls this.off() with itself as the reference. The wrapper must be stored so off() can find it by reference — which means you need to associate the original fn with its wrapper.
// The once() Wrapper Pattern
// Naive implementation — works but can't be removed early
once(event: string, fn: Listener): this {
const wrapper: Listener = (...args) => {
fn(...args)
this.off(event, wrapper) // self-removing
}
return this.on(event, wrapper) // registers wrapper, not fn
}
// Problem: ee.off('data', originalFn) won't work because
// we registered `wrapper`, not `fn`.
// Fix: track the wrapper → original mapping
private wrappers = new Map<Listener, Listener>() // bridges originalFn → wrapper
once(event: string, fn: Listener): this {
const wrapper: Listener = (...args) => {
fn(...args) // call the real handler
this.off(event, wrapper)
this.wrappers.delete(fn) // avoid memory leak
}
this.wrappers.set(fn, wrapper)
return this.on(event, wrapper)
}
off(event: string, fn: Listener): this {
// Check if fn has an associated wrapper
const toRemove = this.wrappers.get(fn) ?? fn // resolve to internal wrapper
const existing = this.listeners.get(event) ?? []
this.listeners.set(event, existing.filter(l => l !== toRemove))
return this
}
The Project: mini-nodemon
A production-grade CLI file watcher that uses your EventEmitter as its event bus — detecting file system changes with glob pattern matching and automatically restarting a child process. The same architecture powering the real nodemon.
Here's what makes it interesting:
- Glob pattern matching (src//.ts)*
- Debounced restart with configurable delay
- Colored console output with restart counter
- .nodemonrc.json config file support
Here's how the project is laid out:
mini-nodemon/
├── event-emitter.ts
├── glob-matcher.ts
├── file-watcher.ts
├── debounce.ts
├── process-runner.ts
├── config.ts
├── index.ts
├── integration.test.ts
├── package.json
├── tsconfig.json
Building It Step by Step
Step 1: Build the EventEmitter core
Implement the full EventEmitter — the event bus the whole project uses. Map-based listener registry, on/off/emit/once, removeAllListeners, listenerCount. This is the engine everything hooks into.
Working in src/core/event-emitter.ts
| Input | event: string, fn: (...args: unknown[]) => void |
| Output | this (for chaining); listener stored in Map<string, Listener[]> |
// Use Map<string, Listener[]>. The once() wrapper needs a wrappers Map so off(originalFn) can find the internal wrapper to remove it.
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() }
return this
}
listenerCount(event: string): number {
return this.listeners.get(event)?.length ?? 0
}
}
The EventEmitter is the event bus for the whole project. FileWatcher extends it to emit 'change'/'add'/'remove', ProcessRunner subscribes to those events to trigger restarts. The wrappers Map solves the once() removability problem — off(originalFn) resolves to the internal wrapper automatically.
Watch out for:
Snapshot with fns.slice() before iterating — once() wrappers remove themselves during emit which mutates the array
The wrappers Map bridges off(originalFn) → finds internal wrapper → removes it correctly
removeAllListeners() must also clear the wrappers map to avoid memory leaks
Test it: const ee = new EventEmitter(); ee.on('change', p => console.log(p)); ee.emit('change', 'src/index.ts') — should log the path
Step 2: Build GlobMatcher and FileWatcher
GlobMatcher converts patterns like src/**/*.ts into regex. FileWatcher uses Node's fs.watch recursively + GlobMatcher to filter paths, then emits 'change', 'add', 'remove' events on the EventEmitter bus.
Working in src/watcher/file-watcher.ts
| Input | patterns: string[] (e.g. ['src/**/*.ts']), dir: string |
| Output | EventEmitter emitting 'change' with file path when a matching file changes |
// Use `fs.watch(dir, { recursive: true })` to watch subdirectories. Raw fs.watch fires 2-3 times per save — you'll debounce this in the next step. For now, emit immediately and filter by glob.
// src/watcher/glob-matcher.ts
export function globToRegex(pattern: string): RegExp {
const escaped = pattern
.replace(/[.+^${}()|[\]\\]/g, '\\$&')
.replace(/\*\*/g, '<<<DOUBLE>>>')
.replace(/\*/g, '[^/]*')
.replace(/<<<DOUBLE>>>/g, '.*')
.replace(/\?/g, '[^/]')
return new RegExp(`^${escaped}$`)
}
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))
}
}
// src/watcher/file-watcher.ts
import fs from 'fs'
import path from 'path'
import { EventEmitter } from '../core/event-emitter'
import { GlobMatcher } from './glob-matcher'
interface FileWatcherOptions {
patterns: string[]
dir: string
}
export class FileWatcher extends EventEmitter {
private matcher: GlobMatcher
private dir: string
private watcher: fs.FSWatcher | null = null
constructor({ patterns, dir }: FileWatcherOptions) {
super()
this.matcher = new GlobMatcher(patterns)
this.dir = path.resolve(dir)
}
async start(): Promise<void> {
this.watcher = fs.watch(this.dir, { recursive: true }, (eventType, filename) => {
if (!filename) return
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 directly — it IS the event bus for file events. GlobMatcher converts glob syntax to regex:
**matches any path segment depth,*matches within a segment. The{ recursive: true }option on fs.watch handles deep directory watching natively.
Watch out for:
fs.watch fires multiple events per single file save — the debouncer in step 3 will fix this
filename on Windows uses backslashes — normalize with replace(/\\/g, '/') before matching
recursive option is not available on all Linux systems — add a fallback note in README
Test it: const fw = new FileWatcher({ patterns: ['**/*.ts'], dir: './src' }); fw.on('change', console.log); fw.start() — edit a .ts file and see the log
Step 3: Build Debounce utility and ProcessRunner
debounce(fn, ms) delays execution — prevents restart storms when fs.watch fires multiple times per save. ProcessRunner spawns a child process, listens to FileWatcher 'change' events, kills and respawns on each change, logs restarts with color and a restart counter.
Working in src/runner/process-runner.ts
| Input | command: string (e.g. 'node dist/index.js'), watcher: FileWatcher |
| Output | Child process spawned; on watcher 'change' event: old process killed, new process spawned, restart count logged |
// Use `child_process.spawn` with `shell: true` to run arbitrary commands. Kill with `child.kill('SIGTERM')`. Track a restart counter and log with ANSI colors: `\x1b[32m` for green, `\x1b[0m` to reset.
// src/runner/debounce.ts
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)
timer = setTimeout(() => { fn(...args); timer = null }, ms)
}) as T
}
// src/runner/process-runner.ts
import { spawn, ChildProcess } from 'child_process'
import { debounce } from './debounce'
import type { FileWatcher } from '../watcher/file-watcher'
interface ProcessRunnerOptions {
command: string
watcher: FileWatcher
delay?: number
}
export class ProcessRunner {
private child: ChildProcess | null = null
private restartCount = 0
private command: string
private watcher: FileWatcher
private delay: number
constructor({ command, watcher, delay = 300 }: ProcessRunnerOptions) {
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, stdio: 'inherit' })
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})`)
this.child?.kill('SIGTERM')
this.spawn()
}
stop(): void {
this.child?.kill('SIGTERM')
this.watcher.stop()
}
}
debounce prevents restart storms: fs.watch fires 2-3 times per save, but the debounced restart only fires once after the last event within the delay window. SIGTERM is the graceful shutdown signal — the child process can clean up before exiting.
Watch out for:
stdio: 'inherit' passes child process output directly to parent terminal — without this you won't see the command output
Kill SIGTERM before spawning — if you spawn first, you'll have two processes running simultaneously
The debounce delay (300ms default) should be configurable — different projects need different tolerances
Test it: const runner = new ProcessRunner({ command: 'echo hello', watcher }); runner.start() — should print 'hello', then reprint on each file change
Step 4: Build the CLI entry point and config loader
config.ts reads .nodemonrc.json (watch patterns, delay, ignore list). index.ts parses process.argv, merges with config file, wires FileWatcher + ProcessRunner together. Adds a bin field to package.json so users can run mini-nodemon globally.
Working in src/cli/index.ts
| Input | process.argv: ['node', 'mini-nodemon', './src', 'node dist/index.js', '--delay=500'] |
| Output | FileWatcher started on ./src, ProcessRunner running 'node dist/index.js', watching for changes |
// Parse argv: `node mini-nodemon [watchDir] [command] [--delay=500]`. Read .nodemonrc.json with fs.existsSync + JSON.parse. The bin field in package.json: `{ "bin": { "mini-nodemon": "./dist/cli/index.js" } }`.
// 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 {}
}
}
// src/cli/index.ts
import { FileWatcher } from '../watcher/file-watcher'
import { ProcessRunner } from '../runner/process-runner'
import { loadConfig } from './config'
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
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.start().then(() => runner.start())
process.on('SIGINT', () => {
console.log('\n\x1b[33m[mini-nodemon]\x1b[0m Shutting down...')
runner.stop()
process.exit(0)
})
The CLI composes FileWatcher and ProcessRunner together. Config is loaded from .nodemonrc.json in the cwd, with CLI args taking precedence. SIGINT handler (Ctrl+C) gracefully shuts down both the watcher and runner process.
Watch out for:
args[1] might be undefined if user only passes watchDir — always provide a default command
The watcher must start before the runner to avoid missing events during startup
SIGINT must call runner.stop() not just process.exit() — otherwise the child process becomes orphaned
Test it: npx ts-node src/cli/index.ts ./src 'echo restarted' -- edit any file in ./src and see 'restarted' print
Step 5: Write the integration test
Test the full cycle: create a temp directory, start FileWatcher with a glob pattern, write a file to the temp dir, verify the 'change' event fires with the correct path. Test debounce fires once on rapid changes. Test ProcessRunner restart count increments.
Working in tests/integration.test.ts
| Input | Temp dir with a .ts file written to it |
| Output | FileWatcher emits 'change' event with the correct file path within 500ms |
// Use `fs.mkdtempSync(path.join(os.tmpdir(), 'nodemon-test-'))` for an isolated temp dir. Write a file with fs.writeFileSync and await the event with a Promise + setTimeout timeout.
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'
async function waitForEvent(emitter: FileWatcher, event: string, timeoutMs = 1000): Promise<unknown> {
return new Promise((resolve, reject) => {
const timer = setTimeout(() => reject(new Error(`Timeout waiting for '${event}'`)), timeoutMs)
emitter.once(event, (data: unknown) => { clearTimeout(timer); resolve(data) })
})
}
async function runTests() {
// Test 1: FileWatcher emits 'change' when a matching file is written
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nodemon-test-'))
const watcher = new FileWatcher({ patterns: ['**/*.ts'], dir: tmpDir })
await watcher.start()
await new Promise(r => setTimeout(r, 50)) // let watcher initialize
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'), `Expected path ending in test.ts, got: ${changedPath}`)
console.log('✓ FileWatcher emits change for matching files')
// Test 2: .js files are ignored when pattern is **/*.ts
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 change for .js files')
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 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) })
The integration test uses a real temp directory and actual fs.watch to verify the full file-watching pipeline works end-to-end. waitForEvent converts EventEmitter.once into a Promise with a timeout, making async assertions clean. Tests clean up after themselves with fs.rmSync.
Watch out for:
fs.watch needs a small delay after start() before it begins detecting changes — add a 50ms pause
On macOS, fs.watch may fire the filename as just the basename (not the full path) — resolve it with path.join(dir, filename)
Always clean up temp directories in tests — use try/finally or add cleanup to process.on('exit')
Test it: npx ts-node tests/integration.test.ts — should print 'All tests passed!'
The Integration Test
End-to-end integration: watch a temp directory, write a .ts file, verify the 'change' event fires with the correct path, verify debounce prevents multiple rapid restarts
import { EventEmitter } from './src/core/event-emitter'
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'
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nodemon-e2e-'))
const watcher = new FileWatcher({ patterns: ['**/*.ts'], dir: tmpDir })
const events: string[] = []
watcher.on('change', (p: unknown) => events.push(String(p)))
await watcher.start()
await new Promise(r => setTimeout(r, 50))
fs.writeFileSync(path.join(tmpDir, 'index.ts'), 'export const x = 1')
await new Promise(r => setTimeout(r, 300))
console.assert(events.length >= 1, 'change event fired')
console.assert(events[0].endsWith('index.ts'), 'correct path emitted')
await watcher.stop()
fs.rmSync(tmpDir, { recursive: true })
console.log('mini-nodemon e2e test passed!')
Run it with: npx ts-node tests/integration.test.ts
Skills: TypeScript · Node.js fs.watch · EventEmitter · Child Processes · CLI Tools
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
Reveal answer
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 + removeEventListener with an anonymous function never removes the listener.
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
Reveal answer
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 emission (as once() wrappers do), it mutates the array being iterated. Snapshotting with slice() before the loop prevents skipping or double-calling other listeners.
Q3: A once() listener and a regular on() listener for the same event will fire in emission order — the listener registered first fires first.
Reveal answer
true — Both on() and once() push to the same listener array. Emission iterates the array in insertion order. The type of registration (on vs once) does not affect ordering.
Q4: Which data structure is most appropriate for the listener registry in a high-performance EventEmitter?
- [ ] Plain object {} — fastest property access
- [ ] Map — O(1) lookup, handles any string key safely
- [ ] Set<[string, Listener]> — deduplicates listeners automatically
- [ ] Array of {event, fn} tuples — simplest implementation
Reveal answer
Map — O(1) lookup, handles any string key safely — Map provides O(1) amortized get/set/delete, handles any string key without prototype collision risk (unlike plain objects where 'constructor' or 'proto' could be event names), and has a clean API for checking existence.
Key Takeaways
- An EventEmitter is a Map with four methods: on, off, emit, once
- off() uses strict reference equality — anonymous functions cannot be removed
- once() requires a wrapper function and a reverse Map to allow early removal via off(originalFn)
- Snapshotting the listener array before iterating in emit() prevents mutation bugs from self-removing listeners
- Deleting empty event keys on off() prevents memory leaks in long-lived emitters
Mental model: 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 (Map) knows which phones are connected to which lines — but you must keep the exact same phone reference to unplug it.
For further actions, you may consider blocking this person and/or reporting abuse
