Forem: Mohammed Abdelhady

The Role of Fiber in React Rendering (Part 1): The Tree, The Walk, The Loop

Mohammed Abdelhady — Wed, 08 Apr 2026 11:51:15 +0000

Every time you call setState, React somehow figures out what changed, what to update, and what to leave alone. All without you thinking about it. But have you ever wondered how?

The answer is Fiber.

Fiber is React's internal engine. It's the system that decides which components to re-render, in what order, and whether it can pause halfway through to keep your app responsive. Once you understand Fiber, patterns like React.memo, Suspense, and transitions stop feeling like magic and start making sense.

This is a two-part series. In Part 1, we'll build the foundation: what a Fiber is, how the tree is structured, and how React walks through it. In part 2, we'll go deeper into reconciliation, double buffering, hooks, the commit phase, and why interruptible rendering changes everything.

Let's open up the engine and look inside.

What You'll Walk Away With

By the end of Part 1, you'll understand that a Fiber is just a JavaScript object. One node in a tree React builds behind the scenes. You'll see how these nodes link together with child, sibling, and return pointers, forming a structure React can walk through efficiently. And you'll learn about the two-phase traversal (down with beginWork, back up with completeWork) and the work loop that drives it all.

Why should you care? Fiber is the backbone of concurrent React. Understanding it turns React from a black box into a system you can predict and debug. Suddenly, you'll know why React.memo prevents re-renders, how Suspense knows to show a fallback, and what time-slicing actually means under the hood.

So What Exactly Is a Fiber?

Strip away the jargon, and a Fiber is a plain JavaScript object. That's it. Each one holds information about a single piece of your UI: a component, a DOM element, a text node. Think of it as React's internal sticky note for that piece. What type it is, what props it received, what state it holds, and what work needs to be done.

Here's the key difference from the element tree you're used to: React elements get recreated every render. Fiber nodes don't. They persist. React mutates them in place, updating their props and state rather than throwing them away and rebuilding from scratch. This is what allows React to track things across renders. Hooks, effects, scheduling priorities, all of it lives on the Fiber.

Here's a simplified look at what a Fiber node holds:

interface Fiber {
  // What am I?
  tag: number              // FunctionComponent, HostComponent, etc.
  type: string | Function  // 'div', 'span', or YourComponent

  // Where do I sit in the tree?
  child: Fiber | null      // My first child
  sibling: Fiber | null    // My next sibling
  return: Fiber | null     // My parent

  // What are my inputs and outputs?
  pendingProps: object     // New props coming in this render
  memoizedProps: object    // Props from the last render
  memoizedState: unknown   // Current state (hooks linked list lives here)

  // What work needs doing?
  flags: number            // Placement, Update, Deletion (bitmask)
  subtreeFlags: number     // Aggregated flags from all my children

  // How urgent is this work?
  lanes: number            // Priority lanes for this fiber
  childLanes: number       // Priority from children

  // Double buffering
  alternate: Fiber | null  // My twin in the other tree
}

Don't try to memorize every field. The important takeaway is that each Fiber knows three things: what it is, where it sits in the tree, and what work needs to happen to it.

How Fibers Connect: The Linked List Tree

If you've worked with tree structures before, you might expect each node to have a children array. Fiber doesn't do that. Instead, it uses three pointers:

child points to the first child only
sibling points to the next sibling
return points back to the parent

This forms a linked list you can walk with simple pointer-following. No arrays, no iteration, no index tracking.

Let's make this concrete. Say you have this component tree:

<App>
  <Header />
  <Main>
    <ItemA />
    <ItemB />
  </Main>
</App>

React builds this Fiber structure:

App
 │
 ├─child──→ Header ──sibling──→ Main
 │            │                    │
 │          return → App        child──→ ItemA ──sibling──→ ItemB
 │                                         │                  │
 │                                       return → Main     return → Main
 │

Notice how App only knows about Header (its first child). To find Main, React has to follow Header.sibling. To get back to App from anywhere below, it follows return pointers up.

This structure is what makes React's traversal so predictable, and so interruptible.

The Two-Phase Walk: beginWork and completeWork

React doesn't render your whole tree in one shot. It walks the Fiber tree in a depth-first order, processing each node in two phases:

Phase 1, beginWork (going down): React visits a Fiber, runs the component (calls your function component or class render method), and figures out what its children should look like. Then it moves to the first child and repeats.

Phase 2, completeWork (bubbling up): When a Fiber has no more children to process, React "completes" it. This is where it prepares any DOM updates. Then it moves to the sibling. If there's no sibling, it goes up to the parent via return and completes that too.

Here's the walk for our example tree:

 1. beginWork(App)        → go to child
 2. beginWork(Header)     → no child, so complete it
 3. completeWork(Header)  → go to sibling
 4. beginWork(Main)       → go to child
 5. beginWork(ItemA)      → no child, complete it
 6. completeWork(ItemA)   → go to sibling
 7. beginWork(ItemB)      → no child, complete it
 8. completeWork(ItemB)   → no sibling, go up (return)
 9. completeWork(Main)    → no sibling, go up (return)
10. completeWork(App)     → done!

This is the heartbeat of every React render. Every component you've ever written gets processed through this exact loop.

The Work Loop

So what actually drives this walk? A function called workLoopSync (or workLoopConcurrent for interruptible renders). It's surprisingly simple, just a while loop:

function workLoopSync() {
  while (workInProgress !== null) {
    performUnitOfWork(workInProgress)
  }
}

function workLoopConcurrent() {
  while (workInProgress !== null && !shouldYield()) {
    performUnitOfWork(workInProgress)
  }
}

That's the entire difference between sync and concurrent mode: one extra check, shouldYield(). This function asks the scheduler "have we been working too long? Does the browser need the thread back?" If yes, React stops the loop and gives control back. The workInProgress pointer stays right where it is, so React can pick up exactly where it left off on the next frame.

performUnitOfWork is where the two phases come together:

function performUnitOfWork(fiber) {
  // Phase 1: process this fiber and get its child
  const next = beginWork(fiber)

  if (next !== null) {
    // Has a child, move down
    workInProgress = next
  } else {
    // No child, complete this fiber then move to
    // sibling or bubble up via return
    completeUnitOfWork(fiber)
  }
}

That's it. beginWork returns the next child (or null). If there's a child, we go deeper. If not, we complete and look for a sibling or parent. The whole tree traversal is just this loop running over and over, one Fiber at a time.

Reconciliation: How React Diffs the Trees

The render phase isn't just walking the tree. It's also comparing the new output with the old one. This process is called reconciliation, and it happens inside beginWork.

When React calls your function component and gets back a new set of children, it doesn't throw away the old Fibers. Instead, it compares the new elements with the existing Fibers to figure out what actually changed. The rules are straightforward:

Same type and key? React keeps the Fiber, updates its props, and moves on. This is why React.memo works. If React sees the same component type and the props haven't changed, it can bail out of beginWork entirely and skip the whole subtree.

Different type? React marks the old Fiber for deletion and creates a new one. This is why swapping <div> for <section> unmounts and remounts everything inside it.

Lists with keys? React uses the key prop to match old Fibers with new elements, even if their order changed. Without keys, React matches by index, which leads to subtle bugs when items get reordered.

Old Fibers:       New Elements:       What React does:
─────────────     ──────────────      ─────────────────
<Header />   →    <Header />          Same type → reuse, update props
<Main />     →    <Sidebar />         Different type → delete Main, create Sidebar
<Footer />   →    <Footer />          Same type → reuse, update props
                  <Banner />          New element → create with Placement flag

The output of reconciliation is an updated Fiber tree where each node is tagged with the right effect flags. Nothing touches the DOM yet.

Test Your Knowledge (Part 1)

Q1: What is a Fiber in React?

[ ] A DOM node wrapper
[ ] A JavaScript object representing a unit of work in React's internal tree
[ ] A Web Worker thread for parallel rendering
[ ] A CSS-in-JS engine

Q2: How are Fiber nodes connected in the tree?

[ ] Each Fiber has a children array
[ ] Fibers use child, sibling, and return pointers (linked list)
[ ] Fibers are stored in a flat array sorted by depth
[ ] Fibers reference each other by string IDs

Q3: In what order does React traverse the Fiber tree during rendering?

[ ] Breadth-first (level by level)
[ ] Random order based on priority
[ ] Depth-first: beginWork goes down, completeWork bubbles up
[ ] Bottom-up only

Reveal all answers

Q1: A JavaScript object representing a unit of work in React's internal tree. A Fiber is a plain JS object that holds information about a component, its props, state, position in the tree, and what side effects need to be performed. Each React element gets a corresponding Fiber node.

Q2: Fibers use child, sibling, and return pointers (linked list). This linked list structure means traversal is just pointer-following. No array allocation, no index management. child points to the first child, sibling to the next sibling, and return back to the parent.

Q3: Depth-first: beginWork goes down, completeWork bubbles up. React processes a Fiber in beginWork and moves to its child. When there's no child, completeWork runs and React moves to the sibling or bubbles up via return.

What's Coming in Part 2

Now that you know what a Fiber is, how the tree is wired, and how React walks through it, we're ready to go deeper. In Part 2, we'll cover:

Double buffering and the current ↔ workInProgress swap
Effect flags and how React knows exactly what DOM work to do
Priority lanes and why not all state updates are equal
Where hooks actually live on the Fiber (and why call order matters)
The commit phase broken into its three sub-phases
Interruptible rendering and how it all ties together

See you there.

Skills: React · Fiber Architecture · Reconciliation · Concurrent Rendering · Virtual DOM

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

Mohammed Abdelhady — Sat, 04 Apr 2026 08:23:35 +0000

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

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

Mohammed Abdelhady — Sat, 04 Apr 2026 08:04:09 +0000

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.

Deep Dive: Array Internals & Memory Layout

Mohammed Abdelhady — Wed, 01 Apr 2026 21:36:51 +0000

Array Internals & Memory Layout

Before you memorize complexity tables, it helps to understand what's actually happening in memory. Once you see it, the complexities stop feeling arbitrary.

Here's what this covers:

Concept	Key insight
Contiguous memory	Elements sit side-by-side with no gaps between them
O(1) random access	`arr[i]` is one arithmetic operation: `baseAddress + i * elementSize`
O(n) insert/delete	Inserting in the middle means shifting every element after it
Amortized O(1) push	Resizing happens exponentially rarely, so it's cheap on average
V8 optimization	Dense arrays get a true contiguous backing store; sparse ones fall back to a hash map

What "contiguous" actually means

Think of memory as a long strip of numbered boxes. A contiguous array reserves a block of consecutive boxes — no gaps, no pointers between elements.

Memory address:  1000  1008  1016  1024  1032
                  ↓     ↓     ↓     ↓     ↓
Array contents: [ 10 ][ 20 ][ 30 ][ 40 ][ 50 ]
                  ↑
              baseAddress

Each box is 8 bytes. So:

arr[0] lives at 1000 + 0 * 8 = 1000
arr[3] lives at 1000 + 3 * 8 = 1024
arr[i] lives at 1000 + i * 8

That's one multiply and one add, regardless of whether i is 0 or 500,000. That's why arrays have O(1) random access.

A linked list has to be traversed instead. Each node holds a pointer to the next:

[10 | *]──→[20 | *]──→[30 | *]──→[40 | *]──→[50 | null]

To reach node[3] you follow pointers: head → next → next → next. That's O(n) and there's no shortcut.

How V8 handles arrays internally

JavaScript arrays aren't always backed by contiguous memory. V8 picks a mode based on how you use them:

Mode	When it applies	What it uses
`PACKED_SMI`	Dense array of small integers	True contiguous block — fastest
`PACKED_DOUBLE`	Dense array of floats	True contiguous block
`PACKED_ELEMENTS`	Dense mixed types	Contiguous block of pointers
Dictionary mode	Sparse array with gaps	Hash map — much slower

const dense = [1, 2, 3, 4, 5]  // PACKED_SMI — contiguous memory

const sparse = []
sparse[1000] = 1                // Dictionary mode — indices 0–999 are holes

Keep your arrays dense and consistent in type. The moment you introduce holes, V8 falls back to a hash map and you lose the performance benefits.

Operation complexities, with reasoning

Reading by index and appending are both fast:

const arr = [10, 20, 30, 40, 50]

// O(1) — CPU jumps directly to baseAddress + 3 * 8
console.log(arr[3]) // 40

// O(1) amortized — backing store has spare capacity, just write to the next slot
arr.push(60)
// [10, 20, 30, 40, 50, 60]

Inserting or removing in the middle is expensive because elements have to shift:

const arr = [10, 20, 30, 40, 50]

// O(n) — everything after index 1 moves right
arr.splice(1, 0, 15)

// Before: [10, 20, 30, 40, 50]
// After:  [10, 15, 20, 30, 40, 50]
//                  ↑   ↑   ↑   ↑
//              all shifted right

// O(n) — every single element shifts right
arr.unshift(5)

Here's what splice(1, 0, 15) actually does to the backing store:

Before:  [10][20][30][40][50][ ]

Step 1 — shift right:
         [10][ ][20][30][40][50]

Step 2 — write 15:
         [10][15][20][30][40][50]

The more elements in the array, the more shifting — hence O(n).

Why arrays beat linked lists even when Big-O is the same

Sequential iteration is O(n) for both arrays and linked lists. In practice arrays can be 10–100× faster, and the reason is the CPU cache.

Modern CPUs don't fetch one byte at a time. They load a cache line — typically 64 bytes at once. When you read arr[0], the CPU automatically pulls in arr[0] through arr[7]. By the time the loop reaches arr[1], it's already in cache.

Cache line loaded when you read arr[0]:
┌────┬────┬────┬────┬────┬────┬────┬────┐
│[0] │[1] │[2] │[3] │[4] │[5] │[6] │[7] │
└────┴────┴────┴────┴────┴────┴────┴────┘
         ↑              ↑
    cache hit       cache hit — already there, no wait

Linked list nodes are scattered across memory. Each pointer-follow likely lands in a cold cache line — the CPU stalls while waiting for RAM to respond.

// Cache-friendly — next element is already loaded
function sum(arr) {
  let total = 0
  for (let i = 0; i < arr.length; i++) {
    total += arr[i]
  }
  return total
}

// Cache-unfriendly — each jump is unpredictable
function randomSum(arr, indices) {
  let total = 0
  for (const i of indices) {
    total += arr[i] // likely a cache miss each time
  }
  return total
}

Dynamic resizing and amortized O(1) push

JavaScript arrays grow automatically. When the backing store is full, V8 allocates a new array roughly 2× the current size and copies everything over. That single push is O(n), but it happens so rarely that the average cost across many pushes stays O(1).

Here's a concrete example showing how the cost spreads out:

Push #	Cost	Resize?
1–4	O(1) each	No
5	O(4) — copies 4 elements	Yes, capacity → 8
6–8	O(1) each	No
9	O(8) — copies 8 elements	Yes, capacity → 16
10–16	O(1) each	No

Each expensive push is paid for by all the cheap ones that came before it. Total work across n pushes is roughly 2n, which averages to O(1) per push.

class DynamicArray {
  constructor() {
    this.data     = new Array(4)
    this.size     = 0
    this.capacity = 4
  }

  push(val) {
    if (this.size === this.capacity) {
      this._resize()
    }
    this.data[this.size] = val
    this.size++
  }

  _resize() {
    this.capacity *= 2
    const newData = new Array(this.capacity)
    for (let i = 0; i < this.size; i++) {
      newData[i] = this.data[i] // O(n) — but only triggered every n pushes
    }
    this.data = newData
  }

  get(i) {
    return this.data[i]
  }
}

One thing worth keeping in mind: amortized O(1) hides occasional O(n) spikes. In game loops or audio threads where every frame has a tight deadline, a resize at the wrong moment causes a drop. If you know the size upfront, pre-allocate:

const arr = new Array(10000).fill(0) // one allocation, no resizing

Choosing the right structure

A few things to watch out for in practice:

splice(0, 1) and shift() are both O(n) — they shift every element left. pop() is O(1) because nothing moves. If you need queue behavior, don't use shift() on large arrays; use a circular buffer instead.

Creating holes in an array pushes V8 into dictionary mode. a[1000] = 1 with nothing at indices 0–999 is the classic case. If you need an explicit empty value, use undefined rather than leaving a gap.

For raw numeric data, TypedArray gives you the most direct control:

const matrix = new Float64Array(1024 * 1024)
// True contiguous memory, fixed element type, zero boxing overhead

Test your knowledge

Q1: Why is accessing arr[500] the same speed as arr[0]?

[ ] The CPU computes baseAddress + 500 * elementSize — one arithmetic operation
[ ] JavaScript caches all indices at creation time
[ ] The array is sorted so binary search finds it in O(log n)
[ ] The garbage collector optimizes frequent accesses

Q2: What is the time complexity of arr.splice(0, 0, 'x') on an array of n elements?

[ ] O(1)
[ ] O(log n)
[ ] O(n)
[ ] O(n²)

Q3: What does this log?

const a = [1, 2, 3]
a.push(4)
a.unshift(0)
console.log(a.length, a[0], a[4])

Q4: Why are arrays faster than linked lists for sequential iteration, even though both are O(n)?

[ ] Cache locality — contiguous memory means the CPU prefetches subsequent elements automatically
[ ] Arrays have shorter pointers
[ ] Linked lists require sorting before iteration
[ ] Arrays use less memory per element

Q5: Why is push() O(1) amortized but not O(1) worst-case?

[ ] Occasionally the backing store must double in size, copying all elements — O(n) for that single push
[ ] push() sorts the array after insertion
[ ] The garbage collector pauses on every push
[ ] V8 recalculates hash codes for the array

Answers

A1: The CPU computes baseAddress + 500 * elementSize — one arithmetic operation. Contiguous layout means any index is reachable via a single address calculation with no traversal.

A2: O(n). Inserting at index 0 requires shifting all n existing elements one position right to make room.

A3: 5 0 4. After push(4): [1, 2, 3, 4]. After unshift(0): [0, 1, 2, 3, 4]. Length is 5, a[0] is 0, a[4] is 4.

A4: Cache locality. When you read arr[i], the CPU loads the surrounding elements into cache too. Linked list nodes are scattered in memory — each pointer-follow is likely a cache miss and the CPU has to wait for RAM.

A5: When the backing store fills up, the array doubles in size and copies all n elements over — that one push is O(n). But this only happens after n pushes, so the cost averages to O(1) across all of them.

Key takeaways

An array is a numbered row of lockers in a corridor. Walking to locker 500 is instant — you compute the number and go directly there. Inserting a new locker in the middle means sliding every subsequent locker down by one. And when the corridor runs out of space, it doubles in length — expensive once, but it happens less and less often as the corridor grows.

Rule	Why it matters
`arr[i]` = `base + i * size`	One arithmetic op — always O(1)
Insertion at index k shifts n−k elements	O(n) — unavoidable for mid-array changes
`pop()` is O(1), `shift()` is O(n)	Remove from the end when you can
Dense arrays stay in V8 fast mode	Holes trigger dictionary mode
Cache lines load 8+ elements at once	Sequential iteration is far faster than scatter
Resize doubles capacity	Keeps amortized push O(1) over n operations

Forem: Mohammed Abdelhady

The Role of Fiber in React Rendering (Part 1): The Tree, The Walk, The Loop

What You'll Walk Away With

So What Exactly Is a Fiber?

How Fibers Connect: The Linked List Tree

The Two-Phase Walk: beginWork and completeWork

The Work Loop

Reconciliation: How React Diffs the Trees

Test Your Knowledge (Part 1)

What's Coming in Part 2

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

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

Three ideas the whole system rests on

The data structure: a Map of arrays

Reference equality: the rule that governs everything

Synchronous emission

Building the EventEmitter

on(): registering a listener

off(): removing a listener

emit(): calling all listeners

once(): the self-removing listener

The complete EventEmitter

The project: mini-nodemon

GlobMatcher: pattern to regex

FileWatcher: OS events to filtered EventEmitter events

Debounce: collapse rapid events into one

ProcessRunner: subscribe to changes, manage child process

Config and CLI entry point

Integration tests

Test your knowledge

Answers

Key takeaways

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

What You'll Learn

Listener Registry Pattern

The once() Wrapper Pattern

The Project: mini-nodemon

Building It Step by Step

Step 1: Build the EventEmitter core

Step 2: Build GlobMatcher and FileWatcher

Step 3: Build Debounce utility and ProcessRunner

Step 4: Build the CLI entry point and config loader

Step 5: Write the integration test

The Integration Test

Test Your Knowledge

Key Takeaways

Deep Dive: Array Internals & Memory Layout

Array Internals & Memory Layout

What "contiguous" actually means

How V8 handles arrays internally

Operation complexities, with reasoning

Why arrays beat linked lists even when Big-O is the same

Dynamic resizing and amortized O(1) push

Choosing the right structure

Test your knowledge

Answers

Key takeaways

`on()`: registering a listener

`off()`: removing a listener

`emit()`: calling all listeners

`once()`: the self-removing listener