🧪 Alchemist Collections

A high-performance collections library for TypeScript, inspired by Java collections. Provides efficient and well-tested data structures for your TypeScript/JavaScript applications.

🚀 Features

• ✅ ArrayList - Dynamic list with optimized automatic growth
• ✅ HashMap - Hash table implementation with collision handling
• ✅ Type-safe with full TypeScript generics - Complete type inference and IDE support
• ✅ High performance - Optimized native methods (copyWithin, fill)
• ✅ Iterable - Compatible with for...of and spread operator
• ✅ Familiar interface - Methods similar to Java collections
• ✅ Fully tested - Complete test coverage
• ✅ Zero dependencies - Pure library with no external packages required

📦 Installation

npm install alchemist-collections

yarn add alchemist-collections

pnpm add alchemist-collections

🎯 Quick Start

ArrayList

import { ArrayList } from 'alchemist-collections';

// Create a list
const numbers = new ArrayList<number>();

// Add elements
numbers.add(10);
numbers.add(20);
numbers.add(30);

// Access elements
console.log(numbers.get(0)); // 10
console.log(numbers.size()); // 3

// Search elements
console.log(numbers.contains(20)); // true
console.log(numbers.indexOf(30)); // 2

// Modify elements
numbers.set(1, 25); // change index 1 to 25

// Insert at specific position
numbers.addAt(1, 15); // [10, 15, 20, 25, 30]

// Remove elements
numbers.remove(2); // remove at index 2

// Iterate
for (const num of numbers) {
  console.log(num);
}

// Convert to array
const arr = numbers.toArray();

// Clear list
numbers.clear();
console.log(numbers.isEmpty()); // true

HashMap

import { HashMap } from 'alchemist-collections';

// Create a map
const map = new HashMap<string, number>();

// Add key-value pairs
map.put('apple', 5);
map.put('banana', 3);
map.put('cherry', 8);

// Get values
console.log(map.get('apple')); // 5
console.log(map.size()); // 3

// Check if key exists
console.log(map.containsKey('banana')); // true

// Check if value exists
console.log(map.containsValue(3)); // true

// Get all keys
const keys = map.keys(); // ['apple', 'banana', 'cherry']

// Get all values
const values = map.values(); // [5, 3, 8]

// Get all entries
const entries = map.entries(); // [['apple', 5], ['banana', 3], ['cherry', 8]]

// Update a value
const oldValue = map.put('apple', 10); // returns 5

// Remove a key
const removed = map.remove('banana'); // returns 3

// Iterate
for (const [key, value] of map) {
  console.log(`${key}: ${value}`);
}

// Clear map
map.clear();
console.log(map.isEmpty()); // true

📚 Complete API

ArrayList

Constructor

// Default initial capacity (10)
const list = new ArrayList<string>();

// Specify initial capacity
const list = new ArrayList<string>(20);

Methods

Method	Description	Example
add(element: E): boolean	Adds element at the end	list.add('hello')
addAt(index: number, element: E): void	Adds element at specific position	list.addAt(0, 'first')
get(index: number): E	Gets element at index	list.get(0)
set(index: number, element: E): E	Sets element and returns previous	list.set(0, 'new')
remove(index: number): E	Removes and returns element	list.remove(0)
contains(element: E): boolean	Checks if element exists	list.contains('hello')
indexOf(element: E): number	Gets index of element	list.indexOf('hello')
size(): number	Returns number of elements	list.size()
isEmpty(): boolean	Checks if empty	list.isEmpty()
clear(): void	Removes all elements	list.clear()
toArray(): E[]	Converts to native array	const arr = list.toArray()

HashMap<K, V>

Constructor

// Default initial capacity (16)
const map = new HashMap<string, number>();

// Specify initial capacity
const map = new HashMap<string, number>(32);

Methods

Method	Description	Example
put(key: K, value: V): V | undefined	Adds/updates entry, returns old value	map.put('name', 'John')
get(key: K): V | undefined	Gets value for key	map.get('name')
remove(key: K): V | undefined	Removes and returns value	map.remove('name')
containsKey(key: K): boolean	Checks if key exists	map.containsKey('name')
containsValue(value: V): boolean	Checks if value exists	map.containsValue('John')
size(): number	Returns number of entries	map.size()
isEmpty(): boolean	Checks if empty	map.isEmpty()
keys(): K[]	Returns all keys	const keys = map.keys()
values(): V[]	Returns all values	const vals = map.values()
entries(): [K, V][]	Returns all key-value pairs	const entries = map.entries()
clear(): void	Removes all entries	map.clear()

💡 Advanced Examples

Working with objects

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

const users = new ArrayList<User>();

users.add({ id: 1, name: 'Alice' });
users.add({ id: 2, name: 'Bob' });

const user = users.get(0);
console.log(user.name); // Alice

Working with HashMap

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

const products = new HashMap<string, Product>();

// Add products
products.put('PROD001', { id: 'PROD001', name: 'Laptop', price: 999 });
products.put('PROD002', { id: 'PROD002', name: 'Mouse', price: 29 });

// Find a product
const product = products.get('PROD001');
if (product) {
  console.log(`${product.name}: $${product.price}`);
}

// Check inventory
console.log(products.size()); // 2

// List all product names
const names = products.values().map(p => p.name);
console.log(names); // ['Laptop', 'Mouse']

HashMap with number keys

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

// Spread
const arr = [...list]; // [1, 2, 3]

// Destructuring
const [first, second] = list; // first = 1, second = 2

Automatic capacity growth

const list = new ArrayList<number>(2);
console.log(list.size()); // 0 (initial capacity 2)

// Add more elements than capacity - grows automatically
for (let i = 0; i < 100; i++) {
  list.add(i);
}
console.log(list.size()); // 100

⚡ Performance

The library uses native optimizations:

• copyWithin() for efficient element movement in add/remove
• fill() for clearing elements in clear()
• Dynamic growth with 1.5x factor to minimize reallocations

Compared to native JavaScript arrays, ArrayList is ideal when you need:

• Frequent insert/remove operations at specific positions
• Type safety with TypeScript generics
• Familiar API for Java developers

🧪 Testing

Run tests:

npm run test

With coverage:

npm run test:coverage

📝 License

MIT © 2026

Legal

This project provides a TypeScript implementation of data structures inspired by the Java Collections Framework.

Java and JDK are trademarks or registered trademarks of Oracle and/or its affiliates.

This project is not affiliated with, endorsed by, or sponsored by Oracle.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

⚠️ Note: This library is currently in Alpha. Interfaces may change, and I am actively working on adding new structures