@supabase/realtime-js 2.13.0 → 2.15.0-next.1

package/src/RealtimeChannel.ts

@@ -1,4 +1,8 @@
-import { CHANNEL_EVENTS, CHANNEL_STATES } from './lib/constants'
+import {
+  CHANNEL_EVENTS,
+  CHANNEL_STATES,
+  MAX_PUSH_BUFFER_SIZE,
+} from './lib/constants'
 import Push from './lib/push'
 import type RealtimeClient from './RealtimeClient'
 import Timer from './lib/timer'
@@ -213,8 +217,7 @@ export default class RealtimeChannel {
 
     this.presence = new RealtimePresence(this)
 
-    this.broadcastEndpointURL =
-      httpEndpointURL(this.socket.endPoint) + '/api/broadcast'
+    this.broadcastEndpointURL = httpEndpointURL(this.socket.endPoint)
     this.private = this.params.config.private || false
   }
 
@@ -571,8 +574,11 @@ export default class RealtimeChannel {
    */
   teardown() {
     this.pushBuffer.forEach((push: Push) => push.destroy())
-    this.rejoinTimer && clearTimeout(this.rejoinTimer.timer)
+    this.pushBuffer = []
+    this.rejoinTimer.reset()
     this.joinPush.destroy()
+    this.state = CHANNEL_STATES.closed
+    this.bindings = {}
   }
 
   /** @internal */
@@ -608,13 +614,31 @@ export default class RealtimeChannel {
     if (this._canPush()) {
       pushEvent.send()
     } else {
-      pushEvent.startTimeout()
-      this.pushBuffer.push(pushEvent)
+      this._addToPushBuffer(pushEvent)
     }
 
     return pushEvent
   }
 
+  /** @internal */
+  _addToPushBuffer(pushEvent: Push) {
+    pushEvent.startTimeout()
+    this.pushBuffer.push(pushEvent)
+
+    // Enforce buffer size limit
+    if (this.pushBuffer.length > MAX_PUSH_BUFFER_SIZE) {
+      const removedPush = this.pushBuffer.shift()
+      if (removedPush) {
+        removedPush.destroy()
+        this.socket.log(
+          'channel',
+          `discarded push due to buffer overflow: ${removedPush.event}`,
+          removedPush.payload
+        )
+      }
+    }
+  }
+
   /**
    * Overridable message hook
    *
@@ -757,12 +781,14 @@ export default class RealtimeChannel {
   _off(type: string, filter: { [key: string]: any }) {
     const typeLower = type.toLocaleLowerCase()
 
-    this.bindings[typeLower] = this.bindings[typeLower].filter((bind) => {
-      return !(
-        bind.type?.toLocaleLowerCase() === typeLower &&
-        RealtimeChannel.isEqual(bind.filter, filter)
-      )
-    })
+    if (this.bindings[typeLower]) {
+      this.bindings[typeLower] = this.bindings[typeLower].filter((bind) => {
+        return !(
+          bind.type?.toLocaleLowerCase() === typeLower &&
+          RealtimeChannel.isEqual(bind.filter, filter)
+        )
+      })
+    }
     return this
   }
 

package/src/RealtimeClient.ts

@@ -1,4 +1,4 @@
-import { WebSocket } from 'isows'
+import WebSocketFactory, { WebSocketLike } from './lib/websocket-factory'
 
 import {
   CHANNEL_EVENTS,
@@ -69,8 +69,6 @@ export interface WebSocketLikeConstructor {
   ): WebSocketLike
 }
 
-export type WebSocketLike = WebSocket
-
 export interface WebSocketLikeError {
   error: any
   message: string
@@ -199,15 +197,37 @@ export default class RealtimeClient {
     this._setAuthSafely('connect')
 
     // Establish WebSocket connection
-    if (!this.transport) {
-      this.transport = WebSocket
-    }
-    if (!this.transport) {
-      this._setConnectionState('disconnected')
-      throw new Error('No transport provided')
+    if (this.transport) {
+      // Use custom transport if provided
+      this.conn = new this.transport(this.endpointURL()) as WebSocketLike
+    } else {
+      // Try to use native WebSocket
+      try {
+        this.conn = WebSocketFactory.createWebSocket(this.endpointURL())
+      } catch (error) {
+        this._setConnectionState('disconnected')
+        const errorMessage = (error as Error).message
+
+        // Provide helpful error message based on environment
+        if (errorMessage.includes('Node.js')) {
+          throw new Error(
+            `${errorMessage}\n\n` +
+              'To use Realtime in Node.js, you need to provide a WebSocket implementation:\n\n' +
+              'Option 1: Use Node.js 22+ which has native WebSocket support\n' +
+              'Option 2: Install and provide the "ws" package:\n\n' +
+              '  npm install ws\n\n' +
+              '  import ws from "ws"\n' +
+              '  const client = new RealtimeClient(url, {\n' +
+              '    ...options,\n' +
+              '    transport: ws\n' +
+              '  })' +
+              'Option 3: Use the auto export which handles WebSocket automatically:\n' +
+              '  import { RealtimeClient } from "@supabase/realtime-js/auto"'
+          )
+        }
+        throw new Error(`WebSocket not available: ${errorMessage}`)
+      }
     }
-
-    this.conn = new this.transport!(this.endpointURL()) as WebSocketLike
     this._setupConnectionHandlers()
   }
 
@@ -462,10 +482,16 @@ export default class RealtimeClient {
     if (customFetch) {
       _fetch = customFetch
     } else if (typeof fetch === 'undefined') {
+      // Node.js environment without native fetch
       _fetch = (...args) =>
-        import('@supabase/node-fetch' as any).then(({ default: fetch }) =>
-          fetch(...args)
-        )
+        import('@supabase/node-fetch' as any)
+          .then(({ default: fetch }) => fetch(...args))
+          .catch((error) => {
+            throw new Error(
+              `Failed to load @supabase/node-fetch: ${error.message}. ` +
+                `This is required for HTTP requests in Node.js environments without native fetch.`
+            )
+          })
     } else {
       _fetch = fetch
     }
@@ -577,7 +603,11 @@ export default class RealtimeClient {
   private _setupConnectionHandlers(): void {
     if (!this.conn) return
 
-    this.conn.binaryType = 'arraybuffer'
+    // Set binary type if supported (browsers and most WebSocket implementations)
+    if ('binaryType' in this.conn) {
+      ;(this.conn as any).binaryType = 'arraybuffer'
+    }
+
     this.conn.onopen = () => this._onConnOpen()
     this.conn.onerror = (error: Event) => this._onConnError(error)
     this.conn.onmessage = (event: any) => this._onConnMessage(event)

package/src/index.auto.ts

@@ -0,0 +1,14 @@
+// TODO(@mandarini): Remove this file in v3.0.0 - also update package.json exports
+/**
+ * @deprecated This auto-detection export will be removed in v3.0.0
+ * Use the main export with explicit transport instead:
+ *
+ * import { RealtimeClient } from "@supabase/realtime-js"
+ * import ws from "ws"
+ * const client = new RealtimeClient(url, { transport: ws })
+ */
+
+export * from './index'
+
+// Override WebSocket factory with auto-detection version
+export { default as WebSocketFactory } from './lib/websocket-factory-auto'

package/src/index.ts

@@ -22,6 +22,7 @@ import RealtimePresence, {
   RealtimePresenceLeavePayload,
   REALTIME_PRESENCE_LISTEN_EVENTS,
 } from './RealtimePresence'
+import WebSocketFactory, { WebSocketLike } from './lib/websocket-factory'
 
 export {
   RealtimePresence,
@@ -45,4 +46,6 @@ export {
   REALTIME_PRESENCE_LISTEN_EVENTS,
   REALTIME_SUBSCRIBE_STATES,
   REALTIME_CHANNEL_STATES,
+  WebSocketFactory,
+  WebSocketLike,
 }

package/src/lib/constants.ts

@@ -8,6 +8,7 @@ export const VERSION = version
 export const DEFAULT_TIMEOUT = 10000
 
 export const WS_CLOSE_NORMAL = 1000
+export const MAX_PUSH_BUFFER_SIZE = 100
 
 export enum SOCKET_STATES {
   connecting = 0,

package/src/lib/timer.ts

@@ -22,6 +22,7 @@ export default class Timer {
   reset() {
     this.tries = 0
     clearTimeout(this.timer)
+    this.timer = undefined
   }
 
   // Cancels any previous scheduleTimeout and schedules callback

package/src/lib/transformers.ts

@@ -250,5 +250,5 @@ export const httpEndpointURL = (socketUrl: string): string => {
   let url = socketUrl
   url = url.replace(/^ws/i, 'http')
   url = url.replace(/(\/socket\/websocket|\/socket|\/websocket)\/?$/i, '')
-  return url.replace(/\/+$/, '')
+  return url.replace(/\/+$/, '') + '/api/broadcast'
 }

package/src/lib/version.ts

@@ -1 +1 @@
-export const version = '2.13.0'
+export const version = '2.15.0-next.1'

package/src/lib/websocket-factory-auto.ts

@@ -0,0 +1,72 @@
+// TODO(@mandarini): Remove this file in v3.0.0 - also update package.json exports
+
+import { WebSocketFactory } from './websocket-factory'
+
+/**
+ * WebSocketFactoryAuto extends WebSocketFactory with automatic WebSocket detection.
+ *
+ * @deprecated This class will be removed in v3.0.0. The main export will require
+ * explicit WebSocket transport for Node.js < 22 environments.
+ */
+export class WebSocketFactoryAuto extends WebSocketFactory {
+  // Static flag to track if warning has been shown
+  private static hasShownDeprecationWarning = false
+
+  /**
+   * Dynamic require for 'ws' package
+   * @private
+   */
+  private static dynamicRequire(moduleId: string): any {
+    try {
+      if (typeof require !== 'undefined') {
+        return require(moduleId)
+      }
+      return null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Show deprecation warning once per process
+   * @private
+   */
+  private static showDeprecationWarning() {
+    if (!this.hasShownDeprecationWarning) {
+      this.hasShownDeprecationWarning = true
+      console.warn(
+        '[DEPRECATED] @supabase/realtime-js/auto will be removed in v3.0.0. ' +
+          'Use explicit transport instead: ' +
+          'https://supabase.com/docs/guides/realtime/js-client#nodejs-support'
+      )
+    }
+  }
+
+  /**
+   * Override getWebSocketConstructor to add dynamic 'ws' loading for Node.js
+   */
+  public static getWebSocketConstructor(): typeof WebSocket {
+    try {
+      // First try the base class (handles browser, Node.js 22+, edge cases, etc.)
+      return super.getWebSocketConstructor()
+    } catch (error) {
+      // If base class fails and we're in Node.js, try dynamic 'ws' import
+      if (
+        typeof process !== 'undefined' &&
+        process.versions &&
+        process.versions.node
+      ) {
+        try {
+          const ws = this.dynamicRequire('ws')
+          if (ws) {
+            return ws.WebSocket ?? ws
+          }
+        } catch {}
+      }
+      // Re-throw original error if dynamic import fails
+      throw error
+    }
+  }
+}
+
+export default WebSocketFactoryAuto

package/src/lib/websocket-factory.ts

@@ -0,0 +1,155 @@
+export interface WebSocketLike {
+  readonly CONNECTING: number
+  readonly OPEN: number
+  readonly CLOSING: number
+  readonly CLOSED: number
+  readonly readyState: number
+  readonly url: string
+  readonly protocol: string
+
+  close(code?: number, reason?: string): void
+  send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void
+
+  onopen: ((this: any, ev: Event) => any) | null
+  onmessage: ((this: any, ev: MessageEvent) => any) | null
+  onclose: ((this: any, ev: CloseEvent) => any) | null
+  onerror: ((this: any, ev: Event) => any) | null
+
+  addEventListener(type: string, listener: EventListener): void
+  removeEventListener(type: string, listener: EventListener): void
+
+  // Add additional properties that may exist on WebSocket implementations
+  binaryType?: string
+  bufferedAmount?: number
+  extensions?: string
+  dispatchEvent?: (event: Event) => boolean
+}
+
+export interface WebSocketEnvironment {
+  type: 'native' | 'ws' | 'cloudflare' | 'unsupported'
+  constructor?: any
+  error?: string
+  workaround?: string
+}
+
+export class WebSocketFactory {
+  private static detectEnvironment(): WebSocketEnvironment {
+    if (typeof WebSocket !== 'undefined') {
+      return { type: 'native', constructor: WebSocket }
+    }
+
+    if (
+      typeof globalThis !== 'undefined' &&
+      typeof (globalThis as any).WebSocket !== 'undefined'
+    ) {
+      return { type: 'native', constructor: (globalThis as any).WebSocket }
+    }
+
+    if (
+      typeof global !== 'undefined' &&
+      typeof (global as any).WebSocket !== 'undefined'
+    ) {
+      return { type: 'native', constructor: (global as any).WebSocket }
+    }
+
+    if (
+      typeof globalThis !== 'undefined' &&
+      typeof (globalThis as any).WebSocketPair !== 'undefined' &&
+      typeof globalThis.WebSocket === 'undefined'
+    ) {
+      return {
+        type: 'cloudflare',
+        error:
+          'Cloudflare Workers detected. WebSocket clients are not supported in Cloudflare Workers.',
+        workaround:
+          'Use Cloudflare Workers WebSocket API for server-side WebSocket handling, or deploy to a different runtime.',
+      }
+    }
+
+    if (
+      (typeof globalThis !== 'undefined' && (globalThis as any).EdgeRuntime) ||
+      (typeof navigator !== 'undefined' &&
+        navigator.userAgent?.includes('Vercel-Edge'))
+    ) {
+      return {
+        type: 'unsupported',
+        error:
+          'Edge runtime detected (Vercel Edge/Netlify Edge). WebSockets are not supported in edge functions.',
+        workaround:
+          'Use serverless functions or a different deployment target for WebSocket functionality.',
+      }
+    }
+
+    if (
+      typeof process !== 'undefined' &&
+      process.versions &&
+      process.versions.node
+    ) {
+      const nodeVersion = parseInt(process.versions.node.split('.')[0])
+
+      // Node.js 22+ should have native WebSocket
+      if (nodeVersion >= 22) {
+        // Check if native WebSocket is available (should be in Node.js 22+)
+        if (typeof globalThis.WebSocket !== 'undefined') {
+          return { type: 'native', constructor: globalThis.WebSocket }
+        }
+        // If not available, user needs to provide it
+        return {
+          type: 'unsupported',
+          error: `Node.js ${nodeVersion} detected but native WebSocket not found.`,
+          workaround:
+            'Provide a WebSocket implementation via the transport option.',
+        }
+      }
+
+      // Node.js < 22 doesn't have native WebSocket
+      return {
+        type: 'unsupported',
+        error: `Node.js ${nodeVersion} detected without native WebSocket support.`,
+        workaround:
+          'For Node.js < 22, install "ws" package and provide it via the transport option:\n' +
+          'import ws from "ws"\n' +
+          'new RealtimeClient(url, { transport: ws })',
+      }
+    }
+
+    return {
+      type: 'unsupported',
+      error: 'Unknown JavaScript runtime without WebSocket support.',
+      workaround:
+        "Ensure you're running in a supported environment (browser, Node.js, Deno) or provide a custom WebSocket implementation.",
+    }
+  }
+
+  public static getWebSocketConstructor(): typeof WebSocket {
+    const env = this.detectEnvironment()
+    if (env.constructor) {
+      return env.constructor
+    }
+    let errorMessage =
+      env.error || 'WebSocket not supported in this environment.'
+    if (env.workaround) {
+      errorMessage += `\n\nSuggested solution: ${env.workaround}`
+    }
+    throw new Error(errorMessage)
+  }
+
+  public static createWebSocket(
+    url: string | URL,
+    protocols?: string | string[]
+  ): WebSocketLike {
+    const WS = this.getWebSocketConstructor()
+    return new WS(url, protocols)
+  }
+
+  public static isWebSocketSupported(): boolean {
+    try {
+      const env = this.detectEnvironment()
+      return env.type === 'native' || env.type === 'ws'
+    } catch {
+      return false
+    }
+  }
+}
+
+export default WebSocketFactory