DOCS / TUTORIAL

Getting started in Node

Install @packvium/engine, call pack() with a plain object, and read why an item was left out.

Docs for Packvium 1.11.x · contract stable since 1.0

01Install#

Node.js 16 or later. The native addon is optional — install always works, and backend() reports which implementation actually answered.

npm install @packvium/engine

02Call 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 exact

07Next 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.