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.”

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:

1
type Callback<T> = (data: T) => void
2

3
export class PubSub<T> {
4
  #subscribers = new Set<Callback<T>>()
5

6
  subscribe(callback: Callback<T>) {
7
    this.#subscribers.add(callback)
8
    return () => this.#subscribers.delete(callback)
9
  }
10

11
  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:

1
const events = new PubSub<{ userId: string; action: string }>()
2

3
const unsubscribe = events.subscribe((data) => console.log(data.action))
4

5
events.publish({ userId: "123", action: "login" })
6
events.publish({ userId: "123", action: "logout" })
7

8
unsubscribe() // Critical: prevents memory leaks

DOM EventTarget Alternative

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

2 collapsed lines
1
// Publisher
2
const event = new CustomEvent("user:login", { detail: { userId: "123" } })
3
document.dispatchEvent(event)
4

5
// Subscriber
6
document.addEventListener("user:login", (e: CustomEvent) => {
7
  console.log(e.detail.userId)
1 collapsed line
8
})

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:

8 collapsed lines
1
type Callback<T = unknown> = (data: T) => void | Promise<void>
2

3
interface Subscription {
4
  token: number
5
  unsubscribe: () => void
6
}
7

8
// Using Map<string, Map<number, Callback>> for:
9
// - O(1) topic lookup
10
// - O(1) subscriber add/remove by token
11
// - Stable iteration order (subscribers called in registration order)
12
class PubSub {
13
  private topics = new Map<string, Map<number, Callback>>()
14
  private nextToken = 0
15

16
  subscribe<T>(topic: string, callback: Callback<T>): Subscription {
17
    const token = this.nextToken++
18

19
    if (!this.topics.has(topic)) {
20
      this.topics.set(topic, new Map())
21
    }
22
    this.topics.get(topic)!.set(token, callback as Callback)
23

24
    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 growth
31
          if (subscribers.size === 0) this.topics.delete(topic)
32
        }
33
      },
34
    }
35
  }
36

37
  // Synchronous publish with error isolation
38
  // Returns: whether any subscribers existed
39
  publish<T>(topic: string, data: T): boolean {
40
    const subscribers = this.topics.get(topic)
41
    if (!subscribers || subscribers.size === 0) return false
42

43
    for (const callback of subscribers.values()) {
44
      // Critical: try/catch per subscriber
45
      // One failing subscriber must not break others
46
      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 handling
51
        // this.publish('pubsub:error', { topic, error, data })
52
      }
53
    }
54
    return true
55
  }
56

57
  // Async publish: waits for all subscribers, doesn't short-circuit on errors
58
  async publishAsync<T>(topic: string, data: T): Promise<PromiseSettledResult<void>[]> {
59
    const subscribers = this.topics.get(topic)
60
    if (!subscribers || subscribers.size === 0) return []
61

62
    // Promise.allSettled (ES2020) ensures all subscribers complete
63
    // even if some reject—critical for reliable event handling
64
    const promises = Array.from(subscribers.values()).map(async (callback) => {
65
      await callback(data)
66
    })
67

68
    return Promise.allSettled(promises)
69
  }
70
}
71

2 collapsed lines
72
// Singleton for cross-module communication
73
export const pubsub = new PubSub()

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):

4 collapsed lines
1
import { useEffect, useState } from "react"
2
import { pubsub } from "./pubsub"
3

4
interface StatusEvent {
5
  userId: string
6
  isOnline: boolean
7
}
8

9
function UserStatus({ userId }: { userId: string }) {
10
  const [isOnline, setIsOnline] = useState(false)
11

12
  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 change
17
    return unsubscribe
18
  }, [userId])
19

20
  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 throws
2
pubsub.subscribe("data", async (data) => {
3
  await saveToDatabase(data) // If this throws, rejection is unhandled
4
})

Solutions:

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

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

Advanced Capabilities

Hierarchical Topics and Wildcard Subscriptions

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

Wildcard types (MQTT convention):

• * — matches exactly one segment: user.*.login matches user.123.login
• # — matches zero or more segments (must be last): user.# matches user, user.123, user.123.login

3 collapsed lines
1
// Matches subscription patterns like "user.*.login" or "user.#"
2
// against published topics like "user.123.login"
3
function topicMatches(pattern: string, topic: string): boolean {
4
  const patternParts = pattern.split(".")
5
  const topicParts = topic.split(".")
6

7
  for (let i = 0; i < patternParts.length; i++) {
8
    const p = patternParts[i]
9
    if (p === "#") return true // Multi-level: match rest
10
    if (p !== "*" && p !== topicParts[i]) return false
11
  }
12

13
  return patternParts.length === topicParts.length
14
}

Backpressure Considerations

Standard pub/sub has no built-in backpressure. Publishers emit as fast as they can regardless of subscriber capacity.

Strategies:

• Debounce/throttle at publish — lossy but prevents flooding
• Buffer with limits — accumulate events, drop oldest when full
• Async iterator with highWater — libraries like event-iterator provide backpressure signals

For high-throughput systems, consider message queues (RabbitMQ, Redis Streams) with explicit acknowledgment.

When NOT to Use Pub/Sub (Antipatterns)

Understanding when to avoid pub/sub is as important as knowing when to use it.

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: “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 (200B), nanoevents (107B) 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 - Messaging patterns reference.
• CodeOpinion: Antipatterns in Event-Driven Architecture - When not to use pub/sub.