@procedures/collections 0.0.0-stage → 0.1.0

package/src/impl/hash-map.ts

@@ -0,0 +1,623 @@
+/**
+ * HashMap implementation - A hash table with custom equality and hashing.
+ *
+ * Provides O(1) average case lookup, insertion, and deletion.
+ * Supports custom equality and hash functions for keys.
+ * Mirrors java.util.HashMap.
+ *
+ * @example
+ * const map = hashMap<string, number>()
+ * map.set('one', 1)
+ * map.set('two', 2)
+ * console.log(map.get('one')) // 1
+ *
+ * // Custom equality for object keys
+ * const userMap = hashMap<User, Data>({
+ *   keyEq: (a, b) => a.id === b.id,
+ *   keyHash: (u) => hashString(u.id)
+ * })
+ */
+
+import type { MapLike, Entry } from "../interfaces/map.js";
+import type { Eq, Hash } from "../core/traits.js";
+import { defaultEq, defaultHash } from "../utils/defaults.js";
+
+/**
+ * Internal entry node for hash buckets.
+ */
+interface Node<K, V> {
+  key: K;
+  value: V;
+  hash: number;
+  next: Node<K, V> | null;
+}
+
+/**
+ * Options for creating a HashMap.
+ */
+export interface HashMapOptions<K, V> {
+  /**
+   * Initial capacity (number of buckets).
+   * Must be a power of 2.
+   * @default 16
+   */
+  initialCapacity?: number;
+
+  /**
+   * Load factor threshold for resizing (0-1).
+   * When size > capacity * loadFactor, the map resizes.
+   * @default 0.75
+   */
+  loadFactor?: number;
+
+  /**
+   * Equality function for keys.
+   * @default defaultEq (===)
+   */
+  keyEq?: Eq<K>;
+
+  /**
+   * Hash function for keys.
+   * @default defaultHash
+   */
+  keyHash?: Hash<K>;
+
+  /**
+   * Equality function for values (used in containsValue).
+   * @default defaultEq (===)
+   */
+  valueEq?: Eq<V>;
+}
+
+/**
+ * HashMap<K, V> - Hash table implementation with custom equality/hashing.
+ *
+ * Uses separate chaining for collision resolution.
+ * Automatically resizes when load factor is exceeded.
+ *
+ * Not thread-safe. Use synchronized() behavior for concurrent access.
+ */
+export class HashMap<K, V> implements MapLike<K, V> {
+  private _buckets: (Node<K, V> | null)[];
+  private _size: number;
+  private readonly _loadFactor: number;
+  private readonly _keyEq: Eq<K>;
+  private readonly _keyHash: Hash<K>;
+  private readonly _valueEq: Eq<V>;
+  private _threshold: number;
+  /**
+   * The count of structural changes (a key added or removed, a clear, a resize). An iterator
+   * records it at its start and throws when it changes. Before, a resize during iteration made
+   * the iterator skip or repeat entries (BUGS-2026-07 L15).
+   */
+  private _modCount = 0;
+
+  constructor(options: HashMapOptions<K, V> = {}) {
+    const {
+      initialCapacity = 16,
+      loadFactor = 0.75,
+      keyEq = defaultEq,
+      keyHash = defaultHash,
+      valueEq = defaultEq,
+    } = options;
+
+    const capacity = this.nextPowerOfTwo(Math.max(4, initialCapacity));
+    this._buckets = new Array(capacity).fill(null);
+    this._size = 0;
+    this._loadFactor = loadFactor;
+    this._keyEq = keyEq;
+    this._keyHash = keyHash;
+    this._valueEq = valueEq;
+    this._threshold = Math.floor(capacity * loadFactor);
+  }
+
+  // ========================================================================
+  // Size
+  // ========================================================================
+
+  get size(): number {
+    return this._size;
+  }
+
+  get isEmpty(): boolean {
+    return this._size === 0;
+  }
+
+  get keyEq(): Eq<K> {
+    return this._keyEq;
+  }
+
+  get valueEq(): Eq<V> {
+    return this._valueEq;
+  }
+
+  // ========================================================================
+  // Lookup
+  // ========================================================================
+
+  has(key: K): boolean {
+    const hash = this._keyHash(key);
+    const index = this.bucketIndex(hash);
+    let node = this._buckets[index] ?? null;
+
+    while (node !== null) {
+      if (node.hash === hash && this._keyEq(node.key, key)) {
+        return true;
+      }
+      node = node.next;
+    }
+
+    return false;
+  }
+
+  get(key: K): V {
+    const value = this.getOrUndefined(key);
+    if (value === undefined) {
+      throw new Error(`Key not found: ${key}`);
+    }
+    return value;
+  }
+
+  getOrUndefined(key: K): V | undefined {
+    const hash = this._keyHash(key);
+    const index = this.bucketIndex(hash);
+    let node = this._buckets[index] ?? null;
+
+    while (node !== null) {
+      if (node.hash === hash && this._keyEq(node.key, key)) {
+        return node.value;
+      }
+      node = node.next;
+    }
+
+    return undefined;
+  }
+
+  getOrDefault(key: K, defaultValue: V): V {
+    const value = this.getOrUndefined(key);
+    return value !== undefined ? value : defaultValue;
+  }
+
+  containsValue(value: V): boolean {
+    for (const bucket of this._buckets) {
+      let node = bucket;
+      while (node !== null) {
+        if (this._valueEq(node.value, value)) {
+          return true;
+        }
+        node = node.next;
+      }
+    }
+    return false;
+  }
+
+  // ========================================================================
+  // Modification
+  // ========================================================================
+
+  set(key: K, value: V): V | undefined {
+    const hash = this._keyHash(key);
+    const index = this.bucketIndex(hash);
+    let node = this._buckets[index] ?? null;
+
+    // Check if key already exists
+    while (node !== null) {
+      if (node.hash === hash && this._keyEq(node.key, key)) {
+        const oldValue = node.value;
+        node.value = value;
+        return oldValue;
+      }
+      node = node.next;
+    }
+
+    // Key doesn't exist, add new entry
+    const newNode: Node<K, V> = {
+      key,
+      value,
+      hash,
+      next: this._buckets[index] ?? null,
+    };
+    this._buckets[index] = newNode;
+    this._size++;
+    this._modCount++;
+
+    // Check if resize is needed
+    if (this._size > this._threshold) {
+      this.resize();
+    }
+
+    return undefined;
+  }
+
+  setIfAbsent(key: K, value: V): V {
+    const existing = this.getOrUndefined(key);
+    if (existing !== undefined) {
+      return existing;
+    }
+    this.set(key, value);
+    return value;
+  }
+
+  delete(key: K): V | undefined {
+    const hash = this._keyHash(key);
+    const index = this.bucketIndex(hash);
+    let node = this._buckets[index] ?? null;
+    let prev: Node<K, V> | null = null;
+
+    while (node !== null) {
+      if (node.hash === hash && this._keyEq(node.key, key)) {
+        // Found the node to delete
+        if (prev === null) {
+          // Node is at head of bucket
+          this._buckets[index] = node.next;
+        } else {
+          // Node is in middle or end
+          prev.next = node.next;
+        }
+        this._size--;
+        this._modCount++;
+        return node.value;
+      }
+      prev = node;
+      node = node.next;
+    }
+
+    return undefined;
+  }
+
+  deleteEntry(key: K, value: V): boolean {
+    const hash = this._keyHash(key);
+    const index = this.bucketIndex(hash);
+    let node = this._buckets[index] ?? null;
+    let prev: Node<K, V> | null = null;
+
+    while (node !== null) {
+      if (
+        node.hash === hash &&
+        this._keyEq(node.key, key) &&
+        this._valueEq(node.value, value)
+      ) {
+        // Found the entry to delete
+        if (prev === null) {
+          this._buckets[index] = node.next;
+        } else {
+          prev.next = node.next;
+        }
+        this._size--;
+        this._modCount++;
+        return true;
+      }
+      prev = node;
+      node = node.next;
+    }
+
+    return false;
+  }
+
+  replace(key: K, value: V): V | undefined {
+    const hash = this._keyHash(key);
+    const index = this.bucketIndex(hash);
+    let node = this._buckets[index] ?? null;
+
+    while (node !== null) {
+      if (node.hash === hash && this._keyEq(node.key, key)) {
+        const oldValue = node.value;
+        node.value = value;
+        return oldValue;
+      }
+      node = node.next;
+    }
+
+    return undefined;
+  }
+
+  replaceEntry(key: K, oldValue: V, newValue: V): boolean {
+    const hash = this._keyHash(key);
+    const index = this.bucketIndex(hash);
+    let node = this._buckets[index] ?? null;
+
+    while (node !== null) {
+      if (
+        node.hash === hash &&
+        this._keyEq(node.key, key) &&
+        this._valueEq(node.value, oldValue)
+      ) {
+        node.value = newValue;
+        return true;
+      }
+      node = node.next;
+    }
+
+    return false;
+  }
+
+  // ========================================================================
+  // Compute operations
+  // ========================================================================
+
+  computeIfAbsent(key: K, mappingFunction: (key: K) => V): V {
+    const existing = this.getOrUndefined(key);
+    if (existing !== undefined) {
+      return existing;
+    }
+
+    const newValue = mappingFunction(key);
+    this.set(key, newValue);
+    return newValue;
+  }
+
+  computeIfPresent(
+    key: K,
+    remappingFunction: (key: K, value: V) => V | undefined
+  ): V | undefined {
+    const existing = this.getOrUndefined(key);
+    if (existing === undefined) {
+      return undefined;
+    }
+
+    const newValue = remappingFunction(key, existing);
+    if (newValue === undefined) {
+      this.delete(key);
+      return undefined;
+    }
+
+    this.set(key, newValue);
+    return newValue;
+  }
+
+  compute(
+    key: K,
+    remappingFunction: (key: K, value: V | undefined) => V | undefined
+  ): V | undefined {
+    const existing = this.getOrUndefined(key);
+    const newValue = remappingFunction(key, existing);
+
+    if (newValue === undefined) {
+      if (existing !== undefined) {
+        this.delete(key);
+      }
+      return undefined;
+    }
+
+    this.set(key, newValue);
+    return newValue;
+  }
+
+  merge(
+    key: K,
+    value: V,
+    remappingFunction: (oldValue: V, newValue: V) => V | undefined
+  ): V | undefined {
+    const existing = this.getOrUndefined(key);
+
+    if (existing === undefined) {
+      this.set(key, value);
+      return value;
+    }
+
+    const merged = remappingFunction(existing, value);
+    if (merged === undefined) {
+      this.delete(key);
+      return undefined;
+    }
+
+    this.set(key, merged);
+    return merged;
+  }
+
+  // ========================================================================
+  // Bulk operations
+  // ========================================================================
+
+  putAll(other: MapLike<K, V> | Iterable<Entry<K, V>>): void {
+    for (const entry of other) {
+      this.set(entry.key, entry.value);
+    }
+  }
+
+  clear(): void {
+    this._buckets.fill(null);
+    this._size = 0;
+    this._modCount++;
+  }
+
+  // ========================================================================
+  // Views
+  // ========================================================================
+
+  *keys(): IterableIterator<K> {
+    const expected = this._modCount;
+    for (const bucket of this._buckets) {
+      let node = bucket;
+      while (node !== null) {
+        yield node.key;
+        this.checkUnchanged(expected);
+        node = node.next;
+      }
+    }
+  }
+
+  *values(): IterableIterator<V> {
+    const expected = this._modCount;
+    for (const bucket of this._buckets) {
+      let node = bucket;
+      while (node !== null) {
+        yield node.value;
+        this.checkUnchanged(expected);
+        node = node.next;
+      }
+    }
+  }
+
+  *entries(): IterableIterator<Entry<K, V>> {
+    const expected = this._modCount;
+    for (const bucket of this._buckets) {
+      let node = bucket;
+      while (node !== null) {
+        yield { key: node.key, value: node.value };
+        this.checkUnchanged(expected);
+        node = node.next;
+      }
+    }
+  }
+
+  // ========================================================================
+  // Iteration
+  // ========================================================================
+
+  *[Symbol.iterator](): Iterator<Entry<K, V>> {
+    yield* this.entries();
+  }
+
+  forEach(action: (value: V, key: K, map: this) => void): void {
+    for (const entry of this.entries()) {
+      action(entry.value, entry.key, this);
+    }
+  }
+
+  // ========================================================================
+  // Internal helpers
+  // ========================================================================
+
+  /** This method throws when the map changed structurally after an iterator started. */
+  private checkUnchanged(expected: number): void {
+    if (this._modCount !== expected) {
+      throw new Error("HashMap changed during iteration");
+    }
+  }
+
+  /**
+   * Returns the bucket index for a given hash.
+   */
+  private bucketIndex(hash: number): number {
+    // Use bitwise AND with (length - 1) for efficient modulo
+    // This works because length is always a power of 2
+    return hash & (this._buckets.length - 1);
+  }
+
+  /**
+   * Resizes the hash table to double its current capacity.
+   */
+  private resize(): void {
+    const oldBuckets = this._buckets;
+    const newCapacity = oldBuckets.length << 1; // Double capacity
+
+    if (newCapacity < 0) {
+      throw new Error("Map too large");
+    }
+
+    this._buckets = new Array(newCapacity).fill(null);
+    this._threshold = Math.floor(newCapacity * this._loadFactor);
+    this._modCount++;
+
+    // Rehash all entries
+    for (const bucket of oldBuckets) {
+      let node = bucket;
+      while (node !== null) {
+        const next = node.next;
+        const index = this.bucketIndex(node.hash);
+        node.next = this._buckets[index] ?? null;
+        this._buckets[index] = node;
+        node = next;
+      }
+    }
+  }
+
+  /**
+   * Returns the next power of 2 >= n.
+   */
+  private nextPowerOfTwo(n: number): number {
+    if (n <= 0) return 1;
+    n--;
+    n |= n >> 1;
+    n |= n >> 2;
+    n |= n >> 4;
+    n |= n >> 8;
+    n |= n >> 16;
+    return n + 1;
+  }
+
+  // ========================================================================
+  // Inspection
+  // ========================================================================
+
+  /**
+   * Returns the current number of buckets.
+   */
+  get capacity(): number {
+    return this._buckets.length;
+  }
+
+  /**
+   * Returns the current load factor (size / capacity).
+   */
+  get loadFactor(): number {
+    return this._size / this._buckets.length;
+  }
+
+  /**
+   * Returns statistics about bucket distribution (for debugging).
+   */
+  getStats(): {
+    size: number;
+    capacity: number;
+    loadFactor: number;
+    avgChainLength: number;
+    maxChainLength: number;
+    emptyBuckets: number;
+  } {
+    let maxChainLength = 0;
+    let totalChainLength = 0;
+    let emptyBuckets = 0;
+
+    for (const bucket of this._buckets) {
+      if (bucket === null) {
+        emptyBuckets++;
+      } else {
+        let length = 0;
+        let node: Node<K, V> | null = bucket;
+        while (node !== null) {
+          length++;
+          node = node.next;
+        }
+        totalChainLength += length;
+        maxChainLength = Math.max(maxChainLength, length);
+      }
+    }
+
+    return {
+      size: this._size,
+      capacity: this._buckets.length,
+      loadFactor: this.loadFactor,
+      avgChainLength: this._size > 0 ? totalChainLength / (this._buckets.length - emptyBuckets) : 0,
+      maxChainLength,
+      emptyBuckets,
+    };
+  }
+}
+
+/**
+ * Factory function to create a HashMap.
+ *
+ * @example
+ * const map = hashMap<string, number>()
+ * const mapWithOptions = hashMap<User, Data>({
+ *   keyEq: (a, b) => a.id === b.id,
+ *   keyHash: (u) => hashString(u.id)
+ * })
+ * const mapFromEntries = hashMap([['a', 1], ['b', 2]])
+ */
+export function hashMap<K, V>(
+  optionsOrEntries?: HashMapOptions<K, V> | Iterable<readonly [K, V]>
+): HashMap<K, V> {
+  // Check if it's an iterable of entries
+  if (optionsOrEntries && Symbol.iterator in optionsOrEntries) {
+    const map = new HashMap<K, V>();
+    for (const [key, value] of optionsOrEntries as Iterable<readonly [K, V]>) {
+      map.set(key, value);
+    }
+    return map;
+  }
+
+  return new HashMap<K, V>(optionsOrEntries as HashMapOptions<K, V>);
+}