offheap 0.1.0 → 0.2.0

package/benchmarks/crossover_bench.js

@@ -0,0 +1,139 @@
+const { LRUCache } = require('lru-cache');
+const { CacheManager } = require('../index.js');
+
+function formatMemory(bytes) {
+  return (bytes / 1024 / 1024).toFixed(2) + ' MB';
+}
+
+function runMeasurement(payloadSize, entryCount) {
+  console.log(`\n------------------------------------------------------------`);
+  console.log(`Payload Size: ${payloadSize} bytes | Total Entries: ${entryCount}`);
+  console.log(`------------------------------------------------------------`);
+
+  const keys = Array.from({ length: entryCount }, (_, i) => `key-${i}`);
+  const val = 'a'.repeat(payloadSize);
+
+  // 1. Measure Pure Map
+  global.gc && global.gc();
+  const memBeforeMap = process.memoryUsage().heapUsed;
+  const map = new Map();
+  const startMapSet = Date.now();
+  for (let i = 0; i < entryCount; i++) {
+    map.set(keys[i], val);
+  }
+  const mapSetTime = Date.now() - startMapSet;
+
+  const startMapGet = Date.now();
+  for (let i = 0; i < entryCount; i++) {
+    const res = map.get(keys[i]);
+  }
+  const mapGetTime = Date.now() - startMapGet;
+  const memAfterMap = process.memoryUsage().heapUsed;
+  const mapMem = Math.max(0, memAfterMap - memBeforeMap);
+
+  map.clear();
+  global.gc && global.gc();
+
+  // 2. Measure lru-cache (JS)
+  global.gc && global.gc();
+  const memBeforeLru = process.memoryUsage().heapUsed;
+  const jsLru = new LRUCache({ max: entryCount });
+  const startLruSet = Date.now();
+  for (let i = 0; i < entryCount; i++) {
+    jsLru.set(keys[i], val);
+  }
+  const lruSetTime = Date.now() - startLruSet;
+
+  const startLruGet = Date.now();
+  for (let i = 0; i < entryCount; i++) {
+    const res = jsLru.get(keys[i]);
+  }
+  const lruGetTime = Date.now() - startLruGet;
+  const memAfterLru = process.memoryUsage().heapUsed;
+  const lruMem = Math.max(0, memAfterLru - memBeforeLru);
+
+  jsLru.clear();
+  global.gc && global.gc();
+
+  // 3. Measure OffHeap
+  global.gc && global.gc();
+  const memBeforeOffheap = process.memoryUsage().heapUsed;
+  const manager = new CacheManager();
+  const offheap = manager.createCache('crossover', { policy: 'lru', capacity: entryCount, shards: 8 });
+  const startOffheapSet = Date.now();
+  for (let i = 0; i < entryCount; i++) {
+    offheap.set(keys[i], val);
+  }
+  const offheapSetTime = Date.now() - startOffheapSet;
+
+  const startOffheapGet = Date.now();
+  for (let i = 0; i < entryCount; i++) {
+    const res = offheap.get(keys[i]);
+  }
+  const offheapGetTime = Date.now() - startOffheapGet;
+  const memAfterOffheap = process.memoryUsage().heapUsed;
+  const offheapMem = Math.max(0, memAfterOffheap - memBeforeOffheap);
+
+  offheap.dispose();
+  manager.dispose();
+  global.gc && global.gc();
+
+  console.log(`Pure Map       | Set: ${mapSetTime}ms | Get: ${mapGetTime}ms | Heap: ${formatMemory(mapMem)}`);
+  console.log(`lru-cache      | Set: ${lruSetTime}ms | Get: ${lruGetTime}ms | Heap: ${formatMemory(lruMem)}`);
+  console.log(`OffHeap        | Set: ${offheapSetTime}ms | Get: ${offheapGetTime}ms | Heap: ${formatMemory(offheapMem)}`);
+  
+  return {
+    payloadSize,
+    entryCount,
+    map: { set: mapSetTime, get: mapGetTime, mem: mapMem },
+    lru: { set: lruSetTime, get: lruGetTime, mem: lruMem },
+    offheap: { set: offheapSetTime, get: offheapGetTime, mem: offheapMem },
+  };
+}
+
+async function run() {
+  console.log('Running OffHeap vs Map vs lru-cache Crossover Benchmark...');
+  console.log('(Note: Run with node --expose-gc to get accurate heap measurements)');
+
+  const results = [];
+  
+  // Test 1: Small payload, medium count (low V8 GC pressure)
+  results.push(runMeasurement(100, 30000));
+
+  // Test 2: Medium payload, medium count
+  results.push(runMeasurement(2048, 30000));
+
+  // Test 3: Large payload, large count (high V8 GC pressure)
+  results.push(runMeasurement(10240, 50000));
+
+  console.log('\n\n========================= CROSSOVER SUMMARY =========================');
+  console.log('| Payload | Entries | Engine   | Set Time | Get Time | V8 Heap Used |');
+  console.log('|---------|---------|----------|----------|----------|--------------|');
+  for (const r of results) {
+    const fmtSize = r.payloadSize >= 1024 ? `${r.payloadSize / 1024} KB` : `${r.payloadSize} B`;
+    console.log(`| ${fmtSize.padEnd(7)} | ${String(r.entryCount).padEnd(7)} | Pure Map | ${String(r.map.set).padEnd(6)}ms | ${String(r.map.get).padEnd(6)}ms | ${formatMemory(r.map.mem).padEnd(12)} |`);
+    console.log(`|         |         | lru-ca.. | ${String(r.lru.set).padEnd(6)}ms | ${String(r.lru.get).padEnd(6)}ms | ${formatMemory(r.lru.mem).padEnd(12)} |`);
+    console.log(`|         |         | OffHeap  | ${String(r.offheap.set).padEnd(6)}ms | ${String(r.offheap.get).padEnd(6)}ms | ${formatMemory(r.offheap.mem).padEnd(12)} |`);
+    console.log('|---------|---------|----------|----------|----------|--------------|');
+  }
+
+  console.log('\n========================= V8 HEAP COMPARISON GRAPH =========================');
+  console.log('Memory usage at 50k entries of 10 KB:');
+  const r3 = results[2];
+  const maxMem = Math.max(r3.map.mem, r3.lru.mem, r3.offheap.mem);
+  const getBar = (bytes) => {
+    if (maxMem === 0) return ' (0.00 MB)';
+    const pct = bytes / maxMem;
+    const len = Math.round(pct * 40);
+    return '█'.repeat(len) + ` (${formatMemory(bytes)})`;
+  };
+  console.log(`Pure Map  : ${getBar(r3.map.mem)}`);
+  console.log(`lru-cache : ${getBar(r3.lru.mem)}`);
+  console.log(`OffHeap   : ${getBar(r3.offheap.mem)}`);
+  console.log('\nCONCLUSION:');
+  console.log('OffHeap keeps the V8 heap usage at virtually 0 MB regardless of cache size and payload size!');
+  console.log('For simple small-map reads, Map/lru-cache are faster in microbenchmarks due to zero-copy direct V8 references.');
+  console.log('However, once cache size exceeds ~50MB or entries exceed ~50,000, OffHeap prevents high GC pauses and memory bloating.');
+}
+
+run().catch(console.error);

package/docs/.vitepress/config.js

@@ -0,0 +1,35 @@
+export default {
+  title: 'OffHeap',
+  description: 'High-performance off-heap caching framework for Node.js',
+  themeConfig: {
+    logo: '/logo.png',
+    nav: [
+      { text: 'Guide', link: '/guide/getting-started' },
+      { text: 'API Reference', link: '/guide/api' },
+      { text: 'Benchmarks', link: '/guide/benchmarks' }
+    ],
+    sidebar: [
+      {
+        text: 'Getting Started',
+        items: [
+          { text: 'Introduction', link: '/guide/getting-started' },
+          { text: 'Architecture & Design', link: '/guide/architecture' }
+        ]
+      },
+      {
+        text: 'Reference',
+        items: [
+          { text: 'API Reference', link: '/guide/api' },
+          { text: 'Benchmarks & Telemetry', link: '/guide/benchmarks' }
+        ]
+      }
+    ],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/ryangustav/OffHeap' }
+    ],
+    footer: {
+      message: 'Released under the MIT and Apache 2.0 Licenses.',
+      copyright: 'Copyright © 2026 Ryan Gustavo & OffHeap Contributors'
+    }
+  }
+}

package/docs/guide/api.md

@@ -0,0 +1,216 @@
+# API Reference
+
+All methods exported by the native addon execute **synchronously** to avoid microtask queue scheduling overhead in Node.js, ensuring maximum throughput. Custom high-level utilities like `getOrSet` seamlessly support both synchronous and asynchronous operations.
+
+---
+
+## `CacheManager`
+
+The central manager responsible for provisioning and isolating individual caches.
+
+```javascript
+const { CacheManager } = require('offheap');
+const manager = new CacheManager();
+```
+
+### `new CacheManager()`
+Instantiates a new central cache manager.
+* **Returns**: `CacheManager` instance.
+
+### `createCache(name, config)`
+Creates and returns an isolated cache instance.
+```javascript
+const cache = manager.createCache('products', {
+  policy: 'tinylfu',
+  capacity: 10000,
+  shards: 16,
+  maxBytes: 100 * 1024 * 1024 // 100 MB byte-capacity limit
+});
+```
+* **Parameters**:
+  * `name` (`string`): Unique name/namespace for the cache.
+  * `config` (`CacheConfig`):
+    * `policy` (`"lru" | "arc" | "tinylfu"`): The eviction policy.
+    * `capacity` (`number`): The maximum number of entries allowed in the cache.
+    * `shards` (`number`, *optional*): Number of internal locks shards. High concurrency workloads benefit from larger shard numbers (e.g. 16 or 32). Default: `8`.
+    * `maxBytes` (`number`, *optional*): The maximum memory size of keys and values combined in bytes. When this threshold is crossed, entries are evicted according to the active policy.
+* **Returns**: `Cache` instance.
+* **Throws**: Error if a cache with the specified `name` already exists.
+
+### `getCache(name)`
+Retrieves an existing cache by name.
+* **Parameters**:
+  * `name` (`string`): The cache namespace.
+* **Returns**: `Cache | null` (returns `null` if the cache does not exist).
+
+### `deleteCache(name)`
+Deletes a cache instance from the manager.
+* **Parameters**:
+  * `name` (`string`): The cache namespace to delete.
+* **Returns**: `boolean` (true if the cache was successfully deleted).
+
+### `clear()`
+Deletes all cache instances managed by this instance.
+* **Returns**: `void`
+
+### `dispose()`
+Releases all cache instances immediately, releasing all underlying native memory.
+* **Returns**: `void`
+
+---
+
+## `Cache`
+
+An isolated, thread-safe cache instance.
+
+### `get(key)`
+Retrieves a value from the cache.
+```javascript
+const value = cache.get('prod_101');
+```
+* **Parameters**:
+  * `key` (`string`): The lookup key.
+* **Returns**: `Buffer | string | object | number | boolean | undefined`
+  * Returns `Buffer` if the value was stored as a `Buffer` or `Uint8Array`.
+  * Returns `string` if the value was stored as a string.
+  * Returns `object | array | number | boolean` if the value was stored as a JSON-serializable type.
+  * Returns `undefined` if the key is missing or expired.
+
+### `set(key, value, ttl_ms?)`
+Stores an entry in the cache. If the key already exists, its value is overwritten.
+```javascript
+cache.set('key', { data: 'test' }, 60000); // Stores object with 60s TTL
+```
+* **Parameters**:
+  * `key` (`string`): The entry key.
+  * `value` (`Buffer | Uint8Array | string | any`): The payload to store.
+  * `ttl_ms` (`number`, *optional*): The time-to-live in milliseconds. If omitted, the entry has no expiry.
+* **Returns**: `Buffer | string | object | undefined` (returns the old value if it was overwritten, or `undefined`).
+
+### `has(key)`
+Checks if a key exists in the cache and is not expired, without deserializing the value.
+```javascript
+if (cache.has('auth_session')) { ... }
+```
+* **Parameters**:
+  * `key` (`string`): Key to check.
+* **Returns**: `boolean` (true if key exists and is valid).
+
+### `peek(key)`
+Retrieves a value without updating the eviction metadata (e.g., LRU order or frequency sketch count). Useful for logging, debugging, or health checks.
+```javascript
+const debugVal = cache.peek('hot_key');
+```
+* **Parameters**:
+  * `key` (`string`): Key to retrieve.
+* **Returns**: `Buffer | string | object | undefined`
+
+### `touch(key, ttl_ms)`
+Renews or changes the Time-To-Live (TTL) of a key without re-writing the cached value.
+```javascript
+cache.touch('session_12', 30 * 60 * 1000); // Extend session by 30 min
+```
+* **Parameters**:
+  * `key` (`string`): Key to renew.
+  * `ttl_ms` (`number`, *optional*): New time-to-live in milliseconds. Use `undefined` to clear expiry.
+* **Returns**: `boolean` (true if the key existed and TTL was updated).
+
+### `increment(key, delta?, ttl_ms?)`
+Atomically increments a numeric counter key in memory (Tag 4). Ideal for rate limiters.
+```javascript
+const requestCount = cache.increment('rate_limit:ip_127.0.0.1', 1, 60000);
+```
+* **Parameters**:
+  * `key` (`string`): Key of the counter.
+  * `delta` (`number`, *optional*): Value to increment by. Default: `1`.
+  * `ttl_ms` (`number`, *optional*): Time-to-live for the counter if it's created.
+* **Returns**: `number` (the newly incremented counter value).
+
+### `decrement(key, delta?, ttl_ms?)`
+Atomically decrements a numeric counter key in memory (Tag 4).
+```javascript
+const remainingTokens = cache.decrement('api_tokens:user_88', 1);
+```
+* **Parameters**:
+  * `key` (`string`): Key of the counter.
+  * `delta` (`number`, *optional*): Value to decrement by. Default: `1`.
+  * `ttl_ms` (`number`, *optional*): Time-to-live.
+* **Returns**: `number` (the newly decremented counter value).
+
+### `mget(keys)`
+Performs a batch lookup for multiple keys in a single FFI boundary crossing, significantly improving throughput for multi-key lookups.
+```javascript
+const items = cache.mget(['k1', 'k2', 'k3']); // Returns { k1: val1, k2: val2 }
+```
+* **Parameters**:
+  * `keys` (`string[]`): Array of keys to retrieve.
+* **Returns**: `Record<string, any>` (Object mapping found keys to their deserialized values).
+
+### `mset(entries, ttl_ms?)`
+Performs a batch write of multiple key-value entries in a single FFI crossing.
+```javascript
+cache.mset({ a: 1, b: 'hello', c: Buffer.from([1, 2]) }, 60000);
+```
+* **Parameters**:
+  * `entries` (`Record<string, any>`): Object representing key-value entries to store.
+  * `ttl_ms` (`number`, *optional*): Time-to-live in milliseconds for all written entries.
+
+### `mdelete(keys)`
+Performs a batch delete of multiple keys in a single FFI crossing.
+```javascript
+const deletedCount = cache.mdelete(['a', 'b', 'c']);
+```
+* **Parameters**:
+  * `keys` (`string[]`): Array of keys to delete.
+* **Returns**: `number` (number of deleted keys).
+
+### `getOrSet(key, factory, ttl_ms?)`
+Implements a coalesced compute-on-miss cache access pattern. If two concurrent requests lookup the same missing key, they will await the **same** factory promise, preventing cache stampedes.
+```javascript
+const product = await cache.getOrSet('prod_101', async () => {
+  return await db.fetchProduct(101);
+}, 60000);
+```
+* **Parameters**:
+  * `key` (`string`): Key.
+  * `factory` (`() => any | Promise<any>`): A callback that computes the value if missing. Can return a Promise or a synchronous value.
+  * `ttl_ms` (`number`, *optional*): TTL in milliseconds for the computed value.
+* **Returns**: `any` (the cached value, or the resolved promise result).
+
+### `delete(key)`
+Deletes a specific key from the cache.
+* **Parameters**:
+  * `key` (`string`): The key to remove.
+* **Returns**: `boolean` (true if the key existed and was deleted).
+
+### `clear()`
+Removes all keys and resets stats for this cache instance.
+* **Returns**: `void`
+
+### `keys()`
+Returns an array of all active (non-expired) keys in the cache.
+* **Returns**: `string[]`
+
+### `stats()`
+Returns telemetry statistics for the cache.
+```javascript
+const telemetry = cache.stats();
+// Telemetry format:
+// {
+//   hits: 1452,
+//   misses: 92,
+//   capacity: 10000,
+//   size: 4210,
+//   bytesUsed: 541029 // total size of keys + values in bytes
+// }
+```
+* **Returns**: `CacheStats` object:
+  * `hits` (`number`): Number of successful read queries.
+  * `misses` (`number`): Number of queries for missing or expired keys.
+  * `capacity` (`number`): Sized capacity.
+  * `size` (`number`): Current count of active entries.
+  * `bytesUsed` (`number`): Current byte-capacity usage of stored keys and values.
+
+### `dispose()`
+Explicitly disposes of the native sub-caches immediately, freeing all of its memory back to the OS.
+* **Returns**: `void`

package/docs/guide/architecture.md

@@ -0,0 +1,58 @@
+# Architecture & Design
+
+```mermaid
+graph TD
+    JS[Node.js Application] <-->|NAPI-RS FFI| Bridge[Native Addon Bridge]
+    Bridge <--> Manager[CacheManager]
+    Manager -->|Instantiates| Cache1[Cache: 'Sessions']
+    Manager -->|Instantiates| Cache2[Cache: 'Products']
+    
+    subgraph Rust Memory Space (Off-Heap)
+        Cache2 --> Lock[Mutex Lock]
+        Lock --> Core[Cache Core Engine]
+        Core --> LRU[LRU Eviction]
+        Core --> ARC[ARC Eviction]
+        Core --> TinyLFU[W-TinyLFU Eviction]
+        
+        TinyLFU -.-> Sketch[4-bit Count-Min Sketch]
+    end
+```
+
+## V8 Heap vs. Off-Heap Caching
+
+In high-throughput Node.js applications, caching millions of elements in standard JavaScript memory (on-heap) introduces major performance bottlenecks. 
+
+### The Problem: V8 Garbage Collection Pauses
+The V8 engine tracks every JavaScript object, array, and string to manage memory. As the cache grows to hundreds of thousands or millions of active entries, the Garbage Collector must traverse an increasingly complex object graph during its mark-and-sweep phases. 
+
+This causes two major issues:
+1. **Stop-the-World Pauses**: Under heavy memory pressure, V8 triggers major GC collections that pause the main JavaScript execution thread, raising P99 latencies from milliseconds to several seconds.
+2. **Heap Memory Limits**: Node.js defaults to a maximum heap size (often 1.4 GB or 4 GB depending on system configuration). Exceeding this limit causes `FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory`.
+
+### The Solution: Off-Heap Memory
+OffHeap completely bypasses the JavaScript heap by allocating memory directly in the **Rust memory space** (off-heap). 
+
+- When you write an entry using `set()`, OffHeap serializes the JavaScript value and transfers the raw bytes across the Foreign Function Interface (FFI) boundary.
+- The raw bytes are stored in standard Rust heap allocations (`Vec<u8>`).
+- To the V8 Garbage Collector, the entire cache exists as a single native pointer. V8 does not traverse, inspect, or manage this memory, reducing major GC sweep times to virtually zero.
+
+---
+
+## Caching Policies
+
+### Least Recently Used (LRU)
+The baseline policy. It evicts the least recently accessed item when the cache capacity is reached. LRU is implemented using a hash map for $O(1)$ lookups and an index-based doubly linked list to track access order.
+
+### Adaptive Replacement Cache (ARC)
+ARC dynamically self-tunes between recency and frequency based on the active workload:
+* It maintains two double-linked lists: $L_1$ for recency (items seen once) and $L_2$ for frequency (items seen multiple times).
+* These lists are split into top sections (actual data stored in the cache) and bottom sections (ghost lists that only store keys of evicted items).
+* If a cache hit occurs in the recency ghost list ($B_1$), the cache adjusts its target allocation to favor recency. If a hit occurs in the frequency ghost list ($B_2$), it tunes the allocation to favor frequency.
+
+### Window TinyLFU (W-TinyLFU)
+While LRU is the industry default, it is highly susceptible to **sparse access bursts**—occasional database sweeps or batch operations can completely flush out highly valuable, frequently accessed data. W-TinyLFU resolves this:
+
+1. **Window LRU**: A small percentage of the total capacity (1%) is allocated to a Window LRU. All new writes enter this window first to capture short-term recency bursts.
+2. **Segmented LRU (SLRU) Main Cache**: The remaining 99% of the capacity is split into a **Probationary Segment** (20%) and a **Protected Segment** (80%). When an item in Probation is hit, it is promoted to the Protected segment.
+3. **TinyLFU Admission Filter**: When items overflow from the Window LRU, they compete to enter the Probationary segment. If the Probationary segment is full, the incoming item (candidate) is compared against the least recently used item in Probation (victim).
+4. **4-bit Count-Min Sketch**: OffHeap uses a memory-efficient Count-Min Sketch (with an aging decay mechanism) to track key frequencies. An item is only admitted to the main cache if its access frequency is strictly higher than the victim's. If not, the candidate is evicted immediately.

package/docs/guide/benchmarks.md

@@ -0,0 +1,48 @@
+# Benchmarks & Telemetry
+
+Below are the performance metrics comparing the throughput of the LRU, ARC, and W-TinyLFU cache engines.
+
+---
+
+## Performance Results
+
+### 1. Write Throughput (`SET` Operations)
+*10,000 capacity, 20,000 unique keys (forcing evictions)*
+
+| Engine | Operations/sec | Avg Latency | Margin | Samples |
+| :--- | :--- | :--- | :--- | :--- |
+| **OffHeap LRU** | **486,701 ops/s** | 2.05 μs | ±0.26% | 486,702 |
+| **OffHeap ARC** | **485,246 ops/s** | 2.06 μs | ±0.24% | 485,247 |
+| **OffHeap W-TinyLFU** | **375,509 ops/s** | 2.66 μs | ±0.30% | 375,510 |
+
+### 2. Read Throughput (`GET` Operations)
+*100% Cache Hits*
+
+| Engine | Operations/sec | Avg Latency | Margin | Samples |
+| :--- | :--- | :--- | :--- | :--- |
+| **OffHeap LRU** | **774,848 ops/s** | 1.29 μs | ±0.84% | 774,849 |
+| **OffHeap ARC** | **784,789 ops/s** | 1.27 μs | ±0.13% | 784,790 |
+| **OffHeap W-TinyLFU** | **727,002 ops/s** | 1.37 μs | ±0.14% | 727,003 |
+
+---
+
+## Testing Methodology
+
+All benchmarks were run locally and are fully reproducible using the scripts in our repository.
+
+* **Machine Specifications**: Intel(R) Core(TM) i9 CPU (2.4 GHz, 8 Cores), 16 GB RAM.
+* **OS Environment**: Windows 11 (build-optimized native binary).
+* **Node.js Version**: v24.16.0
+* **Payload Size**: Storing flat JSON objects containing a 100-character payload string (`{ data: "..." }`).
+* **Test Runner**: Benchmarks compiled with release optimizations (`cargo build --release` / `napi build --release`) and executed using [tinybench](https://www.npmjs.com/package/tinybench) over a 1000ms duration per task.
+
+---
+
+## ⚠️ Important Architectural Warning
+
+> [!WARNING]
+> **FFI Boundary Overhead**
+> The communication between Node.js (V8) and Rust occurs via a Native Foreign Function Interface (FFI) boundary. Crossing this boundary, casting types, and copying bytes incurs a micro overhead of approximately **1.2 to 2.5 microseconds** per operation.
+> 
+> * **When NOT to use OffHeap**: If you are caching small amounts of data (under a few megabytes) consisting of tiny objects, a pure JavaScript Map or simple JS LRU cache will be faster, as it runs entirely in the V8 heap without FFI crossings.
+> * **When to use OffHeap**: If your cache holds **gigabytes of data** or **millions of active keys** where Garbage Collection pauses dominate your application latency, OffHeap is highly superior. The micro FFI overhead is a tiny fraction of the latency saved by preventing major Stop-the-World GC sweeps.

package/docs/guide/getting-started.md

@@ -0,0 +1,74 @@
+# Getting Started
+
+```javascript
+const { CacheManager } = require('offheap');
+
+// 1. Initialize the Central Manager
+const manager = new CacheManager();
+
+// 2. Instantiate isolated caches with specific eviction policies
+const productCache = manager.createCache('products', {
+  policy: 'tinylfu', // Options: 'lru', 'arc', 'tinylfu'
+  capacity: 100000   // Sized for up to 100,000 items
+});
+
+const sessionCache = manager.createCache('sessions', {
+  policy: 'lru',
+  capacity: 20000
+});
+
+// 3. Store and retrieve values (Preserves Buffers, Strings, and JSON Objects)
+productCache.set('prod_1', { id: 1, name: 'Premium Widget', tags: ['fast'] });
+const product = productCache.get('prod_1'); // Returns the parsed JS object
+
+// 4. Set values with TTL (lazily expired)
+sessionCache.set('session_token', 'user_123', 60000); // 60 seconds (60000 ms) TTL
+```
+
+## Automatic Serialization & Type Preservation
+
+OffHeap dynamically adapts its serialization path at the FFI boundary to maximize performance and save memory. You do not need to manually stringify objects or convert buffers to strings:
+
+```javascript
+// 1. Binary Data (zero-copy buffer allocation)
+cache.set('binary_data', fs.readFileSync('image.png'));
+const buffer = cache.get('binary_data'); // Returns a Node.js Buffer
+
+// 2. Plain Text / Strings
+cache.set('text_data', 'Hello World!');
+const message = cache.get('text_data'); // Returns a standard JS string
+
+// 3. Structured JSON (objects, arrays, numbers, booleans)
+cache.set('json_data', { username: 'ryangustavo', role: 'admin' });
+const profile = cache.get('json_data'); // Returns the deserialized JS Object
+
+// 4. Atomic Counters (high-efficiency integer values)
+cache.set('page_views', 100);
+cache.increment('page_views', 1); // Returns 101 without JSON overhead
+```
+
+## Introduction
+
+OffHeap is a high-performance, in-process, off-heap caching framework for Node.js written from scratch in **Rust** using **NAPI-RS**. By moving cached values out of the V8 JavaScript engine heap and into Rust memory space, OffHeap prevents V8 Garbage Collection (GC) sweeps from scanning the cache graphs. This layout eliminates Stop-the-World GC latency spikes under high retention workloads.
+
+Unlike traditional Node.js cache engines that store values as JavaScript objects, OffHeap serializes values and stores them as raw bytes in Rust memory. When data is requested, it is transferred across the Foreign Function Interface (FFI) boundary and deserialized back into its original type. The framework supports raw binary Buffers, text Strings, and complex JSON Objects, choosing the most efficient serialization path based on the type.
+
+OffHeap is built using an architecture where you instantiate isolated, named `Cache` instances from a single central `CacheManager`. This design lets you run multiple caches under different eviction policies—including classic Least Recently Used (LRU), Adaptive Replacement Cache (ARC), and Window TinyLFU (W-TinyLFU)—providing optimal hit ratios tailored to each microservice's access pattern.
+
+## Installation
+
+Install the package using your preferred Node.js package manager:
+
+```bash
+# npm
+npm install offheap
+
+# yarn
+yarn add offheap
+
+# pnpm
+pnpm add offheap
+```
+
+> [!NOTE]
+> The package automatically downloads pre-built native binaries compiled for your target operating system and architecture (Windows, macOS, and Linux) during installation. No local C++ compiler or Rust toolchain is required for end-users.

package/docs/index.md

@@ -0,0 +1,23 @@
+---
+layout: home
+
+hero:
+  name: OffHeap
+  text: High-Performance Off-Heap Caching
+  tagline: Bypassing the V8 Heap using native Rust and NAPI-RS. Zero Garbage Collection overhead at scale.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/getting-started
+    - theme: alt
+      text: View API Reference
+      link: /guide/api
+
+features:
+  - title: Zero GC Pause
+    details: Storing serialized data in Rust memory keeps the V8 heap clean and prevents Stop-the-World garbage collection sweeps.
+  - title: W-TinyLFU & ARC
+    details: Implementations of Adaptive Replacement Cache and Window TinyLFU from scratch to maximize cache hit rates under skewed workloads.
+  - title: Multiple Isolated Caches
+    details: Provision isolated cache instances from a central manager, each with its own capacity and eviction strategies.
+---

package/index.d.ts

@@ -1,30 +1,42 @@
-/* tslint:disable */
-/* eslint-disable */
-
-/* auto-generated by NAPI-RS */
-
 export interface CacheConfig {
-  policy: string
-  capacity: number
+  policy: 'lru' | 'arc' | 'tinylfu';
+  capacity: number;
+  shards?: number;
+  maxBytes?: number;
 }
-export interface CacheStatsJs {
-  hits: number
-  misses: number
-  capacity: number
-  size: number
+
+export interface CacheStats {
+  hits: number;
+  misses: number;
+  capacity: number;
+  size: number;
+  bytesUsed: number;
 }
-export declare class Cache {
-  get(key: string): unknown
-  set(key: string, value: unknown, ttlMs?: number | undefined | null): unknown
-  delete(key: string): boolean
-  clear(): void
-  stats(): CacheStatsJs
-  keys(): Array<string>
+
+export class Cache {
+  get<T = any>(key: string): T | undefined;
+  peek<T = any>(key: string): T | undefined;
+  has(key: string): boolean;
+  set<T = any>(key: string, value: T, ttlMs?: number): T | undefined;
+  touch(key: string, ttlMs?: number): boolean;
+  delete(key: string): boolean;
+  clear(): void;
+  stats(): CacheStats;
+  keys(): string[];
+  increment(key: string, delta?: number, ttlMs?: number): number;
+  decrement(key: string, delta?: number, ttlMs?: number): number;
+  mget(keys: string[]): Record<string, any>;
+  mset(entries: Record<string, any>, ttlMs?: number): void;
+  mdelete(keys: string[]): number;
+  dispose(): void;
+  getOrSet<T = any>(key: string, factory: () => T | Promise<T>, ttlMs?: number): T | Promise<T>;
 }
-export declare class CacheManager {
-  constructor()
-  createCache(name: string, config: CacheConfig): Cache
-  getCache(name: string): Cache | null
-  deleteCache(name: string): boolean
-  clear(): void
+
+export class CacheManager {
+  constructor();
+  createCache(name: string, config: CacheConfig): Cache;
+  getCache(name: string): Cache | null;
+  deleteCache(name: string): boolean;
+  clear(): void;
+  dispose(): void;
 }