@tileflow/routing 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -47,12 +47,14 @@ for (const step of fastest?.legs[0]?.steps ?? []) console.log(step.instruction);
 
 **Request:**
 
-- `locations`: two to five `[longitude, latitude]` positions: an origin, optional stops and a
+- `locations`: two to 25 `[longitude, latitude]` positions: an origin, optional stops and a
   destination. Each stretch between consecutive positions is a leg.
 - `mode`: `driving`, `walking`, `cycling` or `truck`.
 - `alternatives` (optional, 0–2): only between two positions. Fewer come back when no distinct
   alternative exists.
 - `language` (optional): writes the instructions in one of `routingLanguages`.
+- `optimize` (optional): see [Visit stops in the fastest order](#visit-stops-in-the-fastest-order).
+- `departAt` (optional): see [Choose a departure time](#choose-a-departure-time).
 - `vehicle`, `avoid` and `traffic` (optional): see
   [Route a truck around tolls](#route-a-truck-around-tolls).
 
@@ -67,6 +69,41 @@ for (const step of fastest?.legs[0]?.steps ?? []) console.log(step.instruction);
 
 Durations are estimates without traffic; see [Travel times and traffic](#travel-times-and-traffic).
 
+## Visit stops in the fastest order
+
+Set `optimize` to visit the stops between the first and the last location in the fastest order the
+service finds. The first and the last location stay in place; repeat the first to return to it.
+
+```ts
+import {route} from '@tileflow/routing';
+
+const stops: [number, number][] = [
+  [-80.1918, 25.7617],
+  [-80.1312, 25.7795],
+  [-80.2569, 25.7215],
+  [-80.2195, 25.7655],
+  [-80.1918, 25.7617],
+];
+
+const answer = await route({locations: stops, mode: 'driving', optimize: true}, {apiKey});
+
+// The requested index of each location, in the order the route visits them.
+for (const index of answer.locationOrder ?? []) console.log(stops[index]);
+```
+
+The legs of the route follow `locationOrder`. Every two locations must lie within the reach of a
+[matrix](#calculate-a-travel-time-matrix) for the mode: 200 km driving, 10 km walking or
+cycling. An optimized route counts 10 API units, whatever its locations; a route in the given
+order counts 5.
+
+## Choose a departure time
+
+`departAt` says when the route leaves the first location, as `YYYY-MM-DDTHH:mm` in that location's
+local time. The route then respects roads closed at that time where OpenStreetMap records it, and
+each leg states `arriveAt`: its local time at the end of the leg with the UTC offset, such as
+`2027-03-01T16:47-06:00`. It does not add traffic: durations stay
+[without traffic](#travel-times-and-traffic), whatever the time.
+
 ## Route a truck around tolls
 
 <!-- docs:check -->

package/dist/{chunk-MCATD4FU.js → chunk-3P5UQQH3.js}

@@ -12,7 +12,7 @@ import {
   routingNearestResponseSchema,
   routingRouteRequestSchema,
   routingRouteResponseSchema
-} from "./chunk-ECBK2QPL.js";
+} from "./chunk-CDZKLI32.js";
 
 // src/client.ts
 import { z } from "zod";
@@ -30,16 +30,21 @@ var RoutingError = class extends Error {
     this.retryAfterSeconds = input.retryAfterSeconds ?? null;
   }
 };
+function answersOrder(order, locations, optimize) {
+  if (!optimize) return order === void 0;
+  return order?.length === locations && new Set(order).size === locations && order[0] === 0 && order.at(-1) === locations - 1 && order.every((index) => index < locations);
+}
 async function route(request, options) {
   const parsed = routingRouteRequestSchema.safeParse(request);
   if (!parsed.success) throw new Error("Invalid Tileflow route request");
-  const legs = parsed.data.locations.length - 1;
+  const { locations, optimize } = parsed.data;
+  const legs = locations.length - 1;
   return requestRouting(
     "/v1/routing/route",
     parsed.data,
     options,
     routingRouteResponseSchema,
-    (response) => response.routes.length <= (parsed.data.alternatives ?? 0) + 1 && response.routes.every((candidate) => candidate.legs.length === legs)
+    (response) => response.routes.length <= (parsed.data.alternatives ?? 0) + 1 && response.routes.every((candidate) => candidate.legs.length === legs) && answersOrder(response.locationOrder, locations.length, optimize)
   );
 }
 async function isochrone(request, options) {

package/dist/{chunk-ECBK2QPL.js → chunk-CDZKLI32.js}

@@ -42,7 +42,7 @@ var routingLimits = Object.freeze({
   maximumRequestBytes: 8 * 1024,
   maximumResponseBytes: 4 * 1024 * 1024,
   minimumLocations: 2,
-  maximumLocations: 5,
+  maximumLocations: 25,
   maximumAlternatives: 2,
   /** Sum of straight-line distances between consecutive locations, per mode. */
   maximumDirectDistanceMeters: Object.freeze({
@@ -114,11 +114,22 @@ function refineTravelOptions(request, context) {
     context.addIssue({ code: "custom", path: ["avoid"], message: "Avoid each kind once." });
   }
 }
+var localDateTime = z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/u, "Use YYYY-MM-DDTHH:mm, local to the first location.").refine((value) => {
+  const date = /* @__PURE__ */ new Date(`${value}:00Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
+}, "This date does not exist.");
 var routingRouteRequestSchema = z.object({
   locations: z.array(routingPositionSchema).min(routingLimits.minimumLocations).max(routingLimits.maximumLocations),
   ...travelOptions,
   alternatives: z.number().int().min(0).max(routingLimits.maximumAlternatives).optional(),
-  language: z.enum(routingLanguages).optional()
+  language: z.enum(routingLanguages).optional(),
+  /**
+   * Visits the stops between the first and the last location in the fastest order the engine
+   * finds. The first and the last location stay in place; repeat the first to return to it.
+   */
+  optimize: z.boolean().optional(),
+  /** When the route leaves the first location, in that location's local time. */
+  departAt: localDateTime.optional()
 }).strict().superRefine((request, context) => {
   refineTravelOptions(request, context);
   if ((request.alternatives ?? 0) > 0 && request.locations.length !== 2) {
@@ -128,6 +139,20 @@ var routingRouteRequestSchema = z.object({
       message: "Alternatives are available only between two locations."
     });
   }
+  if (request.optimize) {
+    const limit = routingLimits.maximumMatrixDistanceMeters[request.mode];
+    const tooFar = request.locations.some(
+      (a, index) => request.locations.slice(index + 1).some((b) => routingDirectDistance(a, b) > limit)
+    );
+    if (tooFar) {
+      context.addIssue({
+        code: "custom",
+        path: ["locations"],
+        message: `Two locations are too far apart to optimize for ${request.mode}.`
+      });
+    }
+    return;
+  }
   let distance = 0;
   for (let index = 1; index < request.locations.length; index += 1) {
     distance += routingDirectDistance(request.locations[index - 1], request.locations[index]);
@@ -279,6 +304,8 @@ var routingLineStringSchema = z.object({
 var routingLegSchema = z.object({
   distance: meters,
   duration: seconds,
+  /** With `departAt`: when the leg ends, in local time at its end, with that UTC offset. */
+  arriveAt: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}[+-]\d{2}:\d{2}$/u).optional(),
   steps: z.array(routingStepSchema).min(1).max(routingLimits.maximumSteps)
 }).strict();
 var routingRouteSchema = z.object({
@@ -351,6 +378,10 @@ var answer = {
 var routingRouteResponseSchema = z.object({
   ...answer,
   routes: z.array(routingRouteSchema).min(1).max(routingLimits.maximumAlternatives + 1),
+  /** With `optimize`: the requested index of each location, in the order the route visits them. */
+  locationOrder: z.array(
+    z.number().int().min(0).max(routingLimits.maximumLocations - 1)
+  ).min(routingLimits.minimumLocations).max(routingLimits.maximumLocations).optional(),
   usage: routingUsageSchema
 }).strict();
 var routingIsochroneResponseSchema = z.object({ ...answer, isochrones: routingIsochroneCollectionSchema, usage: routingUsageSchema }).strict();

package/dist/client.d.ts

@@ -30,9 +30,10 @@ declare class RoutingError extends Error {
     });
 }
 /**
- * The fastest route through two to five positions, with up to two alternatives between two
+ * The fastest route through two to 25 positions, with up to two alternatives between two
  * positions. Each route has its line, distance, duration, turn-by-turn steps and whether it uses
- * tolls, highways or ferries.
+ * tolls, highways or ferries. With `optimize`, the stops between the first and the last position
+ * are visited in the fastest order found, which `locationOrder` states.
  */
 declare function route(request: RoutingRouteRequest, options: RoutingOptions): Promise<RoutingRouteResponse>;
 /** The areas reachable from a position in one to four times, one polygon per time. */

package/dist/client.js

@@ -5,8 +5,8 @@ import {
   matrix,
   nearest,
   route
-} from "./chunk-MCATD4FU.js";
-import "./chunk-ECBK2QPL.js";
+} from "./chunk-3P5UQQH3.js";
+import "./chunk-CDZKLI32.js";
 export {
   RoutingError,
   isochrone,

package/dist/contract.d.ts

@@ -22,7 +22,7 @@ declare const routingLimits: Readonly<{
     maximumRequestBytes: number;
     maximumResponseBytes: number;
     minimumLocations: 2;
-    maximumLocations: 5;
+    maximumLocations: 25;
     maximumAlternatives: 2;
     /** Sum of straight-line distances between consecutive locations, per mode. */
     maximumDirectDistanceMeters: Readonly<{
@@ -132,6 +132,8 @@ declare const routingRouteRequestSchema: z.ZodObject<{
         "uk-UA": "uk-UA";
         "vi-VN": "vi-VN";
     }>>;
+    optimize: z.ZodOptional<z.ZodBoolean>;
+    departAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 type RoutingRouteRequest = z.input<typeof routingRouteRequestSchema>;
 type NormalizedRoutingRouteRequest = z.output<typeof routingRouteRequestSchema>;
@@ -282,6 +284,7 @@ declare const routingLineStringSchema: z.ZodObject<{
 declare const routingLegSchema: z.ZodObject<{
     distance: z.ZodNumber;
     duration: z.ZodNumber;
+    arriveAt: z.ZodOptional<z.ZodString>;
     steps: z.ZodArray<z.ZodObject<{
         maneuver: z.ZodEnum<{
             arrive: "arrive";
@@ -338,6 +341,7 @@ declare const routingRouteSchema: z.ZodObject<{
     legs: z.ZodArray<z.ZodObject<{
         distance: z.ZodNumber;
         duration: z.ZodNumber;
+        arriveAt: z.ZodOptional<z.ZodString>;
         steps: z.ZodArray<z.ZodObject<{
             maneuver: z.ZodEnum<{
                 arrive: "arrive";
@@ -480,6 +484,7 @@ declare const routingRouteResponseSchema: z.ZodObject<{
         legs: z.ZodArray<z.ZodObject<{
             distance: z.ZodNumber;
             duration: z.ZodNumber;
+            arriveAt: z.ZodOptional<z.ZodString>;
             steps: z.ZodArray<z.ZodObject<{
                 maneuver: z.ZodEnum<{
                     arrive: "arrive";
@@ -524,6 +529,7 @@ declare const routingRouteResponseSchema: z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
+    locationOrder: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
     usage: z.ZodObject<{
         units: z.ZodNumber;
     }, z.core.$strict>;

package/dist/contract.js

@@ -33,7 +33,7 @@ import {
   routingTrafficKinds,
   routingUsageSchema,
   routingVehicleSchema
-} from "./chunk-ECBK2QPL.js";
+} from "./chunk-CDZKLI32.js";
 export {
   routingAttribution,
   routingAvoidances,

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   matrix,
   nearest,
   route
-} from "./chunk-MCATD4FU.js";
+} from "./chunk-3P5UQQH3.js";
 import {
   routingAttribution,
   routingAvoidances,
@@ -41,7 +41,7 @@ import {
   routingTrafficKinds,
   routingUsageSchema,
   routingVehicleSchema
-} from "./chunk-ECBK2QPL.js";
+} from "./chunk-CDZKLI32.js";
 export {
   RoutingError,
   isochrone,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/routing",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "license": "Apache-2.0",
   "description": "Routes, isochrones, matrices, map matching and nearest-road client and wire contracts for Tileflow.",
   "type": "module",