@any-routing/mapbox-data-provider 1.0.0-rc.1

package/README.md

@@ -0,0 +1,18 @@
+# mapbox-data-provider
+
+`AnyRoutingDataProvider` implementation backed by the
+[Mapbox Directions API](https://docs.mapbox.com/api/navigation/directions/).
+
+```ts
+import { MapboxProvider } from '@any-routing/mapbox-data-provider';
+
+const dataProvider = new MapboxProvider({
+  accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
+  profile: 'driving',
+  alternatives: true,
+});
+```
+
+The provider requests GeoJSON geometry and turn-by-turn steps by default.
+Requests run in a Web Worker by default; use `worker: false` when a worker is
+not available.

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@any-routing/mapbox-data-provider",
+  "version": "1.0.0-rc.1",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "dependencies": {
+    "@any-routing/core": "1.0.0-rc.1",
+    "@turf/bbox": "7.4.0",
+    "@turf/helpers": "7.4.0",
+    "@types/geojson": "7946.0.16",
+    "comlink": "4.4.2"
+  }
+}

package/project.json

@@ -0,0 +1,21 @@
+{
+  "name": "mapbox-data-provider",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/mapbox-data-provider/src",
+  "projectType": "library",
+  "release": {
+    "version": {
+      "manifestRootsToUpdate": ["dist/{projectRoot}"],
+      "currentVersionResolver": "git-tag",
+      "fallbackCurrentVersionResolver": "disk"
+    }
+  },
+  "tags": [],
+  "targets": {
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "dist/{projectRoot}"
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './lib/mapbox-data-provider';
+export * from './lib/mapbox-provider.types';

package/src/lib/mapbox-data-provider.ts

@@ -0,0 +1,108 @@
+import { Remote, wrap } from 'comlink';
+import type { AnyRoutingDataProvider, RequestOptions, Waypoint } from '@any-routing/core';
+import { MapboxExecutor, type ExecutorRequestOptions } from './mapbox.executor';
+import type { MapboxRoutingData, Options } from './mapbox-provider.types';
+
+const defaultOptions: Partial<Options> = {
+  baseUrl: 'https://api.mapbox.com/directions/v5/mapbox',
+  profile: 'driving',
+  worker: true,
+  alternatives: false,
+  steps: true,
+  geometries: 'geojson',
+  overview: 'full',
+};
+
+export class MapboxProvider implements AnyRoutingDataProvider {
+  private worker?: Worker;
+  private executorAPI: MapboxExecutor | Remote<MapboxExecutor>;
+  private _options: Options;
+
+  public get options(): Options {
+    return this._options;
+  }
+
+  constructor(options: Options) {
+    this._options = { ...defaultOptions, ...options };
+    if (!this.options.accessToken) {
+      throw new Error('A Mapbox access token is required');
+    }
+
+    if (this.options.worker) {
+      this.worker = new Worker(new URL('./mapbox.worker', import.meta.url), { type: 'module' });
+      this.executorAPI = wrap<MapboxExecutor>(this.worker);
+    } else {
+      this.executorAPI = new MapboxExecutor();
+    }
+  }
+
+  public destroy(): void {
+    this.worker?.terminate();
+  }
+
+  public request(waypoints: Waypoint[], opts: RequestOptions): Promise<MapboxRoutingData> {
+    const url = this.buildUrl(waypoints, { ...this.options, ...opts });
+    const requestOptions = { ...this.options, ...opts, url };
+    delete requestOptions.buildUrl;
+    return this.executorAPI.request(requestOptions as ExecutorRequestOptions);
+  }
+
+  public async abortAllRequests(): Promise<void> {
+    await this.executorAPI.abortAllRequests();
+  }
+
+  public setOption<T extends keyof Options>(key: T, value: Options[T]): void {
+    this.options[key] = value;
+  }
+
+  public async hasPendingRequests(): Promise<boolean> {
+    return await this.executorAPI.hasPendingRequests();
+  }
+
+  private buildUrl(waypoints: Waypoint[], opts: Options & RequestOptions): string {
+    if (waypoints.length < 2) {
+      throw new Error('At least two waypoints are required');
+    }
+
+    const coordinates = waypoints
+      .map(({ position }) => `${position.lng},${position.lat}`)
+      .join(';');
+    const queryParams: Record<string, string> = {
+      access_token: opts.accessToken,
+      alternatives: String(opts.alternatives ?? false),
+      steps: String(opts.steps ?? true),
+      geometries: opts.geometries ?? 'geojson',
+      overview: opts.overview ?? 'full',
+      ...(opts.continueStraight !== undefined
+        ? { continue_straight: String(opts.continueStraight) }
+        : {}),
+      ...(opts.language ? { language: opts.language } : {}),
+      ...(opts.bannerInstructions !== undefined
+        ? { banner_instructions: String(opts.bannerInstructions) }
+        : {}),
+      ...(opts.voiceInstructions !== undefined
+        ? { voice_instructions: String(opts.voiceInstructions) }
+        : {}),
+      ...(opts.voiceUnits ? { voice_units: opts.voiceUnits } : {}),
+      ...(opts.exclude
+        ? { exclude: Array.isArray(opts.exclude) ? opts.exclude.join(',') : opts.exclude }
+        : {}),
+      ...(opts.approaches
+        ? {
+            approaches: Array.isArray(opts.approaches)
+              ? opts.approaches.join(';')
+              : opts.approaches,
+          }
+        : {}),
+      ...(opts.avoidManeuverRestrictions !== undefined
+        ? { avoid_maneuver_restrictions: String(opts.avoidManeuverRestrictions) }
+        : {}),
+      ...Object.fromEntries(
+        Object.entries(opts.queryParams ?? {}).map(([key, value]) => [key, String(value)]),
+      ),
+    };
+    const query = new URLSearchParams(queryParams).toString();
+    const url = `${opts.baseUrl}/${opts.profile ?? 'driving'}/${coordinates}?${query}`;
+    return opts.buildUrl ? opts.buildUrl({ waypoints, options: opts }, url) : url;
+  }
+}

package/src/lib/mapbox-provider.types.ts

@@ -0,0 +1,98 @@
+import type {
+  AnyRoutingDataResponse,
+  RequestOptions,
+  RouteSummary,
+  Waypoint,
+} from '@any-routing/core';
+import type { ExecutorRequestOptions } from './mapbox.executor';
+
+export type MapboxProfile = 'driving' | 'driving-traffic' | 'walking' | 'cycling' | (string & {});
+
+export type MapboxGeometry = 'geojson' | 'polyline' | 'polyline6';
+export type MapboxOverview = 'full' | 'simplified' | 'false';
+
+export interface MapboxRouteSummary extends RouteSummary {
+  rawRoute: MapboxRawRoute;
+}
+
+export interface MapboxRoutingData extends AnyRoutingDataResponse {
+  routes: MapboxRouteSummary[];
+  requestOptions: ExecutorRequestOptions;
+}
+
+export interface MapboxRawStep {
+  distance: number;
+  duration: number;
+  name?: string;
+  geometry?: MapboxRawLineString;
+  maneuver?: {
+    location: [number, number];
+    type?: string;
+    modifier?: string;
+    instruction?: string;
+  };
+  [key: string]: unknown;
+}
+
+export interface MapboxRawLeg {
+  distance: number;
+  duration: number;
+  steps?: MapboxRawStep[];
+  summary?: string;
+}
+
+export interface MapboxRawLineString {
+  type: 'LineString';
+  coordinates: [number, number][];
+}
+
+export interface MapboxRawRoute {
+  distance: number;
+  duration: number;
+  geometry: MapboxRawLineString;
+  legs: MapboxRawLeg[];
+  weight?: number;
+  weight_name?: string;
+  [key: string]: unknown;
+}
+
+export interface MapboxRawWaypoint {
+  name?: string;
+  location: [number, number];
+  distance?: number;
+  waypoint_index?: number;
+  trips_index?: number;
+}
+
+export interface MapboxApiResponse {
+  code: string;
+  message?: string;
+  routes?: MapboxRawRoute[];
+  waypoints?: MapboxRawWaypoint[];
+}
+
+export type Options = {
+  accessToken: string;
+  baseUrl?: string;
+  profile?: MapboxProfile;
+  worker?: boolean;
+  alternatives?: boolean;
+  steps?: boolean;
+  overview?: MapboxOverview;
+  geometries?: MapboxGeometry;
+  annotations?: boolean | string[];
+  continueStraight?: boolean | 'default';
+  language?: string;
+  bannerInstructions?: boolean;
+  voiceInstructions?: boolean;
+  voiceUnits?: 'imperial' | 'metric';
+  exclude?: string | string[];
+  approaches?: string | string[];
+  avoidManeuverRestrictions?: boolean;
+  queryParams?: Record<string, string | number | boolean>;
+  requestParams?: RequestInit;
+  buildUrl?: (
+    ctx: { waypoints: Waypoint[]; options: Options & RequestOptions },
+    url: string,
+  ) => string;
+};

package/src/lib/mapbox.executor.spec.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+import { MapboxExecutor } from './mapbox.executor';
+
+describe('MapboxExecutor', () => {
+  it('requests GeoJSON routes and normalizes route geometry', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          code: 'Ok',
+          routes: [
+            {
+              distance: 1250,
+              duration: 90,
+              geometry: {
+                type: 'LineString',
+                coordinates: [
+                  [-73.99, 40.75],
+                  [-73.98, 40.76],
+                ],
+              },
+              legs: [
+                {
+                  distance: 1250,
+                  duration: 90,
+                  steps: [
+                    {
+                      distance: 1250,
+                      duration: 90,
+                      geometry: {
+                        type: 'LineString',
+                        coordinates: [
+                          [-73.99, 40.75],
+                          [-73.98, 40.76],
+                        ],
+                      },
+                      maneuver: { location: [-73.99, 40.75] },
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await new MapboxExecutor().request({
+      url: 'https://api.mapbox.com/directions/v5/mapbox/driving/coordinates',
+      mode: 'default',
+      accessToken: 'test-token',
+      profile: 'driving',
+      geometries: 'geojson',
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.stringContaining('/directions/'),
+      expect.objectContaining({ method: 'GET' }),
+    );
+    expect(result.routes[0]?.distance).toBe(1250);
+    expect(result.routes[0]?.durationTime).toBe(90);
+    expect(result.routes[0]?.path).toEqual([
+      [40.75, -73.99],
+      [40.76, -73.98],
+    ]);
+    expect(result.routesShapeGeojson.features).toHaveLength(1);
+  });
+});

package/src/lib/mapbox.executor.ts

@@ -0,0 +1,118 @@
+import bbox from '@turf/bbox';
+import { featureCollection, lineString } from '@turf/helpers';
+import type { BBox, Feature, LineString } from 'geojson';
+import { Requester } from '@any-routing/core';
+import type {
+  MapboxApiResponse,
+  MapboxRawLeg,
+  MapboxRawRoute,
+  MapboxRouteSummary,
+  MapboxRoutingData,
+  Options,
+} from './mapbox-provider.types';
+
+export type ExecutorRequestOptions = { url: string } & Options;
+
+type ShapeProperties = { waypoint: number; routeId: number };
+
+export class MapboxExecutor {
+  private readonly requester = new Requester();
+
+  async request(opts: ExecutorRequestOptions): Promise<MapboxRoutingData> {
+    const data = (await this.requester.request(opts.url, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+      },
+      ...opts.requestParams,
+    })) as MapboxApiResponse;
+
+    if (data.code !== 'Ok' || !data.routes?.length) {
+      throw new Error(data.message || `Mapbox request failed with code "${data.code}"`);
+    }
+
+    const routes = data.routes.map((route, routeId) => summarizeRoute(route, routeId));
+    const features = routes.flatMap((route, fid) =>
+      route.shape.features.map((feature) => ({
+        id: fid,
+        ...feature,
+        properties: { ...feature.properties, id: fid, routeId: route.id },
+      })),
+    );
+    const routesShapeGeojson = featureCollection(features);
+    return {
+      routesShapeBounds: bbox(routesShapeGeojson) as BBox,
+      rawResponse: data,
+      routes,
+      selectedRouteId: routes.length ? 0 : null,
+      routesShapeGeojson,
+      version: performance.now(),
+      latest: !this.requester.hasPendingRequests,
+      requestOptions: opts,
+    };
+  }
+
+  hasPendingRequests(): boolean {
+    return this.requester.hasPendingRequests;
+  }
+
+  abortAllRequests(): void {
+    this.requester.abortAllRequests();
+  }
+}
+
+function summarizeRoute(route: MapboxRawRoute, routeId: number): MapboxRouteSummary {
+  const now = new Date();
+  const shapeFeatures = route.legs.flatMap((leg, waypoint) =>
+    buildLegShape(leg, route, routeId, waypoint),
+  );
+  const path = route.geometry.coordinates.map(([lng, lat]) => [lat, lng] as [number, number]);
+  const waypoints = route.legs.flatMap((leg, index) => {
+    const firstStep = leg.steps?.[0];
+    const location = firstStep?.maneuver?.location;
+    if (location) {
+      const [lng, lat] = location;
+      return [{ lat, lng }, ...(index === route.legs.length - 1 ? getLastWaypoint(leg) : [])];
+    }
+    return index === 0 ? [{ lat: path[0]?.[0] ?? 0, lng: path[0]?.[1] ?? 0 }] : [];
+  });
+
+  return {
+    id: routeId,
+    durationTime: route.duration,
+    distance: route.distance,
+    arriveTime: new Date(now.getTime() + route.duration * 1000),
+    departureTime: now,
+    path,
+    waypoints,
+    shape: featureCollection(
+      shapeFeatures.length
+        ? shapeFeatures
+        : [lineString(route.geometry.coordinates, { waypoint: 0, routeId })],
+    ),
+    rawRoute: route,
+  };
+}
+
+function buildLegShape(
+  leg: MapboxRawLeg,
+  route: MapboxRawRoute,
+  routeId: number,
+  waypoint: number,
+): Feature<LineString, ShapeProperties>[] {
+  const coordinates = leg.steps?.flatMap((step) => step.geometry?.coordinates ?? []) ?? [];
+  const deduplicated = coordinates.filter(
+    (coordinate, index) =>
+      index === 0 ||
+      coordinate[0] !== coordinates[index - 1]?.[0] ||
+      coordinate[1] !== coordinates[index - 1]?.[1],
+  );
+  const legCoordinates = deduplicated.length > 1 ? deduplicated : route.geometry.coordinates;
+  return legCoordinates.length > 1 ? [lineString(legCoordinates, { waypoint, routeId })] : [];
+}
+
+function getLastWaypoint(leg: MapboxRawLeg): { lat: number; lng: number }[] {
+  const step = leg.steps?.[leg.steps.length - 1];
+  const location = step?.maneuver?.location;
+  return location ? [{ lat: location[1], lng: location[0] }] : [];
+}

package/src/lib/mapbox.worker.ts

@@ -0,0 +1,4 @@
+import { expose } from 'comlink';
+import { MapboxExecutor } from './mapbox.executor';
+
+expose(new MapboxExecutor());

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "es2022",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "importHelpers": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true
+  },
+  "files": [],
+  "include": [],
+  "references": [{ "path": "./tsconfig.lib.json" }, { "path": "./tsconfig.spec.json" }]
+}

package/tsconfig.lib.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["vite.config.mts", "src/**/*.spec.ts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": ["vitest/globals", "vitest/importMeta", "vite/client", "node", "vitest"]
+  },
+  "include": ["vite.config.mts", "src/**/*.spec.ts"]
+}

package/vite.config.mts

@@ -0,0 +1,41 @@
+/// <reference types="vitest" />
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+import * as path from 'path';
+import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
+import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
+
+export default defineConfig(() => ({
+  root: import.meta.dirname,
+  cacheDir: '../../node_modules/.vite/libs/mapbox-data-provider',
+  plugins: [
+    nxViteTsPaths(),
+    nxCopyAssetsPlugin(['*.md']),
+    dts({
+      entryRoot: 'src',
+      tsconfigPath: path.join(import.meta.dirname, 'tsconfig.lib.json'),
+      pathsToAliases: false,
+    }),
+  ],
+  build: {
+    outDir: '../../dist/libs/mapbox-data-provider',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: { transformMixedEsModules: true },
+    lib: {
+      entry: 'src/index.ts',
+      name: 'mapbox-data-provider',
+      fileName: 'index',
+      formats: ['es' as const],
+    },
+    rolldownOptions: { external: [] },
+  },
+  test: {
+    name: 'mapbox-data-provider',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+  },
+}));