DocsGuidesTime-To-Live

Time-To-Live (TTL)

TopGun supports automatic data expiration via TTL (Time-To-Live). This is useful for temporary data like sessions, cache entries, or ephemeral state that should persist for a short while but not forever.

Auto-Expiration

Set expiration time in milliseconds, and data will be automatically cleaned up.

Works with Maps

TTL is supported on both LWW-Map and OR-Map data structures.

Background GC

Server periodically sweeps expired records to reclaim storage space.

Overview

You can attach a ttlMs (TTL in milliseconds) to individual records in both LWW-Map and OR-Map. The server performs proactive garbage collection to remove expired records.

Usage with LWW-Map

Pass the ttlMs option as the third argument to .set().

src/sessions/manager.ts

const sessions = client.getMap('sessions');

// Create a session that expires in 1 hour (3,600,000 ms)
sessions.set('user:123', { token: 'abc-123' }, 3600 * 1000);

// After 1 hour, 'user:123' will effectively disappear from the map.

Usage with OR-Map

Similarly, pass ttlMs as the third argument to .add().

src/games/lobby.ts

const activeGames = client.getORMap('games:active');

// Add a game lobby that expires in 5 minutes if not updated
activeGames.add('lobby:555', { status: 'waiting' }, 5 * 60 * 1000);

Garbage Collection

Note: Expiration is handled by the server’s background garbage collector. Clients may locally check TTL when reading, but the authoritative removal happens via the sync protocol when the server prunes the data.

Data is not immediately deleted from disk at the exact millisecond of expiration but is filtered out of query results.
Background processes periodically sweep and remove expired records to reclaim space.

Pub/Sub

Deployment