mirror of
https://github.com/github/codeql-action.git
synced 2025-12-26 17:20:10 +08:00
266 lines
5.0 KiB
Markdown
266 lines
5.0 KiB
Markdown
# Toad Cache
|
|
|
|
[](https://npmjs.org/package/toad-cache)
|
|
[](https://npmjs.org/package/toad-cache)
|
|
|
|
[](https://coveralls.io/r/kibertoad/toad-cache?branch=main)
|
|
|
|
Least-Recently-Used and First-In-First-Out caches for Client or Server.
|
|
|
|
## Getting started
|
|
|
|
```javascript
|
|
import { Lru, Fifo } from 'toad-cache'
|
|
const lruCache = new Lru(max, ttl = 0)
|
|
const fifoCache = new Fifo(max, ttl = 0)
|
|
```
|
|
|
|
## clear
|
|
|
|
### Method
|
|
|
|
Clears the contents of the cache
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
cache.clear()
|
|
```
|
|
|
|
## delete
|
|
|
|
### Method
|
|
|
|
Removes item from cache
|
|
|
|
param {String} key Item key
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
cache.delete('myKey')
|
|
```
|
|
|
|
## deleteMany
|
|
|
|
### Method
|
|
|
|
Removes items from cache
|
|
|
|
param {String[]} keys Item keys
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
cache.deleteMany(['myKey', 'myKey2'])
|
|
```
|
|
|
|
## evict
|
|
|
|
### Method
|
|
|
|
Evicts the least recently used item from cache
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
cache.evict()
|
|
```
|
|
|
|
## expiresAt
|
|
|
|
### Method
|
|
|
|
Gets expiration time for cached item
|
|
|
|
param {String} key Item key
|
|
return {Mixed} Undefined or number (epoch time)
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
const item = cache.expiresAt('myKey')
|
|
```
|
|
|
|
## first
|
|
|
|
### Property
|
|
|
|
Item in "first" or "bottom" position
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
const cache = new Lru()
|
|
|
|
cache.first // null - it's a new cache!
|
|
```
|
|
|
|
## get
|
|
|
|
### Method
|
|
|
|
Gets cached item and marks it as recently used (pushes to the back of the list of the candidates for the eviction)
|
|
|
|
param {String} key Item key
|
|
return {Mixed} Undefined or Item value
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
const item = cache.get('myKey')
|
|
```
|
|
|
|
## getMany
|
|
|
|
### Method
|
|
|
|
Gets multiple cached items and marks them as recently used (pushes to the back of the list of the candidates for the eviction)
|
|
|
|
param {String[]} keys Item keys
|
|
return {Mixed[]} Undefined or Item values
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
const item = cache.getMany(['myKey', 'myKey2'])
|
|
```
|
|
|
|
## keys
|
|
|
|
### Method
|
|
|
|
Returns an `Array` of cache item keys.
|
|
|
|
return {Array} Array of keys
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
console.log(cache.keys())
|
|
```
|
|
|
|
## max
|
|
|
|
### Property
|
|
|
|
Max items to hold in cache (1000)
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
const cache = new Lru(500)
|
|
|
|
cache.max // 500
|
|
```
|
|
|
|
## last
|
|
|
|
### Property
|
|
|
|
Item in "last" or "top" position
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
const cache = new Lru()
|
|
|
|
cache.last // null - it's a new cache!
|
|
```
|
|
|
|
## set
|
|
|
|
### Method
|
|
|
|
Sets item in cache as `first`
|
|
|
|
param {String} key Item key
|
|
param {Mixed} value Item value
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
cache.set('myKey', { prop: true })
|
|
```
|
|
|
|
## size
|
|
|
|
### Property
|
|
|
|
Number of items in cache
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
const cache = new Lru()
|
|
|
|
cache.size // 0 - it's a new cache!
|
|
```
|
|
|
|
## ttl
|
|
|
|
### Property
|
|
|
|
Milliseconds an item will remain in cache; lazy expiration upon next `get()` of an item
|
|
|
|
**Example**
|
|
|
|
```javascript
|
|
const cache = new Lru()
|
|
|
|
cache.ttl = 3e4
|
|
```
|
|
|
|
## Hit/miss/expiration tracking
|
|
|
|
In 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:
|
|
|
|
```js
|
|
const sharedRecord = new HitStatisticsRecord() // if you want to use single record object for all of caches, create it manually and pass to each cache
|
|
|
|
const cache = new LruHitStatistics({
|
|
cacheId: 'some-cache-id',
|
|
globalStatisticsRecord: sharedRecord,
|
|
statisticTtlInHours: 24, // how often to reset statistics. On every rotation previously accumulated data is removed
|
|
max: 1000,
|
|
ttlInMsecs: 0,
|
|
})
|
|
```
|
|
|
|
You can retrieve accumulated statistics from the cache, or from the record directly:
|
|
|
|
```js
|
|
// this is the same
|
|
const statistics = sharedRecord.getStatistics()
|
|
const alsoStatistics = cache.getStatistics()
|
|
|
|
/*
|
|
{
|
|
'some-cache-id': {
|
|
'2023-04-06': {
|
|
cacheSize: 100, // how many elements does cache currently have
|
|
evictions: 5, // how many elements were evicted due to cache being at max capacity
|
|
expirations: 0, // how many elements were removed during get due to their ttl being exceeded
|
|
hits: 0, // how many times element was successfully retrieved from cache during get
|
|
emptyHits: 0, // out of all hits, how many were null, undefined or ''?
|
|
falsyHits: 0, // out of all hits, how many were falsy?
|
|
misses: 1, // how many times element was not in cache or expired during get
|
|
invalidateOne: 1, // how many times element was invalidated individually
|
|
invalidateAll: 2, // how many times entire cache was invalidated
|
|
sets: 0, // how many times new element was added
|
|
},
|
|
},
|
|
}
|
|
|
|
Note 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 start
|
|
*/
|
|
```
|
|
|
|
## License
|
|
|
|
Copyright (c) 2023 Igor Savin
|
|
|
|
Based on [tiny-lru](https://github.com/avoidwork/tiny-lru), created by Jason Mulligan
|
|
|
|
Licensed under the MIT license.
|