map

Functional utilities for maps.

Features

Opt-in mutability with remmi
Reference preservation (filter(map, () => true) === map)
Pipe-friendly (pipe(filter(() => true))(map))
Graceful failure handling (get(), getOr(), getOrElse(), getOrThrow())

Installation

npm install @monstermann/map

pnpm add @monstermann/map

yarn add @monstermann/map

bun add @monstermann/map

Tree-shaking

Installation

npm install -D @monstermann/unplugin-map

pnpm -D add @monstermann/unplugin-map

yarn -D add @monstermann/unplugin-map

bun -D add @monstermann/unplugin-map

Usage

// vite.config.tsimportmapfrom"@monstermann/unplugin-map/vite";exportdefaultdefineConfig({plugins: [map()],});

// rollup.config.jsimportmapfrom"@monstermann/unplugin-map/rollup";exportdefault{plugins: [map()],};

// rolldown.config.jsimportmapfrom"@monstermann/unplugin-map/rolldown";exportdefault{plugins: [map()],};

// webpack.config.jsconstmap=require("@monstermann/unplugin-map/webpack");module.exports={plugins: [map()],};

// rspack.config.jsconstmap=require("@monstermann/unplugin-map/rspack");module.exports={plugins: [map()],};

// esbuild.config.jsimport{build}from"esbuild";importmapfrom"@monstermann/unplugin-map/esbuild";build({plugins: [map()],});

Map

clone

functionMap.clone<K,V>(target: ReadonlyMap<K,V>): Map<K,V>

Creates a shallow copy of the map, unless marked as mutable with markAsMutable inside a mutation context (see @monstermann/remmi).

Example

import{Map}from"@monstermann/map";constoriginal=newMap([["a",1],["b",2],]);constcopy=Map.clone(original);// Map { 'a' => 1, 'b' => 2 }

import{Map}from"@monstermann/map";constoriginal=newMap([["a",1],["b",2],]);constcopy=pipe(original,Map.clone());// Map { 'a' => 1, 'b' => 2 }

compact

functionMap.compact<K,V>(target: ReadonlyMap<K,V>,): ReadonlyMap<K,Exclude<V,null|undefined>>

Removes all entries with null or undefined values.

Example

import{Map}from"@monstermann/map";Map.compact(newMap([["a",1],["b",null],["c",undefined],]),);// Map(1) { "a" => 1 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",null],["c",undefined],]),Map.compact(),);// Map(1) { "a" => 1 }

create

functionMap.create<K,V>(iterable?: Iterable<readonly[K,V]>|null|undefined,): Map<K,V>

Creates a new Map from an iterable of key-value pairs.

Example

import{Map}from"@monstermann/map";Map.create([["a",1],["b",2],["c",3],]);// Map(2) { "a" => 1, "b" => 2, "c" => 3 }

every

functionMap.every<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,): boolean

Tests whether all entries in the map pass the test implemented by the predicate function. It returns true if all entries pass, otherwise false.

Example

import{Map}from"@monstermann/map";Map.every(newMap([["a",2],["b",4],["c",6],]),(value)=>value%2===0,);// true

import{Map}from"@monstermann/map";pipe(newMap([["a",2],["b",4],["c",6],]),Map.every((value)=>value%2===0),);// true

filter

functionMap.filter<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,): ReadonlyMap<K,V>

Returns a new map containing only entries that satisfy the predicate function.

Example

import{Map}from"@monstermann/map";Map.filter(newMap([["a",1],["b",2],["c",3],]),(value)=>value>1,);// Map(2) { "b" => 2, "c" => 3 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.filter((value)=>value>1),);// Map(2) { "b" => 2, "c" => 3 }

find

functionMap.find<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,): V|undefined

Returns the first value in the map that satisfies the provided predicate function, or undefined if no value is found.

Example

import{Map}from"@monstermann/map";Map.find(newMap([["a",1],["b",2],["c",3],]),(value)=>value>2,);// 3

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.find((value)=>value>2),);// 3

findMap

functionMap.findMap<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,mapper: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>V,): ReadonlyMap<K,V>

Finds the first entry in the map that satisfies the provided predicate function and applies the mapper function to it, returning a new map with the mapped value.

Example

import{Map}from"@monstermann/map";Map.findMap(newMap([["a",1],["b",2],["c",3],]),(value)=>value>1,(value)=>value*10,);// Map(3) { "a" => 1, "b" => 20, "c" => 3 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findMap((value)=>value>1,(value)=>value*10,),);// Map(3) { "a" => 1, "b" => 20, "c" => 3 }

findMapAll

functionMap.findMapAll<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,mapper: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>V,): ReadonlyMap<K,V>

Finds all entries in the map that satisfy the provided predicate function and applies the mapper function to each of them, returning a new map with the mapped values.

Example

import{Map}from"@monstermann/map";Map.findMapAll(newMap([["a",1],["b",2],["c",3],]),(value)=>value>1,(value)=>value*10,);// Map(3) { "a" => 1, "b" => 20, "c" => 30 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findMapAll((value)=>value>1,(value)=>value*10,),);// Map(3) { "a" => 1, "b" => 20, "c" => 30 }

findMapOr

functionMap.findMapOr<K,V,O>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,mapper: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>V,or: O,): ReadonlyMap<K,V>|O

Finds the first entry in the map that satisfies the provided predicate function and applies the mapper function to it, returning a new map with the mapped value, or or if no entry is found.

Example

import{Map}from"@monstermann/map";Map.findMapOr(newMap([["a",1],["b",2],["c",3],]),(value)=>value>10,(value)=>value*10,newMap(),);// Map(0) {}

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findMapOr((value)=>value>10,(value)=>value*10,newMap(),),);// Map(0) {}

findMapOrElse

functionMap.findMapOrElse<K,V,O>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,mapper: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>V,orElse: (target: ReadonlyMap<K,V>)=>O,): ReadonlyMap<K,V>|O

Finds the first entry in the map that satisfies the provided predicate function and applies the mapper function to it, returning a new map with the mapped value, or the result of calling orElse with the map if no entry is found.

Example

import{Map}from"@monstermann/map";Map.findMapOrElse(newMap([["a",1],["b",2],["c",3],]),(value)=>value>10,(value)=>value*10,(map)=>map.size,);// 3

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findMapOrElse((value)=>value>10,(value)=>value*10,(map)=>map.size,),);// 3

findMapOrThrow

functionMap.findMapOrThrow<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,mapper: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>V,): ReadonlyMap<K,V>

Finds the first entry in the map that satisfies the provided predicate function and applies the mapper function to it, returning a new map with the mapped value, or throws an error if no entry is found.

Example

import{Map}from"@monstermann/map";Map.findMapOrThrow(newMap([["a",1],["b",2],["c",3],]),(value)=>value>1,(value)=>value*10,);// Map(3) { "a" => 1, "b" => 20, "c" => 3 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findMapOrThrow((value)=>value>1,(value)=>value*10,),);// Map(3) { "a" => 1, "b" => 20, "c" => 3 }

findOr

functionMap.findOr<K,V,O>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,or: O,): V|O

Returns the first value in the map that satisfies the provided predicate function, or or if no value is found.

Example

import{Map}from"@monstermann/map";Map.findOr(newMap([["a",1],["b",2],["c",3],]),(value)=>value>10,0,);// 0

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findOr((value)=>value>10,0),);// 0

findOrElse

functionMap.findOrElse<K,V,O>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,orElse: (target: ReadonlyMap<K,V>)=>O,): V|O

Returns the first value in the map that satisfies the provided predicate function, or the result of calling orElse with the map if no value is found.

Example

import{Map}from"@monstermann/map";Map.findOrElse(newMap([["a",1],["b",2],["c",3],]),(value)=>value>10,(map)=>map.size,);// 3

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findOrElse((value)=>value>10,(map)=>map.size,),);// 3

findOrThrow

functionMap.findOrThrow<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,): V

Returns the first value in the map that satisfies the provided predicate function, or throws an error if no value is found.

Example

import{Map}from"@monstermann/map";Map.findOrThrow(newMap([["a",1],["b",2],["c",3],]),(value)=>value>2,);// 3

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findOrThrow((value)=>value>2),);// 3

findRemove

functionMap.findRemove<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,): ReadonlyMap<K,V>

Finds the first entry in the map that satisfies the provided predicate function and removes it, returning a new map without the removed entry.

Example

import{Map}from"@monstermann/map";Map.findRemove(newMap([["a",1],["b",2],["c",3],]),(value)=>value>1,);// Map(2) { "a" => 1, "c" => 3 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findRemove((value)=>value>1),);// Map(2) { "a" => 1, "c" => 3 }

findRemoveOr

functionMap.findRemoveOr<K,V,O>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,or: O,): ReadonlyMap<K,V>|O

Finds the first entry in the map that satisfies the provided predicate function and removes it, returning a new map without the removed entry, or or if no entry is found.

Example

import{Map}from"@monstermann/map";Map.findRemoveOr(newMap([["a",1],["b",2],["c",3],]),(value)=>value>10,newMap(),);// Map(0) {}

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findRemoveOr((value)=>value>10,newMap()),);// Map(0) {}

findRemoveOrElse

functionMap.findRemoveOrElse<K,V,O>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,orElse: (target: ReadonlyMap<K,V>)=>O,): ReadonlyMap<K,V>|O

Finds the first entry in the map that satisfies the provided predicate function and removes it, returning a new map without the removed entry, or the result of calling orElse with the map if no entry is found.

Example

import{Map}from"@monstermann/map";Map.findRemoveOrElse(newMap([["a",1],["b",2],["c",3],]),(value)=>value>10,(map)=>map.size,);// 3

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findRemoveOrElse((value)=>value>10,(map)=>map.size,),);// 3

findRemoveOrThrow

functionMap.findRemoveOrThrow<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,): ReadonlyMap<K,V>

Finds the first entry in the map that satisfies the provided predicate function and removes it, returning a new map without the removed entry, or throws an error if no entry is found.

Example

import{Map}from"@monstermann/map";Map.findRemoveOrThrow(newMap([["a",1],["b",2],["c",3],]),(value)=>value>1,);// Map(2) { "a" => 1, "c" => 3 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findRemoveOrThrow((value)=>value>1),);// Map(2) { "a" => 1, "c" => 3 }

findReplace

functionMap.findReplace<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,replacement: NoInfer<V>,): ReadonlyMap<K,V>

Finds the first entry in the map that satisfies the provided predicate function and replaces its value with replacement, returning a new map with the replaced value.

Example

import{Map}from"@monstermann/map";Map.findReplace(newMap([["a",1],["b",2],["c",3],]),(value)=>value>1,10,);// Map(3) { "a" => 1, "b" => 10, "c" => 3 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findReplace((value)=>value>1,10),);// Map(3) { "a" => 1, "b" => 10, "c" => 3 }

findReplaceOr

functionMap.findReplaceOr<K,V,O>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,replacement: NoInfer<V>,or: O,): ReadonlyMap<K,V>|O

Finds the first entry in the map that satisfies the provided predicate function and replaces its value with replacement, returning a new map with the replaced value, or or if no entry is found.

Example

import{Map}from"@monstermann/map";Map.findReplaceOr(newMap([["a",1],["b",2],["c",3],]),(value)=>value>10,99,newMap(),);// Map(0) {}

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findReplaceOr((value)=>value>10,99,newMap()),);// Map(0) {}

findReplaceOrElse

functionMap.findReplaceOrElse<K,V,O>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,replacement: NoInfer<V>,orElse: (target: ReadonlyMap<K,V>)=>O,): ReadonlyMap<K,V>|O

Finds the first entry in the map that satisfies the provided predicate function and replaces its value with replacement, returning a new map with the replaced value, or the result of calling orElse with the map if no entry is found.

Example

import{Map}from"@monstermann/map";Map.findReplaceOrElse(newMap([["a",1],["b",2],["c",3],]),(value)=>value>10,99,(map)=>map.size,);// 3

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findReplaceOrElse((value)=>value>10,99,(map)=>map.size,),);// 3

findReplaceOrThrow

functionMap.findReplaceOrThrow<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,replacement: NoInfer<V>,): ReadonlyMap<K,V>

Finds the first entry in the map that satisfies the provided predicate function and replaces its value with replacement, returning a new map with the replaced value, or throws an error if no entry is found.

Example

import{Map}from"@monstermann/map";Map.findReplaceOrThrow(newMap([["a",1],["b",2],["c",3],]),(value)=>value>1,99,);// Map(3) { "a" => 1, "b" => 99, "c" => 3 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.findReplaceOrThrow((value)=>value>1,99),);// Map(3) { "a" => 1, "b" => 99, "c" => 3 }

forEach

functionMap.forEach<K,V>(target: ReadonlyMap<K,V>,fn: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>any,): ReadonlyMap<K,V>

Executes a function for each entry in the map and returns the original map.

Example

import{Map}from"@monstermann/map";Map.forEach(newMap([["a",1],["b",2],]),(value,key)=>console.log(key,value),);// Map(2) { "a" => 1, "b" => 2 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.forEach((value,key)=>console.log(key,value)),);// Map(2) { "a" => 1, "b" => 2 }

get

functionMap.get<K,V>(target: ReadonlyMap<K,V>,key: NoInfer<K>,): V|undefined

Gets the value associated with the specified key, or undefined if the key doesn't exist.

Example

import{Map}from"@monstermann/map";Map.get(newMap([["a",1],["b",2],]),"a",);// 1Map.get(newMap([["a",1],["b",2],]),"c",);// undefined

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.get("a"),);// 1pipe(newMap([["a",1],["b",2],]),Map.get("c"),);// undefined

getOr

functionMap.getOr<K,V,U>(target: ReadonlyMap<K,V>,key: NoInfer<K>,or: U,): Exclude<V,null|undefined>|U

Gets the value associated with the specified key, or returns the fallback value if the value is null or undefined.

Example

import{Map}from"@monstermann/map";Map.getOr(newMap([["a",1],["b",null],]),"a",0,);// 1Map.getOr(newMap([["a",1],["b",null],]),"b",0,);// 0Map.getOr(newMap([["a",1],["b",null],]),"c",0,);// 0

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",null],]),Map.getOr("a",0),);// 1pipe(newMap([["a",1],["b",null],]),Map.getOr("b",0),);// 0pipe(newMap([["a",1],["b",null],]),Map.getOr("c",0),);// 0

getOrElse

functionMap.getOrElse<K,V,U>(target: ReadonlyMap<K,V>,key: NoInfer<K>,orElse: (target: ReadonlyMap<K,V>)=>U,): Exclude<V,null|undefined>|U

Gets the value associated with the specified key, or calls the provided function to compute a fallback value if the value is null or undefined.

Example

import{Map}from"@monstermann/map";Map.getOrElse(newMap([["a",1],["b",null],]),"a",()=>0,);// 1Map.getOrElse(newMap([["a",1],["b",null],]),"b",()=>0,);// 0Map.getOrElse(newMap([["a",1],["b",null],]),"c",(map)=>map.size,);// 2

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",null],]),Map.getOrElse("a",()=>0),);// 1pipe(newMap([["a",1],["b",null],]),Map.getOrElse("b",()=>0),);// 0pipe(newMap([["a",1],["b",null],]),Map.getOrElse("c",(map)=>map.size),);// 2

getOrThrow

functionMap.getOrThrow<K,V>(target: ReadonlyMap<K,V>,key: NoInfer<K>,): Exclude<V,null|undefined>

Gets the value associated with the specified key, or throws an error if the value is null or undefined.

Example

import{Map}from"@monstermann/map";Map.getOrThrow(newMap([["a",1],["b",2],]),"a",);// 1Map.getOrThrow(newMap([["a",1],["b",null],]),"b",);// throws FnErrorMap.getOrThrow(newMap([["a",1],["b",2],]),"c",);// throws FnError

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.getOrThrow("a"),);// 1pipe(newMap([["a",1],["b",null],]),Map.getOrThrow("b"),);// throws FnErrorpipe(newMap([["a",1],["b",2],]),Map.getOrThrow("c"),);// throws FnError

has

functionMap.has<K,V>(target: ReadonlyMap<K,V>,key: NoInfer<K>,): boolean

Checks whether the map contains the specified key.

Example

import{Map}from"@monstermann/map";Map.has(newMap([["a",1],["b",2],]),"a",);// trueMap.has(newMap([["a",1],["b",2],]),"c",);// false

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.has("a"),);// truepipe(newMap([["a",1],["b",2],]),Map.has("c"),);// false

hasAll

functionMap.hasAll<K,V>(target: ReadonlyMap<K,V>,keys: Iterable<NoInfer<K>>,): boolean

Checks whether the map contains all of the specified keys.

Example

import{Map}from"@monstermann/map";Map.hasAll(newMap([["a",1],["b",2],["c",3],]),["a","b"],);// trueMap.hasAll(newMap([["a",1],["b",2],["c",3],]),["a","d"],);// false

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.hasAll(["a","b"]),);// truepipe(newMap([["a",1],["b",2],["c",3],]),Map.hasAll(["a","d"]),);// false

hasAny

functionMap.hasAny<K,V>(target: ReadonlyMap<K,V>,keys: Iterable<NoInfer<K>>,): boolean

Checks whether the map contains any of the specified keys.

Example

import{Map}from"@monstermann/map";Map.hasAny(newMap([["a",1],["b",2],]),["a","c"],);// trueMap.hasAny(newMap([["a",1],["b",2],]),["c","d"],);// false

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.hasAny(["a","c"]),);// truepipe(newMap([["a",1],["b",2],]),Map.hasAny(["c","d"]),);// false

hasNone

functionMap.hasNone<K,V>(target: ReadonlyMap<K,V>,keys: Iterable<NoInfer<K>>,): boolean

Checks whether the map contains none of the specified keys.

Example

import{Map}from"@monstermann/map";Map.hasNone(newMap([["a",1],["b",2],]),["c","d"],);// trueMap.hasNone(newMap([["a",1],["b",2],]),["a","c"],);// false

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.hasNone(["c","d"]),);// truepipe(newMap([["a",1],["b",2],]),Map.hasNone(["a","c"]),);// false

is

functionMap.is(target: unknown,): target is Map<unknown,unknown>

Type guard that checks whether a value is a Map instance.

Example

import{Map}from"@monstermann/map";Map.is(newMap());// trueMap.is({});// falseMap.is([]);// false

import{Map}from"@monstermann/map";pipe(newMap(),Map.is());// truepipe({},Map.is());// falsepipe([],Map.is());// false

isEmpty

functionMap.isEmpty<T,U>(target: ReadonlyMap<T,U>): boolean

Checks whether the map is empty (contains no entries).

Example

import{Map}from"@monstermann/map";Map.isEmpty(newMap());// trueMap.isEmpty(newMap([["a",1]]));// false

import{Map}from"@monstermann/map";pipe(newMap(),Map.isEmpty());// truepipe(newMap([["a",1]]),Map.isEmpty());// false

isShallowEqual

functionMap.isShallowEqual<K,V>(target: ReadonlyMap<K,V>,source: ReadonlyMap<NoInfer<K>,NoInfer<V>>,): boolean

Checks whether two maps are shallowly equal (same keys and values using strict equality).

Example

import{Map}from"@monstermann/map";Map.isShallowEqual(newMap([["a",1],["b",2],]),newMap([["a",1],["b",2],]),);// trueMap.isShallowEqual(newMap([["a",1],["b",2],]),newMap([["a",1],["b",3],]),);// false

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.isShallowEqual(newMap([["a",1],["b",2],]),),);// truepipe(newMap([["a",1],["b",2],]),Map.isShallowEqual(newMap([["a",1],["b",3],]),),);// false

map

functionMap.map<K,V>(target: ReadonlyMap<K,V>,key: NoInfer<K>,transform: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>V,): ReadonlyMap<K,V>

Transforms the value at the specified key using the provided function. Returns the original map if the key doesn't exist.

Example

import{Map}from"@monstermann/map";Map.map(newMap([["a",1],["b",2],]),"a",(value)=>value*2,);// Map(2) { "a" => 2, "b" => 2 }Map.map(newMap([["a",1],["b",2],]),"c",(value)=>value*2,);// Map(2) { "a" => 1, "b" => 2 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.map("a",(value)=>value*2),);// Map(2) { "a" => 2, "b" => 2 }pipe(newMap([["a",1],["b",2],]),Map.map("c",(value)=>value*2),);// Map(2) { "a" => 1, "b" => 2 }

mapEach

functionMap.mapEach<K,V,U>(target: ReadonlyMap<K,V>,fn: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>U,): ReadonlyMap<K,U>

Transforms all values in the map using the provided function.

Example

import{Map}from"@monstermann/map";Map.mapEach(newMap([["a",1],["b",2],]),(value,key)=>value*2,);// Map(2) { "a" => 2, "b" => 4 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.mapEach((value,key)=>value*2),);// Map(2) { "a" => 2, "b" => 4 }

mapOr

functionMap.mapOr<K,V,U>(target: ReadonlyMap<K,V>,key: NoInfer<K>,transform: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>V,or: U,): ReadonlyMap<K,V>|U

Transforms the value at the specified key using the provided function, or returns the fallback value if the key doesn't exist.

Example

import{Map}from"@monstermann/map";Map.mapOr(newMap([["a",1],["b",2],]),"a",(value)=>value*2,null,);// Map(2) { "a" => 2, "b" => 2 }Map.mapOr(newMap([["a",1],["b",2],]),"c",(value)=>value*2,null,);// null

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.mapOr("a",(value)=>value*2,null),);// Map(2) { "a" => 2, "b" => 2 }pipe(newMap([["a",1],["b",2],]),Map.mapOr("c",(value)=>value*2,null),);// null

mapOrElse

functionMap.mapOrElse<K,V,U>(target: ReadonlyMap<K,V>,key: NoInfer<K>,transform: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>V,orElse: (target: ReadonlyMap<K,V>)=>U,): ReadonlyMap<K,V>|U

Transforms the value at the specified key using the provided function, or calls the fallback function if the key doesn't exist.

Example

import{Map}from"@monstermann/map";Map.mapOrElse(newMap([["a",1],["b",2],]),"a",(value)=>value*2,()=>null,);// Map(2) { "a" => 2, "b" => 2 }Map.mapOrElse(newMap([["a",1],["b",2],]),"c",(value)=>value*2,(map)=>map.size,);// 2

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.mapOrElse("a",(value)=>value*2,()=>null,),);// Map(2) { "a" => 2, "b" => 2 }pipe(newMap([["a",1],["b",2],]),Map.mapOrElse("c",(value)=>value*2,(map)=>map.size,),);// 2

mapOrThrow

functionMap.mapOrThrow<K,V>(target: ReadonlyMap<K,V>,key: NoInfer<K>,transform: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>V,): ReadonlyMap<K,V>

Transforms the value at the specified key using the provided function, or throws an error if the key doesn't exist.

Example

import{Map}from"@monstermann/map";Map.mapOrThrow(newMap([["a",1],["b",2],]),"a",(value)=>value*2,);// Map(2) { "a" => 2, "b" => 2 }Map.mapOrThrow(newMap([["a",1],["b",2],]),"c",(value)=>value*2,);// throws FnError

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.mapOrThrow("a",(value)=>value*2),);// Map(2) { "a" => 2, "b" => 2 }pipe(newMap([["a",1],["b",2],]),Map.mapOrThrow("c",(value)=>value*2),);// throws FnError

none

functionMap.none<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,): boolean

Returns true if no entries in the map satisfy the provided predicate function, otherwise returns false.

Example

import{Map}from"@monstermann/map";Map.none(newMap([["a",1],["b",2],["c",3],]),(value)=>value>10,);// true

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.none((value)=>value>10),);// true

reject

functionMap.reject<K,V>(target: ReadonlyMap<K,V>,by: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,): ReadonlyMap<K,V>

Returns a new map excluding entries that satisfy the predicate function.

Example

import{Map}from"@monstermann/map";Map.reject(newMap([["a",1],["b",2],["c",3],]),(value)=>value>1,);// Map(1) { "a" => 1 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.reject((value)=>value>1),);// Map(1) { "a" => 1 }

remove

functionMap.remove<K,V>(target: ReadonlyMap<K,V>,key: NoInfer<K>,): ReadonlyMap<K,V>

Removes the specified key from the map. Returns the original map if the key doesn't exist.

Example

import{Map}from"@monstermann/map";Map.remove(newMap([["a",1],["b",2],]),"a",);// Map(1) { "b" => 2 }Map.remove(newMap([["a",1],["b",2],]),"c",);// Map(2) { "a" => 1, "b" => 2 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.remove("a"),);// Map(1) { "b" => 2 }pipe(newMap([["a",1],["b",2],]),Map.remove("c"),);// Map(2) { "a" => 1, "b" => 2 }

removeAll

functionMap.removeAll<K,V>(target: ReadonlyMap<K,V>,keys: Iterable<NoInfer<K>>,): ReadonlyMap<K,V>

Removes all specified keys from the map.

Example

import{Map}from"@monstermann/map";Map.removeAll(newMap([["a",1],["b",2],["c",3],]),["a","c"],);// Map(1) { "b" => 2 }Map.removeAll(newMap([["a",1],["b",2],["c",3],]),["d","e"],);// Map(3) { "a" => 1, "b" => 2, "c" => 3 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.removeAll(["a","c"]),);// Map(1) { "b" => 2 }pipe(newMap([["a",1],["b",2],["c",3],]),Map.removeAll(["d","e"]),);// Map(3) { "a" => 1, "b" => 2, "c" => 3 }

removeOr

functionMap.removeOr<K,V,U>(target: ReadonlyMap<K,V>,key: NoInfer<K>,or: U,): Map<K,V>|U

Removes the specified key from the map, or returns the fallback value if the key doesn't exist.

Example

import{Map}from"@monstermann/map";Map.removeOr(newMap([["a",1],["b",2],]),"a",null,);// Map(1) { "b" => 2 }Map.removeOr(newMap([["a",1],["b",2],]),"c",null,);// null

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.removeOr("a",null),);// Map(1) { "b" => 2 }pipe(newMap([["a",1],["b",2],]),Map.removeOr("c",null),);// null

removeOrElse

functionMap.removeOrElse<K,V,U>(target: ReadonlyMap<K,V>,key: NoInfer<K>,orElse: (target: ReadonlyMap<K,V>)=>U,): Map<K,V>|U

Removes the specified key from the map, or calls the fallback function if the key doesn't exist.

Example

import{Map}from"@monstermann/map";Map.removeOrElse(newMap([["a",1],["b",2],]),"a",()=>null,);// Map(1) { "b" => 2 }Map.removeOrElse(newMap([["a",1],["b",2],]),"c",(map)=>map.size,);// 2

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.removeOrElse("a",()=>null),);// Map(1) { "b" => 2 }pipe(newMap([["a",1],["b",2],]),Map.removeOrElse("c",(map)=>map.size),);// 2

removeOrThrow

functionMap.removeOrThrow<K,V>(target: ReadonlyMap<K,V>,key: NoInfer<K>,): Map<K,V>

Removes the specified key from the map, or throws an error if the key doesn't exist.

Example

import{Map}from"@monstermann/map";Map.removeOrThrow(newMap([["a",1],["b",2],]),"a",);// Map(1) { "b" => 2 }Map.removeOrThrow(newMap([["a",1],["b",2],]),"c",);// throws FnError

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.removeOrThrow("a"),);// Map(1) { "b" => 2 }pipe(newMap([["a",1],["b",2],]),Map.removeOrThrow("c"),);// throws FnError

set

functionMap.set<K,V>(target: ReadonlyMap<K,V>,key: NoInfer<K>,value: NoInfer<V>,): ReadonlyMap<K,V>

Sets or updates the value for the specified key in the map.

Example

import{Map}from"@monstermann/map";Map.set(newMap([["a",1],["b",2],]),"a",10,);// Map(2) { "a" => 10, "b" => 2 }Map.set(newMap([["a",1],["b",2],]),"c",3,);// Map(3) { "a" => 1, "b" => 2, "c" => 3 }

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],]),Map.set("a",10),);// Map(2) { "a" => 10, "b" => 2 }pipe(newMap([["a",1],["b",2],]),Map.set("c",3),);// Map(3) { "a" => 1, "b" => 2, "c" => 3 }

some

functionMap.some<K,V>(target: ReadonlyMap<K,V>,predicate: (value: NoInfer<V>,key: NoInfer<K>,target: ReadonlyMap<K,V>,)=>boolean,): boolean

Returns true if at least one entry in the map satisfies the provided predicate function, otherwise returns false.

Example

import{Map}from"@monstermann/map";Map.some(newMap([["a",1],["b",2],["c",3],]),(value)=>value>2,);// true

import{Map}from"@monstermann/map";pipe(newMap([["a",1],["b",2],["c",3],]),Map.some((value)=>value>2),);// true

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
benchmarks		benchmarks
docs		docs
packages		packages
playground		playground
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
barrels.config.ts		barrels.config.ts
bun.lock		bun.lock
eslint.config.js		eslint.config.js
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

map

Features

Installation

Tree-shaking

Installation

Usage

Map

clone

Example

compact

Example

create

Example

every

Example

filter

Example

find

Example

findMap

Example

findMapAll

Example

findMapOr

Example

findMapOrElse

Example

findMapOrThrow

Example

findOr

Example

findOrElse

Example

findOrThrow

Example

findRemove

Example

findRemoveOr

Example

findRemoveOrElse

Example

findRemoveOrThrow

Example

findReplace

Example

findReplaceOr

Example

findReplaceOrElse

Example

findReplaceOrThrow

Example

forEach

Example

get

Example

getOr

Example

getOrElse

Example

getOrThrow

Example

has

Example

hasAll

Example

hasAny

Example

hasNone

Example

is

Example

isEmpty

Example

isShallowEqual

Example

map