README: data-structure-typed Library

A comprehensive TypeScript data structures library with production-ready implementations.

📚 Installation • Quick Start • Full Docs • API Reference • Playground • Examples

---

Table of Contents

1. Who Should Use This?
2. Why Not Just Array or Map?
3. Key Features
4. Installation
5. Quick Start
6. Data Structures
7. Documentation

---

🎯 Who Should Use This?

If you are building ranked collections, scheduling queues, or sorted data structures in TypeScript,
consider data-structure-typed instead of hand-rolled Arrays or Maps.

Perfect for:

• Leaderboards & Rankings — Maintain top-K efficiently without repeated sorting
• Task Scheduling — Priority queues, ordered execution, time-based operations
• Real-Time Dashboards — Grafana-style workloads with instant lookups
• Time-Series Data — Sorted insertion + fast range queries
• Search & Autocomplete — Prefix matching at scale
• Graph Problems — Pathfinding, cycle detection, topological sorting

---

⚡ Why Not Just Array or Map?

Use Case	Array	Map	data-structure-typed
Sorted Lookup	❌ O(n)	❌ Unordered	✅ O(log n)
Insert at Position	❌ O(n) shift	❌ No position	✅ O(log n)
Leaderboard Top-K	❌ Re-sort O(n log n)	❌ Manual sort	✅ Instant
Remove from Front	❌ O(n)	❌ No dequeue	✅ O(1)
Prefix Search	❌ O(n*m)	❌ Not applicable	✅ O(m + k)
Familiar API	✅ Yes	✅ Yes	✅ Same

Real-World Pain Point

// ❌ WITHOUT data-structure-typed
const queue = [1, 2, 3, ..., 100000
]
;
for (let i = 0; i < 100000; i++) {
  queue.shift();  // O(n) - Reindexes EVERY element!
}
// Time: 2829ms ❌

// ✅ WITH data-structure-typed (Deque)
const deque = new Deque([1, 2, 3, ..., 100000])
;
for (let i = 0; i < 100000; i++) {
  deque.shift();  // O(1) - Just moves a pointer
}
// Time: 5.83ms ✅
// **484x faster!**

---

🚀 Performance (TL;DR)

• 10–40% faster than common JS implementations in hot paths

  • Array.sort() O(n log n) → TreeSet O(log n) insertion
  • Repeated Array.shift() O(n) → Queue O(1)
  • Manual index tracking → RB-Tree auto-balance

• Optimized for V8 JIT (Node.js 18+, modern browsers)

• Tree-shakable ESM / CJS / legacy builds

📊 Full benchmarks →

---

✨ Key Features

🏠 Uniform API

Don't learn new APIs. Just use push, pop, map, filter, and reduce everywhere.

// All linear structures use THE SAME 4 methods
const deque = new Deque([1, 2, 3]);
const queue = new Queue([1, 2, 3]);
const doublyLinkeList = new DoublyLinkedList([1, 2, 3]);
const singlyLinkedList = new SinglyLinkedList([1, 2, 3]);

// They ALL support:
structure.push(item);          // Add to end
structure.pop();               // Remove from end
structure.shift();             // Remove from start
structure.unshift(item);       // Add to start

🛡️ Type Safe

Full generics and strict TypeScript support out of the box.

const tree = new RedBlackTree<number, string>();
tree.set(1, 'Alice');
tree.set(2, 'Bob');

// Type-safe access
const value = tree.get(1);  // Type: string | undefined

✨ Zero Friction

Works everywhere. Spread it [...], loop it for..of, convert it instantly.

// All data structures work with iterator protocol
const tree = new RedBlackTree([5, 2, 8]);
const sorted = [...tree];              // Spread operator
for (const item of tree) {
}           // for...of loop
const set = new Set(tree);             // Set constructor

---

📥 Installation

pnpm add data-structure-typed

npm i data-structure-typed --save

yarn add data-structure-typed

Individual Packages

Use only what you need:

pnpm add heap-typed deque-typed red-black-tree-typed

---

💡 When Should I Consider This Library?

✅ When you need:

• Top-K / Leaderboard queries without repeated sorting
• Insertion order + lookup performance simultaneously
• Priority queues with fast position-based access
• Time-series data with range queries
• Red-Black Tree / Heap performance without learning new APIs

✅ When your current code has:

• array.sort() in hot paths (request handlers, loops)
• Manual index tracking after insertions
• Array.shift() on large lists (queues)
• Custom sorting logic you repeat across files
• Map that needs to be ordered

---

🚀 Quick Start: 30 Seconds

Leaderboard (Ranked Collections)

import { RedBlackTree } from 'data-structure-typed';

const leaderboard = new RedBlackTree([
  [100, 'Alice'],
  [85, 'Bob'],
  [92, 'Charlie']
]);

// Get sorted scores (automatically maintained!)
for (const [score, player] of leaderboard) {
  console.log(`${player}: ${score}`);
}
// Output:
// Alice: 100
// Charlie: 92
// Bob: 85

// Update score
leaderboard.delete(85);
leaderboard.set(95, 'Bob');  // O(log n)

// Query top players
const topPlayers = [...leaderboard.values()].reverse().slice(0, 3);

Task Queue (Scheduling)

import { MaxPriorityQueue } from 'data-structure-typed';

const taskQueue = new MaxPriorityQueue<{priority: number; task: string}>([], {
  comparator: (a, b) => b.priority - a.priority
});

taskQueue.add({ priority: 5, task: 'Email' });
taskQueue.add({ priority: 9, task: 'Alert' });  // Instant priority handling

const nextTask = taskQueue.poll();  // { priority: 9, task: 'Alert' }

Fast Queue (FIFO)

import { Deque } from 'data-structure-typed';

const queue = new Deque([1, 2, 3, 4, 5]);
queue.shift();  // Remove from front: O(1) not O(n)
queue.push(6);  // Add to back: O(1)

---

📊 Data Structures Available

Structure	Use Case	Time Complexity	NPM
RedBlackTree	Sorted collections, range queries	O(log n)	npm
Heap / PriorityQueue	Task scheduling, top-K elements	O(log n)	npm
Deque	Fast front/back operations	O(1)	npm
Trie	Autocomplete, prefix search	O(m+k)	npm
DirectedGraph	Pathfinding, DAG algorithms	O(V+E)	npm
Stack	Undo/redo, expression parsing	O(1)	npm
LinkedList	Dynamic sizing, no index shift	O(1)*	npm
AVLTree	Stricter balance than RB-Tree	O(log n)	npm

👉 See all 20+ structures →

---

📖 Documentation

For Different Use Cases

Your Goal	Start Here	Next Steps
Learn concepts	CONCEPTS.md	GUIDES.md
Use in my project	GUIDES.md	REFERENCE.md
Look up API	REFERENCE.md	PERFORMANCE.md
Performance questions	PERFORMANCE.md	ARCHITECTURE.md
Framework integration	INTEGRATIONS.md	GUIDES.md
Understand design	ARCHITECTURE.md	CONCEPTS.md

Documentation Files

1. CONCEPTS.md - Core Fundamentals & Theory

• Big Three Concepts (BST, Balanced Trees, Heap)
• 13 Plain Language Explanations
• Iterator Protocol Design
• 5 Comparisons with Native JavaScript
• Complete Decision Guide

2. REFERENCE.md - Complete API & Data Structures

• Quick Reference Table
• All 20+ Structures with Examples
• CRUD Operations
• Common Methods
• TypeScript Support

3. ARCHITECTURE.md - Design & Implementation

• Design Philosophy & Principles
• 3 Pain Points Solved
• Why Deque is 484x Faster
• Iterator Protocol Design
• Self-Balancing Strategy
• V8 JIT Optimizations

4. PERFORMANCE.md - Benchmarks & Comparisons

• Performance Summary
• 3 Real-World Scenarios
• Detailed Benchmarks
• When to Use What
• Optimization Tips

5. GUIDES.md - Real-World Examples

• 4 Design Patterns
• 5 Production Code Examples
• Common Mistakes
• Best Practices

6. INTEGRATIONS.md - Framework Integration

• React Integration (State Management, Leaderboard)
• Express Integration (LRU Cache, Rate Limiting)
• Nest.js Integration (Ranking Service, Task Queue)
• TypeScript Configuration

---

💻 Real-World Examples

LRU Cache

class LRUCache<K, V> {
  private cache = new Map<K, V>();
  private order = new DoublyLinkedList<K>();

  get(key: K): V | null {
    if (!this.cache.has(key)) return null;
    // Move to end (recently used)
    // Efficient with O(1) operations
    return this.cache.get(key)!;
  }
}

Leaderboard

type Player = {
  id: string;
  name: string;
  score: number;
};

const seedPlayers: Player[] = [
  { id: 'player_01HZX4E8Q2K8Y3J9M7T1A6B3C4', name: 'Pablo', score: 65 },
  { id: 'player_01HZX4E9R6V2D8K1P0N5S4T7U8', name: 'Bunny', score: 10 },
  { id: 'player_01HZX4EA3M9Q7W1E2R8T6Y5U0I', name: 'Jeff', score: 99 },
];

class ScoreLeaderboard {
  private readonly byScore: RedBlackTree<number, Player, Player>;

  constructor(initialPlayers: Player[]) {
    this.byScore = new RedBlackTree<number, Player, Player>(initialPlayers, {
      isMapMode: false,// Use "node value" storage rather than Map-style.
      toEntryFn: (player) => [player.score, player], // Convert a player object into the tree entry: key = score, value = player.
    });
  }

  /**
   * Returns players whose scores fall within the given range.
   * Supports either a tuple [min, max] or a Range object for inclusive/exclusive bounds.
   */
  public findPlayersByScoreRange(range: [number, number] | Range<number>): (Player | undefined)[] {
    return this.byScore.rangeSearch(range, (node) => node.value);
  }
  
  public upsertPlayer(player: Player) {
    return this.byScore.set(player.score, player);
  }
}

const leaderboard = new ScoreLeaderboard(seedPlayers);

console.log(leaderboard.findPlayersByScoreRange([65, 100]));

leaderboard.upsertPlayer({
  id: 'player_01HZX4EB7C4N2M9Q8R1T3Y6U5I',
  name: 'Alex',
  score: 80,
});

console.log(leaderboard.findPlayersByScoreRange(new Range(65, 100, true, true)));

Message Queue

type Message = {
  id: string;
  type: string;
  payload: unknown;
  priority: 'urgent' | 'normal';
  createdAt: number;
  retryCount?: number;
};

class MessageQueue {
  private urgent = new Deque<Message>();
  private normal = new Deque<Message>();

  dequeue(): Message | null {
    return this.urgent.shift() || this.normal.shift();
  }
}

👉 More examples in GUIDES.md

---

🎯 Use Cases by Industry

📊 Finance

• Price-sorted order book
• Real-time portfolio rankings
• Option chain ordering

🎮 Gaming

• Player leaderboards
• Enemy priority queues
• Game event scheduling

📱 Social Media

• Trending posts (top-K)
• Feed ordering
• Notification scheduling

🏥 Healthcare

• Patient priority queues
• Appointment scheduling
• Medical record organization

🛒 E-commerce

• Product price ranges
• Inventory management
• Order scheduling

---

✨ Why Developers Love This

Pain Point	Solution
Repeated sorting slowing down code	TreeSet auto-maintains order
Array.shift timeout in loops	Deque O(1) shift instead of O(n)
Learning different APIs	All structures use push/pop/shift/unshift
Type safety nightmares	Full TypeScript generics support
Browser compatibility issues	Works everywhere: Node, browsers, CDN

---

📦 What You Get

✅ 20+ data structures (production-ready)
✅ 50+ code examples (real-world patterns)
✅ Full TypeScript support (strict typing)
✅ Performance benchmarks (484x speedups)
✅ Framework integrations (React, Express, Nest.js) ✅ 6 core documentation files (2500+ lines)

---

🚀 Getting Started

Step 1: Install

npm i data-structure-typed

Step 2: Import

import { RedBlackTree, Deque, MaxPriorityQueue } from 'data-structure-typed';

Step 3: Use

const tree = new RedBlackTree([5, 2, 8]);
console.log([...tree]);  // [2, 5, 8] - Automatically sorted!

Playground

🏃🏻‍♀️ Try it instantly:

• Node.js TypeScript
• Node.js JavaScript
• React TypeScript
• NestJS

Step 4: Learn More

👉 Check CONCEPTS.md for core concepts
👉 See GUIDES.md for production examples
👉 Read REFERENCE.md for complete API

---

📊 Comparison Chart

Need frequent head/tail operations?
  → Deque (O(1) shift/unshift/push/pop)

Need sorted + fast lookup?
  → RedBlackTree (O(log n) guaranteed)

Need highest/lowest priority?
  → Heap/PriorityQueue (O(log n) add/remove)

Need prefix/text matching?
  → Trie (O(m+k) where m=prefix)

Need graph operations?
  → DirectedGraph/UndirectedGraph

Otherwise?
  → Use Array (simplest case)

---

🤝 Contributing

Found a bug? Have suggestions? Open an issue

---

📄 License

MIT

---

📚 Full Documentation Structure

docs/
├── README.md (this file)
├── CONCEPTS.md (theory & fundamentals)
├── REFERENCE.md (API documentation)
├── ARCHITECTURE.md (design principles)
├── PERFORMANCE.md (benchmarks)
├── GUIDES.md (real-world examples)
└── INTEGRATIONS.md (framework guides)

---

🎓 Learn More

Just started? → Quick Start

Need concepts? → CONCEPTS.md

Want to build? → GUIDES.md

Need API? → REFERENCE.md

Curious about performance? → PERFORMANCE.md

Framework questions? → INTEGRATIONS.md

---

Ready to supercharge your TypeScript data structures? Get started now →