TimeMap

MIT dep size

ECMAScript 6 Map-Like implementation with keys that have a defined timelife.

Requirements

Node.js v12 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @slimio/timemap
# or
$ yarn add @slimio/timemap

Usage example

const { strictEqual } = require("assert");
const TimeMap = require("@slimio/timemap");

const col = new TimeMap(1000);
col.on("expiration", (key, value) => {
    console.log(`col key ${key} has expired!`);
});

col.set("foo", "bar");
col.set("test", true);
strictEqual(col.has("foo"), true);

setTimeout(() => {
    col.set("hello", "world!");
    strictEqual(col.has("foo", true), true);
}, 500);

setTimeout(() => {
    strictEqual(col.has("foo"), true);
}, 500)

setTimeout(() => {
    strictEqual(col.has("foo"), false);
    strictEqual(col.has("test"), false);
    strictEqual(col.has("hello"), true);
}, 1100);

Events

TimeMap class is extended by a Node.js EventEmitter. The class can trigger several events:

event name	description
expiration	Expired key are emitted before deletion

const map = new TimeMap(100);
map.on("expiration", (key, value) => {
    console.log(`key: ${key}, value: ${value}`);
});

map.set("foo", "bar");

API

Following methods are members of TimeMap class. The type TimeMap.key is declared as follow:

type key = symbol | string | number;

constructor(timeLifeMs: number)

Create a new TimeMap Object. Take an argument which is the time that a key stay alive within the class. ```js const map = new TimeMap(5000); map.set("foo", "bar"); // foo will live for the next 5,000 milliseconds ``` The default **timeLifeMs** is equal to the value of static member `TimeMap.DEFAULT_TIMELIFE_MS` (equal to *1000* by default). ```js const { strictEqual } = require("assert"); const map = new TimeMap(); strictEqual(map.timeLife, TimeMap.DEFAULT_TIMELIFE_MS); ```

set(key: TimeMap.key, value: any): void

Set a new key in the Collection. Inner timer will be initialized by the first key. The key must be a string or a symbol (no other primitive are accepted). ```js const { strictEqual } = require("assert"); const map = new TimeMap(); const sym = Symbol("foo"); map.set(sym, "bar"); strictEqual(map.get(sym), "foo"); ```

has(key: TimeMap.key, refreshTimestamp?: boolean): boolean

Similar to `Map.has` method. Return **true** if the key exist within. ```js const { strictEqual } = require("assert"); const map = new TimeMap(100); map.set("foo", "bar"); setTimeout(() => { strictEqual(map.has("foo", true), true); }, 50); setTimeout(() => { strictEqual(map.has("foo"), true); }, 50); setTimeout(() => { strictEqual(map.has("foo"), false); }, 50); ```

delete(key: TimeMap.key): void

Delete a given key from TimeMap. The key must be a string or a symbol. ```js const { strictEqual } = require("assert"); const map = new TimeMap(100); map.once("expiration", (key) => { strictEqual(key, "hello"); }); map.set("foo", "bar"); map.set("hello", "world"); setTimeout(() => { map.delete("foo"); }, 50) ```

get< T >(key: TimeMap.key, refreshTimestamp?: boolean): T

Get a given key from the Class. Throw an Error if the key doesn't exist in the Collection (use .has() before). ```js const assert = require("assert"); const map = new TimeMap(100); map.set("foo", "bar"); assert.strictEqual(map.get("foo"), "bar"); assert.throws(() => { map.get("world!"); }, { name: "Error" }); ```

clear(): void

Clear internal timer and internal data. Everything will be reset.

keys(): IterableIterator< TimeMap.key >

The keys() method returns a new Iterator object that contains the keys for each element in the TimeMap object in insertion order. ```js const { deepEqual } = require("assert"); const map = new TimeMap(); map.set("foo", "bar"); map.set("yo", "boo"); deepEqual(["foo", "yo"], [...map.keys()]); ```

Properties

All following properties are readonly

.size

The size accessor property returns the number of elements in the TimeMap. ```js const { strictEqual } = require("assert"); const map = new TimeMap(); map.set("foo", "bar"); strictEqual(map.size, 1); ```

.timeLife

The timeLife accessor property return the configured time life for keys ```js const { strictEqual } = require("assert"); const map = new TimeMap(2000); strictEqual(map.timeLife, 2000); ```

Dependencies

This project have no dependencies.

License

MIT

SlimIO / TimeMap

readme