Map

MMO.core · 1 symbol · generated 5 Oct 2026

class

Map

Extension of a javascript Map with events.

class MMO.core.Map extends MMO.core.mixinEventEmitter(Map)

Namespace: MMO.core
Extends: mixinEventEmitter(Map)

Events are triggered asynchronously whenever a change happen on the map. All events have the same signature function (type, map, path, value), where: - type: is one of the MMO.core.MAP_* constant - map is the current map triggering the event - path is the key at which the event is triggered, except for - MMO.core.MAP_CHANGED: this argument is not used - MMO.core.MAP_CONNECT|MMO.core.MAP_DISCONNECT: it is the path of the value compare to the current map - value is only used by : - MMO.core.MAP_INDEX_CHANGED: it is the old index of the key - MMO.core.MAP_KEY_CHANGED: it is the old key - MMO.core.MAP_CONNECT|MMO.core.MAP_DISCONNECT: it is the map being connected Events propagate from the target to all its parents. There are 2 types of events. 1. The ones registered at a given key: `map.on(key, fn(type, map, key, value))` - MMO.core.MAP_VALUE_CHANGED - MMO.core.MAP_VALUE_CREATED - MMO.core.MAP_VALUE_DELETED - MMO.core.MAP_INDEX_CHANGED - MMO.core.MAP_KEY_CHANGED 2. The ones registered with a Symbol: `map.on(MMO.core.MAP_xxx, fn(type, map, key, value))` - MMO.core.MAP_CHANGED - MMO.core.MAP_CONNECT - MMO.core.MAP_DISCONNECT Note: in order for the watches to work, MMO.core.MAP_CONNECT and MMO.core.MAP_DISCONNECT are emitted synchronously

Index

	length accessor	Alias of `size`, so an array Map reads like a javascript array.
	constructor(args)
	From(obj, schema, _hash) static	Build a Map from any plain value, recursively.
	toObject(deep, _hash)	Convert this object to primitive object/array
	toArray(deep, _hash)	Force conversion of this map to an array (if toObject returned an array, only its values are returned)
	toJSON()	Convert this object to primitive object/array
	isEqual(obj, strictOrder)	Test if content of this map is strictly equal to the content of an object
	isSimilar(obj)	Test whether this map CONTAINS the content of an object (a one-way comparison).
	isEmpty()
	getText(key)	Render a value as plain text, through the key's schema when there is one.
	getHTML(key)	Render a value as html, through the key's schema when there is one.
	keyOf(value)	Find the key holding a value (strict equality, first match).
	indexOf(value)	Find the position of a value (strict equality, first match).
	indexOfKey(key)	Find the position of a key.
	keyAtIndex(index)	Get the key sitting at a given index.
	ketAtIndex(index) deprecated
	pathOf(value, _hash)	Get the path of a value
	connectChild(map, key)
	disconnectChild(map, key)	Detach a child map: emit MMO.core.MAP_DISCONNECT, then forget the parent link.
	loopEventsByScopeRecursive(scope, _hash) generator	Yield all events concerning a given scope recursively
	loopEmit() generator	Yield the entries of the global run queue that concern this map, i.e.
	emitChange(_hash)	Emit change asynchronously
	emitValueChange(key, type, _hash)	Emit change of a value at a given key, asynchronously
	emitIndexChange(key, oldIndex)	Emit change of index of a given key, asynchronously
	emitKeyChange(oldKey, newKey, _hash)	Emit a change of key on newKey
	emitChildConnection(type, path, map, _hash)	Emit connection/disconnection of a child synchronously
	watch(path, listener, event, scope)	Watch a value at a given path The listener is called immediately after it has connected successfully.
	unwatch(path, listener, event, scope)	Unwatch a value at a given path
	connectWatch(path, event, bind)	Try to connect watch at a given path.
	disconnectWatch(path, event, bind)	Undo `MMO.core.Map#connectWatch`.
	disconnectScope(scope)	Remove all watch/events set by a given scope
	changeWatchPath(oldPath, newPath, _hash)	Move watch from a path to another
	onChildConnection(type, parent, path, map)	[internal] React to a child being connected or disconnected anywhere below this map, by (re)connecting the watches whose path is now reachable, and dropping the others.
	extendedEntries() generator	Get a list of entries, index and events
	setExtendedEntries(entries, preserveArray)	Set values, keus, indexes and readjust watch path and events INTERNAL: used by sort or changeIndex
	clear()	Clear the map
	get(key)	Read a value.
	set(key, value, _hash)	Set the value at a given key
	delete(key)	Delete a value at a given key
	changeKey(oldKey, newKey, moveValue)	Change key of a value without changing its index.
	changeIndex(key, index, preserveArray)	Change index of a key
	setValue(obj, _hash)	Set the content of this map with the content of an object
	merge(obj, _hash)	Merge values from another object
	yieldWalk(path, create) generator	Walk through the map using json path, creating the structure if needed.
	walkTo(path, create)	Walk through the map using json path, creating the structure if needed.
	keyAt(path)	Get the last key of a path.
	mapAt(path, create)	Get the map HOLDING the value at a path (its parent), not the value itself.
	getAt(path, create)	Get the value at a path.
	safeGetAt(path, def)	Get the value at a path, never throwing.
	exists(path)	Test whether a path holds a value.
	setAt(path, value)	Set a value at a path, creating the missing levels along the way.
	mergeAt(path, value)	Merge a value into a path: recursive when both sides are maps, a plain set otherwise.
	deleteAt(path)	Delete element at given path
	isArray(allowEmpty)	Check if content is a json array (indexes are ordered integer starting from 0)
	push(value)	Append a value.
	unshift(value)	Insert a value in front, shifting every other item up one index.
	pop()	Remove and return the last value.
	shift()	Remove and return the first value, shifting every other item down one index.
	includes(value, similar)	Test whether a value is present.
	usort(cmp, preserveArray)	Sort by key and value
	ksort(cmp)	Sort by keys
	sort(cmp, preserveArray)	Sort by values
	setSchema(schema)	Set map schema
	getKeySchema(key, resolveInstance)	Get the schema describing one key.
	validate()	Validate the map against its schema
	validateKey(key)	Validate one key against its schema.

Properties1

length

accessorMap.js:1215

Alias of size, so an array Map reads like a javascript array.

get length() set length(value)

Type: number

Methods65

constructor(args)

Map.js:65

constructor(...args)

...args

From(obj, schema, _hash)

staticMap.js:80

Build a Map from any plain value, recursively.

static From(obj, schema = null, _hash = new WeakMap())

Nested objects and arrays become Maps too, so the whole tree is observable.

obj	`Object` \| `Array` \| `Map`	the data to import
schema = null	`?(MMO.schemas.Schema` \| `Promise` \| `Object)`	an optional schema to attach
_hash = new WeakMap()	`WeakMap`	[internal] prevents infinite recursion on cyclic data
returns	`this`	an instance of the class From was called on (so Entity.From yields an Entity)

toObject(deep, _hash)

Map.js:98

Convert this object to primitive object/array

toObject(deep = true, _hash = new WeakMap())

deep = true	`Boolean`	if deep, recursively convert inner MMO.core.Map
_hash = new WeakMap()
returns	`Object` \| `Array`

toArray(deep, _hash)

Map.js:116

Force conversion of this map to an array (if toObject returned an array, only its values are returned)

toArray(deep = true, _hash = new WeakMap())

deep = true
_hash = new WeakMap()
returns	`Array`

toJSON()

Map.js:125

Convert this object to primitive object/array

toJSON()

returns Object | Array

isEqual(obj, strictOrder)

Map.js:135

Test if content of this map is strictly equal to the content of an object

isEqual(obj, strictOrder = true)

obj	`Object`
strictOrder = true	`Boolean`	if true check if the order of the keys match too
returns	`Boolean`

isSimilar(obj)

Map.js:145

Test whether this map CONTAINS the content of an object (a one-way comparison).

isSimilar(obj)

See: MMO.core.isSimilar for the exact rules

obj	`Object` \| `Map`
returns	`boolean`

isEmpty()

Map.js:152

isEmpty()

returns boolean true when the map holds nothing

getText(key)

Map.js:161

Render a value as plain text, through the key's schema when there is one.

getText(key)

key	`string` \| `number`
returns	`string`

getHTML(key)

Map.js:172

Render a value as html, through the key's schema when there is one.

getHTML(key)

key	`string` \| `number`
returns	`string` \| `Element`

keyOf(value)

Map.js:186

Find the key holding a value (strict equality, first match).

keyOf(value)

value	`*`
returns	`?(string` \| `number)`	null when the value is absent

indexOf(value)

Map.js:198

Find the position of a value (strict equality, first match).

indexOf(value)

value	`*`
returns	`number`	-1 when the value is absent

indexOfKey(key)

Map.js:212

Find the position of a key.

indexOfKey(key)

key	`string` \| `number`
returns	`number`	-1 when the key is absent

keyAtIndex(index)

Map.js:226

Get the key sitting at a given index.

keyAtIndex(index)

index	`number`	a negative index counts back from the end
returns	`?(string` \| `number)`	null when the index is out of range

ketAtIndex(index)

deprecatedMap.js:238

ketAtIndex(index)

index

pathOf(value, _hash)

Map.js:247

Get the path of a value

pathOf(value, _hash = new WeakSet())

value	`*`
_hash = new WeakSet()
returns	`Array` \| `null`

connectChild(map, key)

Map.js:265

connectChild(map, key)

map
key

disconnectChild(map, key)

Map.js:287

Detach a child map: emit MMO.core.MAP_DISCONNECT, then forget the parent link.

disconnectChild(map, key)

The event is emitted FIRST so listeners can still see the tree they are leaving.

map	MMO.core.Map	the child
key	`string` \| `number`	the key it was held at

loopEventsByScopeRecursive(scope, _hash)

generatorMap.js:298

Yield all events concerning a given scope recursively

*loopEventsByScopeRecursive(scope, _hash = new WeakSet())

scope	`object`	the scope to look for in EventBinding
_hash = new WeakSet()	`WeakSet`	(internal) prevent recursion

loopEmit()

generatorMap.js:322

Yield the entries of the global run queue that concern this map, i.e. the changes that have been emitted but not yet delivered.

*loopEmit()

emitChange(_hash)

Map.js:334

Emit change asynchronously

emitChange(_hash = new WeakSet())

_hash = new WeakSet()

emitValueChange(key, type, _hash)

Map.js:352

Emit change of a value at a given key, asynchronously

emitValueChange(key, type = MMO.core.MAP_VALUE_CHANGED, _hash = new WeakSet())

key	`string` \| `int`
type = MMO.core.MAP_VALUE_CHANGED	`string`	one of MMO.core.(MAP_VALUE_CREATED\|MAP_VALUE_CHANGED\|MAP_VALUE_DELETED)
_hash = new WeakSet()

emitIndexChange(key, oldIndex)

Map.js:366

Emit change of index of a given key, asynchronously

emitIndexChange(key, oldIndex)

key	`string` \| `int`
oldIndex	`int`	the old index of the key

emitKeyChange(oldKey, newKey, _hash)

Map.js:378

Emit a change of key on newKey

emitKeyChange(oldKey, newKey, _hash = new WeakSet())

oldKey	`string`	the old key for the value
newKey	`string`	the new key for the value
_hash = new WeakSet()

emitChildConnection(type, path, map, _hash)

Map.js:392

Emit connection/disconnection of a child synchronously

emitChildConnection(type, path, map, _hash = new WeakSet())

type	`Symbol`	MMO.core.MAP_CONNECT \| MMO.core.MAP_DISCONNECT
path	`string`	the current path of map from this
map	MMO.core.Map	the map being connected
_hash = new WeakSet()

watch(path, listener, event, scope)

Map.js:417

Watch a value at a given path The listener is called immediately after it has connected successfully.

watch(path, listener, event = null, scope = null)

path	`string`	the path at which to register the event (Array path NOT ALLOWED)
listener	`Function` \| MMO.core.EventBinding	function(type, map, key, oldValue)
event = null	`Symbol` \| `null`	if null use the key at the end of path
scope = null	`null` \| `Object`	the scope to call the listener with (ignore when listener is an EventBinding)
returns	MMO.core.EventBinding	the bind

unwatch(path, listener, event, scope)

Map.js:450

Unwatch a value at a given path

unwatch(path, listener = null, event = null, scope = false)

path	`string` \| `integer`	the path at which to register the event (Array path NOT ALLOWED)
listener = null	`Function` \| MMO.core.EventBinding \| `null`	if null will look for binding with the right scope
event = null	`Symbol` \| `null`	if null use the key at the end of path
scope = false	`false` \| `null` \| `Object`	if != false, look for binding with the right scope
returns	?MMO.core.EventBinding	the bind or null if nothing was found

connectWatch(path, event, bind)

Map.js:488

Try to connect watch at a given path.

connectWatch(path, event, bind)

If the watch is connected successfully, it is called directly with the correct arguments

path	`string` \| `integer` \| `Array`	a valid json path
event	`string` \| `Symbol`	the event to connect to
bind	MMO.core.EventBinding	the bind to connect

disconnectWatch(path, event, bind)

Map.js:531

Undo MMO.core.Map#connectWatch. A path that no longer resolves is not an error: the watch simply had nothing attached.

disconnectWatch(path, event, bind)

path	`string` \| `number` \| `Array`
event	`?(string` \| `Symbol)`
bind	MMO.core.EventBinding

disconnectScope(scope)

Map.js:545

Remove all watch/events set by a given scope

disconnectScope(scope)

scope

changeWatchPath(oldPath, newPath, _hash)

Map.js:575

Move watch from a path to another

changeWatchPath(oldPath, newPath, _hash = new WeakMap())

oldPath	`string` \| `integer`	the old path at which the listener was registered (Array path NOT ALLOWED)
newPath	`string` \| `integer`	the new path at which the listener was registered (Array path NOT ALLOWED)
_hash = new WeakMap()

onChildConnection(type, parent, path, map)

Map.js:609

[internal] React to a child being connected or disconnected anywhere below this map, by (re)connecting the watches whose path is now reachable, and dropping the others.

onChildConnection(type, parent, path, map)

type	`Symbol`	MMO.core.MAP_CONNECT \| MMO.core.MAP_DISCONNECT
parent	MMO.core.Map	the map the child was attached to
path	`string`	the child's path, relative to this map
map	MMO.core.Map	the child

extendedEntries()

generatorMap.js:633

Get a list of entries, index and events

*extendedEntries()

returns Generator<key, value, index, events>

setExtendedEntries(entries, preserveArray)

Map.js:648

Set values, keus, indexes and readjust watch path and events INTERNAL: used by sort or changeIndex

setExtendedEntries(entries, preserveArray = true)

entries
preserveArray = true
returns	MMO.core.Map

clear()

Map.js:700

Clear the map

clear()

get(key)

Map.js:718

Read a value.

get(key)

Override: a key declared as an alias in the schema reads through to its target path.

key	`*`
returns	`*`	undefined when the key is absent, when the alias is write-only, or when its path is missing

map.get('adresse'); // undefined -- not a ReferenceError -- when there is no `adresses/default`

set(key, value, _hash)

Map.js:737

Set the value at a given key

set(key, value, _hash = new WeakMap())

key	`*`
value	`*`
_hash = new WeakMap()
returns	`Boolean`	true if the Map has changed

delete(key)

Map.js:790

Delete a value at a given key

delete(key)

key	`*`
returns	`Boolean`	true if the Map has changed

changeKey(oldKey, newKey, moveValue)

Map.js:839

Change key of a value without changing its index.

changeKey(oldKey, newKey, moveValue = true)

If value at newKey is set, it is deleted first

oldKey	`string` \| `integer`	the current key
newKey	`string` \| `integer`	the new key to move to
moveValue = true	`boolean`	if true will also move the value
returns	`boolean`	true if the Map has changed

changeIndex(key, index, preserveArray)

Map.js:884

Change index of a key

changeIndex(key, index, preserveArray = true)

key	`string` \| `integer`	the key
index
preserveArray = true	`boolean`	if this map is an array and this is true, the keys are ignored in the sorting process
returns	`boolean`	true if the Map has changed

setValue(obj, _hash)

Map.js:908

Set the content of this map with the content of an object

setValue(obj, _hash = new WeakMap())

obj	`Object`
_hash = new WeakMap()
returns	`Boolean`	true if object has changed

merge(obj, _hash)

Map.js:1006

Merge values from another object

merge(obj, _hash = new WeakMap())

obj	`object`
_hash = new WeakMap()
returns	`this`

yieldWalk(path, create)

generatorMap.js:1038

Walk through the map using json path, creating the structure if needed.

*yieldWalk(path, create = false)

path	`string` \| `integer` \| `Array`	a valid json path (with no parent reference)
create = false	`boolean`	if true create the structure (as MMO.core.Map) along the way

walkTo(path, create)

Map.js:1081

Walk through the map using json path, creating the structure if needed.

walkTo(path, create = false)

path	`string` \| `integer` \| `Array`	a valid json path (with no parent reference)
create = false	`boolean`	if true create the structure (as MMO.core.Map) along the way
returns		the current key,value,map at the current path (map represents the current parent) if key is null it means the path is empty and value === map

keyAt(path)

Map.js:1092

Get the last key of a path.

keyAt(path)

path	`string` \| `number` \| `Array`
returns	`?(string` \| `number)`	null when the path is empty

mapAt(path, create)

Map.js:1103

Get the map HOLDING the value at a path (its parent), not the value itself.

mapAt(path, create = false)

path	`string` \| `number` \| `Array`
create = false	`boolean`	create the missing levels along the way
returns	MMO.core.Map

getAt(path, create)

Map.js:1115

Get the value at a path.

getAt(path, create = false)

path	`string` \| `number` \| `Array`
create = false	`boolean`	create the missing levels along the way
returns	`*`	undefined when the path holds nothing
throws	MMO.PathError	when the path crosses a value that is not a Map

safeGetAt(path, def)

Map.js:1126

Get the value at a path, never throwing.

safeGetAt(path, def)

path	`string` \| `number` \| `Array`
def	`*`	returned when the path is missing or broken
returns	`*`

exists(path)

Map.js:1141

Test whether a path holds a value.

exists(path)

path	`string` \| `number` \| `Array`
returns	`boolean`	false when the path is missing OR cannot be walked

setAt(path, value)

Map.js:1155

Set a value at a path, creating the missing levels along the way.

setAt(path, value)

path	`string` \| `number` \| `Array`	an empty path replaces this map's whole content
value	`*`
returns	`boolean`	true when something changed

mergeAt(path, value)

Map.js:1166

Merge a value into a path: recursive when both sides are maps, a plain set otherwise.

mergeAt(path, value)

path	`string` \| `number` \| `Array`
value	`*`
returns	`this`

deleteAt(path)

Map.js:1180

Delete element at given path

deleteAt(path)

path	`string` \| `integer` \| `array`
returns	`boolean`

isArray(allowEmpty)

Map.js:1199

Check if content is a json array (indexes are ordered integer starting from 0)

isArray(allowEmpty = false)

allowEmpty = false	`Boolean`	if true, also return true if the map is empty
returns	`Boolean`

push(value)

Map.js:1243

Append a value.

push(value)

value	`*`
returns	`boolean`	true when the map changed
throws	`MMO.TypeError`	when this map is not an array

unshift(value)

Map.js:1255

Insert a value in front, shifting every other item up one index.

unshift(value)

Children keep their parent link, updated to their new index.

value	`*`
returns	`boolean`
throws	`MMO.TypeError`	when this map is not an array

pop()

Map.js:1284

Remove and return the last value.

pop()

returns	`*`	undefined when the map is empty
throws	`MMO.TypeError`	when this map is not an array

shift()

Map.js:1299

Remove and return the first value, shifting every other item down one index.

shift()

returns	`*`	undefined when the map is empty
throws	`MMO.TypeError`	when this map is not an array

includes(value, similar)

Map.js:1314

Test whether a value is present.

includes(value, similar = false)

value	`*`
similar = false	`boolean`	compare with `MMO.core.isSimilar` instead of `===`
returns	`boolean`

usort(cmp, preserveArray)

Map.js:1330

Sort by key and value

usort(cmp, preserveArray = true)

cmp	`Function`	fn([keyA, valueA], [keyB, valueB]): {int}
preserveArray = true	`boolean`	if this map is an array and this is true, the keys are ignored in the sorting process
returns	`this`

ksort(cmp)

Map.js:1340

Sort by keys

ksort(cmp = MMO.core.compare)

cmp = MMO.core.compare	`Function`	fn(keyA, keyB): {int}
returns	`this`

sort(cmp, preserveArray)

Map.js:1350

Sort by values

sort(cmp = MMO.core.compare, preserveArray = true)

cmp = MMO.core.compare	`Function`	fn(valueA, valueB): {int}
preserveArray = true	`boolean`	if this map is an array and this is true, the keys are ignored in the sorting process
returns	`this`

setSchema(schema)

Map.js:1361

Set map schema

setSchema(schema)

schema Promise<MMO.schemas.Schema>

getKeySchema(key, resolveInstance)

Map.js:1407

Get the schema describing one key.

getKeySchema(key, resolveInstance = false)

key	`string` \| `number`
resolveInstance = false	`boolean`	resolve an `instanceOf` schema first; this makes the call ASYNCHRONOUS and it then returns a Promise instead of a Schema
returns	`?(MMO.schemas.Schema` \| `Promise<MMO.schemas.Schema>)`	null when there is no schema

validate()

Map.js:1421

Validate the map against its schema

validate()

returns Promise<MMO.schemas.Annotation> if no schema is set the returned annotation is null

validateKey(key)

Map.js:1431

Validate one key against its schema.

validateKey(key)

key	`string` \| `number`
returns	`Promise<?MMO.schemas.Annotation>`	null when the key has no schema