feat: Add memory percentage limit strategy

BENCHMARK.md

@@ -203,7 +203,7 @@ Multi-level caching provides the most benefit when:
 
 ## Performance Tips
 
-1. **Tune Memory Strategies:** Adjust `MemoryPercentageLimitStrategy` threshold based on your application's memory profile
+1. **Tune Memory Strategies:** Adjust `RamPercentageLimitStrategy` threshold based on your application's memory profile
 2. **Choose Appropriate TTL:** Set cache TTL values that balance freshness and hit rate
 3. **Monitor Cache Metrics:** Track hit rates to optimize cache configuration
 4. **Size Your Cache:** Use Benchmark 4 to estimate memory requirements

README.md

@@ -68,12 +68,12 @@ import {
   CacheService,
   MemoryCacheLevel,
   FirstExpiringMemoryPolicy,
-  MemoryPercentageLimitStrategy
+  RamPercentageLimitStrategy
 } from 'cacheforge';
 
 // Create memory cache with eviction policy and strategy
 const memoryCache = new MemoryCacheLevel({
-  memoryStrategies: [new MemoryPercentageLimitStrategy(80)], // Trigger at 80% memory
+  memoryStrategies: [new RamPercentageLimitStrategy(80)], // Trigger at 80% memory
   evictionPolicy: new FirstExpiringMemoryPolicy()
 });
 
@@ -103,11 +103,11 @@ At the top (CacheService), fallbacks are handled. However the added layers do no
 Fast, in-memory caching using a Map and min-heap for efficient expiration tracking.
 
 ```typescript
-import { MemoryCacheLevel, FirstExpiringMemoryPolicy, MemoryPercentageLimitStrategy } from 'cacheforge';
+import { MemoryCacheLevel, FirstExpiringMemoryPolicy, RamPercentageLimitStrategy } from 'cacheforge';
 
 const memoryCache = new MemoryCacheLevel({
   memoryStrategies: [
-    new MemoryPercentageLimitStrategy(75) // Evict when memory exceeds 75%
+    new RamPercentageLimitStrategy(75) // Evict when memory exceeds 75%
   ],
   evictionPolicy: new FirstExpiringMemoryPolicy()
 });
@@ -145,14 +145,26 @@ const policy = new FirstExpiringMemoryPolicy();
 
 Strategies check conditions and trigger eviction policies when thresholds are met.
 
-#### MemoryPercentageLimitStrategy
+#### MemorySizeLimitStrategy (Recommended Default)
+Triggers eviction when the total size of items in the cache exceeds a defined threshold (as a percentage of the Node.js process heap).
+
+This strategy is recommended as the default for most applications, as it provides a more accurate measurement of cache memory usage and helps prevent out-of-memory errors.
+
+```typescript
+import { MemorySizeLimitStrategy } from 'cacheforge';
+
+// Trigger eviction when cache uses 10% or more of Node.js heap
+const strategy = new MemorySizeLimitStrategy(10);
+```
+
+#### RamPercentageLimitStrategy
 Triggers eviction when system memory usage exceeds a percentage threshold.
 
 ```typescript
-import { MemoryPercentageLimitStrategy } from 'cacheforge';
+import { RamPercentageLimitStrategy } from 'cacheforge';
 
 // Trigger eviction at 80% memory usage
-const strategy = new MemoryPercentageLimitStrategy(80);
+const strategy = new RamPercentageLimitStrategy(80);
 ```
 
 ## Usage Guide
@@ -166,13 +178,13 @@ import {
   CacheService,
   MemoryCacheLevel,
   FirstExpiringMemoryPolicy,
-  MemoryPercentageLimitStrategy
+  RamPercentageLimitStrategy
 } from 'cacheforge';
 
 const cache = new CacheService({
   levels: [
     new MemoryCacheLevel({
-      memoryStrategies: [new MemoryPercentageLimitStrategy(80)],
+      memoryStrategies: [new RamPercentageLimitStrategy(80)],
       evictionPolicy: new FirstExpiringMemoryPolicy()
     })
   ],
@@ -202,12 +214,12 @@ import {
   MemoryCacheLevel,
   RedisCacheLevel,
   FirstExpiringMemoryPolicy,
-  MemoryPercentageLimitStrategy
+  RamPercentageLimitStrategy
 } from 'cacheforge';
 import Redis from 'ioredis';
 
 const memoryCache = new MemoryCacheLevel({
-  memoryStrategies: [new MemoryPercentageLimitStrategy(75)],
+  memoryStrategies: [new RamPercentageLimitStrategy(75)],
   evictionPolicy: new FirstExpiringMemoryPolicy()
 });
 
@@ -236,7 +248,7 @@ import Redis from 'ioredis';
 const cache = new CacheService({
   levels: [
     new MemoryCacheLevel({
-      memoryStrategies: [new MemoryPercentageLimitStrategy(80)],
+      memoryStrategies: [new RamPercentageLimitStrategy(80)],
       evictionPolicy: new FirstExpiringMemoryPolicy()
     }),
     new RedisCacheLevel(new Redis())
@@ -556,8 +568,11 @@ await cache.invalidateKey('user:123');
 
 ### 4. Memory Strategy Thresholds
 
-- Development: 80-90% (more headroom)
-- Production: 70-75% (prevent OOM issues)
+
+- **Recommended Default:** Use `MemorySizeLimitStrategy` with a threshold of 10-20% of Node.js heap for most production workloads.
+- **RamPercentageLimitStrategy:**
+  - Development: 80-90% (more headroom)
+  - Production: 70-75% (prevent OOM issues)
 
 ### 5. Distributed Locking
 
@@ -608,14 +623,14 @@ Example test using the library:
 
 ```typescript
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { CacheService, MemoryCacheLevel, FirstExpiringMemoryPolicy, MemoryPercentageLimitStrategy } from 'cacheforge';
+import { CacheService, MemoryCacheLevel, FirstExpiringMemoryPolicy, RamPercentageLimitStrategy } from 'cacheforge';
 
 describe('Cache Service', () => {
   let cache: CacheService;
 
   beforeEach(() => {
     const memoryCache = new MemoryCacheLevel({
-      memoryStrategies: [new MemoryPercentageLimitStrategy(80)],
+      memoryStrategies: [new RamPercentageLimitStrategy(80)],
       evictionPolicy: new FirstExpiringMemoryPolicy()
     });
 

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cacheforge",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "A multi-level caching library for Node.js applications, supporting in-memory and Redis, and custom cache levels.",
 	"main": "dist/src/index.js",
 	"types": "dist/src/index.d.ts",

src/cache.service.spec.ts

@@ -13,7 +13,7 @@ import {
 	type StoredHeapItem,
 } from "./levels";
 import { FirstExpiringMemoryPolicy } from "./policies/first-expiring-memory.policy";
-import { MemoryPercentageLimitStrategy } from "./strategies/memory-percentage-limit.strategy";
+import { RamPercentageLimitStrategy } from "./strategies/ram-percentage-limit.strategy";
 
 let redisContainer: StartedRedisContainer;
 let redisLevel: RedisCacheLevel;
@@ -25,7 +25,7 @@ let faultyFirstLevelVersionedCacheService: CacheService;
 let faultyFirstLevelCacheService: CacheService;
 let allFaultyLevelsCacheService: CacheService;
 let allFaultyLevelsVersionedCacheService: CacheService;
-const memoryStrategy = new MemoryPercentageLimitStrategy<StoredHeapItem>(70);
+const memoryStrategy = new RamPercentageLimitStrategy<StoredHeapItem>(70);
 const evictionPolicy = new FirstExpiringMemoryPolicy();
 memoryLevel = new MemoryCacheLevel({
 	memoryStrategies: [memoryStrategy],

src/levels/interfaces/in-memory.ts

@@ -12,4 +12,10 @@ export interface InMemory<T> {
 	 * @return Array of items in the heap.
 	 */
 	getHeap(): MemoryHeap<T>;
+
+	/**
+	 * Get the size of the key-value store in bytes.
+	 * @return Size of the store in bytes.
+	 */
+	getStoreSize(): number;
 }

src/levels/memory/eviction-manager.spec.ts

@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { AbstractMemoryEvictionPolicy } from "../../policies/abstract/abstract-memory-eviction.policy";
 import { FirstExpiringMemoryPolicy } from "../../policies/first-expiring-memory.policy";
-import { MemoryPercentageLimitStrategy } from "../../strategies/memory-percentage-limit.strategy";
+import { RamPercentageLimitStrategy } from "../../strategies/ram-percentage-limit.strategy";
 import { EvictionManager } from "./eviction-manager";
 import { MemoryCacheLevel, type StoredHeapItem } from "./memory.level";
 import { triggerMemoryChange } from "./memory-event.manager";
@@ -14,11 +14,11 @@ describe("EvictionManager", () => {
 	let memoryLevel: MemoryCacheLevel;
 	let evictionPolicy: FirstExpiringMemoryPolicy;
 	let memoryWithoutEvictionPolicy: MemoryCacheLevel;
-	let memoryStrategy: MemoryPercentageLimitStrategy<StoredHeapItem>;
+	let memoryStrategy: RamPercentageLimitStrategy<StoredHeapItem>;
 
 	beforeEach(() => {
 		evictionPolicy = new FirstExpiringMemoryPolicy();
-		memoryStrategy = new MemoryPercentageLimitStrategy(0); // Always triggers
+		memoryStrategy = new RamPercentageLimitStrategy(0); // Always triggers
 		memoryLevel = new MemoryCacheLevel({
 			memoryStrategies: [memoryStrategy],
 			evictionPolicy,
@@ -73,7 +73,7 @@ describe("EvictionManager", () => {
 	});
 
 	it("does not evict if no strategy triggers", async () => {
-		const neverStrategy = new MemoryPercentageLimitStrategy(100); // Never triggers
+		const neverStrategy = new RamPercentageLimitStrategy(100); // Never triggers
 		const neverOptions = {
 			memoryStrategies: [neverStrategy],
 			evictionPolicy,

src/levels/memory/memory.level.spec.ts

@@ -2,11 +2,11 @@ import { faker, fakerZH_TW } from "@faker-js/faker";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { generateJSONData } from "../../../tests/utilities/data.utilities";
 import { FirstExpiringMemoryPolicy } from "../../policies";
-import { MemoryPercentageLimitStrategy } from "../../strategies/memory-percentage-limit.strategy";
+import { RamPercentageLimitStrategy } from "../../strategies/ram-percentage-limit.strategy";
 import { MemoryCacheLevel, type StoredHeapItem } from "..";
 
 const evictionPolicy = new FirstExpiringMemoryPolicy();
-const strategy = new MemoryPercentageLimitStrategy<StoredHeapItem>(80);
+const strategy = new RamPercentageLimitStrategy<StoredHeapItem>(80);
 const cacheEngine = new MemoryCacheLevel({
 	memoryStrategies: [strategy],
 	evictionPolicy: evictionPolicy,
@@ -125,6 +125,12 @@ describe("should successfully store data, and retrieve it on demand", async () =
 			await cacheEngine.mget<number>(["bingo", "bingo1", "bingo2"]),
 		).toEqual([undefined, undefined, undefined]);
 	});
+
+	it("should get store size in bytes", () => {
+		const storeSize = cacheEngine.getStoreSize();
+		expect(typeof storeSize).toBe("number");
+		expect(storeSize).toBeGreaterThanOrEqual(0);
+	});
 });
 
 describe("It should successfully manage the application memory usage", () => {

src/levels/memory/memory.level.ts

@@ -3,6 +3,7 @@ import { DEFAULT_TTL } from "../../constants";
 import type { AbstractMemoryEvictionPolicy } from "../../policies/abstract/abstract-memory-eviction.policy";
 import type { MemoryManagementStrategy } from "../../strategies/interfaces/memory-management-strategy";
 import { createCacheHeap } from "../../utils/heap.utils";
+import { serialize } from "../../utils/parsing.utils";
 import type { CacheLevel } from "../interfaces/cache-level";
 import type { InMemory } from "../interfaces/in-memory";
 import type { Purgable } from "../interfaces/purgable";
@@ -26,6 +27,7 @@ export class MemoryCacheLevel
 	implements CacheLevel, Purgable, InMemory<StoredHeapItem>
 {
 	protected store = new Map<string, StoredItem>();
+	protected size = 0;
 	protected heap = createCacheHeap<StoredHeapItem>((item) => item.expiry);
 	protected evictionManager: EvictionManager;
 
@@ -41,17 +43,17 @@ export class MemoryCacheLevel
 		await Promise.all(deletePromises);
 	}
 
-	private insertHeapItem(item: StoredHeapItem) {
-		this.heap.insert(item);
-	}
-
 	private updateStore(key: string, item: StoredItem) {
 		this.store.set(key, item);
-
-		this.insertHeapItem({ ...item, key });
+		this.heap.insert({ ...item, key });
+		this.size += serialize(item).length;
 		triggerMemoryChange();
 	}
 
+	public getStoreSize(): number {
+		return this.size;
+	}
+
 	async mset<T>(
 		keys: string[],
 		values: T[],

src/levels/redis/redis.level.ts

@@ -3,10 +3,7 @@ import type IoRedis from "ioredis";
 import type { Cluster } from "ioredis";
 import { DEFAULT_TTL } from "../../constants";
 import { parseIfJSON } from "../../utils/cache.utils";
-import {
-	deserializeFromRedis,
-	serializeForRedis,
-} from "../../utils/parsing.utils";
+import { deserialize, serialize } from "../../utils/parsing.utils";
 import { generateVersionLookupKey } from "../../utils/version.utils";
 import type { CacheLevel } from "../interfaces/cache-level";
 import type { Lockable } from "../interfaces/lockable";
@@ -38,7 +35,7 @@ export class RedisCacheLevel implements CacheLevel, Lockable {
 		for (let i = 0; i < keys.length; i++) {
 			const key = keys[i];
 			const value = values[i];
-			pipeline.set(key, serializeForRedis(value), "EX", ttl);
+			pipeline.set(key, serialize(value), "EX", ttl);
 		}
 
 		await pipeline.exec();
@@ -56,15 +53,15 @@ export class RedisCacheLevel implements CacheLevel, Lockable {
 			if (cachedValue === null || cachedValue === undefined) {
 				finalResults.push(undefined as T);
 			} else {
-				finalResults.push(deserializeFromRedis(cachedValue));
+				finalResults.push(deserialize(cachedValue));
 			}
 		}
 
 		return finalResults;
 	}
 
 	async set<T>(key: string, value: T, ttl = DEFAULT_TTL) {
-		await this.client.set(key, serializeForRedis(value), "EX", ttl);
+		await this.client.set(key, serialize(value), "EX", ttl);
 
 		return parseIfJSON(value) as T;
 	}

src/policies/first-expiring-memory.policy.spec.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { generateJSONData } from "../../tests/utilities/data.utilities";
 import { MemoryCacheLevel } from "../levels";
-import { MemoryPercentageLimitStrategy } from "../strategies/memory-percentage-limit.strategy";
+import { RamPercentageLimitStrategy } from "../strategies/ram-percentage-limit.strategy";
 import { FirstExpiringMemoryPolicy } from "./first-expiring-memory.policy";
 
 const policy = new FirstExpiringMemoryPolicy();
-const strategy = new MemoryPercentageLimitStrategy(80);
+const strategy = new RamPercentageLimitStrategy(80);
 const cacheEngine = new MemoryCacheLevel({
 	memoryStrategies: [strategy],
 	evictionPolicy: policy,
@@ -33,10 +33,9 @@ describe("First Expiring Memory Policy", () => {
 
 		const policy = new FirstExpiringMemoryPolicy();
 
-		for (let i = 0; i <= 10000; i++) {
-			await policy.evict(cacheEngine);
-		}
+		await policy.evict(cacheEngine);
 
-		expect(cacheEngine.getHeap().getCount()).toEqual(0);
+		// 10% has been removed.
+		expect(cacheEngine.getHeap().getCount()).toEqual(900);
 	});
 });

src/strategies/index.ts

@@ -1 +1,2 @@
-export * from "./memory-percentage-limit.strategy";
+export * from "./memory-size-limit.strategy";
+export * from "./ram-percentage-limit.strategy";