Class HashMap<TKey, TValue, THashedKey>

constructor

• new HashMap<TKey, TValue, THashedKey = TKey>(
      hash: (key: TKey) => THashedKey,
      _map?: Map<THashedKey, TValue>,
      name?: string,
  ): HashMap<TKey, TValue, THashedKey>

  Type Parameters

  • TKey
  • TValue
  • THashedKey = TKey

  Parameters

  • hash: (key: TKey) => THashedKey

    Function called to hash a key before storing or using it to access a value in the map.
  • _map: Map<THashedKey, TValue> = ...

    Internal data structure that we use to store the entries in the map.
  • name: string = "unknown"

    Human readable name for the map instance that is used for debugging purposes.

  Returns HashMap<TKey, TValue, THashedKey>

Readonlyhash

Readonlyname

StaticMissingKeyError

[iterator]

• "[iterator]"(): Iterator<[THashedKey, TValue]>

  Get the iterator over the entires in this map.

  Returns Iterator<[THashedKey, TValue]>

  The entries in this map as an array of key-value pairs.

clear

• clear(): void

  Clears all of the entries in this map.

  Returns void

  Remarks

  This function will mutate the map instance it is called on.

  Example

  const map = HashMap.fromEntries<number, string>([
    [1, "one"],
    [2, "two"],
    [3, "three"],
  ]);
  
  map.clear();
  
  [...map]; // => []
  Copy

delete

• delete(key: TKey): void

  Delete an entry from this map by its key, throwing a HashMap.MissingKeyError if the key does not exist in this map.

  Parameters

  • key: TKey

    The key of the entry to delete.

  Returns void

  Example

  const map = HashMap.fromEntries<number, string>([
    [1, "one"],
    [2, "two"],
    [3, "three"],
  ]);
  
  map.delete(2);
  
  [...map];
  // => [
  //   [1, "one"],
  //   [3, "three"],
  // ]
  
  map.delete(4); // throws HashMap.MissingKeyError
  Copy

  Throws

  HashMap.MissingKeyError if the key does not exist in this map.

deleteIfExists

• deleteIfExists(key: TKey): boolean

  Delete an entry from this map by its key and returns true if it exists, otherwise it simply returns false.

  Parameters

  • key: TKey

    The key of the entry to delete.

  Returns boolean

  true if the key existed and the entry was deleted, false if the key did not exist.

  Example

  const map = HashMap.fromEntries<number, string>([
    [1, "one"],
    [2, "two"],
    [3, "three"],
  ]);
  
  map.deleteIfExists(2); // => true
  map.deleteIfExists(4); // => false
  
  [...map];
  // => [
  //   [1, "one"],
  //   [3, "three"],
  // ]
  Copy

entries

• entries(): IterableIterator<[THashedKey, TValue]>

  Returns the entries in this map as an IterableIterator which each entry as an array of [key, value].

  Returns IterableIterator<[THashedKey, TValue]>

  An IterableIterator of the entries in this map.

  Example

  const map = HashMap.fromEntries<number, string>([
    [1, "one"],
    [2, "two"],
    [3, "three"],
  ]);
  
  [...map.entries()];
  // => [
  //   [1, "one"],
  //   [2, "two"],
  //   [3, "three"],
  // ]
  Copy

filter

• filter(
      fn: HashMapFilterFn<TKey, TValue, THashedKey>,
  ): HashMap<TKey, TValue, THashedKey>

  Returns a new map with only the key-value pairs where the given function returns true, filtering out those that the given function returns false for.

  Parameters

  • fn: HashMapFilterFn<TKey, TValue, THashedKey>

    Function called for each key-value pair in the map that returns true to include the pair in the new map or false to exclude it.

  Returns HashMap<TKey, TValue, THashedKey>

  A new map with only the key-value pairs where the given function returned true for.

  Remarks

  This function does not mutate the original map instance unless you call a mutating function on the map (4th argument) inside the given function.

  Example: Include entries where key is greater than 2

  const map = HashMap.fromEntries<number, string>([
    [1, "one"],
    [2, "two"],
    [3, "three"],
    [4, "four"],
  ]);
  
  const filtered = map.filter((value, key) => key > 2);
  
  [...filtered];
  // => [
  //   [3, "three"],
  //   [4, "four"],
  // ]
  Copy

  Example: Include entries where the value has a length greater than 3

  const map = HashMap.fromEntries<number, string>([
    [1, "one"],
    [2, "two"],
    [3, "three"],
    [4, "four"],
  ]);
  
  const filtered = map.filter((value) => value.length > 3);
  
  [...filtered];
  // => [
  //   [3, "three"],
  //   [4, "four"],
  // ]
  Copy

get

• get(key: TKey): TValue

  Get the value with the given key from this map, throwing a HashMap.MissingKeyError if the key does not exist.

  Parameters

  • key: TKey

    The key of the value to get.

  Returns TValue

  The value with the given key.

  Example

  const map = HashMap.fromEntries([
    [1, "one"],
    [2, "two"],
    [3, "three"]
  ]);
  
  map.get(2) // => "two"
  
  map.get(4) // => throws HashMap.MissingKeyError
  Copy

getOr

• getOr<TDefaultValue = TValue>(
      key: TKey,
      defaultValue: TDefaultValue,
  ): TValue | TDefaultValue

  Get the value with the given key from this map if it exists, otherwise return the given default value.

  Type Parameters

  • TDefaultValue = TValue

  Parameters

  • key: TKey

    The key whose associated value is to be returned.
  • defaultValue: TDefaultValue

    The value to return if the key is not found.

  Returns TValue | TDefaultValue

  • The value associated with the specified key, or the default value if the key does not exist.

has

• has(key: TKey): boolean

  Checks if this map has an entry with the given key.

  Parameters

  • key: TKey

    The key to check for.

  Returns boolean

  true if the key exists in this map, false otherwise.

keys

• keys(): IterableIterator<THashedKey>

  Get the keys in this map as an IterableIterator.

  Returns IterableIterator<THashedKey>

  The keys in this map as an IterableIterator.

map

• map(
      fn: (
          value: TValue,
          key: THashedKey,
          index: number,
          original: HashMap<TKey, TValue, THashedKey>,
      ) => [THashedKey, TValue],
  ): HashMap<TKey, TValue, THashedKey>

  Create a new map with entries that are the result of calling the given callback function on each of the key-value pairs in this map.

  Parameters

  • fn: (
        value: TValue,
        key: THashedKey,
        index: number,
        original: HashMap<TKey, TValue, THashedKey>,
    ) => [THashedKey, TValue]

    Function to call on each key-value pair in the map. The result of this function is used as entries in the new map.

  Returns HashMap<TKey, TValue, THashedKey>

  A new map with the new entries from calling the given function on each key-value pair in the map.

  Example: Swap the keys and values

  const map = HashMap.fromEntries([
   ["one", 1],
   ["two", 2],
   ["three", 3],
  ]);
  
  const swapped = map.map(([key, value]) => [value, key]);
  // => HashMap { 1 => "one", 2 => "two", 3 => "three" }
  Copy

mapKeys

• mapKeys(
      fn: (
          key: THashedKey,
          value: TValue,
          index: number,
          original: HashMap<TKey, TValue, THashedKey>,
      ) => THashedKey,
  ): HashMap<TKey, TValue, THashedKey>

  Create a new map with entries that have keys that are the result of calling the given callback function on each of the key-value pairs in this map.

  Parameters

  • fn: (
        key: THashedKey,
        value: TValue,
        index: number,
        original: HashMap<TKey, TValue, THashedKey>,
    ) => THashedKey

    Function to call on each key-value pair in the map. The result of this function is used as the keys for the entries in the new map.

  Returns HashMap<TKey, TValue, THashedKey>

  A new map with the entries with new keys from calling the given function on each key-value pair in the map.

  Remarks

  The new map will have the same default value as this map.

  This function does not mutate the original map instance unless you call a mutating function on the map (4th argument) inside the given function.

mapValues

• mapValues(
      fn: (
          value: TValue,
          key: THashedKey,
          index: number,
          original: HashMap<TKey, TValue, THashedKey>,
      ) => TValue,
  ): HashMap<TKey, TValue, THashedKey>

  Create a new map with entries that have values that are the result of calling the given callback function on each of the key-value pairs in this map.

  Parameters

  • fn: (
        value: TValue,
        key: THashedKey,
        index: number,
        original: HashMap<TKey, TValue, THashedKey>,
    ) => TValue

    Function to call on each key-value pair in the map. The result of this function is used as the values for the entries in the new map.

  Returns HashMap<TKey, TValue, THashedKey>

  A new map with the entries with new values from calling the given function on each key-value pair in the map.

  Remarks

  The new map will have the same default value as this map.

  This function does not mutate the original map instance unless you call a mutating function on the map (4th argument) inside the given function.

set

• set(key: TKey, value: TValue): void

  Set the value of an entry by it's key in the map, creating a new entry if one doesn't exist or overriding an existing entry if one does.

  Parameters

  • key: TKey

    The key of the entry to set.
  • value: TValue

    The value to set the entry to.

  Returns void

values

• values(): IterableIterator<TValue>

  Get the values in this map as an IterableIterator.

  Returns IterableIterator<TValue>

  The values in this map as an IterableIterator.

Staticempty

• empty<TKey, TValue>(
      options?: Omit<HashMapOptions<TKey>, "hash">,
  ): HashMap<TKey, TValue, TKey>

  Create a new empty map instance.

  Type Parameters

  • TKey
  • TValue

  Parameters

  • options: Omit<HashMapOptions<TKey>, "hash"> = {}

    Options to use to create the new map instance.

  Returns HashMap<TKey, TValue, TKey>

  A new empty map instance.

  Remarks

  This function uses the identity function as the hashing function meaning that keys will be stored without any changes.

  Example

  const map = HashMap.empty<number, string>();
  
  [...map]; // => []
  
  map.set(1, "one");
  
  [...map]; // => [[1, "one"]]
  Copy

  See

  HashMap.emptyWithCustomHash

StaticemptyWithCustomHash

• emptyWithCustomHash<TKey, TValue, THashedKey = TKey>(
      options: HashMapOptions<TKey, THashedKey>,
  ): HashMap<TKey, TValue, THashedKey>

  Create a new empty map instance with a custom hashing function.

  Type Parameters

  • TKey
  • TValue
  • THashedKey = TKey

  Parameters

  • options: HashMapOptions<TKey, THashedKey>

    Options to use to create the new map instance.

  Returns HashMap<TKey, TValue, THashedKey>

  A new empty map instance.

StaticfromCustomEntries

• fromCustomEntries<TKey, TValue, THashedKey>(
      entries: [TKey, TValue][],
      options: HashMapOptions<TKey, THashedKey>,
  ): HashMap<TKey, TValue, THashedKey>

  Create a new map instance from an array of key-value pairs with a custom hashing function.

  Type Parameters

  • TKey
  • TValue
  • THashedKey

  Parameters

  • entries: [TKey, TValue][]

    Array of key-value pairs to create the map with.
  • options: HashMapOptions<TKey, THashedKey>

    Options to use to create the new map instance.

  Returns HashMap<TKey, TValue, THashedKey>

  A new map instance with the given key-value pairs and a given custom hashing function.

  Example: Use ISO string representation of Date objects as hash keys

  const map = HashMap.fromCustomEntries(
  [
    [new Date("2020-01-01"), 1],
    [new Date("2020-02-01"), 2],
    [new Date("2020-03-01"), 3],
  ],
  {
    hash(key) {
      return key.toISOString();
    },
  });
  
  [...map];
  // => [
  //   ["2020-01-01T00:00:00.000Z", 1],
  //   ["2020-02-01T00:00:00.000Z", 2],
  //   ["2020-03-01T00:00:00.000Z", 3],
  // ];
  Copy

StaticfromEntries

• fromEntries<TKey, TValue>(
      entries: [TKey, TValue][],
      options?: Omit<HashMapOptions<TKey>, "hash">,
  ): HashMap<TKey, TValue, TKey>

  Create a new map instance from an array of key-value pairs using the identity as the hash function.

  Type Parameters

  • TKey
  • TValue

  Parameters

  • entries: [TKey, TValue][]

    Array of key-value pairs to create the map with.
  • options: Omit<HashMapOptions<TKey>, "hash"> = {}

    Options to use to create the new map instance.

  Returns HashMap<TKey, TValue, TKey>

  A new map instance with the given key-value pairs.

  Remarks

  This function uses the identity function as the hashing function meaning that keys will be stored without any changes which will therefore use the same behaviour as an ES6 Map.

  Example

  const map = HashMap.fromEntries<number, string>([
    [1, "one"],
    [2, "two"],
    [3, "three"],
  ]);
  
  [...map];
  // => [
  //   [1, "one"],
  //   [2, "two"],
  //   [3, "three"],
  // ];
  Copy