Publish-Subscribe Pattern in JavaScript

Architectural principles, implementation trade-offs, and production patterns for event-driven systems. Covers the three decoupling dimensions, subscriber ordering guarantees, error isolation strategies, and when Pub/Sub is the wrong choice.

Abstract

Mental Model: Pub/Sub trades explicit control flow for decoupling. Publishers fire events into a broker without knowing who (if anyone) receives them. Subscribers register interest without knowing who produces events. The broker is the single point of coupling.

Core Trade-off: Loose coupling enables independent component evolution and many-to-many communication. The cost is implicit control flow—debugging requires tracing events across the system rather than following function calls.

Key Implementation Decisions:

When NOT to Use:

• Request-response patterns (use direct calls)
• Single known recipient (Observer pattern suffices)
• When you need delivery guarantees (Pub/Sub doesn’t guarantee delivery)
• Simple systems unlikely to scale (unnecessary indirection)

The Three Dimensions of Decoupling

Eugster et al.’s foundational paper “The Many Faces of Publish/Subscribe” defines pub/sub as providing “full decoupling of the communicating entities in time, space, and synchronization”:

1. Space Decoupling: Publishers emit events without knowledge of which subscribers (if any) will receive them. Subscribers register without knowing which publishers produce events. Neither knows the other’s identity, location, or count.

2. Time Decoupling: Publishers and subscribers need not be active simultaneously. In distributed systems (MQTT, AMQP), a subscriber can receive messages published while it was offline. In-process implementations typically lack this—events are lost if no subscriber exists at publish time.

3. Synchronization Decoupling: Publishing is non-blocking. The publisher hands the event to the broker and continues immediately. This contrasts with RPC, which the paper notes has “synchronous nature… [which] introduces a strong time, synchronization, and also space coupling.”

Subscription Schemes

Eugster et al. classify pub/sub variants by how subscribers express interest, not by transport. The three schemes are not mutually exclusive — production systems usually pick one as the primary model and layer the others on top.

Topic-based is the dominant production model because the broker can route a publish in constant time — every other scheme either evaluates a predicate per subscriber (content-based) or walks a type lattice (type-based). The broker compares strings; that is the whole reason the model scales¹.

The implementation in this article is topic-based. Most of what you build in JavaScript — EventEmitter, mitt, the production class below — is topic-based with optional wildcard matching layered on top. Reach for content-based filtering only when subscribers genuinely need server-side selection (e.g., “trades > $1M from US exchanges”) and the broker supports an index for the predicate; otherwise filter on the consumer.

Pub/Sub vs Observer Pattern

Observer is appropriate when a single subject owns the state and notifies dependents. Pub/Sub is appropriate when multiple independent components need to communicate without direct references.

Basic Implementation

A minimal implementation using ES6+ Set for O(1) subscriber management:

1type Callback<T> = (data: T) => void23export class PubSub<T> {4  #subscribers = new Set<Callback<T>>()56  subscribe(callback: Callback<T>) {7    this.#subscribers.add(callback)8    return () => this.#subscribers.delete(callback)9  }1011  publish(data: T) {12    for (const subscriber of this.#subscribers) {13      subscriber(data)14    }15  }16}

Why Set over Array:

• O(1) add/delete vs O(n) for array splice
• Automatic deduplication—same callback added twice is stored once
• Insertion order guaranteed per ECMA-262: “Set objects iterate through elements in insertion order”

If you need the same callback to fire multiple times per event (rare), use an array instead.

Usage:

1const events = new PubSub<{ userId: string; action: string }>()23const unsubscribe = events.subscribe((data) => console.log(data.action))45events.publish({ userId: "123", action: "login" })6events.publish({ userId: "123", action: "logout" })78unsubscribe() // Critical: prevents memory leaks

DOM EventTarget Alternative

The browser’s EventTarget provides native pub/sub via CustomEvent:

Show 2 hidden lines3document.dispatchEvent(event)45// Subscriber6document.addEventListener("user:login", (e: CustomEvent) => {7  console.log(e.detail.userId)Show 1 hidden line

Limitations:

• Main thread only—doesn’t work in Web Workers or Node.js
• No TypeScript generics—detail is any
• Global namespace—all events share document, risking collisions

Custom implementation adds ~16 lines but works across all JavaScript runtimes.

Production-Grade Implementation

Production systems require: topic-based routing, error isolation, async support, and proper typing. Key design decisions explained inline:

Show 8 hidden lines9// - O(1) topic lookup10// - O(1) subscriber add/remove by token11// - Stable iteration order (subscribers called in registration order)12class PubSub {13  private topics = new Map<string, Map<number, Callback>>()14  private nextToken = 01516  subscribe<T>(topic: string, callback: Callback<T>): Subscription {17    const token = this.nextToken++1819    if (!this.topics.has(topic)) {20      this.topics.set(topic, new Map())21    }22    this.topics.get(topic)!.set(token, callback as Callback)2324    return {25      token,26      unsubscribe: () => {27        const subscribers = this.topics.get(topic)28        if (subscribers) {29          subscribers.delete(token)30          // Clean up empty topics to prevent memory growth31          if (subscribers.size === 0) this.topics.delete(topic)32        }33      },34    }35  }3637  // Synchronous publish with error isolation38  // Returns: whether any subscribers existed39  publish<T>(topic: string, data: T): boolean {40    const subscribers = this.topics.get(topic)41    if (!subscribers || subscribers.size === 0) return false4243    for (const callback of subscribers.values()) {44      // Critical: try/catch per subscriber45      // One failing subscriber must not break others46      try {47        callback(data)48      } catch (error) {49        console.error(`[PubSub] Error in subscriber for "${topic}":`, error)50        // Optional: emit to error topic for centralized handling51        // this.publish('pubsub:error', { topic, error, data })52      }53    }54    return true55  }5657  // Async publish: waits for all subscribers, doesn't short-circuit on errors58  async publishAsync<T>(topic: string, data: T): Promise<PromiseSettledResult<void>[]> {59    const subscribers = this.topics.get(topic)60    if (!subscribers || subscribers.size === 0) return []6162    // Promise.allSettled (ES2020) ensures all subscribers complete63    // even if some reject—critical for reliable event handling64    const promises = Array.from(subscribers.values()).map(async (callback) => {65      await callback(data)66    })6768    return Promise.allSettled(promises)69  }70}71Show 2 hidden lines

Design Decisions:

Memory Leak Prevention

Memory leaks in pub/sub arise when subscribers outlive their intended scope. Common patterns:

1. Anonymous functions can’t be removed — removeEventListener requires the same function reference
2. Closures capture component state — subscriber holds references preventing garbage collection
3. Missing cleanup on unmount — React components, Angular services, etc.

Node.js warns at 11+ listeners per event: MaxListenersExceededWarning: Possible EventEmitter memory leak detected.

React Pattern (useEffect cleanup):

Show 4 hidden lines5  userId: string6  isOnline: boolean7}89function UserStatus({ userId }: { userId: string }) {10  const [isOnline, setIsOnline] = useState(false)1112  useEffect(() => {13    const { unsubscribe } = pubsub.subscribe<StatusEvent>("user:status", (data) => {14      if (data.userId === userId) setIsOnline(data.isOnline)15    })16    // Critical: cleanup on unmount or userId change17    return unsubscribe18  }, [userId])1920  return <span>{isOnline ? "Online" : "Offline"}</span>21}

Key points:

• Return unsubscribe directly from useEffect — it’s already a cleanup function
• Include userId in deps array — re-subscribes when prop changes
• Named function isn’t needed since we use the returned unsubscribe

Subscriber Ordering and Error Handling

Execution Order Guarantees

Are subscribers called in registration order? It depends on the implementation.

Per ECMA-262, Map and Set iterate in insertion order. Our implementation using Map<number, Callback> guarantees subscribers execute in registration order.

Per Node.js EventEmitter docs: “All listeners attached to it at the time of emitting are called in order.”

Per WHATWG DOM Standard: EventTarget listeners are called in registration order within each phase.

Caveat: Not all libraries guarantee order. If order matters for your use case, either:

1. Use a single subscriber that orchestrates the sequence
2. Verify your library’s implementation

Async Subscriber Pitfalls

Node.js docs warn: “Using async functions with event handlers is problematic, because it can lead to an unhandled rejection in case of a thrown exception.”

1// Dangerous: unhandled rejection if async handler throws2pubsub.subscribe("data", async (data) => {3  await saveToDatabase(data) // If this throws, rejection is unhandled4})

Solutions:

1. Use publishAsync with Promise.allSettled (shown in production implementation)
2. Wrap async subscribers in try/catch:

1pubsub.subscribe("data", async (data) => {2  try {3    await saveToDatabase(data)4  } catch (error) {5    // Handle locally or emit to error topic6    pubsub.publish("error", { source: "data", error })7  }8})

3. For Node’s built-in EventEmitter, enable captureRejections. Node ≥ 13.4 ships an opt-in mode that auto-installs .then(undefined, handler) on the promise an async listener returns and forwards the rejection to the emitter’s 'error' event (or Symbol.for('nodejs.rejection') if defined). It is opt-in because changing the default would break existing emitters whose handlers rely on rejections silently bubbling out.

1import { EventEmitter } from "node:events"23const ee = new EventEmitter({ captureRejections: true })45ee.on("data", async () => {6  throw new Error("kaboom") // Now routed to 'error' below, not unhandled7})8ee.on("error", (err) => console.error("[ee]", err))

Do not use an async function for the 'error' listener itself — Node deliberately leaves that path uncaught to avoid infinite error loops.

Advanced Capabilities

Hierarchical Topics and Wildcard Subscriptions

Topic naming convention: domain.entity.action (e.g., user.profile.updated, cart.item.added).

A minimal AMQP-style matcher in JavaScript:

Show 3 hidden lines4  const patternParts = pattern.split(".")5  const topicParts = topic.split(".")67  for (let i = 0; i < patternParts.length; i++) {8    const p = patternParts[i]9    if (p === "#") return true // Multi-level: match rest10    if (p !== "*" && p !== topicParts[i]) return false11  }1213  return patternParts.length === topicParts.length14}

Backpressure Considerations

Standard pub/sub has no built-in backpressure. Publishers emit as fast as they can regardless of subscriber capacity. The naïve in-process broker has no upper bound on queue depth, no consumer credit, and no signal back to the publisher when subscribers are slow.

In-process strategies, in increasing order of safety:

• Debounce / throttle at the publisher — lossy but bounds publish rate. Use when individual events are fungible (mouse-move, scroll position, dirty-marker).
• Bounded buffer with drop policy — wrap the broker in a ring buffer; on overflow drop oldest, drop newest, or drop random. Match the policy to the consumer (drop-oldest for telemetry, drop-newest for command-like signals you must not reorder).
• Promise.allSettled with a concurrency cap — gate publishAsync behind a semaphore (e.g. p-limit) so the publisher actually waits when subscribers stall. This converts implicit unbounded fan-out into explicit cooperative backpressure.
• Pull-based async iterators — switch the contract: subscribers for await events, the broker only computes the next event on demand. Libraries like event-iterator wrap a callback API with a highWaterMark; once the buffer fills, the broker stops calling the source until the consumer drains. This is the pattern Node uses for readable streams in object mode.

When in-process broker usage moves beyond UI events into work that must not be lost, escalate out of pub/sub to a real broker with acknowledgments and durable storage — see the Async Queue Pattern and the Queues and Pub/Sub articles for the operational model.

Broker vs Brokerless

The classical pub/sub model puts a broker in the middle: every publish lands at the broker, which owns subscription state and dispatch. This is what every example in this article assumes, what EventEmitter does in-process, and what Kafka, RabbitMQ, NATS, and Redis Pub/Sub do over the network.

A brokerless model removes the dispatcher: publishers send directly to known subscribers, often via multicast, gossip, or a distributed routing table. ZeroMQ’s PUB/SUB sockets are the canonical example — there is no central process; the library lets each peer maintain its own subscription table and the publisher writes once per subscriber socket. The trade-off is operational simplicity (no broker to deploy, scale, or operate) for weaker guarantees (no durability, no replay, no central observability) and a heavier client².

In practice, choose brokerless only when you control all participants, the network is trusted, and persistence is genuinely not needed. Everything else benefits from the broker — even if it is only a single-node Redis or NATS server.

Broker Comparison: Redis Pub/Sub vs Kafka vs NATS Core

When the in-process broker is no longer enough, pick the distributed broker that matches your delivery model. The three most common topic-based defaults differ in exactly the dimensions that bite in production:

Pick Redis Pub/Sub for ephemeral notifications inside a system that already runs Redis (cache invalidation, websocket fan-out) and where loss on restart is fine³. Pick Kafka when consumers need replay, exactly-once semantics, or independent scaling on a durable log — the Kafka docs describe it as “a distributed, replicated commit log”, which is exactly what changes the operational model. Pick NATS Core for the lowest-latency fan-out path; add JetStream when you need persistence on top, accepting the extra ops cost⁴.

When NOT to Use Pub/Sub (Antipatterns)

Understanding when to avoid pub/sub is as important as knowing when to use it. The two-question filter:

1. Forcing Commands into Pub/Sub

Per CodeOpinion: “Commands do not use the publish-subscribe pattern. Trying to force everything into publish-subscribe when that’s not the pattern you want will lead you to apply more patterns incorrectly.”

Command vs Event:

• Command: “CreateOrder” — directed to a specific handler, expects execution
• Event: “OrderCreated” — notification of something that happened, no expectation of specific handler

2. Request-Reply Disguised as Events

If your publisher expects a specific response event back, you’ve recreated synchronous RPC with extra complexity. Use direct function calls or actual RPC instead.

3. CRUD Events Lacking Intent

CustomerChanged doesn’t indicate why something changed. Consumers must diff the data to infer intent. Prefer intent-revealing events: CustomerAddressUpdated, CustomerDeactivated.

4. Simple Systems

Pub/sub adds indirection. For a small app with straightforward component communication, direct function calls or context/props are simpler and more debuggable.

5. When Delivery Guarantees Matter

In-process pub/sub doesn’t guarantee delivery. If no subscriber exists when an event fires, it’s lost. For critical events, use message queues with persistence (Redis Streams, RabbitMQ, Kafka).

Debugging Challenges

Martin Fowler in What do you mean by “Event-Driven”? names this directly: “It can become problematic if there really is a logical flow that runs over various event notifications. The problem is that it can be hard to see such a flow as it’s not explicit in any program text.”

The implicit control flow that provides loose coupling also makes debugging harder. Distributed tracing and careful logging are essential for production pub/sub systems.

Real-World Applications

Frontend: Cross-Component Communication

Pub/sub solves “prop drilling” when unrelated components need to react to the same events.

E-commerce cart example:

• ProductCard publishes cart.item.added on button click
• CartIcon subscribes → updates badge count
• Toast subscribes → shows confirmation
• Analytics subscribes → tracks conversion

Each subscriber is independent. Adding a new reaction requires no changes to ProductCard.

Backend: Event-Driven Microservices

External brokers (Redis Pub/Sub, RabbitMQ, Google Cloud Pub/Sub, Kafka) provide distributed pub/sub with durability.

User registration flow:

• UserService publishes user.created
• EmailService → sends welcome email
• AnalyticsService → tracks signup metrics
• OnboardingService → queues tutorial sequence

Services deploy independently. Adding a new reaction (e.g., CRM sync) requires no changes to UserService.

Build vs Buy Decision

For production, prefer battle-tested libraries unless you need custom semantics.

Recommendations:

• Minimal footprint: mitt or nanoevents (both under 200B)
• Node.js API compatibility: EventEmitter3
• Wildcards needed: EventEmitter2 (or MQTT/AMQP for distributed)
• Learning: Build your own—the 20-line implementation teaches the core

mitt caveat: The * handler receives all events but is a listener, not a wildcard pattern. Publishing to * directly causes double-triggering issues.

Best Practices Summary

Implementation Checklist

Error Handling Strategies

1. Per-subscriber isolation: Wrap each callback in try/catch (shown in production implementation)
2. Error topic: Emit to pubsub:error for centralized handling
3. Dead-letter queue: For distributed systems, track repeatedly failing messages
4. Dev mode exceptions: Optionally rethrow in development for stack traces

Conclusion

Pub/Sub trades explicit control flow for decoupling. Publishers emit without knowing receivers; subscribers react without knowing sources. This enables independent component evolution and many-to-many communication at the cost of implicit, harder-to-trace control flow.

Use pub/sub when:

• Multiple independent components need to react to the same events
• Components should evolve independently (add/remove reactions without changing publishers)
• You’re building event-driven architecture (frontend cross-component communication, backend microservices)

Avoid pub/sub when:

• You need request-response semantics
• There’s a single known recipient (use Observer or direct calls)
• Delivery guarantees are required (use message queues)
• The system is simple and unlikely to need the decoupling

Implementation is straightforward: Map<string, Set<Function>>, return unsubscribe, try/catch per subscriber. The challenge is architectural—knowing when the indirection is worth the debuggability cost.

Appendix

Prerequisites

• JavaScript ES6+ (Map, Set, Promise, async/await)
• Basic understanding of event-driven programming
• Familiarity with React hooks (for framework examples)

Terminology

Summary

• Pub/Sub provides three-dimensional decoupling: space, time, synchronization
• Use Map<string, Set<Function>> for O(1) operations and guaranteed order
• Always return unsubscribe function; tie cleanup to component lifecycle
• Isolate subscriber errors with per-callback try/catch
• Use Promise.allSettled for async publish to avoid short-circuiting
• Avoid for request-response, single recipients, or when delivery guarantees matter
• Libraries: mitt (~200 B), nanoevents (~108 B) for minimal footprint

References

Specifications & Standards:

• The Many Faces of Publish/Subscribe - Eugster et al., ACM Computing Surveys 2003. Foundational paper defining the three dimensions of decoupling.
• ECMA-262: Map and Set Objects - Guarantees insertion order for iteration.
• WHATWG DOM Standard: EventTarget - Browser’s native pub/sub mechanism.
• OASIS MQTT 5.0 Specification - Distributed pub/sub protocol.

Official Documentation:

• Node.js Events Documentation - EventEmitter ordering guarantees, async handler pitfalls.
• MDN: CustomEvent - Browser native event API.
• MDN: WeakRef - Memory management considerations.

Libraries:

• mitt - 200B functional event emitter.
• nanoevents - 107B with TypeScript support.
• EventEmitter3 - Node.js-compatible API.
• EventEmitter2 - Wildcard support.

Architectural Guidance:

• Enterprise Integration Patterns: Publish-Subscribe Channel - Hohpe & Woolf, the standard messaging-patterns reference.
• Martin Fowler — What do you mean by “Event-Driven”? - On event notification, event-carried state transfer, event sourcing, CQRS, and the implicit-flow trade-off.
• CodeOpinion: Antipatterns in Event-Driven Architecture - Practitioner walkthrough of when not to use pub/sub.