tessl/npm-pusher-js

Pusher Channels JavaScript library for browsers, React Native, NodeJS and web workers

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Client Management

Name: tessl/npm-pusher-js
Author: tessl

Core Pusher client functionality for establishing connections, managing global events, and controlling the overall WebSocket connection lifecycle.

Capabilities

Pusher Client Class

Main client class for managing connections to Pusher Channels.

/**
 * Main Pusher client class for real-time communication
 * @param app_key - Your Pusher application key
 * @param options - Configuration options for the client
 */
class Pusher {
  constructor(app_key: string, options: Options);
  
  // Connection Management
  connect(): void;
  disconnect(): void;
  
  // Event Binding
  bind(event_name: string, callback: Function, context?: any): Pusher;
  unbind(event_name?: string, callback?: Function, context?: any): Pusher;
  bind_global(callback: Function): Pusher;
  unbind_global(callback?: Function): Pusher;
  unbind_all(callback?: Function): Pusher;
  
  // Channel Management
  subscribe(channel_name: string): Channel;
  unsubscribe(channel_name: string): void;
  subscribeAll(): void;
  channel(name: string): Channel;
  allChannels(): Channel[];
  
  // Client Events
  send_event(event_name: string, data: any, channel?: string): boolean;
  
  // User Authentication
  signin(): void;
  
  // Utilities
  shouldUseTLS(): boolean;
  
  // Static Properties
  static instances: Pusher[];
  static isReady: boolean;
  static logToConsole: boolean;
  static Runtime: AbstractRuntime;
  static ScriptReceivers: any;
  static DependenciesReceivers: any;
  static auth_callbacks: any;
  
  // Static Methods
  static ready(): void;
  static log: (message: any) => void;
  
  // Instance Properties
  key: string;
  channels: Channels;
  global_emitter: EventsDispatcher;
  connection: ConnectionManager;
  user: UserFacade;
  sessionID: number;
  timeline: Timeline;
  timelineSender: TimelineSender;
  timelineSenderTimer: PeriodicTimer;
}

Usage Examples:

import Pusher from "pusher-js";

// Basic initialization
const pusher = new Pusher("your-app-key", {
  cluster: "us2"
});

// Advanced configuration
const pusher = new Pusher("your-app-key", {
  cluster: "us2",
  forceTLS: true,
  enableStats: true,
  activityTimeout: 120000,
  pongTimeout: 30000,
  channelAuthorization: {
    endpoint: "/pusher/auth",
    transport: "ajax"
  }
});

// Manual connection control
pusher.connect();
pusher.disconnect();

Configuration Options

Complete configuration interface for Pusher client initialization.

interface Options {
  // Required
  cluster: string;
  
  // Authentication
  authEndpoint?: string;
  authTransport?: 'ajax' | 'jsonp';
  channelAuthorization?: ChannelAuthorizationOptions;
  userAuthentication?: UserAuthenticationOptions;
  authorizer?: ChannelAuthorizerGenerator;
  auth?: DeprecatedAuthOptions;
  
  // Connection
  forceTLS?: boolean;
  wsHost?: string;
  wsPort?: number;
  wssPort?: number;
  httpHost?: string;
  httpPort?: number;
  httpsPort?: number;
  httpPath?: string;
  wsPath?: string;
  
  // Transport Control
  disabledTransports?: Transport[];
  enabledTransports?: Transport[];
  
  // Timeouts (in milliseconds)
  activityTimeout?: number;
  pongTimeout?: number;
  unavailableTimeout?: number;
  
  // Features
  enableStats?: boolean;
  disableStats?: boolean;
  ignoreNullOrigin?: boolean;
  
  // Advanced
  statsHost?: string;
  timelineParams?: any;
  nacl?: any;
}

Configuration Examples:

// Minimal configuration
const pusher = new Pusher("app-key", { cluster: "us2" });

// Production configuration with authentication
const pusher = new Pusher("app-key", {
  cluster: "eu",
  forceTLS: true,
  channelAuthorization: {
    endpoint: "/pusher/auth",
    headers: {
      "X-CSRF-Token": "csrf-token"
    }
  },
  activityTimeout: 30000,
  pongTimeout: 6000
});

// Custom transport configuration
const pusher = new Pusher("app-key", {
  cluster: "us2",
  enabledTransports: ["ws", "wss"],
  disabledTransports: ["sockjs", "xhr_polling"]
});

Global Event Binding

Bind to connection-level events that occur across all channels.

/**
 * Bind to a global event
 * @param event_name - Name of the event to bind to
 * @param callback - Function to call when event occurs
 * @param context - Optional context for the callback
 * @returns The Pusher instance for chaining
 */
bind(event_name: string, callback: Function, context?: any): Pusher;

/**
 * Unbind from a global event
 * @param event_name - Optional event name (unbinds all if omitted)
 * @param callback - Optional specific callback to unbind
 * @param context - Optional context to match
 * @returns The Pusher instance for chaining
 */
unbind(event_name?: string, callback?: Function, context?: any): Pusher;

/**
 * Bind to all global events
 * @param callback - Function called for every global event
 * @returns The Pusher instance for chaining
 */
bind_global(callback: Function): Pusher;

/**
 * Unbind from all global events
 * @param callback - Optional specific callback to unbind
 * @returns The Pusher instance for chaining
 */
unbind_global(callback?: Function): Pusher;

/**
 * Unbind all global event handlers
 * @param callback - Optional callback (currently unused)
 * @returns The Pusher instance for chaining
 */
unbind_all(callback?: Function): Pusher;

Event Binding Examples:

// Connection events
pusher.bind("connecting", () => {
  console.log("Connecting to Pusher...");
});

pusher.bind("connected", () => {
  console.log("Connected to Pusher");
});

pusher.bind("disconnected", () => {
  console.log("Disconnected from Pusher");
});

pusher.bind("error", (error) => {
  console.error("Pusher error:", error);
});

// Global event listener
pusher.bind_global((event_name, data) => {
  console.log(`Global event: ${event_name}`, data);
});

// Unbinding
pusher.unbind("connected", connectionHandler);
pusher.unbind_all(); // Remove all global bindings

Client Events

Send client-triggered events through the connection.

/**
 * Send a client event
 * @param event_name - Name of the event to send
 * @param data - Data to send with the event
 * @param channel - Optional channel to send event on
 * @returns true if event was sent successfully
 */
send_event(event_name: string, data: any, channel?: string): boolean;

Client Event Examples:

// Send global client event
pusher.send_event("client-message", {
  message: "Hello from client"
});

// Send client event on specific channel
pusher.send_event("client-typing", {
  user: "alice",
  typing: true
}, "chat-room-1");

User Authentication

Manage user authentication for presence channels.

/**
 * Initiate user sign-in for presence channels
 */
signin(): void;

/**
 * Check if the connection should use TLS
 * @returns true if TLS should be used
 */
shouldUseTLS(): boolean;

Static Methods

Class-level utilities and instance management.

/**
 * Mark Pusher as ready and connect all instances
 */
static ready(): void;

/**
 * Logging function for Pusher messages
 */
static log: (message: any) => void;

// Static properties
static instances: Pusher[];      // All Pusher instances
static isReady: boolean;         // Global ready state
static logToConsole: boolean;    // Console logging flag

Static Usage Examples:

// Enable console logging
Pusher.logToConsole = true;

// Custom logging
Pusher.log = (message) => {
  console.log("[Pusher]", message);
};

// Manual ready trigger (usually automatic)
Pusher.ready();

// Access all instances
console.log(`${Pusher.instances.length} Pusher instances`);