strong-tie/inbound-calls

1# Toad Cache2 3[![NPM Version](https://img.shields.io/npm/v/toad-cache.svg)](https://npmjs.org/package/toad-cache)4[![NPM Downloads](https://img.shields.io/npm/dm/toad-cache.svg)](https://npmjs.org/package/toad-cache)5![](https://github.com/kibertoad/toad-cache/workflows/ci/badge.svg)6[![Coverage Status](https://coveralls.io/repos/kibertoad/toad-cache/badge.svg?branch=main)](https://coveralls.io/r/kibertoad/toad-cache?branch=main)7 8Least-Recently-Used and First-In-First-Out caches for Client or Server.9 10## Getting started11 12```javascript13import { Lru, Fifo } from 'toad-cache'14const lruCache = new Lru(max, ttl = 0)15const fifoCache = new Fifo(max, ttl = 0)16```17 18## clear19 20### Method21 22Clears the contents of the cache23 24**Example**25 26```javascript27cache.clear()28```29 30## delete31 32### Method33 34Removes item from cache35 36    param  {String} key Item key37 38**Example**39 40```javascript41cache.delete('myKey')42```43 44## deleteMany45 46### Method47 48Removes items from cache49 50    param  {String[]} keys Item keys51 52**Example**53 54```javascript55cache.deleteMany(['myKey', 'myKey2'])56```57 58## evict59 60### Method61 62Evicts the least recently used item from cache63 64**Example**65 66```javascript67cache.evict()68```69 70## expiresAt71 72### Method73 74Gets expiration time for cached item75 76    param  {String} key Item key77    return {Mixed}      Undefined or number (epoch time)78 79**Example**80 81```javascript82const item = cache.expiresAt('myKey')83```84 85## first86 87### Property88 89Item in "first" or "bottom" position90 91**Example**92 93```javascript94const cache = new Lru()95 96cache.first // null - it's a new cache!97```98 99## get100 101### Method102 103Gets cached item and marks it as recently used (pushes to the back of the list of the candidates for the eviction)104 105    param  {String} key Item key106    return {Mixed}      Undefined or Item value107 108**Example**109 110```javascript111const item = cache.get('myKey')112```113 114## getMany115 116### Method117 118Gets multiple cached items and marks them as recently used (pushes to the back of the list of the candidates for the eviction)119 120    param  {String[]} keys Item keys121    return {Mixed[]}      Undefined or Item values122 123**Example**124 125```javascript126const item = cache.getMany(['myKey', 'myKey2'])127```128 129## keys130 131### Method132 133Returns an `Array` of cache item keys.134 135    return {Array} Array of keys136 137**Example**138 139```javascript140console.log(cache.keys())141```142 143## max144 145### Property146 147Max items to hold in cache (1000)148 149**Example**150 151```javascript152const cache = new Lru(500)153 154cache.max // 500155```156 157## last158 159### Property160 161Item in "last" or "top" position162 163**Example**164 165```javascript166const cache = new Lru()167 168cache.last // null - it's a new cache!169```170 171## set172 173### Method174 175Sets item in cache as `first`176 177    param  {String} key   Item key178    param  {Mixed}  value Item value179 180**Example**181 182```javascript183cache.set('myKey', { prop: true })184```185 186## size187 188### Property189 190Number of items in cache191 192**Example**193 194```javascript195const cache = new Lru()196 197cache.size // 0 - it's a new cache!198```199 200## ttl201 202### Property203 204Milliseconds an item will remain in cache; lazy expiration upon next `get()` of an item205 206**Example**207 208```javascript209const cache = new Lru()210 211cache.ttl = 3e4212```213 214## Hit/miss/expiration tracking215 216In case you want to gather information on cache hit/miss/expiration ratio, as well as cache size and eviction statistics, you can use LruHitStatistics class:217 218```js219const sharedRecord = new HitStatisticsRecord() // if you want to use single record object for all of caches, create it manually and pass to each cache220 221const cache = new LruHitStatistics({222  cacheId: 'some-cache-id',223  globalStatisticsRecord: sharedRecord,224  statisticTtlInHours: 24, // how often to reset statistics. On every rotation previously accumulated data is removed225  max: 1000,226  ttlInMsecs: 0,227})228```229 230You can retrieve accumulated statistics from the cache, or from the record directly:231 232```js233// this is the same234const statistics = sharedRecord.getStatistics()235const alsoStatistics = cache.getStatistics()236 237/*238{239  'some-cache-id': {240    '2023-04-06': {241      cacheSize: 100, // how many elements does cache currently have242      evictions: 5, // how many elements were evicted due to cache being at max capacity    243      expirations: 0, // how many elements were removed during get due to their ttl being exceeded244      hits: 0, // how many times element was successfully retrieved from cache during get245      emptyHits: 0, // out of all hits, how many were null, undefined or ''?246      falsyHits: 0, // out of all hits, how many were falsy?      247      misses: 1, // how many times element was not in cache or expired during get248      invalidateOne: 1, // how many times element was invalidated individually249      invalidateAll: 2, // how many times entire cache was invalidated250      sets: 0, // how many times new element was added      251    },252  },253}254 255Note that date here reflects start of the rotation. If statistics weren't rotated yet, and another day started, it will still be counted against the day of the rotation start256*/257```258 259## License260 261Copyright (c) 2023 Igor Savin262 263Based on [tiny-lru](https://github.com/avoidwork/tiny-lru), created by Jason Mulligan264 265Licensed under the MIT license.266