feat: add custom HashMap implementation with resizing, collision handling, and tests

This PR adds a complete beginner-friendly HashMap implementation from scratch, following The Odin Project’s assignment.
It includes a hash function, dynamic resizing, proper collision handling, utility methods (set, get, has, etc.), test cases (test.js), and notes-style documentation (README.md).

Author: singharyan006

hashmap/README.md

@@ -0,0 +1,123 @@
+# 🧠 HashMap (from scratch)
+
+This project is part of The Odin Project's JavaScript curriculum.  
+In this, I built a custom `HashMap` class without using JavaScript’s built-in `Map` or object key-value behavior.
+
+---
+
+## 📦 Key Concepts
+
+- A **HashMap** stores key-value pairs.
+- Each **key is converted into an index** using a `hash()` function.
+- The key-value pair is then stored in a **bucket** (an array at that index).
+- **Collisions** are handled using **chaining** (each bucket is an array of pairs).
+- **Resizing** happens when the load factor exceeds a threshold (default 0.75).
+
+---
+
+## 🧰 Internal Properties
+
+| Property     | Purpose |
+|--------------|---------|
+| `capacity`   | Total number of buckets (initial: 16) |
+| `size`       | Number of stored key-value pairs |
+| `loadFactor` | Max ratio of size/capacity before resizing (default: 0.75) |
+| `buckets`    | Array of arrays storing key-value pairs |
+
+---
+
+## ⚙️ Hash Function
+
+```js
+hash(key) {
+  let hashCode = 0;
+  const prime = 31;
+
+  for (let i = 0; i < key.length; i++) {
+    hashCode = (prime * hashCode + key.charCodeAt(i)) % this.capacity;
+  }
+
+  return hashCode;
+}
+```
+
+---
+
+## ⚙️ Hash Function Details
+
+- ✅ Uses a **prime multiplier** for better distribution.
+- ✅ Applies **modulo during the loop** to avoid integer overflow.
+- ✅ Assumes **all keys are strings** (as required by the assignment).
+
+---
+
+## ✅ Methods Implemented
+
+### `set(key, value)`
+- Adds a new key-value pair.
+- If the key already exists, updates the value.
+- Triggers a resize if the load factor is exceeded.
+
+### `get(key)`
+- Returns the value for a key, or `null` if not found.
+
+### `has(key)`
+- Returns `true` if the key exists, else `false`.
+
+### `remove(key)`
+- Deletes the key-value pair.
+- Returns `true` if deleted, `false` if not found.
+
+### `length()`
+- Returns the number of stored key-value pairs.
+
+### `clear()`
+- Removes all entries from the map.
+
+### `keys()`
+- Returns an array of all keys.
+
+### `values()`
+- Returns an array of all values.
+
+### `entries()`
+- Returns an array of `[key, value]` pairs.
+
+---
+
+## 🧪 Testing (in `test.js`)
+
+- Inserted 12 values (hit 0.75 load factor)
+- Overwrote some keys (length stayed the same)
+- Inserted 13th value (`"moon"`) → triggered resize (capacity doubled)
+- After resizing, verified that all other methods (`get`, `has`, `remove`, etc.) still worked correctly
+
+---
+
+## 💡 Notes to Self
+
+- Always access **buckets using the hashed index**, never directly with the key.
+- For collision handling, always **check if the key exists inside the bucket array**.
+- During resizing, rehash and reinsert **every key-value pair**.
+- Only increment `size` **when adding a new key**, not when updating an existing one.
+
+---
+
+## 🌱 Possible Improvements
+
+- Support **more data types as keys** (e.g., numbers, symbols).
+- Add a `forEach()` method like the native `Map`.
+- Implement a **`HashSet`** using similar internal logic.
+
+---
+
+## 📁 File Structure
+
+```
+hashmap/
+├── hashMap.js # Main class
+├── test.js # Manual testing file
+└── README.md # You're here!
+```
+
+---

hashmap/hashMap.js

@@ -0,0 +1,142 @@
+class HashMap {
+  constructor() {
+    this.capacity = 16;
+    this.size = 0;
+    this.loadFactor = 0.75;
+    this.buckets = new Array(this.capacity).fill(null).map(() => []);
+  }
+
+  hash(key) {
+    let hashCode = 0;
+    const prime = 31;
+
+    for (let i = 0; i < key.length; i++) {
+      hashCode = (prime * hashCode + key.charCodeAt(i)) % this.capacity;
+    }
+
+    return hashCode;
+  }
+
+  checkIndexBounds(index) {
+    if (index < 0 || index >= this.buckets.length) {
+      throw new Error("Trying to access index out of bounds");
+    }
+  }
+
+  set(key, value) {
+    const index = this.hash(key);
+    this.checkIndexBounds(index);
+
+    const bucket = this.buckets[index];
+
+    for (let i = 0; i < bucket.length; i++) {
+      if (bucket[i][0] === key) {
+        bucket[i][1] = value;
+        return;
+      }
+    }
+
+    bucket.push([key, value]);
+    this.size++;
+
+    if (this.size / this.capacity > this.loadFactor) {
+      this.resize();
+    }
+  }
+
+  get(key) {
+    const index = this.hash(key);
+    this.checkIndexBounds(index);
+
+    const bucket = this.buckets[index];
+
+    for (let i = 0; i < bucket.length; i++) {
+      if (bucket[i][0] === key) {
+        return bucket[i][1];
+      }
+    }
+
+    return null;
+  }
+
+  has(key) {
+    return this.get(key) !== null;
+  }
+
+  remove(key) {
+    const index = this.hash(key);
+    this.checkIndexBounds(index);
+
+    const bucket = this.buckets[index];
+
+    for (let i = 0; i < bucket.length; i++) {
+      if (bucket[i][0] === key) {
+        bucket.splice(i, 1);
+        this.size--;
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  length() {
+    return this.size;
+  }
+
+  clear() {
+    this.buckets = new Array(this.capacity).fill(null).map(() => []);
+    this.size = 0;
+  }
+
+  keys() {
+    const keysArray = [];
+
+    for (let bucket of this.buckets) {
+      for (let [key, _] of bucket) {
+        keysArray.push(key);
+      }
+    }
+
+    return keysArray;
+  }
+
+  values() {
+    const valuesArray = [];
+
+    for (let bucket of this.buckets) {
+      for (let [_, value] of bucket) {
+        valuesArray.push(value);
+      }
+    }
+
+    return valuesArray;
+  }
+
+  entries() {
+    const entriesArray = [];
+
+    for (let bucket of this.buckets) {
+      for (let [key, value] of bucket) {
+        entriesArray.push([key, value]);
+      }
+    }
+
+    return entriesArray;
+  }
+
+  resize() {
+    const oldBuckets = this.buckets;
+    this.capacity *= 2;
+    this.buckets = new Array(this.capacity).fill(null).map(() => []);
+    this.size = 0;
+
+    for (let bucket of oldBuckets) {
+      for (let [key, value] of bucket) {
+        this.set(key, value);
+      }
+    }
+  }
+}
+
+module.exports = HashMap;

hashmap/test.js

@@ -0,0 +1,51 @@
+const HashMap = require('./hashMap');
+const map = new HashMap();
+
+// Fill to capacity (0.75 * 16 = 12 items)
+map.set('apple', 'red');
+map.set('banana', 'yellow');
+map.set('carrot', 'orange');
+map.set('dog', 'brown');
+map.set('elephant', 'gray');
+map.set('frog', 'green');
+map.set('grape', 'purple');
+map.set('hat', 'black');
+map.set('ice cream', 'white');
+map.set('jacket', 'blue');
+map.set('kite', 'pink');
+map.set('lion', 'golden');
+
+console.log('Length after 12 inserts:', map.length()); // Expect: 12
+console.log('Capacity before resize:', map.capacity);  // Expect: 16
+
+// Overwrite some values
+map.set('apple', 'dark red');
+map.set('banana', 'light yellow');
+
+console.log('Updated apple:', map.get('apple')); // Expect: dark red
+console.log('Updated banana:', map.get('banana')); // Expect: light yellow
+console.log('Length should still be 12:', map.length()); // No change
+
+// Trigger resize with 13th item
+map.set('moon', 'silver');
+
+console.log('Length after resize:', map.length()); // Expect: 13
+console.log('Capacity after resize:', map.capacity); // Expect: 32
+
+// Test has()
+console.log('Has "moon"?', map.has('moon')); // true
+console.log('Has "sun"?', map.has('sun'));   // false
+
+// Test remove()
+console.log('Remove "dog":', map.remove('dog')); // true
+console.log('Remove "sun":', map.remove('sun')); // false
+
+// Test keys, values, entries
+console.log('All keys:', map.keys());
+console.log('All values:', map.values());
+console.log('All entries:', map.entries());
+
+// Clear
+map.clear();
+console.log('Length after clear:', map.length()); // Expect: 0
+console.log('Entries after clear:', map.entries()); // Expect: []