INTEGRATION / PACKING-SERVICE

Packing as an HTTP service for your systems

Wrap the library in a small HTTP endpoint with a time budget, a validator check and readable refusals, so any system in any language can pack.

WHERE IT SITS

Where several systems need packing - an ERP, a quoting tool, a TMS - but only one should own the dependency. The engine is a library with no server of its own, so this is the service you own.

HOW THE DATA FLOWS
  1. 01

    A caller POSTs a packing request as JSON.

  2. 02

    The service caps time_limit_ms itself, so no caller can hold a worker longer than you allow.

  3. 03

    pack() answers and validate() re-checks the answer with the reference validator before it leaves.

  4. 04

    A malformed request becomes a 422 with the engine's reason and the JSON Pointer of the bad field; the result is written with stringifyExact, so a very heavy load stays exact.

THE WHOLE PROGRAM, IN Node / JavaScript
import { createServer } from 'node:http';
import { InvalidRequestError, pack, stringifyExact, validate } from '@packvium/engine';

const send = (response, status, body) => {
  response.writeHead(status, { 'content-type': 'application/json' });
  response.end(stringifyExact(body)); // JSON.stringify throws on a weight past 2^53 - 1 ticks
};

createServer(async (request, response) => {
  if (request.method !== 'POST' || request.url !== '/pack') return send(response, 404, { error: 'POST /pack' });
  let body = '';
  for await (const chunk of request) body += chunk;

  try {
    const packing = JSON.parse(body);
    // The caller decides what to pack; this service decides how long it may take.
    packing.configuration = { ...packing.configuration, time_limit_ms: 2000 };
    const result = pack(packing);
    // Belt and braces: the reference validator re-checks the answer before anyone acts on it.
    const issues = validate(packing, result);
    if (issues.length > 0) return send(response, 500, { error: 'invalid result', issues });
    send(response, 200, result);
  } catch (error) {
    if (error instanceof SyntaxError) return send(response, 400, { error: 'expected JSON' });
    // A malformed request names its field: answer the caller, do not page an engineer.
    if (error instanceof InvalidRequestError) return send(response, 422, { reason: error.reason, field: error.field, error: error.message });
    throw error;
  }
}).listen(process.env.PORT ?? 8080);
WHAT IT DOES

A request for four books returns 200 with the full result document. The same request with a book 0 mm long returns 422 with reason invalid_value and field /items/0/dimensions/length, so the caller learns which value to fix without anyone reading a server log.

Every program on these pages is run exactly as printed by this site's test suite, against the published package, on every change.

WHAT TO KEEP

Nothing, if you do not want to: the same request and seed give the same answer on every run, so a cache keyed on the request is safe and a retry cannot change a plan someone already acted on. Log the request and the result together when an answer must be explained later.

WHEN THE ENGINE SAYS NO

Keep three outcomes apart: 400 for a body that is not JSON, 422 for a request the engine refuses by name, and an item the engine could not place, which is a normal 200 answer with that item in unpacked_items. Only a validator issue, which should never happen, is a 500.

INSTALL
npm install @packvium/engine