TreeReferenceMap<K extends Object, V extends Object> class

A Map that retains entries only while their keys are reachable from root.

Internally, this map is backed by a WeakKeyMap. Weak references are used to avoid keeping keys alive beyond their natural lifetime, while reachability from root defines whether an entry is considered valid.

Entries whose keys are no longer reachable from the object tree rooted at root can be explicitly or automatically purged to prevent memory growth.

Browser use case: when root is a DOM Node, values can be safely associated with any Node in the DOM tree, and entries are removed once the node is detached from root Node.

Implemented types

Map<K, V>

Constructors

TreeReferenceMap(K root, {bool autoPurge = false, int autoPurgeThreshold = defaultAutoPurgeThreshold, bool keepPurgedKeys = false, Duration? purgedEntriesTimeout, int? maxPurgedEntries, K? parentGetter(K key)?, Iterable<K> childrenGetter(K key)?, bool childChecker(K parent, K child, bool deep)?, void onPurgedEntries(Map<K, V> purgedEntries)?})

Properties

autoPurge → bool: Whether automatic purging of stale entries is enabled.
final
autoPurgeThreshold → int: Number of operations after which an automatic purge is triggered.
final
childChecker → bool Function(K parent, K child, bool deep)?: The Function that returns true if parent has child.
final
childrenGetter → Iterable<K> Function(K key)?: The Function that returns the children of a key.
final
entries → Iterable<MapEntry<K, V>>: The map entries of this Map.
no setteroverride
hashCode → int: The hash code for this object.
no setterinherited
invalidEntries → List<MapEntry<K, V>>: Returns the invalid entries.
no setter
invalidKeys → List<K>: Returns the invalid keys.
no setter
isEmpty → bool: Whether there is no key/value pair in the map.
no setteroverride
isNotEmpty → bool: Whether there is at least one key/value pair in the map.
no setteroverride
keepPurgedEntries → bool: Will stored purged entries in a separated Map.
final
keys → Iterable<K>: The keys of this Map.
no setteroverride
keysReversed → List<K>: Returns keys reversed (unmodifiable);
no setter
length → int: The number of key/value pairs in the map.
no setteroverride
maxPurgedEntries → int?: Maximum number of purged entries.
final
onPurgedEntries ↔ void Function(Map<K, V> purgedEntries)?: Optional callback invoked after entries are purged.
getter/setter pair
parentGetter → K? Function(K key)?: The Function that returns the parent of a key.
final
purgedEntries → List<MapEntry<K, V>>: Returns the purged entries. Only relevant if keepPurgedEntries is true.
no setter
purgedEntriesCount → int: no setter
purgedEntriesTimeout → Duration?: Purged entries timeout.
final
purgedKeys → List<K>: Returns the purged keys. Only relevant if keepPurgedEntries is true.
no setter
purgedKeysReversed → List<K>: Returns purgedKeys reversed (unmodifiable);
no setter
purgedLength → int: Returns the purged entries length. Only relevant if keepPurgedEntries is true.
no setter
revalidatedPurgedEntriesCount → int: no setter
root → K: The root of the Tree Reference.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
validEntries → List<MapEntry<K, V>>: Returns the valid entries.
no setter
validKeys → List<K>: Returns the valid keys.
no setter
values → Iterable<V>: The values of this Map.
no setteroverride

Methods

addAll(Map<K, V> other) → void: Adds all key/value pairs of other to this map.
override
addEntries(Iterable<MapEntry<K, V>> newEntries) → void: Adds all key/value pairs of newEntries to this map.
override
cast<RK, RV>() → Map<RK, RV>: Provides a view of this map as having RK keys and RV instances, if necessary.
override
checkPurgedEntriesTimeout() → void: Remove expired purged entries. Only relevant if purgedEntriesTimeout is not null.
checkPurgeEntriesLimit() → void: Removed purged entries over maxPurgedEntries limit.
clear() → void: Removes all entries from the map.
override
containsKey(Object? key) → bool: Whether this map contains the given key.
override
containsValue(Object? value) → bool: Whether this map contains the given value.
override
disposePurgedEntries() → void: Disposes purged entries. Only relevant if keepPurgedEntries is true.
doAutoPurge() → bool: Same as purge, but called automatically by many operations. See autoPurge and autoPurgeThreshold.
forEach(void f(K key, V value)) → void: Applies action to each key/value pair of the map.
override
get(K key) → V?
getAlsoFromPurgedEntries(K key) → V?
getChildrenOf(K? key) → Iterable<K>: Returns the children of key.
getFromPurgedEntries(K? key) → V?: Returns key value from purged entries. Only relevant if keepPurgedEntries is true.
getParentKey(K? child, {bool includePurgedEntries = false}) → K?: Get 1st parent key of child;
getParentOf(K? key) → K?: Returns the parent of key.
getParentValue(K? child, {bool includePurgedEntries = false}) → V?: Get 1st parent value of child;
getSubValues(K? key, {bool includePurgedEntries = false, bool traverseSubValues = false}) → List<V>: Gets values from children of key in a tree, using depth-first, left-to-right traversal.
isChildOf(K? parent, K? child, bool deep) → bool: Returns true if parent has child. If deep is true, will check sub nodes children.
isInTree(K? key) → bool: Returns true if key is in the tree.
isValidEntry(K key, V value) → bool: Returns true if key is valid (in the tree).
map<K2, V2>(MapEntry<K2, V2> f(K key, V value)) → Map<K2, V2>: Returns a new map where all entries of this map are transformed by the given convert function.
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
purge() → TreeReferenceMap<K, V>: Remove all invalidKeys. Calls onPurgedEntries if defined.
put(K key, V value) → void
putIfAbsent(K key, V ifAbsent()) → V: Look up the value of key, or add a new entry if it isn't there.
override
remove(Object? key) → V?: Removes key and its associated value, if present, from the map.
override
removeWhere(bool predicate(K key, V value)) → void: Removes all entries of this map that satisfy the given test.
override
revalidatePurgedEntries() → int: Restore purged entries that are currently valid. Only relevant if keepPurgedEntries is true.
toString() → String: A string representation of this object.
override
update(K key, V update(V value), {V ifAbsent()?}) → V: Updates the value for the provided key.
override
updateAll(V update(K key, V value)) → void: Updates all values.
override
walkTree<R>(R walker(K node), {K? root}) → R?: Walks tree from root and stops when walker returns some R object.

Operators

operator ==(Object other) → bool: The equality operator.
inherited
operator [](Object? key) → V?: The value for the given key, or null if key is not in the map.
override
operator []=(K key, V value) → void: Associates the key with the given value.
override

Constants

defaultAutoPurgeThreshold → const int: Default threshold used when none is explicitly provided.