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
```