tripsByName: more options, add to debug CLI, skipped E2E test ✅📝

docs/trips-by-name.md

@@ -1,6 +1,6 @@
-# `tripsByName(lineNameOrFahrtNr, [opt])`
+# `tripsByName([lineNameOrFahrtNr], [opt])`
 
-Get all trips matching a name.
+Get all trips matching one or more criteria, e.g. a specific name.
 
 ## Response
 
@@ -15,6 +15,19 @@ const client = createClient(vbbProfile, 'my-awesome-program')
 console.log(await client.tripsByName('S1'))
 ```
 
+With `opt`, you can override the default options, which look like this:
+
+```js
+{
+	// use either this
+	when: null,
+	// or these
+	fromWhen: null, untilWhen: null,
+
+	onlyCurrentlyRunning: true,
+}
+```
+
 The response may look like this:
 
 ```js

index.js

@@ -495,23 +495,45 @@ const createClient = (profile, userAgent, opt = {}) => {
 		})
 	}
 
-	const tripsByName = (lineNameOrFahrtNr, opt = {}) => {
+	// todo [breaking]: rename to trips()?
+	const tripsByName = (lineNameOrFahrtNr = '*', opt = {}) => {
 		if (!isNonEmptyString(lineNameOrFahrtNr)) {
 			throw new TypeError('lineNameOrFahrtNr must be a non-empty string.')
 		}
 		opt = Object.assign({
+			when: null,
+			fromWhen: null, untilWhen: null,
+			onlyCurrentlyRunning: true,
 		}, opt)
-		opt.when = new Date(opt.when || Date.now())
+
+		const req = {
+			// fields: https://github.com/marudor/BahnhofsAbfahrten/blob/f619e754f212980261eb7e2b151cd73ba0213da8/packages/types/HAFAS/JourneyMatch.ts#L4-L23
+			input: lineNameOrFahrtNr,
+			onlyCR: opt.onlyCurrentlyRunning,
+			// todo: passing `tripId` yields a `CGI_READ_FAILED` error
+			// todo: passing a stop ID as `extId` yields a `PARAMETER` error
+			// todo: `onlyRT: true` reduces the number of results, but filters recent trips 🤔
+			// todo: `onlyTN: true` yields a `NO_MATCH` error
+			// todo: jnyFltrL, useAeqi
+		}
+		if (opt.when !== null) {
+			req.date = profile.formatDate(profile, new Date(opt.when))
+			req.time = profile.formatTime(profile, new Date(opt.when))
+		}
+		// todo: fromWhen doesn't work yet, but untilWhen does
+		if (opt.fromWhen !== null) {
+			req.dateB = profile.formatDate(profile, new Date(opt.fromWhen))
+			req.timeB = profile.formatTime(profile, new Date(opt.fromWhen))
+		}
+		if (opt.untilWhen !== null) {
+			req.dateE = profile.formatDate(profile, new Date(opt.untilWhen))
+			req.timeE = profile.formatTime(profile, new Date(opt.untilWhen))
+		}
 
 		return profile.request({profile, opt}, userAgent, {
 			cfg: {polyEnc: 'GPA'},
 			meth: 'JourneyMatch',
-			req: {
-				input: lineNameOrFahrtNr,
-				// todo: date seems to be ignored
-				date: profile.formatDate(profile, opt.when),
-				// todo: there are probably more options
-			}
+			req,
 		})
 		.then(({res, common}) => {
 			const ctx = {profile, opt, common, res}

test/e2e/vbb.js

@@ -179,6 +179,40 @@ tap.test('trip details', async (t) => {
 	t.end()
 })
 
+// This currently fails because some trips' departure/arrival is out of the range
+// around `when`, as expected by `assertValidWhen`, as called by `validate`.
+// todo: allow turning this off?
+tap.skip('trips', async (t) => {
+	const r1 = await client.tripsByName('S1')
+	t.ok(Array.isArray(r1))
+	t.ok(r1.length > 0)
+	t.ok(r1.every(t => t.line.name.trim() === 'S1'))
+	for (let i = 0; i < r1.length; i++) {
+		validate(t, r1[i], 'trip', `r1[${i}]`)
+	}
+
+	const r2 = await client.tripsByName('S1', {
+		onlyCurrentlyRunning: false,
+	})
+	t.ok(Array.isArray(r2))
+	t.ok(r2.length > r1.length)
+	t.ok(r2.every(t => t.line.name.trim() === 'S1'))
+	for (let i = 0; i < r2.length; i++) {
+		validate(t, r2[i], 'trip', `r2[${i}]`)
+	}
+
+	const r3 = await client.tripsByName('*', {
+		onlyCurrentlyRunning: false,
+	})
+	t.ok(Array.isArray(r3))
+	t.ok(r3.length > r2.length)
+	for (let i = 0; i < r3.length; i++) {
+		validate(t, r3[i], 'trip', `r3[${i}]`)
+	}
+
+	t.end()
+})
+
 tap.test('journeys – station to address', async (t) => {
 	const torfstr = {
 		type: 'location',

tools/debug-cli/cli.js

@@ -39,6 +39,8 @@ const parseArgs = [
 	['trip', 0, toString],
 	['trip', 1, toString],
 	['trip', 2, parseJsObject],
+	['tripsByName', 0, toString],
+	['tripsByName', 1, parseJsObject],
 	['radar', 0, parseJsObject],
 	['radar', 1, parseJsObject],
 	['reachableFrom', 0, parseJsObject],