reachableFrom: realtimeDataFrom -> realtimeDataUpdatedAt 💥✅📝

docs/reachable-from.md

@@ -36,17 +36,22 @@ const vbbProfile = require('hafas-client/p/vbb')
 
 const client = createClient(vbbProfile, 'my-awesome-program')
 
-console.log(await client.reachableFrom({
+const {
+	reachable,
+	realtimeDataUpdatedAt,
+} = await client.reachableFrom({
 	type: 'location',
 	address: '13353 Berlin-Wedding, Torfstr. 17',
 	latitude: 52.541797,
 	longitude: 13.350042
 }, {
 	maxDuration: 10 // minutes
-}))
+})
 ```
 
-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.
+
+`reachable` may look like this:
 
 ```js
 [

index.js

@@ -669,8 +669,12 @@ const createClient = (profile, userAgent, opt = {}) => {
 			}
 		}
 
-		// todo [breaking]: return object with realtimeDataUpdatedAt
-		return byDuration
+		return {
+			reachable: byDuration,
+			realtimeDataUpdatedAt: res.planrtTS && res.planrtTS !== '0'
+				? parseInt(res.planrtTS)
+				: null,
+		}
 	}
 
 	const remarks = async (opt = {}) => {

test/e2e/lib/reachable-from.js

@@ -12,9 +12,17 @@ const testReachableFrom = async (cfg) => {
 		validate
 	} = cfg
 
-	const results = await reachableFrom(address, {
+	const res = await reachableFrom(address, {
 		when, maxDuration
 	})
+	const {
+		reachable: results,
+		realtimeDataUpdatedAt,
+	} = res
+
+	if (realtimeDataUpdatedAt !== null) { // todo: move this check into validators
+		validate(t, realtimeDataUpdatedAt, 'realtimeDataUpdatedAt', 'res.realtimeDataUpdatedAt')
+	}
 
 	t.ok(Array.isArray(results), 'results must an array')
 	t.ok(results.length > 0, 'results must have >0 items')

test/e2e/lib/validators.js

@@ -13,6 +13,7 @@ const is = val => val !== null && val !== undefined
 
 const createValidateRealtimeDataUpdatedAt = (cfg) => {
 	const validateRealtimeDataUpdatedAt = (val, rtDataUpdatedAt, name = 'realtimeDataUpdatedAt') => {
+		a.ok(Number.isInteger(rtDataUpdatedAt), name + ' must be an integer')
 		assertValidWhen(rtDataUpdatedAt * 1000, cfg.when, name, 100 * DAY)
 	}
 	return validateRealtimeDataUpdatedAt