@openally/timestore NPM

!NOTE Internally it uses a Node.js timer. This library does not guarantee that the timers doesn't drift.

Requirements

Node.js v16 or higher

Getting Started

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

$ npm i @openally/timestore
# or
$ yarn add @openally/timestore

Usage example

import { TimeStore } from "@openally/timestore";

const store = new TimeStore({ ttl: 10_000 })
  .add("foo")
  .add("bar", { ttl: 500 })
  .add("bar", { ttl: 200, keepIdentifierBirthTTL: true }); // will be ignored!

console.log(store.ttl); // 10000

store.on(
  TimeStore.Expired,
  (id) => console.log(`identifier '${id}' has expired!`)
);

!IMPORTANT By default the internal timer we use in unreferenced to allow the event loop to properly stop. You can modify this behaviour by enabling the keepEventLoopAlive options.

API

Identifier are often described with the following type:

export type TimeStoreIdentifier = string | symbol | number | boolean | bigint | object | null;

constructor(options?: ITimeStoreConstructorOptions)

The constructor options payload is described by the following TS interface:

interface ITimeStoreConstructorOptions {
  /**
   * Time To Live (Lifetime of stored identifiers).
   */
  ttl?: number;
  /**
   * Automatically expire identifiers when Node.js process "exit" event is triggered.
   *
   * @see https://nodejs.org/api/process.html#event-exit
   * @default false
   */
  expireIdentifiersOnProcessExit?: boolean;
  /**
   * Provide an additional EventEmitter to use for broadcasting events
   */
  eventEmitter?: EventEmitter;

  /**
   * If enabled the internal timer will not be unreferenced
   *  
   * @see https://nodejs.org/dist/latest-v18.x/docs/api/timers.html#timeoutunref
   * @default false
   */
  keepEventLoopAlive?: boolean;
}

If the ttl option is not provided all identifiers will remain active. The default class ttl will be equal zero.

add(identifier: TimeStoreIdentifier, options?: ITimeStoreAddOptions): this

The options payload is described by the following TS interface:

interface ITimeStoreAddOptions {
  /**
   * Time To Live for the given identifier.
   * If no value provided it will take the class TTL value.
   */
  ttl?: number;

  /**
   * If identifier exist then keep is original timestamp and ttl.
   *
   * @default false
   */
  keepIdentifierBirthTTL?: boolean;
}

!NOTE Adding an existing ID will reset its previous TTL/timestamp except if the keepIdentifierBirthTTL option is set to true.

addTsv(data: tSvResponse): this

Add a value using a TimeStoreValue:

import { TimeStore, tSv } from "@openally/timestore";

const tSvFactory = tSv({ ttl: 500 });

const store = new TimeStore({ ttl: 10_000 })
  .addTsv(tSvFactory("key"))
  .addTsv(tSvFactory(["key", "value"])); // value will be ignored here

TimeStoreValue are useful to build higher abstraction using TimeStore. Those values all embed a Global symbol Symbol.for("TimeStoreValue").

The module also export it as TSV_SYMBOL.