01Install#
Node.js 16 or later. The native addon is optional — install always works, and backend() reports which implementation actually answered.
npm install @packvium/engine02Call pack() and read the result#
pack() takes a plain object shaped exactly like the request schema and returns a plain object back — no wrapper classes to learn before the first call.
import { backend, pack } from '@packvium/engine';
const result = pack({
items: [{
id: 'book', quantity: 4,
dimensions: { length: '210', width: '140', height: '30' },
}],
containers: [{
id: 'carton',
inner_dimensions: { length: '400', width: '300', height: '250' },
}],
});
console.log(backend()); // "rust" or "javascript"
console.log(result.status); // "feasible"
console.log(result.containers);03Handle items the engine could not place#
Every entry in result.unpacked_items carries a stable reason string and the id of the item it refers to — read directly, with no helper required to get a first answer.
for (const unpacked of result.unpacked_items) {
console.log(unpacked.item_id, unpacked.reason);
}04What is already checked before you see it#
Every placement pack() returns has been re-checked by validation logic independent of the search that found it. The fixture pages on this site show that validator's verdict next to the engine's for the same request, so a wrong placement is not something you have to take on trust.
05Check a result yourself#
The reference validator ships in the package: validate(request, result) returns every issue it finds, each with a code and a detail, and an empty array means the result is valid. From 1.8.0 it answers after a plain npm install too, without the compiled addon, and also checks the lower bound and gap a result reports; ValidatorUnavailableError is still exported, but nothing throws it.
import { pack, validate } from '@packvium/engine';
const result = pack(request);
for (const issue of validate(request, result)) console.log(issue.code, issue.detail);06Write a result as JSON#
From 1.9.0 a weight is exact up to 2^63 - 1 ticks. A weight's ticks, and a shipping_cost score position that sums weights, stay a Number up to 2^53 - 1 ticks (about 1,126 tonnes in all) and become a BigInt past that, which JSON.stringify refuses. stringifyExact and parseExact carry such a result through JSON text exactly; for any smaller load they write what JSON.stringify writes.
import { pack, parseExact, stringifyExact } from '@packvium/engine';
const text = stringifyExact(pack(request)); // JSON.stringify throws on a BigInt
const result = parseExact(text); // long integers come back exact07Next steps#
Read the request and result contract for every public field, run your own dimensions in the Playground — it calls this same package on every run — or open examples/constraints.mjs for stacking, tags and atomic groups using this same reason-reading pattern.