Implement HashMap similar to Python's dict

package.json

@@ -54,5 +54,8 @@
   },
   "engines": {
     "node": ">=10.6.0"
+  },
+  "dependencies": {
+    "ts-essentials": "^9.4.2"
   }
 }

src/__tests__/hashable.spec.ts

@@ -0,0 +1,73 @@
+import {Primitive} from 'ts-essentials';
+import {HashMap, Hashable} from '../hashable';
+import {PRIMES} from '../primes';
+import {Monzo, monzosEqual} from '../monzo';
+import {describe, it, expect} from 'vitest';
+
+/**
+ * Partial implementation of a rational number capable of holding very large values with a limited number of prime factors.
+ */
+class ImmutableMonzo extends Hashable {
+  vector: Readonly<Monzo>;
+
+  constructor(vector: Readonly<Monzo>) {
+    super();
+    this.vector = vector;
+  }
+
+  valueOf(): number {
+    let value = 1;
+    for (let i = 0; i < this.vector.length; ++i) {
+      value *= PRIMES[i] ** this.vector[i];
+    }
+    return value;
+  }
+
+  strictEquals(other: Hashable | Primitive): boolean {
+    if (other instanceof ImmutableMonzo) {
+      return monzosEqual(this.vector, other.vector);
+    }
+    return false;
+  }
+}
+
+function M(vector: Readonly<Monzo>) {
+  return Object.freeze(new ImmutableMonzo(Object.freeze(vector)));
+}
+
+describe('Hash-map / dictionary', () => {
+  it('can set / get keys that hash to the same value', () => {
+    const thirty = M([1, 1, 1]);
+    const big = M([100000]);
+    const alsoBig = M([-1, 1000]);
+    expect(thirty.valueOf()).toBe(30);
+    expect(big.valueOf()).toBe(alsoBig.valueOf());
+
+    const map = new HashMap<number | ImmutableMonzo, string>([
+      [30, 'number'],
+      [thirty, 'thirty'],
+      [big, 'biig'], // Oops typo. To be overriden.
+    ]);
+
+    map.set(alsoBig, 'also big');
+    map.set(M([100000]), 'big');
+
+    expect(map.get(30)).toBe('number');
+    expect(map.get(M([1, 1, 1]))).toBe('thirty');
+    expect(map.get(M([100000]))).toBe('big');
+    expect(map.get(M([-1, 1000]))).toBe('also big');
+
+    expect(map.size).toBe(4);
+  });
+
+  it('can be cleared', () => {
+    const map = new HashMap();
+    map.set(3, 4);
+    expect(map.size).toBe(1);
+    map.clear();
+    expect(map.size).toBe(0);
+    expect(map.get(3)).toBe(undefined);
+  });
+
+  // TODO: Rest of the methods of HashMap
+});

src/__tests__/index.spec.ts

@@ -1,7 +1,6 @@
 import {describe, it, expect} from 'vitest';
 import {
   Fraction,
-  FractionSet,
   arraysEqual,
   binomial,
   ceilPow2,
@@ -19,7 +18,10 @@ import {
   iteratedEuclid,
   norm,
   valueToCents,
+  F,
 } from '../index';
+import {HashMap, HashSet, Hashable} from '../hashable';
+import {DeepReadonly, Primitive} from 'ts-essentials';
 
 describe('Array equality tester', () => {
   it('works on integer arrays', () => {
@@ -207,11 +209,11 @@ describe('Farey sequence generator', () => {
   });
 
   it('agrees with the brute force method', () => {
-    const everything = new FractionSet();
+    const everything = new HashSet<DeepReadonly<Fraction>>();
     const N = Math.floor(Math.random() * 50) + 1;
     for (let d = 1; d <= N; ++d) {
       for (let n = 0; n <= d; ++n) {
-        everything.add(new Fraction(n, d));
+        everything.add(F(n, d));
       }
     }
     const brute = Array.from(everything);
@@ -254,11 +256,11 @@ describe('Farey interior generator', () => {
   });
 
   it('agrees with the brute force method', () => {
-    const everything = new FractionSet();
+    const everything = new HashSet<DeepReadonly<Fraction>>();
     const N = Math.floor(Math.random() * 50) + 1;
     for (let d = 1; d <= N; ++d) {
       for (let n = 1; n < d; ++n) {
-        everything.add(new Fraction(n, d));
+        everything.add(F(n, d));
       }
     }
     const brute = Array.from(everything);
@@ -382,3 +384,52 @@ describe('Constant structure checker with a margin of equivalence', () => {
     expect(hasMarginConstantStructure([1199, 1200], 2)).toBe(false);
   });
 });
+
+describe('Fractions as hashmap keys', () => {
+  it('can override values using equivalent keys', () => {
+    const hashMap = new HashMap([
+      [F(3, 2), 'fif'],
+      [F(2), 'octave'],
+    ]);
+    hashMap.set(F('5/4'), 'third');
+    hashMap.set(F(1.5), 'fifth');
+    const entries = Array.from(hashMap).sort((a, b) => a[0].compare(b[0]));
+    expect(entries).toEqual([
+      [{s: 1, n: 5, d: 4}, 'third'],
+      [{s: 1, n: 3, d: 2}, 'fifth'],
+      [{s: 1, n: 2, d: 1}, 'octave'],
+    ]);
+  });
+
+  it('plays nicely with mixed keys and mixed data', () => {
+    class OtherHashable extends Hashable {
+      name: string;
+      constructor(name: string) {
+        super();
+        this.name = name;
+      }
+      valueOf(): string {
+        return this.name;
+      }
+      strictEquals(other: Hashable | Primitive): boolean {
+        if (other instanceof OtherHashable) {
+          return this.name === other.name;
+        }
+        return false;
+      }
+    }
+    const hashMap = new HashMap<
+      number | string | Fraction | OtherHashable,
+      string | number | boolean
+    >([
+      [1, 'one'],
+      [F(1), 'other one'],
+      ['1', 1],
+      [Object.freeze(new OtherHashable('1')), true],
+    ]);
+    expect(hashMap.get(1)).toBe('one');
+    expect(hashMap.get(F('7/7'))).toBe('other one');
+    expect(hashMap.get('1')).toBe(1);
+    expect(hashMap.get(Object.freeze(new OtherHashable('1')))).toBe(true);
+  });
+});

src/fraction.ts

@@ -3,6 +3,8 @@
 
 import {valueToCents} from './conversion';
 import {PRIMES} from './primes';
+import {Hashable} from './hashable';
+import {DeepReadonly, Primitive} from 'ts-essentials';
 
 export type UnsignedFraction = {n: number; d: number};
 
@@ -76,7 +78,7 @@ export function mmod(a: number, b: number) {
  * new Fraction("13e-3");  // scientific notation
  * ```
  */
-export class Fraction {
+export class Fraction extends Hashable {
   /** Sign: +1, 0 or -1 */
   s: number;
   /** Numerator */
@@ -85,6 +87,7 @@ export class Fraction {
   d: number;
 
   constructor(numerator: FractionValue, denominator?: number) {
+    super();
     if (denominator !== undefined) {
       if (typeof numerator !== 'number') {
         throw new Error('Numerator must be a number when denominator is given');
@@ -831,6 +834,24 @@ export class Fraction {
     }
   }
 
+  /**
+   * Check if two {@link Fraction} instances represent the same rational number.
+   * Returns `false` for other {@link Hashable} objects.
+   * Examples:
+   * ```ts
+   * new Fraction("19.7").strictEquals(new Fraction("98/5")) // false
+   * new Fraction("19.6").strictEquals(new Fraction("98/5")) // true
+   * new Fraction("19.5").strictEquals(new Fraction("98/5")) // false
+   * ```
+   **/
+  strictEquals(other: Hashable | Primitive) {
+    if (other instanceof Fraction) {
+      const {s, n, d} = other;
+      return this.s === s && this.n === n && this.d === d;
+    }
+    return false;
+  }
+
   /**
    * Check if two rational numbers are divisible
    * (i.e. this is an integer multiple of other)
@@ -1114,3 +1135,16 @@ export class Fraction {
     return other_.pow(exponent);
   }
 }
+
+/**
+ * Construct an immutable {@link Fraction} instance suitable for a key in a {@link HashMap} or a value in {@link HashSet}.
+ * @param numerator Integer numerator, floating point value, string or another {@link Fraction} to convert.
+ * @param denominator Integer denominator (defaults to `1`).
+ * @returns An immutable rational number.
+ */
+export function F(
+  numerator: FractionValue,
+  denominator?: number
+): DeepReadonly<Fraction> {
+  return Object.freeze(new Fraction(numerator, denominator));
+}