@textile/datastore-ttl

Time to Live Datastore (datastore-ttl)

An implementation of the Datastore interface that supports a time-to-live (TTL) for key-value pairs.

After the TTL expires on a given key, the entry will be automatically cleared from the datastore unless it is refreshed in the mean time. In this way you can build utilities like session managers where a given session is refreshed with each interaction but expires after a set period of time since the last interaction. This library borrows inspiration and ideas from level-ttl.

Table of Contents

Click to expand

• Background
• Install
• Usage
• API
• Maintainers
• Contributing
• License

Background

TTLDatastore uses an internal scan every 10 seconds by default, this limits the available resolution of your TTL values, possibly delaying a delete for up to 10 seconds. The resolution can be tuned by passing the frequency option to the constructor.

Of course, a scan takes some resources, particularly on a data store that makes heavy use of TTLs. If you don't require high accuracy for actual deletions then you can increase the frequency. Note though that a scan only involves invoking a query that returns only the entries due to expire, so it doesn't have to manually check through all entries with a TTL. Depending on the backing Datastore, this could be reasonably efficient, or extremely slow. So keep that in mind.

Default TTL

You can set a default TTL value for all your keys by specifying the ttl option to the constructor. This can be overridden by explicitly setting the TTL value on put or by calling the top-level ttl method.

Install

npm i @textileio/datastore-ttl

Usage

import { Buffer } from 'buffer'
import { MemoryDatastore, Key } from 'interface-datastore'
import { TTLDatastore } from '@textile/datastore-ttl'

// Simple promise-based sleep function
const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))

// Use any compliant Datastore
const child = new MemoryDatastore()
const key = new Key('foo')
const store = new TTLDatastore(child)
await ttl.put(key, Buffer.from('bar'), 1000)
// Wait 900 ms...
await sleep(900)
// Keep alive for another 100 ms from now
await ttl.ttl(key, 100)
await ttl.has(key) // true
await ttl.expiration(key) // <unix-timestamp>
await ttl.get(key) // <Buffer>
// Wait 110 ms
await sleep(110)
await ttl.has(key) // false

There are also several useful examples included in the tests.

API

See https://textileio.github.io/js-datastore-ttl

Maintainers

Carson Farmer

Contributing

See the contributing file. PRs accepted!

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT (c) 2019 Textile.io

Thanks

Big thanks to the find folks behind Level/level-ttl.