@asamuzakjp/generational-cache 1.0.0 → 2.0.0

package/README.md

@@ -14,7 +14,7 @@ A lightweight, **generational pseudo-LRU (Least Recently Used) cache** with stri
 2.  **Promotion**: If you `get` an item that exists in the `old` generation, it is promoted to the `current` generation to ensure it stays in the cache longer.
 3.  **Generation Swapping**: Once the `current` generation reaches the boundary size ($max / 2$), the `old` generation is discarded, the `current` generation becomes the `old` generation, and a new empty `current` generation is created.
 
-This "pseudo-LRU" approach avoids the overhead of updating timestamps or complex linked list pointers on every single access.
+This "pseudo-LRU" approach avoids the overhead of updating timestamps or linked list pointers on every access. While not a drop-in replacement for standard LRU caches, it prioritizes raw throughput over strict eviction ordering.
 
 ## Installation
 ```bash
@@ -113,33 +113,18 @@ Benchmarks are divided into two states to simulate real-world conditions:
 | **Hit Rate** | 78.30% | **100.00%** | **100.00%** | **100.00%** |
 | **Throughput** | 10,365,916 ops/sec | 40,832,993 ops/sec | 40,950,040 ops/sec | **48,426,150 ops/sec** |
 
+### 5. Cyclic Access (Max Size = 4,096 / Working Set = 5,000)
+| Metric | **GenerationalCache** | LRUCache | QuickLRU | Mnemonist |
+| :--- | :--- | :--- | :--- | :--- |
+| **Hit Rate** | 18.06% | 18.06% | **99.98%** | 18.06% |
+| **Throughput** | **13,192,612 ops/sec** | 9,672,115 ops/sec | 10,188,487 ops/sec | 7,564,868 ops/sec |
+
 ## Key Characteristics
 
 * **High Eviction Efficiency**: `GenerationalCache` demonstrates strong throughput during high-turnover workloads, maintaining a performance margin compared to standard LRU designs in large-scale eviction scenarios.
 * **Predictable Scalability**: While other libraries may experience performance degradation as cache size increases, `GenerationalCache` maintains consistent throughput due to its generational swap mechanism.
 * **Balanced Read/Write**: It provides stable and competitive performance across all basic operations (`get`, `set`), making it suitable for both read-heavy and write-heavy environments.
-* **Trade-offs**: In cyclic access patterns where the working set is greater than `max / 2` but smaller than `max`, `GenerationalCache` will experience frequent generation swaps and cache misses.
-
-## Conclusion: When to Use GenerationalCache
-
-`GenerationalCache` is not a one-size-fits-all solution.
-Its effectiveness depends on the ratio between your **Working Set Size ($W$)** and the **Cache Capacity ($S$)**.
-
-### 1. High-Turnover Environments ($W \ge S$)
-This is the primary use case for `GenerationalCache`.
-When your working set is larger than the cache size, evictions occur constantly.
-* **Use case**: High-traffic APIs, memory-constrained containers, or streaming data where maintaining high system throughput is more critical than a perfect hit rate.
-
-### 2. Over-Provisioned Environments ($S \ge 2W$)
-If you have abundant memory, `GenerationalCache` operates as an ultra-low-overhead "passive" cache.
-* **Use case**: Static master data or "hot" lookups where you want to minimize CPU cycles and maintain consistent sub-microsecond latency without any internal pointer updates.
-
-### Avoid ($S/2 < W < S$)
-Be cautious when your working set is larger than half the cache but smaller than the total capacity.
-In this specific range, a standard LRU might achieve a 100% hit rate, while `GenerationalCache` will experience periodic misses due to generation swaps.
-
-* **For Stability**: Set **$S \ge 2W$** (Eliminate swap misses)
-* **For Throughput**: Set **$S < W$** (Maximize eviction speed)
+* **Trade-offs**: In cyclic access patterns where the working set is greater than `max / 2` but smaller than `max`, `GenerationalCache` will experience frequent generation swaps and cache misses. To maximize the performance benefits of `GenerationalCache`, it is often better to keep the `max` size small enough to allow some evictions, rather than trying to fit the entire working set (See 4 & 5).
 
 ## License
 

package/package.json

@@ -31,15 +31,15 @@
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-regexp": "^3.1.0",
     "eslint-plugin-unicorn": "^64.0.0",
-    "globals": "^17.5.0",
+    "globals": "^17.6.0",
     "lru-cache": "^11.3.5",
     "mitata": "^1.0.34",
-    "mnemonist": "^0.40.3",
+    "mnemonist": "^0.40.4",
     "mocha": "^11.7.5",
     "neostandard": "^0.13.0",
-    "prettier": "^3.8.2",
+    "prettier": "^3.8.3",
     "quick-lru": "^7.3.0",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   },
   "overrides": {
     "c8": {
@@ -48,6 +48,9 @@
     "eslint": {
       "brace-expansion": "^1.1.13"
     },
+    "mocha": {
+      "diff": "^8.0.3"
+    },
     "serialize-javascript": "^7.0.4"
   },
   "scripts": {
@@ -59,7 +62,7 @@
     "tsc": "node scripts/index clean --dir=types -i && npx tsc"
   },
   "engines": {
-    "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+    "node": "^22.13.0 || >=24.0.0"
   },
-  "version": "1.0.0"
+  "version": "2.0.0"
 }