Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/steveswork/timed-map

A map with aged entries. Outdated entries are routinely removed from the map.
https://github.com/steveswork/timed-map

Last synced: 11 days ago
JSON representation

A map with aged entries. Outdated entries are routinely removed from the map.

Awesome Lists containing this project

README 

        
# Timed-Map



**Name:** Timed-Map



**Install:**\

npm i -S @webkrafters/timed-map



## Description



An observable timed map javascript data structure.

Tracks and removes outdated infrequently `read` entries.



## Ideal Use-case



Ideal for in-app Application Level Memoization and Caching.



## Usage



```js

import TimedMap from '@webkrafters/timed-map';



const timedMap = new TimedMap( 1000 ); // max-age of 1-second per infrequently-used map entries



const timedMap = new TimedMap(); // defaults to 30 mins max-age



```



### MapEntry



A map entry object holds the following information:

```js

{

	createdAt: int // Date in millis since epoch

	key: string

	value: any

	ttl: int // Duration in millis

}

```



## Requirement



The TimedMap `close()` instance method must be called prior to `delete`ing or setting this map to null.

This cleans up the underlying driver along with any system resources used such as cpu timers etc.



## Public Interface



### constructor(maxEntryAgeMillis?: int): TimedMap



Creates an instance of TimedMap. The optional `maxEntryAgeMillis` value is a class-level TTL in milliseconds applied to all entries in the map. A default of 1800000ms (i.e. 30 minutes) is assigned if omitted. Any entry which remained `un-read` at the end of the TTL-cycle is removed. `get(key)` and `getEntry(key)` methods constitute the only valid entry `read` operations. To obtain entry value without restarting the entry TTL-cycle, see the `peak(key)` method. Individual TTLs may be assigned to entries upon insertion. See the `put(...)` method. The individual TTL supersedes the class-level TTL for the individual entry.



### entries: MapEntry[] - readonly



Computed property: available entries.



### isEmpty: boolean - readonly



Computed property: check-flag confirming a map containing no entries.



### keys: string[] - readonlys



Computed property: keys to all available entries.



### maxEntryAge: int



Property: TTL value in milliseconds applied to map entries. Setting this property triggers adjustments in the map's internal TTL cycle processes.



### size: int - readonly



Computed property: number of entries in the map



### clear(): void



Removes all entries from the map



### close(): void



Recommended pre-delete method: please use this method to release system resources and clean up the internal driver prior to `delete`ing this TimeMap instance or setting it to null.



### get(key: string): any



Returns the value at key and restarts the entry's TTL cycle. This constitutes a valid `read` operation.



### getEntry(key: string): MapEntry



Returns the entry object residing at key. This constitutes a valid `read` operation.



### has(key: string): boolean



Verifies the presence of a valid map entry at this key



### off(type: EventType, listener: Eventlistener): void



Cancels event by listener function reference. Please see Events section below for more on event types and event listener.



### offById(eventId: string): void



Cancels event by event ID. Please see Events section below for more on event ID.



### on(type: EventType, listener: Eventlistener, attributes?: Object): string



Subscribes to event of event type and returns unique eventId. Supply any additional info to capture as part of this event to the optional `attributes` object argument. Please see Events section below for more on event types, event ID and event listener.



### once(type: EventType, listener: Eventlistener, attributes?: Object): string



Subscribes to one-use event of event type and returns unique eventId. Supply any additional info to capture as part of this event to the optional `attributes` object argument. Please see Events section below for more on event types, event ID and event listener.



### peak(key: string): any



Returns the value at key without restarting the entry's TTL cycle. 



### put(key: string, value: any, ttl?: int ): MapEntry



Creates a new map entry. If an entry existed at the key, it is overriden and returned. When the optional `ttl` value is supplied, it takes precedence over the class-level TTL value for calculating TTL cycles for this entry. Please see the `get` and `getEntry` methods.



### remove( key: string): MapEntry



If an entry existed at the key, it is removed and returned.



## Events



This map is observable and provides pathways for notifying observers of relevant changes within. For this purpose, six event types have been provided.



### Event Map Table

-----------------------------------------------------------------------------------------------------

|Event Type   |Trigger												  |Event Data

|-------------|-------------------------------------------------------|-------------------------------

|AUTO_RENEWED | After an entry read (See valid read operations above) |key: string
createdAt: int
previouslyCreatedAt: int

|CLEARED      | After a map `clear` operation						  |removed: MapEntry[]

|CLOSING      | The `close` method call prior to clean up operation.  |undefined

|PRUNED       | After pruning outdated entries						  |removed: MapEntry[]

|PUT          | After a `put` method call operation					  |current: MapEntry
previous: MapEntry

|REMOVED      | After a `remove` method call operation				  |removed: MapEntry

--------------------------------------------------------------------------------------------------------



Timing: Excluding the `CLOSING` event, all event listeners are scheduled to run at the conclusion of previously scheduled tasks. `CLOSING` event listeners are run immediately.



-------------------------------------------------------------------------------------------------



### Event Listener



The event listener is triggered with a lone argument: the event payload. The event payload object emitted contains the following information:



attributes: Object (Please see the `on` method discussion above)


data: Event Data Object (See Event Map Table above)
 

date: Date - event date


id: string - event ID


timestamp: int - event date in milliseconds


type: Event Type (See Event Map Table above)



Immutability: With the exception of `attributes` and `date`, immutability is maintained on all properties of the event payload. The `date` property is a native Date instance object. The `attributes` property is presented to the user exactly as defined by the user.



### Event ID



Every subscribed event listener is assigned a unique event ID during subscription. The `on` and `once` methods constitute the two avenues for event subscription. These methods return the unique event ID correspondingly. While the listener function reference remains the most popular means for identifying events for cancellation, the event ID is the surest means of accomplishing same purpose. Please see the `off` and `offById` methods.



## License



	ISC