@contextjs/collections


> A set of object-oriented collection types for TypeScript, designed for clarity, safety, and predictability in modern applications.

Features

- Fully type-safe generic collections
- Well-known data structures designed with a consistent and type-safe API (List, Dictionary, Queue, Stack, HashSet)
- Consistent null handling for empty or missing values
- Clean and minimal runtime behavior
- Optional value equality comparison in HashSet
- Zero external dependencies, tested and production-ready

Installation

``bash
npm i @contextjs/collections
`

Quick Start

Jump to: API Reference • Design Notes • Testing

$3


This guide shows basic usage of all collection types in the @contextjs/collections package.

Dictionary

`ts
import { Dictionary } from '@contextjs/collections';

const dictionary = new Dictionary();

dictionary.set("apple", 1);
dictionary.set("banana", 2);

console.log(dictionary.get("apple")); // 1
console.log(dictionary.has("banana")); // true
console.log(dictionary.has("cherry")); // false

dictionary.delete("banana");
console.log(dictionary.count); // 1

dictionary.clear();
console.log(dictionary.count); // 0
`

HashSet

`ts
import { HashSet } from '@contextjs/collections';

type User = { id: number };

const users = new HashSet((a, b) => a.id === b.id);

users.add({ id: 1 });
users.add({ id: 2 });
users.add({ id: 1 }); // Duplicate by id, ignored

console.log(users.count); // 2
console.log(users.has({ id: 1 })); // true (based on comparer)
console.log(users.has({ id: 3 })); // false

users.remove({ id: 1 });
console.log(users.count); // 1
`

`ts
// Also works with primitives using default equality
const ids = new HashSet();
ids.add(1);
ids.add(1);
console.log(ids.count); // 1
`

List

`ts
import { List } from '@contextjs/collections';

const list = new List();

list.add("alpha");
list.add("beta");
list.add("gamma");

console.log(list.get(1)); // "beta"
console.log(list.count); // 3

list.remove(0); // removes "alpha"
console.log(list.get(0)); // "beta"

list.clear();
console.log(list.count); // 0
`

Queue

`ts
import { Queue } from '@contextjs/collections';

const queue = new Queue();

queue.enqueue("first");
queue.enqueue("second");

console.log(queue.peek); // "first"
console.log(queue.dequeue()); // "first"
console.log(queue.dequeue()); // "second"
console.log(queue.dequeue()); // null (empty)

queue.enqueue("third");
console.log(queue.count); // 1

queue.clear();
console.log(queue.isEmpty); // true
`

Stack

`ts
import { Stack } from '@contextjs/collections';

const stack = new Stack();

stack.push(10);
stack.push(20);

console.log(stack.current); // 20
console.log(stack.pop()); // 20
console.log(stack.pop()); // 10
console.log(stack.pop()); // null (empty)

stack.push(30);
console.log(stack.count); // 1

stack.clear();
console.log(stack.isEmpty); // true
`

API Reference

For detailed API documentation, please refer to the API Reference.

Design Notes

These collections are written in TypeScript-first style with predictable, runtime-safe behavior:

- null is returned instead of throwing when an item is missing.
- HashSet` supports structural equality with a custom comparer function.
- Internals are designed to be lightweight, avoiding unnecessary abstraction.

Testing

This package maintains full test coverage for:
- All public collection methods
- Edge behavior on underflow, removal, or clear
- Equality comparison logic
- Type safety and mutation guarantees