JS: the Map Object Tutorial

New in ES2015.

1. Map objects are collections of key/value pairs. Each pair is called a “entry”.
2. The key can be any value type. [see JS: Value Types]
3. The value can be any JavaScript type.
4. Keys are always distinct.
5. 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 JS: 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 JS: Access Property]

• 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 JS: Iterable]

const 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
const m = new Map([ [3, "n3"], [4, "n4"]]);
console.log(m) // Map { 3 => 'n3', 4 => 'n4' }

Note: the map constructor (new Map()) does not accept a object datatype.

[see JS: Map Constructor]

[see JS: Convert Object to/from Map]

Parent of Map Objects

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

[see JS: Prototype and Inheritance]

Size of Map

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

// size of map
const 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
const m = new Map();
m.set (1,2);
m.set ("a","b");
console.log(m); // Map { 1 => 2, 'a' => 'b' }

[see JS: Map.prototype.set]

Delete a Entry

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

const 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 JS: Map.prototype.delete]

Check Existence

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

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

[see JS: 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.

const 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 JS: Map.prototype.get]

Clear Map

JS: Map.prototype.clear

Iterate Map

[see JS: Iterate Over Map Object]

Get All Keys

[see JS: Map.prototype.keys]

Get All Values

[see JS: 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.)

const 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