@supabase/realtime-js 2.100.0-rc.0 → 2.100.0

package/src/RealtimeChannel.ts

@@ -210,7 +210,9 @@ export default class RealtimeChannel {
    * The topic determines which realtime stream you are subscribing to. Config options let you
    * enable acknowledgement for broadcasts, presence tracking, or private channels.
    *
-   * @example
+   * @category Realtime
+   *
+   * @example Example for a public channel
    * ```ts
    * import RealtimeClient from '@supabase/realtime-js'
    *
@@ -253,7 +255,10 @@ export default class RealtimeChannel {
     }
   }
 
-  /** Subscribe registers your client with the server */
+  /**
+   * Subscribe registers your client with the server
+   * @category Realtime
+   */
   subscribe(
     callback?: (status: REALTIME_SUBSCRIBE_STATES, err?: Error) => void,
     timeout = this.timeout
@@ -372,6 +377,8 @@ export default class RealtimeChannel {
    *
    * The shape is a map keyed by presence key (for example a user id) where each entry contains the
    * tracked metadata for that user.
+   *
+   * @category Realtime
    */
   presenceState<T extends { [key: string]: any } = {}>(): RealtimePresenceState<T> {
     return this.presence.state as RealtimePresenceState<T>
@@ -380,6 +387,8 @@ export default class RealtimeChannel {
   /**
    * Sends the supplied payload to the presence tracker so other subscribers can see that this
    * client is online. Use `untrack` to stop broadcasting presence for the same key.
+   *
+   * @category Realtime
    */
   async track(
     payload: { [key: string]: any },
@@ -397,6 +406,8 @@ export default class RealtimeChannel {
 
   /**
    * Removes the current presence state for this client.
+   *
+   * @category Realtime
    */
   async untrack(opts: { [key: string]: any } = {}): Promise<RealtimeChannelSendResponse> {
     return await this.send(
@@ -529,6 +540,165 @@ export default class RealtimeChannel {
     filter: {},
     callback: (payload: any) => void
   ): RealtimeChannel
+  /**
+   * Listen to realtime events on this channel.
+   * @category Realtime
+   *
+   * @remarks
+   * - By default, Broadcast and Presence are enabled for all projects.
+   * - By default, listening to database changes is disabled for new projects due to database performance and security concerns. You can turn it on by managing Realtime's [replication](/docs/guides/api#realtime-api-overview).
+   * - You can receive the "previous" data for updates and deletes by setting the table's `REPLICA IDENTITY` to `FULL` (e.g., `ALTER TABLE your_table REPLICA IDENTITY FULL;`).
+   * - Row level security is not applied to delete statements. When RLS is enabled and replica identity is set to full, only the primary key is sent to clients.
+   *
+   * @example Listen to broadcast messages
+   * ```js
+   * const channel = supabase.channel("room1")
+   *
+   * channel.on("broadcast", { event: "cursor-pos" }, (payload) => {
+   *   console.log("Cursor position received!", payload);
+   * }).subscribe((status) => {
+   *   if (status === "SUBSCRIBED") {
+   *     channel.send({
+   *       type: "broadcast",
+   *       event: "cursor-pos",
+   *       payload: { x: Math.random(), y: Math.random() },
+   *     });
+   *   }
+   * });
+   * ```
+   *
+   * @example Listen to presence sync
+   * ```js
+   * const channel = supabase.channel('room1')
+   * channel
+   *   .on('presence', { event: 'sync' }, () => {
+   *     console.log('Synced presence state: ', channel.presenceState())
+   *   })
+   *   .subscribe(async (status) => {
+   *     if (status === 'SUBSCRIBED') {
+   *       await channel.track({ online_at: new Date().toISOString() })
+   *     }
+   *   })
+   * ```
+   *
+   * @example Listen to presence join
+   * ```js
+   * const channel = supabase.channel('room1')
+   * channel
+   *   .on('presence', { event: 'join' }, ({ newPresences }) => {
+   *     console.log('Newly joined presences: ', newPresences)
+   *   })
+   *   .subscribe(async (status) => {
+   *     if (status === 'SUBSCRIBED') {
+   *       await channel.track({ online_at: new Date().toISOString() })
+   *     }
+   *   })
+   * ```
+   *
+   * @example Listen to presence leave
+   * ```js
+   * const channel = supabase.channel('room1')
+   * channel
+   *   .on('presence', { event: 'leave' }, ({ leftPresences }) => {
+   *     console.log('Newly left presences: ', leftPresences)
+   *   })
+   *   .subscribe(async (status) => {
+   *     if (status === 'SUBSCRIBED') {
+   *       await channel.track({ online_at: new Date().toISOString() })
+   *       await channel.untrack()
+   *     }
+   *   })
+   * ```
+   *
+   * @example Listen to all database changes
+   * ```js
+   * supabase
+   *   .channel('room1')
+   *   .on('postgres_changes', { event: '*', schema: '*' }, payload => {
+   *     console.log('Change received!', payload)
+   *   })
+   *   .subscribe()
+   * ```
+   *
+   * @example Listen to a specific table
+   * ```js
+   * supabase
+   *   .channel('room1')
+   *   .on('postgres_changes', { event: '*', schema: 'public', table: 'countries' }, payload => {
+   *     console.log('Change received!', payload)
+   *   })
+   *   .subscribe()
+   * ```
+   *
+   * @example Listen to inserts
+   * ```js
+   * supabase
+   *   .channel('room1')
+   *   .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, payload => {
+   *     console.log('Change received!', payload)
+   *   })
+   *   .subscribe()
+   * ```
+   *
+   * @exampleDescription Listen to updates
+   * By default, Supabase will send only the updated record. If you want to receive the previous values as well you can
+   * enable full replication for the table you are listening to:
+   *
+   * ```sql
+   * alter table "your_table" replica identity full;
+   * ```
+   *
+   * @example Listen to updates
+   * ```js
+   * supabase
+   *   .channel('room1')
+   *   .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries' }, payload => {
+   *     console.log('Change received!', payload)
+   *   })
+   *   .subscribe()
+   * ```
+   *
+   * @exampleDescription Listen to deletes
+   * By default, Supabase does not send deleted records. If you want to receive the deleted record you can
+   * enable full replication for the table you are listening to:
+   *
+   * ```sql
+   * alter table "your_table" replica identity full;
+   * ```
+   *
+   * @example Listen to deletes
+   * ```js
+   * supabase
+   *   .channel('room1')
+   *   .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, payload => {
+   *     console.log('Change received!', payload)
+   *   })
+   *   .subscribe()
+   * ```
+   *
+   * @exampleDescription Listen to multiple events
+   * You can chain listeners if you want to listen to multiple events for each table.
+   *
+   * @example Listen to multiple events
+   * ```js
+   * supabase
+   *   .channel('room1')
+   *   .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, handleRecordInserted)
+   *   .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, handleRecordDeleted)
+   *   .subscribe()
+   * ```
+   *
+   * @exampleDescription Listen to row level changes
+   * You can listen to individual rows using the format `{table}:{col}=eq.{val}` - where `{col}` is the column name, and `{val}` is the value which you want to match.
+   *
+   * @example Listen to row level changes
+   * ```js
+   * supabase
+   *   .channel('room1')
+   *   .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries', filter: 'id=eq.200' }, handleRecordUpdated)
+   *   .subscribe()
+   * ```
+   */
   on(
     type: `${REALTIME_LISTEN_TYPES}`,
     filter: { event: string; [key: string]: string },
@@ -550,6 +720,8 @@ export default class RealtimeChannel {
    * @param payload Payload to be sent (required)
    * @param opts Options including timeout
    * @returns Promise resolving to object with success status, and error details if failed
+   *
+   * @category Realtime
    */
   async httpSend(
     event: string,
@@ -611,6 +783,39 @@ export default class RealtimeChannel {
    * @param args.event The name of the event being sent
    * @param args.payload Payload to be sent
    * @param opts Options to be used during the send process
+   *
+   * @category Realtime
+   *
+   * @remarks
+   * - When using REST you don't need to subscribe to the channel
+   * - REST calls are only available from 2.37.0 onwards
+   *
+   * @example Send a message via websocket
+   * ```js
+   * const channel = supabase.channel('room1')
+   *
+   * channel.subscribe((status) => {
+   *   if (status === 'SUBSCRIBED') {
+   *     channel.send({
+   *       type: 'broadcast',
+   *       event: 'cursor-pos',
+   *       payload: { x: Math.random(), y: Math.random() },
+   *     })
+   *   }
+   * })
+   * ```
+   *
+   * @exampleResponse Send a message via websocket
+   * ```js
+   * ok | timed out | error
+   * ```
+   *
+   * @example Send a message via REST
+   * ```js
+   * supabase
+   *   .channel('room1')
+   *   .httpSend('cursor-pos', { x: Math.random(), y: Math.random() })
+   * ```
    */
   async send(
     args: {
@@ -687,6 +892,8 @@ export default class RealtimeChannel {
   /**
    * Updates the payload that will be sent the next time the channel joins (reconnects).
    * Useful for rotating access tokens or updating config without re-creating the channel.
+   *
+   * @category Realtime
    */
   updateJoinPayload(payload: Record<string, any>) {
     this.channelAdapter.updateJoinPayload(payload)
@@ -700,6 +907,8 @@ export default class RealtimeChannel {
    *
    * To receive leave acknowledgements, use the a `receive` hook to bind to the server ack, ie:
    * channel.unsubscribe().receive("ok", () => alert("left!") )
+   *
+   * @category Realtime
    */
   async unsubscribe(timeout = this.timeout) {
     return new Promise<RealtimeChannelSendResponse>((resolve) => {
@@ -713,6 +922,8 @@ export default class RealtimeChannel {
 
   /**
    * Destroys and stops related timers.
+   *
+   * @category Realtime
    */
   teardown() {
     this.channelAdapter.teardown()

package/src/RealtimeClient.ts

@@ -15,14 +15,7 @@ import { httpEndpointURL } from './lib/transformers'
 import RealtimeChannel from './RealtimeChannel'
 import type { RealtimeChannelOptions } from './RealtimeChannel'
 import SocketAdapter from './phoenix/socketAdapter'
-import type {
-  Message,
-  SocketOptions,
-  HeartbeatCallback,
-  Encode,
-  Decode,
-  Vsn,
-} from './phoenix/types'
+import type { Message, SocketOptions, HeartbeatCallback, Encode, Decode } from './phoenix/types'
 
 type Fetch = typeof fetch
 
@@ -65,7 +58,7 @@ export type RealtimeClientOptions = {
   timeout?: number
   heartbeatIntervalMs?: number
   heartbeatCallback?: (status: HeartbeatStatus, latency?: number) => void
-  vsn?: Vsn
+  vsn?: string
   logger?: (kind: string, msg: string, data?: any) => void
   encode?: Encode<void>
   decode?: Decode<void>
@@ -204,7 +197,10 @@ export default class RealtimeClient {
    * @param options.worker Use Web Worker to set a side flow. Defaults to false.
    * @param options.workerUrl The URL of the worker script. Defaults to https://realtime.supabase.com/worker.js that includes a heartbeat event call to keep the connection alive.
    * @param options.vsn The protocol version to use when connecting. Supported versions are "1.0.0" and "2.0.0". Defaults to "2.0.0".
-   * @example
+   *
+   * @category Realtime
+   *
+   * @example Example for a public channel
    * ```ts
    * import RealtimeClient from '@supabase/realtime-js'
    *
@@ -231,6 +227,8 @@ export default class RealtimeClient {
 
   /**
    * Connects the socket, unless already connected.
+   *
+   * @category Realtime
    */
   connect(): void {
     // Skip if already connecting, disconnecting, or connected
@@ -276,6 +274,8 @@ export default class RealtimeClient {
   /**
    * Returns the URL of the websocket.
    * @returns string The URL of the websocket.
+   *
+   * @category Realtime
    */
   endpointURL(): string {
     return this.socketAdapter.endPointURL()
@@ -286,6 +286,8 @@ export default class RealtimeClient {
    *
    * @param code A numeric status code to send on disconnect.
    * @param reason A custom reason for the disconnect.
+   *
+   * @category Realtime
    */
   async disconnect(code?: number, reason?: string) {
     if (this.isDisconnecting()) {
@@ -303,6 +305,8 @@ export default class RealtimeClient {
 
   /**
    * Returns all created channels
+   *
+   * @category Realtime
    */
   getChannels(): RealtimeChannel[] {
     return this.channels
@@ -311,6 +315,8 @@ export default class RealtimeClient {
   /**
    * Unsubscribes, removes and tears down a single channel
    * @param channel A RealtimeChannel instance
+   *
+   * @category Realtime
    */
   async removeChannel(channel: RealtimeChannel): Promise<RealtimeRemoveChannelResponse> {
     const status = await channel.unsubscribe()
@@ -328,6 +334,8 @@ export default class RealtimeClient {
 
   /**
    * Unsubscribes, removes and tears down all channels
+   *
+   * @category Realtime
    */
   async removeAllChannels(): Promise<RealtimeRemoveChannelResponse[]> {
     const promises = this.channels.map(async (channel) => {
@@ -345,6 +353,8 @@ export default class RealtimeClient {
    * Logs the message.
    *
    * For customized logging, `this.logger` can be overridden in Client constructor.
+   *
+   * @category Realtime
    */
   log(kind: string, msg: string, data?: any) {
     this.socketAdapter.log(kind, msg, data)
@@ -352,6 +362,8 @@ export default class RealtimeClient {
 
   /**
    * Returns the current state of the socket.
+   *
+   * @category Realtime
    */
   connectionState() {
     return this.socketAdapter.connectionState() || CONNECTION_STATE.closed
@@ -359,6 +371,8 @@ export default class RealtimeClient {
 
   /**
    * Returns `true` is the connection is open.
+   *
+   * @category Realtime
    */
   isConnected(): boolean {
     return this.socketAdapter.isConnected()
@@ -366,6 +380,8 @@ export default class RealtimeClient {
 
   /**
    * Returns `true` if the connection is currently connecting.
+   *
+   * @category Realtime
    */
   isConnecting(): boolean {
     return this.socketAdapter.isConnecting()
@@ -373,6 +389,8 @@ export default class RealtimeClient {
 
   /**
    * Returns `true` if the connection is currently disconnecting.
+   *
+   * @category Realtime
    */
   isDisconnecting(): boolean {
     return this.socketAdapter.isDisconnecting()
@@ -384,6 +402,8 @@ export default class RealtimeClient {
    * Topics are automatically prefixed with `realtime:` to match the Realtime service.
    * If a channel with the same topic already exists it will be returned instead of creating
    * a duplicate connection.
+   *
+   * @category Realtime
    */
   channel(topic: string, params: RealtimeChannelOptions = { config: {} }): RealtimeChannel {
     const realtimeTopic = `realtime:${topic}`
@@ -403,6 +423,8 @@ export default class RealtimeClient {
    * Push out a message if the socket is connected.
    *
    * If the socket is not connected, the message gets enqueued within a local buffer, and sent out when a connection is next established.
+   *
+   * @category Realtime
    */
   push(data: RealtimeMessage): void {
     this.socketAdapter.push(data)
@@ -427,6 +449,8 @@ export default class RealtimeClient {
    *
    * // Switch back to using the accessToken callback
    * client.realtime.setAuth()
+   *
+   * @category Realtime
    */
   async setAuth(token: string | null = null): Promise<void> {
     this._authPromise = this._performAuth(token)
@@ -448,6 +472,8 @@ export default class RealtimeClient {
 
   /**
    * Sends a heartbeat message if the socket is connected.
+   *
+   * @category Realtime
    */
   async sendHeartbeat() {
     this.socketAdapter.sendHeartbeat()
@@ -456,6 +482,8 @@ export default class RealtimeClient {
   /**
    * Sets a callback that receives lifecycle events for internal heartbeat messages.
    * Useful for instrumenting connection health (e.g. sent/ok/timeout/disconnected).
+   *
+   * @category Realtime
    */
   onHeartbeat(callback: HeartbeatCallback) {
     this.socketAdapter.heartbeatCallback = this._wrapHeartbeatCallback(callback)
@@ -672,7 +700,7 @@ export default class RealtimeClient {
     result.timeout = options?.timeout ?? DEFAULT_TIMEOUT
     result.heartbeatIntervalMs =
       options?.heartbeatIntervalMs ?? CONNECTION_TIMEOUTS.HEARTBEAT_INTERVAL
-    result.vsn = options?.vsn ?? DEFAULT_VSN
+
     // @ts-ignore - mismatch between phoenix and supabase
     result.transport = options?.transport ?? WebSocketFactory.getWebSocketConstructor()
     result.params = options?.params
@@ -687,7 +715,9 @@ export default class RealtimeClient {
     let defaultEncode: Encode<void>
     let defaultDecode: Decode<void>
 
-    switch (result.vsn) {
+    const vsn = options?.vsn ?? DEFAULT_VSN
+
+    switch (vsn) {
       case VSN_1_0_0:
         defaultEncode = (payload, callback) => {
           return callback(JSON.stringify(payload))
@@ -704,6 +734,7 @@ export default class RealtimeClient {
         throw new Error(`Unsupported serializer version: ${result.vsn}`)
     }
 
+    result.vsn = vsn
     result.encode = options?.encode ?? defaultEncode
     result.decode = options?.decode ?? defaultDecode
 

package/src/RealtimePresence.ts

@@ -51,7 +51,9 @@ export default class RealtimePresence {
    * @param channel - The realtime channel to bind to.
    * @param opts - Optional custom event names, e.g. `{ events: { state: 'state', diff: 'diff' } }`.
    *
-   * @example
+   * @category Realtime
+   *
+   * @example Example for a presence channel
    * ```ts
    * const presence = new RealtimePresence(channel)
    *

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.100.0-rc.0'
+export const version = '2.100.0'

package/src/lib/websocket-factory.ts

@@ -138,10 +138,16 @@ export class WebSocketFactory {
   /**
    * Returns the best available WebSocket constructor for the current runtime.
    *
-   * @example
+   * @category Realtime
+   *
+   * @example Example with error handling
    * ```ts
-   * const WS = WebSocketFactory.getWebSocketConstructor()
-   * const socket = new WS('wss://realtime.supabase.co/socket')
+   * try {
+   *   const WS = WebSocketFactory.getWebSocketConstructor()
+   *   const socket = new WS('wss://example.com/socket')
+   * } catch (error) {
+   *   console.error('WebSocket not available in this environment.', error)
+   * }
    * ```
    */
   public static getWebSocketConstructor(): typeof WebSocket {
@@ -159,10 +165,13 @@ export class WebSocketFactory {
   /**
    * Detects whether the runtime can establish WebSocket connections.
    *
-   * @example
+   * @category Realtime
+   *
+   * @example Example in a Node.js script
    * ```ts
    * if (!WebSocketFactory.isWebSocketSupported()) {
-   *   console.warn('Falling back to long polling')
+   *   console.error('WebSockets are required for this script.')
+   *   process.exitCode = 1
    * }
    * ```
    */