A Promise-first SDK over the same Rust core the CLI uses, bound through Node-API. Fully typed, with AbortSignal cancellation and progress events — for release dashboards, CI tools and orchestration. Published as @orelvis15/cavs-sdk.
Ships TypeScript types. Requires Node 20+ and a C toolchain-free install — the native binding loads a prebuilt library.
The library resolves from @orelvis15/cavs-sdk-<os>-<arch> optional deps, or CAVS_SDK_LIBRARY.
Every operation returns a Promise. The non-progress path runs off the event loop; failures reject with CavsError.
The matching @orelvis15/cavs-sdk-<platform> package is pulled automatically. For a source checkout, npm run native stages the library locally.
CAVS
import { CavsClient } from "@orelvis15/cavs-sdk";
const cavs = new CavsClient();
try {
const preview = await cavs.preview({
oldPath: "Build_v1",
newPath: "Build_v2",
policy: "balanced",
});
console.log("Recommended route:", preview.recommendedRoute);
for (const r of preview.routes) {
console.log(` ${r.name}: ${r.networkBytes} bytes`);
}
} finally {
cavs.close();
}
Every method returns a Promise and accepts an options object with onProgress and signal. Failures reject with a CavsError carrying a stable .code.
analyze({ oldPath, newPath })packDirectory({ inputDir, outputCavs })preview({ oldPath, newPath, policy })createPlan({ oldPath, newPath, outputPlan })applyPlan({ oldPath, planPath, outputPath })verifyInstall({ target, signature })benchmark({ oldPath, newPath })estimateSavings({ pricePerGb, monthlyDownloads, … })import { CavsClient, CavsError, ErrorCode } from "@orelvis15/cavs-sdk";
const cavs = new CavsClient();
const ac = new AbortController();
setTimeout(() => ac.abort(), 30_000);
try {
const plan = await cavs.createPlan(
{ oldPath: "Build_v1", newPath: "Build_v2", outputPlan: "update.cavsplan" },
{
signal: ac.signal,
onProgress: (e) => console.log(`[${e.type}] ${e.phase ?? ""}`),
},
);
console.log("reused bytes:", plan.reusedBytes);
} catch (err) {
if (err instanceof CavsError && err.code === ErrorCode.PathNotFound) {
console.error("old build not found");
} else {
throw err;
}
} finally {
cavs.close();
}
Enabling onProgress runs the operation synchronously so callbacks stay on the JS thread; the default (non-progress) path runs off the event loop and honors signal.
// release-preview.ts — run in CI, publish the report
const cavs = new CavsClient();
const preview = await cavs.preview({
oldPath: process.env.OLD_BUILD!,
newPath: process.env.NEW_BUILD!,
});
await uploadReport(preview); // JSON straight to your dashboard
cavs.close();