or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

channel.mdindex.mdpresence.mdpush.mdsocket.mdutilities.md
tile.json

tessl/npm-types--phoenix

TypeScript definitions for Phoenix JavaScript client library enabling real-time WebSocket communication with Phoenix Framework applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@types/phoenix@1.6.x

To install, run

npx @tessl/cli install tessl/npm-types--phoenix@1.6.0

index.mddocs/

Phoenix JavaScript Client Types

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.

Package Information

  • Package Name: @types/phoenix
  • Package Type: npm (TypeScript definitions)
  • Language: TypeScript
  • Installation: npm install @types/phoenix phoenix

Core Imports

import { Socket, Channel, Push, Presence, Timer } from "phoenix";

For CommonJS:

const { Socket, Channel, Push, Presence, Timer } = require("phoenix");

Basic Usage

import { Socket, Channel, Presence } from "phoenix";

// Create and connect to Phoenix socket
const socket = new Socket("/socket", {
  params: { userToken: "abc123" },
  heartbeatIntervalMs: 30000
});
socket.connect();

// Join a channel and handle messages
const channel = socket.channel("room:lobby", { clientId: "user123" });

channel.on("new_message", (message) => {
  console.log("Received:", message);
});

channel.join()
  .receive("ok", (resp) => console.log("Joined successfully", resp))
  .receive("error", (resp) => console.log("Unable to join", resp));

// Send messages with status handling
channel.push("new_message", { body: "Hello Phoenix!" })
  .receive("ok", (resp) => console.log("Message sent", resp))
  .receive("error", (resp) => console.log("Send failed", resp));

Architecture

Phoenix JavaScript client is built around several key components:

  • Socket: WebSocket connection manager with automatic reconnection, heartbeat, and transport fallbacks
  • Channel: Topic-based message routing with join/leave lifecycle and bidirectional communication
  • Push: Message sending mechanism with status callbacks for delivery confirmation
  • Presence: Real-time user presence tracking with join/leave detection and state synchronization
  • Transport System: Pluggable transport layer supporting WebSocket with Long Poll fallback
  • Connection Management: Automatic reconnection with configurable backoff strategies

Capabilities

WebSocket Connection Management

Core Socket functionality for establishing and managing WebSocket connections to Phoenix applications, including connection lifecycle, authentication, and transport configuration.

class Socket {
  constructor(endPoint: string, opts?: Partial<SocketConnectOption>);

  connect(params?: any): void;
  connectionState(): ConnectionState;
  isConnected(): boolean;

  onOpen(callback: () => void | Promise<void>): MessageRef;
  onClose(callback: (event: CloseEvent) => void | Promise<void>): MessageRef;
  onError(callback: (
    error: Event | string | number,
    transport: new(endpoint: string) => object,
    establishedConnections: number
  ) => void | Promise<void>): MessageRef;
}

type ConnectionState = "connecting" | "open" | "closing" | "closed";
type MessageRef = string;

Socket Connection

Channel Communication

Channel-based messaging system for subscribing to topics and exchanging real-time messages with Phoenix applications, including join/leave lifecycle and event handling.

class Channel {
  constructor(topic: string, params?: object | (() => object), socket?: Socket);

  readonly state: ChannelState;
  readonly topic: string;

  join(timeout?: number): Push;
  leave(timeout?: number): Push;

  on(event: string, callback: (response?: any) => void | Promise<void>): number;
  push(event: string, payload: object, timeout?: number): Push;
}

type ChannelState = "closed" | "errored" | "joined" | "joining" | "leaving";

Channel Communication

Message Push Operations

Push mechanism for sending messages to channels with delivery status tracking and timeout handling, enabling reliable message delivery confirmation.

class Push {
  constructor(channel: Channel, event: string, payload: object, timeout: number);

  send(): void;
  resend(timeout: number): void;
  receive(status: PushStatus, callback: (response?: any) => any): this;
}

type PushStatus = "ok" | "error" | "timeout";

Push Operations

Presence Tracking

Real-time presence tracking system for monitoring user join/leave events and maintaining synchronized presence state across connected clients.

class Presence {
  constructor(channel: Channel, opts?: PresenceOpts);

  onJoin(callback: PresenceOnJoinCallback): void;
  onLeave(callback: PresenceOnLeaveCallback): void;
  list<T = any>(chooser?: (key: string, presence: any) => T): T[];

  static syncState(
    currentState: object,
    newState: object,
    onJoin?: PresenceOnJoinCallback,
    onLeave?: PresenceOnLeaveCallback
  ): any;
}

type PresenceOnJoinCallback = (key?: string, currentPresence?: any, newPresence?: any) => void;
type PresenceOnLeaveCallback = (key?: string, currentPresence?: any, newPresence?: any) => void;

Presence Tracking

Transport and Utilities

Supporting utilities including Timer for reconnection backoff, LongPoll fallback transport, and Ajax helper for HTTP requests when WebSocket is unavailable.

class Timer {
  constructor(callback: () => void | Promise<void>, timerCalc: (tries: number) => number);

  reset(): void;
  scheduleTimeout(): void;
}

class LongPoll {
  constructor(endPoint: string);

  poll(): void;
  send(body: any): void;
  close(code?: any, reason?: any): void;
}

Transport and Utilities

Core Types

interface SocketConnectOption {
  binaryType: BinaryType;
  params: object | (() => object);
  transport: new(endpoint: string) => object;
  timeout: number;
  heartbeatIntervalMs: number;
  longPollFallbackMs: number;
  longpollerTimeout: number;
  encode: (payload: object, callback: (encoded: any) => void | Promise<void>) => void;
  decode: (payload: string, callback: (decoded: any) => void | Promise<void>) => void;
  logger: (kind: string, message: string, data: any) => void;
  reconnectAfterMs: (tries: number) => number;
  rejoinAfterMs: (tries: number) => number;
  vsn: string;
  debug: boolean;
  sessionStorage: object;
}

interface PresenceOpts {
  events?: { state: string; diff: string } | undefined;
}

type BinaryType = "arraybuffer" | "blob";