add routingMode query parameter to /journeys route 📝✅

closes #46

Co-Authored-By: Jannis R <[email protected]>

api.js

@@ -20,6 +20,8 @@ import {parseBoolean, parseInteger} from 'hafas-rest-api/lib/parse.js'
 import {loyaltyCardParser} from './lib/loyalty-cards.js'
 import {route as stations} from './routes/stations.js'
 import {route as station} from './routes/station.js'
+import {parseRoutingMode} from './lib/parse.js'
+import {routingModes} from 'hafas-client/p/db/routing-modes.js'
 
 const pkg = require('./package.json')
 
@@ -103,6 +105,13 @@ const mapRouteParsers = (route, parsers) => {
 			defaultStr: '*adult*',
 			parse: parseInteger
 		},
+		routingMode: {
+			description: 'HAFAS routing mode, see the "Routing Mode" section',
+			type: 'string',
+			enum: Object.keys(routingModes),
+			defaultStr: '`REALTIME`',
+			parse: parseRoutingMode
+		},
 	}
 }
 

build/api-docs.js

@@ -68,7 +68,17 @@ Uses [\`hafasClient.journeys()\`](https://github.com/public-transport/hafas-clie
 
 Given a response, you can also fetch more journeys matching the same criteria. Instead of \`from*\`, \`to*\` & \`departure\`/\`arrival\`, pass \`earlierRef\` from the first response as \`earlierThan\` to get journeys "before", or \`laterRef\` as \`laterThan\` to get journeys "after".
 
+*Pagination isn't fully functioning with the default [\`routingMode\`](#routing-mode).*
+
 Check the [\`hafasClient.journeys()\` docs](https://github.com/public-transport/hafas-client/blob/6/docs/journeys.md) for more details.
+
+### Routing mode
+
+The \`routingMode\` parameter influences which data the system uses to compute the query results. The default is \`REALTIME\` and does *not* include canceled journeys. If you want canceled journeys to be included in the response, use \`HYBRID\` instead.
+
+Furthermore, \`REALTIME\` doesn't support [Pagination](#pagination) fully. If you need fully functioning pagination, use \`HYBRID\` instead.
+
+The \`hafas-client\` repository has [more details on the different routing modes](https://github.com/public-transport/hafas-client/blob/45610fc951bb834e1b6f09e363ee820c0b92b673/p/db/readme.md#using-the-routingmode-option).
 `,
 	'/journeys/:ref': `\
 Uses [\`hafasClient.refreshJourney()\`](https://github.com/public-transport/hafas-client/blob/6/docs/refresh-journey.md) to **"refresh" a journey, using its \`refreshToken\`**.

lib/parse.js

@@ -0,0 +1,12 @@
+import {routingModes} from 'hafas-client/p/db/routing-modes.js'
+
+const parseRoutingMode = (key, val) => {
+	if ('string' !== typeof val) throw new Error(key + ' must be a string')
+	val = val.toUpperCase()
+	if(Object.prototype.hasOwnProperty.call(routingModes, val)) return routingModes[val]
+	throw new Error(key + ' must be one of ' + Object.keys(routingModes).join(', '))
+}
+
+export {
+	parseRoutingMode
+}

test/index.js

@@ -41,6 +41,15 @@ tape.test('/journeys?loyaltyCard works', async (t) => {
 	}, {}, '/journeys?from=123&to=234&loyaltyCard=bahncard-2nd-50')
 })
 
+tape.test('/journeys?routingMode works', async (t) => {
+	await fetchWithTestApi({
+		journeys: async (from, to, opt = {}) => {
+			t.equal(opt.routingMode, 'HYBRID', 'value is not case-sensitive')
+			return NO_JOURNEYS
+		}
+	}, {}, '/journeys?from=123&to=234&routingMode=HYbriD')
+})
+
 tape.test('/stations works', async (t) => {
 	const {data: allStations} = await pAllStations
 	const someStationId = Object.keys(allStations)[0]