lane-lookup

(no submodules)

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

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

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

Usage: Advanced

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.

2.0 KiB Raw Permalink Blame History