lane-distance

(no submodules)

Purpose

Computes great-circle distance metrics for a ShippingLane's waypoint chain. estimateLaneDistance sums every segment for the lane total; cumulativeDistances returns the per-waypoint cumulative array used by findPositionOnLane and estimateETA. Both functions reject lanes with fewer than two waypoints because any distance metric over a single-point chain is undefined.

Features

estimateLaneDistance(lane) — total nautical miles, rounded to two decimals.
cumulativeDistances(lane) — number[] of length waypoints.length where entry 0 is 0 and entry i is the cumulative nm distance from waypoints[0] to waypoints[i].
Throws PortsInsufficientWaypointsError (PORTS.INSUFFICIENT_WAYPOINTS) for lanes shorter than two waypoints.
Emits the ports.lane_distance_duration_ms histogram.
Uses the package's shared distanceNm helper so the rounding policy is centralised.

Usage: Basic

import { estimateLaneDistance, getShippingLaneStrict } from "@suaveplan/ports";

const suez = getShippingLaneStrict("asia-europe-suez");
const totalNm = estimateLaneDistance(suez);

Usage: Advanced

import { cumulativeDistances, getShippingLaneStrict } from "@suaveplan/ports";

const lane = getShippingLaneStrict("asia-europe-suez");
const cum = cumulativeDistances(lane);
// cum[i] - cum[i-1] gives segment length between waypoints i-1 and i.
for (let i = 1; i < cum.length; i++) {
    console.log("segment", i, cum[i] - cum[i - 1], "nm");
}

API Reference

estimateLaneDistance(lane: ShippingLane): number.
cumulativeDistances(lane: ShippingLane): number[].

Implementation Notes

Each segment runs through distanceNm which itself routes through @suaveplan/geo's greatCircleDistance against the EARTH_SPHERE constant. The cumulative function recomputes segment distances rather than reusing the running sum from estimateLaneDistance — this keeps the two functions independent so callers can use either in isolation without paying for both. The trivial perf cost is acceptable at curated-dataset scale.

2.1 KiB Raw Blame History