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

package/README.md

@@ -0,0 +1,31 @@
+# osrm-data-provider
+
+`AnyRoutingDataProvider` implementation backed by an [OSRM](https://project-osrm.org/) HTTP server (`route` service, see the [OSRM HTTP API docs](https://project-osrm.org/docs/v5.24.0/api/#requests)).
+
+## Usage
+
+```ts
+import { AnyRouting } from '@any-routing/core';
+import { OsrmProvider } from '@any-routing/osrm-data-provider';
+
+const dataProvider = new OsrmProvider({
+  baseUrl: 'https://router.project-osrm.org/route/v1/driving',
+  alternatives: 2,
+});
+
+const routing = new AnyRouting({
+  dataProvider,
+  waypointsSyncStrategy: 'none',
+});
+```
+
+By default requests run inside a Web Worker (`worker: true`), mirroring `@any-routing/here-data-provider`. Set `worker: false` to run the executor on the main thread instead.
+
+## Building
+
+Run `nx build osrm-data-provider` to build the library.
+
+## Running unit tests
+
+Run `nx test osrm-data-provider` to execute the unit tests via [Vitest](https://vitest.dev/).
+

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

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

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

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

@@ -0,0 +1,120 @@
+import { wrap, Remote } from 'comlink';
+
+import { ExecutorRequestOptions, OsrmExecutor } from './osrm.executor';
+import type {
+  AnyRoutingDataProvider,
+  RequestOptions,
+  Waypoint,
+  WaypointPosition,
+} from '@any-routing/core';
+import { OsrmRoutingData, Options } from './osrm-provider.types';
+
+const defaultOptions: Partial<Options> = {
+  baseUrl: 'https://router.project-osrm.org/route/v1/driving',
+  worker: true,
+  alternatives: 0,
+  steps: true,
+  geometries: 'geojson',
+  overview: 'full',
+};
+
+export class OsrmProvider implements AnyRoutingDataProvider {
+  private worker?: Worker;
+  // Comlink's `wrap` returns a `Remote<T>` proxy whose methods always
+  // resolve to promises, even for originally-synchronous ones — typing
+  // this union up front avoids the `@ts-ignore` a plain assignment would
+  // otherwise need.
+  private executorAPI: OsrmExecutor | Remote<OsrmExecutor>;
+  private _options: Options;
+
+  public get options(): Options {
+    return this._options;
+  }
+
+  constructor(options: Options = {}) {
+    this._options = { ...defaultOptions, ...options };
+
+    if (this.options.worker === true) {
+      this.worker = new Worker(new URL('./osrm.worker', import.meta.url), {
+        type: 'module',
+      });
+
+      this.executorAPI = wrap<OsrmExecutor>(this.worker);
+    } else {
+      this.executorAPI = new OsrmExecutor();
+    }
+  }
+
+  public destroy(): void {
+    if (this.worker) {
+      this.worker.terminate();
+    }
+  }
+
+  public request(waypoints: Waypoint[], opts: RequestOptions): Promise<OsrmRoutingData> {
+    const url = this.buildUrl(waypoints, { ...this.options, ...opts });
+
+    // `buildUrl` is a function and must never be forwarded into
+    // `requestParams` below — when running with `worker: true`,
+    // `executorAPI` is a Comlink `Remote<OsrmExecutor>` and the call goes
+    // through `postMessage`'s structured clone algorithm, which cannot
+    // clone functions and throws `DataCloneError` at runtime.
+    const requestOptions = { ...this.options, ...opts, url };
+    delete requestOptions.buildUrl;
+    const requestParams: ExecutorRequestOptions = requestOptions;
+
+    return this.executorAPI.request(requestParams);
+  }
+
+  public async abortAllRequests(): Promise<void> {
+    await this.executorAPI.abortAllRequests();
+  }
+
+  public setOption<T extends keyof Options>(optionKey: T, value: Options[T]): void {
+    this.options[optionKey] = value;
+  }
+
+  public async hasPendingRequests(): Promise<boolean> {
+    return await this.executorAPI.hasPendingRequests();
+  }
+
+  private buildUrl(waypoints: Waypoint[], opts: Options & RequestOptions): string {
+    if (!waypoints[0] || !waypoints[waypoints.length - 1]) {
+      throw new Error('At least two waypoints are required');
+    }
+
+    const coordinates = waypoints.map((w) => this.formatWp(w.position)).join(';');
+
+    const queryParamsObj: Record<string, string | number | boolean | undefined | null> = {
+      alternatives: opts.mode === 'default' ? opts.alternatives ?? 0 : 0,
+      steps: opts.steps,
+      geometries: opts.geometries || 'geojson',
+      overview: opts.overview || 'full',
+      continue_straight: opts.continueStraight,
+      annotations: opts.annotations,
+      ...opts.queryParams,
+    };
+
+    // Only truthy/explicitly-set values are sent, matching OSRM's own
+    // defaults for anything omitted (mirrors here-data-provider's filter).
+    const queryParams: Record<string, string> = Object.entries(queryParamsObj).reduce(
+      (acc, [key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          acc[key] = String(value);
+        }
+        return acc;
+      },
+      {} as Record<string, string>,
+    );
+
+    const qp = new URLSearchParams(queryParams).toString();
+
+    const url = `${this.options.baseUrl}/${coordinates}${qp ? `?${qp}` : ''}`;
+
+    return this.options.buildUrl ? this.options.buildUrl({ waypoints, options: opts }, url) : url;
+  }
+
+  private formatWp({ lat, lng }: WaypointPosition): string {
+    return `${lng},${lat}`;
+  }
+}

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

@@ -0,0 +1,95 @@
+import type { AnyRoutingDataResponse, RequestOptions, RouteSummary, Waypoint } from '@any-routing/core';
+import type { ExecutorRequestOptions } from './osrm.executor';
+
+export type OsrmGeometry = 'polyline' | 'polyline6' | 'geojson';
+export type OsrmOverview = 'simplified' | 'full' | 'false';
+
+export interface OsrmRouteSummary extends RouteSummary {
+  rawRoute: OsrmRawRoute;
+}
+
+export interface OsrmRoutingData extends AnyRoutingDataResponse {
+  routes: OsrmRouteSummary[];
+  requestOptions: ExecutorRequestOptions;
+}
+
+export type Options = {
+  /**
+   * Base URL of the OSRM HTTP server up to and including the profile, e.g.
+   * `https://router.project-osrm.org/route/v1/driving`. `{coordinates}` and
+   * query options are appended by this provider.
+   */
+  baseUrl?: string;
+  worker?: boolean;
+  alternatives?: number;
+  steps?: boolean;
+  annotations?: boolean | 'nodes' | 'distance' | 'duration' | 'datasources' | 'weight' | 'speed';
+  geometries?: OsrmGeometry;
+  overview?: OsrmOverview;
+  continueStraight?: 'default' | boolean;
+  queryParams?: Record<string, unknown>;
+  requestParams?: RequestInit;
+  buildUrl?: (ctx: { waypoints: Waypoint[]; options: Options & RequestOptions }, url: string) => string;
+};
+
+// ---------------------------------------------------------------------------
+// OSRM `route` service raw response types (the subset the executor reads).
+// Modeled after https://project-osrm.org/docs/v5.24.0/api/#route-service and
+// the OSRM HTTP API docs. `geometries=geojson` is always requested by this
+// provider so `geometry` is always a GeoJSON `LineString`.
+// ---------------------------------------------------------------------------
+
+export interface OsrmRawLineStringGeometry {
+  type: 'LineString';
+  coordinates: [number, number][];
+}
+
+export interface OsrmRawStepManeuver {
+  location: [number, number];
+  bearing_before: number;
+  bearing_after: number;
+  type: string;
+  modifier?: string;
+  exit?: number;
+}
+
+export interface OsrmRawStep {
+  distance: number;
+  duration: number;
+  weight?: number;
+  name: string;
+  ref?: string;
+  geometry: OsrmRawLineStringGeometry;
+  maneuver: OsrmRawStepManeuver;
+}
+
+export interface OsrmRawLeg {
+  distance: number;
+  duration: number;
+  weight?: number;
+  summary?: string;
+  steps: OsrmRawStep[];
+}
+
+export interface OsrmRawRoute {
+  distance: number;
+  duration: number;
+  weight?: number;
+  weight_name?: string;
+  geometry: OsrmRawLineStringGeometry;
+  legs: OsrmRawLeg[];
+}
+
+export interface OsrmRawWaypoint {
+  hint?: string;
+  distance: number;
+  name: string;
+  location: [number, number];
+}
+
+export interface OsrmApiResponse {
+  code: string;
+  message?: string;
+  waypoints?: OsrmRawWaypoint[];
+  routes?: OsrmRawRoute[];
+}

package/src/lib/osrm.executor.ts

@@ -0,0 +1,156 @@
+import bbox from '@turf/bbox';
+import { featureCollection, lineString } from '@turf/helpers';
+import type { BBox, Feature, LineString } from 'geojson';
+
+import { type Mode, Requester, type WaypointPosition } from '@any-routing/core';
+
+import type {
+  Options,
+  OsrmApiResponse,
+  OsrmRawLeg,
+  OsrmRawRoute,
+  OsrmRouteSummary,
+  OsrmRoutingData,
+} from './osrm-provider.types';
+
+export type ExecutorRequestOptions = { url: string; mode: Mode } & Options;
+
+/** Properties attached to each rendered segment of a route's shape. */
+type ShapeFeatureProperties = {
+  waypoint: number;
+  routeId: number;
+};
+
+export class OsrmExecutor {
+  private readonly requester = new Requester();
+
+  async request(opts: ExecutorRequestOptions): Promise<OsrmRoutingData> {
+    const data = (await this.requester.request(opts.url, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+      },
+      ...opts.requestParams,
+    })) as OsrmApiResponse;
+
+    if (data.code !== 'Ok' || !data.routes?.length) {
+      throw new Error(data.message || `OSRM request failed with code "${data.code}"`);
+    }
+
+    const routeSummaries = data.routes.map((route, routeId) =>
+      summarizeRoute(route, routeId),
+    );
+
+    const features = routeSummaries.flatMap((routeSummary, fid) =>
+      routeSummary.shape.features.map((feature) => ({
+          id: fid,
+          ...feature,
+          properties: {
+            ...feature.properties,
+            id: fid,
+            routeId: routeSummary.id,
+          },
+      })),
+    );
+
+    const routesShapeGeojson = featureCollection(features);
+
+    return {
+      routesShapeBounds: bbox(routesShapeGeojson) as BBox,
+      rawResponse: data,
+      routes: routeSummaries,
+      selectedRouteId: routeSummaries.length ? 0 : null,
+      routesShapeGeojson,
+      version: performance.now(),
+      latest: !this.requester.hasPendingRequests,
+      mode: opts.mode,
+      requestOptions: opts,
+    };
+  }
+
+  hasPendingRequests() {
+    return this.requester.hasPendingRequests;
+  }
+
+  abortAllRequests() {
+    this.requester.abortAllRequests();
+  }
+}
+
+/**
+ * Waypoints introduced by a leg: OSRM legs don't carry per-leg
+ * departure/arrival coordinates directly, so waypoints are instead derived
+ * from the route's own `geometry` boundaries via the accumulated leg
+ * distances — simpler and sufficient here: every leg boundary is a waypoint,
+ * taken from the first/last coordinate of the leg's own geometry (built up
+ * from its steps).
+ */
+function extractLegWaypoints(leg: OsrmRawLeg): WaypointPosition[] {
+  const firstStep = leg.steps[0];
+  const lastStep = leg.steps[leg.steps.length - 1];
+
+  if (!firstStep || !lastStep) {
+    return [];
+  }
+
+  const [lng, lat] = firstStep.maneuver.location;
+
+  return [{ lat, lng }];
+}
+
+function buildLegShape(
+  leg: OsrmRawLeg,
+  routeId: number,
+  waypointIndex: number,
+): Feature<LineString, ShapeFeatureProperties>[] {
+  const legPath = leg.steps.flatMap((step) => step.geometry.coordinates);
+
+  if (!legPath.length) {
+    return [];
+  }
+
+  return [
+    lineString(legPath, { waypoint: waypointIndex, routeId }) as Feature<
+      LineString,
+      ShapeFeatureProperties
+    >,
+  ];
+}
+
+const summarizeRoute = (route: OsrmRawRoute, routeId: number): OsrmRouteSummary => {
+  const now = new Date();
+
+  let waypoints: WaypointPosition[] = [];
+  let shapeFeatures: Feature<LineString, ShapeFeatureProperties>[] = [];
+  let waypointIndex = 0;
+
+  route.legs.forEach((leg, index) => {
+    waypoints = [...waypoints, ...extractLegWaypoints(leg)];
+    shapeFeatures = [...shapeFeatures, ...buildLegShape(leg, routeId, waypointIndex)];
+
+    const isLastLeg = index === route.legs.length - 1;
+    if (isLastLeg) {
+      const lastStep = leg.steps[leg.steps.length - 1];
+      if (lastStep) {
+        const [lng, lat] = lastStep.maneuver.location;
+        waypoints = [...waypoints, { lat, lng }];
+      }
+    }
+
+    waypointIndex += 1;
+  });
+
+  const path = route.geometry.coordinates.map(([lng, lat]) => [lat, lng]);
+
+  return {
+    id: routeId,
+    durationTime: route.duration,
+    distance: route.distance,
+    path,
+    arriveTime: new Date(now.getTime() + route.duration * 1000),
+    departureTime: now,
+    waypoints,
+    shape: featureCollection(shapeFeatures),
+    rawRoute: route,
+  };
+};

package/src/lib/osrm.worker.ts

@@ -0,0 +1,6 @@
+import { expose } from 'comlink';
+import { OsrmExecutor } from './osrm.executor';
+
+const executor = new OsrmExecutor();
+
+expose(executor);

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "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,23 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx"
+  ]
+}

package/tsconfig.spec.json

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

package/vite.config.mts

@@ -0,0 +1,59 @@
+/// <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/osrm-data-provider',
+  plugins: [
+    nxViteTsPaths(),
+    nxCopyAssetsPlugin(['*.md']),
+    dts({
+      entryRoot: 'src',
+      tsconfigPath: path.join(import.meta.dirname, 'tsconfig.lib.json'),
+      pathsToAliases: false,
+    }),
+  ],
+  // Uncomment this if you are using workers.
+  // worker: {
+  //   plugins: () => [ nxViteTsPaths() ],
+  // },
+  // Configuration for building your library.
+  // See: https://vite.dev/guide/build.html#library-mode
+  build: {
+    outDir: '../../dist/libs/osrm-data-provider',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true,
+    },
+    lib: {
+      // Could also be a dictionary or array of multiple entry points.
+      entry: 'src/index.ts',
+      name: 'osrm-data-provider',
+      fileName: 'index',
+      // Change this to the formats you want to support.
+      // Don't forget to update your package.json as well.
+      formats: ['es' as const],
+    },
+    rolldownOptions: {
+      // External packages that should not be bundled into your library.
+      external: [],
+    },
+  },
+  test: {
+    name: 'osrm-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/osrm-data-provider',
+      provider: 'v8' as const,
+    },
+  },
+}));