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

package/README.md

@@ -0,0 +1,17 @@
+# valhalla-data-provider
+
+`AnyRoutingDataProvider` implementation backed by the [Valhalla route API](https://valhalla.github.io/valhalla/api/route/api-reference/).
+
+```ts
+import { ValhallaProvider } from '@any-routing/valhalla-data-provider';
+
+const dataProvider = new ValhallaProvider({
+  baseUrl: 'https://valhalla1.openstreetmap.de/route',
+  costing: 'auto',
+});
+```
+
+The provider sends Valhalla's JSON route request with `POST`, decodes Valhalla's
+polyline6 geometry, and supports alternative routes through `alternates`.
+Requests run in a Web Worker by default; use `worker: false` when a worker is
+not available.

package/eslint.config.mjs

@@ -0,0 +1,22 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: [
+            '{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}',
+            '{projectRoot}/vite.config.{js,ts,mjs,mts}',
+          ],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+];

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@any-routing/valhalla-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": "valhalla-data-provider",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/valhalla-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/valhalla-data-provider';
+export * from './lib/valhalla-provider.types';

package/src/lib/valhalla-data-provider.spec.ts

@@ -0,0 +1,7 @@
+import { valhallaDataProvider } from './valhalla-data-provider';
+
+describe('valhallaDataProvider', () => {
+  it('should work', () => {
+    expect(valhallaDataProvider()).toEqual('valhalla-data-provider');
+  });
+});

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

@@ -0,0 +1,77 @@
+import { Remote, wrap } from 'comlink';
+import type { AnyRoutingDataProvider, RequestOptions, Waypoint } from '@any-routing/core';
+import { ValhallaExecutor, type ExecutorRequestOptions } from './valhalla.executor';
+import type { Options, ValhallaRoutingData } from './valhalla-provider.types';
+
+const defaultOptions: Partial<Options> = {
+  baseUrl: 'https://valhalla1.openstreetmap.de/route',
+  costing: 'auto',
+  units: 'kilometers',
+  language: 'en-US',
+  worker: true,
+  alternatives: 0,
+  shapeFormat: 'polyline6',
+};
+
+export class ValhallaProvider implements AnyRoutingDataProvider {
+  private worker?: Worker;
+  private executorAPI: ValhallaExecutor | Remote<ValhallaExecutor>;
+  private _options: Options;
+
+  public get options(): Options {
+    return this._options;
+  }
+
+  constructor(options: Options = {}) {
+    this._options = { ...defaultOptions, ...options };
+    if (this.options.worker) {
+      this.worker = new Worker(new URL('./valhalla.worker', import.meta.url), { type: 'module' });
+      this.executorAPI = wrap<ValhallaExecutor>(this.worker);
+    } else {
+      this.executorAPI = new ValhallaExecutor();
+    }
+  }
+
+  public destroy(): void {
+    this.worker?.terminate();
+  }
+
+  public request(waypoints: Waypoint[], opts: RequestOptions): Promise<ValhallaRoutingData> {
+    const url = this.buildUrl(waypoints, { ...this.options, ...opts });
+    const requestOptions = {
+      ...this.options,
+      ...opts,
+      url,
+      requestLocations: waypoints.map(({ position }, index) => ({
+        lat: position.lat,
+        lon: position.lng,
+        type: index === 0 || index === waypoints.length - 1 ? 'break' : 'via',
+      })),
+    };
+    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 query = new URLSearchParams(
+      Object.entries(opts.queryParams ?? {}).map(([key, value]) => [key, String(value)]),
+    ).toString();
+    const url = `${opts.baseUrl ?? defaultOptions.baseUrl}${query ? `?${query}` : ''}`;
+    return opts.buildUrl ? opts.buildUrl({ waypoints, options: opts }, url) : url;
+  }
+}

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

@@ -0,0 +1,95 @@
+import type {
+  AnyRoutingDataResponse,
+  RequestOptions,
+  RouteSummary,
+  Waypoint,
+} from '@any-routing/core';
+import type { ExecutorRequestOptions } from './valhalla.executor';
+
+export type ValhallaLocationType = 'break' | 'through' | 'via' | 'break_through';
+export type ValhallaUnits = 'kilometers' | 'miles';
+
+export interface ValhallaRouteSummary extends RouteSummary {
+  rawRoute: ValhallaRawTrip;
+}
+
+export interface ValhallaRoutingData extends AnyRoutingDataResponse {
+  routes: ValhallaRouteSummary[];
+  requestOptions: ExecutorRequestOptions;
+}
+
+export interface ValhallaRawManeuver {
+  type?: number;
+  instruction?: string;
+  length?: number;
+  time?: number;
+  begin_shape_index?: number;
+  end_shape_index?: number;
+  [key: string]: unknown;
+}
+
+export interface ValhallaRawLeg {
+  shape: string;
+  summary?: { length?: number; time?: number; cost?: number };
+  maneuvers?: ValhallaRawManeuver[];
+}
+
+export interface ValhallaRawLocation {
+  lat: number;
+  lon: number;
+  type?: ValhallaLocationType;
+  original_index?: number;
+}
+
+export interface ValhallaRawTrip {
+  locations: ValhallaRawLocation[];
+  legs: ValhallaRawLeg[];
+  summary?: { length?: number; time?: number; cost?: number };
+  status?: number;
+  status_message?: string;
+  units?: string;
+  [key: string]: unknown;
+}
+
+export interface ValhallaApiResponse {
+  trip?: ValhallaRawTrip;
+  alternates?: Array<{ trip: ValhallaRawTrip }>;
+  error_code?: number;
+  error?: string;
+  status?: number;
+  status_message?: string;
+}
+
+export type Options = {
+  baseUrl?: string;
+  worker?: boolean;
+  costing?: string;
+  costingOptions?: Record<string, unknown>;
+  units?: ValhallaUnits;
+  language?: string;
+  alternatives?: number;
+  shapeFormat?: 'polyline6' | 'polyline5';
+  directionsOptions?: Record<string, unknown>;
+  queryParams?: Record<string, string | number | boolean>;
+  requestParams?: RequestInit;
+  buildUrl?: (
+    ctx: { waypoints: Waypoint[]; options: Options & RequestOptions },
+    url: string,
+  ) => string;
+};
+
+export class ValhallaAPIError extends Error {
+  constructor(
+    message: string,
+    public readonly status?: number,
+    public readonly body?: {
+      error?: string;
+      error_code?: number;
+      status_code?: number;
+      status: string;
+    },
+  ) {
+    super(message);
+    this.name = 'ValhallaAPIError';
+  }
+}

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

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ValhallaExecutor } from './valhalla.executor';
+
+describe('ValhallaExecutor', () => {
+  it('posts a Valhalla request and normalizes polyline geometry', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          trip: {
+            locations: [
+              { lat: 38.5, lon: -120.2 },
+              { lat: 40.7, lon: -120.95 },
+            ],
+            legs: [
+              {
+                shape: '_p~iF~ps|U_ulLnnqC_mqNvxq`@',
+                summary: { length: 100, time: 12 },
+              },
+            ],
+            summary: { length: 100, time: 12 },
+            status: 0,
+          },
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await new ValhallaExecutor().request({
+      url: 'https://example.test/route',
+      mode: 'default',
+      requestLocations: [
+        { lat: 38.5, lon: -120.2, type: 'break' },
+        { lat: 40.7, lon: -120.95, type: 'break' },
+      ],
+      costing: 'auto',
+      units: 'kilometers',
+      shapeFormat: 'polyline5',
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://example.test/route',
+      expect.objectContaining({
+        method: 'POST',
+        body: expect.stringContaining('"locations"'),
+      }),
+    );
+    expect(result.routes[0]?.distance).toBe(100);
+    expect(result.routes[0]?.path).toEqual([
+      [38.5, -120.2],
+      [40.7, -120.95],
+      [43.252, -126.453],
+    ]);
+    expect(result.routesShapeGeojson.features[0]?.geometry.coordinates[0]).toEqual([-120.2, 38.5]);
+  });
+});

package/src/lib/valhalla.executor.ts

@@ -0,0 +1,180 @@
+import bbox from '@turf/bbox';
+import { featureCollection, lineString } from '@turf/helpers';
+import type { BBox, Feature, LineString } from 'geojson';
+import { Requester, UnauthorizedError } from '@any-routing/core';
+import {
+  ValhallaAPIError,
+  type Options,
+  type ValhallaApiResponse,
+  type ValhallaRawLeg,
+  type ValhallaRawTrip,
+  type ValhallaRouteSummary,
+  type ValhallaRoutingData,
+} from './valhalla-provider.types';
+
+export type ExecutorRequestOptions = {
+  url: string;
+  requestLocations: Array<{ lat: number; lon: number; type: string }>;
+} & Options;
+
+type ShapeProperties = { waypoint: number; routeId: number };
+
+export class ValhallaExecutor {
+  private readonly requester = new Requester();
+
+  async request(opts: ExecutorRequestOptions): Promise<ValhallaRoutingData> {
+    const body = {
+      locations: opts.requestLocations,
+      costing: opts.costing,
+      costing_options: opts.costingOptions,
+      units: opts.units,
+      language: opts.language,
+      alternates: opts.alternatives ?? 0,
+      shape_format: opts.shapeFormat,
+      directions_options: opts.directionsOptions,
+    };
+
+    try {
+      const response = (await this.requester.request(opts.url, {
+        ...opts.requestParams,
+        method: 'POST',
+        headers: {
+          ...opts.requestParams?.headers,
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      })) as ValhallaApiResponse;
+
+      if (!response.trip || (response.trip.status && response.trip.status !== 0)) {
+        throw new Error(
+          response.error ||
+            response.status_message ||
+            response.trip?.status_message ||
+            'Valhalla returned no route',
+        );
+      }
+
+      const trips = [response.trip, ...(response.alternates ?? []).map(({ trip }) => trip)];
+      const routes = trips.map((trip, routeId) => summarizeRoute(trip, routeId, opts.shapeFormat));
+      const features = routes.flatMap((route, fid) =>
+        route.shape.features.map((feature) => ({
+          id: fid,
+          ...feature,
+          properties: { ...feature.properties, routeId: route.id, id: fid },
+        })),
+      );
+      const routesShapeGeojson = featureCollection(features);
+
+      return {
+        routesShapeBounds: bbox(routesShapeGeojson) as BBox,
+        rawResponse: response,
+        routes,
+        selectedRouteId: routes.length ? 0 : null,
+        routesShapeGeojson,
+        version: performance.now(),
+        latest: !this.requester.hasPendingRequests,
+        requestOptions: opts,
+      };
+    } catch (error: unknown) {
+      if (error instanceof Response) {
+        const body = await error.json();
+
+        if (error.status === 401) {
+          throw new UnauthorizedError(body);
+        }
+
+        throw new ValhallaAPIError(
+          body.error || body.status_message || 'Valhalla returned an error',
+          error.status,
+          body
+        );
+      }
+
+      throw error;
+    }
+  }
+
+  hasPendingRequests(): boolean {
+    return this.requester.hasPendingRequests;
+  }
+
+  abortAllRequests(): void {
+    this.requester.abortAllRequests();
+  }
+}
+
+function summarizeRoute(
+  trip: ValhallaRawTrip,
+  routeId: number,
+  shapeFormat: Options['shapeFormat'],
+): ValhallaRouteSummary {
+  const now = new Date();
+  const precision = shapeFormat === 'polyline5' ? 5 : 6;
+  const legPaths = trip.legs.map((leg) => decodePolyline(leg.shape, precision));
+  const path = legPaths.flatMap((legPath, index) => (index ? legPath.slice(1) : legPath));
+  const shapeFeatures: Feature<LineString, ShapeProperties>[] = legPaths
+    .filter((legPath) => legPath.length > 1)
+    .map((legPath, waypoint) =>
+      lineString(
+        legPath.map(([lat, lon]) => [lon, lat]),
+        { waypoint, routeId },
+      ),
+    );
+  const summary = trip.summary ?? {};
+  const duration =
+    summary.time ?? trip.legs.reduce((total, leg) => total + (leg.summary?.time ?? 0), 0);
+  const distance =
+    summary.length ?? trip.legs.reduce((total, leg) => total + (leg.summary?.length ?? 0), 0);
+  const locations = trip.locations.map(({ lat, lon }) => ({ lat, lng: lon }));
+
+  return {
+    id: routeId,
+    durationTime: duration,
+    distance,
+    arriveTime: new Date(now.getTime() + duration * 1000),
+    departureTime: now,
+    path,
+    waypoints: locations,
+    shape: featureCollection(shapeFeatures),
+    rawRoute: trip,
+  };
+}
+
+function decodePolyline(encoded: string, precision: number): Array<[number, number]> {
+  const coordinates: Array<[number, number]> = [];
+  const factor = 10 ** precision;
+  let index = 0;
+  let latitude = 0;
+  let longitude = 0;
+
+  while (index < encoded.length) {
+    const latitudeResult = decodeValue(encoded, index);
+    index = latitudeResult.index;
+    latitude += latitudeResult.value;
+    const longitudeResult = decodeValue(encoded, index);
+    index = longitudeResult.index;
+    longitude += longitudeResult.value;
+    coordinates.push([latitude / factor, longitude / factor]);
+  }
+
+  return coordinates;
+}
+
+function decodeValue(encoded: string, start: number): { value: number; index: number } {
+  let result = 0;
+  let shift = 0;
+  let index = start;
+  let byte: number;
+
+  do {
+    if (index >= encoded.length) {
+      throw new Error('Invalid Valhalla polyline geometry');
+    }
+    byte = encoded.charCodeAt(index++) - 63;
+    result |= (byte & 0x1f) << shift;
+    shift += 5;
+  } while (byte >= 0x20);
+
+  return { value: (result & 1) !== 0 ? ~(result >> 1) : result >> 1, index };
+}

package/src/lib/valhalla.worker.ts

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

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/valhalla-data-provider',
+  plugins: [
+    nxViteTsPaths(),
+    nxCopyAssetsPlugin(['*.md']),
+    dts({
+      entryRoot: 'src',
+      tsconfigPath: path.join(import.meta.dirname, 'tsconfig.lib.json'),
+      pathsToAliases: false,
+    }),
+  ],
+  build: {
+    outDir: '../../dist/libs/valhalla-data-provider',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: { transformMixedEsModules: true },
+    lib: {
+      entry: 'src/index.ts',
+      name: 'valhalla-data-provider',
+      fileName: 'index',
+      formats: ['es' as const],
+    },
+    rolldownOptions: { external: [] },
+  },
+  test: {
+    name: 'valhalla-data-provider',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+  },
+}));