@any-routing/here-data-provider 0.1.0 → 1.0.0-rc.1

package/README.md

@@ -2,6 +2,10 @@
 
 This library was generated with [Nx](https://nx.dev).
 
+## Building
+
+Run `nx build here-data-provider` to build the library.
+
 ## Running unit tests
 
-Run `nx test here-data-provider` to execute the unit tests via [Jest](https://jestjs.io).
+Run `nx test here-data-provider` to execute the unit tests via [Vitest](https://vitest.dev/).

package/eslint.config.mjs

@@ -0,0 +1,24 @@
+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

@@ -1,18 +1,16 @@
 {
   "name": "@any-routing/here-data-provider",
-  "version": "0.1.0",
-  "private": false,
+  "version": "1.0.0-rc.1",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
   "dependencies": {
-    "@liberty-rider/flexpolyline": "0.1.0",
-    "@turf/bbox": "6.5.0",
-    "@turf/helpers": "6.5.0",
-    "comlink": "4.3.1",
-    "simplify-js": "1.2.4"
-  },
-  "peerDependencies": {
-    "@any-routing/core": "^0.0.0",
-    "tslib": "2.5.0"
-  },
-  "main": "./src/index.js",
-  "types": "./src/index.d.ts"
-}
+    "@any-routing/core": "1.0.0-rc.1",
+    "comlink": "4.4.2",
+    "@here/flexpolyline": "0.1.0",
+    "simplify-js": "1.2.4",
+    "@turf/bbox": "7.4.0",
+    "@turf/helpers": "7.4.0",
+    "@types/geojson": "7946.0.16"
+  }
+}

package/project.json

@@ -0,0 +1,9 @@
+{
+  "name": "here-data-provider",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/here-data-provider/src",
+  "projectType": "library",
+  "tags": [],
+  "// targets": "to see all targets run: nx show project here-data-provider --web",
+  "targets": {}
+}

package/src/{index.d.ts → index.ts}

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

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

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

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

@@ -0,0 +1,148 @@
+import { wrap, Remote } from 'comlink';
+
+import { ExecutorRequestOptions, HereExecutor } from './here.executor';
+import type {
+  AnyRoutingDataProvider,
+  RequestOptions,
+  Waypoint,
+  WaypointPosition,
+} from '@any-routing/core';
+import { HereRoutingData, PluginOptions } from './here-provider.types';
+
+const defaultOptions: Partial<PluginOptions> = {
+  baseUrl: 'https://router.hereapi.com/v8/routes',
+  transportMode: 'car',
+  worker: true,
+  alternatives: 2,
+  shapePolylinePrecision: 0.0000065,
+  routeExcludeNotice: {
+    critical: 'all',
+  },
+};
+
+export class HereProvider 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` the previous version
+  // needed on assignment.
+  private executorAPI: HereExecutor | Remote<HereExecutor>;
+  private _options: PluginOptions;
+
+  public get options(): PluginOptions {
+    return this._options;
+  }
+
+  constructor(defaultModeOptions: PluginOptions) {
+    this._options = { ...defaultOptions, ...defaultModeOptions };
+
+    if (this.options.worker === true) {
+      this.worker = new Worker(new URL('./here.worker', import.meta.url), {
+        type: 'module',
+      });
+
+      this.executorAPI = wrap<HereExecutor>(this.worker);
+    } else {
+      this.executorAPI = new HereExecutor();
+    }
+  }
+
+  public destroy(): void {
+    if (this.worker) {
+      this.worker.terminate();
+    }
+  }
+
+  public request(waypoints: Waypoint[], opts: Record<string, unknown>): Promise<HereRoutingData> {
+    const configOptions = this.options;
+
+    const url = this.buildUrl(waypoints, { ...configOptions, ...opts });
+
+    // `buildUrl` is a function and must never be forwarded into
+    // `requestParams` below — when running with `worker: true`,
+    // `executorAPI` is a Comlink `Remote<HereExecutor>` and the call goes
+    // through `postMessage`'s structured clone algorithm, which cannot
+    // clone functions and throws `DataCloneError` at runtime. A previous
+    // revision of this file destructured `buildUrl` out for exactly this
+    // reason; that got lost in the last edit — restoring it here.
+    const requestOptions = { ...configOptions, ...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 PluginOptions>(optionKey: T, value: PluginOptions[T]): void {
+    this.options[optionKey] = value;
+  }
+
+  public async hasPendingRequests(): Promise<boolean> {
+    return await this.executorAPI.hasPendingRequests();
+  }
+
+  private buildUrl(waypoints: Waypoint[], opts: PluginOptions & RequestOptions): string {
+    if (!waypoints[0] || !waypoints[waypoints.length - 1]) {
+      throw new Error('At least two waypoints are required');
+    }
+
+    const start = waypoints[0].position;
+    const end = waypoints[waypoints.length - 1].position;
+
+    const spans = opts.spans?.join(',') ?? null;
+
+    const returnFields = [...(opts.return || []), 'polyline', 'summary', 'routeLabels'].join(',');
+
+    const queryParamsObj: Record<string, string | number | undefined | null> = {
+      apiKey: opts.apiKey,
+      origin: this.formatWp(start),
+      destination: this.formatWp(end),
+      transportMode: opts.transportMode || '',
+      spans,
+      return: returnFields,
+      alternatives: opts?.alternatives ?? 0,
+      currency: opts.currency || undefined,
+      ...opts.queryParams,
+    };
+
+    if (this.options.selectRouteStrategy === 'cheapest' && !String(queryParamsObj['return']).includes('tolls')) {
+      queryParamsObj['return'] = `${queryParamsObj['return']},tolls`;
+    }
+
+    // Preserves the original truthy filter (drops 0 / '' / null / undefined),
+    // just stringifies everything up front so `URLSearchParams` type-checks.
+    const queryParams: Record<string, string> = Object.entries(queryParamsObj).reduce(
+      (acc, [key, value]) => {
+        if (value) {
+          acc[key] = String(value);
+        }
+        return acc;
+      },
+      {} as Record<string, string>
+    );
+
+    let qp = new URLSearchParams(queryParams).toString();
+
+    if (waypoints.length > 2) {
+      qp += `&${this.serializeWaypoints(waypoints)}`;
+    }
+
+    const url = `${opts.baseUrl}?${qp}`;
+
+    return opts.buildUrl ? opts.buildUrl({ waypoints, options: opts }, url) : url;
+  }
+
+  private serializeWaypoints(waypoints: Waypoint[]): string {
+    return waypoints
+      .slice(1, waypoints.length - 1)
+      .map((w) => `via=${this.formatWp(w.position)}`)
+      .join('&');
+  }
+
+  private formatWp({ lat, lng }: WaypointPosition): string {
+    return `${lat},${lng}`;
+  }
+}

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

@@ -0,0 +1,179 @@
+import type { AnyRoutingDataResponse, LngLatPosition, RequestOptions, RouteSummary, Waypoint } from '@any-routing/core';
+import type { ExecutorRequestOptions } from './here.executor';
+
+export type SelectRouteStrategy = 'fastest' | 'shortest' | 'cheapest' | 'none';
+
+export type RouteExcludeNoticeDefinitions = {
+  [key in 'critical' | 'info']?: string[] | 'all';
+};
+
+/**
+ * HERE's `action` values on `turnByTurnActions` are documented as an
+ * "extensible enum" — HERE can add new maneuver types over time, and
+ * clients are expected to handle unknown values gracefully rather than
+ * fail. We type the values we know about explicitly (for autocomplete /
+ * exhaustiveness where it matters) but keep the type open to any other
+ * string so a future HERE rollout doesn't produce values TypeScript
+ * silently rejects at compile time / mangles at runtime.
+ *
+ * Source: HERE Routing API v8 docs — "What is an action".
+ */
+export type HereActionType =
+  | 'depart'
+  | 'arrive'
+  | 'continue'
+  | 'turn'
+  | 'uTurn'
+  | 'ramp'
+  | 'keep'
+  | 'roundaboutEnter'
+  | 'roundaboutPass'
+  | 'roundaboutExit'
+  | 'exit'
+  | 'ferry'
+  | (string & {});
+
+export type TurnByTurnAction = {
+  action: HereActionType;
+  duration: number;
+  length: number;
+  position: { lat: number; lng: number };
+  offset: number;
+};
+
+export type RoutePath = LngLatPosition[];
+
+export interface HereRouteSummary extends RouteSummary {
+  turnByTurnActions: TurnByTurnAction[];
+  shapePath: RoutePath;
+  rawRoute: HereRawRoute;
+}
+
+export interface HereRoutingData extends AnyRoutingDataResponse {
+  routes: HereRouteSummary[];
+  requestOptions: ExecutorRequestOptions;
+}
+
+export type GeoJsonSplitStrategy = 'jamFactor';
+
+export type BaseOptions = {
+  alternatives?: number;
+  worker?: boolean;
+  apiKey: string;
+  baseUrl?: string;
+  selectRouteStrategy?: SelectRouteStrategy;
+  spans?: string[];
+  return?: string[];
+  currency?: string;
+  transportMode?: string;
+  queryParams?: Record<string, unknown>;
+  requestParams?: RequestInit;
+  routeExcludeNotice?: RouteExcludeNoticeDefinitions;
+  shapePolylinePrecision?: number;
+  geoJSONShapeSplitStrategies?: Array<GeoJsonSplitStrategy>;
+  buildUrl?: (ctx: { waypoints: Waypoint[]; options: BaseOptions & RequestOptions }, url: string) => string;
+};
+
+export type PluginOptions = BaseOptions;
+
+// ---------------------------------------------------------------------------
+// HERE Routing API v8 raw response types (the subset the executor reads).
+// These model the JSON documented at
+// https://docs.here.com/routing/docs/routing-v8-get-started#response and the
+// "What is a span" / "What is a notice" guides. Fields not consumed by this
+// package are intentionally left out rather than fully modeled, and open
+// dictionaries (`spans`) are typed loosely since their shape depends on the
+// `spans=` request parameter the caller chose.
+// ---------------------------------------------------------------------------
+
+export interface HereRawPlace {
+  type: string;
+  location: { lat: number; lng: number };
+  /** Present only when this endpoint was geocoded from a raw waypoint. */
+  originalLocation?: { lat: number; lng: number };
+}
+
+export interface HereRawSectionEndpoint {
+  place: HereRawPlace;
+  time?: string;
+}
+
+export interface HereRawSummary {
+  duration?: number;
+  length?: number;
+  baseDuration?: number;
+}
+
+export interface HereRawFarePrice {
+  value: number;
+  currency: string;
+}
+
+export interface HereRawFare {
+  price?: HereRawFarePrice;
+  convertedPrice?: HereRawFarePrice;
+}
+
+export interface HereRawToll {
+  fares?: HereRawFare[];
+}
+
+export interface HereRawDynamicSpeedInfo {
+  baseSpeed: number;
+  trafficSpeed: number;
+  turnTime?: number;
+}
+
+/**
+ * A single `spans[]` entry. Which attributes are present depends entirely
+ * on the `spans=` query param sent in the request (see "What is a span" in
+ * the HERE docs), so beyond the `offset` every requested attribute name
+ * (`dynamicSpeedInfo`, `names`, `countryCode`, ...) shows up as an optional
+ * key — hence the index signature rather than an exhaustive interface.
+ */
+export interface HereRawSpan {
+  offset: number;
+  dynamicSpeedInfo?: HereRawDynamicSpeedInfo;
+  [attribute: string]: unknown;
+}
+
+export interface HereRawAction {
+  action: HereActionType;
+  duration: number;
+  length: number;
+  offset: number;
+  instruction?: string;
+}
+
+export interface HereRawNotice {
+  code: string;
+  severity: 'critical' | 'info';
+}
+
+export interface HereRawSection {
+  id: string;
+  type: string;
+  departure: HereRawSectionEndpoint;
+  arrival: HereRawSectionEndpoint;
+  summary?: HereRawSummary;
+  polyline: string;
+  spans?: HereRawSpan[];
+  tolls?: HereRawToll[];
+  turnByTurnActions?: HereRawAction[];
+  notices?: HereRawNotice[];
+}
+
+export interface HereRawRouteLabel {
+  name: { value: string; language?: string };
+}
+
+export interface HereRawRoute {
+  id: string;
+  sections: HereRawSection[];
+  routeLabels?: HereRawRouteLabel[];
+}
+
+export interface HereApiResponse {
+  routes: HereRawRoute[];
+  notices?: HereRawNotice[];
+}