@procedures/collections 0.0.0-stage → 0.1.0

package/src/impl/linked-hash-map.ts

@@ -0,0 +1,572 @@
+/**
+ * LinkedHashMap - HashMap that maintains insertion order.
+ *
+ * Combines a hash table with a doubly-linked list to maintain predictable
+ * iteration order. Mirrors java.util.LinkedHashMap.
+ *
+ * Key features:
+ * - O(1) access, insert, delete (like HashMap)
+ * - Predictable iteration order (insertion order or access order)
+ * - Perfect for LRU caches when accessOrder is true
+ *
+ * @example
+ * const map = linkedHashMap<string, number>()
+ * map.set('a', 1)
+ * map.set('b', 2)
+ * map.set('c', 3)
+ * // Iteration order: a, b, c (insertion order)
+ *
+ * @example
+ * // LRU cache with access order
+ * const lru = linkedHashMap<string, number>({ accessOrder: true })
+ * lru.set('a', 1)
+ * lru.set('b', 2)
+ * lru.get('a') // Moves 'a' to end
+ * // Iteration order: b, a (access order)
+ */
+
+import type { MapLike, Entry } from "../interfaces/map.js";
+import type { Eq, Hash } from "../core/traits.js";
+import { defaultEq, defaultHash } from "../utils/defaults.js";
+
+/**
+ * An entry. It is in two lists: the chain of its hash bucket (`next`) and the order list
+ * (`before`, `after`). Before, one `next` field served both lists, so the first collision or
+ * resize corrupted the map (BUGS-2026-07 C10).
+ */
+interface LinkedNode<K, V> {
+  key: K;
+  value: V;
+  hash: number;
+  /** The next entry of the same hash bucket */
+  next: LinkedNode<K, V> | null;
+  /** The entry before this one in the iteration order */
+  before: LinkedNode<K, V> | null;
+  /** The entry after this one in the iteration order */
+  after: LinkedNode<K, V> | null;
+}
+
+/**
+ * Options for creating a LinkedHashMap.
+ */
+export interface LinkedHashMapOptions<K, V> {
+  /**
+   * Initial capacity of the hash table.
+   * @default 16
+   */
+  initialCapacity?: number;
+
+  /**
+   * Load factor before resizing.
+   * @default 0.75
+   */
+  loadFactor?: number;
+
+  /**
+   * Equality function for keys.
+   * @default defaultEq
+   */
+  eq?: Eq<K>;
+
+  /**
+   * Hash function for keys.
+   * @default defaultHash
+   */
+  hash?: Hash<K>;
+
+  /**
+   * Equality function for values.
+   * @default defaultEq
+   */
+  valueEq?: Eq<V>;
+
+  /**
+   * If true, maintain access order instead of insertion order.
+   * Useful for LRU caches.
+   * @default false
+   */
+  accessOrder?: boolean;
+}
+
+/**
+ * LinkedHashMap<K, V> - Hash map with predictable iteration order.
+ *
+ * Maintains a doubly-linked list of entries to preserve insertion order
+ * (or access order if accessOrder is true).
+ */
+export class LinkedHashMap<K, V> implements MapLike<K, V> {
+  private _buckets: (LinkedNode<K, V> | null)[];
+  private _size: number = 0;
+  private readonly _loadFactor: number;
+  private readonly _eq: Eq<K>;
+  private readonly _hash: Hash<K>;
+  private readonly _valueEq: Eq<V>;
+  private readonly _accessOrder: boolean;
+
+  // Doubly-linked list sentinels
+  private _head: LinkedNode<K, V> | null = null;
+  private _tail: LinkedNode<K, V> | null = null;
+
+  constructor(options: LinkedHashMapOptions<K, V> = {}) {
+    const {
+      initialCapacity = 16,
+      loadFactor = 0.75,
+      eq = defaultEq,
+      hash = defaultHash,
+      valueEq = defaultEq,
+      accessOrder = false,
+    } = options;
+
+    this._buckets = new Array(Math.max(1, initialCapacity)).fill(null);
+    this._loadFactor = loadFactor;
+    this._eq = eq;
+    this._hash = hash;
+    this._valueEq = valueEq;
+    this._accessOrder = accessOrder;
+  }
+
+  // ========================================================================
+  // Size and state
+  // ========================================================================
+
+  get size(): number {
+    return this._size;
+  }
+
+  get isEmpty(): boolean {
+    return this._size === 0;
+  }
+
+  get eq(): Eq<K> {
+    return this._eq;
+  }
+
+  get keyEq(): Eq<K> {
+    return this._eq;
+  }
+
+  get valueEq(): Eq<V> {
+    return this._valueEq;
+  }
+
+  get hash(): Hash<K> {
+    return this._hash;
+  }
+
+  // ========================================================================
+  // Lookup operations
+  // ========================================================================
+
+  has(key: K): boolean {
+    return this.getNode(key) !== null;
+  }
+
+  containsKey(key: K): boolean {
+    return this.has(key);
+  }
+
+  containsValue(value: V): boolean {
+    let node = this._head;
+    while (node !== null) {
+      if (this._valueEq(node.value, value)) {
+        return true;
+      }
+      node = node.after;
+    }
+    return false;
+  }
+
+  get(key: K): V {
+    const node = this.getNode(key);
+    if (node === null) {
+      throw new Error("Key not found");
+    }
+    if (this._accessOrder) {
+      this.moveToEnd(node);
+    }
+    return node.value;
+  }
+
+  getOrUndefined(key: K): V | undefined {
+    const node = this.getNode(key);
+    if (node === null) return undefined;
+    if (this._accessOrder) {
+      this.moveToEnd(node);
+    }
+    return node.value;
+  }
+
+  getOrDefault(key: K, defaultValue: V): V {
+    const node = this.getNode(key);
+    if (node === null) return defaultValue;
+    if (this._accessOrder) {
+      this.moveToEnd(node);
+    }
+    return node.value;
+  }
+
+  // ========================================================================
+  // Modification operations
+  // ========================================================================
+
+  set(key: K, value: V): V | undefined {
+    const hashCode = this._hash(key);
+    const index = this.getBucketIndex(hashCode);
+    let node = this._buckets[index] ?? null;
+
+    // Check if key already exists
+    while (node !== null) {
+      if (node.hash === hashCode && this._eq(node.key, key)) {
+        const oldValue = node.value;
+        node.value = value;
+        if (this._accessOrder) {
+          this.moveToEnd(node);
+        }
+        return oldValue;
+      }
+      node = node.next;
+    }
+
+    // Key doesn't exist, add new entry
+    const newNode: LinkedNode<K, V> = {
+      key,
+      value,
+      hash: hashCode,
+      next: this._buckets[index] ?? null,
+      before: null,
+      after: null,
+    };
+
+    this._buckets[index] = newNode;
+    this._size++;
+
+    // Add to linked list
+    this.addToEnd(newNode);
+
+    // Resize if needed
+    if (this._size > this._buckets.length * this._loadFactor) {
+      this.resize();
+    }
+
+    return undefined;
+  }
+
+  setIfAbsent(key: K, value: V): V {
+    const existing = this.getNode(key);
+    if (existing !== null) {
+      if (this._accessOrder) {
+        this.moveToEnd(existing);
+      }
+      return existing.value;
+    }
+    this.set(key, value);
+    return value;
+  }
+
+  replace(key: K, value: V): V | undefined {
+    const node = this.getNode(key);
+    if (node === null) return undefined;
+    const oldValue = node.value;
+    node.value = value;
+    if (this._accessOrder) {
+      this.moveToEnd(node);
+    }
+    return oldValue;
+  }
+
+  replaceEntry(key: K, oldValue: V, newValue: V): boolean {
+    const node = this.getNode(key);
+    if (node === null || !this._valueEq(node.value, oldValue)) {
+      return false;
+    }
+    node.value = newValue;
+    if (this._accessOrder) {
+      this.moveToEnd(node);
+    }
+    return true;
+  }
+
+  delete(key: K): V | undefined {
+    const node = this.getNode(key);
+    if (node === null) return undefined;
+
+    const oldValue = node.value;
+
+    // Remove from bucket
+    this.removeFromBucket(node);
+
+    // Remove from linked list
+    this.removeFromList(node);
+
+    this._size--;
+    return oldValue;
+  }
+
+  deleteEntry(key: K, value: V): boolean {
+    const node = this.getNode(key);
+    if (node === null || !this._valueEq(node.value, value)) {
+      return false;
+    }
+
+    // Remove from bucket
+    this.removeFromBucket(node);
+
+    // Remove from linked list
+    this.removeFromList(node);
+
+    this._size--;
+    return true;
+  }
+
+  clear(): void {
+    this._buckets = new Array(this._buckets.length).fill(null);
+    this._size = 0;
+    this._head = null;
+    this._tail = null;
+  }
+
+  // ========================================================================
+  // Bulk operations
+  // ========================================================================
+
+  putAll(other: MapLike<K, V> | Iterable<Entry<K, V>>): void {
+    if ('entries' in other && typeof other.entries === 'function') {
+      for (const entry of other.entries()) {
+        this.set(entry.key, entry.value);
+      }
+    } else {
+      for (const entry of other as Iterable<Entry<K, V>>) {
+        this.set(entry.key, entry.value);
+      }
+    }
+  }
+
+  // ========================================================================
+  // Computed operations
+  // ========================================================================
+
+  computeIfAbsent(key: K, mappingFunction: (key: K) => V): V {
+    const existing = this.getNode(key);
+    if (existing !== null) {
+      if (this._accessOrder) {
+        this.moveToEnd(existing);
+      }
+      return existing.value;
+    }
+    const value = mappingFunction(key);
+    this.set(key, value);
+    return value;
+  }
+
+  computeIfPresent(key: K, remappingFunction: (key: K, value: V) => V | undefined): V | undefined {
+    const existing = this.getNode(key);
+    if (existing === null) return undefined;
+
+    const newValue = remappingFunction(key, existing.value);
+    if (newValue === undefined) {
+      this.delete(key);
+      return undefined;
+    }
+    existing.value = newValue;
+    if (this._accessOrder) {
+      this.moveToEnd(existing);
+    }
+    return newValue;
+  }
+
+  compute(key: K, remappingFunction: (key: K, value: V | undefined) => V | undefined): V | undefined {
+    const existing = this.getNode(key);
+    const newValue = remappingFunction(key, existing?.value);
+
+    if (newValue === undefined) {
+      if (existing !== null) {
+        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.getNode(key);
+
+    if (existing === null) {
+      this.set(key, value);
+      return value;
+    }
+
+    const merged = remappingFunction(existing.value, value);
+    if (merged === undefined) {
+      this.delete(key);
+      return undefined;
+    }
+
+    existing.value = merged;
+    if (this._accessOrder) {
+      this.moveToEnd(existing);
+    }
+    return merged;
+  }
+
+  // ========================================================================
+  // View operations
+  // ========================================================================
+
+  *keys(): IterableIterator<K> {
+    let node = this._head;
+    while (node !== null) {
+      yield node.key;
+      node = node.after;
+    }
+  }
+
+  *values(): IterableIterator<V> {
+    let node = this._head;
+    while (node !== null) {
+      yield node.value;
+      node = node.after;
+    }
+  }
+
+  *entries(): IterableIterator<Entry<K, V>> {
+    let node = this._head;
+    while (node !== null) {
+      yield { key: node.key, value: node.value };
+      node = node.after;
+    }
+  }
+
+  *[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);
+    }
+  }
+
+  toArray(): Entry<K, V>[] {
+    return Array.from(this.entries());
+  }
+
+  // ========================================================================
+  // Private helpers
+  // ========================================================================
+
+  private getNode(key: K): LinkedNode<K, V> | null {
+    const hashCode = this._hash(key);
+    const index = this.getBucketIndex(hashCode);
+    let node = this._buckets[index] ?? null;
+
+    while (node !== null) {
+      if (node.hash === hashCode && this._eq(node.key, key)) {
+        return node;
+      }
+      node = node.next;
+    }
+
+    return null;
+  }
+
+  private getBucketIndex(hashCode: number): number {
+    return Math.abs(hashCode) % this._buckets.length;
+  }
+
+  private removeFromBucket(node: LinkedNode<K, V>): void {
+    const index = this.getBucketIndex(node.hash);
+    let current = this._buckets[index] ?? null;
+    let prev: LinkedNode<K, V> | null = null;
+
+    while (current !== null) {
+      if (current === node) {
+        if (prev === null) {
+          this._buckets[index] = current.next;
+        } else {
+          prev.next = current.next;
+        }
+        return;
+      }
+      prev = current;
+      current = current.next;
+    }
+  }
+
+  private addToEnd(node: LinkedNode<K, V>): void {
+    node.before = this._tail;
+    node.after = null;
+    if (this._tail === null) this._head = node;
+    else this._tail.after = node;
+    this._tail = node;
+  }
+
+  private removeFromList(node: LinkedNode<K, V>): void {
+    if (node.before !== null) node.before.after = node.after;
+    else this._head = node.after;
+    if (node.after !== null) node.after.before = node.before;
+    else this._tail = node.before;
+    node.before = node.after = null;
+  }
+
+  private moveToEnd(node: LinkedNode<K, V>): void {
+    if (node === this._tail) return; // Already at end
+    this.removeFromList(node);
+    this.addToEnd(node);
+  }
+
+  private resize(): void {
+    this._buckets = new Array(this._buckets.length * 2).fill(null);
+    // Rebuild the bucket chains (`next`) from the order list (`after`)
+    for (let node = this._head; node !== null; node = node.after) {
+      const index = this.getBucketIndex(node.hash);
+      node.next = this._buckets[index] ?? null;
+      this._buckets[index] = node;
+    }
+  }
+
+  // ========================================================================
+  // Utility methods
+  // ========================================================================
+
+  toString(): string {
+    const entries = Array.from(this.entries())
+      .map(({ key, value }) => `${key}=${value}`)
+      .join(', ');
+    return `LinkedHashMap{${entries}}`;
+  }
+}
+
+/**
+ * Factory function to create a LinkedHashMap.
+ *
+ * @example
+ * const map = linkedHashMap<string, number>()
+ * map.set('a', 1)
+ * map.set('b', 2)
+ *
+ * @example
+ * // With initial entries
+ * const map = linkedHashMap<string, number>([
+ *   ['a', 1],
+ *   ['b', 2]
+ * ])
+ *
+ * @example
+ * // LRU cache with access order
+ * const lru = linkedHashMap<string, number>({ accessOrder: true })
+ */
+export function linkedHashMap<K, V>(
+  optionsOrEntries?: LinkedHashMapOptions<K, V> | Iterable<[K, V]>
+): LinkedHashMap<K, V> {
+  if (optionsOrEntries && Symbol.iterator in optionsOrEntries) {
+    const map = new LinkedHashMap<K, V>();
+    for (const [key, value] of optionsOrEntries as Iterable<[K, V]>) {
+      map.set(key, value);
+    }
+    return map;
+  }
+
+  return new LinkedHashMap<K, V>(optionsOrEntries as LinkedHashMapOptions<K, V>);
+}