offheap 0.1.0

package/benches/rust_bench.rs

@@ -0,0 +1,96 @@
+use criterion::{criterion_group, criterion_main, Criterion};
+use offheap::algorithms::{
+    CacheImpl,
+    lru::LruCache,
+    arc::ArcCache,
+    tinylfu::TinyLfuCache,
+};
+
+fn bench_sets(c: &mut Criterion) {
+    let mut group = c.benchmark_group("Cache Set");
+    let capacity = 10000;
+    
+    group.bench_function("LRU Set", |b| {
+        let mut cache = LruCache::new(capacity);
+        let mut i = 0;
+        b.iter(|| {
+            let key = format!("key-{}", i);
+            cache.set(&key, vec![1, 2, 3], None);
+            i += 1;
+        });
+    });
+
+    group.bench_function("ARC Set", |b| {
+        let mut cache = ArcCache::new(capacity);
+        let mut i = 0;
+        b.iter(|| {
+            let key = format!("key-{}", i);
+            cache.set(&key, vec![1, 2, 3], None);
+            i += 1;
+        });
+    });
+
+    group.bench_function("W-TinyLFU Set", |b| {
+        let mut cache = TinyLfuCache::new(capacity);
+        let mut i = 0;
+        b.iter(|| {
+            let key = format!("key-{}", i);
+            cache.set(&key, vec![1, 2, 3], None);
+            i += 1;
+        });
+    });
+
+    group.finish();
+}
+
+fn bench_gets(c: &mut Criterion) {
+    let mut group = c.benchmark_group("Cache Get");
+    let capacity = 10000;
+
+    // LRU Warm up
+    let mut lru = LruCache::new(capacity);
+    for i in 0..capacity {
+        lru.set(&format!("key-{}", i), vec![1, 2, 3], None);
+    }
+    
+    group.bench_function("LRU Get Hit", |b| {
+        let mut i = 0;
+        b.iter(|| {
+            lru.get(&format!("key-{}", i % capacity));
+            i += 1;
+        });
+    });
+
+    // ARC Warm up
+    let mut arc = ArcCache::new(capacity);
+    for i in 0..capacity {
+        arc.set(&format!("key-{}", i), vec![1, 2, 3], None);
+    }
+
+    group.bench_function("ARC Get Hit", |b| {
+        let mut i = 0;
+        b.iter(|| {
+            arc.get(&format!("key-{}", i % capacity));
+            i += 1;
+        });
+    });
+
+    // TinyLFU Warm up
+    let mut tinylfu = TinyLfuCache::new(capacity);
+    for i in 0..capacity {
+        tinylfu.set(&format!("key-{}", i), vec![1, 2, 3], None);
+    }
+
+    group.bench_function("W-TinyLFU Get Hit", |b| {
+        let mut i = 0;
+        b.iter(|| {
+            tinylfu.get(&format!("key-{}", i % capacity));
+            i += 1;
+        });
+    });
+
+    group.finish();
+}
+
+criterion_group!(benches, bench_sets, bench_gets);
+criterion_main!(benches);

package/benchmarks/js_bench.js

@@ -0,0 +1,67 @@
+const { Bench } = require('tinybench');
+const { CacheManager } = require('../index.js');
+
+async function runBenchmark() {
+  const manager = new CacheManager();
+  const capacity = 10000;
+
+  // Instantiate caches
+  const lruCache = manager.createCache('bench-lru', { policy: 'lru', capacity });
+  const arcCache = manager.createCache('bench-arc', { policy: 'arc', capacity });
+  const tinyLfuCache = manager.createCache('bench-tinylfu', { policy: 'tinylfu', capacity });
+
+  // Prepare benchmark keys and values
+  const keys = Array.from({ length: 20000 }, (_, i) => `key-${i}`);
+  const val = { data: 'a'.repeat(100) }; // 100 char string object
+  let writeIdx = 0;
+  let readIdx = 0;
+
+  const benchSet = new Bench({ time: 1000 });
+  
+  benchSet
+    .add('OffHeap LRU - Set', () => {
+      lruCache.set(keys[writeIdx % keys.length], val);
+      writeIdx++;
+    })
+    .add('OffHeap ARC - Set', () => {
+      arcCache.set(keys[writeIdx % keys.length], val);
+      writeIdx++;
+    })
+    .add('OffHeap W-TinyLFU - Set', () => {
+      tinyLfuCache.set(keys[writeIdx % keys.length], val);
+      writeIdx++;
+    });
+
+  console.log('=== Benchmarking SET operations (10k capacity, 20k unique keys) ===');
+  await benchSet.run();
+  console.table(benchSet.table());
+
+  // Warm up caches for GET benchmarks
+  for (let i = 0; i < capacity; i++) {
+    lruCache.set(keys[i], val);
+    arcCache.set(keys[i], val);
+    tinyLfuCache.set(keys[i], val);
+  }
+
+  const benchGet = new Bench({ time: 1000 });
+
+  benchGet
+    .add('OffHeap LRU - Get', () => {
+      lruCache.get(keys[readIdx % capacity]);
+      readIdx++;
+    })
+    .add('OffHeap ARC - Get', () => {
+      arcCache.get(keys[readIdx % capacity]);
+      readIdx++;
+    })
+    .add('OffHeap W-TinyLFU - Get', () => {
+      tinyLfuCache.get(keys[readIdx % capacity]);
+      readIdx++;
+    });
+
+  console.log('\n=== Benchmarking GET operations (100% Cache Hits) ===');
+  await benchGet.run();
+  console.table(benchGet.table());
+}
+
+runBenchmark().catch(console.error);

package/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+  napi_build::setup();
+}

package/index.d.ts

@@ -0,0 +1,30 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export interface CacheConfig {
+  policy: string
+  capacity: number
+}
+export interface CacheStatsJs {
+  hits: number
+  misses: number
+  capacity: number
+  size: 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 declare class CacheManager {
+  constructor()
+  createCache(name: string, config: CacheConfig): Cache
+  getCache(name: string): Cache | null
+  deleteCache(name: string): boolean
+  clear(): void
+}

package/index.js

@@ -0,0 +1,316 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'offheap.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./offheap.android-arm64.node')
+          } else {
+            nativeBinding = require('offheap-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'offheap.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./offheap.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('offheap-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'offheap.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./offheap.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('offheap-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'offheap.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./offheap.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('offheap-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'offheap.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./offheap.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('offheap-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'offheap.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./offheap.darwin-universal.node')
+      } else {
+        nativeBinding = require('offheap-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'offheap.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./offheap.darwin-x64.node')
+          } else {
+            nativeBinding = require('offheap-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'offheap.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./offheap.darwin-arm64.node')
+          } else {
+            nativeBinding = require('offheap-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'offheap.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./offheap.freebsd-x64.node')
+      } else {
+        nativeBinding = require('offheap-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'offheap.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./offheap.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('offheap-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'offheap.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./offheap.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('offheap-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'offheap.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./offheap.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('offheap-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'offheap.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./offheap.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('offheap-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'offheap.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./offheap.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('offheap-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'offheap.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./offheap.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('offheap-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'offheap.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./offheap.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('offheap-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'offheap.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./offheap.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('offheap-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'offheap.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./offheap.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('offheap-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { Cache, CacheManager } = nativeBinding
+
+module.exports.Cache = Cache
+module.exports.CacheManager = CacheManager

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "offheap",
+  "version": "0.1.0",
+  "description": "High-performance off-heap caching framework for Node.js written in Rust",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "name": "offheap",
+    "triple": {
+      "defaults": true,
+      "additional": []
+    }
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "prepublishOnly": "napi prepublish -t npm --skip-gh-release",
+    "test": "node --test tests/index.test.js",
+    "benchmark": "node benchmarks/js_bench.js"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4",
+    "tinybench": "^2.9.0"
+  },
+  "engines": {
+    "node": ">= 18"
+  },
+  "license": "MIT OR Apache-2.0",
+  "optionalDependencies": {
+    "offheap-win32-x64-msvc": "0.1.0",
+    "offheap-darwin-x64": "0.1.0",
+    "offheap-linux-x64-gnu": "0.1.0"
+  }
+}