DefaultMap

DefaultMap is a data structure that makes working with default values easier. It extends a Map and adds additional methods.

It is a common pattern to look up a value in a Map, and then, if the value does not exist, set a default value for the key, and then return the default value. DefaultMap abstracts this operation away by providing the getAndSetDefault method.

Using a DefaultMap is nice because it makes code more declarative, since you specify what the default value is alongside the types of the keys/values.

When instantiating a new DefaultMap, you must specify default value as the first argument. (The default value is the initial value that will be assigned to every new entry in the getAndSetDefault method.) For example:

// Initializes a new empty DefaultMap with a default value of "foo".
const defaultMapWithString = new DefaultMap<string, string>("foo");

const value = defaultMapWithString.getAndSetDefault("bar");
// value is now "foo" and an entry for "bar" is now set.

Sometimes, instead of having a static initial value for every entry in the map, you will want a dynamic initial value that is contingent upon the key or some other variable. In these cases, you can instead specify that the DefaultMap should run a function that will return the initial value. (This is referred to as a "factory function".) For example:

// Initializes a new empty DefaultMap with a default value based on "someGlobalVariable".
const factoryFunction = () => someGlobalVariable ? 0 : 1;
const defaultMapWithFactoryFunction = new DefaultMap<string, string>(factoryFunction);

Note that in TypeScript and Lua, booleans, numbers, and strings are "passed by value". This means that when the DefaultMap creates a new entry, if the default value is one of these 3 types, the values will be copied. On the other hand, arrays and maps and other complex data structures are "passed by reference". This means that when the DefaultMap creates a new entry, if the default value is an array, then it would not be copied. Instead, the same shared array would be assigned to every entry. Thus, to solve this problem, any variable that is passed by reference must be created using a factory function to ensure that each copy is unique. For example:

// Initializes a new empty DefaultMap with a default value of a new empty array.
const factoryFunction = () => [];
const defaultMapWithArray = new DefaultMap<string, string[]>(factoryFunction);

In the previous two examples, the factory functions did not have any arguments. But you can also specify a factory function that takes one or more arguments:

const factoryFunction = (arg: boolean) => arg ? 0 : 1;
const defaultMapWithArg = new DefaultMap<string, string, [arg: boolean]>(factoryFunction);

Similar to a normal Map, you can also include an initializer list in the constructor as the second argument:

// Initializes a DefaultMap with a default value of "foo" and some initial values.
const defaultMapWithInitialValues = new DefaultMap<string, string>("foo", [
  ["a1", "a2"],
  ["b1", "b2"],
], );

Finally, note that DefaultMap has the following additional utility methods:

• getAndSetDefault - The method that is called inside the overridden get method. In most cases, you can use the overridden get method instead of calling this function directly. However, if a factory function was provided during instantiation, and the factory function has one or more arguments, then you must call this method instead (and provide the corresponding arguments).
• getDefaultValue - Returns the default value to be used for a new key. (If a factory function was provided during instantiation, this will execute the factory function.)
• getConstructorArg - Helper method for cloning the map. Returns either the default value or the reference to the factory function.

Type parameters

Name	Type
Key	Key
Value	Value
Args	extends unknown[] = []

Hierarchy

• Map<Key, Value>

  ↳ DefaultMap

Constructors

constructor

• new DefaultMap<Key, Value, Args>(defaultValueOrFactoryFunction, initializerArray?): DefaultMap<Key, Value, Args>

See the main DefaultMap documentation: https://isaacscript.github.io/isaacscript-common/other/classes/DefaultMap

Type parameters

Name	Type
Key	Key
Value	Value
Args	extends unknown[] = []

Parameters

Name	Type
defaultValueOrFactoryFunction	Value | FactoryFunction<Value, Args>
initializerArray?	Iterable<[Key, Value]>

Returns

DefaultMap<Key, Value, Args>

Overrides

Map&lt; Key, Value &gt;.constructor

Defined in

packages/isaacscript-common/src/classes/DefaultMap.ts:95

Properties

size

• Readonly size: number

Inherited from

Map.size

Defined in

node_typescript/lib/lib.es2015.collection.d.ts:45

---

[toStringTag]

• Readonly [toStringTag]: string

Inherited from

Map.[toStringTag]

Defined in

node_typescript/lib/lib.es2015.symbol.wellknown.d.ts:137

---

[species]

▪ Static Readonly [species]: MapConstructor

Inherited from

Map.[species]

Defined in

node_typescript/lib/lib.es2015.symbol.wellknown.d.ts:319

Methods

clear

▸ clear(): void

Returns

void

Inherited from

Map.clear

Defined in

node_typescript/lib/lib.es2015.collection.d.ts:20

---

delete

▸ delete(key): boolean

Parameters

Name	Type
key	Key

Returns

boolean

true if an element in the Map existed and has been removed, or false if the element does not exist.

Inherited from

Map.delete

Defined in

node_typescript/lib/lib.es2015.collection.d.ts:24

---

forEach

▸ forEach(callbackfn, thisArg?): void

Executes a provided function once per each key/value pair in the Map, in insertion order.

Parameters

Name	Type
callbackfn	(value: Value, key: Key, map: Map<Key, Value>) => void
thisArg?	any

Returns

void

Inherited from

Map.forEach

Defined in

node_typescript/lib/lib.es2015.collection.d.ts:28

---

get

▸ get(key): undefined | Value

Returns a specified element from the Map object. If the value that is associated to the provided key is an object, then you will get a reference to that object and any change made to that object will effectively modify it inside the Map.

Parameters

Name	Type
key	Key

Returns

undefined | Value

Returns the element associated with the specified key. If no element is associated with the specified key, undefined is returned.

Inherited from

Map.get

Defined in

node_typescript/lib/lib.es2015.collection.d.ts:33

---

has

▸ has(key): boolean

Parameters

Name	Type
key	Key

Returns

boolean

boolean indicating whether an element with the specified key exists or not.

Inherited from

Map.has

Defined in

node_typescript/lib/lib.es2015.collection.d.ts:37

---

set

▸ set(key, value): this

Adds a new element with a specified key and value to the Map. If an element with the same key already exists, the element will be updated.

Parameters

Name	Type
key	Key
value	Value

Returns

this

Inherited from

Map.set

Defined in

node_typescript/lib/lib.es2015.collection.d.ts:41

---

[iterator]

▸ [iterator](): IterableIterator<[Key, Value]>

Returns an iterable of entries in the map.

Returns

IterableIterator<[Key, Value]>

Inherited from

Map.[iterator]

Defined in

node_typescript/lib/lib.es2015.iterable.d.ts:119

---

entries

▸ entries(): IterableIterator<[Key, Value]>

Returns an iterable of key, value pairs for every entry in the map.

Returns

IterableIterator<[Key, Value]>

Inherited from

Map.entries

Defined in

node_typescript/lib/lib.es2015.iterable.d.ts:124

---

keys

▸ keys(): IterableIterator<Key>

Returns an iterable of keys in the map

Returns

IterableIterator<Key>

Inherited from

Map.keys

Defined in

node_typescript/lib/lib.es2015.iterable.d.ts:129

---

values

▸ values(): IterableIterator<Value>

Returns an iterable of values in the map

Returns

IterableIterator<Value>

Inherited from

Map.values

Defined in

node_typescript/lib/lib.es2015.iterable.d.ts:134

---

groupBy

▸ groupBy<K, T>(items, keySelector): Map<K, T[]>

Groups members of an iterable according to the return value of the passed callback.

Type parameters

Name
K
T

Parameters

Name	Type	Description
items	Iterable<T>	An iterable.
keySelector	(item: T, index: number) => K	A callback which will be invoked for each item in items.

Returns

Map<K, T[]>

Inherited from

Map.groupBy

Defined in

node_typescript/lib/lib.esnext.collection.d.ts:25

---

getAndSetDefault

▸ getAndSetDefault(key, ...args): Value

If the key exists, this will return the same thing as the normal Map.get method. Otherwise, it will set a default value for the provided key, and then return the default value.

Parameters

Name	Type
key	Key
...args	Args

Returns

Value

Allow Empty Variadic

Defined in

packages/isaacscript-common/src/classes/DefaultMap.ts:124

---

getDefaultValue

▸ getDefaultValue(...args): Value

Returns the default value to be used for a new key. (If a factory function was provided during instantiation, this will execute the factory function.)

Parameters

Name	Type
...args	Args

Returns

Value

Defined in

packages/isaacscript-common/src/classes/DefaultMap.ts:139

---

getConstructorArg

▸ getConstructorArg(): Value | FactoryFunction<Value, Args>

Helper method for cloning the map. Returns either the default value or a reference to the factory function.

Returns

Value | FactoryFunction<Value, Args>

Defined in

packages/isaacscript-common/src/classes/DefaultMap.ts:155