You also need NodeJS installed locally : we **strongly** advise to install [Node Version Manager](https://github.com/nvm-sh/nvm) and use the latest LTS version of Node (check that your local version matches with the one used in the Dockerfile).
The API will run inside a docker container, **but** the install itself is made outside the container, because during development we need tools that need to be available locally (eg. ESLint or Prettier with fix-on-save).
_If the schedule is not set, the driver departure time is guessed to be the ideal departure time to reach the passenger, and the passenger departure time is guessed to be the ideal pick up time for the driver_
-**seatsProposed** (integer, optional): number of seats proposed as driver (_default : 3_)
-**seatsRequested** (integer, optional): number of seats requested as passenger (_default : 1_)
-**waypoints**: an array of addresses that represent the waypoints of the journey (only first and last waypoints are used for passenger ads). Note that positions are **required** and **must** be consecutives
-**algorithmType** (optional): the type of algorithm to use (as of 2023-09-28, only the default `PASSENGER_ORIENTED` is accepted)
-**remoteness** (integer, optional): an integer to indicate the maximum flying distance (in metres) between the driver route and the passenger pick-up / drop-off points (_default : 15000_)
-**useProportion** (boolean, optional): a boolean to indicate if the matching algorithm will compare the distance of the passenger route against the distance of the driver route (_default : 1_). Works in combination with **proportion** parameter
-**proportion** (float, optional): a fraction (float between 0 and 1) to indicate minimum proportion of the distance of the passenger route against the distance of the driver route (_default : 0.3_). Works in combination with **use_proportion** parameter
-**useAzimuth** (boolean, optional): a boolean to indicate if the matching algorithm will use the azimuth of the driver and passenger routes (_default : 1_)
-**azimuthMargin** (integer, optional): an integer (representing the number of degrees) to indicate the range around the opposite azimuth to consider the candidate route excluded (_default : 10_)
-**maxDetourDistanceRatio** (float, optional): a fraction (float between 0 and 1) of the driver route distance to indicate the maximum detour distance acceptable for a passenger (_default : 0.3_)
-**maxDetourDurationRatio** (float, optional): a fraction (float between 0 and 1) of the driver route duration to indicate the maximum detour duration acceptable for a passenger (_default : 0.3_)
-**page** (integer, optional): the page of results to display (_default : 1_)
-**perPage** (integer, optional): the number of results to display per page (_default : 10_)
If the matching is successful, you will get a result, containing :
-**id**: the id of the matching; as matching is a time-consuming process, results are cached and thus accessible later using this id (pagination works as well !)
-**total**: the total number of results
-**page**: the number of the page that is returned (may be different than the number of the required page, if number of results does not match with perPage parameter)
-**perPage**: the number of results per page (as it may not be specified in the request)
-**data**: an array of the results themselves, each including:
-**adId**: the id of the ad that matches
-**role**: the role of the ad owner in that match
-**distance**: the distance in metres of the resulting carpool
-**duration**: the duration in seconds of the resulting carpool
-**initialDistance**: the initial distance in metres for the driver
-**initialDuration**: the initial duration in seconds for the driver
-**distanceDetour**: the detour distance in metres
-**durationDetour**: the detour duration in seconds
-**distanceDetourPercentage**: the detour distance in percentage of the original distance
-**durationDetourPercentage**: the detour duration in percentage of the original duration
-**journeys**: the possible journeys for the carpool (one journey for punctual carpools, one or more journeys for recurrent carpools), each including:
-**day**: the week day for the journey, as a number, from 0 (sunday) to 6 (saturday)
-**firstDate**: the first possible date for the journey
-**lastDate**: the last possible date for the journey
-**steps**: the steps of the journey (coordinates with distance, duration and actors implied), each including:
-**distance**: the distance to reach the step in metres
-**duration**: the duration to reach the step in seconds
-**lon**: the longitude of the point for the step
-**lat**: the longitude of the point for the step
-**time**: the driver time at that step
-**actors**: the actors for that step:
-**role**: the role of the actor (`DRIVER` or `PASSENGER`)
-**target**: the meaning of the step for the actor:
-_START_ for the first point of the actor
-_FINISH_ for the last point of the actor
-_INTERMEDIATE_ for a driver intermediate point
-_NEUTRAL_ for a passenger point from the point of view of a driver
Matching is a time-consuming process, so the results of a matching request are stored in cache before being paginated and returned to the requester.
An id is attributed to the overall results of a request : on further requests (for example to query for different pages of results), the requester can provide this id and get in return the cached data, avoiding another longer process of computing the results from scratch. Obviously, new computing must be done periodically to get fresh new results !
Tests are run outside the container for ease of use (switching between different environments inside containers using prisma is complicated and error prone).
The integration tests use a dedicated database (see _db-test_ section of _docker-compose.yml_).
```bash
# run all tests (unit + integration)
npm run test
# unit tests only
npm run test:unit
# integration tests only
npm run test:integration
# coverage
npm run test:cov
# ESLint
npm run lint
# Prettier
npm run pretty
```
## License
Mobicoop V3 - Matcher Service is [AGPL licensed](LICENSE).
