JavaScript SDKAPI reference
Topics and subscriptions
Reference for Topic, publish and subscribe options, Subscription, Message, PublishReceipt and topic sets.
Topic
client.topic(name) or client.topic<Events>(name).
| Member | Returns | Meaning |
|---|---|---|
name | string | The topic's name |
publish(event, data, options?) | Promise<PublishReceipt>, or Promise<void> for signals | Publishes one event. See PublishOptions |
subscribe(handler?, options?) / subscribe(options) | Subscription | Subscribes. See SubscribeOptions |
messages | LiveView<TopicMessage[]> | The latest 100 stream events, plus your own sends, while a subscription on this topic is active |
values(event?) | ValuesView | Current kv values by key, or signals by sender, for one event name. Without a name: every value, keyed name/key |
publish parameters
| Parameter | Type | Meaning |
|---|---|---|
event | string | The event's name, e.g. 'message'. Non-empty, at most 64 bytes |
data | any JSON value, string, Uint8Array, ArrayBuffer or typed array | The payload. Objects are sent as JSON, strings as text, bytes as bytes |
options | PublishOptions | Optional, below |
PublishOptions
| Option | Type | Default | Meaning |
|---|---|---|---|
delivery | 'stream' | 'kv' | 'signal' | 'stream', or the topic definition's type | How the event is delivered. Must match the topic's rule |
key | string | your identity | kv: which key to set or remove |
ttlMs | number | none | kv: how long the value lives, in ms |
remove | boolean | false | kv: remove the key; data is ignored |
headers | Record<string, string> | none | Up to limits.maxHeaders (16) string headers, passed to subscribers |
contentType | 'json' | 'text' | 'bytes' | 'flatbuffers' | 'protobuf' | 'msgpack' | 'cbor' | number | from data | Labels the payload. With an explicit type other than json or text, data must be bytes |
idempotencyKey | string | generated | 32 hex digits or a UUID. The node applies a key at most once within 10 minutes |
clientTime | number | Date.now() | Your clock for the event, Unix ms |
signal | AbortSignal | none | Stop waiting for the receipt. The event may still be published |
key, ttlMs and remove with a delivery other than kv throw InvalidArgument.
PublishReceipt
What a stream or kv publish resolves with.
| Field | Type | Meaning |
|---|---|---|
topic | string | The topic |
delivery | 'stream' | 'kv' | 'signal' | The delivery type used |
id | string | The same as Message.id of the delivered event |
uid | string (optional) | The event's permanent id |
cursor | Cursor (optional) | Its position in the topic, for stream events |
level | 'accepted' | 'committed' | How durably it was stored. Today always 'accepted' |
duplicate | boolean | true if the node had already stored this idempotency key. Still a success |
serverTime | number | When the node accepted it, Unix ms |
SubscribeOptions
| Option | Type | Default | Meaning |
|---|---|---|---|
from | 'latest' | 'oldest' | { last: number } | { after: Cursor | string } | 'latest' | Where stream events start when there is no saved position |
onGap | 'from-oldest' | 'from-latest' | 'fail' | 'from-oldest' | What to do when the requested position is no longer kept |
types | ('stream' | 'kv' | 'signal')[] | all | Only receive these delivery types |
events | string[] | all | Only receive these event names |
The handler, (message) => void | Promise<void>, runs for each event in order, one at a time.
Subscription
| Member | Type | Meaning |
|---|---|---|
topic | string | The topic |
ready | Promise<void> | Resolves when the node confirms; rejects if it refuses |
status | 'pending' | 'active' | 'resyncing' | 'failed' | 'ended' | 'closed' | The current status |
cursor | Cursor | undefined | The last event this subscription finished handling |
deliveries | ('stream' | 'kv' | 'signal')[] | The delivery types the topic allows, once confirmed |
unsubscribe() | Promise<void> | Stops this subscription |
[Symbol.asyncIterator] | for await (const msg of sub); ends when the subscription does |
Subscription events
sub.on(event, fn) returns a function that removes the listener; once() and off() are also available.
| Event | Arguments | When |
|---|---|---|
message | (message) | Every event, after your handler ran |
snapshot | (messages[]) | The current kv values or signals, on subscribe and after reconnects |
gap | (gap) | Events were missed, see GapEvent |
error | (err) | The subscription failed, or your handler threw |
ended | (err) | The node ended it (permissions narrowed), the identity changed, or the client closed |
status | (status) | The status changed |
GapEvent
| Field | Type | Meaning |
|---|---|---|
topic | string | The topic |
reason | 'expired' | 'epoch-lost' | 'slow-consumer' | 'unspecified' | Why: history was trimmed, the node restarted, or the client fell too far behind |
requested | Cursor (optional) | The position you asked to resume after |
oldest | Cursor (optional) | The oldest event still kept |
latest | Cursor (optional) | The newest event |
resumed | boolean | false when onGap: 'fail' ended the subscription |
Message
Every event you receive.
| Field | Type | Meaning |
|---|---|---|
topic | string | The topic |
name | string | The event's name |
delivery | 'stream' | 'kv' | 'signal' | Its delivery type |
data | your type, or unknown | The decoded payload: JSON as a value, text as a string, anything else as a Uint8Array. undefined for a removed kv key |
publisher | string | The verified identity of the sender. Trust this, not names inside data |
id | string | Unique within the topic; use it as a React key |
uid | string (optional) | Permanent id for stream and kv events. Point replies, edits and reactions at it |
cursor | Cursor (optional) | Position in the topic, for stream events |
key | string (optional) | kv: the key. Signals: the publisher |
deleted | boolean | A removed kv key |
headers | Record<string, string> | Headers set by the publisher |
contentType | number | The payload's content type code |
payload | Uint8Array | The raw payload; don't modify it |
serverTime | number | When the node accepted it, Unix ms. Informational, not for ordering |
clientTime | number (optional) | The publisher's clock |
replayed | boolean | Delivered from history rather than live |
pending | boolean | Sent by this client and not yet confirmed |
fromCache | boolean | Read from the local store and not yet confirmed by the node |
Entries of topic.messages also have:
| Field | Type | Meaning |
|---|---|---|
status | 'pending' | 'sent' | 'failed' | Where your own send is; received events are 'sent' |
error | RealtimeError (optional) | Why a send failed |
retry() | () => Promise<void> (optional) | Sends a failed message again, with the same idempotency key |
ValuesView
topic.values(event): a read-only Map<string, Message> that is also a live value.
It has get, has, size, keys(), values(), entries(), forEach() and can be iterated with for…of.
TopicSet
client.topic(['chat/a', 'chat/b']).
| Member | Returns | Meaning |
|---|---|---|
names | string[] | The topics in the set |
add(names) | this | Adds topics; active subscriptions of the set pick them up |
remove(names) | this | Removes topics; active subscriptions of the set stop them |
get(name) | Topic | The single topic's handle |
subscribe(handler?, options?) | SetSubscription | Subscribes to every topic. Takes SubscribeOptions plus strict |
publish(event, data, options?) | Promise<PublishReceipt[]> | Publishes to every topic; one receipt per topic, in order |
Set subscribe options add strict: boolean (default false): reject ready if any topic fails.
SetSubscription
| Member | Type | Meaning |
|---|---|---|
ready | Promise<{ ok: string[]; failed: { topic, error }[] }> | Settles when every topic has answered |
topics | string[] | The topics currently covered |
statuses | Map<string, SubscriptionStatus> | Each topic's status |
unsubscribe() | Promise<void> | Stops every topic |
| Events | message, gap, error, ended | As for a single subscription |
EventFilter
The filter of client.on(filter, handler). Every field is optional and narrows the match.
| Field | Type | Meaning |
|---|---|---|
topic | string | A topic name or pattern (* one level, trailing > one or more) |
delivery | 'stream' | 'kv' | 'signal' | Only this delivery type |
event | string | string[] | Only these event names |
publisher | string | string[] | Only these publishers |
self | boolean | false skips events your own identity published |