add tripsByName() method, docs 📝

docs

docs/readme.md

@@ -3,6 +3,7 @@
 - [`journeys(from, to, [opt])`](journeys.md) – get journeys between locations
 - [`refreshJourney(refreshToken, [opt])`](refresh-journey.md) – fetch up-to-date/more details of a `journey`
 - [`trip(id, lineName, [opt])`](trip.md) – get details for a trip
+- [`tripsByName(lineNameOrFahrtNr, [opt])`](trips-by-name.md) – get all trips matching a name
 - [`departures(station, [opt])`](departures.md) – query the next departures at a station
 - [`arrivals(station, [opt])`](arrivals.md) – query the next arrivals at a station
 - [`locations(query, [opt])`](locations.md) – find stations, POIs and addresses

docs/trips-by-name.md

@@ -0,0 +1,81 @@
+# `tripsByName(lineNameOrFahrtNr, [opt])`
+
+Get all trips matching a name.
+
+## Response
+
+As an example, we're going to use the [VBB profile](../p/vbb):
+
+```js
+const createClient = require('hafas-client')
+const vbbProfile = require('hafas-client/p/vbb')
+
+const client = createClient(vbbProfile, 'my-awesome-program')
+
+console.log(await client.tripsByName('S1'))
+```
+
+The response may look like this:
+
+```js
+[
+	{
+		id: '1|1214|0|86|16092020'
+		direction: null,
+		line: {
+			type: 'line',
+			id: 's1',
+			fahrtNr: '325',
+			name: 'S1',
+			mode: 'train',
+			product: 'suburban',
+			// …
+		},
+
+		origin: {
+			type: 'stop',
+			id: '900000550239',
+			name: 'Warnemünde, Bhf',
+			location: { /* … */ },
+			products: { /* … */ },
+		},
+		departure: '2020-09-16T04:03:00+02:00',
+		plannedDeparture: '2020-09-16T04:03:00+02:00',
+		departureDelay: null,
+		departurePlatform: null,
+		plannedDeparturePlatform: null,
+
+		destination: {
+			type: 'stop',
+			id: '900000550002',
+			name: 'Rostock, Hbf',
+			location: { /* … */ },
+			products: { /* … */ },
+		},
+		arrival: '2020-09-16T04:24:00+02:00',
+		plannedArrival: '2020-09-16T04:24:00+02:00',
+		arrivalDelay: null,
+		arrivalPlatform: null,
+		plannedArrivalPlatform: null,
+	},
+	// …
+	{
+		id: '1|62554|0|86|16092020'
+		direction: null,
+		line: {
+			type: 'line',
+			id: 's1',
+			fahrtNr: '2001',
+			name: 'S1',
+			public: true,
+			mode: 'train',
+			product: 'suburban',
+			// …
+		},
+
+		origin: { /* … */ },
+		destination: { /* … */ },
+		// …
+	}
+]
+```

index.js

@@ -361,6 +361,29 @@ const createClient = (profile, userAgent, opt = {}) => {
 		})
 	}
 
+	const tripsByName = (lineNameOrFahrtNr, opt = {}) => {
+		if (!isNonEmptyString(lineNameOrFahrtNr)) {
+			throw new TypeError('lineNameOrFahrtNr must be a non-empty string.')
+		}
+		opt = Object.assign({
+		}, opt)
+		opt.when = new Date(opt.when || Date.now())
+
+		return profile.request({profile, opt}, userAgent, {
+			cfg: {polyEnc: 'GPA'},
+			meth: 'JourneyMatch',
+			req: {
+				input: lineNameOrFahrtNr,
+				date: profile.formatDate(profile, opt.when),
+				// todo: there are probably more options
+			}
+		})
+		.then(({res, common}) => {
+			const ctx = {profile, opt, common, res}
+			return res.jnyL.map(t => profile.parseTrip(ctx, t))
+		})
+	}
+
 	const radar = ({north, west, south, east}, opt) => {
 		if ('number' !== typeof north) throw new TypeError('north must be a number.')
 		if ('number' !== typeof west) throw new TypeError('west must be a number.')
@@ -449,6 +472,7 @@ const createClient = (profile, userAgent, opt = {}) => {
 	if (profile.radar) client.radar = radar
 	if (profile.refreshJourney) client.refreshJourney = refreshJourney
 	if (profile.reachableFrom) client.reachableFrom = reachableFrom
+	if (profile.tripsByName) client.tripsByName = tripsByName
 	Object.defineProperty(client, 'profile', {value: profile})
 	return client
 }

lib/default-profile.js

@@ -103,7 +103,8 @@ const defaultProfile = {
 	departuresStbFltrEquiv: true, // `departures()` method: support for `stbFltrEquiv` field?
 	trip: false,
 	radar: false,
-	refreshJourney: true
+	refreshJourney: true,
+	tripsByName: true
 }
 
 module.exports = defaultProfile