JavaScript SDKAPI reference
Client
Reference for Folkways.Realtime — its methods and properties, the connection, the session, and the SDK's helper exports.
Folkways
import { Folkways } from '@folkways/realtime';| Member | Meaning |
|---|---|
new Folkways.Realtime(options) | Creates a client. See Client options |
Folkways.connect(options) | Creates a client and connects. Resolves with the connected client; on failure closes it and rejects |
Folkways.version | The SDK version, e.g. '0.1.0' |
Realtime and connect are also exported on their own.
Realtime
Methods
| Method | Returns | Meaning |
|---|---|---|
connect(options?) | Promise<Session> | Connects and resolves with the session. Rejects on a fatal error, or with Timeout after connectTimeoutMs while it keeps trying. Calling it again after failed starts over |
topic(name) | Topic | The handle for one topic. The same object for the same name. Throws InvalidTopic for a bad name. Accepts an event map type: topic<Events>(name) |
topic(names[]) | TopicSet | A set of topics handled together |
on(handler) / on(filter, handler) | () => void | Listens to every event the client receives, optionally filtered. Returns a function that stops listening. See Listening to everything |
updateToken(token) | Promise<void> | Swaps the token or token function. Same identity: everything stays. Different identity: reconnects, ends subscriptions with IdentityChanged and wipes the old identity's local data |
serverNow() | number | Date.now() corrected by the measured clock offset to the node |
close(options?) | Promise<void> | Closes for good. Queued publishes fail with ClientClosed. { clear: true } also wipes local data |
Properties
| Property | Type | Meaning |
|---|---|---|
connection | Connection | The connection's state, transport and events |
session | Session | null | Who this client is, once connected; null before. Kept up to date across token refreshes |
sessionView | LiveView<Session | null> | session as a live value, for UI bindings |
Connection
client.connection. Also a live value: getSnapshot() returns { state, transport, error }.
| Member | Type | Meaning |
|---|---|---|
state | ConnectionState | 'idle', 'connecting', 'connected', 'reconnecting', 'offline', 'failed' or 'closed' |
transport | 'websocket' | 'http' | null | The transport in use, or null while not connected |
error | RealtimeError | null | Why the connection failed, while failed |
whenConnected() | Promise<void> | Resolves when connected; rejects if the connection fails or closes first |
on('change', fn) | () => void | fn({ current, previous, reason? }) on every state change |
on('error', fn) | () => void | fn(err) for errors not tied to one call |
getSnapshot(), subscribe(listener) | Live value interface, for useSyncExternalStore |
once() and off() are also available.
Session
What connect() resolves with, and client.session. A new session object replaces it on every reconnect or token
refresh.
| Property | Type | Meaning |
|---|---|---|
identity | string | null | Who this connection acts for, e.g. 'user:42'; null when anonymous |
anonymous | boolean | true for publishable-key and other anonymous connections |
id | string | This connection's session id (32 hex digits) |
segment | { id: string; environment: string | null } | null | The verified segment, e.g. { id: '5fae…', environment: 'production' } |
permissions | { topics: string; ops: Op[] }[] | What the token allows |
can(op, topic) | boolean | Whether the token allows op on topic, for hiding UI. The node still enforces it |
expiresAt | number | null | When the token expires (Unix ms). The SDK refreshes before it |
limits | Limits | The node's limits, see below |
transport | 'websocket' | 'http' | The transport of this session |
features | string[] | Optional features the node announced |
Limits
session.limits, as announced by the node. The defaults below apply until it says otherwise.
| Limit | Default | Meaning |
|---|---|---|
maxPayloadBytes | 61440 (60 KiB) | Largest payload of one event |
maxHeaders | 16 | Most headers on one event |
maxTopicBytes | 255 | Longest topic name |
maxSubscriptions | 1000 | Most topics one connection may subscribe to |
maxFrameBytes | 65536 | Largest protocol frame |
maxFramesPerPacket | 64 | Most frames sent together |
heartbeatMs | 30000 | Heartbeat interval |
idleTimeoutMs | 90000 | Silence after which the node closes a connection |
LiveView
Live values (client.connection, client.sessionView, topic.messages, topic.values()) share one interface,
which React's useSyncExternalStore, Svelte stores and Vue refs accept as is:
| Member | Meaning |
|---|---|
getSnapshot() | The current value: an immutable snapshot that is replaced, never changed, on update |
subscribe(listener) | Calls listener() after every change. Returns a function that removes it |
Helper exports
| Export | Meaning |
|---|---|
isRealtimeError(e) | true if e is a RealtimeError |
RealtimeError | The error class. See Errors |
Code | Error codes by name, e.g. Code.Forbidden. See Error codes |
codeName(code) | The name of a code, e.g. 'Forbidden' |
codeInfo(code) | { name, httpStatus, retry, closesConnection } for a code |
defineTopic | Shared, typed topic definitions. See Typed events |
topicError(name) | Why a topic name is invalid, or undefined if it is valid |
cursor(epoch, seq) | Builds a Cursor |
formatCursor(cursor) | 'epoch:seq' |
parseCursor(text) | A Cursor, or undefined for anything else |
isAfter(cursor, ref) | Whether cursor comes after ref |
consoleLogger(level?, prefix?) | A logger writing to the console at level ('debug', 'info' (default), 'warn', 'error') and above |
silentLogger | A logger that drops everything (the default) |
memoryStore() | The default in-memory store |
encodePayload(data, contentType?) | Encodes data as the SDK does when publishing |
decodePayload(contentType, bytes) | Decodes a payload as the SDK does when receiving |
endpointsFromUrl(url) | The WebSocket and HTTP addresses the SDK derives from url |
VERSION | The SDK version |