{"_id":"@bilal-alachisoft/ncache","name":"@bilal-alachisoft/ncache","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@bilal-alachisoft/ncache","version":"1.0.1","description":"Node.js SDK for NCache — Java-mirror architecture on top of a Node-API (N-API) native addon.","main":"dist/cjs/index.js","module":"dist/esm/index.js","types":"dist/types/index.d.ts","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"}},"keywords":["ncache","cache","distributed-cache","alachisoft","napi","node-api","node-addon-api"],"author":{"name":"NCache"},"license":"Proprietary","engines":{"node":">=24"},"dependencies":{"bindings":"^1.5.0","node-addon-api":"^7.1.0"},"directories":{"example":"examples","test":"tests"},"type":"commonjs","arch":["x64"],"optionalDependencies":{"@bilal-alachisoft/ncache-linux-x64":"1.0.1","@bilal-alachisoft/ncache-win32-x64":"1.0.1"},"_id":"@bilal-alachisoft/ncache@1.0.1","_integrity":"sha512-d0HEZ12qPSy2iGnWY8GR9/U6ISSv7GjVXXOT2GEzwmA4ot8t2/bTkZ3IVBSY2wwGccjmpDUXqvjUHErvCnKp/A==","_resolved":"D:\\Repos\\CacheWrapperC++\\nodejs\\dist-packages\\bilal-alachisoft-ncache-1.0.1.tgz","_from":"file:bilal-alachisoft-ncache-1.0.1.tgz","_nodeVersion":"20.18.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-d0HEZ12qPSy2iGnWY8GR9/U6ISSv7GjVXXOT2GEzwmA4ot8t2/bTkZ3IVBSY2wwGccjmpDUXqvjUHErvCnKp/A==","shasum":"030138189d0ed8ab0b002ac40c26558b98b70057","tarball":"https://registry.npmjs.org/@bilal-alachisoft/ncache/-/ncache-1.0.1.tgz","fileCount":1746,"unpackedSize":2174367,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBCMu4rm20STZEmijo2/t4uvFssGQ15ukuytMQp4yvYvAiBUhMAdesn93Q7inpRupgBfOhz4MW5jR9HTsBaCOFEigQ=="}]},"_npmUser":{"name":"bilal-alachisoft","email":"ba1339855@gmail.com"},"maintainers":[{"name":"bilal-alachisoft","email":"ba1339855@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ncache_1.0.1_1788525325571_0.3475668812728854"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-04T12:35:25.358Z","1.0.1":"2026-09-04T12:35:25.737Z","modified":"2026-09-04T12:35:25.951Z"},"maintainers":[{"name":"bilal-alachisoft","email":"ba1339855@gmail.com"}],"description":"Node.js SDK for NCache — Java-mirror architecture on top of a Node-API (N-API) native addon.","keywords":["ncache","cache","distributed-cache","alachisoft","napi","node-api","node-addon-api"],"author":{"name":"NCache"},"license":"Proprietary","readme":"# ncache-node — Node.js SDK for NCache (Node-API native addon)\n\nLine-for-line mirror of the Java client. Every Java class has a\nTypeScript counterpart at the same layer. The FFI layer is a real\n**Node-API (N-API)** native addon written in C++ with\n[`node-addon-api`](https://github.com/nodejs/node-addon-api).\n\nNode-API is ABI-stable across Node.js versions, so once the addon is\nbuilt for a platform it keeps working on future Node upgrades without\nrebuilding.\n\n## Requirements\n\n- Node.js 16 or newer (64-bit)\n- A C++17 toolchain (Visual Studio Build Tools on Windows, `build-essential` on Linux, Xcode on macOS)\n- Python 3.x (used by `node-gyp`)\n- `ncache_wrapper.dll` on Windows or `libncache_wrapper.so` on Linux\n- `NCache.Bridge.dll` and its runtime files beside the native wrapper\n- .NET 8 runtime + an accessible NCache server for integration tests\n\n## Install & build\n\n```powershell\ncd nodejs\nnpm install         # builds the native addon via node-gyp\n$env:NCACHE_WRAPPER_PATH = \"D:\\Repos\\CacheWrapperC++\\build\\bridge\\ncache_wrapper.dll\"\nnpm run build:ts    # compile TypeScript to dist/\n```\n\n`npm install` triggers `node-gyp rebuild` which compiles the addon into\n`build/Release/ncache_addon.node`. The TS layer loads it via the\n`bindings` package.\n\n## Quick start\n\n```ts\nimport { CacheManager } from \"ncache-node\";\n\nconst cache = await CacheManager.getCache(\"demoCache\");\ntry {\n  await cache.insert(\"key\", { name: \"value\" });\n  const back = await cache.get<{ name: string }>(\"key\");\n  console.log(back);\n} finally {\n  await cache.close();\n}\n```\n\n## Architecture\n\nSame five-layer stack as the Java and Python SDKs:\n\n```\nConsumer  →  interfaceImpl (CacheImpl, CounterImpl, …)\n          →  interfaceImpl.bridgeImpl.Native*BridgeImpl\n              (serialisation + ExceptionMapper)\n          →  nativeClass.CacheNative etc.\n              (uses `src/native/addon.ts` — the N-API surface)\n          →  src/native/addon.ts\n              (loads `build/Release/ncache_addon.node`)\n          →  native C++ addon\n              (dlopen/LoadLibrary of ncache_wrapper.dll)\n```\n\nThe N-API addon returns a uniform envelope per call:\n\n```ts\ninterface NativeResult<T> {\n  status: number;                   // NcStatus (0 = success, non-zero = failure)\n  out?: T;                          // typed output payload if any\n  error?: {                         // populated on failure\n    code: number;\n    message: string;\n    exceptionType: string | null;\n    stackTrace: string | null;\n  } | null;\n}\n```\n\nEvery `*Native` class converts that envelope into the Java-mirror\n`*Response` object; `bridgeImpl` re-raises via `ExceptionMapper`.\n\n## Package layout\n\nMirrors `com.ncache.client.*` one-for-one:\n\n| Node/TypeScript                                          | Java                                                    |\n| -------------------------------------------------------- | ------------------------------------------------------- |\n| `src/cacheManager/CacheManager.ts`                       | `cachemanager.CacheManager`                             |\n| `src/cacheManager/ExceptionMapper.ts`                    | `cachemanager.ExceptionMapper`                          |\n| `src/interfaces/*.ts`                                    | `interfaces.*`                                          |\n| `src/interfaceImpl/*.ts`                                 | `interfaceImpl.*`                                       |\n| `src/interfaceImpl/bridgeImpl/*.ts`                      | `interfaceImpl.bridgeImpl.*`                            |\n| `src/nativeClass/*.ts`                                   | `nativeClass.*`                                         |\n| `src/models/*.ts`                                        | `models.*`                                              |\n| `src/models/nativeResponse.ts`                           | `models.nativeResponse.*`                               |\n| `src/exceptions/*.ts`                                    | `Exceptions.*`                                          |\n| `src/enums/*.ts`                                         | `enums.*`                                               |\n| `src/classes/*.ts`                                       | `classes.*`                                             |\n| `src/utils/*.ts`                                         | `utils.*`                                               |\n| `src/annotations/index.ts`                               | `annotations.*`                                         |\n| `src/services/PollingWorker.ts`                          | shared polling infra                                    |\n| `src/native/addon.ts` + `native/*.cc`                    | JNI shim (`ncache-jni/cpp`)                             |\n\n## Tests\n\nUnit tests do not require the addon (they exercise pure-TS layers):\n\n```powershell\nnpm run test:unit\n```\n\nIntegration tests need the addon compiled and a live cluster:\n\n```powershell\n$env:NCACHE_TEST_CACHE = \"demoCache\"\nnpm run test:integration\n```\n\n## Troubleshooting `npm install`\n\nIf `node-gyp rebuild` fails on Windows, install the Visual Studio Build\nTools 2022 workload including \"Desktop development with C++\". On Linux\ninstall `build-essential` and `python3`.\n\nThe addon includes headers from `../ncache-c-api/include` (relative to\nthis `nodejs/` folder). If you move the SDK, adjust `include_dirs` in\n`binding.gyp`.\n","readmeFilename":"README.md","_rev":"1-278d48988e376960a6b0e8e5a9e30997"}