@zukall/zap 0.2.2 → 0.3.0

package/PROTOCOL.md

@@ -1,7 +1,7 @@
 # ZAP — Zukall Addressing Protocol, version 2
 
 Protocol 2 uses **100-meter grid blocks** and **1-meter detail**, computed from
-unrounded projected GPS coordinates. The npm package version (`0.2.2`) and
+unrounded projected GPS coordinates. The npm package version (`0.3.0`) and
 protocol version (`2`) are separate. Previously issued protocol-1 addresses retain
 their original text and identity; see [PROTOCOL-V1.md](PROTOCOL-V1.md).
 

package/README.md

@@ -1,19 +1,51 @@
 # ZAP — Zukall Addressing Protocol
 
 **`@zukall/zap`** generates addresses directly from latitude and longitude using
-fixed country/province grids. Protocol **2** encodes **100-meter blocks** and
-separate **whole-meter remainders**. It needs no Google Places API, geocoding
-service, network request, or runtime dependency. Generation works offline.
+fixed country/province grids.
+
+**Give real places a recognizable address, without waiting for street names or
+house numbers.**
+
+Imagine building a courier application that serves Uganda, Haiti, Florida in
+the United States, and Germany. Your couriers and remote dispatchers need to
+recognize addresses quickly, even when those places use different languages,
+street names, and numbering systems.
+
+With ZAP, they learn one address format and use it across the configured
+countries and states. A home, business, rural entrance, or pickup point can have
+an address based on its GPS location. A dispatcher can read the same address
+structure in each market. Your application can show a courier where a
+destination lies relative to their current location in the same grid, then open
+map directions using the destination’s saved GPS point.
+
+Once you have the GPS coordinates, you can generate the address offline,
+without a geocoding service, API key, or per-address fee. ZAP works alongside
+existing street addresses and also gives you a location address where street
+names or house numbers are missing.
 
 ## See how ZAP works: Haiti’s grid
 
-These illustrations show locations in the same fixed Haiti grid. Each address
-is derived independently from its coordinates. The road can run north–south,
-east–west, diagonally, or curve; the grid origin and axes stay fixed.
+ZAP starts with a configured rectangle around a country. Where a country uses
+province or state grids, it uses the selected province’s rectangle instead—for
+example, Florida’s grid within the United States.
+
+Each rectangle has a fixed center and two axes: north/south and east/west.
+Think of laying a grid of **100 × 100-meter square blocks** across the area.
+The main address numbers count complete blocks from the center, and the
+direction letters tell you which side of the center the location is on.
+
+A suffix such as **`#23-43`** adds the position within that block: 23 whole meters
+along the address’s north/south direction and 43 along its east/west direction.
+That gives a home, entrance, or pickup point a location code with whole-meter
+detail. Keep apartment and unit numbers alongside the code as separate details.
+
+The Haiti illustrations below show the same fixed grid in use. Each address
+comes from its own GPS point. Roads can run straight, diagonally, or curve;
+the grid’s center and axes stay fixed.
 
 ### Whole-country grid and fixed center
 
-![Haiti’s entire configured ZAP grid, its fixed center in the Gulf of Gonâve, and a GPS-to-address example](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.2/asset/zukall-haiti-country-grid.webp)
+![Haiti’s entire configured ZAP grid, its fixed center in the Gulf of Gonâve, and a GPS-to-address example](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.3/asset/zukall-haiti-country-grid.webp)
 
 The Haiti grid has one fixed center: **19.0578675° N, 73.0641385° W**.
 It is the center of the configured rectangle, in the Gulf of Gonâve, rather than
@@ -44,7 +76,7 @@ The examples and captions below use the current dashed format.
 
 ### North–south: easting stays fixed
 
-![Haiti ZAP grid with five north–south locations, constant easting, and 100-meter projected intervals](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.2/asset/zukall-north-south-example.webp)
+![Haiti ZAP grid with five north–south locations, constant easting, and 100-meter projected intervals](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.3/asset/zukall-north-south-example.webp)
 
 ```text
 Point A: 580 S 772 E #42-68, HT ZAP
@@ -58,7 +90,7 @@ Moving north on this side of the origin decreases the south block.
 
 ### East–west: northing stays fixed
 
-![Haiti ZAP grid with five east–west locations, constant south offset, and 100-meter projected intervals](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.2/asset/zukall-west-east.webp)
+![Haiti ZAP grid with five east–west locations, constant south offset, and 100-meter projected intervals](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.3/asset/zukall-west-east.webp)
 
 ```text
 Point A: 582 S 770 E #42-68, HT ZAP
@@ -72,7 +104,7 @@ Moving west on this side of the origin decreases the east block.
 
 ### Diagonal streets: both axes can change
 
-![Haiti ZAP grid over a diagonal street, showing changing south and east offsets with a fixed grid](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.2/asset/zukall-diagnol-example.webp)
+![Haiti ZAP grid over a diagonal street, showing changing south and east offsets with a fixed grid](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.3/asset/zukall-diagnol-example.webp)
 
 ```text
 Point A: 580 S 770 E #43-46, HT ZAP
@@ -191,7 +223,7 @@ npm install @zukall/zap
 Before publication, install the verified local package:
 
 ```sh
-npm install /absolute/path/to/zukall-address-protocol/.artifacts/zukall-zap-0.2.2.tgz
+npm install /absolute/path/to/zukall-address-protocol/.artifacts/zukall-zap-0.3.0.tgz
 ```
 
 Build and verify the source:
@@ -449,6 +481,196 @@ API key. You can also pass `saved.coordinates` to your own map provider. Never
 use the formatted ZAP string, grid center, city name, or coordinate suffix as the
 routing destination.
 
+## Measure distance between locations
+
+**ZAP’s strongest advantage here is making distance understandable to people;
+software can handle either easily.** Within one grid, a difference of three
+blocks along an axis represents 300 projected meters. That is easier for a
+person to read than comparing decimal GPS coordinates. Software can calculate
+distance from either representation.
+
+Use complete saved records whenever available. `getDistance` defaults to the
+original GPS coordinates, including when the records come from different
+countries, states, or protocol versions:
+
+```js
+import { generateAddress, getDistance } from "@zukall/zap";
+
+const depot = generateAddress({
+  countryCode: "UG", city: "Kampala", latitude: 0.3476, longitude: 32.5825,
+});
+const pickup = generateAddress({
+  countryCode: "UG", city: "Kampala", latitude: 0.3486, longitude: 32.5825,
+});
+
+const distance = getDistance(depot, pickup);
+console.log(distance.method); // haversine
+console.log(distance.meters.toFixed(1)); // 111.2
+console.log(distance.kilometers.toFixed(4)); // 0.1112
+
+// Latitude/longitude objects also work.
+getDistance(depot.coordinates, pickup.coordinates);
+
+// Optional distance in the saved grid's projected plane.
+const gridDistance = getDistance(depot, pickup, { method: "projected" });
+console.log(gridDistance.method); // projected
+console.log(gridDistance.gridId === depot.gridId); // true
+```
+
+Haversine measures the geographic great-circle distance on a sphere, using the
+same **6,371,008.8-meter Earth radius** as the address projection. Values retain
+number precision; rounding above is only for display. It does not measure road
+length, altitude, or terrain.
+
+Projected mode uses `Math.hypot()` on the stored northing/easting differences.
+Both records must have **exactly the same `gridId`** and finite offsets. A
+different country, province, snapshot, or encoding ID is rejected. This mode
+does not regenerate addresses or reproject older records; protocol-1 offsets
+can retain their original snapping. Projected-plane distances can differ from
+geographic distances away from the grid origin. Neither mode parses the address
+text, subtracts unit numbers, or treats the suffix as a house number.
+
+## Optimize randomly entered stops
+
+`optimizeRoute` returns an **optimized straight-line itinerary**. It chooses an
+order that reduces the sum of distances between consecutive stops. Your
+application can use that order to plan visits, then open map directions from
+each stop's saved GPS point. It does not provide driving directions or guarantee
+the shortest journey along roads.
+
+This example uses illustrative GPS points along a meridian, entered out of order:
+
+```js
+import { generateAddress, optimizeRoute } from "@zukall/zap";
+
+const stop = (id, latitude) => ({
+  id,
+  ...generateAddress({
+    countryCode: "UG", city: "Kampala", latitude, longitude: 32.5825,
+  }),
+});
+const stops = [
+  stop("depot", 0.3476),
+  stop("C", 0.3506),
+  stop("A", 0.3486),
+  stop("B", 0.3496),
+];
+
+const itinerary = optimizeRoute(stops);
+console.log(itinerary.description); // optimized straight-line itinerary
+console.log(itinerary.orderedStops.map(stop => stop.id)); // ["depot", "A", "B", "C"]
+console.log(itinerary.originalIndices); // [0, 2, 3, 1]
+console.log(itinerary.totalMeters.toFixed(1)); // 333.6
+console.log(itinerary.originalTotalMeters.toFixed(1)); // 667.2
+console.log(itinerary.optimization); // exact
+console.log(itinerary.algorithm); // held-karp
+console.log(itinerary.method); // haversine
+
+for (const leg of itinerary.legs) {
+  console.log(stops[leg.fromIndex].id, stops[leg.toIndex].id, leg.meters);
+}
+
+// Select endpoints by their ORIGINAL input indices.
+const fixedEndpoints = optimizeRoute(stops, { startIndex: 2, endIndex: 1 });
+// Starts at A (input 2), finishes at C (input 1), and includes every other stop.
+
+const roundTrip = optimizeRoute(stops, { returnToStart: true });
+console.log(roundTrip.legs.at(-1).isReturn); // true
+// orderedStops still includes the depot only once; legs include the return to it.
+```
+
+| Option | Behavior |
+| --- | --- |
+| `startIndex` | Fixed start selected from the supplied stops; defaults to input index `0`. |
+| `endIndex` | Optional fixed final stop, selected by original index. |
+| `returnToStart` | Adds a closing leg to the start; defaults to `false` and cannot be combined with `endIndex`. |
+| `method` | `"haversine"` by default, or `"projected"` when every saved record has the identical grid ID. |
+| `resolveAddress` | Caller-owned lookup for address strings; supplying it makes the call return a Promise. |
+| `distanceMatrix` | Optional meter costs indexed by original stop indices; cannot be combined with `method`. |
+
+Endpoints must be supplied stops. If a depot is outside your delivery list,
+include it in `points` and select its index. An open itinerary with multiple
+stops cannot have the same start and end; choose `returnToStart` for that case.
+
+The result contains the original objects or strings in `orderedStops`, their
+`originalIndices`, `resolvedPoints` in the same order, and `legs` with
+`fromIndex`, `toIndex`, meters, kilometers, method, and `isReturn`. Totals are
+available as `totalMeters` and `totalKilometers`. Inputs and saved addresses are
+not modified. Duplicate coordinates and duplicate references remain separate
+stops and retain their own indices.
+
+### Exact and approximate optimization
+
+- **Up to 12 stops:** Held–Karp subset dynamic programming finds an exact minimum
+  for the selected distance costs and endpoint constraints.
+- **13–1000 stops:** Deterministic nearest neighbor followed by 2-opt returns an
+  approximate order. Both the nearest-neighbor order and the original feasible
+  order are improved, with at most 100 2-opt passes per seed. Fixed endpoints
+  remain fixed. Results are never longer than the original feasible order.
+
+`optimization` reports `"exact"` or `"approximate"`; `algorithm` names the
+algorithm, and `exactCutoff` is `12`. Equal-cost choices use original input
+indices deterministically. `ROUTE_OPTIMIZATION` exports the frozen work limits.
+The original feasible order moves the selected start first and end last, keeping
+the other stops in their entered order; its cost is `originalTotalMeters`.
+
+Empty lists and single stops return an exact zero-distance itinerary with no
+legs, even for a round trip. Explicit endpoint indices must still be valid.
+Invalid coordinates, sparse arrays, contradictory endpoints, and lists above
+1000 stops are rejected. Optimizing many stops uses a quadratic distance matrix;
+approximate results are not a guarantee of the best possible order.
+
+### Address strings need saved-record lookups
+
+The package has **no reverse decoder or automatic geocoder**. A text-only ZAP
+address cannot restore the original GPS point. Supply a resolver that retrieves
+the corresponding saved record; it may return the record directly or use an
+asynchronous database lookup:
+
+```js
+const savedByAddress = new Map(stops.map(record => [record.address, record]));
+const resolveAddress = async (address, originalIndex) => {
+  const record = savedByAddress.get(address);
+  if (!record) throw new Error(`No saved GPS record for input ${originalIndex}`);
+  return record;
+};
+
+const textStops = stops.map(record => record.address);
+const itineraryFromText = await optimizeRoute(textStops, { resolveAddress });
+const distanceFromText = await getDistance(textStops[0], textStops[1], { resolveAddress });
+```
+
+Resolvers receive each string and its original input index (0/1 for
+`getDistance`), once per string occurrence. The original strings remain in
+`orderedStops`; retrieved records are in `resolvedPoints`. A resolver must return
+a saved record with valid `coordinates`; missing records and lookup failures
+reject the Promise. Direct GPS/record calls without a resolver stay synchronous.
+Use full records and your own stop IDs when addresses are shared by different
+units or records; an address string alone does not identify a unique household.
+
+### Supplying distance costs from another provider
+
+The optimizer consumes a distance matrix internally. Your application can supply
+one from a future road-distance provider without changing stop identities:
+
+```js
+const matrix = [
+  [0, 400, 100],
+  [350, 0, 200],
+  [120, 220, 0],
+];
+const suppliedCosts = optimizeRoute(stops.slice(0, 3), { distanceMatrix: matrix });
+console.log(suppliedCosts.method); // distance-matrix
+console.log(suppliedCosts.description); // optimized distance-matrix itinerary
+```
+
+Rows/columns follow **original input order**, entries are nonnegative finite
+**meters**, and the diagonal must be zero. Matrices may be asymmetric; both
+algorithms account for the full cost of reversing directed legs. Values must
+leave room for finite route totals. The package does not fetch provider data.
+Results are labeled separately when caller-supplied costs are used. The function
+still returns a stop order, not driving instructions or a vehicle scheduling plan.
+
 ## Upgrade from protocol 1 without changing issued addresses
 
 Package `0.2.0` introduces protocol 2. `generateAddress` no longer accepts
@@ -544,6 +766,9 @@ See [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) and [PROTOCOL.md](PROTOCOL.
 | `generateAddress(input)` | Generate a protocol-2 address with fixed 100-meter blocks and 1-meter detail. |
 | `generateLegacyAddress(input)` | Explicitly reproduce the original protocol-1 address and grid ID. |
 | `getDirectionsUrl(savedRecord)` | Build directions using original saved GPS coordinates, for either version. |
+| `getDistance(pointA, pointB, options?)` | Haversine meters/kilometers from GPS, or projected distance within one exact grid ID. |
+| `optimizeRoute(points, options?)` | Exact or approximate stop order, original indices, legs and totals for an optimized straight-line itinerary. |
+| `ROUTE_OPTIMIZATION` | Inspect the 12-stop exact cutoff, 1000-stop limit and 100-pass heuristic work bound. |
 | `getCountries()` / `getCountry(code)` | Select or inspect immutable country configurations. |
 | `getProvinces(code)` | List configured provinces; country-wide grids return `[]`. |
 | `ZAP_PROTOCOL` / `LEGACY_ZAP_PROTOCOL` | Read current or original protocol constants. |
@@ -562,7 +787,11 @@ Tests cover the requested formats, all directions, zero and sub-meter negatives,
 99/100-meter boundaries, two-digit suffixes, country/province selection, unchanged
 grid identity components, date-line rectangles, diagonal sequences, 100-meter
 axis movements, old-address compatibility, saved GPS directions, and all centers
-and corners of 747 configured grids. Package verification checks ESM/CommonJS
+and corners of 747 configured grids. Distance/itinerary tests check known
+distances, mixed grids, endpoints, return legs, duplicate identities, explicit
+resolvers, and exact solutions against an independent exhaustive search.
+Heuristics are checked against the original feasible order, including directed
+matrices. Package verification checks ESM/CommonJS
 runtime exports and compiles both TypeScript consumer formats, including the
 removed-option error.
 
@@ -571,11 +800,11 @@ removed-option error.
 ```sh
 npm login
 npm run pack:check
-npm publish ./.artifacts/zukall-zap-0.2.2.tgz --access public
+npm publish ./.artifacts/zukall-zap-0.3.0.tgz --access public
 ```
 
 An npm account with permission to publish `@zukall/zap` is required. Building and
-packing do not publish the package. Package version is `0.2.2`; current protocol
+packing do not publish the package. Package version is `0.3.0`; current protocol
 version is `2`, while preserved legacy results remain version `1`.
 
 ## License

package/dist/cjs/distance.d.ts

@@ -0,0 +1,8 @@
+import type { Coordinates, DistanceMethod, DistanceOptions, DistanceResult, LocationInput, LocationPoint, ResolvedDistanceOptions } from "./types.js";
+export declare function getDistanceMethod(method: DistanceMethod | undefined): DistanceMethod;
+/** Geographic great-circle surface distance, using the existing spherical Earth radius. */
+export declare function haversineMeters(pointA: Coordinates, pointB: Coordinates): number;
+export declare function requireFiniteDistance(meters: number): number;
+export declare function getDistance(pointA: LocationPoint, pointB: LocationPoint, options?: DistanceOptions): DistanceResult;
+export declare function getDistance(pointA: LocationInput, pointB: LocationInput, options: ResolvedDistanceOptions): Promise<DistanceResult>;
+export declare function getDistance(pointA: LocationPoint, pointB: LocationPoint, options: DistanceOptions | ResolvedDistanceOptions): DistanceResult | Promise<DistanceResult>;

package/dist/cjs/distance.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDistanceMethod = getDistanceMethod;
+exports.haversineMeters = haversineMeters;
+exports.requireFiniteDistance = requireFiniteDistance;
+exports.getDistance = getDistance;
+const protocol_js_1 = require("./protocol.js");
+const locations_js_1 = require("./locations.js");
+function getDistanceMethod(method) {
+    if (method !== undefined && method !== "haversine" && method !== "projected") {
+        throw new TypeError("method must be haversine or projected.");
+    }
+    return method ?? "haversine";
+}
+/** Geographic great-circle surface distance, using the existing spherical Earth radius. */
+function haversineMeters(pointA, pointB) {
+    const radians = (degrees) => degrees * Math.PI / 180;
+    const latitudeA = radians(pointA.latitude);
+    const latitudeB = radians(pointB.latitude);
+    let longitudeDifference = pointB.longitude - pointA.longitude;
+    if (longitudeDifference > 180)
+        longitudeDifference -= 360;
+    if (longitudeDifference < -180)
+        longitudeDifference += 360;
+    const cosineA = Math.abs(pointA.latitude) === 90 ? 0 : Math.cos(latitudeA);
+    const cosineB = Math.abs(pointB.latitude) === 90 ? 0 : Math.cos(latitudeB);
+    const haversine = Math.sin(radians(pointB.latitude - pointA.latitude) / 2) ** 2
+        + cosineA * cosineB * Math.sin(radians(longitudeDifference) / 2) ** 2;
+    const clamped = Math.max(0, Math.min(1, haversine));
+    return 2 * protocol_js_1.ZAP_PROTOCOL.earthRadiusMeters * Math.atan2(Math.sqrt(clamped), Math.sqrt(1 - clamped));
+}
+function requireFiniteDistance(meters) {
+    if (!Number.isFinite(meters) || meters < 0)
+        throw new RangeError("Distance must be finite and nonnegative.");
+    return meters === 0 ? 0 : meters;
+}
+function calculateDistance(points, method) {
+    const pointA = points[0];
+    const pointB = points[1];
+    const coordinatesA = (0, locations_js_1.getLocationCoordinates)(pointA);
+    const coordinatesB = (0, locations_js_1.getLocationCoordinates)(pointB);
+    if (method === "projected") {
+        const gridA = (0, locations_js_1.getProjectedPoint)(pointA);
+        const gridB = (0, locations_js_1.getProjectedPoint)(pointB);
+        if (gridA.gridId !== gridB.gridId) {
+            throw new RangeError("Projected distance requires exactly the same gridId.");
+        }
+        const meters = requireFiniteDistance(Math.hypot(gridB.northingMeters - gridA.northingMeters, gridB.eastingMeters - gridA.eastingMeters));
+        return { method, meters, kilometers: meters / 1000, gridId: gridA.gridId };
+    }
+    const meters = requireFiniteDistance(haversineMeters(coordinatesA, coordinatesB));
+    return { method, meters, kilometers: meters / 1000 };
+}
+/** GPS by default; supplying a resolver returns a Promise and never silently geocodes text. */
+function getDistance(pointA, pointB, options = {}) {
+    (0, locations_js_1.validateLocationOptions)(options);
+    const method = getDistanceMethod(options.method);
+    const resolved = (0, locations_js_1.resolveLocationPoints)([pointA, pointB], options.resolveAddress);
+    return resolved instanceof Promise
+        ? resolved.then(points => calculateDistance(points, method)) : calculateDistance(resolved, method);
+}

package/dist/cjs/index.d.ts

@@ -1,10 +1,12 @@
 import { generateAddress } from "./address.js";
 import { generateLegacyAddress } from "./legacy-address.js";
 import { getDirectionsUrl } from "./directions.js";
+import { getDistance } from "./distance.js";
+import { optimizeRoute, ROUTE_OPTIMIZATION } from "./route.js";
 import { getCountries, getCountry, getProvinces } from "./country.js";
 import { ZAP_PROTOCOL, LEGACY_ZAP_PROTOCOL } from "./protocol.js";
-export { generateAddress, generateLegacyAddress, getDirectionsUrl, getCountries, getCountry, getProvinces, ZAP_PROTOCOL, LEGACY_ZAP_PROTOCOL, };
-export type { AddressInput, AddressResult, AddressEncoding, LegacyAddressInput, LegacyAddressResult, Coordinates, Corners, GridInput, Country, CountryOption, Province, ProvinceCountry, ProvinceOption, } from "./types.js";
+export { generateAddress, generateLegacyAddress, getDirectionsUrl, getDistance, optimizeRoute, ROUTE_OPTIMIZATION, getCountries, getCountry, getProvinces, ZAP_PROTOCOL, LEGACY_ZAP_PROTOCOL, };
+export type { AddressInput, AddressResult, AddressEncoding, LegacyAddressInput, LegacyAddressResult, Coordinates, Corners, GridInput, Country, CountryOption, Province, ProvinceCountry, ProvinceOption, SavedLocationPoint, LocationPoint, LocationInput, AddressResolver, DistanceMethod, RouteDistanceMethod, DistanceOptions, ResolvedDistanceOptions, DistanceResult, DistanceMatrix, RouteOptions, ResolvedRouteOptions, RouteLeg, RouteResult, } from "./types.js";
 /** Named namespace for applications that refer to the protocol as `zap`. */
 export declare const zap: Readonly<{
     protocol: Readonly<{
@@ -21,6 +23,13 @@ export declare const zap: Readonly<{
     generateAddress: typeof generateAddress;
     generateLegacyAddress: typeof generateLegacyAddress;
     getDirectionsUrl: typeof getDirectionsUrl;
+    getDistance: typeof getDistance;
+    optimizeRoute: typeof optimizeRoute;
+    routeOptimization: Readonly<{
+        readonly exactMaxStops: 12;
+        readonly maxStops: 1000;
+        readonly twoOptMaxPasses: 100;
+    }>;
     getCountries: typeof getCountries;
     getCountry: typeof getCountry;
     getProvinces: typeof getProvinces;

package/dist/cjs/index.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.zap = exports.LEGACY_ZAP_PROTOCOL = exports.ZAP_PROTOCOL = exports.getProvinces = exports.getCountry = exports.getCountries = exports.getDirectionsUrl = exports.generateLegacyAddress = exports.generateAddress = void 0;
+exports.zap = exports.LEGACY_ZAP_PROTOCOL = exports.ZAP_PROTOCOL = exports.getProvinces = exports.getCountry = exports.getCountries = exports.ROUTE_OPTIMIZATION = exports.optimizeRoute = exports.getDistance = exports.getDirectionsUrl = exports.generateLegacyAddress = exports.generateAddress = void 0;
 const address_js_1 = require("./address.js");
 Object.defineProperty(exports, "generateAddress", { enumerable: true, get: function () { return address_js_1.generateAddress; } });
 const legacy_address_js_1 = require("./legacy-address.js");
 Object.defineProperty(exports, "generateLegacyAddress", { enumerable: true, get: function () { return legacy_address_js_1.generateLegacyAddress; } });
 const directions_js_1 = require("./directions.js");
 Object.defineProperty(exports, "getDirectionsUrl", { enumerable: true, get: function () { return directions_js_1.getDirectionsUrl; } });
+const distance_js_1 = require("./distance.js");
+Object.defineProperty(exports, "getDistance", { enumerable: true, get: function () { return distance_js_1.getDistance; } });
+const route_js_1 = require("./route.js");
+Object.defineProperty(exports, "optimizeRoute", { enumerable: true, get: function () { return route_js_1.optimizeRoute; } });
+Object.defineProperty(exports, "ROUTE_OPTIMIZATION", { enumerable: true, get: function () { return route_js_1.ROUTE_OPTIMIZATION; } });
 const country_js_1 = require("./country.js");
 Object.defineProperty(exports, "getCountries", { enumerable: true, get: function () { return country_js_1.getCountries; } });
 Object.defineProperty(exports, "getCountry", { enumerable: true, get: function () { return country_js_1.getCountry; } });
@@ -20,6 +25,9 @@ exports.zap = Object.freeze({
     generateAddress: address_js_1.generateAddress,
     generateLegacyAddress: legacy_address_js_1.generateLegacyAddress,
     getDirectionsUrl: directions_js_1.getDirectionsUrl,
+    getDistance: distance_js_1.getDistance,
+    optimizeRoute: route_js_1.optimizeRoute,
+    routeOptimization: route_js_1.ROUTE_OPTIMIZATION,
     getCountries: country_js_1.getCountries,
     getCountry: country_js_1.getCountry,
     getProvinces: country_js_1.getProvinces,

package/dist/cjs/locations.d.ts

@@ -0,0 +1,11 @@
+import type { AddressResolver, Coordinates, LocationInput, LocationPoint, SavedLocationPoint } from "./types.js";
+export declare function validateLocationOptions(options: unknown): void;
+/** Read original GPS only; never parse text, grid blocks, unit numbers, or suffixes. */
+export declare function getLocationCoordinates(point: LocationPoint): Coordinates;
+export declare function resolveLocationPoints(points: readonly LocationInput[], resolver: AddressResolver | undefined): LocationPoint[] | Promise<LocationPoint[]>;
+export type ProjectedPoint = SavedLocationPoint & Readonly<{
+    gridId: string;
+    northingMeters: number;
+    eastingMeters: number;
+}>;
+export declare function getProjectedPoint(point: LocationPoint): ProjectedPoint;

package/dist/cjs/locations.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateLocationOptions = validateLocationOptions;
+exports.getLocationCoordinates = getLocationCoordinates;
+exports.resolveLocationPoints = resolveLocationPoints;
+exports.getProjectedPoint = getProjectedPoint;
+const grid_js_1 = require("./grid.js");
+function validateLocationOptions(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("Options must be an object.");
+    }
+    if ("resolveAddress" in options && options.resolveAddress !== undefined && typeof options.resolveAddress !== "function") {
+        throw new TypeError("resolveAddress must be a function.");
+    }
+}
+/** Read original GPS only; never parse text, grid blocks, unit numbers, or suffixes. */
+function getLocationCoordinates(point) {
+    if (!point || typeof point !== "object" || Array.isArray(point)) {
+        throw new TypeError("A latitude/longitude object or a saved record with coordinates is required.");
+    }
+    const coordinates = "coordinates" in point ? point.coordinates : point;
+    if (!coordinates || typeof coordinates !== "object" || Array.isArray(coordinates)) {
+        throw new TypeError("A saved record must contain its original GPS coordinates.");
+    }
+    (0, grid_js_1.validateCoordinates)(coordinates);
+    return { latitude: coordinates.latitude, longitude: coordinates.longitude };
+}
+function validateResolvedRecord(record) {
+    if (!record || typeof record !== "object" || Array.isArray(record) || !("coordinates" in record)) {
+        throw new TypeError("resolveAddress must return a saved record with original GPS coordinates.");
+    }
+    getLocationCoordinates(record);
+    return record;
+}
+function resolveLocationPoints(points, resolver) {
+    const checkString = (point) => {
+        if (!point.trim())
+            throw new TypeError("An address string must be nonempty.");
+    };
+    if (resolver !== undefined) {
+        // Promise.all installs rejection handlers for every asynchronous lookup.
+        return Promise.all(points.map(async (point, originalIndex) => {
+            if (typeof point === "string") {
+                checkString(point);
+                return validateResolvedRecord(await resolver(point, originalIndex));
+            }
+            getLocationCoordinates(point);
+            return point;
+        }));
+    }
+    return points.map(point => {
+        if (typeof point === "string") {
+            checkString(point);
+            throw new TypeError("Address strings require resolveAddress; ZAP has no reverse decoder or automatic geocoder.");
+        }
+        getLocationCoordinates(point);
+        return point;
+    });
+}
+function getProjectedPoint(point) {
+    if (!("coordinates" in point) || !("gridId" in point) || typeof point.gridId !== "string" || !point.gridId.trim()
+        || !("northingMeters" in point) || !Number.isFinite(point.northingMeters)
+        || !("eastingMeters" in point) || !Number.isFinite(point.eastingMeters)) {
+        throw new TypeError("Projected distance requires saved records with a gridId and finite northingMeters/eastingMeters.");
+    }
+    return point;
+}

package/dist/cjs/route.d.ts

@@ -0,0 +1,10 @@
+import type { LocationInput, LocationPoint, ResolvedRouteOptions, RouteOptions, RouteResult } from "./types.js";
+/** Work limits are separate from address protocol/configuration versions. */
+export declare const ROUTE_OPTIMIZATION: Readonly<{
+    readonly exactMaxStops: 12;
+    readonly maxStops: 1000;
+    readonly twoOptMaxPasses: 100;
+}>;
+export declare function optimizeRoute<T extends LocationPoint>(points: readonly T[], options?: RouteOptions): RouteResult<T>;
+export declare function optimizeRoute<T extends LocationInput>(points: readonly T[], options: ResolvedRouteOptions): Promise<RouteResult<T>>;
+export declare function optimizeRoute<T extends LocationPoint>(points: readonly T[], options: RouteOptions | ResolvedRouteOptions): RouteResult<T> | Promise<RouteResult<T>>;