@furkot/directions 1.5.1

package/Readme.md

@@ -0,0 +1,34 @@
+[![NPM version][npm-image]][npm-url]
+[![Build Status][build-image]][build-url]
+[![Dependency Status][deps-image]][deps-url]
+
+# furkot-directions
+
+Directions service for Furkot
+
+## Install
+
+```sh
+$ npm install --save furkot-directions
+```
+
+## Usage
+
+```js
+var furkotDirections = require('furkot-directions');
+
+furkotDirections('Rainbow');
+```
+
+## License
+
+MIT © [Damian Krzeminski](https://pirxpilot.me)
+
+[npm-image]: https://img.shields.io/npm/v/@furkot/directions
+[npm-url]: https://npmjs.org/package/@furkot/directions
+
+[build-url]: https://github.com/furkot/directions/actions/workflows/check.yaml
+[build-image]: https://img.shields.io/github/workflow/status/furkot/directions/check
+
+[deps-image]: https://img.shields.io/librariesio/release/npm/@furkot/directions
+[deps-url]: https://libraries.io/npm/@furkot%2Fdirections

package/index.js

@@ -0,0 +1 @@
+module.exports = require('./lib/directions');

package/lib/directions.js

@@ -0,0 +1,137 @@
+const strategy = require('run-waterfall-until');
+const travelMode = require('./model').travelMode;
+const util = require('./service/util');
+
+module.exports = furkotDirections;
+
+function skip(options, query, result) {
+  // some other service already calculated directions
+  // or service is disabled
+  return result || !options.enable(query, result);
+}
+
+// query cascades through services until one produces a result
+// 'skip' function for a service is used to determine whether
+// it should be skipped or applied to a given request
+const services = {
+  graphhopper: {
+    service: require('./service/graphhopper'),
+    skip
+  },
+  mapquest: {
+    service: require('./service/mapquest'),
+    skip
+  },
+  openroute: {
+    service: require('./service/openroute'),
+    skip
+  },
+  valhalla: {
+    service: require('./service/valhalla'),
+    skip
+  },
+  osrm: {
+    service: require('./service/osrm'),
+    skip(options, query, result) {
+      // or asking for walking or biking directions (OSRM doesn't do it well)
+      return skip(options, query, result) || (query.mode !== travelMode.car && query.mode !== travelMode.motorcycle);
+    }
+  }
+};
+
+// default timeout to complete operation
+const defaultTimeout = 20 * 1000;
+
+let id = 0;
+
+function furkotDirections(options) {
+
+  /**
+   * Asynchronous directions service
+   * @param query directions query object
+   * @param fn function called with directions
+   */
+  function directions(query, fn) {
+    if (!query) {
+      return fn();
+    }
+
+    id += 1;
+
+    const result = new Array(query.length);
+    if (!query.length) {
+      return fn(query, result);
+    }
+
+    const queryId = id;
+    let timeoutId = setTimeout(function () {
+      timeoutId = undefined;
+      // cancel outstanding requests
+      options.services.forEach(function (service) {
+        service.abort(queryId);
+      });
+    }, options.timeout);
+
+    strategy(options.services, queryId, query, result, function (err, queryId, query, result) {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = undefined;
+      }
+      if (err) {
+        return fn();
+      }
+      // if no results, mark first as empty
+      if (result.length > 0 && !result.some(function (r) {
+          return r;
+        })) {
+        result[0] = {
+          query: query[0],
+          routes: [{
+            distance: 0,
+            duration: 0
+          }]
+        };
+      }
+      fn(query, result);
+    });
+  }
+
+  options = util.defaults(options, {
+    timeout: defaultTimeout,
+    order: ['osrm', 'mapquest', 'valhalla', 'graphhopper', 'openroute']
+  });
+  if (!options.services) {
+    options.services = options.order.reduce(function (result, name) {
+      const service = services[options[name] || name];
+      let defaults;
+      if (service && options[(name + '_enable')]) {
+        defaults = {
+          name,
+          limiter: options[(name + '_limiter')],
+          enable: options[(name + '_enable')],
+          skip: service.skip
+        };
+        if (options[name]) {
+          Object.keys(options).reduce(mapOptions, {
+            options,
+            name,
+            optName: options[name],
+            defaults
+          });
+        }
+        result.push(service.service(util.defaults(defaults, options)));
+      }
+      return result;
+    }, []);
+  }
+
+  directions.options = options;
+  return directions;
+}
+
+function mapOptions(result, opt) {
+  if (opt.startsWith(result.name)) {
+    result.defaults[opt.replace(result.name, result.optName)] = result.options[opt];
+  }
+  return result;
+}

package/lib/model.js

@@ -0,0 +1,64 @@
+// path simplification constants
+const pathType = {
+  none: 'none', // don't include the path in route (default)
+  coarse: 'coarse', // include heavily simplified path
+  smooth: 'smooth', // include path that is somewhat simplified
+  full: 'full' // don't simplify the route path at all
+};
+
+// travel mode constants
+const travelMode = {
+  motorcycle: -1,
+  car: 0,
+  bicycle: 1,
+  walk: 2,
+  other: 3,
+  ferry: 6
+};
+
+// template for directions query object
+const directionsQuery = [{ // array of legs each for consecutive series of points
+  mode: travelMode.car, // numeric value of travel mode
+  avoidHighways: false, // true to avoid highways
+  avoidTolls: false, // true to avoid toll roads
+  units: 'm', // m - miles, km - kilometers
+  points: [
+    [0, 0]
+  ], // array of consecutive series of points; each point is [lon, lat]
+  isInChina: false, // points are in China (some services need this information)
+  begin: '', // date/time for the begin of route as 'YYYY-MM-DDThh:mm'
+  turnbyturn: false, // provide detailed turn-by-turn instructions (segments in directionsResult)
+  seasonal: false, // include roads that are seasonally closed
+  path: pathType.none, // the degree of route path simplification
+  span: 0, // distance in meters for more detailed path simplification
+  alternate: false, // return alternatives to the default route
+  stats: [] // set on output - list of providers that requests have been sent to to obtain directions
+}];
+
+// template for directions results object
+const directionsResult = [{ // array of directions legs, one for each consecutive series of points
+  query: directionsQuery, // query parameters
+  places: [], // addresses or place names corresponding to points (if directions service performs reverse geocoding)
+  name: '', // human-readable name of directions (if available)
+  routes: [{ // routes; one for each point with a successor in the query.points
+    duration: 0, // route duration in seconds
+    distance: 0, // route distance in meters
+    path: [], // simplified series of interim points; each point is [lon, lat]
+    seasonal: false, // indicates a road that is seasonally closed
+    segmentIndex: 0 // index of the turn-by-turn directions segment
+  }],
+  segments: [{ // turn-by-turn directions
+    duration: 0, // segment duration in seconds
+    distance: 0, // segment distance in meters
+    path: [], // series of interim points; each point is [lon, lat]
+    instructions: '' // textual instructions for this segment
+  }],
+  provider: '' // identifies service providing the directions
+}];
+
+module.exports = {
+  directionsQuery,
+  directionsResult,
+  pathType,
+  travelMode
+};

package/lib/service/graphhopper/index.js

@@ -0,0 +1,164 @@
+const { pathType } = require("../../model");
+const status = require('../status');
+const util = require('../util');
+
+module.exports = init;
+
+const vehicle = {
+  '-1': 'car',
+  0: 'car',
+  1: 'bike',
+  2: 'foot',
+  5: 'truck'
+};
+
+const weighting = {
+  true: 'curvature',
+  1: 'curvature',
+  2: 'curvaturefastest'
+};
+
+function prepareWaypoint(qs, p) {
+  // waypoint format is lat,lon
+  qs.push('point=' + encodeURIComponent(p[1] + ',' + p[0]));
+  return qs;
+}
+
+function extractSegment(result, { distance, interval, text, time }) {
+  const { directions: { segments }, path } = result;
+  segments.push({
+    duration: Math.round((time || 0) / 1000),
+    distance: Math.round(distance || 0),
+    path: path && path.slice(interval[0], interval[1]),
+    instructions: text
+  });
+  return result;
+}
+
+function extractDirections(result, { distance, instructions, points, time }) {
+  const { directions: { routes, segments }, fullPath } = result;
+  result.path = util.decode(points);
+  const route = {
+    duration: Math.round((time || 0) / 1000),
+    distance: Math.round(distance || 0)
+  };
+  if (fullPath) {
+    route.path = result.path;
+  }
+  if (segments) {
+    route.segmentIndex = segments.length;
+  }
+  routes.push(route);
+  if (segments && instructions) {
+    instructions.reduce(extractSegment, result);
+    if (segments.length) {
+      util.last(segments).path.push(util.last(result.path));
+    }
+  }
+  return result;
+}
+
+function getStatus(st, response) {
+  st = st && st.status;
+  if (!(st || response)) {
+    return;
+  }
+  response = response || {};
+  response.status = response.status || st;
+  // 401 Unauthorized, 429 Too Many Requests
+  if (st === 401 || st === 429) {
+    // we exceeded the limit
+    return status.failure;
+  }
+  if (st === 400 && response.message) {
+    return status.empty;
+  }
+  if (!st) {
+    return status.success;
+  }
+}
+
+function init(options) {
+
+  function prepareUrl(url, { avoidHighways, avoidTolls, avoidUnpaved, curvy, mode, path, points, turnbyturn }) {
+    let req = {
+      vehicle: vehicle[mode] || vehicle[0],
+      key: options.graphhopper_key
+    };
+    if (curvy && mode === -1) {
+      req.vehicle = 'motorcycle.kurviger.de';
+      req.weighting = weighting[curvy];
+      if (options.parameters.app_type) {
+        req['app.type'] = options.parameters.app_type;
+      }
+      if (avoidUnpaved) {
+        req.avoid_unpaved_roads = true;
+      }
+    }
+    if (!turnbyturn && path !== pathType.smooth && path !== pathType.coarse) {
+      req.instructions = false;
+    }
+    if (options.parameters.flexible) {
+      if (avoidTolls) {
+        req['ch.disable'] = true;
+        req.avoid = ['toll'];
+      }
+      if (avoidHighways) {
+        req['ch.disable'] = true;
+        req.avoid = req.avoid || [];
+        req.avoid.push('motorway');
+      }
+    }
+
+    req = points.reduce(prepareWaypoint, Object.keys(req).map(function (name) {
+      return name + '=' + encodeURIComponent(req[name]);
+    }));
+
+    return url + '?' + req.join('&');
+  }
+
+  function prepareRequest({ mode, points, curvy }) {
+    return !(options.parameters.max_curvy_distance && curvy && mode === -1 && points.length === 2 &&
+      util.distance(points[0], points[1]) > options.parameters.max_curvy_distance);
+  }
+
+  function processResponse(response, query) {
+
+    if (response && response.status >= 400) {
+      // let it cascade to the next service
+      return;
+    }
+
+    const directions = {
+      query,
+      provider: options.name
+    };
+    const paths = response && response.paths;
+    if (paths) {
+      directions.routes = [];
+      if (query.turnbyturn || query.path === pathType.smooth || query.path === pathType.coarse) {
+        directions.segments = [];
+      }
+      const fullPath = query.path === pathType.full;
+      paths.reduce(extractDirections, {
+        directions,
+        fullPath
+      });
+      if (fullPath) {
+        // path is already prepared - no need to do it again from segments
+        directions.pathReady = true;
+      }
+    }
+    return directions;
+  }
+
+  options = util.defaults(options, {
+    maxPoints: options.graphhopper_max_points || 5, // max 5 points for free and 30-150 for paid plan
+    url: prepareUrl.bind(undefined, options.graphhopper_url),
+    status: getStatus,
+    prepareRequest,
+    processResponse
+  });
+  options.parameters = options.graphhopper_parameters || {};
+  return require('..')(options);
+}

package/lib/service/index.js

@@ -0,0 +1,228 @@
+const fetchagent = require('fetchagent');
+const pathType = require("../model").pathType;
+const series = require('run-series');
+const status = require('./status');
+const util = require('./util');
+const debug = require('debug')('furkot:directions:service');
+
+module.exports = init;
+
+const limiters = {};
+
+const ERROR = 'input error';
+
+function eachOfSeries(items, task, fn) {
+  const tasks = items.map(function (item, i) {
+    return task.bind(null, item, i);
+  });
+  return series(tasks, fn);
+}
+
+function request(url, req, fn) {
+  const options = this;
+  let fa = fetchagent;
+  if (options.post) {
+    fa = fa.post(url).send(req);
+  } else {
+    fa = fa.get(url).query(req);
+  }
+  if (options.authorization) {
+    fa.set('authorization', options.authorization);
+  }
+  return fa
+    .set('accept', 'application/json')
+    .end(fn);
+}
+
+function initUrl(url) {
+  if (typeof url === 'function') {
+    return url;
+  }
+  return function () {
+    return url;
+  };
+}
+
+function init(options) {
+  let limiter;
+  let holdRequests;
+  let simplify;
+  const outstanding = {};
+
+  function abort(queryId) {
+    debug('abort', queryId);
+    if (!outstanding[queryId]) {
+      return;
+    }
+    // cancel later request if scheduled
+    if (outstanding[queryId].laterTimeoutId) {
+      clearTimeout(outstanding[queryId].laterTimeoutId);
+    }
+    // cancel request in progress
+    if (outstanding[queryId].reqInProgress) {
+      outstanding[queryId].reqInProgress.abort();
+    }
+    outstanding[queryId].callback(ERROR);
+  }
+
+  function directions(queryId, queryArray, result, fn) {
+
+    function spliceResults(idx, segments, segResult) {
+      Array.prototype.splice.apply(queryArray, [idx + queryArray.delta, 1].concat(segments));
+      Array.prototype.splice.apply(result, [idx + queryArray.delta, 1].concat(segResult));
+      queryArray.delta += segments.length - 1;
+    }
+
+    function queryDirections(query, idx, callback) {
+      let req;
+      let segments;
+
+      function requestLater() {
+        outstanding[queryId].laterTimeoutId = setTimeout(function () {
+          if (outstanding[queryId]) {
+            delete outstanding[queryId].laterTimeoutId;
+          }
+          queryDirections(query, idx, callback);
+        }, options.penaltyTimeout);
+      }
+
+      if (!outstanding[queryId]) {
+        // query has been aborted
+        return;
+      }
+      outstanding[queryId].callback = callback;
+
+      if (options.skip(options, query, result[idx + queryArray.delta])) {
+        return callback();
+      }
+
+      if (holdRequests) {
+        return callback();
+      }
+
+      segments = util.splitPoints(query, queryArray.maxPoints || options.maxPoints);
+      if (!segments) {
+        return callback(ERROR);
+      }
+
+      if (segments !== query) {
+        segments[0].stats = query.stats;
+        delete query.stats;
+        return directions(queryId, segments,
+          new Array(segments.length),
+          function (err, stop, id, query, result) {
+            if (query && result) {
+              spliceResults(idx, query, result);
+            }
+            callback(err);
+          });
+      }
+
+      query.path = query.path || pathType.none;
+      req = options.prepareRequest(query);
+      if (!req) {
+        return callback();
+      }
+      if (req === true) {
+        req = undefined;
+      }
+
+      limiter.trigger(function () {
+        if (!outstanding[queryId]) {
+          // query has been aborted
+          limiter.skip(); // immediately process the next request in the queue
+          return;
+        }
+        query.stats = query.stats || [];
+        query.stats.push(options.name);
+        outstanding[queryId].reqInProgress = options.request(options.url(query), req, function (err, response) {
+          let st;
+          let res;
+          if (!outstanding[queryId]) {
+            // query has been aborted
+            return;
+          }
+          delete outstanding[queryId].reqInProgress;
+          st = options.status(err, response);
+          if (st === undefined) {
+            // shouldn't happen (bug or unexpected response format)
+            // treat it as no route
+            st = status.empty;
+          }
+          if (st === status.failure) {
+            // don't ever ask again
+            holdRequests = true;
+            return callback();
+          }
+          if (st === status.error) {
+            // try again later
+            limiter.penalty();
+            return requestLater();
+          }
+          if (st === status.empty && query.points.length > 2) {
+            query = [query];
+            query.maxPoints = 2;
+
+            return directions(queryId, query,
+              new Array(1),
+              function (err, stop, id, query, result) {
+                if (query && result) {
+                  spliceResults(idx, query, result);
+                }
+                callback(err);
+              });
+          }
+
+          res = options.processResponse(response, query);
+          if (res) {
+            if (!res.pathReady && res.routes && res.segments) {
+              simplify(query.path, query.span, res.routes, res.segments);
+            }
+            if (!query.turnbyturn) {
+              delete res.segments;
+            }
+            result[idx + queryArray.delta] = res;
+          }
+          callback();
+        });
+      });
+    }
+
+    outstanding[queryId] = outstanding[queryId] || {
+      stack: 0,
+      hits: 0
+    };
+    outstanding[queryId].stack += 1;
+    outstanding[queryId].callback = function (err) {
+      fn(err, true, queryId, queryArray, result);
+    };
+    queryArray.delta = 0;
+
+    eachOfSeries(queryArray, queryDirections, function (err) {
+      if (outstanding[queryId]) {
+        outstanding[queryId].stack -= 1;
+        if (!outstanding[queryId].stack) {
+          delete outstanding[queryId];
+        }
+        if (err === ERROR) {
+          return fn(outstanding[queryId] ? err : undefined, true, queryId, queryArray, result);
+        }
+        fn(err, false, queryId, queryArray, result);
+      }
+    });
+  }
+
+  options = util.defaults(options, {
+    interval: 340,
+    penaltyInterval: 2000,
+    limiter: limiters[options.name],
+    request,
+    abort
+  });
+  options.url = initUrl(options.url);
+  limiters[options.name] = options.limiter || require('limiter-component')(options.interval, options.penaltyInterval);
+  limiter = limiters[options.name];
+  simplify = require('./simplify')(options);
+  directions.abort = options.abort;
+  return directions;
+}