@zukall/zap 0.2.2 → 0.3.0

package/dist/esm/route.js

@@ -0,0 +1,285 @@
+import { getDistanceMethod, haversineMeters, requireFiniteDistance } from "./distance.js";
+import { getLocationCoordinates, getProjectedPoint, resolveLocationPoints, validateLocationOptions } from "./locations.js";
+/** Work limits are separate from address protocol/configuration versions. */
+export const 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) {
+    validateLocationOptions(options);
+    if (!Array.isArray(points))
+        throw new TypeError("points must be an array of locations.");
+    if (points.length > ROUTE_OPTIMIZATION.maxStops) {
+        throw new RangeError(`At most ${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.");
+    }
+    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(getLocationCoordinates);
+    if (options.distanceMatrix !== undefined) {
+        return { matrix: validateMatrix(options.distanceMatrix, points.length), method: "distance-matrix" };
+    }
+    const method = getDistanceMethod(options.method);
+    const projected = method === "projected" ? points.map(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 = requireFiniteDistance(projected ? Math.hypot(projected[right].northingMeters - projected[left].northingMeters, projected[right].eastingMeters - projected[left].eastingMeters) : 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 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 < 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 <= 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: 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. */
+export 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 = resolveLocationPoints(inputs, settings.resolveAddress);
+    return resolved instanceof Promise
+        ? resolved.then(locations => optimizeResolved(inputs, locations, settings)) : optimizeResolved(inputs, resolved, settings);
+}

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

@@ -1,7 +1,7 @@
 {
   "name": "@zukall/zap",
-  "version": "0.2.2",
-  "description": "ZAP (Zukall Addressing Protocol): deterministic 100-meter grid blocks with whole-meter detail from GPS coordinates.",
+  "version": "0.3.0",
+  "description": "ZAP (Zukall Addressing Protocol): GPS addresses, geographic distance, and optimized straight-line itineraries.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/cjs/index.js",