simple-cache


A basic key value store with bounded capacity for simple caching.

Install

``sh
npm install @alexsasharegan/simple-cache
`

Documentation

Visit the
API Documentation here.

Cache is an interface for caching key/value pairs of types K/V. It's primary
functionality includes:

- Cache.write: write a value at a key
- Cache.read: read a value from a key
- Cache.get: read a value as an Option (maybe type)
- Cache.remove: remove a value by key
- Cache.clear: empty the cache

Usage

Creating a cache looks like this in plain JavaScript:

`js
// Creates a cache with a capacity of 10 items. The second parameter is the
// "type label". It serves as a convenience option for more meaningful
// toString behavior.
let userCache = SimpleCache(10, { key: "ID", value: "User" })
userCache.toString()
// SimpleCache { size: 0, capacity: 10 }
`

If you're using TypeScript, you need to create a cache by declaring the key and
value types as generic parameters:

`ts
interface User {
id: number
name: string
}

let userCache = SimpleCache(10, { key: "ID", value: "User" })
userCache.toString()
// SimpleCache { size: 0, capacity: 10 }
`

Here are some examples of the five main interaction methods shown in REPL style.
If you're curious to learn more about the Option type returned from
Cache.get, visit the
safe-types repository.

`js
let userA = { name: "User A", id: 1 }
let userB = { name: "User B", id: 2 }

userCache.write(userA.id, userA)
userCache.write(userB.id, userB)
userCache.size()
// 2

userCache.read(1)
// { name: "User A", id: 1 }
userCache.read(2)
// { name: "User B", id: 2 }
userCache.get(2)
// Some<{ name: "User B", id: 2 }>
userCache.read(3)
// undefined
userCache.get(3)
// None

userCache.remove(1)
userCache.size()
// 1
userCache.read(1)
// undefined
userCache.clear()
userCache.size()
// 0
`

There is an Ephemeral Cache available. It caches items for a duration that's
given in milliseconds.

`ts
// Sets a capacity of 10 users and a max lifetime of 5 seconds
let userCache = EphemeralCache(10, 5000, {
key: "ID",
value: "User",
})

userCache.write(1, { name: "Temp", id: 1 })

setTimeout(() => {
userCache.read(1)
// undefined
}, 5001)

userCache.read(1)
// { name: "Temp", id: 1 }
``