🧪 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