axle-load-calculator

TypeScript library that merges ms-faixas-porcentuais weight_on_axles_physics orchestration with the axleweight physics engine. v1 is in-process only (no HTTP).

Requirements

• Node.js 20+
• npm

How to install

npm install
npm run build

Usage

import {
    calculate_weight_on_axles_physics,
    UnsupportedVehicleTypeError,
    type WeightByAxisRequestInput,
    type WeightByAxisSuccessOutput
} from '@jetta/axle-load-calculator'
import { ZodError } from 'zod'

const request: WeightByAxisRequestInput = { envs: [...] }

try {
    const response: WeightByAxisSuccessOutput = calculate_weight_on_axles_physics(request)
    // response.envs with axle weights
} catch (error) {
    if (error instanceof ZodError) {
        // invalid request shape (null, array, missing containers, etc.)
    } else if (error instanceof UnsupportedVehicleTypeError) {
        // unsupported tipoVeiculo
    }
}

CommonJS consumers resolve the same API through the require condition:

const { calculate_weight_on_axles_physics } = require('@jetta/axle-load-calculator')

Load the package through one syntax only. import and require resolve to separate builds, so the exported error classes are distinct constructors across them and instanceof fails when both are mixed in the same process.

Contract:

• Input: object { envs, config? } with required containers on each env (cloned before processing)
• Success: { envs } with containers[].pesoEixos filled; items and faixas cleared on containers
• Failure: throws (see Errors below)

Connector payload (ms-faixas sidecar)

const { calculate_loaded_weights_from_connector } = require('@jetta/axle-load-calculator')

const loaded_weights = calculate_loaded_weights_from_connector(connector_payload)

• Input: one transport in jettainterface wire format (_id, qtd, pesoDeCarga, primeiroEixo, containers, eixos, ...) plus center_of_mass keyed by grouper: { "1": { "mass": 5000, "z_position": 6.29 } }
• Success: number[], the loaded cargo weight per axle in axle order
• Failure: throws (see Errors below)

Errors

Thrown by calculate_weight_on_axles_physics and calculate_loaded_weights_from_connector

| Class | When | |-------|------| | ZodError (from zod, not re-exported) | calculate_weight_on_axles_physics request shape is invalid (null, array, missing containers, etc.) | | InvalidCenterOfMassError | Connector center_of_mass is missing or malformed. message is axle_weight.081004 | | MissingRequiredFieldError | A required transport, container or axle field is missing or invalid. message is axle_weight.081001; message_entry is ["axle_weight.081001", field, reader] | | UnsupportedVehicleTypeError | Unknown tipoVeiculo | | UnrecognizedSuspensionTypeError | Invalid vanderleia suspension type | | GrouperNotFoundError | Merged-container grouper not found |

Import ZodError directly from zod.

Exported for lower-level use

Also exported from @jetta/axle-load-calculator for instanceof checks when using internal physics modules (not thrown by calculate_weight_on_axles_physics):

| Class | When | |-------|------| | ContainerSequenceNotFoundError | Container sequence missing on transport | | MissingContainerError | Container lookup failed | | UnknownItemIdError | Unknown item template id | | DeflectionModelNotImplementedError | No deflection model for the vehicle |

Dependencies

• zod — request validation at the public boundary
• publint (dev) — npm package manifest validation

Scripts

| Command | Description | |---------|-------------| | npm test | Mocha tests (physics + Java integration fixtures) | | npm run lint | ESLint (src, test/src) | | npm run lint:package | Validate npm publish manifest with publint (run after build) | | npm run build | tsc → build/ (ESM) and build-cjs/ (CommonJS) | | npm run test:esm | Smoke check that import resolves the package by name | | npm run test:cjs | Smoke check that require resolves the package by name |

Layout

• src/index.ts — public API
• src/core/physics/ — axleweight port (models, deflection, tare, services)
• src/core/orchestration/ — Java weight-by-axis glue (mass center, output)
• src/service/ — reserved for future HTTP layer
• test/src/ — mirrors src/; fixtures under test/data/src/