trip/tripsByName: realtimeDataFrom -> separate realtimeDataUpdatedAt field 💥✅📝

docs/trip.md

@@ -44,12 +44,17 @@ const vbbProfile = require('hafas-client/p/vbb')
 
 const client = createClient(vbbProfile)
 
-console.log(await client.trip('1|31431|28|86|17122017', 'S9', {
+const {
+	trip,
+	realtimeDataUpdatedAt,
+} = await client.trip('1|31431|28|86|17122017', 'S9', {
 	when: 1513534689273,
-}))
+})
 ```
 
-The result looked like this:
+`realtimeDataUpdatedAt` is a UNIX timestamp reflecting the latest moment when (at least some of) the response's realtime data have been updated.
+
+When running the code above, `trip` looked like this:
 
 ```js
 {

docs/trips-by-name.md

@@ -12,7 +12,10 @@ const vbbProfile = require('hafas-client/p/vbb')
 
 const client = createClient(vbbProfile, 'my-awesome-program')
 
-await client.tripsByName('S1')
+const {
+	trips,
+	realtimeDataUpdatedAt,
+} = await client.tripsByName('S1')
 ```
 
 With `opt`, you can override the default options, which look like this:
@@ -42,7 +45,9 @@ With `opt`, you can override the default options, which look like this:
 }
 ```
 
-The result may look like this:
+`realtimeDataUpdatedAt` is a UNIX timestamp reflecting the latest moment when (at least some of) the response's realtime data have been updated.
+
+`trips` may look like this:
 
 ```js
 [

index.js

@@ -495,8 +495,14 @@ const createClient = (profile, userAgent, opt = {}) => {
 		const {res, common} = await profile.request({profile, opt}, userAgent, req)
 		const ctx = {profile, opt, common, res}
 
-		// todo [breaking]: return object with realtimeDataUpdatedAt
-		return profile.parseTrip(ctx, res.journey)
+		const trip = profile.parseTrip(ctx, res.journey)
+
+		return {
+			trip,
+			realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0'
+				? parseInt(res.planrtTS)
+				: null,
+		}
 	}
 
 	// todo [breaking]: rename to trips()?
@@ -576,8 +582,14 @@ const createClient = (profile, userAgent, opt = {}) => {
 		// todo [breaking]: catch `NO_MATCH` errors, return []
 		const ctx = {profile, opt, common, res}
 
-		// todo [breaking]: return object with realtimeDataUpdatedAt
-		return res.jnyL.map(t => profile.parseTrip(ctx, t))
+		const trips = res.jnyL.map(t => profile.parseTrip(ctx, t))
+
+		return {
+			trips,
+			realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0'
+				? parseInt(res.planrtTS)
+				: null,
+		}
 	}
 
 	const radar = async ({north, west, south, east}, opt) => {

parse/trip.js

@@ -5,7 +5,7 @@ const maxBy = require('lodash/maxBy')
 const last = require('lodash/last')
 
 const parseTrip = (ctx, t) => { // t = raw trip
-	const {profile, opt, res} = ctx
+	const {profile, opt} = ctx
 
 	// pretend the trip is a leg in a journey
 	const fakeLeg = {
@@ -43,11 +43,6 @@ const parseTrip = (ctx, t) => { // t = raw trip
 		trip.scheduledDays = profile.parseScheduledDays(ctx, sDays)
 	}
 
-	if (res.planrtTS) {
-		// todo [breaking]: remove here
-		trip.realtimeDataUpdatedAt = parseInt(res.planrtTS)
-	}
-
 	return trip
 }
 

test/e2e/bvg.js

@@ -225,9 +225,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/cfl.js

@@ -176,9 +176,10 @@ tap.test('trip', async (t) => {
 	const p = journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/cmta.js

@@ -155,9 +155,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/db-busradar-nrw.js

@@ -55,9 +55,10 @@ tap.test('trip details', async (t) => {
 	const p = res.departures[0] || {}
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/db.js

@@ -11,7 +11,7 @@ const createClient = require('../..')
 const dbProfile = require('../../p/db')
 const products = require('../../p/db/products')
 const {
-	station: createValidateStation,
+    station: createValidateStation,
 	trip: createValidateTrip
 } = require('./lib/validators')
 const createValidate = require('./lib/validate-fptf-with')
@@ -314,7 +314,8 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
+
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
 
 	const validateTrip = createValidateTrip(cfg)
 	const validate = createValidate(cfg, {
@@ -324,7 +325,7 @@ tap.test('trip details', async (t) => {
 			validateTrip(validate, trip, name)
 		}
 	})
-	validate(t, trip, 'trip', 'trip')
+	validate(t, tripRes, 'tripResult', 'tripRes')
 
 	t.end()
 })

test/e2e/hvv.js

@@ -144,9 +144,10 @@ tap.skip('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/insa.js

@@ -182,9 +182,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/invg.js

@@ -167,9 +167,10 @@ tap.test('trip details', async (t) => {
 	const p = journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/lib/departures-in-direction.js

@@ -24,7 +24,7 @@ const testDeparturesInDirection = async (cfg) => {
 		const name = `deps[${i}]`
 
 		const line = dep.line && dep.line.name
-		const trip = await fetchTrip(dep.tripId, line, {
+		const {trip} = await fetchTrip(dep.tripId, line, {
 			when, stopovers: true
 		})
 		t.ok(trip.stopovers.some(st => (

test/e2e/lib/validators.js

@@ -448,6 +448,26 @@ const validateTrip = (val, trip, name = 'trip') => {
 	val.journeyLeg(val, withFakeTripId, name)
 }
 
+const validateTripResult = (val, res, name = 'tripResult') => {
+	a.ok(isObj(res), name + ' must be an object')
+
+	val.trip(val, res.trip, name + '.trip')
+
+	val.realtimeDataUpdatedAt(val, res.realtimeDataUpdatedAt, name + '.realtimeDataUpdatedAt')
+}
+
+const validateTripsByNameResult = (val, res, name = 'tripsByNameResult') => {
+	a.ok(isObj(res), name + ' must be an object')
+
+	a.ok(Array.isArray(res.trips), name + '.trips must be an array')
+	a.ok(res.trips.length > 0, name + '.trips must not be empty')
+	for (let i = 0; i < res.trips.length; i++) {
+		val.trip(val, res.trips[i], `${name}.trips[${i}]`)
+	}
+
+	val.realtimeDataUpdatedAt(val, res.realtimeDataUpdatedAt, name + '.realtimeDataUpdatedAt')
+}
+
 const createValidateArrivalOrDeparture = (type, cfg) => {
 	if (type !== 'arrival' && type !== 'departure') throw new Error('invalid type')
 
@@ -631,6 +651,8 @@ module.exports = {
 	journeysResult: () => validateJourneysResult,
 	refreshJourneyResult: () => validateRefreshJourneyResult,
 	trip: () => validateTrip,
+	tripResult: () => validateTripResult,
+	tripsByNameResult: () => validateTripsByNameResult,
 	arrival: createValidateArrival,
 	departure: createValidateDeparture,
 	arrivals: createValidateArrivals,

test/e2e/mobil-nrw.js

@@ -142,9 +142,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/mobiliteit-lu.js

@@ -180,9 +180,10 @@ tap.test('trip', async (t) => {
 	const p = journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/nahsh.js

@@ -217,9 +217,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/nvv.js

@@ -164,9 +164,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/oebb.js

@@ -237,9 +237,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/pkp.js

@@ -99,9 +99,10 @@ tap.skip('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, { when })
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/rejseplanen.js

@@ -111,9 +111,10 @@ tap.test('trip', async (t) => {
 	const p = journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/rmv.js

@@ -59,9 +59,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/saarfahrplan.js

@@ -165,9 +165,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, { when })
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, { when })
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/sbahn-muenchen.js

@@ -170,9 +170,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/sncb.js

@@ -64,9 +64,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/svv.js

@@ -66,9 +66,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/vbb.js

@@ -177,9 +177,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 
@@ -187,7 +188,7 @@ tap.test('trip details', async (t) => {
 // 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')
+	const {trips: 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'))
@@ -195,7 +196,7 @@ tap.skip('trips', async (t) => {
 		validate(t, r1[i], 'trip', `r1[${i}]`)
 	}
 
-	const r2 = await client.tripsByName('S1', {
+	const {trips: r2} = await client.tripsByName('S1', {
 		onlyCurrentlyRunning: false,
 	})
 	t.ok(Array.isArray(r2))
@@ -205,7 +206,7 @@ tap.skip('trips', async (t) => {
 		validate(t, r2[i], 'trip', `r2[${i}]`)
 	}
 
-	const r3 = await client.tripsByName('*', {
+	const {trips: r3} = await client.tripsByName('*', {
 		onlyCurrentlyRunning: false,
 	})
 	t.ok(Array.isArray(r3))

test/e2e/vbn.js

@@ -59,9 +59,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/vrn.js

@@ -138,9 +138,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/vsn.js

@@ -94,9 +94,10 @@ tap.test('trip', async (t) => {
 	const p = journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/e2e/zvv.js

@@ -71,9 +71,10 @@ tap.test('trip details', async (t) => {
 	const p = res.journeys[0].legs.find(l => !l.walking)
 	t.ok(p.tripId, 'precondition failed')
 	t.ok(p.line.name, 'precondition failed')
-	const trip = await client.trip(p.tripId, p.line.name, {when})
 
-	validate(t, trip, 'trip', 'trip')
+	const tripRes = await client.trip(p.tripId, p.line.name, {when})
+
+	validate(t, tripRes, 'tripResult', 'res')
 	t.end()
 })
 

test/fixtures/bvg-trip-with-occupancy.js

@@ -99,8 +99,6 @@ module.exports = {
 		'2021-12-16': false,
 	},
 
-	realtimeDataUpdatedAt: 1635406146,
-
 	origin: {
 		type: 'stop',
 		id: '900009102',

test/fixtures/oebb-trip.js

@@ -100,7 +100,6 @@ module.exports = {
 	id: '2|#VN#0#ST#1591790769#PI#0#ZI#398470#TA#0#DA#110620#1S#8100353#1T#1633#LS#8100002#LT#1948#PU#81#RT#1#CA#RJ#ZE#742#ZB#RJ 742  #',
 	origin: wienFlughafen,
 	destination: salzburgHbf,
-	realtimeDataUpdatedAt: 1591881826,
 	arrival: '2020-06-11T19:48:00+02:00',
 	plannedArrival: '2020-06-11T19:48:00+02:00',
 	arrivalDelay: null,

test/fixtures/rejseplanen-trip.js

@@ -21,7 +21,6 @@ module.exports = {
 		product: 'national-train',
 		operator: { type: 'operator', id: 'dsb', name: 'DSB' },
 	},
-	realtimeDataUpdatedAt: 1634050700,
 
 	origin: {
 		type: 'stop',

test/fixtures/vbb-on-demand-trip.js

@@ -20,7 +20,6 @@ module.exports = {
 		},
 	},
 	reachable: true,
-	realtimeDataUpdatedAt: 1635084435,
 
 	origin: {},
 	departure: null,