ts-collections

332/332 tests passing. Comprehensive test coverage for all implementations.

Coming from Java?

You'll feel right at home! Type safety works exactly like Java:

// Java
List<Integer> list = new ArrayList<>();
list.add(1);
list.add("text"); // ❌ Compile error

// TypeScript with ts-collections
const list = new ArrayList<number>();
list.add(1);
list.add("text" as any); // ❌ Runtime error (automatic!)

📖 Java Migration Guide →

📚 API Overview

Core Interfaces

Available Implementations

Native JavaScript Equivalents

This table helps developers quickly map ts-collections data structures to familiar native JavaScript alternatives.

Architecture

graph TD
    A[Collection Interface] --> B[List]
    A --> C[Set]
    A --> D[Queue]
    E[Map Interface] --> F[HashMap]
    B --> G[ArrayList]
    B --> H[LinkedList]
    C --> I[HashSet]
    D --> J[LinkedQueue]

📦 Installation

npm i @karelaking/ts-collections

pnpm i @karelaking/ts-collections

# Using pnpm
pnpm add ts-collections

# Using yarn
yarn add ts-collections

🚀 Quick Start

Lists - Ordered Collections

import { ArrayList } from "ts-collections";

const list = new ArrayList<number>();
list.add(10);
list.add(20);
list.add(30);

console.log(list.get(0)); // 10
console.log(list.size()); // 3
list.removeAt(1); // [10, 30]

Sets - Unique Elements

import { HashSet } from "ts-collections";

const set = new HashSet<string>();
set.add("apple");
set.add("banana");
set.add("apple"); // Duplicate ignored

console.log(set.size()); // 2
console.log(set.contains("apple")); // true

Maps - Key-Value Pairs

import { HashMap } from "ts-collections";

const map = new HashMap<string, number>();
map.put("Alice", 25);
map.put("Bob", 30);

console.log(map.get("Alice")); // 25
console.log(map.containsKey("Bob")); // true

Queues - FIFO Processing

import { LinkedQueue } from "ts-collections";

const queue = new LinkedQueue<string>();
queue.offer("Task 1");
queue.offer("Task 2");

console.log(queue.poll()); // "Task 1"
console.log(queue.peek()); // "Task 2"

Iterators - Traverse Elements

import { ArrayList } from "ts-collections";

const list = new ArrayList<number>();
list.add(1);
list.add(2);
list.add(3);

const iterator = list.iterator();
while (iterator.hasNext()) {
  console.log(iterator.next());
}

Priority Queues - Sorted Processing

import { PriorityQueue } from "ts-collections";

const priorities = new PriorityQueue<number>();
priorities.offer(5);
priorities.offer(1);
priorities.offer(3);

console.log(priorities.poll()); // 1
console.log(priorities.peek()); // 3

Tree Maps - Sorted Key Order

import { TreeMap } from "ts-collections";

const sortedMap = new TreeMap<string, number>();
sortedMap.put("c", 3);
sortedMap.put("a", 1);
sortedMap.put("b", 2);

console.log(sortedMap.keys()); // ["a", "b", "c"]

Tree Sets - Sorted Unique Values

import { TreeSet } from "ts-collections";

const sortedSet = new TreeSet<number>();
sortedSet.add(3);
sortedSet.add(1);
sortedSet.add(2);

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

Double-Ended Queues - Front and Back Operations

import { LinkedDeque } from "ts-collections";

const deque = new LinkedDeque<string>();
deque.addFirst("middle");
deque.addFirst("front");
deque.addLast("back");

console.log(deque.pollFirst()); // "front"
console.log(deque.pollLast()); // "back"

FAQ

Why use ts-collections instead of native JavaScript collections?

ts-collections provides a broader set of data structures and stronger collection APIs than native arrays, maps, and sets. It adds type-safe behavior, consistent method names, and specialized implementations like priority queues and sorted trees.

Does runtime validation affect performance?

Runtime validation can add a small cost on inserts, but it helps catch invalid values early and keeps collections reliable. The library is designed so this overhead is minimal for most typical use cases.

Can runtime validation be customized or disabled?

Yes — runtime validation can be customized with a Zod schema or a custom validator, and it can be disabled by setting strict: false. This makes it easy to choose either the safety of runtime checks or the speed of unchecked collections.

Which collection should I choose for my use case?

Use ArrayList for ordered lists and frequent iteration, HashMap for key-value lookups, and HashSet for unique values. Choose LinkedQueue for FIFO queues, PriorityQueue for priority-based processing, and TreeMap/TreeSet when you need sorted data and ordered traversal.

Is the library inspired by Java Collections Framework?

Yes, the library follows Java-style collection interfaces and naming patterns while remaining idiomatic to TypeScript. It combines familiar Java concepts with TypeScript runtime safety and native JavaScript interop.

💡 Common Use Cases

import { ArrayList } from "ts-collections";

interface Product {
  id: string;
  name: string;
  price: number;
}

class ShoppingCart {
  private items = new ArrayList<Product>();

  addItem(product: Product): void {
    this.items.add(product);
  }

  getTotalPrice(): number {
    return this.items.toArray().reduce((sum, item) => sum + item.price, 0);
  }
}

const cart = new ShoppingCart();
cart.addItem({ id: "1", name: "Laptop", price: 999 });
console.log(cart.getTotalPrice()); // 999

import { HashMap } from "ts-collections";

interface Session {
  userId: string;
  loginTime: Date;
}

class SessionManager {
  private sessions = new HashMap<string, Session>();

  createSession(userId: string): string {
    const sessionId = this.generateId();
    this.sessions.put(sessionId, { userId, loginTime: new Date() });
    return sessionId;
  }

  getSession(sessionId: string): Session | undefined {
    return this.sessions.get(sessionId);
  }
}

import { LinkedQueue } from "ts-collections";

const taskQueue = new LinkedQueue<string>();

// Add tasks
taskQueue.offer("Process payment");
taskQueue.offer("Send email");
taskQueue.offer("Update inventory");

// Process tasks
while (taskQueue.size() > 0) {
  const task = taskQueue.poll();
  console.log(`Processing: ${task}`);
}

import { HashSet } from "ts-collections";