EdgeAIG's picture
download
raw
68.7 kB
/** * 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. * * @since 2.0.0 */ import type { Equal } from "./Equal.ts" import type { Inspectable } from "./Inspectable.ts" import * as internal from "./internal/hashMap.ts" import type { Option } from "./Option.ts" import type { Pipeable } from "./Pipeable.ts" import type { Result } from "./Result.ts" import type { NoInfer } from "./Types.ts" const TypeId = internal.HashMapTypeId /** * 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. * * **Example** (Using basic HashMap operations) * * ```ts * import { HashMap } from "effect" * * // Create a HashMap * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * * // Access values * const valueA = HashMap.get(map, "a") // Option.some(1) * const valueD = HashMap.get(map, "d") // Option.none() * * // Check if key exists * console.log(HashMap.has(map, "b")) // true * * // Add/update values (returns new HashMap) * const updated = HashMap.set(map, "d", 4) * console.log(HashMap.size(updated)) // 4 * ``` * * @category models * @since 2.0.0 */ export interface HashMap<out Key, out Value> extends Iterable<[Key, Value]>, Equal, Pipeable, Inspectable { readonly [TypeId]: typeof TypeId } /** * The HashMap namespace contains type-level utilities and helper types * for working with HashMap instances. * * **Example** (Extracting HashMap types) * * ```ts * import { HashMap } from "effect" * * // Create a concrete HashMap for type extraction * const inventory = HashMap.make( * ["laptop", { quantity: 5, price: 999 }], * ["mouse", { quantity: 20, price: 29 }] * ) * * // Extract types for reuse * type ProductId = HashMap.HashMap.Key<typeof inventory> // string * type Product = HashMap.HashMap.Value<typeof inventory> // { quantity: number, price: number } * type InventoryEntry = HashMap.HashMap.Entry<typeof inventory> // [string, Product] * * // Use extracted types in functions * const updateInventory = (id: ProductId, product: Product) => * HashMap.set(inventory, id, product) * * const processEntry = ([id, product]: InventoryEntry) => * `${id}: ${product.quantity} @ $${product.price}` * * // Example of extracted types in action * const newProduct: Product = { quantity: 10, price: 199 } * const updatedInventory = updateInventory("tablet", newProduct) * ``` * * @since 2.0.0 */ export declare namespace HashMap { /** * A function that updates a value based on its current state. * Takes an Option representing the current value and returns an Option * representing the new value. * * **Example** (Updating values from Options) * * ```ts * import { HashMap, Option } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * // Increment existing value or set to 1 if not present * const updateFn = (option: Option.Option<number>) => * Option.isSome(option) ? Option.some(option.value + 1) : Option.some(1) * * const updated = HashMap.modifyAt(map, "a", updateFn) * console.log(HashMap.get(updated, "a")) // Option.some(2) * ``` * * @category models * @since 2.0.0 */ export type UpdateFn<V> = (option: Option<V>) => Option<V> /** * This type-level utility extracts the key type `K` from a `HashMap<K, V>` type. * * **Example** (Extracting key types) * * ```ts * import { HashMap } from "effect" * * // Create a HashMap to extract key type from * const userMap = HashMap.make( * ["alice", { name: "Alice", age: 30 }], * ["bob", { name: "Bob", age: 25 }] * ) * * // Extract the key type (string) * type UserKey = HashMap.HashMap.Key<typeof userMap> * * // Use the extracted type in functions * const getUserById = (id: UserKey) => HashMap.get(userMap, id) * console.log(getUserById("alice")) // Option.some({ name: "Alice", age: 30 }) * ``` * * @category utility types * @since 2.0.0 */ export type Key<T extends HashMap<any, any>> = [T] extends [HashMap<infer _K, infer _V>] ? _K : never /** * This type-level utility extracts the value type `V` from a `HashMap<K, V>` type. * * **Example** (Extracting value types) * * ```ts * import { HashMap } from "effect" * * // Create a HashMap with user data * const userMap = HashMap.make( * ["alice", { name: "Alice", age: 30, active: true }], * ["bob", { name: "Bob", age: 25, active: false }] * ) * * // Extract the value type (User object) * type User = HashMap.HashMap.Value<typeof userMap> * * // Use the extracted type for type-safe operations * const processUser = (user: User) => { * return user.active ? `${user.name} (active)` : `${user.name} (inactive)` * } * * const alice = HashMap.get(userMap, "alice") * // alice has type Option<User> thanks to type extraction * ``` * * @category utility types * @since 2.0.0 */ export type Value<T extends HashMap<any, any>> = [T] extends [HashMap<infer _K, infer _V>] ? _V : never /** * This type-level utility extracts the entry type `[K, V]` from a `HashMap<K, V>` type. * * **Example** (Extracting entry types) * * ```ts * import { HashMap } from "effect" * * // Create a product catalog HashMap * const catalog = HashMap.make( * ["laptop", { price: 999, category: "electronics" }], * ["book", { price: 29, category: "education" }] * ) * * // Extract the entry type [string, Product] * type CatalogEntry = HashMap.HashMap.Entry<typeof catalog> * * // Use the extracted type for processing entries * const processEntry = ([productId, product]: CatalogEntry) => { * return `${productId}: $${product.price} (${product.category})` * } * * // Convert to entries, process, and sort for deterministic output * const descriptions = HashMap.toEntries(catalog).map(processEntry).sort() * console.log(descriptions) // ["book: $29 (education)", "laptop: $999 (electronics)"] * ``` * * @category utility types * @since 3.9.0 */ export type Entry<T extends HashMap<any, any>> = [Key<T>, Value<T>] } /** * Checks whether a value is a HashMap. * * **Example** (Checking HashMap values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * const notMap = { a: 1 } * * console.log(HashMap.isHashMap(map)) // true * console.log(HashMap.isHashMap(notMap)) // false * console.log(HashMap.isHashMap(null)) // false * ``` * * @category refinements * @since 2.0.0 */ export const isHashMap: { /** * Checks whether a value is a HashMap. * * **Example** (Checking HashMap values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * const notMap = { a: 1 } * * console.log(HashMap.isHashMap(map)) // true * console.log(HashMap.isHashMap(notMap)) // false * console.log(HashMap.isHashMap(null)) // false * ``` * * @category refinements * @since 2.0.0 */ <K, V>(u: Iterable<readonly [K, V]>): u is HashMap<K, V> /** * Checks whether a value is a HashMap. * * **Example** (Checking HashMap values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * const notMap = { a: 1 } * * console.log(HashMap.isHashMap(map)) // true * console.log(HashMap.isHashMap(notMap)) // false * console.log(HashMap.isHashMap(null)) // false * ``` * * @category refinements * @since 2.0.0 */ (u: unknown): u is HashMap<unknown, unknown> } = internal.isHashMap /** * Creates a new empty `HashMap`. * * **Example** (Creating an empty HashMap) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.empty<string, number>() * console.log(HashMap.isEmpty(map)) // true * console.log(HashMap.size(map)) // 0 * ``` * * @category constructors * @since 2.0.0 */ export const empty: <K = never, V = never>() => HashMap<K, V> = internal.empty /** * Constructs a new `HashMap` from an array of key/value pairs. * * **Example** (Creating a HashMap from entries) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * console.log(HashMap.size(map)) // 3 * console.log(HashMap.get(map, "b")) // Option.some(2) * ``` * * @category constructors * @since 2.0.0 */ export 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 > = internal.make /** * Creates a new `HashMap` from an iterable collection of key/value pairs. * * **Example** (Creating a HashMap from an iterable) * * ```ts * import { HashMap } from "effect" * * const entries = [["a", 1], ["b", 2], ["c", 3]] as const * const map = HashMap.fromIterable(entries) * console.log(HashMap.size(map)) // 3 * console.log(HashMap.get(map, "a")) // Option.some(1) * ``` * * @category constructors * @since 2.0.0 */ export const fromIterable: <K, V>(entries: Iterable<readonly [K, V]>) => HashMap<K, V> = internal.fromIterable /** * Checks whether the `HashMap` contains no entries. * * **Example** (Checking for empty HashMaps) * * ```ts * import { HashMap } from "effect" * * const emptyMap = HashMap.empty<string, number>() * const nonEmptyMap = HashMap.make(["a", 1]) * * console.log(HashMap.isEmpty(emptyMap)) // true * console.log(HashMap.isEmpty(nonEmptyMap)) // false * ``` * * @category elements * @since 2.0.0 */ export const isEmpty: <K, V>(self: HashMap<K, V>) => boolean = internal.isEmpty /** * Looks up the value for the specified key in the `HashMap` safely using the * internal hashing function. * * **Example** (Looking up values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * console.log(HashMap.get(map, "a")) // Option.some(1) * console.log(HashMap.get(map, "c")) // Option.none() * * // Using pipe syntax * const value = HashMap.get("b")(map) * console.log(value) // Option.some(2) * ``` * * @category elements * @since 2.0.0 */ export const get: { /** * Looks up the value for the specified key in the `HashMap` safely using the * internal hashing function. * * **Example** (Looking up values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * console.log(HashMap.get(map, "a")) // Option.some(1) * console.log(HashMap.get(map, "c")) // Option.none() * * // Using pipe syntax * const value = HashMap.get("b")(map) * console.log(value) // Option.some(2) * ``` * * @category elements * @since 2.0.0 */ <K1 extends K, K>(key: K1): <V>(self: HashMap<K, V>) => Option<V> /** * Looks up the value for the specified key in the `HashMap` safely using the * internal hashing function. * * **Example** (Looking up values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * console.log(HashMap.get(map, "a")) // Option.some(1) * console.log(HashMap.get(map, "c")) // Option.none() * * // Using pipe syntax * const value = HashMap.get("b")(map) * console.log(value) // Option.some(2) * ``` * * @category elements * @since 2.0.0 */ <K1 extends K, K, V>(self: HashMap<K, V>, key: K1): Option<V> } = internal.get /** * Looks up the value for the specified key in the `HashMap` safely using a custom hash. * * **Example** (Looking up values with a hash) * * ```ts * import { Hash, HashMap } from "effect" * * // Useful when implementing custom equality for complex keys * const userMap = HashMap.make( * ["user123", { name: "Alice", role: "admin" }], * ["user456", { name: "Bob", role: "user" }] * ) * * // Use precomputed hash for performance in hot paths * const userId = "user123" * const precomputedHash = Hash.string(userId) * * // Lookup with custom hash (e.g., cached hash value) * const user = HashMap.getHash(userMap, userId, precomputedHash) * console.log(user) // Option.some({ name: "Alice", role: "admin" }) * * // This avoids recomputing the hash when you already have it * const notFound = HashMap.getHash(userMap, "user999", Hash.string("user999")) * console.log(notFound) // Option.none() * ``` * * @category elements * @since 2.0.0 */ export const getHash: { /** * Looks up the value for the specified key in the `HashMap` safely using a custom hash. * * **Example** (Looking up values with a hash) * * ```ts * import { Hash, HashMap } from "effect" * * // Useful when implementing custom equality for complex keys * const userMap = HashMap.make( * ["user123", { name: "Alice", role: "admin" }], * ["user456", { name: "Bob", role: "user" }] * ) * * // Use precomputed hash for performance in hot paths * const userId = "user123" * const precomputedHash = Hash.string(userId) * * // Lookup with custom hash (e.g., cached hash value) * const user = HashMap.getHash(userMap, userId, precomputedHash) * console.log(user) // Option.some({ name: "Alice", role: "admin" }) * * // This avoids recomputing the hash when you already have it * const notFound = HashMap.getHash(userMap, "user999", Hash.string("user999")) * console.log(notFound) // Option.none() * ``` * * @category elements * @since 2.0.0 */ <K1 extends K, K>(key: K1, hash: number): <V>(self: HashMap<K, V>) => Option<V> /** * Looks up the value for the specified key in the `HashMap` safely using a custom hash. * * **Example** (Looking up values with a hash) * * ```ts * import { Hash, HashMap } from "effect" * * // Useful when implementing custom equality for complex keys * const userMap = HashMap.make( * ["user123", { name: "Alice", role: "admin" }], * ["user456", { name: "Bob", role: "user" }] * ) * * // Use precomputed hash for performance in hot paths * const userId = "user123" * const precomputedHash = Hash.string(userId) * * // Lookup with custom hash (e.g., cached hash value) * const user = HashMap.getHash(userMap, userId, precomputedHash) * console.log(user) // Option.some({ name: "Alice", role: "admin" }) * * // This avoids recomputing the hash when you already have it * const notFound = HashMap.getHash(userMap, "user999", Hash.string("user999")) * console.log(notFound) // Option.none() * ``` * * @category elements * @since 2.0.0 */ <K1 extends K, K, V>(self: HashMap<K, V>, key: K1, hash: number): Option<V> } = internal.getHash /** * 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`. * * **Example** (Unsafely looking up values) * * ```ts * import { HashMap, Option } from "effect" * * const config = HashMap.make( * ["api_url", "https://api.example.com"], * ["timeout", "5000"], * ["retries", "3"] * ) * * // Safe: use when you're certain the key exists * const apiUrl = HashMap.getUnsafe(config, "api_url") // "https://api.example.com" * console.log(`Connecting to: ${apiUrl}`) * * // Preferred: use get() for uncertain keys * const dbUrl = HashMap.get(config, "db_url") // Option.none() * if (Option.isSome(dbUrl)) { * console.log(`Database: ${dbUrl.value}`) * } * * // This would throw: HashMap.getUnsafe(config, "db_url") * // Error: "HashMap.getUnsafe: key not found" * ``` * * @category unsafe * @since 4.0.0 */ export const getUnsafe: { /** * 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`. * * **Example** (Unsafely looking up values) * * ```ts * import { HashMap, Option } from "effect" * * const config = HashMap.make( * ["api_url", "https://api.example.com"], * ["timeout", "5000"], * ["retries", "3"] * ) * * // Safe: use when you're certain the key exists * const apiUrl = HashMap.getUnsafe(config, "api_url") // "https://api.example.com" * console.log(`Connecting to: ${apiUrl}`) * * // Preferred: use get() for uncertain keys * const dbUrl = HashMap.get(config, "db_url") // Option.none() * if (Option.isSome(dbUrl)) { * console.log(`Database: ${dbUrl.value}`) * } * * // This would throw: HashMap.getUnsafe(config, "db_url") * // Error: "HashMap.getUnsafe: key not found" * ``` * * @category unsafe * @since 4.0.0 */ <K1 extends K, K>(key: K1): <V>(self: HashMap<K, V>) => V /** * 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`. * * **Example** (Unsafely looking up values) * * ```ts * import { HashMap, Option } from "effect" * * const config = HashMap.make( * ["api_url", "https://api.example.com"], * ["timeout", "5000"], * ["retries", "3"] * ) * * // Safe: use when you're certain the key exists * const apiUrl = HashMap.getUnsafe(config, "api_url") // "https://api.example.com" * console.log(`Connecting to: ${apiUrl}`) * * // Preferred: use get() for uncertain keys * const dbUrl = HashMap.get(config, "db_url") // Option.none() * if (Option.isSome(dbUrl)) { * console.log(`Database: ${dbUrl.value}`) * } * * // This would throw: HashMap.getUnsafe(config, "db_url") * // Error: "HashMap.getUnsafe: key not found" * ``` * * @category unsafe * @since 4.0.0 */ <K1 extends K, K, V>(self: HashMap<K, V>, key: K1): V } = internal.getUnsafe /** * Checks whether the specified key has an entry in the `HashMap`. * * **Example** (Checking for keys) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * console.log(HashMap.has(map, "a")) // true * console.log(HashMap.has(map, "c")) // false * * // Using pipe syntax * const hasB = HashMap.has("b")(map) * console.log(hasB) // true * ``` * * @category elements * @since 2.0.0 */ export const has: { /** * Checks whether the specified key has an entry in the `HashMap`. * * **Example** (Checking for keys) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * console.log(HashMap.has(map, "a")) // true * console.log(HashMap.has(map, "c")) // false * * // Using pipe syntax * const hasB = HashMap.has("b")(map) * console.log(hasB) // true * ``` * * @category elements * @since 2.0.0 */ <K1 extends K, K>(key: K1): <K, V>(self: HashMap<K, V>) => boolean /** * Checks whether the specified key has an entry in the `HashMap`. * * **Example** (Checking for keys) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * console.log(HashMap.has(map, "a")) // true * console.log(HashMap.has(map, "c")) // false * * // Using pipe syntax * const hasB = HashMap.has("b")(map) * console.log(hasB) // true * ``` * * @category elements * @since 2.0.0 */ <K1 extends K, K, V>(self: HashMap<K, V>, key: K1): boolean } = internal.has /** * Checks whether the specified key has an entry in the `HashMap` using a custom * hash. * * **Example** (Checking keys with a hash) * * ```ts * import { Hash, HashMap } from "effect" * * // Create a map with case-sensitive keys * const userMap = HashMap.make( * ["Admin", { role: "administrator" }], * ["User", { role: "standard" }] * ) * * // Check with exact hash * const exactHash = Hash.string("Admin") * console.log(HashMap.hasHash(userMap, "Admin", exactHash)) // true * * // A matching hash does not override key equality * console.log(HashMap.hasHash(userMap, "admin", exactHash)) // false * * // A different hash also cannot find the existing key * const lowercaseHash = Hash.string("admin") * console.log(HashMap.hasHash(userMap, "Admin", lowercaseHash)) // false * ``` * * @category elements * @since 2.0.0 */ export const hasHash: { /** * Checks whether the specified key has an entry in the `HashMap` using a custom * hash. * * **Example** (Checking keys with a hash) * * ```ts * import { Hash, HashMap } from "effect" * * // Create a map with case-sensitive keys * const userMap = HashMap.make( * ["Admin", { role: "administrator" }], * ["User", { role: "standard" }] * ) * * // Check with exact hash * const exactHash = Hash.string("Admin") * console.log(HashMap.hasHash(userMap, "Admin", exactHash)) // true * * // A matching hash does not override key equality * console.log(HashMap.hasHash(userMap, "admin", exactHash)) // false * * // A different hash also cannot find the existing key * const lowercaseHash = Hash.string("admin") * console.log(HashMap.hasHash(userMap, "Admin", lowercaseHash)) // false * ``` * * @category elements * @since 2.0.0 */ <K1 extends K, K>(key: K1, hash: number): <V>(self: HashMap<K, V>) => boolean /** * Checks whether the specified key has an entry in the `HashMap` using a custom * hash. * * **Example** (Checking keys with a hash) * * ```ts * import { Hash, HashMap } from "effect" * * // Create a map with case-sensitive keys * const userMap = HashMap.make( * ["Admin", { role: "administrator" }], * ["User", { role: "standard" }] * ) * * // Check with exact hash * const exactHash = Hash.string("Admin") * console.log(HashMap.hasHash(userMap, "Admin", exactHash)) // true * * // A matching hash does not override key equality * console.log(HashMap.hasHash(userMap, "admin", exactHash)) // false * * // A different hash also cannot find the existing key * const lowercaseHash = Hash.string("admin") * console.log(HashMap.hasHash(userMap, "Admin", lowercaseHash)) // false * ``` * * @category elements * @since 2.0.0 */ <K1 extends K, K, V>(self: HashMap<K, V>, key: K1, hash: number): boolean } = internal.hasHash /** * Checks whether an element matching the given predicate exists in the given `HashMap`. * * **Example** (Checking entries by predicate) * * ```ts * import { HashMap } from "effect" * * const hm = HashMap.make([1, "a"]) * HashMap.hasBy(hm, (value, key) => value === "a" && key === 1) // -> true * HashMap.hasBy(hm, (value) => value === "b") // -> false * ``` * * @category elements * @since 3.16.0 */ export const hasBy: { /** * Checks whether an element matching the given predicate exists in the given `HashMap`. * * **Example** (Checking entries by predicate) * * ```ts * import { HashMap } from "effect" * * const hm = HashMap.make([1, "a"]) * HashMap.hasBy(hm, (value, key) => value === "a" && key === 1) // -> true * HashMap.hasBy(hm, (value) => value === "b") // -> false * ``` * * @category elements * @since 3.16.0 */ <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>) => boolean): (self: HashMap<K, V>) => boolean /** * Checks whether an element matching the given predicate exists in the given `HashMap`. * * **Example** (Checking entries by predicate) * * ```ts * import { HashMap } from "effect" * * const hm = HashMap.make([1, "a"]) * HashMap.hasBy(hm, (value, key) => value === "a" && key === 1) // -> true * HashMap.hasBy(hm, (value) => value === "b") // -> false * ``` * * @category elements * @since 3.16.0 */ <K, V>( self: HashMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>) => boolean ): boolean } = internal.hasBy /** * Sets the specified key to the specified value using the internal hashing * function. * * **Example** (Setting a value) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1]) * const map2 = HashMap.set(map1, "b", 2) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.get(map2, "b")) // Option.some(2) * * // Original map is unchanged * console.log(HashMap.size(map1)) // 1 * ``` * * @category transforming * @since 2.0.0 */ export const set: { /** * Sets the specified key to the specified value using the internal hashing * function. * * **Example** (Setting a value) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1]) * const map2 = HashMap.set(map1, "b", 2) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.get(map2, "b")) // Option.some(2) * * // Original map is unchanged * console.log(HashMap.size(map1)) // 1 * ``` * * @category transforming * @since 2.0.0 */ <K, V>(key: K, value: V): (self: HashMap<K, V>) => HashMap<K, V> /** * Sets the specified key to the specified value using the internal hashing * function. * * **Example** (Setting a value) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1]) * const map2 = HashMap.set(map1, "b", 2) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.get(map2, "b")) // Option.some(2) * * // Original map is unchanged * console.log(HashMap.size(map1)) // 1 * ``` * * @category transforming * @since 2.0.0 */ <K, V>(self: HashMap<K, V>, key: K, value: V): HashMap<K, V> } = internal.set /** * Returns an `IterableIterator` of the keys within the `HashMap`. * * **Example** (Iterating keys) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const keys = Array.from(HashMap.keys(map)) * console.log(keys.sort()) // ["a", "b", "c"] * ``` * * @category getters * @since 2.0.0 */ export const keys: <K, V>(self: HashMap<K, V>) => IterableIterator<K> = internal.keys /** * Returns an `IterableIterator` of the values within the `HashMap`. * * **Example** (Iterating values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const values = Array.from(HashMap.values(map)) * console.log(values.sort()) // [1, 2, 3] * ``` * * @category getters * @since 2.0.0 */ export const values: <K, V>(self: HashMap<K, V>) => IterableIterator<V> = internal.values /** * Returns an `Array` of the values within the `HashMap`. * * **Example** (Converting values to an array) * * ```ts * import { HashMap } from "effect" * * const employees = HashMap.make( * ["alice", { department: "engineering", salary: 90000 }], * ["bob", { department: "marketing", salary: 75000 }], * ["charlie", { department: "engineering", salary: 95000 }] * ) * * // Extract all employee records * const allEmployees = HashMap.toValues(employees) * console.log(allEmployees.length) // 3 * * // Calculate total salary * const totalSalary = allEmployees.reduce((sum, emp) => sum + emp.salary, 0) * console.log(totalSalary) // 260000 * * // Filter by department * const engineers = allEmployees.filter((emp) => emp.department === "engineering") * console.log(engineers.length) // 2 * ``` * * @category getters * @since 3.13.0 */ export const toValues = <K, V>(self: HashMap<K, V>): Array<V> => Array.from(values(self)) /** * Returns an `IterableIterator` of the entries within the `HashMap`. * * **Example** (Iterating entries) * * ```ts * import { HashMap } from "effect" * * // Create a configuration map * const config = HashMap.make( * ["database.host", "localhost"], * ["database.port", "5432"], * ["cache.enabled", "true"] * ) * * // Sort the derived array for deterministic output * const settings = Array.from(HashMap.entries(config)) * .sort(([left], [right]) => left.localeCompare(right)) * .map(([key, value]) => `Setting ${key} = ${value}`) * * console.log(settings) * // ["Setting cache.enabled = true", "Setting database.host = localhost", "Setting database.port = 5432"] * * // Convert to array when you need all entries at once * const allEntries = Array.from(HashMap.entries(config)) * console.log(allEntries.length) // 3 * ``` * * @category getters * @since 2.0.0 */ export const entries: <K, V>(self: HashMap<K, V>) => IterableIterator<[K, V]> = internal.entries /** * Returns an `Array<[K, V]>` of the entries within the `HashMap`. * * **Example** (Converting entries to an array) * * ```ts * import { HashMap } from "effect" * * const gameScores = HashMap.make( * ["alice", 1250], * ["bob", 980], * ["charlie", 1100] * ) * * // Convert to entries for processing * const scoreEntries = HashMap.toEntries(gameScores) * * // Sort by score (descending) * const leaderboard = scoreEntries * .sort(([, a], [, b]) => b - a) * .map(([player, score], rank) => `${rank + 1}. ${player}: ${score}`) * * console.log(leaderboard) * // ["1. alice: 1250", "2. charlie: 1100", "3. bob: 980"] * * // Convert back to HashMap if needed * const sortedMap = HashMap.fromIterable(scoreEntries) * ``` * * @category getters * @since 2.0.0 */ export const toEntries = <K, V>(self: HashMap<K, V>): Array<[K, V]> => Array.from(entries(self)) /** * Returns the number of entries within the `HashMap`. * * **Example** (Getting the size) * * ```ts * import { HashMap } from "effect" * * const emptyMap = HashMap.empty<string, number>() * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * * console.log(HashMap.size(emptyMap)) // 0 * console.log(HashMap.size(map)) // 3 * ``` * * @category getters * @since 2.0.0 */ export const size: <K, V>(self: HashMap<K, V>) => number = internal.size /** * 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`. * * **Example** (Beginning batch mutation) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1]) * * // Begin mutation for efficient batch operations * const mutable = HashMap.beginMutation(map) * * // Multiple operations are now more efficient * HashMap.set(mutable, "b", 2) * HashMap.set(mutable, "c", 3) * HashMap.remove(mutable, "a") * * // End mutation to get final immutable result * const result = HashMap.endMutation(mutable) * console.log(HashMap.size(result)) // 2 * ``` * * @category mutations * @since 2.0.0 */ export const beginMutation: <K, V>(self: HashMap<K, V>) => HashMap<K, V> = internal.beginMutation /** * Marks the `HashMap` as immutable, completing the mutation cycle. * * **Example** (Ending batch mutation) * * ```ts * import { HashMap } from "effect" * * // Start with an existing map * const original = HashMap.make(["x", 10], ["y", 20]) * * // Begin mutation for batch operations * const mutable = HashMap.beginMutation(original) * * // Perform multiple efficient operations * HashMap.set(mutable, "z", 30) * HashMap.remove(mutable, "x") * HashMap.set(mutable, "w", 40) * * // End mutation to get final immutable result * const final = HashMap.endMutation(mutable) * * console.log(HashMap.size(final)) // 3 * console.log(HashMap.has(final, "x")) // false * console.log(HashMap.get(final, "z")) // Option.some(30) * ``` * * @category mutations * @since 2.0.0 */ export const endMutation: <K, V>(self: HashMap<K, V>) => HashMap<K, V> = internal.endMutation /** * 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. * * **Example** (Applying batched mutations) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1]) * const map2 = HashMap.mutate(map1, (mutable) => { * HashMap.set(mutable, "b", 2) * HashMap.set(mutable, "c", 3) * }) * // Returns a new HashMap with mutations applied * ``` * * @category mutations * @since 2.0.0 */ export const mutate: { /** * 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. * * **Example** (Applying batched mutations) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1]) * const map2 = HashMap.mutate(map1, (mutable) => { * HashMap.set(mutable, "b", 2) * HashMap.set(mutable, "c", 3) * }) * // Returns a new HashMap with mutations applied * ``` * * @category mutations * @since 2.0.0 */ <K, V>(f: (self: HashMap<K, V>) => void): (self: HashMap<K, V>) => HashMap<K, V> /** * 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. * * **Example** (Applying batched mutations) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1]) * const map2 = HashMap.mutate(map1, (mutable) => { * HashMap.set(mutable, "b", 2) * HashMap.set(mutable, "c", 3) * }) * // Returns a new HashMap with mutations applied * ``` * * @category mutations * @since 2.0.0 */ <K, V>(self: HashMap<K, V>, f: (self: HashMap<K, V>) => void): HashMap<K, V> } = internal.mutate /** * 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. * * **Example** (Updating values with Options) * * ```ts * import { HashMap, Option } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * // Increment existing value or set to 1 if not present * const updateFn = (option: Option.Option<number>) => * Option.isSome(option) ? Option.some(option.value + 1) : Option.some(1) * * const updated = HashMap.modifyAt(map, "a", updateFn) * console.log(HashMap.get(updated, "a")) // Option.some(2) * ``` * * @category transforming * @since 2.0.0 */ export const modifyAt: { /** * 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. * * **Example** (Updating values with Options) * * ```ts * import { HashMap, Option } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * // Increment existing value or set to 1 if not present * const updateFn = (option: Option.Option<number>) => * Option.isSome(option) ? Option.some(option.value + 1) : Option.some(1) * * const updated = HashMap.modifyAt(map, "a", updateFn) * console.log(HashMap.get(updated, "a")) // Option.some(2) * ``` * * @category transforming * @since 2.0.0 */ <K, V>(key: K, f: HashMap.UpdateFn<V>): (self: HashMap<K, V>) => HashMap<K, V> /** * 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. * * **Example** (Updating values with Options) * * ```ts * import { HashMap, Option } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * * // Increment existing value or set to 1 if not present * const updateFn = (option: Option.Option<number>) => * Option.isSome(option) ? Option.some(option.value + 1) : Option.some(1) * * const updated = HashMap.modifyAt(map, "a", updateFn) * console.log(HashMap.get(updated, "a")) // Option.some(2) * ``` * * @category transforming * @since 2.0.0 */ <K, V>(self: HashMap<K, V>, key: K, f: HashMap.UpdateFn<V>): HashMap<K, V> } = internal.modifyAt /** * 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. * * **Example** (Updating values with a hash) * * ```ts * import { Hash, HashMap, Option } from "effect" * * // Useful when working with precomputed hashes for performance * const counters = HashMap.make(["downloads", 100], ["views", 250]) * * // Cache hash computation for frequently accessed keys * const metricKey = "downloads" * const cachedHash = Hash.string(metricKey) * * // Update function that increments counter or initializes to 1 * const incrementCounter = (current: Option.Option<number>) => * Option.isSome(current) ? Option.some(current.value + 1) : Option.some(1) * * // Use cached hash for efficient updates in loops * const updated = HashMap.modifyHash( * counters, * metricKey, * cachedHash, * incrementCounter * ) * console.log(HashMap.get(updated, "downloads")) // Option.some(101) * * // Add new metric with precomputed hash * const newMetric = "clicks" * const clicksHash = Hash.string(newMetric) * const withClicks = HashMap.modifyHash( * updated, * newMetric, * clicksHash, * incrementCounter * ) * console.log(HashMap.get(withClicks, "clicks")) // Option.some(1) * ``` * * @category transforming * @since 2.0.0 */ export const modifyHash: { /** * 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. * * **Example** (Updating values with a hash) * * ```ts * import { Hash, HashMap, Option } from "effect" * * // Useful when working with precomputed hashes for performance * const counters = HashMap.make(["downloads", 100], ["views", 250]) * * // Cache hash computation for frequently accessed keys * const metricKey = "downloads" * const cachedHash = Hash.string(metricKey) * * // Update function that increments counter or initializes to 1 * const incrementCounter = (current: Option.Option<number>) => * Option.isSome(current) ? Option.some(current.value + 1) : Option.some(1) * * // Use cached hash for efficient updates in loops * const updated = HashMap.modifyHash( * counters, * metricKey, * cachedHash, * incrementCounter * ) * console.log(HashMap.get(updated, "downloads")) // Option.some(101) * * // Add new metric with precomputed hash * const newMetric = "clicks" * const clicksHash = Hash.string(newMetric) * const withClicks = HashMap.modifyHash( * updated, * newMetric, * clicksHash, * incrementCounter * ) * console.log(HashMap.get(withClicks, "clicks")) // Option.some(1) * ``` * * @category transforming * @since 2.0.0 */ <K, V>(key: K, hash: number, f: HashMap.UpdateFn<V>): (self: HashMap<K, V>) => HashMap<K, V> /** * 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. * * **Example** (Updating values with a hash) * * ```ts * import { Hash, HashMap, Option } from "effect" * * // Useful when working with precomputed hashes for performance * const counters = HashMap.make(["downloads", 100], ["views", 250]) * * // Cache hash computation for frequently accessed keys * const metricKey = "downloads" * const cachedHash = Hash.string(metricKey) * * // Update function that increments counter or initializes to 1 * const incrementCounter = (current: Option.Option<number>) => * Option.isSome(current) ? Option.some(current.value + 1) : Option.some(1) * * // Use cached hash for efficient updates in loops * const updated = HashMap.modifyHash( * counters, * metricKey, * cachedHash, * incrementCounter * ) * console.log(HashMap.get(updated, "downloads")) // Option.some(101) * * // Add new metric with precomputed hash * const newMetric = "clicks" * const clicksHash = Hash.string(newMetric) * const withClicks = HashMap.modifyHash( * updated, * newMetric, * clicksHash, * incrementCounter * ) * console.log(HashMap.get(withClicks, "clicks")) // Option.some(1) * ``` * * @category transforming * @since 2.0.0 */ <K, V>(self: HashMap<K, V>, key: K, hash: number, f: HashMap.UpdateFn<V>): HashMap<K, V> } = internal.modifyHash /** * Updates the value of the specified key within the `HashMap` if it exists. * * **Example** (Modifying existing values) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const map2 = HashMap.modify(map1, "a", (value) => value * 3) * * console.log(HashMap.get(map2, "a")) // Option.some(3) * console.log(HashMap.get(map2, "b")) // Option.some(2) * ``` * * @category transforming * @since 2.0.0 */ export const modify: { /** * Updates the value of the specified key within the `HashMap` if it exists. * * **Example** (Modifying existing values) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const map2 = HashMap.modify(map1, "a", (value) => value * 3) * * console.log(HashMap.get(map2, "a")) // Option.some(3) * console.log(HashMap.get(map2, "b")) // Option.some(2) * ``` * * @category transforming * @since 2.0.0 */ <K, V>(key: K, f: (v: V) => V): (self: HashMap<K, V>) => HashMap<K, V> /** * Updates the value of the specified key within the `HashMap` if it exists. * * **Example** (Modifying existing values) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const map2 = HashMap.modify(map1, "a", (value) => value * 3) * * console.log(HashMap.get(map2, "a")) // Option.some(3) * console.log(HashMap.get(map2, "b")) // Option.some(2) * ``` * * @category transforming * @since 2.0.0 */ <K, V>(self: HashMap<K, V>, key: K, f: (v: V) => V): HashMap<K, V> } = internal.modify /** * Combines two `HashMap`s 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`. * * **Example** (Combining HashMaps) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const map2 = HashMap.make(["b", 20], ["c", 3]) * const union = HashMap.union(map1, map2) * * console.log(HashMap.size(union)) // 3 * console.log(HashMap.get(union, "b")) // Option.some(20) - map2 wins * ``` * * @category combining * @since 2.0.0 */ export const union: { /** * Combines two `HashMap`s 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`. * * **Example** (Combining HashMaps) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const map2 = HashMap.make(["b", 20], ["c", 3]) * const union = HashMap.union(map1, map2) * * console.log(HashMap.size(union)) // 3 * console.log(HashMap.get(union, "b")) // Option.some(20) - map2 wins * ``` * * @category combining * @since 2.0.0 */ <K1, V1>(that: HashMap<K1, V1>): <K0, V0>(self: HashMap<K0, V0>) => HashMap<K1 | K0, V1 | V0> /** * Combines two `HashMap`s 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`. * * **Example** (Combining HashMaps) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const map2 = HashMap.make(["b", 20], ["c", 3]) * const union = HashMap.union(map1, map2) * * console.log(HashMap.size(union)) // 3 * console.log(HashMap.get(union, "b")) // Option.some(20) - map2 wins * ``` * * @category combining * @since 2.0.0 */ <K0, V0, K1, V1>(self: HashMap<K0, V0>, that: HashMap<K1, V1>): HashMap<K0 | K1, V0 | V1> } = internal.union /** * Removes the entry for the specified key in the `HashMap` using the internal * hashing function. * * **Example** (Removing a key) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const map2 = HashMap.remove(map1, "b") * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.has(map2, "b")) // false * console.log(HashMap.has(map2, "a")) // true * ``` * * @category transforming * @since 2.0.0 */ export const remove: { /** * Removes the entry for the specified key in the `HashMap` using the internal * hashing function. * * **Example** (Removing a key) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const map2 = HashMap.remove(map1, "b") * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.has(map2, "b")) // false * console.log(HashMap.has(map2, "a")) // true * ``` * * @category transforming * @since 2.0.0 */ <K>(key: K): <V>(self: HashMap<K, V>) => HashMap<K, V> /** * Removes the entry for the specified key in the `HashMap` using the internal * hashing function. * * **Example** (Removing a key) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const map2 = HashMap.remove(map1, "b") * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.has(map2, "b")) // false * console.log(HashMap.has(map2, "a")) // true * ``` * * @category transforming * @since 2.0.0 */ <K, V>(self: HashMap<K, V>, key: K): HashMap<K, V> } = internal.remove /** * Removes all entries in the `HashMap` which have the specified keys. * * **Example** (Removing multiple keys) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4]) * const map2 = HashMap.removeMany(map1, ["b", "d"]) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.has(map2, "a")) // true * console.log(HashMap.has(map2, "c")) // true * ``` * * @category transforming * @since 2.0.0 */ export const removeMany: { /** * Removes all entries in the `HashMap` which have the specified keys. * * **Example** (Removing multiple keys) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4]) * const map2 = HashMap.removeMany(map1, ["b", "d"]) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.has(map2, "a")) // true * console.log(HashMap.has(map2, "c")) // true * ``` * * @category transforming * @since 2.0.0 */ <K>(keys: Iterable<K>): <V>(self: HashMap<K, V>) => HashMap<K, V> /** * Removes all entries in the `HashMap` which have the specified keys. * * **Example** (Removing multiple keys) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4]) * const map2 = HashMap.removeMany(map1, ["b", "d"]) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.has(map2, "a")) // true * console.log(HashMap.has(map2, "c")) // true * ``` * * @category transforming * @since 2.0.0 */ <K, V>(self: HashMap<K, V>, keys: Iterable<K>): HashMap<K, V> } = internal.removeMany /** * Sets multiple key-value pairs in the `HashMap`. * * **Example** (Setting multiple entries) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const newEntries = [["c", 3], ["d", 4], ["a", 10]] as const // "a" will be overwritten * const map2 = HashMap.setMany(map1, newEntries) * * console.log(HashMap.size(map2)) // 4 * console.log(HashMap.get(map2, "a")) // Option.some(10) * console.log(HashMap.get(map2, "c")) // Option.some(3) * ``` * * @category transforming * @since 4.0.0 */ export const setMany: { /** * Sets multiple key-value pairs in the `HashMap`. * * **Example** (Setting multiple entries) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const newEntries = [["c", 3], ["d", 4], ["a", 10]] as const // "a" will be overwritten * const map2 = HashMap.setMany(map1, newEntries) * * console.log(HashMap.size(map2)) // 4 * console.log(HashMap.get(map2, "a")) // Option.some(10) * console.log(HashMap.get(map2, "c")) // Option.some(3) * ``` * * @category transforming * @since 4.0.0 */ <K, V>(entries: Iterable<readonly [K, V]>): (self: HashMap<K, V>) => HashMap<K, V> /** * Sets multiple key-value pairs in the `HashMap`. * * **Example** (Setting multiple entries) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const newEntries = [["c", 3], ["d", 4], ["a", 10]] as const // "a" will be overwritten * const map2 = HashMap.setMany(map1, newEntries) * * console.log(HashMap.size(map2)) // 4 * console.log(HashMap.get(map2, "a")) // Option.some(10) * console.log(HashMap.get(map2, "c")) // Option.some(3) * ``` * * @category transforming * @since 4.0.0 */ <K, V>(self: HashMap<K, V>, entries: Iterable<readonly [K, V]>): HashMap<K, V> } = internal.setMany /** * Maps over the entries of the `HashMap` using the specified function. * * **Example** (Mapping values) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const map2 = HashMap.map(map1, (value, key) => `${key}:${value * 2}`) * * console.log(HashMap.get(map2, "a")) // Option.some("a:2") * console.log(HashMap.get(map2, "b")) // Option.some("b:4") * ``` * * @category mapping * @since 2.0.0 */ export const map: { /** * Maps over the entries of the `HashMap` using the specified function. * * **Example** (Mapping values) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const map2 = HashMap.map(map1, (value, key) => `${key}:${value * 2}`) * * console.log(HashMap.get(map2, "a")) // Option.some("a:2") * console.log(HashMap.get(map2, "b")) // Option.some("b:4") * ``` * * @category mapping * @since 2.0.0 */ <A, V, K>(f: (value: V, key: K) => A): (self: HashMap<K, V>) => HashMap<K, A> /** * Maps over the entries of the `HashMap` using the specified function. * * **Example** (Mapping values) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const map2 = HashMap.map(map1, (value, key) => `${key}:${value * 2}`) * * console.log(HashMap.get(map2, "a")) // Option.some("a:2") * console.log(HashMap.get(map2, "b")) // Option.some("b:4") * ``` * * @category mapping * @since 2.0.0 */ <K, V, A>(self: HashMap<K, V>, f: (value: V, key: K) => A): HashMap<K, A> } = internal.map /** * Maps each entry to a `HashMap` and flattens the results. * * **Gotchas** * * The hash and equality behavior of both maps have to be the same. * * **Example** (FlatMapping values) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const map2 = HashMap.flatMap( * map1, * (value, key) => HashMap.make([key + "1", value], [key + "2", value * 2]) * ) * * console.log(HashMap.size(map2)) // 4 * console.log(HashMap.get(map2, "a1")) // Option.some(1) * console.log(HashMap.get(map2, "b2")) // Option.some(4) * ``` * * @category sequencing * @since 2.0.0 */ export const flatMap: { /** * Maps each entry to a `HashMap` and flattens the results. * * **Gotchas** * * The hash and equality behavior of both maps have to be the same. * * **Example** (FlatMapping values) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const map2 = HashMap.flatMap( * map1, * (value, key) => HashMap.make([key + "1", value], [key + "2", value * 2]) * ) * * console.log(HashMap.size(map2)) // 4 * console.log(HashMap.get(map2, "a1")) // Option.some(1) * console.log(HashMap.get(map2, "b2")) // Option.some(4) * ``` * * @category sequencing * @since 2.0.0 */ <A, K, B>(f: (value: A, key: K) => HashMap<K, B>): (self: HashMap<K, A>) => HashMap<K, B> /** * Maps each entry to a `HashMap` and flattens the results. * * **Gotchas** * * The hash and equality behavior of both maps have to be the same. * * **Example** (FlatMapping values) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2]) * const map2 = HashMap.flatMap( * map1, * (value, key) => HashMap.make([key + "1", value], [key + "2", value * 2]) * ) * * console.log(HashMap.size(map2)) // 4 * console.log(HashMap.get(map2, "a1")) // Option.some(1) * console.log(HashMap.get(map2, "b2")) // Option.some(4) * ``` * * @category sequencing * @since 2.0.0 */ <K, A, B>(self: HashMap<K, A>, f: (value: A, key: K) => HashMap<K, B>): HashMap<K, B> } = internal.flatMap /** * Applies the specified function to the entries of the `HashMap`. * * **Example** (Iterating with side effects) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * const collected: Array<[string, number]> = [] * * HashMap.forEach(map, (value, key) => { * collected.push([key, value]) * }) * * console.log(collected.sort()) // [["a", 1], ["b", 2]] * ``` * * @category traversing * @since 2.0.0 */ export const forEach: { /** * Applies the specified function to the entries of the `HashMap`. * * **Example** (Iterating with side effects) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * const collected: Array<[string, number]> = [] * * HashMap.forEach(map, (value, key) => { * collected.push([key, value]) * }) * * console.log(collected.sort()) // [["a", 1], ["b", 2]] * ``` * * @category traversing * @since 2.0.0 */ <V, K>(f: (value: V, key: K) => void): (self: HashMap<K, V>) => void /** * Applies the specified function to the entries of the `HashMap`. * * **Example** (Iterating with side effects) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2]) * const collected: Array<[string, number]> = [] * * HashMap.forEach(map, (value, key) => { * collected.push([key, value]) * }) * * console.log(collected.sort()) // [["a", 1], ["b", 2]] * ``` * * @category traversing * @since 2.0.0 */ <V, K>(self: HashMap<K, V>, f: (value: V, key: K) => void): void } = internal.forEach /** * Reduces the specified state over the entries of the `HashMap`. * * **Example** (Reducing values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const sum = HashMap.reduce(map, 0, (acc, value) => acc + value) * * console.log(sum) // 6 * ``` * * @category folding * @since 2.0.0 */ export const reduce: { /** * Reduces the specified state over the entries of the `HashMap`. * * **Example** (Reducing values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const sum = HashMap.reduce(map, 0, (acc, value) => acc + value) * * console.log(sum) // 6 * ``` * * @category folding * @since 2.0.0 */ <Z, V, K>(zero: Z, f: (accumulator: Z, value: V, key: K) => Z): (self: HashMap<K, V>) => Z /** * Reduces the specified state over the entries of the `HashMap`. * * **Example** (Reducing values) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const sum = HashMap.reduce(map, 0, (acc, value) => acc + value) * * console.log(sum) // 6 * ``` * * @category folding * @since 2.0.0 */ <K, V, Z>(self: HashMap<K, V>, zero: Z, f: (accumulator: Z, value: V, key: K) => Z): Z } = internal.reduce /** * Filters entries out of a `HashMap` using the specified predicate. * * **Example** (Filtering entries) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4]) * const map2 = HashMap.filter(map1, (value) => value % 2 === 0) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.has(map2, "b")) // true * console.log(HashMap.has(map2, "d")) // true * console.log(HashMap.has(map2, "a")) // false * ``` * * @category filtering * @since 2.0.0 */ export const filter: { /** * Filters entries out of a `HashMap` using the specified predicate. * * **Example** (Filtering entries) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4]) * const map2 = HashMap.filter(map1, (value) => value % 2 === 0) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.has(map2, "b")) // true * console.log(HashMap.has(map2, "d")) // true * console.log(HashMap.has(map2, "a")) // false * ``` * * @category filtering * @since 2.0.0 */ <K, A>(f: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => HashMap<K, A> /** * Filters entries out of a `HashMap` using the specified predicate. * * **Example** (Filtering entries) * * ```ts * import { HashMap } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4]) * const map2 = HashMap.filter(map1, (value) => value % 2 === 0) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.has(map2, "b")) // true * console.log(HashMap.has(map2, "d")) // true * console.log(HashMap.has(map2, "a")) // false * ``` * * @category filtering * @since 2.0.0 */ <K, A>(self: HashMap<K, A>, f: (a: A, k: K) => boolean): HashMap<K, A> } = internal.filter /** * Filters out `None` values from a `HashMap` of `Options`s. * * **Example** (Compacting Option values) * * ```ts * import { HashMap, Option } from "effect" * * const map1 = HashMap.make( * ["a", Option.some(1)], * ["b", Option.none()], * ["c", Option.some(3)] * ) * const map2 = HashMap.compact(map1) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.get(map2, "a")) // Option.some(1) * console.log(HashMap.has(map2, "b")) // false * ``` * * @category filtering * @since 2.0.0 */ export const compact: <K, A>(self: HashMap<K, Option<A>>) => HashMap<K, A> = internal.compact /** * Maps over the entries of the `HashMap` using the specified filter and keeps * only successful results. * * **Example** (Filtering and mapping Results) * * ```ts * import { HashMap, Result } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4]) * const map2 = HashMap.filterMap( * map1, * (value) => value % 2 === 0 ? Result.succeed(value * 2) : Result.failVoid * ) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.get(map2, "b")) // Option.some(4) * console.log(HashMap.get(map2, "d")) // Option.some(8) * ``` * * @category filtering * @since 2.0.0 */ export const filterMap: { /** * Maps over the entries of the `HashMap` using the specified filter and keeps * only successful results. * * **Example** (Filtering and mapping Results) * * ```ts * import { HashMap, Result } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4]) * const map2 = HashMap.filterMap( * map1, * (value) => value % 2 === 0 ? Result.succeed(value * 2) : Result.failVoid * ) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.get(map2, "b")) // Option.some(4) * console.log(HashMap.get(map2, "d")) // Option.some(8) * ``` * * @category filtering * @since 2.0.0 */ <A, K, B, X>(f: (input: A, key: K) => Result<B, X>): (self: HashMap<K, A>) => HashMap<K, B> /** * Maps over the entries of the `HashMap` using the specified filter and keeps * only successful results. * * **Example** (Filtering and mapping Results) * * ```ts * import { HashMap, Result } from "effect" * * const map1 = HashMap.make(["a", 1], ["b", 2], ["c", 3], ["d", 4]) * const map2 = HashMap.filterMap( * map1, * (value) => value % 2 === 0 ? Result.succeed(value * 2) : Result.failVoid * ) * * console.log(HashMap.size(map2)) // 2 * console.log(HashMap.get(map2, "b")) // Option.some(4) * console.log(HashMap.get(map2, "d")) // Option.some(8) * ``` * * @category filtering * @since 2.0.0 */ <K, A, B, X>(self: HashMap<K, A>, f: (input: A, key: K) => Result<B, X>): HashMap<K, B> } = internal.filterMap /** * Returns the first element that satisfies the specified * predicate, or `None` if no such element exists. * * **Example** (Finding the first matching entry) * * ```ts * import { HashMap, Option } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const result = HashMap.findFirst(map, (value, key) => key === "b" && value > 1) * console.log(result) // Option.some(["b", 2]) * console.log(Option.getOrElse(result, () => ["", 0])) // ["b", 2] * ``` * * @category elements * @since 2.0.0 */ export const findFirst: { /** * Returns the first element that satisfies the specified * predicate, or `None` if no such element exists. * * **Example** (Finding the first matching entry) * * ```ts * import { HashMap, Option } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const result = HashMap.findFirst(map, (value, key) => key === "b" && value > 1) * console.log(result) // Option.some(["b", 2]) * console.log(Option.getOrElse(result, () => ["", 0])) // ["b", 2] * ``` * * @category elements * @since 2.0.0 */ <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => Option<[K, A]> /** * Returns the first element that satisfies the specified * predicate, or `None` if no such element exists. * * **Example** (Finding the first matching entry) * * ```ts * import { HashMap, Option } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * const result = HashMap.findFirst(map, (value, key) => key === "b" && value > 1) * console.log(result) // Option.some(["b", 2]) * console.log(Option.getOrElse(result, () => ["", 0])) // ["b", 2] * ``` * * @category elements * @since 2.0.0 */ <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): Option<[K, A]> } = internal.findFirst /** * Checks whether any entry in a hashmap meets a specific condition. * * **Example** (Checking for any matching entry) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * * console.log(HashMap.some(map, (value) => value > 2)) // true * console.log(HashMap.some(map, (value) => value > 5)) // false * ``` * * @category elements * @since 3.13.0 */ export const some: { /** * Checks whether any entry in a hashmap meets a specific condition. * * **Example** (Checking for any matching entry) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * * console.log(HashMap.some(map, (value) => value > 2)) // true * console.log(HashMap.some(map, (value) => value > 5)) // false * ``` * * @category elements * @since 3.13.0 */ <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => boolean /** * Checks whether any entry in a hashmap meets a specific condition. * * **Example** (Checking for any matching entry) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * * console.log(HashMap.some(map, (value) => value > 2)) // true * console.log(HashMap.some(map, (value) => value > 5)) // false * ``` * * @category elements * @since 3.13.0 */ <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): boolean } = internal.some /** * Checks whether all entries in a hashmap meets a specific condition. * * **Example** (Checking all entries) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * * console.log(HashMap.every(map, (value) => value > 0)) // true * console.log(HashMap.every(map, (value) => value > 1)) // false * ``` * * @category elements * @since 3.14.0 */ export const every: { /** * Checks whether all entries in a hashmap meets a specific condition. * * **Example** (Checking all entries) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * * console.log(HashMap.every(map, (value) => value > 0)) // true * console.log(HashMap.every(map, (value) => value > 1)) // false * ``` * * @category elements * @since 3.14.0 */ <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => boolean /** * Checks whether all entries in a hashmap meets a specific condition. * * **Example** (Checking all entries) * * ```ts * import { HashMap } from "effect" * * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3]) * * console.log(HashMap.every(map, (value) => value > 0)) // true * console.log(HashMap.every(map, (value) => value > 1)) // false * ``` * * @category elements * @since 3.14.0 */ <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): boolean } = internal.every
/**
* 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.
*
* @since 2.0.0
*/
import type { Equal } from "./Equal.ts"
import type { Inspectable } from "./Inspectable.ts"
import * as internal from "./internal/hashMap.ts"
import type { Option } from "./Option.ts"
import type { Pipeable } from "./Pipeable.ts"
import type { Result } from "./Result.ts"
import type { NoInfer } from "./Types.ts"
const TypeId = internal.HashMapTypeId
/**
* 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.
*
* **Example** (Using basic HashMap operations)
*
* ```ts
* import { HashMap } from "effect"
*
* // Create a HashMap
* const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
*
* // Access values
* const valueA = HashMap.get(map, "a") // Option.some(1)
* const valueD = HashMap.get(map, "d") // Option.none()
*
* // Check if key exists
* console.log(HashMap.has(map, "b")) // true
*
* // Add/update values (returns new HashMap)
* const updated = HashMap.set(map, "d", 4)
* console.log(HashMap.size(updated)) // 4
* ```
*
* @category models
* @since 2.0.0
*/
export interface HashMap<out Key, out Value> extends Iterable<[Key, Value]>, Equal, Pipeable, Inspectable {
readonly [TypeId]: typeof TypeId
}
/**
* The HashMap namespace contains type-level utilities and helper types
* for working with HashMap instances.
*
* **Example** (Extracting HashMap types)
*
* ```ts
* import { HashMap } from "effect"
*
* // Create a concrete HashMap for type extraction
* const inventory = HashMap.make(
* ["laptop", { quantity: 5, price: 999 }],
* ["mouse", { quantity: 20, price: 29 }]
* )
*
* // Extract types for reuse
* type ProductId = HashMap.HashMap.Key<typeof inventory> // string
* type Product = HashMap.HashMap.Value<typeof inventory> // { quantity: number, price: number }
* type InventoryEntry = HashMap.HashMap.Entry<typeof inventory> // [string, Product]
*
* // Use extracted types in functions
* const updateInventory = (id: ProductId, product: Product) =>
* HashMap.set(inventory, id, product)
*
* const processEntry = ([id, product]: InventoryEntry) =>
* `${id}: ${product.quantity} @ $${product.price}`
*
* // Example of extracted types in action
* const newProduct: Product = { quantity: 10, price: 199 }
* const updatedInventory = updateInventory("tablet", newProduct)
* ```
*
* @since 2.0.0
*/
export declare namespace HashMap {
/**
* A function that updates a value based on its current state.
* Takes an Option representing the current value and returns an Option
* representing the new value.
*
* **Example** (Updating values from Options)
*
* ```ts
* import { HashMap, Option } from "effect"
*
* const map = HashMap.make(["a", 1], ["b", 2])

Xet Storage Details

Size:
68.7 kB
·
Xet hash:
51c49a35277c7db9c85d2aa44b4fc81856d377e4468b748ac2d537e027cb17b3

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.