Item Stability

Library that calculates a stability index (0–1) for each allocated item inside a container, combining weighted geometric factors.

Sources are written in TypeScript and compile to CommonJS under build/. The public API is exposed through build/main.js (with .d.ts types).

Requirements

• Node.js 18 or later
• npm 9 or later (for npm ci)

How to install

From npm (after publish):

npm install @jetta/item-stability

Local development:

npm ci
npm run build

The published package ships build/main.js, build/main.d.ts, and build/core/ only. The full build/ folder (including compiled tests) is generated locally and is not committed.

Usage

After building, require the compiled entry point:

const calculate_item_stability = require('./build/main')
// or, when installed as a dependency:
// const calculate_item_stability = require('@jetta/item-stability')

const input_data = {
    container: {w: 10, h: 10, l: 10},
    item_list: [
        {x: 0, y: 0, z: 0, w: 2, h: 2, l: 2}
    ]
}

const stability_index = calculate_item_stability(input_data)
// [0.742] — one score per item, same order as item_list

Factor weights default to ITEM_STABILITY_FACTOR_WEIGHT in core/constants/ItemStabilityFactorWeights.ts. Pass config.item_stability_factor_weight to override them. All four keys are required when that object is present. CompletelyStable stays at coefficient 1.

| Factor | Default weight | |--------|----------------| | measure_relation | 0.30 | | covered_sides | 0.75 | | closest_object_distance | 0.05 | | tip_over_angle | 0.10 |

Optional timing logs for local debugging:

calculate_item_stability(input_data, {log_timing: true})

Project layout

| Path | Purpose | |------|---------| | main.ts | Public entry point | | core/ | Domain models, spatial indexing, factor strategies | | core/validation/ | Zod input schemas | | core/types/ | Shared TypeScript types (AppData, InputData, etc.) | | test/src/ | Mocha test suites (compiled with production code) | | test/data/ | JSON fixtures for data-driven tests | | debug/ | Local debug scripts (run via tsx) | | build/ | Compiled output (main.js, core/ for publish; test/src/ for local/CI tests) |

Dependencies

Runtime

| Package | Purpose | |---------|---------| | zod | Input validation at the API boundary |

Development

| Package | Purpose | |---------|---------| | typescript | Type checking and compilation | | tsx | Run benchmark and debug scripts | | mocha / chai | Tests and assertions | | eslint / typescript-eslint | Linting | | c8 | Code coverage | | publint | npm package manifest validation | | @types/node, @types/mocha, @types/chai | Type definitions |

Scripts

| Script | Description | |--------|-------------| | npm run build | Compile production TypeScript to build/ (main.js, core/) | | npm run build:test | Compile tests to build/test/ (used by npm test) | | npm run typecheck | Type-check without emitting files | | npm test | build:test, then run Mocha on build/test/src/**/*.js | | npm run lint | ESLint on .ts sources | | npm run lint:fix | ESLint with auto-fix | | npm run lint:package | Validate npm publish manifest with publint (run after build) | | npm run coverage | Tests with c8 (HTML + text reports) | | npm run coverage:ci | Same tests under c8 with coverage thresholds (used in CI) | | npm run benchmark | Benchmark spatial setup (tsx test/benchmark/...) | | npm run publish:alpha / publish:stable | Bump version and tag for npm publish via CI | | npm run prerelease:alpha | Bump alpha prerelease version |

Test plan

Full verification:

npm run typecheck
npm run lint
npm run build
npm run lint:package
npm run coverage:ci
npm run benchmark

Run a subset:

npm test -- --grep "ItemStability integration"
npm test -- --grep "TipOverAngle"

Documentation

• Configuration reference
• Stability calculus (Google Doc)
• Jira ISSUE-318

Contract

Input

• Ordered set of allocated items (x, y, z, w, h, l; coordinates may be zero at floor/walls)
• Container dimensions (w, h, l)

Optional config.item_stability_factor_weight with measure_relation, covered_sides, closest_object_distance, and tip_over_angle. Omitted weights use the defaults in Usage.

Output

• Ordered array of floats in [0, 1], one stability score per item

Invalid payloads throw InvalidInputException.