JavaScript: the Map Object Tutorial

New in ES2015.

Map objects are collections of key/value pairs. Each pair is called a “entry”.

The key can be any JavaScript type.

The value can be any JavaScript type. 〔►see JavaScript: Data Types〕

Keys are always distinct.

The insertion order of entries are maintained.

The map object is designed to be used as a map data structure (similar to Python Dictionary or Ruby Hash Table or Java Collection, Map. ).

What's the difference between object and map?

• Map object's keys can be any type. Object's keys can be only string or symbol. 〔►see JavaScript: Symbol Tutorial〕

• The key/value pairs in map object are not properties. You don't have to worry about getting property key from parent object, or if a property is not enumerable. 〔►see JavaScript: Access Property, List Properties〕

• Map object is designed to be used as a map data structure (aka hash table). For example, there's a “size” property to let you find number of entries, and there are proper methods to iterate thru the entries.

Creating Map

new Map() → creates a empty map.

new Map(iterable) → create a map from values in iterable object iterable.

〔►see JavaScript: Iterable〕

var m = new Map();

// add new item
m.set(1, "n1");
m.set(2, "n2");

console.log(m) // Map { 1 => 'n1', 2 => 'n2' }

There's no literal expression for map. But you can pass in a literal expression of array of array, like this:

// using nested array as literal expression for map
var m = new Map([ [3, "n3"], [4, "n4"]]);
console.log(m) // Map { 3 => 'n3', 4 => 'n4' }

Parent of Map Objects

The parent (aka prototype) of any map object is Map.prototype.

〔►see JavaScript: Prototype and Inheritance〕

Size of Map

map_obj.size → returns the total count of entries in map_obj.

// size of map
var m = new Map([["3", "n3"], ["4", "n4"] ]);
console.log(m.size); // 2

Set/Add a Entry

map.set(key, val) → add an entry to the map. If the key already exists, overwrite its value. Returns the modified map.

// create a map, add entry to it
var m = new Map();
m.set (1,2);
m.set ("a","b");
console.log(m); // Map { 1 => 2, 'a' => 'b' }

〔►see JavaScript: Map.prototype.set〕

Delete a Entry

map.delete(key) → delete the entry of key. Returns true if found, else false.

var m = new Map([[3, "n3"], [4, "n4"] ]);

// delete a entry. return true if found
console.log(m.delete(4)); // true
console.log(m.delete(99)); // false

console.log(m); // Map { 3 => 'n3'}

〔►see JavaScript: Map.prototype.delete〕

Check Existence

map.has(key) → return true if key exist. Else, false.

// check existence
var m = new Map([ [4, "n4"], [5, "n5"] ]);
console.log(m.has (5)); // true
console.log(m.has (99)); // false

〔►see JavaScript: Map.prototype.has〕

Get Value of a Key

map.get(key) → return the value of the key key. If key isn't found, return undefined.

var m = new Map([ [4, "n4"], [5, "n5"] ]);

// get the value of a key
console.log(m.get (5)); // "n5"

console.log(m.get (99)); // undefined

〔►see JavaScript: Map.prototype.get〕

Clear Map

JavaScript: Map.prototype.clear

Iterate Map

〔►see JavaScript: Iterate Over Map Object〕

Get All Keys

〔►see JavaScript: Map.prototype.keys〕

Get All Values

〔►see JavaScript: Map.prototype.values〕

Add Arbitrary Properties to Map

Because map is a object, you can still add arbitrary properties to a map object. (but you shouldn't do it.)

var m = new Map([[3, "n3"], [4, "n4"], [5, "n5"] ]);

// you can add arbitrary properties to a map object
m.pp = 22;
console.log(m.pp) // 22

console.log(Object.getOwnPropertyNames(m)); // [ 'pp' ]

Reference

ECMAScript 2015 §Keyed Collection#sec-map-objects