Key-value (kv) events

A kv event sets a value under a key. Only the latest value per key is kept, and anyone who subscribes gets the current values first, then every change. Use it for state rather than history: where each driver is, who read up to which message, each player's score.

The topic's rule in the dashboard must have the class Last value.

Set a valueCopy Anchor Link

const ride = client.topic('rides/42/location');

await ride.publish('location', { lat: 59.43, lng: 24.75 }, { delivery: 'kv' });

The key defaults to your identity, so each driver writes their own entry. Choose another key with key:

await ride.publish('location', { lat: 59.43, lng: 24.75 }, { delivery: 'kv', key: 'driver-7' });

Expire or remove itCopy Anchor Link

// Gone after 30 seconds unless set again.
await ride.publish('location', { lat: 59.43, lng: 24.75 }, { delivery: 'kv', ttlMs: 30_000 });

// Remove your entry now (data is ignored).
await ride.publish('location', null, { delivery: 'kv', remove: true });

A rule can also give every value a default lifetime (TTL on the Topic rules tab).

Read the current valuesCopy Anchor Link

Subscribe, then read topic.values(event): a live map from key to the latest Message.

ride.subscribe();

const locations = ride.values('location'); // ReadonlyMap<key, Message>
locations.subscribe(() => {
  for (const [driver, msg] of locations) moveMarker(driver, msg.data);
});

values() stays up to date while a subscription on the topic is active. It works directly with React's useSyncExternalStore; see Using it with React.

If you'd rather handle changes as events, use the subscription:

ride.subscribe((msg) => {
  if (msg.deleted) removeMarker(msg.key);
  else moveMarker(msg.key, msg.data);
});

A removed key arrives as a message with deleted: true and data set to undefined.

PermissionsCopy Anchor Link

Setting or removing a value needs the set or publish operation in the token. In the dashboard, allow publish on the rule.