Karrot Introduces Promise Queuing System for Concurrency Control of Neighborhood Walking Overlays

Karrot's Neighborhood Walking service introduced a Promise queuing system to resolve issues where multiple overlays, such as modals, bottom sheets, and OS permission popups, triggered simultaneously and overlapped on the screen. Previously, direct connections between components (onClose chaining) resulted in mixed domain logic and branching conditions, creating QA blind spots. This was redefined as a problem of 'concurrency control for independent overlay triggers.'

Promise.withResolvers-Based Queuing Implementation

The core implementation utilized the Promise.withResolvers pattern (standardized in ES2024) with a 9-line helper to control resolve/reject externally. By using queueMicrotask, all reserve calls within the same synchronous task were collected before being sorted and processed at once, preventing interference from other tasks that could occur when using macrotasks. A Zustand store was adopted as the internal structure, including trigger functions and Promise control capabilities in the Entry.

Priority Policy and API Design

The useReserveOverlay hook was provided, designed to allow callers to reference priority, id, and subOrder from the catalog (OVERLAY_PRIORITY). Priorities are divided into four levels: critical (forced preemption), high, normal, and low. Within the same priority, ordering is adjusted via FIFO or subOrder. Cancellation (cancelled) returns via resolve, while reject is handled only when trigger throws, clearly distinguishing result states.

Effects and Validation

Overlay ordering code (order, condition, etc.) was removed, so changing the order only requires modifying the subOrder value in the catalog. For example, moving the Climate Campaign stamp flow behind the consecutive attendance modal was achieved simply by changing the subOrder from 10 to 40. During 4.5 months of queue operation, there were 15 ordering change requests, all handled without rewriting complex conditions. Additionally, the validation method was shifted from manual QA to CI tests (4 files, 29 cases) to automatically verify priority-ordered processing, preemption, and unmount handling.