@geoapify/route-planner-sdk
Version:
TypeScript SDK for the Geoapify Route Planner API. Supports route optimization, delivery planning, and timeline visualization in browser and Node.js
203 lines (202 loc) • 8.13 kB
TypeScript
import { RoutePlannerResult } from "./models/entities/route-planner-result";
import { Job, Shipment, AddAssignOptions, RemoveOptions, ReoptimizeOptions } from "./models";
/**
* Editor for modifying route planner results.
*
* Provides methods to assign, remove, and add jobs/shipments to agent routes.
* Supports two strategies: reoptimize (default) and preserveOrder.
*
* @example
* ```typescript
* import { RoutePlannerResultEditor, PRESERVE_ORDER, REOPTIMIZE } from '@geoapify/route-planner-sdk';
*
* const editor = new RoutePlannerResultEditor(plannerResult);
*
* // Assign job to agent (with full reoptimization)
* await editor.assignJobs('agent-A', ['job-1']);
*
* // Find optimal insertion point without reordering (Route Matrix API)
* await editor.assignJobs('agent-A', ['job-2'], { strategy: PRESERVE_ORDER });
*
* // Append job to end of route (no API call)
* await editor.assignJobs('agent-A', ['job-2'], { strategy: PRESERVE_ORDER, append: true });
*
* // Remove job while keeping route order
* await editor.removeJobs(['job-3'], { strategy: PRESERVE_ORDER });
*
* // Get the modified result
* const modifiedResult = editor.getModifiedResult();
* ```
*/
export declare class RoutePlannerResultEditor {
private rawData;
private callOptions;
private routingOptions;
private jobEditor;
private shipmentEditor;
/**
* Creates a new RoutePlannerResultEditor.
* Note: The editor works on a cloned copy of the result, not the original.
*
* @param result - The route planner result to edit
*/
constructor(result: RoutePlannerResult);
/**
* Assigns jobs to an agent. Removes the jobs if they're currently assigned to another agent.
*
* @param agentIdOrIndex - The ID or index of the agent
* @param jobIndexesOrIds - Array of job IDs or indexes to assign
* @param options - Assignment options
* @returns Promise resolving to true if successful
*
* @example
* ```typescript
* // Default: full reoptimization (Route Planner API)
* await editor.assignJobs('agent-A', ['job-1', 'job-2']);
*
* // Find optimal insertion point (Route Matrix API)
* await editor.assignJobs('agent-A', ['job-1'], { strategy: 'preserveOrder' });
*
* // Insert at specific position (no API call)
* await editor.assignJobs('agent-A', ['job-2'], {
* strategy: 'preserveOrder',
* afterId: 'job-1'
* });
*
* // Append to end of route (no API call)
* await editor.assignJobs('agent-A', ['job-1'], {
* strategy: 'preserveOrder',
* append: true
* });
* ```
*/
assignJobs(agentIdOrIndex: string | number, jobIndexesOrIds: number[] | string[], options?: AddAssignOptions): Promise<boolean>;
/**
* Assigns shipments to an agent. Removes the shipments if they're currently assigned to another agent.
*
* @param agentIdOrIndex - The ID or index of the agent
* @param shipmentIndexesOrIds - Array of shipment IDs or indexes to assign
* @param options - Assignment options
* @returns Promise resolving to true if successful
*
* @example
* ```typescript
* // Default: full reoptimization (Route Planner API)
* await editor.assignShipments('agent-A', ['shipment-1']);
*
* // Find optimal insertion point (Route Matrix API)
* await editor.assignShipments('agent-A', ['shipment-1'], { strategy: 'preserveOrder' });
*
* // Append pickup and delivery to end of route (no API call)
* await editor.assignShipments('agent-A', ['shipment-1'], {
* strategy: 'preserveOrder',
* append: true
* });
* ```
*/
assignShipments(agentIdOrIndex: string | number, shipmentIndexesOrIds: number[] | string[], options?: AddAssignOptions): Promise<boolean>;
/**
* Removes jobs from the plan, marking them as unassigned.
*
* @param jobIndexesOrIds - Array of job IDs or indexes to remove
* @param options - Removal options
* @returns Promise resolving to true if successful
*
* @example
* ```typescript
* // Default: reoptimize remaining route
* await editor.removeJobs(['job-1', 'job-2']);
*
* // Remove without reordering remaining jobs
* await editor.removeJobs(['job-1'], { strategy: 'preserveOrder' });
* ```
*/
removeJobs(jobIndexesOrIds: number[] | string[], options?: RemoveOptions): Promise<boolean>;
/**
* Removes shipments from the plan, marking them as unassigned.
*
* @param shipmentIndexesOrIds - Array of shipment IDs or indexes to remove
* @param options - Removal options
* @returns Promise resolving to true if successful
*
* @example
* ```typescript
* // Default: reoptimize remaining route
* await editor.removeShipments(['shipment-1']);
*
* // Remove without reordering remaining shipments
* await editor.removeShipments(['shipment-1'], { strategy: 'preserveOrder' });
* ```
*/
removeShipments(shipmentIndexesOrIds: number[] | string[], options?: RemoveOptions): Promise<boolean>;
/**
* Adds new jobs to an agent's schedule.
*
* @param agentIdOrIndex - The ID or index of the agent
* @param jobs - Array of Job objects to add
* @param options - Assignment options
* @returns Promise resolving to true if successful
*
* @example
* ```typescript
* const newJob = new Job()
* .setId('new-job')
* .setLocation(44.5, 40.2)
* .setDuration(300);
*
* // Default: reoptimize with new job (Route Planner API)
* await editor.addNewJobs('agent-A', [newJob]);
*
* // Find optimal insertion point (Route Matrix API)
* await editor.addNewJobs('agent-A', [newJob], { strategy: 'preserveOrder' });
*
* // Append to end of route (no API call)
* await editor.addNewJobs('agent-A', [newJob], { strategy: 'preserveOrder', append: true });
* ```
*/
addNewJobs(agentIdOrIndex: string | number, jobs: Job[], options?: AddAssignOptions): Promise<boolean>;
/**
* Adds new shipments to an agent's schedule.
*
* @param agentIdOrIndex - The ID or index of the agent
* @param shipments - Array of Shipment objects to add
* @param options - Assignment options
* @returns Promise resolving to true if successful
*
* @example
* ```typescript
* const newShipment = new Shipment()
* .setId('new-shipment')
* .setPickup(new ShipmentStep().setLocation(44.5, 40.2).setDuration(120))
* .setDelivery(new ShipmentStep().setLocation(44.6, 40.3).setDuration(120));
*
* // Default: reoptimize with new shipment (Route Planner API)
* await editor.addNewShipments('agent-A', [newShipment]);
*
* // Find optimal insertion point (Route Matrix API)
* await editor.addNewShipments('agent-A', [newShipment], { strategy: 'preserveOrder' });
*
* // Append to end of route (no API call)
* await editor.addNewShipments('agent-A', [newShipment], {
* strategy: 'preserveOrder',
* append: true
* });
* ```
*/
addNewShipments(agentIdOrIndex: string | number, shipments: Shipment[], options?: AddAssignOptions): Promise<boolean>;
getModifiedResult(): RoutePlannerResult;
reoptimizeAgentPlan(agentIdOrIndex: string | number, options?: ReoptimizeOptions): Promise<boolean>;
addDelayAfterWaypoint(agentIdOrIndex: string | number, waypointIndex: number, delaySeconds: number): void;
/**
* @deprecated use addDelayAfterWaypoint()
*/
addTimeOffsetAfterWaypoint(agentIdOrIndex: string | number, waypointIndex: number, offsetSeconds: number): void;
moveWaypoint(agentIdOrIndex: string | number, fromWaypointIndex: number, toWaypointIndex: number): Promise<void>;
private assertArray;
private normalizeAddAssignOptions;
private resolveInsertPosition;
private validateAfterWaypointIndex;
private normalizeRemoveOptions;
private getJobEditor;
private getShipmentEditor;
}