cached-hafas-client

Pass in a HAFAS client, cache data from it.

Note: This package is mainly intended to prevent expensive and/or frequent API calls to HAFAS. As a side effect, it may reduce local CPU load & latency, but that depends on the specific use case.

cached-hafas-client's core logic is separated from data storage code; You can pick the store implementation that fits your use case best. Right now the following stores are implemented:

store name	built on top of	notes
cached-hafas-client/stores/redis.js	Redis
cached-hafas-client/stores/sqlite.js	SQLite	TTL not implemented yet
cached-hafas-client/stores/in-memory.js	in-memory (using quick-lru)

Installation

1npm install cached-hafas-client

Usage

Let's set up a cached hafas-client instance.

1// create HAFAS client
2import {createVbbHafas} from 'vbb-hafas'
3const hafas = createVbbHafas('my-awesome-program')
4
5// create a store backed by Redis
6import Redis from 'ioredis'
7import {createRedisStore} from 'cached-hafas-client/stores/redis.js'
8const redis = new Redis()
9const store = createRedisStore(redis)
10
11// wrap HAFAS client with cache
12import {createCachedHafasClient as withCache} from 'cached-hafas-client'
13const cachedHafas = withCache(hafas, store)

Because cached-hafas-client caches HAFAS responses by "request signature", it is build on the assumption that, HAFAS works deterministically, aside from the ever-changing transit data underneath. Because there are no guarantees for this, use cached-hafas-client with a grain of salt.

This is why you must send deterministic queries; for example, you must pass opt.duration to departures()/arrivals(), so that cached-hafas-client knows the time frame that the list of results returned by HAFAS is for.

1const wollinerStr = '900000007105'
2const husemannstr = '900000110511'
3const when = new Date(Date.now() + 60 * 60 * 1000)
4
5// will fetch fresh data from HAFAS
6await cachedHafas.departures(wollinerStr, {duration: 10, when})
7
8// within the time frame of the departures() call above,
9// so it will use the cached data
10await cachedHafas.departures(wollinerStr, {
11	duration: 3, when: new Date(+when + 3 * 60 * 1000)
12})

Note: cached-hafas-client is only compatible with hafas-client@5.

with a custom cache TTL

By default, cached-hafas-client uses TTLs that try to strike a balance between up-to-date-ness and a cache hit ratio: The caching duration depends on how far in the future you query for.

You can pass custom cache TTLs per hafas-client method, either as static values or as a function returning the cache TTL based on the arguments.

1const SECOND = 1000
2const MINUTE = 60 * SECOND
3
4const cachePeriods = {
5	// cache all cachedHafas.stop(…) calls for 10m
6	stop: 10 * MINUTE,
7	// cache cachedHafas.trip(tripId, opt) based on sqrt(opt.when - now)
8	trip: (_, opt = {}) => {
9		const diffSecs = (new Date(opt.when) - Date.now()) / SECOND
10		if (Number.isNaN(diffSecs)) return 10 * SECOND // fallback
11		return Math.round(Math.pow(diffSecs, 1/2) * SECOND)
12	},
13}
14const cachedHafas = withCache(hafas, store, {cachePeriods})

Counting cache hits & misses

1cachedHafas.on('hit', (hafasClientMethod, ...args) => {
2	console.info('cache hit!', hafasClientMethod, ...args)
3})
4cachedHafas.on('miss', (hafasClientMethod, ...args) => {
5	console.info('cache miss!', hafasClientMethod, ...args)
6})

Bypassing the cache

1import {CACHED} from 'cached-hafas-client'
2
3// will always fresh data
4await cachedHafas.departures(wollinerStr, {[CACHED]: false})

tracking hits & misses as Prometheus metrics

You can optionally track the number of hits & misses as two Prometheus Counters cached_hafas_client_hits_total & cached_hafas_client_misses_total, respectively:

1import {trackCachingMetrics} from 'cached-hafas-client/with-metrics.js'
2
3trackCachingMetrics(cachedHafas) // will keep metrics now

API

1createCachedHafas(hafas, storage, opt = {})

hafas must be a hafas-client@6-compatible API client.

opt overrides this default configuration:

1{
2	cachePeriods: {
3		departures: 30_1000, arrivals: 30_1000, // 30s
4		journeys: 30_1000, // 30s
5		refreshJourney: 60_1000, // 1m
6		trip: 30_1000, // 30s
7		radar: 10_1000, // 10s
8		locations: 3_600_1000, // 1h
9		stop: 3_600_1000, // 1h
10		nearby: 3_600_1000, // 1h
11		reachableFrom: 30_1000,
12	},
13}

Contributing

If you have a question or need support using cached-hafas-client, please double-check your code and setup first. If you think you have found a bug or want to propose a feature, use the issues page.