Core Package API

The @route-optimization/core package provides the foundation for all other packages, including TypeScript types, map adapters, and utility functions.

Installation

npm install @route-optimization/core

Types

Route

The main type representing a delivery or transportation route.

interface Route {
  id: string;
  vehicleId: string;
  metadata?: {
    startTime?: string;
    endTime?: string;
    startLocation?: LatLng;
    endLocation?: LatLng;
    [key: string]: any;
  };
  stops: Stop[];
  segments?: RouteSegment[];
  totalDistance?: number;
  totalDuration?: number;
}

Properties:

Property	Type	Required	Description
id	string	Yes	Unique route identifier
vehicleId	string	Yes	Vehicle assigned to this route
metadata	object	No	Additional route information
stops	Stop[]	Yes	Ordered list of stops
segments	RouteSegment[]	No	Path segments between stops
totalDistance	number	No	Total distance in meters
totalDuration	number	No	Total duration in seconds

Stop

Represents a single location on a route.

interface Stop {
  id: string;
  location: LatLng;
  type: StopType;
  sequence: number;
  label?: string;
  arrivalTime?: string;
  departureTime?: string;
  serviceDuration?: number;
  metadata?: {
    markerConfig?: MarkerConfig;
    [key: string]: any;
  };
}

Properties:

Property	Type	Required	Description
id	string	Yes	Unique stop identifier
location	LatLng	Yes	Geographic coordinates
type	StopType	Yes	Type of stop
sequence	number	Yes	Order in route (0-based)
label	string	No	Display label
arrivalTime	string	No	Expected arrival (ISO 8601)
departureTime	string	No	Expected departure (ISO 8601)
serviceDuration	number	No	Service time in seconds
metadata	object	No	Additional stop data

StopType

type StopType = 'START' | 'END' | 'PICKUP' | 'DELIVERY' | 'WAYPOINT';

LatLng

Geographic coordinates.

interface LatLng {
  lat: number;
  lng: number;
}

Vehicle

Vehicle information and constraints.

interface Vehicle {
  id: string;
  type?: string;
  capacity?: number;
  metadata?: {
    [key: string]: any;
  };
}

MapConfig

Configuration for map initialization.

interface MapConfig {
  apiKey: string;
  container: string | HTMLElement;
  center?: LatLng;
  zoom?: number;
  mapTypeId?: string;
  styles?: google.maps.MapTypeStyle[];
  options?: google.maps.MapOptions;
}

RouteRenderOptions

Options for rendering routes on the map.

interface RouteRenderOptions {
  color?: string;
  polyline?: {
    strokeColor?: string;
    strokeWeight?: number;
    strokeOpacity?: number;
    geodesic?: boolean;
    zIndex?: number;
    icons?: google.maps.IconSequence[];
  };
}

MarkerConfig

Configuration for map markers.

interface MarkerConfig {
  label?: string;
  color?: string;
  icon?: string | google.maps.Icon | google.maps.Symbol;
}

GoogleMapsAdapter

The main adapter for Google Maps integration.

Constructor

const adapter = new GoogleMapsAdapter(options?: MapAdapterOptions);

Methods

initialize()

Initialize the map instance.

await adapter.initialize(config: MapConfig): Promise<void>

Example:

await adapter.initialize({
  apiKey: 'YOUR_API_KEY',
  container: document.getElementById('map')!,
  center: { lat: 13.7563, lng: 100.5018 },
  zoom: 12,
});

renderRoute()

Render a route on the map.

adapter.renderRoute(route: Route, options?: RouteRenderOptions): void

Example:

adapter.renderRoute(route, {
  color: '#FF0000',
  polyline: {
    strokeWeight: 5,
    strokeOpacity: 0.8,
  },
});

clearRoutes()

Remove all routes from the map.

adapter.clearRoutes(): void

addMarker()

Add a marker for a stop.

adapter.addMarker(stop: Stop, config?: MarkerConfig): void

removeMarker()

Remove a specific marker.

adapter.removeMarker(stopId: string): void

clearMarkers()

Remove all markers.

adapter.clearMarkers(): void

setCenter()

Set map center.

adapter.setCenter(center: LatLng): void

setZoom()

Set zoom level.

adapter.setZoom(zoom: number): void

fitBounds()

Fit map to show all markers.

adapter.fitBounds(bounds?: MapBounds): void

getBounds()

Get current map bounds.

adapter.getBounds(): MapBounds | null

getMapInstance()

Get the underlying Google Maps instance.

adapter.getMapInstance(): google.maps.Map | null

Utility Functions

calculateDistance()

Calculate distance between two coordinates (Haversine formula).

import { calculateDistance } from '@route-optimization/core';

const distance = calculateDistance(
  { lat: 13.7563, lng: 100.5018 },
  { lat: 13.7467, lng: 100.5342 }
);
// Returns distance in meters

calculateBounds()

Calculate bounds for a set of coordinates.

import { calculateBounds } from '@route-optimization/core';

const bounds = calculateBounds([
  { lat: 13.7563, lng: 100.5018 },
  { lat: 13.7467, lng: 100.5342 },
]);
// Returns: { north, south, east, west }

validateRoute()

Validate a route object.

import { validateRoute } from '@route-optimization/core';

const isValid = validateRoute(route);
// Returns true if route is valid

Examples

Basic Usage

import { GoogleMapsAdapter } from '@route-optimization/core';
import type { Route } from '@route-optimization/core';

const adapter = new GoogleMapsAdapter();

await adapter.initialize({
  apiKey: 'YOUR_API_KEY',
  container: 'map',
  center: { lat: 13.7563, lng: 100.5018 },
  zoom: 12,
});

const route: Route = {
  id: 'route-1',
  vehicleId: 'vehicle-1',
  stops: [
    {
      id: 'depot',
      location: { lat: 13.7563, lng: 100.5018 },
      type: 'START',
      sequence: 0,
    },
    {
      id: 'delivery-1',
      location: { lat: 13.7467, lng: 100.5342 },
      type: 'DELIVERY',
      sequence: 1,
    },
  ],
};

adapter.renderRoute(route);

With Custom Styling

adapter.renderRoute(route, {
  color: '#4CAF50',
  polyline: {
    strokeWeight: 6,
    strokeOpacity: 0.9,
    geodesic: true,
  },
});

Event Handling

const adapter = new GoogleMapsAdapter({
  events: {
    onClick: (latLng) => {
      console.log('Map clicked:', latLng);
    },
    onZoomChanged: (zoom) => {
      console.log('Zoom changed:', zoom);
    },
    onBoundsChanged: (bounds) => {
      console.log('Bounds changed:', bounds);
    },
  },
});

Next Steps

• React Package API
• Vue Package API
• Vanilla Package API
• Examples