spatial-monorepo

---

spatial-monorepo / core/src / FeatureStateLRU

Class: FeatureStateLRU

Defined in: packages/core/src/rtls/FeatureStateLRU.ts:23

Issue #42 / #110 / #464 — FeatureStateLRU (canonical, standalone)

Tracks which feature-state keys have been set (keyed by assetId or any string) together with the last-update timestamp. Used to evict stale entries from MapLibre feature state, preventing the zoom-lag bug (#6633) when thousands of keys accumulate.

Consolidated (#464) from two divergent implementations: this rtls/ variant (onEvict-callback based, with TTL eviction) and a since-removed utils/ variant that called map.setFeatureState/removeFeatureState directly. This one was picked as canonical because it carries the TTL eviction used for the #6633 mitigation and keeps the class decoupled from MapLibre.

Design decisions:

• Deliberately decoupled from MapLibre — eviction is signalled via the onEvict callback so callers decide how to call removeFeatureState.
• JS Map preserves insertion order → oldest = map.keys().next().value.
• Cap at maxKeys (default 10 000); when exceeded the oldest entry is evicted.
• evictStale() removes entries older than ttlMs (default 30 s).

Constructors

Constructor

new FeatureStateLRU(onEvict, maxKeys?): FeatureStateLRU

Defined in: packages/core/src/rtls/FeatureStateLRU.ts:29

Parameters

onEvict

(key) => void

maxKeys?

number = 10_000

Returns

FeatureStateLRU

Methods

clear()

clear(): void

Defined in: packages/core/src/rtls/FeatureStateLRU.ts:81

Returns

void

---

delete()

delete(key): void

Defined in: packages/core/src/rtls/FeatureStateLRU.ts:69

Remove a single key without calling onEvict.

Parameters

key

string

Returns

void

---

evictStale()

evictStale(nowMs?, ttlMs?): void

Defined in: packages/core/src/rtls/FeatureStateLRU.ts:58

Remove all entries older than ttlMs milliseconds. Calls onEvict for each removed entry.

Parameters

nowMs?

number = ...

ttlMs?

number = 30_000

Returns

void

---

has()

has(key): boolean

Defined in: packages/core/src/rtls/FeatureStateLRU.ts:73

Parameters

key

string

Returns

boolean

---

set()

set(key, nowMs?): void

Defined in: packages/core/src/rtls/FeatureStateLRU.ts:38

Record or refresh a key with the current timestamp. If the cache is over capacity after insertion the oldest entry is evicted.

Parameters

key

string

nowMs?

number = ...

Returns

void

---

size()

size(): number

Defined in: packages/core/src/rtls/FeatureStateLRU.ts:77

Returns

number