DEV Community: Ruiwen Zeng

Beyond Array and Map: What `data-structure-typed` Brings to TypeScript Collections

Ruiwen Zeng — Sun, 22 Mar 2026 04:49:28 +0000

When TypeScript developers need a collection, we almost always start with Array, Map, or Set.

That works for a lot of code.

But once your workload becomes queue-heavy, continuously ordered, range-oriented, or built around real domain objects, those built-in structures start to feel stretched. That is the gap data-structure-typed is designed to fill.

This library is not just “a bunch of data structures for TypeScript.”

What makes it interesting is that it tries to bring a more complete collections world into TS/JS, while still keeping the API and usage style close to the way JavaScript developers already think.

If you want to browse the project first, here are the most useful entry points:

In other words, it is not only about having trees, heaps, deques, and tries.

It is about making them feel usable in everyday TypeScript.

1. A Uniform API Matters More Than People Think

One of the biggest problems with many data structure libraries is not missing functionality.

It is API fragmentation.

Every structure has its own style. Every structure wants you to learn a different mental model. That makes the whole library feel like a bag of unrelated utilities instead of a coherent collections toolkit.

data-structure-typed goes in the opposite direction. It tries to keep familiar JavaScript collection operations available across structures, so developers do not have to mentally switch gears every time they move from one collection to another. The project's Reference and Architecture pages make this design direction especially clear.

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

const deque = new Deque([1, 2]);
deque.push(3);
deque.unshift(0);
deque.pop();
deque.shift();

const list = new DoublyLinkedList([1, 2]);
list.push(3);
list.unshift(0);
list.pop();
list.shift();

That may look simple, but it is an important design choice.

The point is not that every structure is identical.

The point is that advanced collections should not feel like an entirely different language.

You can also try this style directly in the official playgrounds:

2. Advanced Collections Should Still Support Expressive Code

A lot of data structure libraries are fine when all you need is add, delete, and has.

But real application code usually wants more than that.

It wants to filter, transform, and aggregate data without dropping back to raw arrays every time.

That is why one of my favorite parts of data-structure-typed is that advanced collections can still participate in expressive, everyday data-processing code. The Reference and Guides are especially good places to explore this style further.

For example, a TreeSet can still be used in a very JavaScript-friendly chain:

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

const users = new TreeSet([
  { id: 1, name: 'Alice', age: 24 },
  { id: 2, name: 'Bob', age: 31 },
  { id: 3, name: 'Charlie', age: 29 },
  { id: 4, name: 'David', age: 22 },
], {
  comparator: (a, b) => a.age - b.age
});

const totalAge = users
  .filter(user => user.age > 26)
  .map(
    user => ({ ...user, senior: user.age >= 30 }),
    { comparator: (a, b) => a.age - b.age }
  )
  .reduce((sum, user) => sum + user.age, 0);

console.log(totalAge); // 60

This is a small example, but it shows something important.

The impressive part is not just that filter, map, and reduce exist.

The impressive part is that they exist on a tree-based collection without forcing you back into arrays first.

That is a very different developer experience from libraries where advanced structures only feel usable at the lowest operational level.

3. Collections Should Plug Into JavaScript, Not Fight It

Another major strength of this library is that the structures do not feel isolated from the language.

If a collection works naturally with JavaScript’s iteration model, it becomes much easier to adopt in real code. You can loop it, spread it, convert it, and pass it around using familiar syntax. This is one of the design ideas called out in the project's Architecture notes and Concepts / theory guide.

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

const tree = new TreeSet([3, 1, 2]);

const arr = [...tree];
const copy = Array.from(tree);

for (const value of tree) {
  console.log(value);
}

const nativeSet = new Set(tree);

console.log(arr);       // [1, 2, 3]
console.log(copy);      // [1, 2, 3]
console.log(nativeSet); // Set { 1, 2, 3 }

This kind of zero-friction interoperability matters a lot.

It means advanced collections are not “special objects you only touch in special ways.”

They behave like natural extensions of JavaScript itself.

4. Stop Using Arrays as Queues

One of the clearest examples in the whole library is Deque.

This is not just a case of “here is another container.”

It exposes a very common mistake in TS/JS codebases: using arrays as queues.

A lot of code ends up looking like this:

const queue = [1, 2, 3, 4, 5];
queue.shift();
queue.push(6);

That works functionally, but it is a poor abstraction for queue-heavy workloads.

A Deque makes the intention clearer and gives you a collection built for front and back operations:

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

const queue = new Deque([1, 2, 3, 4, 5]);
queue.shift();
queue.push(6);

That is why this example is stronger than it looks.

It does not just say, “Use this because it is faster.”

It says, “A queue is not just an array that happens to call shift().”

That is the kind of conceptual correction good data structure libraries should make.

If you want the exact numbers and benchmark breakdowns, go straight to the official benchmark report and the project’s performance documentation.

5. Some Collections Should Stay Ordered All the Time

Another place where built-in collections start to show their limits is ordered data.

A lot of developers instinctively reach for an array and call sort() whenever they need ranked results. But some datasets are not meant to be re-sorted occasionally. They are meant to stay ordered as updates happen.

That is where a tree-backed ordered collection becomes much more natural.

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

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

for (const [score, player] of leaderboard) {
  console.log(`${player}: ${score}`);
}

leaderboard.delete(85);
leaderboard.set(95, 'Bob');

const topPlayers = [...leaderboard.values()].reverse().slice(0, 3);
console.log(topPlayers);

The point of this example is not just that trees can sort.

It is that a leaderboard is not really “an array that I sort from time to time.”

It is a collection whose order should be maintained continuously.

That is a much better fit for workloads like rankings, scoreboards, time-series windows, and other order-sensitive systems. The project’s guides and reference have more examples in this direction.

6. Ordered Collections Need More Than Basic CRUD

What I also like about data-structure-typed is that its ordered collections are not limited to basic membership operations.

Once you move into ordered data, you often want range-friendly, navigable semantics:

nearest greater value
nearest smaller value
boundary lookups
range extraction

That is the kind of collection power TS/JS developers often end up rebuilding manually.

A TreeSet makes these operations part of the collection model itself:

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

const scores = new TreeSet([1, 3, 5, 7, 9]);

console.log(scores.ceiling(4)); // 5
console.log(scores.floor(4));   // 3
console.log(scores.higher(5));  // 7
console.log(scores.lower(5));   // 3

console.log(scores.rangeSearch([3, 7])); // [3, 5, 7]

This is where the library starts to feel less like “extra containers” and more like a real collections toolkit.

Because once a collection is ordered, those ordered semantics should be first-class. If that part interests you, the API reference is the best next stop.

7. Real Domain Objects Should Be Able to Live Directly Inside the Collection

Another thing I think this library does especially well is handling real business objects, not just primitives.

A lot of demos in data structure libraries stop at number, string, or simple key-value pairs. That is fine for teaching basics, but real applications usually work with richer domain objects: players, products, users, tasks, transactions, events.

data-structure-typed gives you ways to map those objects into collection structure directly, instead of forcing you to flatten everything ahead of time.

For example:

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

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

const players: Player[] = [
  { id: 1, name: 'Alice', score: 100 },
  { id: 2, name: 'Bob', score: 85 },
  { id: 3, name: 'Charlie', score: 92 }
];

const leaderboard = new RedBlackTree<number, Player, Player>(players, {
  isMapMode: false,
  toEntryFn: (player) => [player.score, player]
});

for (const player of leaderboard.values()) {
  console.log(player.name, player.score);
}

Or with TreeSet, where domain objects can be transformed into ordered set elements:

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

interface User {
  id: number;
  name: string;
}

const users: User[] = [
  { id: 3, name: 'Charlie' },
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' }
];

const userIds = new TreeSet<number, User>(users, {
  toElementFn: user => user.id
});

console.log([...userIds]); // [1, 2, 3]

This matters because it makes the library feel much more usable in actual applications.

It is not just “collections for demos.”

It is collections that can sit closer to real domain models.

You can dig deeper into these patterns in the real-world guides and reference documentation.

What Makes This Interesting to Me

What stands out to me about data-structure-typed is not just that it has many structures.

It is that it combines several things that are rarely strong at the same time:

a more complete collections model for TypeScript
APIs that still feel familiar to JavaScript developers
expressive collection-level operations
natural interoperability with the language
ordered and navigable collection semantics
support for real domain objects, not just primitives

That combination is what gives the library its identity.

It is not just trying to bring classic data structures into TypeScript.

It is trying to make them feel like they actually belong there.

Final Thoughts

For me, the most interesting part of data-structure-typed is not any single container.

It is the idea that TypeScript developers should not have to choose between:

staying inside familiar JavaScript patterns, or
reaching for richer collection abstractions

A good collections library should let you have both.

That is what this project is trying to do.

If you want to explore further, here are the best places to continue:

data-structure-typed: A Modern Data Structures Library for TypeScript

Ruiwen Zeng — Mon, 02 Mar 2026 08:18:36 +0000

Why I Built data-structure-typed: A Modern Data Structures Library for TypeScript

TL;DR: After years of using various data structure libraries in JavaScript/TypeScript, I built one that prioritizes type safety, native API familiarity, and performance. Here's what I learned.

The Problem

If you've worked on algorithm-heavy TypeScript projects, you've probably faced this dilemma:

Native JS only gives you Array, Map, Set, and Object — no trees, no heaps, no graphs
Existing libraries often have inconsistent APIs, poor TypeScript support, or expose too many internals

I wanted something that felt like a natural extension of JavaScript's built-in collections — with the same API patterns, full type safety, and solid performance.

What is data-structure-typed?

It's a comprehensive collection of data structures for JavaScript and TypeScript:

Binary Trees: BST, AVL Tree, Red-Black Tree, TreeMap, TreeSet
Heaps: Min/Max Heap, Priority Queue
Graphs: Directed, Undirected (with Dijkstra, Bellman-Ford, Floyd-Warshall, etc.)
Linear: Queue, Deque, Stack, Singly/Doubly Linked List
Others: Trie, HashMap, and more

Design Philosophy

1. Native API Familiarity

If you know JavaScript's Map and Set, you already know how to use TreeMap and TreeSet:

import { TreeMap, TreeSet } from 'data-structure-typed';

// Works just like native Map, but keys are always sorted
const map = new TreeMap<string, number>();
map.set('banana', 3);
map.set('apple', 1);
map.set('cherry', 2);

console.log([...map.keys()]); // ['apple', 'banana', 'cherry'] - sorted!

// Works just like native Set, but elements are always sorted
const set = new TreeSet<number>([3, 1, 4, 1, 5, 9, 2, 6]);
console.log([...set]); // [1, 2, 3, 4, 5, 6, 9] - sorted & deduplicated!

2. Full TypeScript Support

Everything is fully typed with generics. No any types leaking through:

interface User {
  id: number;
  name: string;
  score: number;
}

// Type-safe priority queue
const leaderboard = new MaxPriorityQueue<User>({
  comparator: (a, b) => a.score - b.score
});

leaderboard.add({ id: 1, name: 'Alice', score: 100 });
leaderboard.add({ id: 2, name: 'Bob', score: 150 });

const top = leaderboard.poll(); // Type: User | undefined
console.log(top?.name); // 'Bob'

3. Navigation Methods (Java-style)

TreeMap and TreeSet include Java's NavigableMap/NavigableSet methods:

const prices = new TreeMap<number, string>([
  [10, 'cheap'],
  [50, 'medium'],
  [100, 'expensive'],
  [500, 'luxury']
]);

prices.floor(75);    // [50, 'medium'] - largest key ≤ 75
prices.ceiling(75);  // [100, 'expensive'] - smallest key ≥ 75
prices.lower(50);    // [10, 'cheap'] - largest key < 50
prices.higher(50);   // [100, 'expensive'] - smallest key > 50

4. Functional Methods

All collections support map, filter, reduce, forEach:

const numbers = new TreeSet([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

const evens = numbers.filter(n => n % 2 === 0);
console.log([...evens]); // [2, 4, 6, 8, 10]

const doubled = numbers.map(n => n * 2);
console.log([...doubled]); // [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

Performance

Under the hood, TreeMap and TreeSet use Red-Black Trees. Here's how they compare to the popular js-sdsl library:

Operation	data-structure-typed	js-sdsl
set (100K)	1.00x	1.54x slower
get (100K)	1.00x	1.02x
delete (100K)	1.22x	1.00x
iterate (100K)	1.00x	2.15x slower

Benchmarks run on Node.js 22, Apple M1

The key win is iteration — we're 2x faster because we use an optimized iterator implementation.

Real-World Use Cases

LeetCode / Competitive Programming

// LeetCode 729: My Calendar I
class MyCalendar {
  private bookings = new TreeMap<number, number>();

  book(start: number, end: number): boolean {
    const prev = this.bookings.floor(start);
    const next = this.bookings.ceiling(start);

    if (prev && prev[1] > start) return false;
    if (next && next[0] < end) return false;

    this.bookings.set(start, end);
    return true;
  }
}

Task Scheduling

const taskQueue = new MinPriorityQueue<Task>({
  comparator: (a, b) => a.priority - b.priority
});

// Add tasks
taskQueue.add({ id: 1, priority: 3, name: 'Low priority' });
taskQueue.add({ id: 2, priority: 1, name: 'Urgent!' });
taskQueue.add({ id: 3, priority: 2, name: 'Medium' });

// Process in priority order
while (!taskQueue.isEmpty()) {
  const task = taskQueue.poll()!;
  console.log(`Processing: ${task.name}`);
}
// Output: Urgent! → Medium → Low priority

Graph Algorithms

const graph = new DirectedGraph<string, number>();

graph.addVertex('A');
graph.addVertex('B');
graph.addVertex('C');
graph.addEdge('A', 'B', 1);
graph.addEdge('B', 'C', 2);
graph.addEdge('A', 'C', 5);

const { distMap } = graph.dijkstra('A');
console.log(distMap.get('C')); // 3 (A→B→C is shorter than A→C)

Installation

npm install data-structure-typed

Or install individual packages for smaller bundles:

npm install tree-map-typed    # Just TreeMap
npm install heap-typed        # Just Heap/PriorityQueue

What's Next?

Performance improvements (we're always benchmarking)
More LeetCode-style examples in docs
Interactive playground

Why Complex Visualizations Need Algorithms: Analyzing Grafana Forks' Dependencies

Ruiwen Zeng — Mon, 05 Jan 2026 06:09:21 +0000

Subtitle: When Array.filter isn't enough—how specialized data structures power the next generation of frontend observability.

Front-end development has evolved. We are no longer just manipulating DOM elements; we are building full-blown data processing engines in the browser.

Recently, I noticed an interesting pattern while analyzing the dependency graphs of several advanced Grafana forks (including AI-enhanced versions and complex topology visualizers). They all shared a common deviation from the standard React ecosystem: they abandoned native JavaScript Arrays for specialized data structures.

Why? Because at the scale of industrial monitoring, O(n) is the enemy.

The "60 FPS" Bottleneck

Imagine a Service Dependency Graph visualizing 5,000 microservices. You need to highlight the "Critical Path" in real-time as the user hovers over a node.

The Naive Approach

Store edges in a standard JavaScript Array. Iterate through the array to find connections every time the user moves their mouse.

Performance: $O(V+E)$ per frame.
Result: With 5,000 nodes, the browser main thread blocks, causing significant UI stutter (jank).

The Specialized Approach

Use a Directed Graph implementation with Adjacency Lists or Adjacency Matrices.

Performance: $O(1)$ lookups for neighbors.
Result: Silky smooth interactions, regardless of dataset size.

This is why libraries like data-structure-typed are quietly appearing in the package.json of high-performance tools. It’s not just about syntax; it’s about physics.

Case Study: The "Top K" Problem in Logs

Another common scenario in observability is live-streaming logs to find the "Top 10 Errors" or "Slowest Requests" in real-time.

Native JS: The Sorting Trap

// This runs for EVERY new log entry
logs.push(newLog);
logs.sort((a, b) => b.latency - a.latency);
const top10 = logs.slice(0, 10);

Cost: $O(N \log N)$ for every single new log entry.
Impact: Massive Garbage Collection (GC) pressure and CPU spikes. As logs grows to 100k+, the browser will freeze.

The Min-Heap Solution

Instead of sorting the entire array, we maintain a Min-Heap of fixed size 10.

Compare the new log's latency with the heap's root (minimum of the top 10).
If it's larger, replace the root and re-heapify.

Cost: $O(\log K)$ (where K=10).
Impact: The difference between processing 100,000 logs with sorting vs. Heaps is the difference between a frozen browser and a responsive dashboard.

Why Standard Libraries Fall Short

JavaScript (and by extension TypeScript) is one of the few major languages without a standard library for advanced data structures.

Python: Has heapq and collections.
Java: Has PriorityQueue, TreeMap, LinkedList.
C++: Has std::priority_queue, std::set.
JavaScript: Has Array, Map, Set. That's it.

When frontend engineers need to solve "LeetCode Hard" problems in production—like calculating the shortest path in a network topology (Dijkstra) or managing task priority queues—they are often forced to write buggy, unoptimized implementations from scratch.

Conclusion

As frontend applications invade the territory of data science and systems engineering, our toolset must adapt. Native Map, Set, and Array are great generalists, but for specialized tasks—like those found in Grafana's heavy-lifting forks—we need specialized tools.

If you are building complex visualizations or processing heavy data streams in the client, stop sorting arrays. Start using Trees and Heaps.

Explore the library mentioned in this analysis: data-structure-typed on GitHub