MutableHashMap

Stores key/value entries in a mutable hash map.

MutableHashMap updates the same collection in place and supports fast lookup, insertion, removal, clearing, and iteration. It combines a native Map for ordinary JavaScript keys with hash buckets for keys that implement Effect Equal and Hash, so callers can mix reference-based and structural lookup in the same collection.

17 exports Added in v2.0.0 Source

Constructors

empty

Added in v2.0.0 Source

Creates an empty MutableHashMap.

When to use

Use to create a fresh mutable map before adding entries over time.

Details

Each call returns a new empty map instance.

See

make for creating a map from explicit entries
fromIterable for creating a map from an iterable of entries

Signature

declare function empty<K, V>(): MutableHashMap<K, V>

Example

(Creating an empty map)

import { MutableHashMap } from "effect"

const map = MutableHashMap.empty<string, number>()

// Add some entries
MutableHashMap.set(map, "key1", 42)
MutableHashMap.set(map, "key2", 100)

MutableHashMap.size(map) // => 2

fromIterable

Added in v2.0.0 Source

Creates a MutableHashMap from an iterable collection of key-value pairs.

When to use

Use to create a mutable hash map from an existing iterable of entries.

See

make for creating a map from explicit entries
empty for creating an empty map

Signature

declare function fromIterable<K, V>(entries: Iterable<readonly [K, V]>): MutableHashMap<K, V>

Example

(Creating a map from an iterable)

import { MutableHashMap, Option } from "effect"

const entries = [
  ["apple", 1],
  ["banana", 2],
  ["cherry", 3]
] as const

const map = MutableHashMap.fromIterable(entries)

MutableHashMap.get(map, "banana") // => Option.some(2)
MutableHashMap.size(map) // => 3

// Works with any iterable
const fromMap = MutableHashMap.fromIterable(new Map([["x", 10], ["y", 20]]))
MutableHashMap.get(fromMap, "x") // => Option.some(10)

make

Added in v2.0.0 Source

Creates a MutableHashMap from a variable number of key-value pairs.

When to use

Use to create a mutable hash map from explicit entries known at the call site.

See

empty for creating an empty map
fromIterable for creating a map from an iterable of entries

Signature

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

Example

(Creating a map from entries)

import { MutableHashMap, Option } from "effect"

const map = MutableHashMap.make(
  ["key1", 42],
  ["key2", 100],
  ["key3", 200]
)

MutableHashMap.get(map, "key1") // => Option.some(42)
MutableHashMap.size(map) // => 3

Getters

get

Added in v2.0.0 Source

Looks up a key in the MutableHashMap safely.

When to use

Use to safely read a MutableHashMap value for a key as an Option.

Details

Returns Some(value) when an equal key is present and None when the key is absent.

See

has for checking only whether a key is present
set for inserting or replacing a value by key

Signature

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

Example

(Getting a value)

import { MutableHashMap, Option } from "effect"

const map = MutableHashMap.make(["key1", 42], ["key2", 100])

MutableHashMap.get(map, "key1") // => Option.some(42)
MutableHashMap.get(map, "key3") // => Option.none()

// Pipe-able version
MutableHashMap.get("key1")(map) // => Option.some(42)

keys

Added in v3.8.0 Source

Returns an iterable over the keys in the MutableHashMap.

When to use

Use to iterate over the keys currently stored in a mutable hash map.

See

values for iterating over stored values
has for checking one key without iterating

Signature

declare function keys<K, V>(self: MutableHashMap<K, V>): Iterable<K>

Example

(Reading keys)

import { MutableHashMap } from "effect"

const map = MutableHashMap.make(
  ["apple", 1],
  ["banana", 2],
  ["cherry", 3]
)

Array.from(MutableHashMap.keys(map)) // => ["apple", "banana", "cherry"]

size

Added in v2.0.0 Source

Returns the number of key-value pairs in the MutableHashMap.

When to use

Use to read how many entries are currently stored in the mutable hash map.

See

isEmpty for checking whether the map has no entries

Signature

declare function size<K, V>(self: MutableHashMap<K, V>): number

Example

(Checking map size)

import { MutableHashMap } from "effect"

const map = MutableHashMap.empty<string, number>()
MutableHashMap.size(map) // => 0

MutableHashMap.set(map, "key1", 42)
MutableHashMap.set(map, "key2", 100)
MutableHashMap.size(map) // => 2

MutableHashMap.remove(map, "key1")
MutableHashMap.size(map) // => 1

MutableHashMap.clear(map)
MutableHashMap.size(map) // => 0

values

Added in v3.8.0 Source

Returns an iterable over the values in the MutableHashMap.

When to use

Use to iterate over the values currently stored in a mutable hash map.

See

keys for iterating over stored keys

Signature

declare function values<K, V>(self: MutableHashMap<K, V>): Iterable<V>

Example

(Reading values)

import { MutableHashMap } from "effect"

const map = MutableHashMap.make(
  ["apple", 1],
  ["banana", 2],
  ["cherry", 3]
)

const allValues = Array.from(MutableHashMap.values(map)) // => [1, 2, 3]

// Useful for calculations
allValues.reduce((sum, value) => sum + value, 0) // => 6

// Filter values
allValues.filter((value) => value > 1) // => [2, 3]

Guards

isMutableHashMap

Added in v4.0.0 Source

Checks whether the specified value is a MutableHashMap, false otherwise.

When to use

Use to narrow an unknown value before treating it as a mutable hash map.

Details

The check looks for the MutableHashMap runtime marker.

Gotchas

The check does not validate the key or value types carried by the map.

See

MutableHashMap for the mutable hash map interface

Signature

declare function isMutableHashMap<K, V>(value: unknown): value is MutableHashMap<K, V>

Models

MutableHashMap interface

Added in v2.0.0 Source

A mutable hash map that stores key-value pairs and supports both referential and Effect structural equality.

When to use

Use as a mutable key-value map when in-place updates are acceptable and keys may rely on Effect structural equality.

Details

Operations mutate the map in place. Keys that implement Equal / Hash can be looked up structurally; other keys use normal JavaScript reference or primitive equality.

See

empty for creating an empty mutable hash map
get for reading values by key
set for mutating entries by key

Signature

interface MutableHashMap<out K, out V> extends Iterable<[K, V]>, Pipeable, Inspectable {
  readonly "~effect/collections/MutableHashMap": "~effect/collections/MutableHashMap";
  readonly backing: Map<K, V>;
  readonly buckets: Map<number, [K, ...Array<K>]>;
}

Example

(Using a mutable hash map)

import { MutableHashMap } from "effect"

// Create a mutable hash map with string keys and number values
const map: MutableHashMap.MutableHashMap<string, number> = MutableHashMap
  .empty()

// Add some data
MutableHashMap.set(map, "count", 42)
MutableHashMap.set(map, "total", 100)

Array.from(map) // => [["count", 42], ["total", 100]]

Mutations

clear

Added in v2.0.0 Source

Removes all key-value pairs from the MutableHashMap, mutating the map in place. The map becomes empty after this operation.

When to use

Use to empty a mutable hash map while keeping the same map instance.

See

remove for deleting one key
empty for creating a fresh empty map

Signature

declare function clear<K, V>(self: MutableHashMap<K, V>): MutableHashMap<K, V>

Example

(Clearing all entries)

import { MutableHashMap } from "effect"

const map = MutableHashMap.make(
  ["key1", 42],
  ["key2", 100],
  ["key3", 200]
)

MutableHashMap.size(map) // => 3

// Clear all entries
MutableHashMap.clear(map)

MutableHashMap.size(map) // => 0
MutableHashMap.has(map, "key1") // => false

// Can still add new entries after clearing
MutableHashMap.set(map, "new", 999)
Array.from(map) // => [["new", 999]]

modify

Added in v2.0.0 Source

Updates the value of the specified key within the MutableHashMap if it exists. If the key doesn't exist, the map remains unchanged.

When to use

Use to transform an existing MutableHashMap value in place without inserting missing keys.

See

set for inserting or replacing a value directly
modifyAt for handling both missing and existing keys

Signature

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

Example

(Modifying existing values)

import { MutableHashMap, Option } from "effect"

const map = MutableHashMap.make(["count", 5], ["total", 100])

// Increment existing value
MutableHashMap.modify(map, "count", (n) => n + 1)
MutableHashMap.get(map, "count") // => Option.some(6)

// Double existing value
MutableHashMap.modify(map, "total", (n) => n * 2)
MutableHashMap.get(map, "total") // => Option.some(200)

// Try to modify non-existent key (no effect)
MutableHashMap.modify(map, "missing", (n) => n + 1)
MutableHashMap.has(map, "missing") // => false

// Pipe-able version
MutableHashMap.modify("count", (n: number) => n + 1)(map)
MutableHashMap.get(map, "count") // => Option.some(7)

modifyAt

Added in v2.0.0 Source

Updates or removes the specified key using a function from the current optional value to the next optional value.

When to use

Use to decide whether to insert, update, or remove a key based on its current optional value.

See

modify for updating only when the key already exists
set for inserting or replacing directly
remove for deleting directly

Signature

declare const modifyAt: {
  <K, V>(key: K, f: (value: Option<V>) => Option<V>): (self: MutableHashMap<K, V>) => MutableHashMap<K, V>;
  <K, V>(self: MutableHashMap<K, V>, key: K, f: (value: Option<V>) => Option<V>): MutableHashMap<K, V>;
}

Example

(Updating or removing a key)

import { MutableHashMap, Option } from "effect"

const map = MutableHashMap.make(["count", 5])

// Update existing key
MutableHashMap.modifyAt(
  map,
  "count",
  (option) => Option.map(option, (n) => n * 2)
)
MutableHashMap.get(map, "count") // => Option.some(10)

// Add new key
MutableHashMap.modifyAt(
  map,
  "new",
  (option) => Option.isNone(option) ? Option.some(42) : option
)
MutableHashMap.get(map, "new") // => Option.some(42)

// Remove key by returning None
MutableHashMap.modifyAt(map, "count", () => Option.none())
MutableHashMap.get(map, "count") // => Option.none()

// Conditional update
MutableHashMap.modifyAt(
  map,
  "new",
  (option) => Option.filter(option, (n) => n > 50) // Remove if <= 50
)
MutableHashMap.get(map, "new") // => Option.none()

remove

Added in v2.0.0 Source

Removes the specified key from the MutableHashMap, mutating the map in place. If the key doesn't exist, the map remains unchanged.

When to use

Use to delete one key from a mutable hash map in place.

See

clear for removing all entries
modifyAt for conditionally removing based on the current value

Signature

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

Example

(Removing a key)

import { MutableHashMap } from "effect"

const map = MutableHashMap.make(
  ["key1", 42],
  ["key2", 100],
  ["key3", 200]
)

MutableHashMap.size(map) // => 3

// Remove existing key
MutableHashMap.remove(map, "key2")
MutableHashMap.size(map) // => 2
MutableHashMap.has(map, "key2") // => false

// Remove non-existent key (no effect)
MutableHashMap.remove(map, "nonexistent")
MutableHashMap.size(map) // => 2

// Pipe-able version
MutableHashMap.remove("key1")(map)
MutableHashMap.size(map) // => 1

set

Added in v2.0.0 Source

Sets a key-value pair in the MutableHashMap, mutating the map in place. If the key already exists, its value is updated.

When to use

Use to insert a new MutableHashMap entry or replace an existing entry in place.

See

modify for updating an existing value with a function
modifyAt for setting or removing based on the current optional value
remove for deleting an entry by key

Signature

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

Example

(Setting key-value pairs)

import { MutableHashMap, Option } from "effect"

const map = MutableHashMap.empty<string, number>()

// Add new entries
MutableHashMap.set(map, "key1", 42)
MutableHashMap.set(map, "key2", 100)

MutableHashMap.get(map, "key1") // => Option.some(42)
MutableHashMap.size(map) // => 2

// Update existing entry
MutableHashMap.set(map, "key1", 999)
MutableHashMap.get(map, "key1") // => Option.some(999)

// Pipe-able version
MutableHashMap.set("key3", 300)(map)
MutableHashMap.size(map) // => 3

Predicates

has

Added in v2.0.0 Source

Checks whether the MutableHashMap contains the specified key.

When to use

Use to test whether a key is present in a MutableHashMap without reading its value.

See

get for reading the value as an Option

Signature

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

Example

(Checking for a key)

import { MutableHashMap } from "effect"

const map = MutableHashMap.make(["key1", 42], ["key2", 100])

MutableHashMap.has(map, "key1") // => true
MutableHashMap.has(map, "key3") // => false

// Pipe-able version
MutableHashMap.has("key1")(map) // => true

isEmpty

Added in v2.0.0 Source

Returns true when the MutableHashMap contains no key-value pairs.

When to use

Use to branch on whether a mutable map currently has any entries.

See

size for reading the exact number of entries

Signature

declare function isEmpty<K, V>(self: MutableHashMap<K, V>): boolean

Traversing

forEach

Added in v2.0.0 Source

Runs a callback for each key-value pair in the MutableHashMap.

When to use

Use to run a synchronous side-effecting callback for every key-value pair in an existing mutable map.

Details

Iteration follows the backing map's order. The callback receives the value first and the key second, matching Map.prototype.forEach.

See

keys for iterating only keys
values for iterating only values

Signature

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