offheap 0.1.0 → 0.2.0

package/src/cache.rs

@@ -1,11 +1,13 @@
 use std::sync::Arc;
-use napi::{Env, JsUnknown, JsBuffer, JsString, Result, ValueType};
-use super::algorithms::{CacheImpl, CacheStats, lru::LruCache, arc::ArcCache, tinylfu::TinyLfuCache};
+use napi::{Env, JsUnknown, JsBuffer, JsString, JsObject, Result, ValueType};
+use super::algorithms::{CacheImpl, lru::LruCache, arc::ArcCache, tinylfu::TinyLfuCache};
 
 #[napi(object)]
 pub struct CacheConfig {
     pub policy: String,
     pub capacity: u32,
+    pub shards: Option<u32>,
+    pub max_bytes: Option<f64>,
 }
 
 #[napi(object)]
@@ -14,17 +16,18 @@ pub struct CacheStatsJs {
     pub misses: f64,
     pub capacity: f64,
     pub size: f64,
+    pub bytes_used: f64,
 }
 
 #[napi]
 pub struct Cache {
-    inner: Arc<parking_lot::Mutex<Box<dyn CacheImpl>>>,
+    shards: Vec<Arc<parking_lot::Mutex<Option<Box<dyn CacheImpl>>>>>,
 }
 
 impl Clone for Cache {
     fn clone(&self) -> Self {
         Self {
-            inner: Arc::clone(&self.inner),
+            shards: self.shards.clone(),
         }
     }
 }
@@ -32,58 +35,32 @@ impl Clone for Cache {
 impl Cache {
     pub fn from_config(config: CacheConfig) -> Self {
         let capacity = config.capacity as usize;
+        let shards_count = config.shards.unwrap_or(8).max(1) as usize;
         let policy_lower = config.policy.to_lowercase();
-        let inner: Box<dyn CacheImpl> = match policy_lower.as_str() {
-            "arc" => Box::new(ArcCache::new(capacity)),
-            "tinylfu" | "w-tinylfu" => Box::new(TinyLfuCache::new(capacity)),
-            _ => Box::new(LruCache::new(capacity)),
-        };
-        Self {
-            inner: Arc::new(parking_lot::Mutex::new(inner)),
+        
+        let shard_capacity = (capacity / shards_count).max(1);
+        let shard_max_bytes = config.max_bytes.map(|mb| (mb as usize / shards_count).max(1));
+
+        let mut shards = Vec::with_capacity(shards_count);
+        for _ in 0..shards_count {
+            let inner: Box<dyn CacheImpl> = match policy_lower.as_str() {
+                "arc" => Box::new(ArcCache::new_with_max_bytes(shard_capacity, shard_max_bytes)),
+                "tinylfu" | "w-tinylfu" => Box::new(TinyLfuCache::new_with_max_bytes(shard_capacity, shard_max_bytes)),
+                _ => Box::new(LruCache::new_with_max_bytes(shard_capacity, shard_max_bytes)),
+            };
+            shards.push(Arc::new(parking_lot::Mutex::new(Some(inner))));
         }
+
+        Self { shards }
     }
-}
 
-#[napi]
-impl Cache {
-    #[napi]
-    pub fn get(&self, env: Env, key: String) -> Result<JsUnknown> {
-        let mut lock = self.inner.lock();
-        if let Some(bytes) = lock.get(&key) {
-            if bytes.is_empty() {
-                return Ok(env.get_undefined()?.into_unknown());
-            }
-            let tag = bytes[0];
-            let payload = &bytes[1..];
-            match tag {
-                1 => {
-                    // Buffer
-                    let js_buf = env.create_buffer_copy(payload)?;
-                    Ok(js_buf.into_unknown())
-                }
-                2 => {
-                    // String
-                    let s = std::str::from_utf8(payload)
-                        .map_err(|e| napi::Error::new(napi::Status::StringExpected, e.to_string()))?;
-                    let js_str = env.create_string(s)?;
-                    Ok(js_str.into_unknown())
-                }
-                3 => {
-                    // JSON
-                    let json_val: serde_json::Value = serde_json::from_slice(payload)
-                        .map_err(|e| napi::Error::new(napi::Status::InvalidArg, e.to_string()))?;
-                    let parsed = env.to_js_value(&json_val)?;
-                    Ok(parsed)
-                }
-                _ => Err(napi::Error::new(napi::Status::InvalidArg, "Invalid data type tag in cache storage")),
-            }
-        } else {
-            Ok(env.get_undefined()?.into_unknown())
-        }
+    fn get_shard(&self, key: &str) -> Result<Arc<parking_lot::Mutex<Option<Box<dyn CacheImpl>>>>> {
+        let hash = seahash::hash(key.as_bytes()) as usize;
+        let idx = hash % self.shards.len();
+        Ok(Arc::clone(&self.shards[idx]))
     }
 
-    #[napi]
-    pub fn set(&self, env: Env, key: String, value: JsUnknown, ttl_ms: Option<f64>) -> Result<JsUnknown> {
+    fn serialize_value(&self, env: Env, value: JsUnknown) -> Result<Vec<u8>> {
         let mut bytes = Vec::new();
         let value_type = value.get_type()?;
 
@@ -97,76 +74,294 @@ impl Cache {
             let utf8 = js_str.into_utf8()?;
             bytes.push(2); // Tag: String
             bytes.extend_from_slice(utf8.as_slice());
+        } else if value_type == ValueType::Number {
+            let num = value.coerce_to_number()?;
+            let val = num.get_double()?;
+            if val.fract() == 0.0 && val >= (i64::MIN as f64) && val <= (i64::MAX as f64) {
+                bytes.push(4); // Tag: i64
+                bytes.extend_from_slice(&(val as i64).to_ne_bytes());
+            } else {
+                let json_val = serde_json::Value::Number(serde_json::Number::from_f64(val).unwrap());
+                let serialized = serde_json::to_vec(&json_val)
+                    .map_err(|e| napi::Error::new(napi::Status::InvalidArg, e.to_string()))?;
+                bytes.push(3); // Tag: JSON
+                bytes.extend_from_slice(&serialized);
+            }
         } else {
-            // Treat as JSON
             let json_val: serde_json::Value = env.from_js_value(value)?;
             let serialized = serde_json::to_vec(&json_val)
                 .map_err(|e| napi::Error::new(napi::Status::InvalidArg, e.to_string()))?;
             bytes.push(3); // Tag: JSON
             bytes.extend_from_slice(&serialized);
         }
+        Ok(bytes)
+    }
 
-        let ttl = ttl_ms.map(|ms| ms as u64);
-        let mut lock = self.inner.lock();
-        let old_bytes = lock.set(&key, bytes, ttl);
-
-        if let Some(bytes) = old_bytes {
-            if bytes.is_empty() {
-                return Ok(env.get_undefined()?.into_unknown());
+    fn deserialize_value(&self, env: Env, bytes: Vec<u8>) -> Result<JsUnknown> {
+        if bytes.is_empty() {
+            return Ok(env.get_undefined()?.into_unknown());
+        }
+        let tag = bytes[0];
+        let payload = &bytes[1..];
+        match tag {
+            1 => {
+                let js_buf = env.create_buffer_copy(payload)?;
+                Ok(js_buf.into_unknown())
             }
-            let tag = bytes[0];
-            let payload = &bytes[1..];
-            match tag {
-                1 => {
-                    let js_buf = env.create_buffer_copy(payload)?;
-                    Ok(js_buf.into_unknown())
-                }
-                2 => {
-                    let s = std::str::from_utf8(payload)
-                        .map_err(|e| napi::Error::new(napi::Status::StringExpected, e.to_string()))?;
-                    let js_str = env.create_string(s)?;
-                    Ok(js_str.into_unknown())
-                }
-                3 => {
-                    let json_val: serde_json::Value = serde_json::from_slice(payload)
-                        .map_err(|e| napi::Error::new(napi::Status::InvalidArg, e.to_string()))?;
-                    let parsed = env.to_js_value(&json_val)?;
-                    Ok(parsed)
+            2 => {
+                let s = std::str::from_utf8(payload)
+                    .map_err(|e| napi::Error::new(napi::Status::StringExpected, e.to_string()))?;
+                let js_str = env.create_string(s)?;
+                Ok(js_str.into_unknown())
+            }
+            3 => {
+                let json_val: serde_json::Value = serde_json::from_slice(payload)
+                    .map_err(|e| napi::Error::new(napi::Status::InvalidArg, e.to_string()))?;
+                let parsed = env.to_js_value(&json_val)?;
+                Ok(parsed)
+            }
+            4 => {
+                if payload.len() == 8 {
+                    let val = i64::from_ne_bytes(payload.try_into().unwrap());
+                    let js_num = env.create_double(val as f64)?;
+                    Ok(js_num.into_unknown())
+                } else {
+                    Err(napi::Error::new(napi::Status::InvalidArg, "Counter value is corrupted"))
                 }
-                _ => Err(napi::Error::new(napi::Status::InvalidArg, "Invalid data type tag in cache storage")),
             }
+            _ => Err(napi::Error::new(napi::Status::InvalidArg, "Invalid data type tag in cache storage")),
+        }
+    }
+}
+
+#[napi]
+impl Cache {
+    #[napi]
+    pub fn get(&self, env: Env, key: String) -> Result<JsUnknown> {
+        let shard_lock = self.get_shard(&key)?;
+        let mut lock = shard_lock.lock();
+        let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+        
+        if let Some(bytes) = cache.get(&key) {
+            self.deserialize_value(env, bytes)
         } else {
             Ok(env.get_undefined()?.into_unknown())
         }
     }
 
     #[napi]
-    pub fn delete(&self, key: String) -> bool {
-        let mut lock = self.inner.lock();
-        lock.delete(&key)
+    pub fn peek(&self, env: Env, key: String) -> Result<JsUnknown> {
+        let shard_lock = self.get_shard(&key)?;
+        let mut lock = shard_lock.lock();
+        let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+        
+        if let Some(bytes) = cache.peek(&key) {
+            self.deserialize_value(env, bytes)
+        } else {
+            Ok(env.get_undefined()?.into_unknown())
+        }
     }
 
     #[napi]
-    pub fn clear(&self) {
-        let mut lock = self.inner.lock();
-        lock.clear();
+    pub fn has(&self, key: String) -> Result<bool> {
+        let shard_lock = self.get_shard(&key)?;
+        let mut lock = shard_lock.lock();
+        let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+        Ok(cache.has(&key))
     }
 
     #[napi]
-    pub fn stats(&self) -> CacheStatsJs {
-        let lock = self.inner.lock();
-        let stats = lock.stats();
-        CacheStatsJs {
-            hits: stats.hits as f64,
-            misses: stats.misses as f64,
-            capacity: stats.capacity as f64,
-            size: stats.size as f64,
+    pub fn set(&self, env: Env, key: String, value: JsUnknown, ttl_ms: Option<f64>) -> Result<JsUnknown> {
+        let bytes = self.serialize_value(env, value)?;
+        let ttl = ttl_ms.map(|ms| ms as u64);
+        
+        let shard_lock = self.get_shard(&key)?;
+        let mut lock = shard_lock.lock();
+        let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+        
+        let old_bytes = cache.set(&key, bytes, ttl);
+        if let Some(bytes) = old_bytes {
+            self.deserialize_value(env, bytes)
+        } else {
+            Ok(env.get_undefined()?.into_unknown())
         }
     }
 
     #[napi]
-    pub fn keys(&self) -> Vec<String> {
-        let lock = self.inner.lock();
-        lock.keys()
+    pub fn touch(&self, key: String, ttl_ms: Option<f64>) -> Result<bool> {
+        let ttl = ttl_ms.map(|ms| ms as u64);
+        let shard_lock = self.get_shard(&key)?;
+        let mut lock = shard_lock.lock();
+        let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+        Ok(cache.touch(&key, ttl))
+    }
+
+    #[napi]
+    pub fn delete(&self, key: String) -> Result<bool> {
+        let shard_lock = self.get_shard(&key)?;
+        let mut lock = shard_lock.lock();
+        let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+        Ok(cache.delete(&key))
+    }
+
+    #[napi]
+    pub fn clear(&self) -> Result<()> {
+        for shard_lock in &self.shards {
+            let mut lock = shard_lock.lock();
+            let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+            cache.clear();
+        }
+        Ok(())
+    }
+
+    #[napi]
+    pub fn stats(&self) -> Result<CacheStatsJs> {
+        let mut total_hits = 0.0;
+        let mut total_misses = 0.0;
+        let mut total_capacity = 0.0;
+        let mut total_size = 0.0;
+        let mut total_bytes = 0.0;
+        
+        for shard_lock in &self.shards {
+            let lock = shard_lock.lock();
+            let cache = lock.as_ref().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+            let stats = cache.stats();
+            total_hits += stats.hits as f64;
+            total_misses += stats.misses as f64;
+            total_capacity += stats.capacity as f64;
+            total_size += stats.size as f64;
+            total_bytes += stats.bytes_used as f64;
+        }
+        
+        Ok(CacheStatsJs {
+            hits: total_hits,
+            misses: total_misses,
+            capacity: total_capacity,
+            size: total_size,
+            bytes_used: total_bytes,
+        })
+    }
+
+    #[napi]
+    pub fn keys(&self) -> Result<Vec<String>> {
+        let mut all_keys = Vec::new();
+        for shard_lock in &self.shards {
+            let lock = shard_lock.lock();
+            let cache = lock.as_ref().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+            all_keys.extend(cache.keys());
+        }
+        Ok(all_keys)
+    }
+
+    #[napi]
+    pub fn dispose(&self) -> Result<()> {
+        for shard_lock in &self.shards {
+            let mut lock = shard_lock.lock();
+            *lock = None;
+        }
+        Ok(())
+    }
+
+    #[napi]
+    pub fn increment(&self, env: Env, key: String, delta: i64, ttl_ms: Option<f64>) -> Result<JsUnknown> {
+        let shard_lock = self.get_shard(&key)?;
+        let mut lock = shard_lock.lock();
+        let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+        
+        let mut current_val = 0i64;
+        
+        if let Some(bytes) = cache.get(&key) {
+            if !bytes.is_empty() {
+                let tag = bytes[0];
+                let payload = &bytes[1..];
+                match tag {
+                    4 => {
+                        if payload.len() == 8 {
+                            current_val = i64::from_ne_bytes(payload.try_into().unwrap());
+                        } else {
+                            return Err(napi::Error::new(napi::Status::InvalidArg, "Counter value is corrupted"));
+                        }
+                    }
+                    3 => {
+                        let json_val: serde_json::Value = serde_json::from_slice(payload)
+                            .map_err(|e| napi::Error::new(napi::Status::InvalidArg, e.to_string()))?;
+                        if let Some(n) = json_val.as_i64() {
+                            current_val = n;
+                        } else {
+                            return Err(napi::Error::new(napi::Status::InvalidArg, "Value is not a valid 64-bit integer"));
+                        }
+                    }
+                    _ => return Err(napi::Error::new(napi::Status::InvalidArg, "Value is not a numeric counter")),
+                }
+            }
+        }
+        
+        let new_val = current_val.wrapping_add(delta);
+        let mut new_bytes = Vec::with_capacity(9);
+        new_bytes.push(4); // Tag 4: i64
+        new_bytes.extend_from_slice(&new_val.to_ne_bytes());
+        
+        let ttl = ttl_ms.map(|ms| ms as u64);
+        cache.set(&key, new_bytes, ttl);
+        
+        let js_num = env.create_double(new_val as f64)?;
+        Ok(js_num.into_unknown())
+    }
+
+    #[napi]
+    pub fn decrement(&self, env: Env, key: String, delta: i64, ttl_ms: Option<f64>) -> Result<JsUnknown> {
+        self.increment(env, key, -delta, ttl_ms)
+    }
+
+    #[napi]
+    pub fn mget(&self, env: Env, keys: Vec<String>) -> Result<JsObject> {
+        let mut result_obj = env.create_object()?;
+        for key in keys {
+            let shard_lock = self.get_shard(&key)?;
+            let mut lock = shard_lock.lock();
+            let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+            
+            if let Some(bytes) = cache.get(&key) {
+                let val = self.deserialize_value(env, bytes)?;
+                result_obj.set(&key, val)?;
+            }
+        }
+        Ok(result_obj)
+    }
+
+    #[napi]
+    pub fn mset(&self, env: Env, entries: JsObject, ttl_ms: Option<f64>) -> Result<()> {
+        let keys_array = entries.get_property_names()?;
+        let len = keys_array.get_array_length()?;
+        let ttl = ttl_ms.map(|ms| ms as u64);
+        
+        for i in 0..len {
+            let key_unknown: JsUnknown = keys_array.get_element(i)?;
+            let key_str = key_unknown.coerce_to_string()?;
+            let key = key_str.into_utf8()?.into_owned()?;
+            
+            let val: JsUnknown = entries.get_named_property(&key)?;
+            let bytes = self.serialize_value(env, val)?;
+            
+            let shard_lock = self.get_shard(&key)?;
+            let mut lock = shard_lock.lock();
+            let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+            cache.set(&key, bytes, ttl);
+        }
+        Ok(())
+    }
+
+    #[napi]
+    pub fn mdelete(&self, keys: Vec<String>) -> Result<u32> {
+        let mut count = 0;
+        for key in keys {
+            let shard_lock = self.get_shard(&key)?;
+            let mut lock = shard_lock.lock();
+            let cache = lock.as_mut().ok_or_else(|| napi::Error::new(napi::Status::GenericFailure, "Cache has been disposed"))?;
+            if cache.delete(&key) {
+                count += 1;
+            }
+        }
+        Ok(count)
     }
 }

package/tests/index.test.js

@@ -1,6 +1,6 @@
 const test = require('node:test');
 const assert = require('node:assert');
-const { CacheManager } = require('../index.js'); // NAPI generated file
+const { CacheManager } = require('../index.js');
 
 test('CacheManager - isolated caches', () => {
   const manager = new CacheManager();
@@ -44,7 +44,8 @@ test('Cache - DataType Preservation (String, Buffer, JSON Object)', () => {
 
 test('Cache Policies - LRU eviction', () => {
   const manager = new CacheManager();
-  const cache = manager.createCache('lru-evict', { policy: 'lru', capacity: 3 });
+  // Set shards: 1 to ensure a single eviction pool of size 3
+  const cache = manager.createCache('lru-evict', { policy: 'lru', capacity: 3, shards: 1 });
 
   cache.set('a', 1);
   cache.set('b', 2);
@@ -64,7 +65,8 @@ test('Cache Policies - LRU eviction', () => {
 
 test('Cache Policies - ARC adaptation & eviction', () => {
   const manager = new CacheManager();
-  const cache = manager.createCache('arc-evict', { policy: 'arc', capacity: 4 });
+  // Set shards: 1 to ensure a single eviction pool of size 4
+  const cache = manager.createCache('arc-evict', { policy: 'arc', capacity: 4, shards: 1 });
 
   // Warm up ARC
   cache.set('a', 1);
@@ -80,22 +82,20 @@ test('Cache Policies - ARC adaptation & eviction', () => {
   // Insert e, which triggers replace. Since |T1| > p, it evicts from T1 (evicting c or d)
   cache.set('e', 5);
 
-  // Check stats
   const stats = cache.stats();
   assert.strictEqual(stats.size, 4);
 });
 
 test('Cache Policies - W-TinyLFU eviction competition', () => {
   const manager = new CacheManager();
-  // W-TinyLFU capacity 10
-  const cache = manager.createCache('tinylfu-evict', { policy: 'tinylfu', capacity: 10 });
+  // Set shards: 1 to ensure a single eviction pool of size 10
+  const cache = manager.createCache('tinylfu-evict', { policy: 'tinylfu', capacity: 10, shards: 1 });
 
   // Fill cache
   for (let i = 0; i < 12; i++) {
     cache.set(`key-${i}`, i);
   }
 
-  // Check that size is limited to capacity
   const stats = cache.stats();
   assert.strictEqual(stats.capacity, 10);
   assert.ok(stats.size <= 10);
@@ -133,3 +133,130 @@ test('Cache - keys() and delete()', () => {
 
   assert.deepStrictEqual(cache.keys().sort(), ['a', 'c']);
 });
+
+test('Cache - touch(key, ttl)', async () => {
+  const manager = new CacheManager();
+  const cache = manager.createCache('lru-touch', { policy: 'lru', capacity: 10 });
+
+  cache.set('a', 'value', 15); // 15ms TTL
+  assert.strictEqual(cache.touch('a', 1000), true); // Extend to 1000ms
+
+  // Wait 30ms. It would normally have expired, but should remain due to touch
+  await new Promise((resolve) => setTimeout(resolve, 30));
+  assert.strictEqual(cache.get('a'), 'value');
+  
+  assert.strictEqual(cache.touch('non-existent', 100), false);
+});
+
+test('Cache - Atomic Counters (increment / decrement)', () => {
+  const manager = new CacheManager();
+  const cache = manager.createCache('lru-counters', { policy: 'lru', capacity: 10 });
+
+  // Init and increment
+  assert.strictEqual(cache.increment('counter', 5), 5);
+  assert.strictEqual(cache.increment('counter', 2), 7);
+  assert.strictEqual(cache.get('counter'), 7);
+
+  // Decrement
+  assert.strictEqual(cache.decrement('counter', 3), 4);
+  assert.strictEqual(cache.decrement('counter', 1), 3);
+  assert.strictEqual(cache.get('counter'), 3);
+});
+
+test('Cache - Batch Operations (mget / mset / mdelete)', () => {
+  const manager = new CacheManager();
+  const cache = manager.createCache('lru-batch', { policy: 'lru', capacity: 10 });
+
+  // mset
+  cache.mset({ a: 1, b: 'hello', c: { x: 9 } });
+
+  // mget
+  const retrieved = cache.mget(['a', 'b', 'c', 'd']);
+  assert.deepStrictEqual(retrieved, {
+    a: 1,
+    b: 'hello',
+    c: { x: 9 },
+  });
+
+  // mdelete
+  assert.strictEqual(cache.mdelete(['a', 'b', 'z']), 2); // 'a' and 'b' deleted, 'z' not found
+  assert.strictEqual(cache.get('a'), undefined);
+  assert.deepStrictEqual(cache.get('c'), { x: 9 });
+});
+
+test('Cache - has() and peek()', () => {
+  const manager = new CacheManager();
+  const cache = manager.createCache('lru-has-peek', { policy: 'lru', capacity: 3, shards: 1 });
+
+  cache.set('a', 1);
+  cache.set('b', 2);
+  cache.set('c', 3);
+
+  // has
+  assert.strictEqual(cache.has('a'), true);
+  assert.strictEqual(cache.has('z'), false);
+
+  // peek does not update eviction order
+  assert.strictEqual(cache.peek('a'), 1);
+  cache.set('d', 4); // Should evict 'a' (the tail, since peek didn't promote it!)
+  assert.strictEqual(cache.get('a'), undefined);
+});
+
+test('Cache - getOrSet() Coalescing', async () => {
+  const manager = new CacheManager();
+  const cache = manager.createCache('lru-getorset', { policy: 'lru', capacity: 10 });
+
+  let calls = 0;
+  const factory = () => {
+    calls++;
+    return new Promise((resolve) => setTimeout(() => resolve('computed'), 20));
+  };
+
+  // Trigger concurrent calls
+  const [res1, res2] = await Promise.all([
+    cache.getOrSet('key', factory),
+    cache.getOrSet('key', factory),
+  ]);
+
+  assert.strictEqual(res1, 'computed');
+  assert.strictEqual(res2, 'computed');
+  assert.strictEqual(calls, 1); // Factory must only be called once!
+
+  assert.strictEqual(cache.get('key'), 'computed');
+});
+
+test('Cache - maxBytes Memory Eviction Limit', () => {
+  const manager = new CacheManager();
+  // Set capacity = 100, shards = 1, but maxBytes = 35.
+  const cache = manager.createCache('lru-bytes', {
+    policy: 'lru',
+    capacity: 100,
+    maxBytes: 35,
+    shards: 1
+  });
+
+  cache.set('k1', '1234567890'); // key len 2 + value len 10 = 12 bytes + 1 tag = 13 bytes.
+  cache.set('k2', '1234567890'); // key len 2 + value len 10 = 12 bytes + 1 tag = 13 bytes. Total = 26 bytes.
+  
+  assert.strictEqual(cache.get('k1'), '1234567890');
+  assert.strictEqual(cache.get('k2'), '1234567890');
+
+  // Insert k3. Total would be 39 bytes (exceeds 35 maxBytes). Should evict k1.
+  cache.set('k3', '1234567890');
+
+  assert.strictEqual(cache.get('k1'), undefined);
+  assert.strictEqual(cache.get('k2'), '1234567890');
+  assert.strictEqual(cache.get('k3'), '1234567890');
+});
+
+test('Cache - Deterministic dispose()', () => {
+  const manager = new CacheManager();
+  const cache = manager.createCache('lru-dispose', { policy: 'lru', capacity: 10 });
+
+  cache.set('a', 1);
+  cache.dispose();
+
+  assert.throws(() => {
+    cache.get('a');
+  }, /Cache has been disposed/);
+});