diff --git a/docs/journeys-from-trip.md b/docs/journeys-from-trip.md index 8d12f304..ce9bf623 100644 --- a/docs/journeys-from-trip.md +++ b/docs/journeys-from-trip.md @@ -39,7 +39,12 @@ const leg = journey.legs.find(l => l.line.product === 'nationalExpress') const previousStopover = leg.stopovers.find(st => st.departure && new Date(st.departure) < Date.now()) // find journeys from the ICE train to Köln Hbf -const journeys = await client.journeysFromTrip(leg.id, previousStopover, kölnHbf) +const { + journeys, + realtimeDataUpdatedAt, +} = await client.journeysFromTrip(leg.id, previousStopover, kölnHbf) ``` -`journeys` will be an array of [FPTF `journey`s](https://github.com/public-transport/friendly-public-transport-format/blob/3bd36faa721e85d9f5ca58fb0f38cdbedb87bbca/spec/readme.md#journey), as documented in [`journeys()`](journeys.md). +`journeys` is an array of [FPTF `journey`s](https://github.com/public-transport/friendly-public-transport-format/blob/3bd36faa721e85d9f5ca58fb0f38cdbedb87bbca/spec/readme.md#journey), as documented in [`journeys()`](journeys.md). + +`realtimeDataUpdatedAt` is a UNIX timestamp reflecting the latest moment when (at least some of) the response's realtime data have been updated. diff --git a/docs/journeys.md b/docs/journeys.md index cbd61db1..2c80f208 100644 --- a/docs/journeys.md +++ b/docs/journeys.md @@ -97,7 +97,12 @@ await client.journeys('900000003201', '900000100008', { }) ``` -`journeys()` will resolve with an object with the `journeys` & `earlierRef`/`laterRef` fields. It might look like this: +`journeys()` will resolve with an object with the following fields: +- `journeys` +- `earlierRef`/`laterRef` – pass them as `opt.earlierThan`/`opt.laterThan` into another `journeys()` call to retrieve the next "page" of journeys +- `realtimeDataUpdatedAt` – a UNIX timestamp reflecting the latest moment when (at least some of) the response's realtime data have been updated + +This object might look like this: ```js { @@ -267,6 +272,7 @@ await client.journeys('900000003201', '900000100008', { } ], earlierRef: '…', // use with the `earlierThan` option laterRef: '…' // use with the `laterThan` option + realtimeDataUpdatedAt: 1531259400, // 2018-07-10T23:50:00+02 } ``` diff --git a/docs/refresh-journey.md b/docs/refresh-journey.md index 31445937..f9e0d777 100644 --- a/docs/refresh-journey.md +++ b/docs/refresh-journey.md @@ -30,7 +30,10 @@ const client = createClient(vbbProfile) const {journeys} = await client.journeys('900000003201', '900000100008', {results: 1}) // later, fetch up-to-date info on the journey -await client.refreshJourney(journeys[0].refreshToken, {stopovers: true, remarks: true}) +const journey = await client.refreshJourney(journeys[0].refreshToken, {stopovers: true, remarks: true}) +const {realtimeDataUpdatedAt} = journey ``` -`refreshJourney()` will return a *single* [*Friendly Public Transport Format* v2 draft](https://github.com/public-transport/friendly-public-transport-format/blob/3bd36faa721e85d9f5ca58fb0f38cdbedb87bbca/spec/readme.md) `journey`, in the same format as with `journeys()`. +`journey` is a *single* [*Friendly Public Transport Format* v2 draft](https://github.com/public-transport/friendly-public-transport-format/blob/3bd36faa721e85d9f5ca58fb0f38cdbedb87bbca/spec/readme.md) `journey`, in the same format as returned by [`journeys()`](journeys.md). + +`realtimeDataUpdatedAt` is a UNIX timestamp reflecting the latest moment when (at least some of) the response's realtime data have been updated. diff --git a/index.js b/index.js index 06ba8f94..a695c14d 100644 --- a/index.js +++ b/index.js @@ -231,8 +231,9 @@ const createClient = (profile, userAgent, opt = {}) => { earlierRef: res.outCtxScrB, laterRef: res.outCtxScrF, journeys, - // todo [breaking]: rename to realtimeDataUpdatedAt - realtimeDataFrom: res.planrtTS ? parseInt(res.planrtTS) : null, + realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0' + ? parseInt(res.planrtTS) + : null, } } @@ -261,8 +262,9 @@ const createClient = (profile, userAgent, opt = {}) => { const ctx = {profile, opt, common, res} return { - // todo [breaking]: rename to realtimeDataUpdatedAt - realtimeDataFrom: res.planrtTS ? parseInt(res.planrtTS) : null, + realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0' + ? parseInt(res.planrtTS) + : null, ...profile.parseJourney(ctx, res.outConL[0]) } } @@ -368,8 +370,7 @@ const createClient = (profile, userAgent, opt = {}) => { if (!Array.isArray(res.outConL)) return [] const ctx = {profile, opt, common, res} - // todo [breaking]: return object with realtimeDataUpdatedAt - return res.outConL + const journeys = res.outConL .map(rawJourney => profile.parseJourney(ctx, rawJourney)) .map((journey) => { // For the first (transit) leg, HAFAS sometimes returns *all* past @@ -388,6 +389,13 @@ const createClient = (profile, userAgent, opt = {}) => { ], } }) + + return { + journeys, + realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0' + ? parseInt(res.planrtTS) + : null, + } } const locations = async (query, opt = {}) => { diff --git a/test/e2e/lib/refresh-journey.js b/test/e2e/lib/refresh-journey.js index 13962c03..f75827e8 100644 --- a/test/e2e/lib/refresh-journey.js +++ b/test/e2e/lib/refresh-journey.js @@ -15,16 +15,17 @@ const testRefreshJourney = async (cfg) => { test: t, fetchJourneys, refreshJourney, + validate, fromId, toId, when, - // todo: validate } = cfg const modelRes = await fetchJourneys(fromId, toId, { results: 1, departure: when, stopovers: false }) + validate(t, modelRes, 'journeysResult', 'modelRes') const [model] = modelRes.journeys // todo: move to journeys validator? @@ -34,6 +35,8 @@ const testRefreshJourney = async (cfg) => { const refreshed = await refreshJourney(model.refreshToken, { stopovers: false }) + validate(t, refreshed, 'refreshJourneyResult', 'refreshed') + t.same(simplify(refreshed), simplify(model)) } diff --git a/test/e2e/lib/validators.js b/test/e2e/lib/validators.js index ca410cfe..04afb443 100644 --- a/test/e2e/lib/validators.js +++ b/test/e2e/lib/validators.js @@ -428,6 +428,14 @@ const validateJourneysResult = (val, res, name = 'journeysResult') => { a.ok(isObj(res), name + ' must be an object') // todo: `earlierRef`, `laterRef` val.journeys(val, res.journeys, name + '.journeys') + + val.realtimeDataUpdatedAt(val, res.realtimeDataUpdatedAt, name + '.realtimeDataUpdatedAt') +} + +const validateRefreshJourneyResult = (val, res, name = 'refreshJourneyResult') => { + val.journey(val, res, name + '.journey') + + val.realtimeDataUpdatedAt(val, res.realtimeDataUpdatedAt, name + '.realtimeDataUpdatedAt') } const validateTrip = (val, trip, name = 'trip') => { @@ -619,6 +627,7 @@ module.exports = { journey: () => validateJourney, journeys: () => validateJourneys, journeysResult: () => validateJourneysResult, + refreshJourneyResult: () => validateRefreshJourneyResult, trip: () => validateTrip, arrival: createValidateArrival, departure: createValidateDeparture,