Maps & Associative Collections

/**
 * Bidirectional map with forward and inverse mappings
 */
function BiMap<K, V>(): BiMap<K, V>;

interface BiMap<K, V> extends Map<K, V> {
  /** Access to the inverse map (value -> key) */
  readonly inverse: InverseMap<V, K>;
  
  /** Standard Map interface */
  set(key: K, value: V): this;
  get(key: K): V | undefined;
  has(key: K): boolean;
  delete(key: K): boolean;
  clear(): void;
  readonly size: number;
  
  /** Standard iteration methods */
  values(): IterableIterator<V>;
  keys(): IterableIterator<K>;
  entries(): IterableIterator<[K, V]>;
  [Symbol.iterator](): IterableIterator<[K, V]>;
  forEach(callback: (value: V, key: K, map: this) => void): void;
  
  inspect(): any;
}

interface InverseMap<V, K> extends Map<V, K> {
  /** Standard Map interface for reverse mapping */
  get(value: V): K | undefined;
  has(value: V): boolean;
  // Other Map methods for value->key mapping
}

/**
 * Map allowing multiple values per key
 * @param container Container constructor (Array or Set)
 */
function MultiMap<K, V>(container?: ArrayConstructor | SetConstructor): MultiMap<K, V>;

interface MultiMap<K, V> {
  /** Number of unique keys */
  readonly size: number;
  /** Total number of key-value associations */
  readonly dimension: number;
  
  /** Add value to key's collection */
  set(key: K, value: V): this;
  
  /** Get all values for key */
  get(key: K): Array<V> | Set<V> | undefined;
  
  /** Check if key exists */
  has(key: K): boolean;
  
  /** Check if key has specific value */
  hasValue(key: K, value: V): boolean;
  
  /** Remove specific value from key */
  remove(key: K, value: V): boolean;
  
  /** Remove all values for key */
  delete(key: K): boolean;
  
  /** Remove all key-value pairs */
  clear(): void;
  
  /** Get number of values for key */
  multiplicity(key: K): number;
  
  /** Iterate over all key-value associations */
  forEachAssociation(callback: (value: V, key: K) => void): void;
  
  /** Standard iteration over keys */
  keys(): IterableIterator<K>;
  values(): IterableIterator<Array<V> | Set<V>>;
  entries(): IterableIterator<[K, Array<V> | Set<V>]>;
  [Symbol.iterator](): IterableIterator<[K, Array<V> | Set<V>]>;
  
  inspect(): any;
}

/**
 * Map with automatic default value creation
 * @param factory Function to create default values
 */
function DefaultMap<K, V>(factory: () => V): DefaultMap<K, V>;

interface DefaultMap<K, V> extends Map<K, V> {
  /** Get value or create default if key doesn't exist */
  get(key: K): V;
  
  /** Standard Map interface */
  set(key: K, value: V): this;
  has(key: K): boolean;
  delete(key: K): boolean;
  clear(): void;
  readonly size: number;
  
  values(): IterableIterator<V>;
  keys(): IterableIterator<K>;
  entries(): IterableIterator<[K, V]>;
  [Symbol.iterator](): IterableIterator<[K, V]>;
  forEach(callback: (value: V, key: K, map: this) => void): void;
  
  inspect(): any;
}

/**
 * Map with fuzzy string matching
 * @param distance Distance function for string comparison
 * @param tolerance Maximum distance for matches
 */
function FuzzyMap<V>(distance: DistanceFunction, tolerance: number): FuzzyMap<V>;

interface FuzzyMap<V> {
  readonly size: number;
  
  /** Set key-value pair */
  set(key: string, value: V): this;
  
  /** Get value with fuzzy matching */
  get(key: string): V | undefined;
  
  /** Check if fuzzy match exists */
  has(key: string): boolean;
  
  /** Delete exact key */
  delete(key: string): boolean;
  
  /** Remove all entries */
  clear(): void;
  
  values(): IterableIterator<V>;
  keys(): IterableIterator<string>;
  entries(): IterableIterator<[string, V]>;
  [Symbol.iterator](): IterableIterator<[string, V]>;
  
  inspect(): any;
}

type DistanceFunction = (a: string, b: string) => number;

/**
 * MultiMap with fuzzy string matching
 * @param distance Distance function for string comparison
 * @param tolerance Maximum distance for matches
 */
function FuzzyMultiMap<V>(distance: DistanceFunction, tolerance: number): FuzzyMultiMap<V>;

interface FuzzyMultiMap<V> {
  readonly size: number;
  readonly dimension: number;
  
  /** Add value with fuzzy key matching */
  set(key: string, value: V): this;
  
  /** Get all values with fuzzy key matching */
  get(key: string): Array<V> | undefined;
  
  /** Check if fuzzy match exists */
  has(key: string): boolean;
  
  /** Remove specific value with fuzzy matching */
  remove(key: string, value: V): boolean;
  
  /** Delete all values for fuzzy-matched key */
  delete(key: string): boolean;
  
  clear(): void;
  
  /** Iterate over all associations */
  forEachAssociation(callback: (value: V, key: string) => void): void;
  
  keys(): IterableIterator<string>;
  values(): IterableIterator<Array<V>>;
  entries(): IterableIterator<[string, Array<V>]>;
  
  inspect(): any;
}

/**
 * WeakMap with automatic default value creation
 * @param factory Function to create default values
 */
function DefaultWeakMap<K extends object, V>(factory: () => V): DefaultWeakMap<K, V>;

interface DefaultWeakMap<K extends object, V> extends WeakMap<K, V> {
  /** Get value or create default if key doesn't exist */
  get(key: K): V;
  
  /** Standard WeakMap interface */
  set(key: K, value: V): this;
  has(key: K): boolean;
  delete(key: K): boolean;
}

import {BiMap} from "mnemonist";

const userMap = new BiMap<number, string>();
userMap.set(123, "alice");
userMap.set(456, "bob");

// Forward lookup
console.log(userMap.get(123)); // "alice"

// Reverse lookup
console.log(userMap.inverse.get("alice")); // 123
console.log(userMap.inverse.has("bob"));   // true

import {MultiMap} from "mnemonist";

// Array-based multimap
const tags = new MultiMap<string, string>(Array);
tags.set("javascript", "async");
tags.set("javascript", "promises");
tags.set("javascript", "closures");

console.log(tags.get("javascript")); // ["async", "promises", "closures"]
console.log(tags.multiplicity("javascript")); // 3

// Set-based multimap (no duplicates)
const categories = new MultiMap<string, string>(Set);
categories.set("frontend", "react");
categories.set("frontend", "vue");
categories.set("frontend", "react"); // Duplicate ignored in Set

console.log(categories.get("frontend")); // Set(2) {"react", "vue"}

import {DefaultMap} from "mnemonist";

// Counter using default map
const counter = new DefaultMap<string, number>(() => 0);
counter.set("apple", counter.get("apple") + 1); // Creates 0, then sets to 1
counter.set("apple", counter.get("apple") + 1); // Increments to 2

// Grouping with default arrays
const groups = new DefaultMap<string, Array<any>>(() => []);
groups.get("fruits").push("apple");
groups.get("fruits").push("banana");
groups.get("vegetables").push("carrot");

import {FuzzyMap} from "mnemonist";

// Using Levenshtein distance for fuzzy matching
function levenshtein(a: string, b: string): number {
  // Implementation of edit distance
  return /* calculated distance */;
}

const fuzzyMap = new FuzzyMap<string>(levenshtein, 2);
fuzzyMap.set("javascript", "JS programming language");
fuzzyMap.set("python", "Python programming language");

// Fuzzy lookups
console.log(fuzzyMap.get("javascrip")); // Matches "javascript" (distance 1)
console.log(fuzzyMap.get("Java"));      // No match (distance > 2)
console.log(fuzzyMap.has("pythom"));    // true (matches "python")