Skip to content

HashMap

Stores key/value entries in an immutable hash map.

A HashMap<Key, Value> hashes keys and resolves matches with Effect's structural equality rules. Lookup, insertion, removal, and transformation operations return new maps, while temporary mutation helpers support efficient batch updates. This module also includes constructors, iteration, conversion, mapping, filtering, and reducing helpers.

40 exports Added in v2.0.0 Source

Combining

union

Added in v2.0.0 Source

Combines two HashMaps into one.

Details

Entries from that are inserted into self; when both maps contain an equal key, the value from that replaces the value from self.

Signature

declare const union: {
  <K1, V1>(that: HashMap<K1, V1>): <K0, V0>(self: HashMap<K0, V0>) => HashMap<K1 | K0, V1 | V0>;
  <K0, V0, K1, V1>(self: HashMap<K0, V0>, that: HashMap<K1, V1>): HashMap<K0 | K1, V0 | V1>;
};

Constructors

empty

Added in v2.0.0 Source

Creates a new empty HashMap.

Signature

declare const empty: <K = never, V = never>() => HashMap<K, V>;

fromIterable

Added in v2.0.0 Source

Creates a new HashMap from an iterable collection of key/value pairs.

Signature

declare const fromIterable: <K, V>(entries: Iterable<readonly [K, V]>) => HashMap<K, V>;

make

Added in v2.0.0 Source

Constructs a new HashMap from an array of key/value pairs.

Signature

declare const make: <Entries extends ReadonlyArray<readonly [any, any]>>(
  ...entries: Entries
) => HashMap<
  Entries[number] extends readonly [infer K, any] ? K : never,
  Entries[number] extends readonly [any, infer V] ? V : never
>;

Filtering

compact

Added in v2.0.0 Source

Filters out None values from a HashMap of Optionss.

Signature

declare const compact: <K, A>(self: HashMap<K, Option<A>>) => HashMap<K, A>;

filter

Added in v2.0.0 Source

Filters entries out of a HashMap using the specified predicate.

Signature

declare const filter: {
  <K, A>(f: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => HashMap<K, A>;
  <K, A>(self: HashMap<K, A>, f: (a: A, k: K) => boolean): HashMap<K, A>;
};

filterMap

Added in v2.0.0 Source

Maps over the entries of the HashMap using the specified filter and keeps only successful results.

Signature

declare const filterMap: {
  <A, K, B, X>(f: (input: A, key: K) => Result<B, X>): (self: HashMap<K, A>) => HashMap<K, B>;
  <K, A, B, X>(self: HashMap<K, A>, f: (input: A, key: K) => Result<B, X>): HashMap<K, B>;
};

Folding

reduce

Added in v2.0.0 Source

Reduces the specified state over the entries of the HashMap.

Signature

declare const reduce: {
  <Z, V, K>(zero: Z, f: (accumulator: Z, value: V, key: K) => Z): (self: HashMap<K, V>) => Z;
  <K, V, Z>(self: HashMap<K, V>, zero: Z, f: (accumulator: Z, value: V, key: K) => Z): Z;
};

Getters

entries

Added in v2.0.0 Source

Returns an IterableIterator of the entries within the HashMap.

Signature

declare const entries: <K, V>(self: HashMap<K, V>) => IterableIterator<[K, V]>;

get

Added in v2.0.0 Source

Looks up the value for the specified key in the HashMap safely using the internal hashing function.

Signature

declare const get: {
  <K1, K>(key: K1): <V>(self: HashMap<K, V>) => Option<V>;
  <K1, K, V>(self: HashMap<K, V>, key: K1): Option<V>;
};

getHash

Added in v2.0.0 Source

Looks up the value for the specified key in the HashMap safely using a custom hash.

Signature

declare const getHash: {
  <K1, K>(key: K1, hash: number): <V>(self: HashMap<K, V>) => Option<V>;
  <K1, K, V>(self: HashMap<K, V>, key: K1, hash: number): Option<V>;
};

keys

Added in v2.0.0 Source

Returns an IterableIterator of the keys within the HashMap.

Signature

declare const keys: <K, V>(self: HashMap<K, V>) => IterableIterator<K>;

size

Added in v2.0.0 Source

Returns the number of entries within the HashMap.

Signature

declare const size: <K, V>(self: HashMap<K, V>) => number;

toEntries

Added in v2.0.0 Source

Returns an Array<[K, V]> of the entries within the HashMap.

Signature

declare function toEntries<K, V>(self: HashMap<K, V>): Array<[K, V]>;

toValues

Added in v3.13.0 Source

Returns an Array of the values within the HashMap.

Signature

declare function toValues<K, V>(self: HashMap<K, V>): Array<V>;

values

Added in v2.0.0 Source

Returns an IterableIterator of the values within the HashMap.

Signature

declare const values: <K, V>(self: HashMap<K, V>) => IterableIterator<V>;

Guards

isHashMap

Added in v2.0.0 Source

Checks whether a value is a HashMap.

Signature

declare const isHashMap: {
  <K, V>(u: Iterable<readonly [K, V]>): u is HashMap<K, V>;
  (u: unknown): u is HashMap<unknown, unknown>;
};

Mapping

map

Added in v2.0.0 Source

Maps over the entries of the HashMap using the specified function.

Signature

declare const map: {
  <A, V, K>(f: (value: V, key: K) => A): (self: HashMap<K, V>) => HashMap<K, A>;
  <K, V, A>(self: HashMap<K, V>, f: (value: V, key: K) => A): HashMap<K, A>;
};

Models

HashMap interface

Added in v2.0.0 Source

A HashMap is an immutable key-value data structure that provides efficient lookup, insertion, and deletion operations. It uses a Hash Array Mapped Trie (HAMT) internally for structural sharing and optimal performance.

Signature

interface HashMap<out Key, out Value> extends Iterable<[Key, Value]>, Equal, Pipeable, Inspectable {
  readonly "~effect/collections/HashMap": "~effect/collections/HashMap";
}

Mutations

beginMutation

Added in v2.0.0 Source

Creates a transient mutable HashMap for efficient batched updates.

Details

Apply updates to the returned map, then call endMutation to finish the mutation window and use the result as an immutable HashMap.

Signature

declare const beginMutation: <K, V>(self: HashMap<K, V>) => HashMap<K, V>;

endMutation

Added in v2.0.0 Source

Marks the HashMap as immutable, completing the mutation cycle.

Signature

declare const endMutation: <K, V>(self: HashMap<K, V>) => HashMap<K, V>;

mutate

Added in v2.0.0 Source

Runs a batch of updates against a transient mutable copy of the HashMap and returns the finalized immutable result.

Details

The callback may call mutation-oriented helpers such as set and remove on the transient map.

Signature

declare const mutate: {
  <K, V>(f: (self: HashMap<K, V>) => void): (self: HashMap<K, V>) => HashMap<K, V>;
  <K, V>(self: HashMap<K, V>, f: (self: HashMap<K, V>) => void): HashMap<K, V>;
};

Other

HashMap

Added in v2.0.0 Source

The HashMap namespace contains type-level utilities and helper types for working with HashMap instances.

Predicates

every

Added in v3.14.0 Source

Checks whether all entries in a hashmap meets a specific condition.

Signature

declare const every: {
  <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => boolean;
  <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): boolean;
};

has

Added in v2.0.0 Source

Checks whether the specified key has an entry in the HashMap.

Signature

declare const has: {
  <K1, K>(key: K1): <K, V>(self: HashMap<K, V>) => boolean;
  <K1, K, V>(self: HashMap<K, V>, key: K1): boolean;
};

hasBy

Added in v3.16.0 Source

Checks whether an element matching the given predicate exists in the given HashMap.

Signature

declare const hasBy: {
  <K, V>(
    predicate: (value: NoInfer<V>, key: NoInfer<K>) => boolean,
  ): (self: HashMap<K, V>) => boolean;
  <K, V>(self: HashMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>) => boolean): boolean;
};

hasHash

Added in v2.0.0 Source

Checks whether the specified key has an entry in the HashMap using a custom hash.

Signature

declare const hasHash: {
  <K1, K>(key: K1, hash: number): <V>(self: HashMap<K, V>) => boolean;
  <K1, K, V>(self: HashMap<K, V>, key: K1, hash: number): boolean;
};

isEmpty

Added in v2.0.0 Source

Checks whether the HashMap contains no entries.

Signature

declare const isEmpty: <K, V>(self: HashMap<K, V>) => boolean;

some

Added in v3.13.0 Source

Checks whether any entry in a hashmap meets a specific condition.

Signature

declare const some: {
  <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => boolean;
  <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): boolean;
};

Searching

findFirst

Added in v2.0.0 Source

Returns the first element that satisfies the specified predicate, or None if no such element exists.

Signature

declare const findFirst: {
  <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => Option<[K, A]>;
  <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): Option<[K, A]>;
};

Sequencing

flatMap

Added in v2.0.0 Source

Maps each entry to a HashMap and flattens the results.

Gotchas

The hash and equality behavior of both maps have to be the same.

Signature

declare const flatMap: {
  <A, K, B>(f: (value: A, key: K) => HashMap<K, B>): (self: HashMap<K, A>) => HashMap<K, B>;
  <K, A, B>(self: HashMap<K, A>, f: (value: A, key: K) => HashMap<K, B>): HashMap<K, B>;
};

Transforming

modify

Added in v2.0.0 Source

Updates the value of the specified key within the HashMap if it exists.

Signature

declare const modify: {
  <K, V>(key: K, f: (v: V) => V): (self: HashMap<K, V>) => HashMap<K, V>;
  <K, V>(self: HashMap<K, V>, key: K, f: (v: V) => V): HashMap<K, V>;
};

modifyAt

Added in v2.0.0 Source

Sets or removes the specified key using an update function.

Details

The update function receives Some(value) when the key exists or None when it does not. Returning Some(newValue) stores the value, and returning None removes the key or leaves it absent.

Signature

declare const modifyAt: {
  <K, V>(key: K, f: UpdateFn<V>): (self: HashMap<K, V>) => HashMap<K, V>;
  <K, V>(self: HashMap<K, V>, key: K, f: UpdateFn<V>): HashMap<K, V>;
};

modifyHash

Added in v2.0.0 Source

Sets or removes the specified key using a precomputed hash and an update function.

Details

The update function receives Some(value) when the key exists or None when it does not. Returning Some(newValue) stores the value, and returning None removes the key or leaves it absent.

Signature

declare const modifyHash: {
  <K, V>(key: K, hash: number, f: UpdateFn<V>): (self: HashMap<K, V>) => HashMap<K, V>;
  <K, V>(self: HashMap<K, V>, key: K, hash: number, f: UpdateFn<V>): HashMap<K, V>;
};

remove

Added in v2.0.0 Source

Removes the entry for the specified key in the HashMap using the internal hashing function.

Signature

declare const remove: {
  <K>(key: K): <V>(self: HashMap<K, V>) => HashMap<K, V>;
  <K, V>(self: HashMap<K, V>, key: K): HashMap<K, V>;
};

removeMany

Added in v2.0.0 Source

Removes all entries in the HashMap which have the specified keys.

Signature

declare const removeMany: {
  <K>(keys: Iterable<K>): <V>(self: HashMap<K, V>) => HashMap<K, V>;
  <K, V>(self: HashMap<K, V>, keys: Iterable<K>): HashMap<K, V>;
};

set

Added in v2.0.0 Source

Sets the specified key to the specified value using the internal hashing function.

Signature

declare const set: {
  <K, V>(key: K, value: V): (self: HashMap<K, V>) => HashMap<K, V>;
  <K, V>(self: HashMap<K, V>, key: K, value: V): HashMap<K, V>;
};

setMany

Added in v4.0.0 Source

Sets multiple key-value pairs in the HashMap.

Signature

declare const setMany: {
  <K, V>(entries: Iterable<readonly [K, V]>): (self: HashMap<K, V>) => HashMap<K, V>;
  <K, V>(self: HashMap<K, V>, entries: Iterable<readonly [K, V]>): HashMap<K, V>;
};

Traversing

forEach

Added in v2.0.0 Source

Applies the specified function to the entries of the HashMap.

Signature

declare const forEach: {
  <V, K>(f: (value: V, key: K) => void): (self: HashMap<K, V>) => void;
  <V, K>(self: HashMap<K, V>, f: (value: V, key: K) => void): void;
};

Unsafe

getUnsafe

Added in v4.0.0 Source

Looks up the value for the specified key in the HashMap unsafely using the internal hashing function.

When to use

Use when reading from a HashMap by a key known to exist, and throwing is an acceptable programming error for a missing key.

Gotchas

This function throws an error if the key is not found. Use HashMap.get for safe access that returns Option.

Signature

declare const getUnsafe: {
  <K1, K>(key: K1): <V>(self: HashMap<K, V>) => V;
  <K1, K, V>(self: HashMap<K, V>, key: K1): V;
};