@zukall/zap 0.2.2 → 0.3.0

package/dist/cjs/route.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTE_OPTIMIZATION = void 0;
+exports.optimizeRoute = optimizeRoute;
+const distance_js_1 = require("./distance.js");
+const locations_js_1 = require("./locations.js");
+/** Work limits are separate from address protocol/configuration versions. */
+exports.ROUTE_OPTIMIZATION = Object.freeze({
+    exactMaxStops: 12, maxStops: 1000, twoOptMaxPasses: 100,
+});
+const at = (matrix, from, to) => matrix[from][to];
+function validateEndpoint(index, count, name) {
+    if (index !== undefined && (!Number.isSafeInteger(index) || index < 0 || index >= count)) {
+        throw new RangeError(`${name} must be an original input index within points.`);
+    }
+}
+function validateRouteOptions(points, options) {
+    (0, locations_js_1.validateLocationOptions)(options);
+    if (!Array.isArray(points))
+        throw new TypeError("points must be an array of locations.");
+    if (points.length > exports.ROUTE_OPTIMIZATION.maxStops) {
+        throw new RangeError(`At most ${exports.ROUTE_OPTIMIZATION.maxStops} stops are supported per itinerary.`);
+    }
+    for (let index = 0; index < points.length; index++) {
+        if (!(index in points))
+            throw new TypeError("points must not contain empty slots.");
+    }
+    validateEndpoint(options.startIndex, points.length, "startIndex");
+    validateEndpoint(options.endIndex, points.length, "endIndex");
+    if (options.returnToStart !== undefined && typeof options.returnToStart !== "boolean") {
+        throw new TypeError("returnToStart must be a boolean.");
+    }
+    if (options.returnToStart && options.endIndex !== undefined) {
+        throw new RangeError("endIndex cannot be combined with returnToStart.");
+    }
+    if (points.length > 1 && options.endIndex === (options.startIndex ?? 0)) {
+        throw new RangeError("An open itinerary must have distinct startIndex/endIndex; use returnToStart for a round trip.");
+    }
+    (0, distance_js_1.getDistanceMethod)(options.method);
+    if (options.distanceMatrix !== undefined && options.method !== undefined) {
+        throw new TypeError("distanceMatrix cannot be combined with method.");
+    }
+}
+function validateMatrix(matrix, count) {
+    if (!Array.isArray(matrix) || matrix.length !== count) {
+        throw new RangeError("distanceMatrix must have one row and column per original input stop.");
+    }
+    // Reserve headroom so summing every leg is finite, including a closing leg.
+    const maximum = Number.MAX_VALUE / (count + 1);
+    return Array.from({ length: count }, (_, rowIndex) => {
+        const row = matrix[rowIndex];
+        if (!Array.isArray(row) || row.length !== count) {
+            throw new RangeError("distanceMatrix must have one row and column per original input stop.");
+        }
+        return Array.from({ length: count }, (_, columnIndex) => {
+            const value = row[columnIndex];
+            if (!Number.isFinite(value) || value < 0 || value > maximum || (rowIndex === columnIndex && value !== 0)) {
+                throw new RangeError("distanceMatrix entries must be finite nonnegative meters with a zero diagonal and finite route totals.");
+            }
+            return value;
+        });
+    });
+}
+function buildMatrix(points, options) {
+    const coordinates = points.map(locations_js_1.getLocationCoordinates);
+    if (options.distanceMatrix !== undefined) {
+        return { matrix: validateMatrix(options.distanceMatrix, points.length), method: "distance-matrix" };
+    }
+    const method = (0, distance_js_1.getDistanceMethod)(options.method);
+    const projected = method === "projected" ? points.map(locations_js_1.getProjectedPoint) : undefined;
+    const gridId = projected?.[0]?.gridId;
+    if (projected?.some(point => point.gridId !== gridId)) {
+        throw new RangeError("Projected distance requires exactly the same gridId for every stop.");
+    }
+    const matrix = Array.from({ length: points.length }, () => Array(points.length).fill(0));
+    for (let left = 0; left < points.length; left++) {
+        for (let right = left + 1; right < points.length; right++) {
+            const meters = (0, distance_js_1.requireFiniteDistance)(projected ? Math.hypot(projected[right].northingMeters - projected[left].northingMeters, projected[right].eastingMeters - projected[left].eastingMeters) : (0, distance_js_1.haversineMeters)(coordinates[left], coordinates[right]));
+            if (meters > Number.MAX_VALUE / (points.length + 1))
+                throw new RangeError("Route distances must have finite totals.");
+            matrix[left][right] = meters;
+            matrix[right][left] = meters;
+        }
+    }
+    return { matrix, method, ...(gridId !== undefined ? { gridId } : {}) };
+}
+function routeCost(order, matrix, closed) {
+    let total = 0;
+    for (let index = 1; index < order.length; index++)
+        total += at(matrix, order[index - 1], order[index]);
+    if (closed && order.length > 1)
+        total += at(matrix, order[order.length - 1], order[0]);
+    return (0, distance_js_1.requireFiniteDistance)(total);
+}
+function feasibleOrder(count, start, end) {
+    if (count === 0)
+        return [];
+    const order = [start];
+    for (let index = 0; index < count; index++)
+        if (index !== start && index !== end)
+            order.push(index);
+    if (end !== undefined && end !== start)
+        order.push(end);
+    return order;
+}
+/** Held–Karp subset dynamic programming, including directed matrices and endpoint constraints. */
+function exactOrder(matrix, start, end, closed) {
+    const count = matrix.length;
+    const free = Array.from({ length: count }, (_, index) => index).filter(index => index !== start && index !== end);
+    const size = free.length;
+    if (size === 0)
+        return feasibleOrder(count, start, end);
+    const states = 1 << size;
+    const costs = new Float64Array(states * size).fill(Infinity);
+    const keys = new Float64Array(states * size).fill(Infinity);
+    const parents = new Int16Array(states * size).fill(-1);
+    // Up to 12 base-13 digits fit exactly in a JS integer; keys settle equal-cost ties by input index.
+    const base = count + 1;
+    for (let last = 0; last < size; last++) {
+        const state = (1 << last) * size + last;
+        costs[state] = at(matrix, start, free[last]);
+        keys[state] = (start + 1) * base + free[last] + 1;
+    }
+    for (let mask = 1; mask < states; mask++) {
+        for (let last = 0; last < size; last++) {
+            if (!(mask & (1 << last)))
+                continue;
+            const state = mask * size + last;
+            if (!Number.isFinite(costs[state]))
+                continue;
+            for (let next = 0; next < size; next++) {
+                if (mask & (1 << next))
+                    continue;
+                const nextState = (mask | (1 << next)) * size + next;
+                const candidate = costs[state] + at(matrix, free[last], free[next]);
+                const key = keys[state] * base + free[next] + 1;
+                if (candidate < costs[nextState] || (candidate === costs[nextState] && key < keys[nextState])) {
+                    costs[nextState] = candidate;
+                    keys[nextState] = key;
+                    parents[nextState] = last;
+                }
+            }
+        }
+    }
+    const full = states - 1;
+    let bestCost = Infinity;
+    let bestKey = Infinity;
+    let last = -1;
+    for (let candidate = 0; candidate < size; candidate++) {
+        const state = full * size + candidate;
+        const destination = end ?? (closed ? start : undefined);
+        const cost = costs[state] + (destination === undefined ? 0 : at(matrix, free[candidate], destination));
+        if (cost < bestCost || (cost === bestCost && keys[state] < bestKey)) {
+            bestCost = cost;
+            bestKey = keys[state];
+            last = candidate;
+        }
+    }
+    const reversed = [];
+    let mask = full;
+    while (last >= 0) {
+        reversed.push(free[last]);
+        const previous = parents[mask * size + last];
+        mask ^= 1 << last;
+        last = previous;
+    }
+    return [start, ...reversed.reverse(), ...(end === undefined ? [] : [end])];
+}
+function nearestNeighbor(matrix, start, end) {
+    const remaining = new Set(Array.from({ length: matrix.length }, (_, index) => index).filter(index => index !== start && index !== end));
+    const order = [start];
+    while (remaining.size) {
+        const current = order[order.length - 1];
+        let next = -1;
+        let best = Infinity;
+        for (const candidate of remaining) {
+            const cost = at(matrix, current, candidate);
+            if (cost < best || (cost === best && candidate < next)) {
+                best = cost;
+                next = candidate;
+            }
+        }
+        order.push(next);
+        remaining.delete(next);
+    }
+    if (end !== undefined)
+        order.push(end);
+    return order;
+}
+/** Fixed-start 2-opt; directed reversal costs are included, not just the two boundary edges. */
+function twoOpt(seed, matrix, closed, fixedEnd) {
+    let order = [...seed];
+    let total = routeCost(order, matrix, closed);
+    for (let pass = 0; pass < exports.ROUTE_OPTIMIZATION.twoOptMaxPasses; pass++) {
+        const reverseCosts = Array(order.length).fill(0);
+        for (let index = 0; index < order.length - 1; index++) {
+            reverseCosts[index + 1] = reverseCosts[index] + at(matrix, order[index + 1], order[index]) - at(matrix, order[index], order[index + 1]);
+        }
+        let improved = false;
+        const maximumEnd = order.length - (fixedEnd ? 2 : 1);
+        for (let first = 1; first < maximumEnd && !improved; first++) {
+            for (let last = first + 1; last <= maximumEnd; last++) {
+                const before = order[first - 1];
+                const head = order[first];
+                const tail = order[last];
+                const after = order[last + 1] ?? (closed ? order[0] : undefined);
+                const delta = at(matrix, before, tail) - at(matrix, before, head)
+                    + (after === undefined ? 0 : at(matrix, head, after) - at(matrix, tail, after))
+                    + reverseCosts[last] - reverseCosts[first];
+                if (delta >= 0)
+                    continue;
+                const candidate = [...order.slice(0, first), ...order.slice(first, last + 1).reverse(), ...order.slice(last + 1)];
+                const candidateCost = routeCost(candidate, matrix, closed);
+                if (candidateCost < total) {
+                    order = candidate;
+                    total = candidateCost;
+                    improved = true;
+                    break;
+                }
+            }
+        }
+        if (!improved)
+            break;
+    }
+    return order;
+}
+function lexicographicallyBefore(left, right) {
+    for (let index = 0; index < left.length; index++) {
+        if (left[index] !== right[index])
+            return left[index] < right[index];
+    }
+    return false;
+}
+function optimizeResolved(inputs, points, options) {
+    const { matrix, method, gridId } = buildMatrix(points, options);
+    const start = options.startIndex ?? 0;
+    const end = options.endIndex;
+    const closed = options.returnToStart ?? false;
+    const baseline = feasibleOrder(points.length, start, end);
+    const originalTotalMeters = routeCost(baseline, matrix, closed);
+    const exact = points.length <= exports.ROUTE_OPTIMIZATION.exactMaxStops;
+    let order = baseline;
+    if (points.length > 1) {
+        if (exact)
+            order = exactOrder(matrix, start, end, closed);
+        else {
+            // Optimizing both seeds and retaining the baseline guarantees no regression against supplied order.
+            let bestCost = originalTotalMeters;
+            for (const seed of [baseline, nearestNeighbor(matrix, start, end)]) {
+                const candidate = twoOpt(seed, matrix, closed, end !== undefined);
+                const cost = routeCost(candidate, matrix, closed);
+                if (cost < bestCost || (cost === bestCost && lexicographicallyBefore(candidate, order))) {
+                    order = candidate;
+                    bestCost = cost;
+                }
+            }
+        }
+    }
+    const legs = [];
+    const addLeg = (fromIndex, toIndex, isReturn) => {
+        const meters = at(matrix, fromIndex, toIndex);
+        legs.push({ fromIndex, toIndex, meters, kilometers: meters / 1000, method, isReturn });
+    };
+    for (let index = 1; index < order.length; index++)
+        addLeg(order[index - 1], order[index], false);
+    if (closed && order.length > 1)
+        addLeg(order[order.length - 1], order[0], true);
+    const totalMeters = routeCost(order, matrix, closed);
+    return {
+        orderedStops: order.map(index => inputs[index]), originalIndices: order,
+        resolvedPoints: order.map(index => points[index]), legs, totalMeters, totalKilometers: totalMeters / 1000,
+        method, ...(gridId !== undefined ? { gridId } : {}), optimization: exact ? "exact" : "approximate",
+        algorithm: points.length < 2 ? "trivial" : exact ? "held-karp" : "nearest-neighbor-2-opt",
+        exactCutoff: exports.ROUTE_OPTIMIZATION.exactMaxStops, returnToStart: closed, originalTotalMeters,
+        description: method === "distance-matrix" ? "optimized distance-matrix itinerary" : "optimized straight-line itinerary",
+    };
+}
+/** Reorder stops without mutating them or changing any issued address/grid identity. */
+function optimizeRoute(points, options = {}) {
+    validateRouteOptions(points, options);
+    // Snapshot array order before asynchronous lookups; retain each original stop reference.
+    const inputs = [...points];
+    const settings = { ...options };
+    if (settings.distanceMatrix !== undefined)
+        settings.distanceMatrix = validateMatrix(settings.distanceMatrix, inputs.length);
+    const resolved = (0, locations_js_1.resolveLocationPoints)(inputs, settings.resolveAddress);
+    return resolved instanceof Promise
+        ? resolved.then(locations => optimizeResolved(inputs, locations, settings)) : optimizeResolved(inputs, resolved, settings);
+}

package/dist/cjs/types.d.ts

@@ -112,3 +112,73 @@ export type ProvinceOption = Readonly<{
     code: string;
     name: string;
 }>;
+/** A saved location, including either address protocol's complete result. */
+export type SavedLocationPoint = Readonly<{
+    coordinates: Coordinates;
+}>;
+export type LocationPoint = Coordinates | SavedLocationPoint;
+export type LocationInput = LocationPoint | string;
+/** Resolve an exact address string to its saved original GPS record. */
+export type AddressResolver = (address: string, originalIndex: number) => SavedLocationPoint | PromiseLike<SavedLocationPoint>;
+export type DistanceMethod = "haversine" | "projected";
+export type RouteDistanceMethod = DistanceMethod | "distance-matrix";
+export type DistanceOptions = {
+    /** Defaults to Haversine from the original GPS point. */
+    method?: DistanceMethod;
+    resolveAddress?: never;
+};
+/** Supplying a resolver makes the operation asynchronous, even for a cache lookup. */
+export type ResolvedDistanceOptions = Omit<DistanceOptions, "resolveAddress"> & {
+    resolveAddress: AddressResolver;
+};
+export type DistanceResult = Readonly<{
+    meters: number;
+    kilometers: number;
+}> & ({
+    readonly method: "haversine";
+} | {
+    readonly method: "projected";
+    readonly gridId: string;
+});
+/** Meter costs indexed by original input index; directed/asymmetric matrices are supported. */
+export type DistanceMatrix = readonly (readonly number[])[];
+export type RouteOptions = DistanceOptions & {
+    /** Original input index of the fixed start; defaults to 0 for a nonempty list. */
+    startIndex?: number;
+    /** Original input index of the fixed end; incompatible with returnToStart. */
+    endIndex?: number;
+    returnToStart?: boolean;
+    /** Optional caller-supplied costs in meters; cannot be combined with method. */
+    distanceMatrix?: DistanceMatrix;
+};
+export type ResolvedRouteOptions = Omit<RouteOptions, "resolveAddress"> & {
+    resolveAddress: AddressResolver;
+};
+export type RouteLeg = Readonly<{
+    fromIndex: number;
+    toIndex: number;
+    meters: number;
+    kilometers: number;
+    method: RouteDistanceMethod;
+    /** The closing leg; the start is not duplicated in orderedStops. */
+    isReturn: boolean;
+}>;
+export type RouteResult<T extends LocationInput = LocationInput> = Readonly<{
+    /** Original inputs, retaining object identity and including coincident stops separately. */
+    orderedStops: readonly T[];
+    originalIndices: readonly number[];
+    /** Resolved GPS points/records in the same order as orderedStops. */
+    resolvedPoints: readonly LocationPoint[];
+    legs: readonly RouteLeg[];
+    totalMeters: number;
+    totalKilometers: number;
+    method: RouteDistanceMethod;
+    gridId?: string;
+    optimization: "exact" | "approximate";
+    algorithm: "trivial" | "held-karp" | "nearest-neighbor-2-opt";
+    exactCutoff: 12;
+    returnToStart: boolean;
+    /** Cost of supplied order with the requested start moved first and end moved last. */
+    originalTotalMeters: number;
+    description: "optimized straight-line itinerary" | "optimized distance-matrix itinerary";
+}>;

package/dist/esm/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/esm/distance.js

@@ -0,0 +1,55 @@
+import { ZAP_PROTOCOL } from "./protocol.js";
+import { getLocationCoordinates, getProjectedPoint, resolveLocationPoints, validateLocationOptions } from "./locations.js";
+export 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. */
+export 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 * ZAP_PROTOCOL.earthRadiusMeters * Math.atan2(Math.sqrt(clamped), Math.sqrt(1 - clamped));
+}
+export 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 = getLocationCoordinates(pointA);
+    const coordinatesB = getLocationCoordinates(pointB);
+    if (method === "projected") {
+        const gridA = getProjectedPoint(pointA);
+        const gridB = 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. */
+export function getDistance(pointA, pointB, options = {}) {
+    validateLocationOptions(options);
+    const method = getDistanceMethod(options.method);
+    const resolved = resolveLocationPoints([pointA, pointB], options.resolveAddress);
+    return resolved instanceof Promise
+        ? resolved.then(points => calculateDistance(points, method)) : calculateDistance(resolved, method);
+}

package/dist/esm/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/esm/index.js

@@ -1,15 +1,20 @@
 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 { generateAddress, generateLegacyAddress, getDirectionsUrl, getDistance, optimizeRoute, ROUTE_OPTIMIZATION, getCountries, getCountry, getProvinces, ZAP_PROTOCOL, LEGACY_ZAP_PROTOCOL, };
 /** Named namespace for applications that refer to the protocol as `zap`. */
 export const zap = Object.freeze({
     protocol: ZAP_PROTOCOL,
     generateAddress,
     generateLegacyAddress,
     getDirectionsUrl,
+    getDistance,
+    optimizeRoute,
+    routeOptimization: ROUTE_OPTIMIZATION,
     getCountries,
     getCountry,
     getProvinces,

package/dist/esm/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/esm/locations.js

@@ -0,0 +1,61 @@
+import { validateCoordinates } from "./grid.js";
+export 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. */
+export 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.");
+    }
+    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;
+}
+export 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;
+    });
+}
+export 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/esm/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>>;