https://github.com/tcm9439/ts-key-value-cache
Typescript Key Value Cache (in-mem / external)
https://github.com/tcm9439/ts-key-value-cache
Last synced: 23 days ago
JSON representation
Typescript Key Value Cache (in-mem / external)
- Host: GitHub
- URL: https://github.com/tcm9439/ts-key-value-cache
- Owner: tcm9439
- License: mit
- Created: 2023-01-12T14:41:42.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-21T11:13:07.000Z (7 months ago)
- Last Synced: 2025-05-14T14:34:33.686Z (about 2 months ago)
- Language: TypeScript
- Homepage:
- Size: 246 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Typescript Local Key Value Cache
A key-value cache with string as key and value of any type. It support
- time-to-live management
- size control which remove exceed key-value pair in a FIFO manner
- housekeep function to clear the expired item in cache with O(k log N) times, where k is the number of expired items.
- in-memory or external storage (e.g. localStorage, Redis) for storing the key-value pair
## Installation
```
npm i ts-key-value-cache
```
## Examples
TypeScript
```ts
import { CacheOption, IKeyValueCache, Duration, IMapStorage } from "ts-key-value-cache";
// ===============
// init a cache
// ===============
const cacheOption = new CacheOption()
cacheOption.setMaxSize(100) // this cache keep 100 key-value pair at most
cacheOption.setDefaultTTL(new Duration({ minutes: 10 })) // default TTL is 10 minutes
// One cache can only accept one type of value
// For IKeyValueCache, V is the type of the value it accept
let cache: IKeyValueCache = cacheOption.create()
// E.g. the value must be string for this cache
// ===============
// basic usage
// ===============
// insert a pair with 30 minute TTL
cache.put("key1", "first", { ttl: new Duration({ minutes: 30 }) })
// update the value of key1, and renew the ttl to the default on (i.e. 10 minutes)
cache.put("key1", "testing")
// insert a pair with no TTL (i.e. never expired)
// it only get removed when the cache is full and need to push out some items, and it is the first one to expired (being oldest item among all items that will not expire when all items in the cache are without TTL)
cache.put("key2", "123", { noTtl: true })
let value1: string | null = cache.get("not-a-key")
// value1 is null
let value2: string | null = cache.get("key1")
// value2 is "testing"
// ====================
// use external storage
// ====================
class SomeMapStorageImplementation implements IMapStorage {...}
const cacheOption = new CacheOption()
cacheOption.setStorage(new SomeMapStorageImplementation())
let cache: IKeyValueCache = cacheOption.create()
```
## Operations on IKeyValueCache
`get(key: string): V | null`
Return value if found in cache and it is not yet expired.
Otherwise, return undefined.
`put(key: string, value: V, param?: { ttl?: Duration; noTtl?: boolean; }): void`
Put the item into cache.
If there is already a cache with the same key, this will replace the old one and the expired timestamp will be renew base on the new TTL.
If the cache is full, it will remove
- the item that will expire first if there exist at least one item with TTL
- the item inserted first if all items in the cache are without TTL
`delete(key: string): boolean`
Delete the item from cache with the given key if exists.
`clear(): void`
Delete all items in the cache.
`size(): Integer`
Return the total number of item in this cache.
`clearExpiredItems(): void`
Delete all expired items in the cache.
## Config
The cache created is config by the `CacheOption` passed to the factory.
Set up the `CacheOption` by the setter of its attributes (listed below).
| Option | Type | Default | Description |
| :---------- | ---------------- | ------- | :---------- |
| defaultTTL | Duration or null | null | The TTL for a item put() without a TTL.
null = never timeout |
| maxSize | integer > 0 | 100 | The maximum number of key-value pairs the cache can hold. |