https://github.com/zeptosec/event-cache
An in-memory cache with event-driven expiration.
https://github.com/zeptosec/event-cache
cache caching deno event-driven in-memory typescript
Last synced: 2 months ago
JSON representation
An in-memory cache with event-driven expiration.
- Host: GitHub
- URL: https://github.com/zeptosec/event-cache
- Owner: Zeptosec
- License: mit
- Created: 2025-03-08T19:36:44.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-27T20:49:59.000Z (over 1 year ago)
- Last Synced: 2025-10-12T03:43:38.674Z (9 months ago)
- Topics: cache, caching, deno, event-driven, in-memory, typescript
- Language: TypeScript
- Homepage:
- Size: 148 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://codecov.io/gh/Zeptosec/event-cache)
[](https://jsr.io/@zeptosec/event-cache)
[](https://www.npmjs.com/package/@riposte/event-cache)
[](/LICENSE)
# Event Cache
The main purpose of this libary is to store key-value pairs while also managing
the expiration of those entries and emitting events when items expire. This is
useful for scenarios where you need a cache that automatically removes stale
data and notifies other parts of your application when that happens.
# Library description
## Provided functions
A table documenting all public methods of each class
### EventCache class
| Method Name | Parameters | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| constructor | `options: EventCacheProps - deleteOnExpire?: boolean`: Whether to delete expired items (defaults to `true`). - `eventStrategy: EventStrategy`: The event expiration strategy. | Initializes a new EventCache instance, setting the deleteOnExpire option and the eventStrategy. |
| set | `key: K` `value: V`. `key`: The key to add/update in the cache. `value`: The value to store associated with the key. | Adds or updates a key-value pair in the cache. It also manages the expiration event for the item. Returns `this` (the `EventCache` instance). |
| delete | `key: K`. The key to remove from the cache. | Removes a key-value pair from the cache and the associated expiration event. Returns `true` if an item was removed, false otherwise. |
| get | `key: K`. The key to retrieve from the cache. | Retrieves the value associated with the given key. Returns the value if found, `undefined` otherwise. |
| clear | None | Clears all key-value pairs from the cache and removes all expiration events. |
| size | None | A getter that returns the number of items currently in the cache. |
| entries | Returns an iterator of `[key, value]` pairs for each entry in the cache | Returns an iterator of `[key, value]` pairs for each entry in the cache. |
| keys | None | Returns an iterator of keys for each entry in the cache. |
| values | None | Returns an iterator of values for each entry in the cache. |
| has | `key: K`. The key to check for. | Checks if the cache contains a key. Returns `true` if the key exists, `false` otherwise. |
| forEach | `callback: (value: V, key: K, map: Map) => void` A function to execute for each key-value pair. It receives the value, key, and the map as arguments. | Iterates over each key-value pair in the cache and executes the provided callback function. |
| addEventListener | `type: T extends keyof EventCacheEvents listener: (event: EventCacheEvents[T]) => void` options?: boolean | A function that will be called when an item in a cache expires. |
## Business problems that library solves
This library helps to solve several business problems related to caching and
event management:
- **Managing expired data:** Many applications need to cache data for
permormance, but that data often has a limited lifespan. This library
automates removal of old data while still working as a cache.
- **Event based notifications:** Provides a convenient way of knowing when data
becomes outdated through events.
- **Flexible expiration strategies:** For better performance there's `interval`
based strategy which can handle many more events. For more accuracy there's
`timeout` based strategy.
## Intended use
This library is intended for use in applications that requires caching with data
expiration.
- **Real-time data:** frequently updated data, such as price discounts, weather
information. Once data expires it can easily be updated again when event is
received.
- **Rate-limiting:** Caching responses from APIs with rate limits. It can cache
frequently fetched responses so that the database isn't used on every request.
- **Web applications:** Caching frequently used data to improve performance and
user expirience. Caching API responses on the front end.
This library is useful in any situation where data needs to be cached for
performance while expired data is removed.
## Restrictions for library usage
Here are outlined the main restrictions for using the library
### Technical restrictions
- **Event Listener Management:** `addEventListener` provides a way to attach an
event to an object to receive events after the data expired. This event should
be removed with `AbortController` after it is no longer needed.
- **Implementation limitations:** `EventCache` triggers events asynchronously.
This means that expiration events are not guaranteed to happen **exactly** at
specified time. Slight delays should be expected.
### Business restrictions
- **Expiry requirement:** This libary is primarily for caching data that will
expire. If your data never expires then a simpler caching solutions might be
more appropriate.
- **Data sensitivy:** This library doesn't provide any data encryption. It is
stored as provided.
## Other important information
### Performance
The performance of event cache is directly related to `EventStrategy`. So it is
very important to choose event strategy that you need. `IntervalStrategy` is
more performant, but events may not be received on time. `TimeoutStrategy`
should be more accurate than `IntervalStrategy`, but it may consume more memory
when there's a lot of data.
## Features
- **Time-based expiration (TimeoutStrategy):** Items expire after a specified
time-to-live (TTL).
- **Interval-based expiration (IntervalStrategy):** Items are checked for
expiration at regular intervals.
- **Event-driven expiration:** Events are emitted when items expire, allowing
you to perform cleanup or other actions.
- **Configurable deleteOnExpire:** Choose whether to automatically remove
expired items from the cache or retain them.
- **Extensible:** Easily create custom expiration strategies.
- **Simple API:** Easy to use and integrate into your projects.
## Class diagram
Below is the class diagram illustrating the architecture of the Event Cache
library.
[](./assets/class_diagram.jpg)
## Examples
The `EventCacheFactory` provides convenient methods to create caches with
predefined strategies:
```ts
import { EventCacheFactory } from "@zeptosec/event-cache";
// Time-based expiration using TimeoutStrategy
const timeoutCache = EventCacheFactory.createEventCacheTimeout(
5000,
); // Items expire after 5 seconds
// Create AbortController for removing event listener if needed
const abortController = new AbortController();
timeoutCache.addEventListener("expire", (expiredItem) => {
console.log(`Item '${expiredItem.key}' expired. Value: ${expiredItem.value}`);
}, {
signal: abortController.signal,
});
timeoutCache.set("myKey", 123);
setTimeout(() => {
console.log(`myKey (3000 ms): ${timeoutCache.get("myKey")}`);
// Access the value before expiration
}, 3000);
setTimeout(() => {
console.log(`myKey (7000 ms): ${timeoutCache.get("myKey")}`);
// Access the value after expiration
abortController.abort(); // Remove event listener
}, 7000);
// Interval-based expiration using IntervalStrategy
const intervalCache = EventCacheFactory.createEventCacheInterval<
string,
string
>(2000); // Items are checked every 2 seconds
intervalCache.addEventListener("expire", (expiredItem) => {
console.log(`Item '${expiredItem.key}' expired. Value: ${expiredItem.value}`);
});
intervalCache.set("key2", "hello");
setTimeout(() => {
console.log(`key2 (1000 ms): ${intervalCache.get("anotherKey")}`);
// Access the value before expiration
}, 1000);
setTimeout(() => {
console.log(`key2 (3000 ms): ${intervalCache.get("anotherKey")}`);
// Access the value after expiration
}, 3000);
```
Using `EventCacheBuilder` to build your own `EventCache`:
```ts
import { EventCacheBuilder, IntervalStrategy } from "@zeptosec/event-cache";
const builder = new EventCacheBuilder();
// Items are checked every 500ms, TTL is 1000ms, and expired items are NOT deleted.
const intervalCacheCustom = builder
.withStrategy(
new IntervalStrategy(1000, 500),
false,
).build();
intervalCacheCustom.addEventListener("expire", (expiredItem) => {
console.log(`Item '${expiredItem.key}' expired. Value: ${expiredItem.value}`);
});
intervalCacheCustom.set(1, "test");
setTimeout(() => {
console.log(`1 (2000ms): ${intervalCacheCustom.get(1)}`); // Value should still be present even after expiration.
}, 2000);
setTimeout(() => {
console.log(`1 (3000ms): ${intervalCacheCustom.get(1)}`); // Value should still be present even after expiration.
}, 3000);
```
Using `EventCache` with strategy directly:
```ts
import { EventCache, TimeoutStrategy } from "@zeptosec/event-cache";
const eventCache = new EventCache({
deleteOnExpire: false, // do not delete after expired
eventStrategy: new TimeoutStrategy(1000), // TTL: 1 second
});
eventCache.set(42, "answer");
eventCache.addEventListener("expire", ({ key, value }) => {
console.log(`expired: ${key}: ${value}`);
});
setTimeout(() => {
console.log(`Before expired: ${eventCache.get(42)}`);
// value is defined
}, 500);
setTimeout(() => {
console.log(`After expired: ${eventCache.get(42)}`);
// value is still defined
}, 2000);
```
## Analysis of alternative packages
There are many different packages for caching data and receiving event when it
expires.
[@cacheable](https://www.npmjs.com/package/cacheable) has more features and is
very popular.
[@cache-manager](https://www.npmjs.com/package/cache-manager) Similar to
[@cacheable](https://www.npmjs.com/package/cacheable) has a lot of different
functionality for managing the cache like emitting event when key is set or
deleted.
[@node-cache](https://www.npmjs.com/package/node-cache) Also very popular
package with the similar functionaly and many more features.
[@buffered-queue](https://www.npmjs.com/package/buffered-queue) stores a list of
items and then after specified time returns an event with all the data in the
queue or if the size limit is reached.
So there are many other packages to choose from if you find that this pacakage
is lacking some features that you need.