Initial Commit

packages/geospatial/logistics/ports/src/lane-lookup/lane-lookup.md

@@ -0,0 +1,67 @@
+# 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.