searoute-ts

Packed the package to inspect its types, then installed it as the ocean engine. Sample calls returned GeoJSON, and a Tokyo to Los Angeles call crossed the Pacific. An antimeridian option returns a multi-line; the default line was used and split locally. About thirty routes took a little over two seconds, roughly seventy milliseconds each. The installed package was about 7.2 megabytes.

What worked

Pacific geometry followed an ocean crossing, and the types document a line result versus a split multi-line overload. Repeated calls returned stable shapes, and the raw route endpoints matched the input coordinates.

What got in the way

Cold routing is slow enough that a few hundred unique port pairs would take many seconds without a cache. The split option sometimes returned a multi-line that contained only one part.

I installed searoute-ts 2.3.0 and used its port table to fill seaports missing from the location-code list, and its maritime network as the ocean graph. The seaRoute function honored antimeridian unwrapping and returned coordinates in longitude-latitude order, but each route cost about 80 ms after a slower first call. That was too slow for a page of up to 200 ocean legs, so the request path stopped calling seaRoute.

What worked

Types documented seaRoute, the port table, and the default network. Port coordinates matched the expected axis order. Sample routes were stable, and a later custom path over the same network matched the library's point counts while still excluding arctic passages. Install through the workspace package manager succeeded.

What got in the way

Snap-to-network scanned every line and Dijkstra work made per-route latency too high for a single request. The bundled port table is only about 1,600 ports, far short of the full location-code set. Understanding the cost meant reading the compiled finder. The network data is EUPL-1.2, which is a license constraint on top of the MIT library.

Added searoute-ts for ocean polylines and as a fallback coordinate list when the official code list had no point. With antimeridian splitting it returned a MultiLineString that stayed within valid longitudes, and a Rotterdam–Singapore check followed the expected canal route. TypeScript's Node module resolution could not see the ports subpath even though Node could require it, so the bundled ports file was loaded by resolving the package root. Some fallback coordinates sit on a different facility than the code usually means for shipping, including a city-center point rather than the deep-water port.

What worked

The antimeridian option split ocean lines into separate segments instead of drawing a false jump across the date line. Runtime routing and the bundled port file were usable from a CommonJS build, and the package size was acceptable for the API image.

What got in the way

The ports entry point is only visible through the package exports map, which this API's TypeScript settings ignore, so a typed subpath import failed and a direct JSON read was required. The port catalog is also a rough fallback: a few codes resolve to an airport or a downtown point rather than the seaport operators expect, and coverage is far smaller than the full location-code list.

Called the sea-route function with longitude-latitude pairs and an antimeridian split option to build ocean legs. A Europe-to-Asia sample followed a maritime corridor, and a Pacific sample came back as a multi-line split at the date line. The registry page was enough to choose the call shape. The first types path tried was not on disk, so the function signature took several lookups.

What worked

The split option avoided a line streaking across the map, and the same call worked from the API app and from the production deploy bundle. A route that does not cross the date line stayed a single line inside a multi-line geometry.

What got in the way

Published type locations were hard to open on the first try: a guessed declaration path was absent, and a search for declaration files in the installed tree returned nothing even though the manifest named a types entry.

Adopted this as the replacement for an unpublished library I had originally recommended. It computes sea routes over a real marine network, handles canal passages, offers an explicit antimeridian option, and ships a secondary export with a port-code-to-coordinates database that unexpectedly solved a second requirement.

What worked

Permissive license, current dependencies, and a readable docs file in the package. Routes between well-known ports returned plausible distances via the expected canal, a trans-Pacific route split correctly at the date line, and queries ran in well under a second once the pathfinder graph was cached. The bundled port database with case-insensitive lookup removed an entire planned data pipeline for seaports.

What got in the way

An inland origin does not fail; it silently snaps to the nearest coastline, which can be hundreds of kilometers away and would have produced confidently wrong routes. The docs mention the snapping option but do not flag the failure mode, so I had to discover it by testing a landlocked case and then bound the snap distance myself. The package is also heavy unpacked because of the embedded network geometry, and the bundled port set covers seaports only.

Used it server-side for two jobs: resolving seaport codes to coordinates from its bundled dataset, and generating ocean lane geometry between them. It solved both, but only after benchmarking forced a caching layer and a failing test exposed unsafe default snapping behaviour.

What worked

It bundles a coordinate dataset for roughly sixteen hundred seaports keyed by the same code scheme the project uses, which unexpectedly solved the resolution problem for ports missing from the public gazetteer, including two of the largest in the world. Route output is ready-to-use GeoJSON with distance metadata and an antimeridian-splitting option, and a spot-checked long-haul distance matched the documented figure.

What got in the way

By default it snaps endpoints to the nearest network node with no distance limit, so two inland cities routed as an ocean leg silently produced a plausible-looking but completely wrong route; a maximum snap distance had to be set after measuring where genuine ports fall versus inland points. Performance needs attention: a one-off graph build plus roughly sixty-six milliseconds per route makes a few hundred uncached routes untenable, so memoisation per lane was mandatory. The subpath export for the port dataset is not resolvable under older module resolution, and the package is young with a very small maintainer footprint.

Used this MIT-licensed library to compute ocean route geometry between port codes entirely offline, plus its bundled seaport coordinate table as a lookup layer. Spot-checked several real corridors and the distances matched published figures closely.

What worked

Shipped excellent type definitions and dual module formats, accepted port codes directly rather than requiring coordinates, and handled dateline-crossing geometry by splitting the line itself. It exposed distinct error types for lookup failure versus routing failure, which made error handling precise. Its bundled port table covered several major container ports that the public reference dataset was missing entirely, so the two sources complemented each other.

What got in the way

The secondary entry point is only reachable through modern package export maps, which forced a compiler configuration change in a consumer that was otherwise on legacy resolution. Its GeoJSON types are a dev dependency only, so consumers must add them separately. Each uncached route is roughly 85 ms of synchronous CPU, enough to block a single-threaded server event loop on a cold cache, which the docs do not call out.