0
# Phoenix JavaScript Client Types
1
2
Phoenix JavaScript client TypeScript definitions providing complete type safety for real-time WebSocket communication with Phoenix Framework applications. These types enable full IDE support and compile-time checking for Phoenix channels, presence tracking, and connection management.
3
4
## Package Information
5
6
- **Package Name**: @types/phoenix
7
- **Package Type**: npm (TypeScript definitions)
8
- **Language**: TypeScript
9
- **Installation**: `npm install @types/phoenix phoenix`
10
11
## Core Imports
12
13
```typescript
14
import { Socket, Channel, Push, Presence, Timer } from "phoenix";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { Socket, Channel, Push, Presence, Timer } = require("phoenix");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { Socket, Channel, Presence } from "phoenix";
27
28
// Create and connect to Phoenix socket
29
const socket = new Socket("/socket", {
30
params: { userToken: "abc123" },
31
heartbeatIntervalMs: 30000
32
});
33
socket.connect();
34
35
// Join a channel and handle messages
36
const channel = socket.channel("room:lobby", { clientId: "user123" });
37
38
channel.on("new_message", (message) => {
39
console.log("Received:", message);
40
});
41
42
channel.join()
43
.receive("ok", (resp) => console.log("Joined successfully", resp))
44
.receive("error", (resp) => console.log("Unable to join", resp));
45
46
// Send messages with status handling
47
channel.push("new_message", { body: "Hello Phoenix!" })
48
.receive("ok", (resp) => console.log("Message sent", resp))
49
.receive("error", (resp) => console.log("Send failed", resp));
50
```
51
52
## Architecture
53
54
Phoenix JavaScript client is built around several key components:
55
56
- **Socket**: WebSocket connection manager with automatic reconnection, heartbeat, and transport fallbacks
57
- **Channel**: Topic-based message routing with join/leave lifecycle and bidirectional communication
58
- **Push**: Message sending mechanism with status callbacks for delivery confirmation
59
- **Presence**: Real-time user presence tracking with join/leave detection and state synchronization
60
- **Transport System**: Pluggable transport layer supporting WebSocket with Long Poll fallback
61
- **Connection Management**: Automatic reconnection with configurable backoff strategies
62
63
## Capabilities
64
65
### WebSocket Connection Management
66
67
Core Socket functionality for establishing and managing WebSocket connections to Phoenix applications, including connection lifecycle, authentication, and transport configuration.
68
69
```typescript { .api }
70
class Socket {
71
constructor(endPoint: string, opts?: Partial<SocketConnectOption>);
72
73
connect(params?: any): void;
74
connectionState(): ConnectionState;
75
isConnected(): boolean;
76
77
onOpen(callback: () => void | Promise<void>): MessageRef;
78
onClose(callback: (event: CloseEvent) => void | Promise<void>): MessageRef;
79
onError(callback: (
80
error: Event | string | number,
81
transport: new(endpoint: string) => object,
82
establishedConnections: number
83
) => void | Promise<void>): MessageRef;
84
}
85
86
type ConnectionState = "connecting" | "open" | "closing" | "closed";
87
type MessageRef = string;
88
```
89
90
[Socket Connection](./socket.md)
91
92
### Channel Communication
93
94
Channel-based messaging system for subscribing to topics and exchanging real-time messages with Phoenix applications, including join/leave lifecycle and event handling.
95
96
```typescript { .api }
97
class Channel {
98
constructor(topic: string, params?: object | (() => object), socket?: Socket);
99
100
readonly state: ChannelState;
101
readonly topic: string;
102
103
join(timeout?: number): Push;
104
leave(timeout?: number): Push;
105
106
on(event: string, callback: (response?: any) => void | Promise<void>): number;
107
push(event: string, payload: object, timeout?: number): Push;
108
}
109
110
type ChannelState = "closed" | "errored" | "joined" | "joining" | "leaving";
111
```
112
113
[Channel Communication](./channel.md)
114
115
### Message Push Operations
116
117
Push mechanism for sending messages to channels with delivery status tracking and timeout handling, enabling reliable message delivery confirmation.
118
119
```typescript { .api }
120
class Push {
121
constructor(channel: Channel, event: string, payload: object, timeout: number);
122
123
send(): void;
124
resend(timeout: number): void;
125
receive(status: PushStatus, callback: (response?: any) => any): this;
126
}
127
128
type PushStatus = "ok" | "error" | "timeout";
129
```
130
131
[Push Operations](./push.md)
132
133
### Presence Tracking
134
135
Real-time presence tracking system for monitoring user join/leave events and maintaining synchronized presence state across connected clients.
136
137
```typescript { .api }
138
class Presence {
139
constructor(channel: Channel, opts?: PresenceOpts);
140
141
onJoin(callback: PresenceOnJoinCallback): void;
142
onLeave(callback: PresenceOnLeaveCallback): void;
143
list<T = any>(chooser?: (key: string, presence: any) => T): T[];
144
145
static syncState(
146
currentState: object,
147
newState: object,
148
onJoin?: PresenceOnJoinCallback,
149
onLeave?: PresenceOnLeaveCallback
150
): any;
151
}
152
153
type PresenceOnJoinCallback = (key?: string, currentPresence?: any, newPresence?: any) => void;
154
type PresenceOnLeaveCallback = (key?: string, currentPresence?: any, newPresence?: any) => void;
155
```
156
157
[Presence Tracking](./presence.md)
158
159
### Transport and Utilities
160
161
Supporting utilities including Timer for reconnection backoff, LongPoll fallback transport, and Ajax helper for HTTP requests when WebSocket is unavailable.
162
163
```typescript { .api }
164
class Timer {
165
constructor(callback: () => void | Promise<void>, timerCalc: (tries: number) => number);
166
167
reset(): void;
168
scheduleTimeout(): void;
169
}
170
171
class LongPoll {
172
constructor(endPoint: string);
173
174
poll(): void;
175
send(body: any): void;
176
close(code?: any, reason?: any): void;
177
}
178
```
179
180
[Transport and Utilities](./utilities.md)
181
182
## Core Types
183
184
```typescript { .api }
185
interface SocketConnectOption {
186
binaryType: BinaryType;
187
params: object | (() => object);
188
transport: new(endpoint: string) => object;
189
timeout: number;
190
heartbeatIntervalMs: number;
191
longPollFallbackMs: number;
192
longpollerTimeout: number;
193
encode: (payload: object, callback: (encoded: any) => void | Promise<void>) => void;
194
decode: (payload: string, callback: (decoded: any) => void | Promise<void>) => void;
195
logger: (kind: string, message: string, data: any) => void;
196
reconnectAfterMs: (tries: number) => number;
197
rejoinAfterMs: (tries: number) => number;
198
vsn: string;
199
debug: boolean;
200
sessionStorage: object;
201
}
202
203
interface PresenceOpts {
204
events?: { state: string; diff: string } | undefined;
205
}
206
207
type BinaryType = "arraybuffer" | "blob";
208
```