Part 1: Taming Asynchronous JavaScript: How to Build a "Mailbox" Queue

The article explains how to build a JavaScript "Mailbox" queue using Promises to manage asynchronous data flow when a producer sends data faster than a consumer can process it. The implementation stores incoming messages in an array and uses a waiter array to pause the consumer via unresolved Promises until new data arrives. The author notes that while this approach works for typical use cases, it can freeze a server when handling very large volumes of data, which will be addressed in a follow-up article.

Have you ever tried to catch water from a fire hydrant with a paper cup? That is exactly what it feels like when you are building a JavaScript app and data starts coming in way faster than your code can process it. Maybe you are handling a flood of incoming webhooks, reading a massive file, or listening to a busy WebSocket. If your data sender is faster than your data receiver, things break. What you need is a waiting room. A place where incoming data can chill out until your app is ready to handle it. In computer science, this is called a "Queue" or a "Channel." Today, we are going to build one from scratch. Let's call it our Mailbox. The Idea Behind the Mailbox Think of a literal physical mailbox. The Mail Carrier The Producer : Drops letters into the box. They don't care if you are home; they just drop the mail and leave. You The Consumer : You check the mailbox. If there is mail, you take it. If the box is empty, you just wait until the mail carrier shows up. We can recreate this exact relationship in JavaScript using Promises. Here is the code. It might look a little magical at first, but we will break it down right after export class Mailbox { constructor { this.messages = this.waiters = this.closed = false } push message { if this.closed { throw new Error "Mailbox is closed" } // Deliver directly to waiting consumer if this.waiters.length 0 { const resolve = this.waiters.shift resolve message return } this.messages.push message } async pop { // Message already available if this.messages.length 0 { return this.messages.shift } // Closed mailbox if this.closed { return null } // Wait for future message return new Promise resolve = { this.waiters.push resolve } } close { this.closed = true // Wake all waiting consumers while this.waiters.length 0 { const resolve = this.waiters.shift resolve null } } get size { return this.messages.length } async Symbol.asyncIterator { while true { const msg = await this.pop if msg === null { break } yield msg } } } The "Aha " Moment: Pausing JavaScript The coolest part of this code is inside the pop method. Usually, when we use a Promise in JavaScript, it's for something like fetch You make a request, and eventually, it resolves. But here, we are doing something sneaky. If the mailbox is empty, we create a new Promise, but we take its resolve function and shove it into our this.waiters array. We are essentially bottling up the ability to finish the Promise for later. Your code effectively pauses. It just sits there, waiting. Then, when the push method gets called, it looks inside this.waiters, pulls out that bottled-up resolve function, and triggers it with the new message. Boom Your paused code instantly wakes up with the data. How to Use It Because we added that weird looking Symbol.asyncIterator at the bottom of the class, using our Mailbox is beautifully simple: js const mailbox = new Mailbox ; // 1. You: waiting for mail async function readMail { // This loop will naturally pause and wait for new messages for await const msg of mailbox { console.log "Just got:", msg ; } console.log "No more mail coming " ; } readMail ; // 2. The Mail Carrier: dropping off mail at random times mailbox.push "Letter 1" ; setTimeout = mailbox.push "Letter 2" , 1000 ; setTimeout = mailbox.close , 2000 ; This setup works flawlessly for everyday tasks. But there is a hidden monster in this code. If you get too popular—say, someone drops 1,000,000 letters into your mailbox at once—this exact code will completely freeze your server for minutes. In Part 2, we are going to find out exactly why JavaScript hates huge arrays, and how to fix our Mailbox to handle millions of messages in a fraction of a second. The link to the repo of full source code of this: https://github.com/pckrishnadas88/mailbox https://github.com/pckrishnadas88/mailbox