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

package/README.md

@@ -0,0 +1,22 @@
+# ors-data-provider
+
+`@any-routing/ors-data-provider` uses the openrouteservice Directions API v2
+GeoJSON endpoint.
+
+```ts
+import { OrsProvider } from '@any-routing/ors-data-provider';
+
+const dataProvider = new OrsProvider({
+  apiKey: 'YOUR_ORS_API_KEY',
+  profile: 'driving-car',
+  alternatives: 2,
+});
+```
+
+Requests use `POST /openrouteservice/v2/directions/{profile}/geojson` on the
+documented `api.heigit.org` server, send
+coordinates as `[longitude, latitude]` pairs, and authenticate with the
+`Authorization` header as required by the
+[openrouteservice Directions API](https://docs.openrouteservice.org/all/docs).
+Requests run in a Web Worker by default; set `worker: false` to execute on the
+main thread.

package/eslint.config.mjs

@@ -0,0 +1,3 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [...baseConfig];

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@any-routing/ors-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",
+    "comlink": "4.4.2",
+    "@turf/bbox": "7.4.0",
+    "@turf/helpers": "7.4.0",
+    "@types/geojson": "7946.0.16"
+  }
+}

package/project.json

@@ -0,0 +1,28 @@
+{
+  "name": "ors-data-provider",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/ors-data-provider/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "@nx/vite:build",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/ors-data-provider",
+        "configFile": "libs/ors-data-provider/vite.config.mts"
+      }
+    },
+    "test": {
+      "executor": "@nx/vitest:test",
+      "options": {
+        "configFile": "libs/ors-data-provider/vite.config.mts"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "lintFilePatterns": ["libs/ors-data-provider/**/*.ts"]
+      }
+    }
+  }
+}

package/src/index.ts

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

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

@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { OrsProvider } from './ors-data-provider';
+
+describe('OrsProvider', () => {
+  it('sends an ORS GeoJSON directions request with longitude/latitude coordinates', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          type: 'FeatureCollection',
+          features: [
+            {
+              type: 'Feature',
+              geometry: {
+                type: 'LineString',
+                coordinates: [
+                  [19, 52],
+                  [20, 53],
+                ],
+              },
+              properties: {
+                summary: { distance: 1000, duration: 120 },
+              },
+            },
+          ],
+        }),
+        { headers: { 'Content-Type': 'application/geo+json' } },
+      ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const provider = new OrsProvider({
+      apiKey: 'test-key',
+      baseUrl: 'https://api.openrouteservice.org/v2/directions',
+      worker: false,
+    });
+    const data = await provider.request(
+      [
+        { position: { lat: 52, lng: 19 } },
+        { position: { lat: 53, lng: 20 } },
+      ],
+      { mode: 'default' },
+    );
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.openrouteservice.org/v2/directions/driving-car',
+      expect.objectContaining({
+        method: 'POST',
+        headers: expect.objectContaining({ Authorization: 'test-key' }),
+      }),
+    );
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toMatchObject({
+      coordinates: [
+        [19, 52],
+        [20, 53],
+      ],
+    });
+    expect(data.routes[0]?.distance).toBe(1000);
+    expect(data.routes[0]?.path).toEqual([
+      [52, 19],
+      [53, 20],
+    ]);
+  });
+});

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

@@ -0,0 +1,83 @@
+import { Remote, wrap } from 'comlink';
+
+import type { AnyRoutingDataProvider, RequestOptions, Waypoint } from '@any-routing/core';
+import { OrsExecutor, type ExecutorRequestOptions } from './ors.executor';
+import type { Options, OrsRoutingData } from './ors-provider.types';
+
+const defaultOptions: Partial<Options> = {
+  baseUrl: 'https://api.heigit.org/openrouteservice/v2/directions',
+  profile: 'driving-car',
+  worker: true,
+  alternatives: 0,
+  preference: 'recommended',
+  units: 'm',
+  instructions: true,
+  instructionsFormat: 'text',
+  geometry: true,
+  maneuvers: false,
+};
+
+export class OrsProvider implements AnyRoutingDataProvider {
+  private worker?: Worker;
+  private executorAPI: OrsExecutor | Remote<OrsExecutor>;
+  private _options: Options;
+
+  public get options(): Options {
+    return this._options;
+  }
+
+  constructor(options: Options) {
+    this._options = { ...defaultOptions, ...options };
+    if (!this.options.apiKey) {
+      throw new Error('An openrouteservice API key is required');
+    }
+
+    if (this.options.worker) {
+      this.worker = new Worker(new URL('./ors.worker', import.meta.url), { type: 'module' });
+      this.executorAPI = wrap<OrsExecutor>(this.worker);
+    } else {
+      this.executorAPI = new OrsExecutor();
+    }
+  }
+
+  public destroy(): void {
+    this.worker?.terminate();
+  }
+
+  public request(waypoints: Waypoint[], opts: RequestOptions): Promise<OrsRoutingData> {
+    const url = this.buildUrl(waypoints, { ...this.options, ...opts });
+    const requestOptions = {
+      ...this.options,
+      ...opts,
+      url,
+      requestCoordinates: waypoints.map(({ position }) => [position.lng, position.lat] as [number, number]),
+    };
+    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 profile = encodeURIComponent(opts.profile ?? 'driving-car');
+    const query = new URLSearchParams(
+      Object.entries(opts.queryParams ?? {}).map(([key, value]) => [key, String(value)]),
+    ).toString();
+    const url = `${opts.baseUrl}/${profile}${query ? `?${query}` : ''}/geojson`;
+    return opts.buildUrl ? opts.buildUrl({ waypoints, options: opts }, url) : url;
+  }
+}

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

@@ -0,0 +1,95 @@
+import type { AnyRoutingDataResponse, RequestOptions, RouteSummary, Waypoint } from '@any-routing/core';
+import type { ExecutorRequestOptions } from './ors.executor';
+
+export type OrsProfile =
+  | 'driving-car'
+  | 'driving-hgv'
+  | 'cycling-regular'
+  | 'cycling-road'
+  | 'cycling-mountain'
+  | 'cycling-electric'
+  | 'foot-walking'
+  | 'foot-hiking'
+  | 'wheelchair'
+  | 'public-transport'
+  | (string & {});
+
+export type OrsPreference = 'fastest' | 'shortest' | 'recommended' | 'custom';
+export type OrsUnits = 'm' | 'km' | 'mi';
+
+export interface OrsRouteSummary extends RouteSummary {
+  rawRoute: OrsRawFeature;
+}
+
+export interface OrsRoutingData extends AnyRoutingDataResponse {
+  routes: OrsRouteSummary[];
+  requestOptions: ExecutorRequestOptions;
+}
+
+export interface OrsRawStep {
+  distance: number;
+  duration: number;
+  instruction?: string;
+  name?: string;
+  type?: number;
+  way_points?: [number, number];
+}
+
+export interface OrsRawSegment {
+  distance: number;
+  duration: number;
+  steps?: OrsRawStep[];
+  way_points?: [number, number];
+}
+
+export interface OrsRawFeatureProperties {
+  summary?: { distance?: number; duration?: number; ascent?: number; descent?: number };
+  segments?: OrsRawSegment[];
+  way_points?: [number, number];
+  [key: string]: unknown;
+}
+
+export interface OrsRawFeature {
+  type: 'Feature';
+  geometry: { type: 'LineString'; coordinates: [number, number][] };
+  properties: OrsRawFeatureProperties;
+}
+
+export interface OrsApiResponse {
+  type: 'FeatureCollection';
+  features?: OrsRawFeature[];
+  bbox?: number[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface OrsApiErrorResponse {
+  error?: {
+    code?: number | string;
+    message?: string;
+  };
+  message?: string;
+  code?: number | string;
+}
+
+export type Options = {
+  apiKey: string;
+  profile?: OrsProfile;
+  baseUrl?: string;
+  worker?: boolean;
+  alternatives?: number;
+  preference?: OrsPreference;
+  units?: OrsUnits;
+  language?: string;
+  instructions?: boolean;
+  instructionsFormat?: 'text' | 'html';
+  maneuvers?: boolean;
+  geometry?: boolean;
+  extraInfo?: string[];
+  attributes?: string[];
+  continueStraight?: boolean;
+  elevation?: boolean;
+  options?: Record<string, unknown>;
+  queryParams?: Record<string, string | number | boolean>;
+  requestParams?: RequestInit;
+  buildUrl?: (ctx: { waypoints: Waypoint[]; options: Options & RequestOptions }, url: string) => string;
+};

package/src/lib/ors.executor.ts

@@ -0,0 +1,136 @@
+import bbox from '@turf/bbox';
+import { featureCollection, lineString } from '@turf/helpers';
+import type { BBox, LineString } from 'geojson';
+
+import { Requester } from '@any-routing/core';
+import type {
+  Options,
+  OrsApiErrorResponse,
+  OrsApiResponse,
+  OrsRawFeature,
+  OrsRouteSummary,
+  OrsRoutingData,
+} from './ors-provider.types';
+
+export type ExecutorRequestOptions = {
+  url: string;
+  requestCoordinates: [number, number][];
+} & Options;
+
+type ShapeProperties = { waypoint: number; routeId: number };
+
+export class OrsExecutor {
+  private readonly requester = new Requester();
+
+  async request(opts: ExecutorRequestOptions): Promise<OrsRoutingData> {
+    const body = {
+      coordinates: opts.requestCoordinates,
+      preference: opts.preference,
+      units: opts.units,
+      language: opts.language,
+      instructions: opts.instructions,
+      instructions_format: opts.instructionsFormat,
+      maneuvers: opts.maneuvers,
+      geometry: opts.geometry,
+      extra_info: opts.extraInfo,
+      attributes: opts.attributes,
+      continue_straight: opts.continueStraight,
+      elevation: opts.elevation,
+      options: opts.options,
+      alternative_routes:
+        opts.alternatives
+          ? { target_count: opts.alternatives }
+          : undefined,
+    };
+    const response = (await this.requester.request(opts.url, {
+      ...opts.requestParams,
+      method: 'POST',
+      headers: {
+        ...opts.requestParams?.headers,
+        Accept: 'application/geo+json, application/json',
+        'Content-Type': 'application/json',
+        Authorization: opts.apiKey,
+      },
+      body: JSON.stringify(body),
+    })) as OrsApiResponse & OrsApiErrorResponse;
+
+    if (response.type !== 'FeatureCollection' || !response.features?.length) {
+      const error = response.error;
+      const message = error?.message ?? response.message;
+      const code = error?.code ?? response.code;
+      throw new Error(
+        message
+          ? `openrouteservice request failed${code ? ` (${code})` : ''}: ${message}`
+          : 'openrouteservice returned no routes',
+      );
+    }
+
+    const routes = response.features.map((route, id) => summarizeRoute(route, id));
+
+    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: response,
+      routes,
+      selectedRouteId: 0,
+      routesShapeGeojson,
+      version: performance.now(),
+      latest: !this.requester.hasPendingRequests,
+      requestOptions: opts,
+    };
+  }
+
+  hasPendingRequests(): boolean {
+    return this.requester.hasPendingRequests;
+  }
+
+  abortAllRequests(): void {
+    this.requester.abortAllRequests();
+  }
+}
+
+function summarizeRoute(route: OrsRawFeature, routeId: number): OrsRouteSummary {
+  const now = new Date();
+  const summary = route.properties.summary ?? {};
+  const path = route.geometry.coordinates.map(([lng, lat]) => [lat, lng]);
+  const segments = route.properties.segments ?? [];
+  const shapeFeatures = segments.flatMap((segment, waypoint) => {
+    const [start, end] = segment.way_points ?? [0, route.geometry.coordinates.length - 1];
+    const coordinates = route.geometry.coordinates.slice(start, end + 1);
+    return coordinates.length > 1 ? [lineString(coordinates, { waypoint, routeId })] : [];
+  });
+  const shape = featureCollection<LineString, ShapeProperties>(
+    shapeFeatures.length
+      ? shapeFeatures
+      : [lineString(route.geometry.coordinates, { waypoint: 0, routeId })],
+  );
+  const waypointIndexes = segments.length
+    ? segments.flatMap((segment, index) => {
+        const [start, end] = segment.way_points ?? [0, route.geometry.coordinates.length - 1];
+        return index === segments.length - 1 ? [start, end] : [start];
+      })
+    : [0, route.geometry.coordinates.length - 1];
+
+  return {
+    id: routeId,
+    durationTime: summary.duration ?? 0,
+    distance: summary.distance ?? 0,
+    arriveTime: new Date(now.getTime() + (summary.duration ?? 0) * 1000),
+    departureTime: now,
+    path,
+    waypoints: waypointIndexes
+      .map((index) => route.geometry.coordinates[index])
+      .filter((point): point is [number, number] => Boolean(point))
+      .map(([lng, lat]) => ({ lat, lng })),
+    shape,
+    rawRoute: route,
+  };
+}

package/src/lib/ors.worker.ts

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

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "target": "es2022",
+    "strict": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "../../dist/out-tsc"
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc"
+  },
+  "include": ["src/**/*.spec.ts", "src/**/*.d.ts"]
+}

package/vite.config.mts

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