JavaScript SDKAPI reference
Client options
Every option of new Folkways.Realtime() and Folkways.connect(), with its type, default and meaning.
import { Folkways } from '@folkways/realtime';
const client = new Folkways.Realtime(options); // then: await client.connect()
const connected = await Folkways.connect(options); // create and connect in one calloptions needs a node address (url or endpoints) and exactly one way to authenticate (authUrl, token or
publishableKey). Everything else is optional. An invalid option throws InvalidArgument from the constructor.
Address
| Option | Type | Default | Meaning |
|---|---|---|---|
url | string | – | The node URL from the segment's Connect tab, e.g. https://rte.example.com. Gives wss://rte.example.com/v1/ws for WebSocket and https://rte.example.com/v1/… for HTTP |
endpoints | { websocket?: string; http?: string } | from url | Explicit addresses; each one overrides what url gives |
Authentication
Give exactly one of authUrl, token or publishableKey.
| Option | Type | Default | Meaning |
|---|---|---|---|
authUrl | string | – | Your backend's token endpoint. The SDK POSTs { "reason": … } as JSON and reads { "token": "…" } JSON or a plain-text token |
authHeaders | Record<string, string> or a function returning them (may be async) | – | Extra headers for authUrl requests, e.g. your app's Authorization header |
token | string or ({ reason }) => string | Promise<string> | – | A token, or a function that returns one. reason is 'initial', 'expiring' or 'rejected'. A fixed string can't be refreshed |
publishableKey | string | – | A publishable key (rte_pk_…) for anonymous, read-only access. Needs the HTTP address (url or endpoints.http) |
Connection
| Option | Type | Default | Meaning |
|---|---|---|---|
transports | ('websocket' | 'http')[] | ['websocket', 'http'] | Transports to use, in order of preference |
connectTimeoutMs | number | 15000 | connect() rejects with Timeout after this long, while the client keeps trying. 0 waits forever |
openTimeoutMs | number | 10000 | Time allowed for one connection attempt |
requestTimeoutMs | number | 10000 | Time allowed for subscribe, unsubscribe and token-swap replies |
reconnect | { initialDelayMs?, maxDelayMs?, maxAttempts? } or false | { initialDelayMs: 500, maxDelayMs: 30000, maxAttempts: Infinity } | Backoff between reconnect attempts. false gives up on the first disconnect |
offlineAfterMs | number | 120000 | After this long of failed reconnecting the state becomes offline and publishes stop waiting |
fallbackAfterFailures | number | 2 | WebSocket failures in a row before switching to HTTP long-polling |
webSocketRetryMs | number | 300000 | While on HTTP after a fallback, how often to try WebSocket again. 0 never |
pongTimeoutMs | number | 10000 | Extra silence tolerated after a missed heartbeat before the connection is replaced |
longPoll | { waitMs?, maxEvents?, emptyStateRecheckMs? } | { waitMs: 25000, maxEvents: 100, emptyStateRecheckMs: 2000 } | HTTP long-poll tuning: how long one poll waits, how many events it returns, how often to recheck state topics |
Publishing
| Option | Type | Default | Meaning |
|---|---|---|---|
publishTimeoutMs | number | 30000 | How long a publish may take in total, retries included, before it fails with Timeout |
publishRetries | number | 3 | Retries of publishes the node turned away for being busy or rate-limited |
offlineQueue | { maxSize?: number } or false | { maxSize: 1000 } | Publishes kept while reconnecting; more fail with QueueFull. false rejects them with NotConnected |
Subscriptions
| Option | Type | Default | Meaning |
|---|---|---|---|
cursorAckIntervalMs | number | 5000 | How often processed positions are reported to the node. 0 turns it off |
signalTtlMs | number | 5000 | How long a signal stays in topic.values() |
Local storage
See Offline and local storage.
| Option | Type | Default | Meaning |
|---|---|---|---|
store | Store | memoryStore() | Where cursors, the outbox and the cache are kept. Use a persistent store to keep them across reloads |
outbox | { maxAgeMs?: number } | { maxAgeMs: 600000 } | With a persistent store: unsent publishes older than this fail instead of being resent |
cache | { messagesPerTopic?, maxBytes? } or false | { messagesPerTopic: 100, maxBytes: 5242880 } | With a persistent store: how many recent messages and values to cache for fast reloads. false turns it off |
cipher | { encrypt(plain), decrypt(sealed) } | – | Encrypts what is written to a persistent store. Both functions take and return strings, and may be async |
Runtime
| Option | Type | Default | Meaning |
|---|---|---|---|
webSocket | WebSocket constructor | globalThis.WebSocket | For runtimes without a global one, e.g. WebSocket from the ws package on Node.js 20 |
fetch | fetch-compatible function | globalThis.fetch | For runtimes without a global fetch |
logger | { debug, info, warn, error } | silent | Where diagnostics go. consoleLogger('debug') logs to the console. Tokens are never logged |
clientName | string | folkways-js/<version> | Reported to the node, for troubleshooting |
device | string | – | A label such as ios or web-chrome, reported to the node. Descriptive only |
transportOverrides | { stream?, request? } | – | Advanced: replace the transports, for tests or custom runtimes |
connect() and close() options
| Method | Option | Type | Meaning |
|---|---|---|---|
client.connect(options?) | segment | string | Fail with SegmentMismatch if the token is for another segment. Also accepted by Folkways.connect() |
client.close(options?) | clear | boolean | Also wipe this identity's local data (cursors, cache, outbox) |