atmosphere.js 5.0 API Reference

Atmosphere

import { Atmosphere } from 'atmosphere.js';
const atm = new Atmosphere({
 logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error' | 'silent'
 defaultTransport: 'websocket', // Default transport for all subscriptions
 fallbackTransport: 'long-polling', // Default fallback
 interceptors: [], // Client-side interceptors
});
atm.version; // '5.0.0'

subscribe(request, handlers): Promise<Subscription>

const sub = await atm.subscribe(request, handlers);

closeAll(): void

getSubscriptions(): Map<string, Subscription>

AtmosphereRequest

{
 url: string; // Endpoint URL (required)
 transport: TransportType; // 'websocket' | 'sse' | 'long-polling' | 'streaming'
 fallbackTransport?: TransportType; // Fallback if primary fails
 contentType?: string; // Default: 'text/plain'
 trackMessageLength?: boolean; // Length-prefix messages (recommended: true)
 messageDelimiter?: string; // Default: '|'
 enableProtocol?: boolean; // Atmosphere protocol handshake
 timeout?: number; // Inactivity timeout (ms)
 connectTimeout?: number; // Connection timeout (ms)
 reconnect?: boolean; // Auto-reconnect (default: true)
 reconnectInterval?: number; // Base reconnect delay (ms)
 maxReconnectOnClose?: number; // Max reconnect attempts (default: 5)
 maxRequest?: number; // Max long-polling request cycles
 headers?: Record<string, string>; // Custom HTTP headers
 withCredentials?: boolean; // Include cookies (CORS)
 heartbeat?: {
 client?: number; // Client heartbeat interval (ms)
 server?: number; // Expected server heartbeat (ms)
 };
}

SubscriptionHandlers

{
 open?: (response: AtmosphereResponse) => void;
 message?: (response: AtmosphereResponse) => void;
 close?: (response: AtmosphereResponse) => void;
 error?: (error: Error) => void;
 reopen?: (response: AtmosphereResponse) => void;
 reconnect?: (request: AtmosphereRequest, response: AtmosphereResponse) => void;
 transportFailure?: (reason: string, request: AtmosphereRequest) => void;
 clientTimeout?: (request: AtmosphereRequest) => void;
 failureToReconnect?: (request: AtmosphereRequest, response: AtmosphereResponse) => void;
}

Subscription

sub.id; // string — unique subscription ID
sub.state; // ConnectionState
sub.push(message); // Send string | object | ArrayBuffer
await sub.close(); // Disconnect
sub.suspend(); // Pause receiving
await sub.resume(); // Resume receiving
sub.on(event, handler); // Add event listener
sub.off(event, handler); // Remove event listener

ConnectionState

'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'suspended' | 'closed' | 'error'

AtmosphereRooms

import { AtmosphereRooms } from 'atmosphere.js';
const rooms = new AtmosphereRooms(atmosphere, baseRequest);

join(roomName, member, handlers): Promise<RoomHandle>

const handle = await rooms.join('lobby', { id: 'alice' }, {
 message: (data, member) => { },
 join: (event: PresenceEvent) => { },
 leave: (event: PresenceEvent) => { },
 joined: (roomName, members) => { },
 error: (error) => { },
});

leave(roomName): void

leaveAll(): Promise<void>

room(name): RoomHandle | undefined

joinedRooms(): string[]

RoomHandle

handle.name; // Room name
handle.members; // ReadonlyMap<string, RoomMember>
handle.broadcast(data); // Send to all members
handle.sendTo(memberId, data); // Direct message
handle.leave(); // Leave the room

Types

RoomMember

{ id: string; metadata?: Record<string, unknown>; }

PresenceEvent

{ type: 'join' | 'leave'; room: string; member: RoomMember; timestamp: number; }

RoomMessage (wire format)

{ type: 'join' | 'leave' | 'broadcast' | 'direct' | 'presence';
 room: string;
 data?: unknown;
 member?: RoomMember;
 target?: string; }

AtmosphereInterceptor (Client-Side)

{
 name?: string;
 onOutgoing?: (data: string | ArrayBuffer) => string | ArrayBuffer;
 onIncoming?: (body: string) => string;
}

Framework Hooks

React — useRoom<T>(options): UseRoomResult<T>

import { useRoom } from 'atmosphere.js/react';
const { joined, members, messages, broadcast, sendTo, error } = useRoom<T>({
 request: AtmosphereRequest,
 room: string,
 member: RoomMember,
});

Vue — useRoom<T>(request, roomName, member): Refs

import { useRoom } from 'atmosphere.js/vue';
const { joined, members, messages, broadcast, sendTo, error } = useRoom<T>(
 request, 'lobby', { id: 'alice' }
);

Svelte — createRoomStore<T>(request, roomName, member)

import { createRoomStore } from 'atmosphere.js/svelte';
const { store, broadcast, sendTo } = createRoomStore<T>(
 request, 'lobby', { id: 'alice' }
);
// $store.joined, $store.members, $store.messages, $store.error