feat(data-structures/unstable): add Deque

[tomas-zijdemans]

Deque (double-ended queue) is a standard data structure in many ecosystems (e.g. Rust’s VecDeque, npm’s Denque with ~73M monthly downloads).

Potential std consumers: Channel, binary-search-tree, untar-stream and more

Bench

Array.push()/Array.pop() is extremely optimized in V8. If you only need a stack (push/pop from one end), use a plain Array.

Array.unshift() and Array.shift() is slow because the engine must move all elements. Deque's ring buffer makes these very fast.

The most common real-world use case for a Deque is a queue (push back + pop front) . This is where it shines 🚀

Scenario	n=100	n=1,000	n=10,000	n=100,000
push (back)	1.8× ❌	2.2× ❌	2.1× ❌	2.0× ❌
pop (back)	3.5× ❌	5.8× ❌	3.8× ❌	4.0× ❌
unshift (front push)	~same	5.6× ✅	65.6× ✅	977.0× ✅
shift (front pop)	1.4× ❌	1.7× ✅	2.5× ✅	733.1× ✅
queue (push→shift)	2.0× ❌	1.5× ✅	1.8× ✅	620.0× ✅
stack (push→pop)	3.8× ❌	2.9× ❌	3.7× ❌	3.4× ❌
indexed read	1.4× ✅	3.2× ❌	9.1× ❌	5.4× ❌

✅ = Deque faster, ❌ = Array faster. Multiplier is relative speed (e.g. "5.6× ✅" means Deque is 5.6× faster).

Results are from a M1 MacBook pro. 30 warmup + 100 measured runs per cell.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.77%. Comparing base (4221795) to head (d4f62cd).
⚠️ Report is 15 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7019      +/-   ##
==========================================
+ Coverage   93.73%   93.77%   +0.03%     
==========================================
  Files         620      621       +1     
  Lines       49388    49681     +293     
  Branches     8651     8713      +62     
==========================================
+ Hits        46293    46586     +293     
  Misses       3025     3025              
  Partials       70       70              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[kt3k]

JS array has pop, push, shift, and unshift, and I guess the engines do the similar optimization internally for those methods. How is the performance of this Deque compared to a native array?

[tomas-zijdemans]

JS array has pop, push, shift, and unshift, and I guess the engines do the similar optimization internally for those methods. How is the performance of this Deque compared to a native array?

Added benchmarks in the description

[kt3k]

Thanks for adding benchmarks!

Now Deque looks a meaningful addition. LGTM