# lane-lookup

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

## Purpose

Public lookup surface for the curated `shippingLanes` registry. Mirrors
the port-lookup module in style: an O(1) `Map` index by lane id, mode
filtering, and a "get all" accessor for downstream consumers that want
to render lists or build their own indices. The strict variant of
`getShippingLane` throws a typed `PortsLaneNotFoundError` so consumers
can branch on `.code` rather than nullable returns.

## Features

- `getShippingLane(id)` — lazy `Map<string, ShippingLane>` lookup.
- `getShippingLaneStrict(id)` — throws on miss with `laneId` in error
  context.
- `getShippingLanesByMode(mode, lanes?)` — `LaneMode` filter.
- `getAllShippingLanes()` — returns the curated registry directly
  (readonly).
- Every call emits `ports.lane_lookup_total{mode}` (mode is `all` for
  `getAllShippingLanes` and miss-paths).

## Usage: Basic

```ts
import { getShippingLane, getShippingLanesByMode } from "@suaveplan/ports";

const suez = getShippingLane("asia-europe-suez");
const seaLanes = getShippingLanesByMode("sea");
```

## Usage: Advanced

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

try {
    const lane = getShippingLaneStrict("missing-lane");
} catch (err) {
    if (err instanceof PortsLaneNotFoundError) {
        // err.context.laneId === "missing-lane"
    }
}
```

## API Reference

- `getShippingLane(id: string): ShippingLane | undefined`.
- `getShippingLaneStrict(id: string): ShippingLane`.
- `getShippingLanesByMode(mode: LaneMode, lanes?: readonly ShippingLane[]):
  ShippingLane[]`.
- `getAllShippingLanes(): readonly ShippingLane[]`.

## Implementation Notes

The lane id index is built lazily on first call and cached at module
scope for the lifetime of the process. `getAllShippingLanes` returns
the curated registry directly rather than a copy — callers must not
mutate it. Filtering helpers return fresh arrays so callers retain
mutation safety on derived sets.