DefaultMap

Classes

DefaultMap

Defined in: packages/isaacscript-common/src/classes/DefaultMap.ts:82

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.

Extends

• Map<Key, Value>

Type Parameters

Key

Key

Value

Value

Args

Args extends unknown[] = []

Constructors

Constructor

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

Defined in: packages/isaacscript-common/src/classes/DefaultMap.ts:94

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

Parameters

defaultValueOrFactoryFunction

Value | FactoryFunction<Value, Args>

initializerArray?

Iterable<[Key, Value], any, any>

Returns

DefaultMap<Key, Value, Args>

Overrides

Map< Key, Value >.constructor

Properties

size

readonly size: number

Defined in: node_modules/typescript/lib/lib.es2015.collection.d.ts:46

Returns

the number of elements in the Map.

Inherited from

Map.size

[toStringTag]

readonly [toStringTag]: string

Defined in: node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts:135

Inherited from

Map.[toStringTag]

[species]

readonly static [species]: MapConstructor

Defined in: node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts:317

Inherited from

Map.[species]

Methods

getAndSetDefault()

getAndSetDefault(key, …args): Value

Defined in: packages/isaacscript-common/src/classes/DefaultMap.ts:123

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

key

Key

args

…Args

Returns

Value

Allow Empty Variadic

getDefaultValue()

getDefaultValue(…args): Value

Defined in: packages/isaacscript-common/src/classes/DefaultMap.ts:138

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

args

…Args

Returns

Value

getConstructorArg()

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

Defined in: packages/isaacscript-common/src/classes/DefaultMap.ts:154

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

Returns

Value | FactoryFunction<Value, Args>

clear()

clear(): void

Defined in: node_modules/typescript/lib/lib.es2015.collection.d.ts:21

Removes all elements from the Map.

Returns

void

Inherited from

Map.clear

delete()

delete(key): boolean

Defined in: node_modules/typescript/lib/lib.es2015.collection.d.ts:25

Parameters

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

forEach()

forEach(callbackfn, thisArg?): void

Defined in: node_modules/typescript/lib/lib.es2015.collection.d.ts:29

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

Parameters

callbackfn

(value, key, map) => void

thisArg?

any

Returns

void

Inherited from

Map.forEach

get()

get(key): Value | undefined

Defined in: node_modules/typescript/lib/lib.es2015.collection.d.ts:34

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

key

Key

Returns

Value | undefined

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

Inherited from

Map.get

has()

has(key): boolean

Defined in: node_modules/typescript/lib/lib.es2015.collection.d.ts:38

Parameters

key

Key

Returns

boolean

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

Inherited from

Map.has

set()

set(key, value): this

Defined in: node_modules/typescript/lib/lib.es2015.collection.d.ts:42

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

key

Key

value

Value

Returns

this

Inherited from

Map.set

[iterator]()

[iterator](): MapIterator<[Key, Value]>

Defined in: node_modules/typescript/lib/lib.es2015.iterable.d.ts:141

Returns an iterable of entries in the map.

Returns

MapIterator<[Key, Value]>

Inherited from

Map.[iterator]

entries()

entries(): MapIterator<[Key, Value]>

Defined in: node_modules/typescript/lib/lib.es2015.iterable.d.ts:146

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

Returns

MapIterator<[Key, Value]>

Inherited from

Map.entries

keys()

keys(): MapIterator<Key>

Defined in: node_modules/typescript/lib/lib.es2015.iterable.d.ts:151

Returns an iterable of keys in the map

Returns

MapIterator<Key>

Inherited from

Map.keys

values()

values(): MapIterator<Value>

Defined in: node_modules/typescript/lib/lib.es2015.iterable.d.ts:156

Returns an iterable of values in the map

Returns

MapIterator<Value>

Inherited from

Map.values

groupBy()

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

Defined in: node_modules/typescript/lib/lib.es2024.collection.d.ts:23

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

Type Parameters

K

K

T

T

Parameters

items

Iterable<T>

An iterable.

keySelector

(item, index) => K

A callback which will be invoked for each item in items.

Returns

Map<K, T[]>

Inherited from

Map.groupBy

getOrInsert()

getOrInsert(key, defaultValue): Value

Defined in: node_modules/typescript/lib/lib.esnext.collection.d.ts:25

Returns a specified element from the Map object. If no element is associated with the specified key, a new element with the value defaultValue will be inserted into the Map and returned.

Parameters

key

Key

defaultValue

Value

Returns

Value

The element associated with the specified key, which will be defaultValue if no element previously existed.

Inherited from

Map.getOrInsert

getOrInsertComputed()

getOrInsertComputed(key, callback): Value

Defined in: node_modules/typescript/lib/lib.esnext.collection.d.ts:31

Returns a specified element from the Map object. If no element is associated with the specified key, the result of passing the specified key to the callback function will be inserted into the Map and returned.

Parameters

key

Key

callback

(key) => Value

Returns

Value

The element associated with the specific key, which will be the newly computed value if no element previously existed.

Inherited from

Map.getOrInsertComputed

Type Aliases

FactoryFunction

FactoryFunction<V, Args> = (…args) => V

Defined in: packages/isaacscript-common/src/classes/DefaultMap.ts:175

A function that creates the default value for your DefaultMap. For example, if it was a DefaultMap containing maps, the factory function would be:

() => new Map()

Type Parameters

V

V

Args

Args extends unknown[]

Parameters

args

…Args

Returns

V