Cargo Stability

TypeScript ESM library that centralizes cargo stability calculations for items, containers, and transport.

Requirements

• Node.js 24+
• npm
• TypeScript 6.x (dev dependency)

How to install

npm install @jetta/cargo-stability

Usage

import { calculate_cargo_stability } from '@jetta/cargo-stability'

const result = calculate_cargo_stability({
    calculation_type: 'transport',
    containers: [
        {
            w: 2.15,
            h: 2.1,
            l: 4.5,
            item_list: [
                { x: 0, y: 0, z: 0, w: 1, h: 1, l: 1 }
            ]
        }
    ],
    config: {
        item_stability_factor_weight: {
            tip_over_angle: 0.1,
            covered_sides: 0.75,
            closest_object_distance: 0.05,
            measure_relation: 0.1
        }
    }
})

Calculation modes

| calculation_type | Output shape | | :--- | :--- | | items | number[][] — per-container item stability indices | | container | number[] — per-container stability indices | | transport | { items, containers, transport } — full breakdown plus transport average |

Invalid input throws Invalid_Input_Exception.

Project layout

src/
  core/           # domain: validation, calculators, types, container_stability
                  # orchestration entry: CargoStability.ts
index.ts          # public exports (calculate_cargo_stability)

Dependencies

1. @jetta/item-stability — item-level stability factors
2. zod — input/output contract validation

Container aggregation lives in src/core/container_stability/ (inlined, formerly a separate repo).

Development

npm ci
npm run typecheck
npm run lint
npm test
npm run lint:package
npm run regolden   # refresh fixture expected outputs after formula changes

I/O contract

JSON examples live in ./docs/contract:

• input.json — request payload
• output_item.json — items mode response
• output_container.json — container mode response
• output_transport.json — transport mode response

Contract tests under test/src/core/validation/schemas/ validate these fixtures with Zod.

CI/CD and release

Bitbucket Pipelines runs on pull requests and on version tags:

| Trigger | Action | | :--- | :--- | | Pull requests | lint, build + publint, security audit, coverage | | Tag alpha-* | publish to npm with dist-tag alpha | | Tag v* | publish stable release to npm |

Local release helpers:

npm run publish:alpha    # creates alpha-v* tag
npm run publish:stable   # creates v* tag

Required Bitbucket variable: NPM_PUBLISH_TOKEN.

Issues and documentation

• ISSUE-318