data-structure-typed

English | 简体中文

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

!npm
!GitHub contributors
!npm package minimized gzipped size (select exports)
!GitHub top language
!GITHUB Star
!eslint
!NPM
!npm

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

$3

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

$3

``javascript
// ❌ 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 ❌
`

`javascript
// ✅ 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

$3

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

`javascript
// 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
`

$3

Full generics and strict TypeScript support out of the box.

`typescript
const tree = new RedBlackTree();
tree.set(1, 'Alice');
tree.set(2, 'Bob');

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

$3

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

`javascript
// 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

`bash
pnpm add data-structure-typed
`

`bash
npm i data-structure-typed --save
`

`bash
yarn add data-structure-typed
`

$3

Use only what you need:

`bash
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

$3

`typescript
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);
`

$3

`typescript
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' }
`

$3

`typescript
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

$3

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

$3

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

$3

`typescript
class LRUCache {
private cache = new Map();
private order = new DoublyLinkedList();

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)!;
}
}
`

$3

`typescript

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;

constructor(initialPlayers: Player[]) {
this.byScore = new RedBlackTree(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): (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)));
`

$3

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

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

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

👉 More examples in GUIDES.md

---

🎯 Use Cases by Industry

$3

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

$3

- Player leaderboards
- Enemy priority queues
- Game event scheduling

$3

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

$3

- Patient priority queues
- Appointment scheduling
- Medical record organization

$3

- 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

$3

`bash
npm i data-structure-typed
`

$3

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

$3

`typescript
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

$3

👉 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

`
README.md (this file)
docs/
├── 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 →