tessl/npm-types--phoenix

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Phoenix JavaScript Client Types

Name: tessl/npm-types--phoenix
Author: tessl

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";