feat: Upgrade event callbacks into EventEmitter (#16)

Author: helloscoopa

.github/workflows/build.yml

@@ -19,5 +19,8 @@ jobs:
           node-version: "18"
           registry-url: "https://registry.npmjs.org"
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Build
         run: npm run build

.vscode/settings.json

@@ -1,3 +1,3 @@
 {
-  "cSpell.words": ["refetchable", "refetched"]
+  "cSpell.words": ["refetchable", "refetched", "refetches"]
 }

README.md

@@ -2,19 +2,18 @@
 [![license](https://img.shields.io/github/license/helloscoopa/run-cache)](https://github.com/helloscoopa/run-cache?tab=MIT-1-ov-file)
 [![ci-build](https://img.shields.io/github/actions/workflow/status/helloscoopa/run-cache/build.yml?label=build)](https://github.com/helloscoopa/run-cache/actions/workflows/build.yml)
 [![ci-tests](https://img.shields.io/github/actions/workflow/status/helloscoopa/run-cache/tests.yml?label=tests)](https://github.com/helloscoopa/run-cache/actions/workflows/tests.yml)
-[![commits-since](https://img.shields.io/github/commits-since/helloscoopa/run-cache/latest/main?color=yellow)](https://github.com/helloscoopa/run-cache/releases/latest)
 
 # Run~time~Cache
 
-RunCache is a dependency nil, light-weight in-memory caching library for JavaScript and TypeScript that allows you to cache `string` values with optional time-to-live (TTL) settings. It also supports caching values generated from asynchronous functions and provides methods to refetch them on demand.
+RunCache is a dependency-free, lightweight runtime caching library for JavaScript and TypeScript that allows you to cache `string` values with optional time-to-live (TTL) settings. It also supports caching values generated from sync/async functions and provide methods to refetch them on expiry or on demand; with a set of events to keep track of the state of the cache.
 
 ## Features
 
-- **In-memory caching** with optional TTL (time-to-live).
-- **Asynchronous source functions** for fetching and caching dynamic data.
-- **Refetch functionality** to update cache values using stored source functions.
-- **Events** to get know when cache expires or being refetched.
-- **Easy interface** for managing cached data: set, get, delete and check existence.
+- **Dependency-free:** Does not consume any external dependencies.
+- **In-memory caching:** A runtime cache that gives you quick access.
+- **Sync/async source functions:** Fetch dynamic data from user-defined functions.
+- **Events:** Get to know when cache expires, refetched or refetch fails.
+- **Intuitive SDK:** Clean interface to access data.
 
 ## Installation
 
@@ -32,7 +31,7 @@ npm install run-cache
 import { RunCache } from "run-cache";
 ```
 
-#### Set cache:
+#### Set cache
 
 ```ts
 // Set a cache value
@@ -68,38 +67,52 @@ await RunCache.set({
 });
 
 /*
-  Use a callback function to get know when your cache expires
+  Use a callback function to get to know when your cache expires
   or when its being refetched. The expiry is triggered only
   on demand, not automatically.
 */
 import { EventParam } from "run-cache";
 
+// Event of all expiries
+RunCache.onExpiry((cache: EventParam) => {
+  console.log(`Cache of key '${cache.key}' has been expired`);
+})
+
+// Event of a specific key expiry
+RunCache.onKeyExpiry('Key', (cache: EventParam) => {
+  console.log(`Cache of key '${cache.key}' has been expired`);
+})
+
 await RunCache.set({
   key: "Key",
-  ttl: 10000,
-  onExpiry: async (cache: EventParam) => {
-    console.log(`Cache of key '${cache.key}' has been expired`);
-  }
+  ttl: 10000
+})
+
+// Event of all refetches
+RunCache.onRefetch((cache: EventParam) => {
+  console.log(`Cache of key '${cache.key}' has been refetched`);
+})
+
+// Event of a specific key refetch
+RunCache.onKeyRefetch('Key', (cache: EventParam) => {
+  console.log(`Cache of key '${cache.key}' has been refetched`);
 })
 
 await RunCache.set({
   key: "Key",
   ttl: 10000,
   sourceFn: () => { return Promise.resolve("Value") }
-  onRefetch: async (cache: EventParam) => {
-    console.log(`Cache of key '${cache.key}' has been refetched`);
-  }
 })
 ```
 
-#### Refetch cache:
+#### Refetch cache
 
 ```ts
 // Refetch the cache value (Only works if the key is set with a sourceFn)
 await RunCache.refetch("Key");
 ```
 
-#### Get cache:
+#### Get cache
 
 ```ts
 /* 
@@ -109,19 +122,37 @@ await RunCache.refetch("Key");
 const value = await RunCache.get("Key");
 ```
 
-#### Delete cache:
+#### Delete cache
 
 ```ts
 // Delete a specific cache key
 RunCache.delete("Key");
 
 // Delete all cache keys
-RunCache.deleteAll();
+RunCache.flush();
 ```
 
-#### Check existence of a specific cache:
+#### Check the existence of a specific cache
 
 ```ts
 // Returns a boolean, expired cache returns `false` even if they're refetchable
 const hasCache = RunCache.has("Key");
 ```
+
+#### Clear event listeners
+
+```ts
+// Clear all listeners
+RunCache.clearEventListeners();
+
+// Clear specific event listeners
+RunCache.clearEventListeners({
+  event: "expiry",
+});
+
+// Clear specific event key listeners
+RunCache.clearEventListeners({
+  event: "expiry",
+  key: "Key",
+});
+```

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "run-cache",
-  "version": "1.3.2",
-  "description": "RunCache is a dependency nil, light-weight in-memory caching library for JavaScript and TypeScript that allows you to cache `string` values with optional time-to-live (TTL) settings. It also supports caching values generated from asynchronous functions and provides methods to refetch them on demand.",
+  "version": "1.4.0",
+  "description": "RunCache is a dependency-free, light-weight in-memory caching library for JavaScript and TypeScript that allows you to cache `string` values with optional time-to-live (TTL) settings. It also supports caching values generated from asynchronous functions and provides methods to refetch them on demand.",
   "main": "dist/run-cache.js",
   "types": "dist/run-cache.d.ts",
   "scripts": {
@@ -29,8 +29,10 @@
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",
+    "@types/uuid": "^10.0.0",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.5",
-    "tsx": "^4.19.1"
+    "tsx": "^4.19.1",
+    "uuid": "^10.0.0"
   }
 }