# lane-distance

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

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

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

## Usage: Advanced

```ts
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.