googlemaps-kit 0.3.1 → 0.5.0

package/dist/services/waypoint-optimizer.js

@@ -0,0 +1,235 @@
+/**
+ * Waypoint order optimization.
+ *
+ * Consumer Maps has no `optimize:true` equivalent, so this composes the
+ * anonymous directions-fan-out distance matrix with a travelling-salesman
+ * heuristic: nearest-neighbour construction followed by 2-opt improvement.
+ * Fixed origin/destination are respected; open tours (no fixed ends) try
+ * every stop as a starting point and keep the best tour after 2-opt.
+ */
+import { GMapsError } from '../types/common.js';
+/** Upper bound on 2-opt improving passes to keep worst cases bounded. */
+const MAX_TWO_OPT_PASSES = 64;
+export class WaypointOptimizerService {
+    matrix;
+    directions;
+    geocode;
+    constructor(matrix, directions, geocode) {
+        this.matrix = matrix;
+        this.directions = directions;
+        this.geocode = geocode;
+    }
+    /**
+     * Reorder `stops` into an efficient visiting order.
+     *
+     * Costs come from real driving durations/distances via the directions
+     * fan-out matrix. With ~N stops the matrix costs N² unique pairs, so this
+     * suits up to roughly a dozen stops; larger lists still work but take
+     * proportionally longer.
+     */
+    async optimize(options) {
+        const start = performance.now();
+        if (!Array.isArray(options.stops) || options.stops.length === 0) {
+            throw new GMapsError('optimizeWaypoints requires at least one stop');
+        }
+        if (options.roundTrip && !options.origin) {
+            throw new GMapsError('roundTrip requires a fixed origin to return to');
+        }
+        const mode = options.mode ?? 'driving';
+        const useDistance = options.metric === 'distance';
+        const [origin, destination, stops] = await Promise.all([
+            options.origin ? this.resolve(options.origin) : Promise.resolve(undefined),
+            options.destination
+                ? this.resolve(options.destination)
+                : options.roundTrip && options.origin
+                    ? this.resolve(options.origin)
+                    : Promise.resolve(undefined),
+            Promise.all(options.stops.map((s) => this.resolve(s))),
+        ]);
+        const nodes = [];
+        const originIndex = origin ? nodes.push(origin) - 1 : -1;
+        const firstStopIndex = nodes.length;
+        for (const s of stops)
+            nodes.push(s);
+        const destinationIndex = destination ? nodes.push(destination) - 1 : -1;
+        const matrixResult = await this.matrix.getMatrix({
+            origins: nodes,
+            destinations: nodes,
+            mode,
+            concurrency: options.concurrency,
+            hl: options.hl,
+            gl: options.gl,
+        });
+        const cellAt = (from, to) => matrixResult.rows[from]?.[to];
+        const costOf = (from, to) => {
+            const cell = cellAt(from, to);
+            if (!cell)
+                return Number.POSITIVE_INFINITY;
+            const value = useDistance ? cell.distanceMeters : cell.durationSeconds;
+            return value ?? Number.POSITIVE_INFINITY;
+        };
+        const tourCost = (order) => {
+            const full = buildFullSequence(order, originIndex, destinationIndex);
+            let cost = 0;
+            for (let i = 0; i < full.length - 1; i++) {
+                cost += costOf(full[i], full[i + 1]);
+            }
+            return cost;
+        };
+        const inputOrder = stops.map((_, i) => firstStopIndex + i);
+        const startCandidates = originIndex >= 0 ? [originIndex] : [...inputOrder];
+        let bestOrder = null;
+        let bestCost = Number.POSITIVE_INFINITY;
+        for (const startNode of startCandidates) {
+            const remaining = new Set(inputOrder);
+            const order = [];
+            let current = startNode;
+            if (remaining.has(current)) {
+                order.push(current);
+                remaining.delete(current);
+            }
+            while (remaining.size > 0) {
+                let next;
+                let nextCost = Number.POSITIVE_INFINITY;
+                for (const candidate of remaining) {
+                    const c = costOf(current, candidate);
+                    if (c < nextCost) {
+                        nextCost = c;
+                        next = candidate;
+                    }
+                }
+                if (next === undefined)
+                    break;
+                order.push(next);
+                remaining.delete(next);
+                current = next;
+            }
+            twoOptImprove(order, costOf, originIndex, destinationIndex);
+            const improvedCost = tourCost(order);
+            if (improvedCost < bestCost) {
+                bestCost = improvedCost;
+                bestOrder = [...order];
+            }
+        }
+        const order = (bestOrder ?? inputOrder).map((n) => n - firstStopIndex);
+        const result = {
+            order,
+            stops: order.map((i) => stops[i]),
+            matrixRequests: matrixResult.requestCount,
+            legRequests: 0,
+            timingMs: performance.now() - start,
+        };
+        const totalFull = buildFullSequence(order.map((i) => firstStopIndex + i), originIndex, destinationIndex);
+        const totals = sumPath(totalFull, cellAt);
+        if (totals.durationKnown)
+            result.totalDurationSeconds = totals.duration;
+        if (totals.distanceKnown)
+            result.totalDistanceMeters = totals.distance;
+        const baselineFull = buildFullSequence(inputOrder, originIndex, destinationIndex);
+        const baselineTotals = sumPath(baselineFull, cellAt);
+        if (baselineTotals.durationKnown)
+            result.baselineDurationSeconds = baselineTotals.duration;
+        if (baselineTotals.distanceKnown)
+            result.baselineDistanceMeters = baselineTotals.distance;
+        const base = useDistance ? result.totalDistanceMeters : result.totalDurationSeconds;
+        const baseline = useDistance ? result.baselineDistanceMeters : result.baselineDurationSeconds;
+        if (base !== undefined && baseline !== undefined && baseline > 0) {
+            result.improvementPercent = Math.round(((baseline - base) / baseline) * 1000) / 10;
+        }
+        if (options.includeLegs) {
+            const legs = [];
+            for (let i = 0; i < totalFull.length - 1; i++) {
+                const from = nodes[totalFull[i]];
+                const to = nodes[totalFull[i + 1]];
+                const leg = await this.directions.get({ origin: from, destination: to, mode });
+                result.legRequests += 1;
+                legs.push({
+                    from,
+                    to,
+                    durationSeconds: leg.durationSeconds,
+                    distanceMeters: leg.distanceMeters,
+                });
+            }
+            result.legs = legs;
+        }
+        return result;
+    }
+    /** Coordinates for any node, geocoding address strings once. */
+    async resolve(value) {
+        if (typeof value !== 'string')
+            return value;
+        const response = await this.geocode.geocode(value);
+        const hit = response.result ?? response.alternatives[0];
+        if (!hit) {
+            throw new GMapsError(`Could not resolve waypoint: ${value}`);
+        }
+        return { lat: hit.lat, lng: hit.lng };
+    }
+}
+function buildFullSequence(stopNodes, originIndex, destinationIndex) {
+    const full = [];
+    if (originIndex >= 0)
+        full.push(originIndex);
+    full.push(...stopNodes);
+    if (destinationIndex >= 0)
+        full.push(destinationIndex);
+    return full;
+}
+function sumPath(sequence, cellAt) {
+    let duration = 0;
+    let distance = 0;
+    let durationKnown = true;
+    let distanceKnown = true;
+    for (let i = 0; i < sequence.length - 1; i++) {
+        const cell = cellAt(sequence[i], sequence[i + 1]);
+        if (!cell || cell.durationSeconds === undefined)
+            durationKnown = false;
+        else
+            duration += cell.durationSeconds;
+        if (!cell || cell.distanceMeters === undefined)
+            distanceKnown = false;
+        else
+            distance += cell.distanceMeters;
+    }
+    return { duration, distance, durationKnown, distanceKnown };
+}
+/** In-place 2-opt on the stop-node subsequence; segment reversal keeps fixed endpoints. */
+function twoOptImprove(order, costOf, originIndex, destinationIndex) {
+    const full = buildFullSequence(order, originIndex, destinationIndex);
+    // Only the origin is prepended; the destination trails behind the stops.
+    const offset = originIndex >= 0 ? 1 : 0;
+    for (let pass = 0; pass < MAX_TWO_OPT_PASSES; pass++) {
+        let improved = false;
+        for (let i = 0; i < order.length - 1; i++) {
+            for (let k = i + 1; k < order.length; k++) {
+                const beforeA = offset + i - 1 >= 0 ? full[offset + i - 1] ?? null : null;
+                const afterB = offset + k + 1 < full.length ? full[offset + k + 1] ?? null : null;
+                const edgeAFrom = beforeA !== null ? full[offset + i] : undefined;
+                const edgeBTo = afterB !== null ? full[offset + k] : undefined;
+                const removedEdgeA = beforeA !== null && edgeAFrom !== undefined ? costOf(beforeA, edgeAFrom) : 0;
+                const removedEdgeB = afterB !== null && edgeBTo !== undefined ? costOf(edgeBTo, afterB) : 0;
+                const addedEdgeA = beforeA !== null && edgeBTo !== undefined ? costOf(beforeA, edgeBTo) : 0;
+                const addedEdgeB = afterB !== null && edgeAFrom !== undefined ? costOf(edgeAFrom, afterB) : 0;
+                if (addedEdgeA + addedEdgeB < removedEdgeA + removedEdgeB) {
+                    reverseSegment(full, offset + i, offset + k);
+                    improved = true;
+                }
+            }
+        }
+        if (!improved)
+            break;
+    }
+    for (let i = 0; i < order.length; i++) {
+        order[i] = full[offset + i];
+    }
+}
+function reverseSegment(arr, from, to) {
+    while (from < to) {
+        const tmp = arr[from];
+        arr[from] = arr[to];
+        arr[to] = tmp;
+        from++;
+        to--;
+    }
+}
+//# sourceMappingURL=waypoint-optimizer.js.map

package/dist/services/waypoint-optimizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waypoint-optimizer.js","sourceRoot":"","sources":["../../src/services/waypoint-optimizer.ts"],"names":[],"mappings":"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"}

package/dist/types/batch-url.d.ts

@@ -1,9 +1,40 @@
 /** Decoded Maps URL from DecodeUrl batchexecute RPC. */
 export interface DecodedMapsUrl {
+    /**
+     * Place name extracted from the decoded URL (e.g. "Kake Di Hatti").
+     * Present only when the URL pointed to a place page.
+     */
     name?: string;
+    /** Viewport / place latitude from the decoded URL coordinates block. */
     lat?: number;
+    /** Viewport / place longitude. */
     lng?: number;
+    /** Map zoom level from the decoded URL. */
     zoom?: number;
+    /**
+     * Hex feature id (`0x…:0x…`) when present in the decoded URL payload.
+     * Currently not extracted by the parser — reserved for future extraction.
+     */
+    hexId?: string;
+    /**
+     * ChIJ place id when present in the decoded URL payload.
+     * Currently not extracted by the parser — reserved for future extraction.
+     */
+    placeId?: string;
+    /**
+     * Formatted address string when the decoded URL carries one.
+     * Currently not extracted by the parser — reserved for future extraction.
+     */
+    address?: string;
+    /**
+     * URL type derived from the type code in the DecodeUrl response (`coordsBlock[1][0]`).
+     * - `'place'` — place page URL (type code 2, confirmed from fixture)
+     * - `'search'` — search results URL (type code 1, inferred)
+     * - `'directions'` — directions URL (type code 3, inferred)
+     * - `'viewport'` — bare viewport URL (type code 4, inferred)
+     * `undefined` when the type code is absent or unrecognized.
+     */
+    type?: 'place' | 'search' | 'directions' | 'viewport';
     raw?: unknown;
 }
 export interface DecodeUrlOptions {

package/dist/types/batch-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch-url.d.ts","sourceRoot":"","sources":["../../src/types/batch-url.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf"}
+{"version":3,"file":"batch-url.d.ts","sourceRoot":"","sources":["../../src/types/batch-url.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAC;IACtD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf"}

package/dist/types/categories.d.ts

@@ -1,20 +1,34 @@
+/**
+ * Result wrapper for `categories.getHierarchy()`.
+ * The `nodes` array contains the top-level category roots; each node may have nested `children`.
+ */
+export interface CategoryHierarchyResult {
+    /** Top-level category nodes (each may have `.children` for sub-categories). */
+    nodes: CategoryNode[];
+    raw?: unknown;
+}
 /** Google Maps category taxonomy node from LocalRapService.GetCategoryHierarchy. */
 export interface CategoryNode {
     name: string;
     gcid?: string;
     id?: number;
     children?: CategoryNode[];
+    raw?: unknown;
 }
 export interface CategorySuggestion {
     gcid: string;
     label: string;
+    raw?: unknown;
+}
+export interface PlaceInfoEntry {
+    hexId?: string;
+    label?: string;
+    raw?: unknown;
 }
 export interface PlaceInfoResult {
     hexId?: string;
-    entries: Array<{
-        hexId?: string;
-        label?: string;
-    }>;
+    entries: PlaceInfoEntry[];
+    raw?: unknown;
 }
 export interface PotentialDuplicate {
     hexId: string;
@@ -23,10 +37,12 @@ export interface PotentialDuplicate {
     address?: string;
     rating?: number;
     reviewCount?: number;
+    raw?: unknown;
 }
 export interface SignedPlaceUrl {
     hexId: string;
     signedPath: string;
+    raw?: unknown;
 }
 export interface GetCategorySuggestionsOptions {
     query: string;

package/dist/types/categories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../src/types/categories.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../src/types/categories.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;CACf"}