Class ExpiringMap<K, V>

A map that can have a capacity limit. The elapsed time for each get/set operation is maintained allowing for items to be automatically removed. has() does not affect the last access time.

By default, it uses the none eviction policy, meaning that when full an error will be thrown if attempting to add new keys.

Eviction policies: oldestGet removes the item that hasn't been accessed the longest, oldestSet removes the item that hasn't been updated the longest.

const map = new ExpiringMap();
map.set(`fruit`, `apple`);

// Remove all entries that were set more than 100ms ago
map.deleteWithElapsed(100, `set`);
// Remove all entries that were last accessed more than 100ms ago
map.deleteWithElapsed(100, `get`);
// Returns the elapsed time since `fruit` was last accessed
map.elapsedGet(`fruit`);
// Returns the elapsed time since `fruit` was last set
map.elapsedSet(`fruit`);

Last set/get time for a key can be manually reset using touch.

Events:

'expired': when an item is automatically removed.
'removed': when an item is manually or automatically removed.
'newKey': when a new key is added

map.addEventListener(`expired`, evt => {
 const { key, value } = evt;
});

The map can automatically remove items based on elapsed intervals.

Example

Automatically delete items that haven't been accessed for one second

const map = new ExpiringMap({
 autoDeleteElapsed: 1000,
 autoDeletePolicy: `get`
});

Example

Automatically delete the oldest item if we reach a capacity limit

const map = new ExpiringMap({
 capacity: 5,
 evictPolicy: `oldestSet`
});

Type Parameters

K
Type of keys
V
Type of values

Hierarchy (View Summary)

SimpleEventEmitter<ExpiringMapEvents<K, V>>
- ExpiringMap

Index

Constructors

constructor

new ExpiringMap<K, V>(opts?: ExpiringMapOpts): ExpiringMap<K, V>
Type Parameters
- K
- V
Parameters
- opts: ExpiringMapOpts = {}
Returns ExpiringMap<K, V>
Overrides SimpleEventEmitter.constructor

Accessors

isDisposed

get isDisposed(): boolean
Returns boolean
Inherited from SimpleEventEmitter.isDisposed

keyLength

get keyLength(): number
Returns the number of keys being stored.

Returns number

Methods

addEventListener

addEventListener<K extends keyof ExpiringMapEvents<K, V>>(
    name: K,
    listener: (
        event: ExpiringMapEvents<K, V>[K],
        sender: SimpleEventEmitter<ExpiringMapEvents<K, V>>,
    ) => void,
): void
Adds event listener.
Type Parameters
- Kextendskeyof ExpiringMapEvents<K, V>
  Events
Parameters
- name: K
  Event name
- listener: (
  event: ExpiringMapEvents<K, V>[K],
  sender: SimpleEventEmitter<ExpiringMapEvents<K, V>>,
  ) => void
  Event handler
Returns void
Throws
Error if emitter is disposed

Inherited from SimpleEventEmitter.addEventListener

clear

clear(): void
Clears the contents of the map. Note: does not fire removed event

Returns void

delete

delete(key: K): boolean
Deletes the value under key, if present.

Returns true if something was removed.
Parameters
- key: K
Returns boolean

deleteWithElapsed

deleteWithElapsed(
interval: Interval,
property: "get" | "set" | "either",
): [k: K, v: V][]
Deletes all values where elapsed time has past for get/set or either.
```
// Delete all keys (and associated values) not accessed for a minute
em.deleteWithElapsed({mins:1}, `get`);
// Delete things that were set 1s ago
em.deleteWithElapsed(1000, `set`);
```
Parameters
- interval: Interval
  Interval
- property: "get" | "set" | "either"
  Basis for deletion 'get','set' or 'either'
Returns [k: K, v: V][]
Items removed

dispose

dispose(): void
Returns void
Overrides SimpleEventEmitter.dispose

elapsedGet

elapsedGet(key: K): undefined | number
Returns the elapsed time since key was accessed. Returns undefined if key does not exist
Parameters
- key: K
Returns undefined | number

elapsedSet

elapsedSet(key: K): undefined | number
Returns the elapsed time since key was set. Returns undefined if key does not exist
Parameters
- key: K
Returns undefined | number

entries

entries(): IterableIterator<[k: K, v: V]>
Returns IterableIterator<[k: K, v: V]>

`Protected`fireEvent

fireEvent<K extends keyof ExpiringMapEvents<K, V>>(
type: K,
args: ExpiringMapEvents<K, V>[K],
): void
Fire event
Type Parameters
- Kextendskeyof ExpiringMapEvents<K, V>
Parameters
- type: K
  Type of event
- args: ExpiringMapEvents<K, V>[K]
  Arguments for event
Returns void
Inherited from SimpleEventEmitter.fireEvent

get

get(key: K): undefined | V
Gets an item from the map by key, returning undefined if not present
Parameters
- key: K
  Key
Returns undefined | V
Value, or undefined

has

has(key: K): boolean
Returns true if key is stored. Does not affect the key's last access time.
Parameters
- key: K
Returns boolean

keys

keys(): IterableIterator<K>
Returns IterableIterator<K>

removeEventListener

removeEventListener<K extends keyof ExpiringMapEvents<K, V>>(
    type: K,
    listener: (
        event: ExpiringMapEvents<K, V>[K],
        sender: SimpleEventEmitter<ExpiringMapEvents<K, V>>,
    ) => void,
): void
Remove event listener
Type Parameters
- Kextendskeyof ExpiringMapEvents<K, V>
Parameters
- type: K
- listener: (
  event: ExpiringMapEvents<K, V>[K],
  sender: SimpleEventEmitter<ExpiringMapEvents<K, V>>,
  ) => void
Returns void
Inherited from SimpleEventEmitter.removeEventListener

set

set(key: K, value: V): void
Sets the key to be value.

If the key already exists, it is updated.

If the map is full, according to its capacity, another value is selected for removal.
Parameters
- key: K
- value: V
Returns void

touch

touch(key: K): boolean
Updates the lastSet/lastGet time for a value under k.

Returns false if key was not found
Parameters
- key: K
Returns boolean

values

values(): IterableIterator<V>
Returns IterableIterator<V>

Class ExpiringMap<K, V>

Example

Example

Type Parameters

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns ExpiringMap<K, V>

Accessors

isDisposed

Returns boolean

keyLength

Returns number

Methods

addEventListener

Type Parameters

Parameters

Returns void

Throws

clear

Returns void

delete

Parameters

Returns boolean

deleteWithElapsed

Parameters

Returns [k: K, v: V][]

dispose

Returns void

elapsedGet

Parameters

Returns undefined | number

elapsedSet

Parameters

Returns undefined | number

entries

Returns IterableIterator<[k: K, v: V]>

ProtectedfireEvent

Type Parameters

Parameters

Returns void

get

Parameters

Returns undefined | V

has

Parameters

Returns boolean

keys

Returns IterableIterator<K>

removeEventListener

Type Parameters

Parameters

Returns void

set

Parameters

Returns void

touch

Parameters

Returns boolean

values

Returns IterableIterator<V>

Settings

On This Page

`Protected`fireEvent