empty-spaces-manager-nodejs

TypeScript library (ESM) for finding and choosing axis-aligned empty regions in 3D containers. It subtracts placed items (and optional corner castings), merges fragments, then scores remaining spaces so you can pick where to place the next item.

Requirements

• Node.js (with native ESM support)
• npm

Install

npm install empty-spaces-manager-nodejs

The published package ships only the compiled output under build/ ("files": ["build"]). Point "main" / "types" at build/index.js and build/index.d.ts.

Local development: clone, run npm install, then npm run build before linking or packing.

Scripts

| Script | Description | | ------ | ----------- | | npm run build | Compile src/ → build/ (tsc) | | npm test | Mocha + tsx on test/**/*.test.ts | | npm run lint | ESLint on src/**/*.ts and test/**/*.ts | | npm run lint:fix | ESLint with --fix | | npm run coverage | Tests with c8 (HTML + text reports) | | npm run coverage:ci | Same tests under c8 with text summary and minimum coverage thresholds (used in CI) |

Dependencies

Runtime:

• @jetta/number-compare — safe numeric comparisons for intervals and geometry.

Development: TypeScript, ESLint, Mocha, Chai, c8, tsx (see package.json / lockfile).

Public API

Named exports from empty-spaces-manager-nodejs (see src/index.ts):

| Export | Role | | ------ | ---- | | EmptySpaceFinder | Builds empty Space[] inside a container. Constructor applies optional corner castings (same allocate + merge path as items). Call allocate_item_list for placed PositionedCube items, then empty_spaces() for the current list. Throws InvalidDimensionsException if the container or any obstacle has non-positive extents after rounding. | | ClassicEmptySpaceChooser | Scores empty spaces with weighted strategies from a cargo profile; evaluate_spaces() returns the best Space. | | ChooserConstructorInput (type) | Payload shape for new ClassicEmptySpaceChooser(…). | | Space | Positioned empty-space fragment (extends PositionedCube); supports fragment generation and merge rules. | | Cube | Width / height / length only (internal code may use degenerate extents; user-facing paths validate positive volume). | | Item | Cube + allowed rotations (ItemSpec); rejects non-positive dimensions after rounding. | | PositionedCube | Positioned box (x, y, z + dimensions). | | Rotations | Rotation id constants (pos1 … pos6). | | CornerCasting | Positioned obstacle with optional position label. | | Direction | Namespace import: Direction.ABOVE, Direction.BELOW, Direction.LEFT, … |

Domain errors (for instanceof / typed handling):

| Export | When | | ------ | ---- | | InvalidAxisException | Invalid axis id on PositionedCube helpers. | | InvalidDimensionsException | Non-positive width, height, or length after rounding (Item). | | InvalidIntersectionException | Interval intersection used on non-overlapping ranges. | | InvalidPositionException | Negative x, y, or z on PositionedCube (e.g. Space). | | InvalidRotationException | Item rotation not in the allowed list. | | InvalidSpaceChooserParams | Missing or unusable chooser criteria in the cargo profile. | | NoSpaceLeftException | No scorable empty space. | | StrategyEvaluateNotImplementedException | Strategy subclass missing evaluate. | | StrategyNotFoundException | Unknown strategy name in the map. | | StrategyStubNotImplementedException | Stub strategy not implemented. |

Usage

Find empty spaces

import {
    EmptySpaceFinder,
    Space,
    PositionedCube
} from 'empty-spaces-manager-nodejs'

const container = new Space({
    x: 0, y: 0, z: 0,
    width: 3, height: 3, length: 3
})

const finder = new EmptySpaceFinder(container, [])

const placed = [
    new PositionedCube({x: 1, y: 1, z: 1, width: 1, height: 1, length: 1})
]
finder.allocate_item_list(placed)

const empty_spaces = finder.empty_spaces()

allocate_item_list works on a copy of the array you pass: it sorts by highest Y first for allocation but does not reorder your original array.

Choose a space for the next item

import {
    ClassicEmptySpaceChooser,
    Item,
    Rotations
} from 'empty-spaces-manager-nodejs'

const chooser = new ClassicEmptySpaceChooser({
    container,
    empty_spaces,
    items: [
        new Item({
            width: 1,
            height: 1,
            length: 1,
            rotations: [Rotations.POS1]
        })
    ],
    cargo_profile: {
        'allocation.empty_space.chooser.score_strategy_criterias': [
            {criteria: 'MaximumStacking', weight: 1}
        ],
        'allocation.empty_space.chooser.enable_full_contained_removal': false
    }
})

const chosen = chooser.evaluate_spaces()

Cargo profile (chooser)

• allocation.empty_space.chooser.score_strategy_criterias — { criteria: string, weight: number }[]. At least one non-zero weight. Criteria names are resolved by the internal strategy map (e.g. MaximumStacking, FloorAllocation, ItemFit, FrontAllocation, LeftAllocation, …).
• allocation.empty_space.chooser.enable_full_contained_removal — If true, drops spaces that are fully contained in another space before scoring. Legacy keys enable_full_contains_removal and enable_full_containes_removal are also accepted.

Development

• Source lives under src/**/*.ts (NodeNext resolution; imports use .js specifiers).
• Tests live under test/**/*.test.ts; shared fixtures follow test/data/src/… where applicable.

License

ISC