@supabase/realtime-js 1.7.4 → 1.8.0-next.1

package/src/{RealtimeSubscription.ts → RealtimeChannel.ts}

@@ -2,8 +2,9 @@ import { CHANNEL_EVENTS, CHANNEL_STATES } from './lib/constants'
 import Push from './lib/push'
 import RealtimeClient from './RealtimeClient'
 import Timer from './lib/timer'
+import RealtimePresence from './RealtimePresence'
 
-export default class RealtimeSubscription {
+export default class RealtimeChannel {
   bindings: any[] = []
   timeout: number
   state = CHANNEL_STATES.closed
@@ -11,6 +12,7 @@ export default class RealtimeSubscription {
   joinPush: Push
   rejoinTimer: Timer
   pushBuffer: Push[] = []
+  presence: RealtimePresence
 
   constructor(
     public topic: string,
@@ -56,9 +58,38 @@ export default class RealtimeSubscription {
       this.state = CHANNEL_STATES.errored
       this.rejoinTimer.scheduleTimeout()
     })
-    this.on(CHANNEL_EVENTS.reply, (payload: any, ref: string) => {
+    this.on(CHANNEL_EVENTS.reply, {}, (payload: any, ref: string) => {
       this.trigger(this.replyEventName(ref), payload)
     })
+    this.presence = new RealtimePresence(this)
+  }
+
+  list() {
+    return this.presence.list()
+  }
+
+  async track(
+    payload: { [key: string]: any },
+    opts: { [key: string]: any } = {}
+  ) {
+    return await this.send(
+      {
+        type: 'presence',
+        event: 'track',
+        payload,
+      },
+      opts
+    )
+  }
+
+  async untrack(opts: { [key: string]: any } = {}) {
+    return await this.send(
+      {
+        type: 'presence',
+        event: 'untrack',
+      },
+      opts
+    )
   }
 
   rejoinUntilConnected() {
@@ -72,29 +103,69 @@ export default class RealtimeSubscription {
     if (this.joinedOnce) {
       throw `tried to subscribe multiple times. 'subscribe' can only be called a single time per channel instance`
     } else {
+      const configs = this.bindings.reduce(
+        (acc, binding: { [key: string]: any }) => {
+          const { type } = binding
+          if (
+            ![
+              'phx_close',
+              'phx_error',
+              'phx_reply',
+              'presence_diff',
+              'presence_state',
+            ].includes(type)
+          ) {
+            acc[type] = binding
+          }
+          return acc
+        },
+        {}
+      )
+
+      if (Object.keys(configs).length) {
+        this.updateJoinPayload({ configs })
+      }
+
       this.joinedOnce = true
       this.rejoin(timeout)
       return this.joinPush
     }
   }
 
+  /**
+   * Registers a callback that will be executed when the channel closes.
+   */
   onClose(callback: Function) {
-    this.on(CHANNEL_EVENTS.close, callback)
+    this.on(CHANNEL_EVENTS.close, {}, callback)
   }
 
+  /**
+   * Registers a callback that will be executed when the channel encounteres an error.
+   */
   onError(callback: Function) {
-    this.on(CHANNEL_EVENTS.error, (reason: string) => callback(reason))
+    this.on(CHANNEL_EVENTS.error, {}, (reason: string) => callback(reason))
   }
 
-  on(event: string, callback: Function) {
-    this.bindings.push({ event, callback })
+  on(type: string, filter?: { [key: string]: string }, callback?: Function) {
+    this.bindings.push({
+      type,
+      filter: filter ?? {},
+      callback: callback ?? (() => {}),
+    })
   }
 
-  off(event: string) {
-    this.bindings = this.bindings.filter((bind) => bind.event !== event)
+  off(type: string, filter: { [key: string]: any }) {
+    this.bindings = this.bindings.filter((bind) => {
+      return !(
+        bind.type === type && RealtimeChannel.isEqual(bind.filter, filter)
+      )
+    })
   }
 
-  canPush() {
+  /**
+   * Returns `true` if the socket is connected and the channel has been joined.
+   */
+  canPush(): boolean {
     return this.socket.isConnected() && this.isJoined()
   }
 
@@ -118,7 +189,7 @@ export default class RealtimeSubscription {
   }
 
   /**
-   * Leaves the channel
+   * Leaves the channel.
    *
    * Unsubscribes from server events, and instructs channel to terminate on server.
    * Triggers onClose() hooks.
@@ -126,16 +197,16 @@ export default class RealtimeSubscription {
    * To receive leave acknowledgements, use the a `receive` hook to bind to the server ack, ie:
    * channel.unsubscribe().receive("ok", () => alert("left!") )
    */
-  unsubscribe(timeout = this.timeout) {
+  unsubscribe(timeout = this.timeout): Push {
     this.state = CHANNEL_STATES.leaving
-    let onClose = () => {
+    const onClose = () => {
       this.socket.log('channel', `leave ${this.topic}`)
       this.trigger(CHANNEL_EVENTS.close, 'leave', this.joinRef())
     }
     // Destroy joinPush to avoid connection timeouts during unscription phase
     this.joinPush.destroy()
 
-    let leavePush = new Push(this, CHANNEL_EVENTS.leave, {}, timeout)
+    const leavePush = new Push(this, CHANNEL_EVENTS.leave, {}, timeout)
     leavePush.receive('ok', () => onClose()).receive('timeout', () => onClose())
     leavePush.send()
     if (!this.canPush()) {
@@ -155,15 +226,15 @@ export default class RealtimeSubscription {
     return payload
   }
 
-  isMember(topic: string) {
+  isMember(topic: string): boolean {
     return this.topic === topic
   }
 
-  joinRef() {
+  joinRef(): string {
     return this.joinPush.ref
   }
 
-  rejoin(timeout = this.timeout) {
+  rejoin(timeout = this.timeout): void {
     if (this.isLeaving()) {
       return
     }
@@ -172,46 +243,78 @@ export default class RealtimeSubscription {
     this.joinPush.resend(timeout)
   }
 
-  trigger(event: string, payload?: any, ref?: string) {
-    let { close, error, leave, join } = CHANNEL_EVENTS
-    let events: string[] = [close, error, leave, join]
-    if (ref && events.indexOf(event) >= 0 && ref !== this.joinRef()) {
+  trigger(type: string, payload?: any, ref?: string) {
+    const { close, error, leave, join } = CHANNEL_EVENTS
+    const events: string[] = [close, error, leave, join]
+    if (ref && events.indexOf(type) >= 0 && ref !== this.joinRef()) {
       return
     }
-    let handledPayload = this.onMessage(event, payload, ref)
+    const handledPayload = this.onMessage(type, payload, ref)
     if (payload && !handledPayload) {
       throw 'channel onMessage callbacks must return the payload, modified or unmodified'
     }
 
     this.bindings
       .filter((bind) => {
-        // Bind all events if the user specifies a wildcard.
-        if (bind.event === '*') {
-          return event === payload?.type
-        } else {
-          return bind.event === event
-        }
+        return (
+          bind?.type === type &&
+          (bind?.filter?.event === '*' ||
+            bind?.filter?.event === payload?.event)
+        )
       })
       .map((bind) => bind.callback(handledPayload, ref))
   }
 
-  replyEventName(ref: string) {
+  send(
+    payload: { type: string; [key: string]: any },
+    opts: { [key: string]: any } = {}
+  ) {
+    const push = this.push(
+      payload.type as any,
+      payload,
+      opts.timeout ?? this.timeout
+    )
+
+    return new Promise((resolve) => {
+      push.receive('ok', () => resolve('ok'))
+      push.receive('timeout', () => resolve('timeout'))
+    })
+  }
+
+  replyEventName(ref: string): string {
     return `chan_reply_${ref}`
   }
 
-  isClosed() {
+  isClosed(): boolean {
     return this.state === CHANNEL_STATES.closed
   }
-  isErrored() {
+  isErrored(): boolean {
     return this.state === CHANNEL_STATES.errored
   }
-  isJoined() {
+  isJoined(): boolean {
     return this.state === CHANNEL_STATES.joined
   }
-  isJoining() {
+  isJoining(): boolean {
     return this.state === CHANNEL_STATES.joining
   }
-  isLeaving() {
+  isLeaving(): boolean {
     return this.state === CHANNEL_STATES.leaving
   }
+
+  private static isEqual(
+    obj1: { [key: string]: string },
+    obj2: { [key: string]: string }
+  ) {
+    if (Object.keys(obj1).length !== Object.keys(obj2).length) {
+      return false
+    }
+
+    for (const k in obj1) {
+      if (obj1[k] !== obj2[k]) {
+        return false
+      }
+    }
+
+    return true
+  }
 }

package/src/RealtimeClient.ts

@@ -11,7 +11,7 @@ import {
 } from './lib/constants'
 import Timer from './lib/timer'
 import Serializer from './lib/serializer'
-import RealtimeSubscription from './RealtimeSubscription'
+import RealtimeChannel from './RealtimeChannel'
 
 export type Options = {
   transport?: WebSocket
@@ -41,7 +41,7 @@ const noop = () => {}
 
 export default class RealtimeClient {
   accessToken: string | null = null
-  channels: RealtimeSubscription[] = []
+  channels: RealtimeChannel[] = []
   endPoint: string = ''
   headers?: { [key: string]: string } = DEFAULT_HEADERS
   params?: { [key: string]: string } = {}
@@ -255,14 +255,43 @@ export default class RealtimeClient {
    *
    * @param channel An open subscription.
    */
-  remove(channel: RealtimeSubscription) {
+  remove(channel: RealtimeChannel) {
     this.channels = this.channels.filter(
-      (c: RealtimeSubscription) => c.joinRef() !== channel.joinRef()
+      (c: RealtimeChannel) => c.joinRef() !== channel.joinRef()
     )
   }
 
-  channel(topic: string, chanParams: ChannelParams = {}): RealtimeSubscription {
-    const chan = new RealtimeSubscription(topic, chanParams, this)
+  channel(topic: string, chanParams: ChannelParams = {}): RealtimeChannel {
+    const { selfBroadcast, ...params } = chanParams
+
+    if (selfBroadcast) {
+      params.self_broadcast = selfBroadcast
+    }
+
+    const chan = new RealtimeChannel(topic, params, this)
+
+    chan.presence.onJoin((key, currentPresences, newPresences) => {
+      chan.trigger('presence', {
+        event: 'join',
+        key,
+        currentPresences,
+        newPresences,
+      })
+    })
+
+    chan.presence.onLeave((key, currentPresences, leftPresences) => {
+      chan.trigger('presence', {
+        event: 'leave',
+        key,
+        currentPresences,
+        leftPresences,
+      })
+    })
+
+    chan.presence.onSync(() => {
+      chan.trigger('presence', { event: 'sync' })
+    })
+
     this.channels.push(chan)
     return chan
   }
@@ -306,8 +335,8 @@ export default class RealtimeClient {
         payload
       )
       this.channels
-        .filter((channel: RealtimeSubscription) => channel.isMember(topic))
-        .forEach((channel: RealtimeSubscription) =>
+        .filter((channel: RealtimeChannel) => channel.isMember(topic))
+        .forEach((channel: RealtimeChannel) =>
           channel.trigger(event, payload, ref)
         )
       this.stateChangeCallbacks.message.forEach((callback) => callback(msg))
@@ -395,7 +424,7 @@ export default class RealtimeClient {
   }
 
   private _triggerChanError() {
-    this.channels.forEach((channel: RealtimeSubscription) =>
+    this.channels.forEach((channel: RealtimeChannel) =>
       channel.trigger(CHANNEL_EVENTS.error)
     )
   }

package/src/RealtimePresence.ts

@@ -0,0 +1,326 @@
+/*
+  This file draws heavily from https://github.com/phoenixframework/phoenix/blob/d344ec0a732ab4ee204215b31de69cf4be72e3bf/assets/js/phoenix/presence.js
+  License: https://github.com/phoenixframework/phoenix/blob/d344ec0a732ab4ee204215b31de69cf4be72e3bf/LICENSE.md
+*/
+
+import {
+  PresenceOpts,
+  PresenceOnJoinCallback,
+  PresenceOnLeaveCallback,
+} from 'phoenix'
+import RealtimeChannel from './RealtimeChannel'
+
+type Presence = {
+  presence_id: string
+  [key: string]: any
+}
+
+type PresenceState = { [key: string]: Presence[] }
+
+type PresenceDiff = {
+  joins: PresenceState
+  leaves: PresenceState
+}
+
+type RawPresenceState = {
+  [key: string]: Record<
+    'metas',
+    {
+      phx_ref?: string
+      phx_ref_prev?: string
+      [key: string]: any
+    }[]
+  >
+}
+
+type RawPresenceDiff = {
+  joins: RawPresenceState
+  leaves: RawPresenceState
+}
+
+type PresenceChooser<T> = (key: string, presences: any) => T
+
+export default class RealtimePresence {
+  state: PresenceState = {}
+  pendingDiffs: RawPresenceDiff[] = []
+  joinRef: string | null = null
+  caller: {
+    onJoin: PresenceOnJoinCallback
+    onLeave: PresenceOnLeaveCallback
+    onSync: () => void
+  } = {
+    onJoin: () => {},
+    onLeave: () => {},
+    onSync: () => {},
+  }
+
+  /**
+   * Initializes the Presence.
+   *
+   * @param channel - The RealtimeChannel
+   * @param opts - The options,
+   *        for example `{events: {state: 'state', diff: 'diff'}}`
+   */
+  constructor(public channel: RealtimeChannel, opts?: PresenceOpts) {
+    const events = opts?.events || {
+      state: 'presence_state',
+      diff: 'presence_diff',
+    }
+
+    this.channel.on(events.state, {}, (newState: RawPresenceState) => {
+      const { onJoin, onLeave, onSync } = this.caller
+
+      this.joinRef = this.channel.joinRef()
+
+      this.state = RealtimePresence.syncState(
+        this.state,
+        newState,
+        onJoin,
+        onLeave
+      )
+
+      this.pendingDiffs.forEach((diff) => {
+        this.state = RealtimePresence.syncDiff(
+          this.state,
+          diff,
+          onJoin,
+          onLeave
+        )
+      })
+
+      this.pendingDiffs = []
+
+      onSync()
+    })
+
+    this.channel.on(events.diff, {}, (diff: RawPresenceDiff) => {
+      const { onJoin, onLeave, onSync } = this.caller
+
+      if (this.inPendingSyncState()) {
+        this.pendingDiffs.push(diff)
+      } else {
+        this.state = RealtimePresence.syncDiff(
+          this.state,
+          diff,
+          onJoin,
+          onLeave
+        )
+
+        onSync()
+      }
+    })
+  }
+
+  /**
+   * Used to sync the list of presences on the server with the
+   * client's state.
+   *
+   * An optional `onJoin` and `onLeave` callback can be provided to
+   * react to changes in the client's local presences across
+   * disconnects and reconnects with the server.
+   */
+  static syncState(
+    currentState: PresenceState,
+    newState: RawPresenceState | PresenceState,
+    onJoin: PresenceOnJoinCallback,
+    onLeave: PresenceOnLeaveCallback
+  ): PresenceState {
+    const state = this.cloneDeep(currentState)
+    const transformedState = this.transformState(newState)
+    const joins: PresenceState = {}
+    const leaves: PresenceState = {}
+
+    this.map(state, (key: string, presences: Presence[]) => {
+      if (!transformedState[key]) {
+        leaves[key] = presences
+      }
+    })
+
+    this.map(transformedState, (key, newPresences: Presence[]) => {
+      const currentPresences: Presence[] = state[key]
+
+      if (currentPresences) {
+        const newPresenceIds = newPresences.map((m: Presence) => m.presence_id)
+        const curPresenceIds = currentPresences.map(
+          (m: Presence) => m.presence_id
+        )
+        const joinedPresences: Presence[] = newPresences.filter(
+          (m: Presence) => curPresenceIds.indexOf(m.presence_id) < 0
+        )
+        const leftPresences: Presence[] = currentPresences.filter(
+          (m: Presence) => newPresenceIds.indexOf(m.presence_id) < 0
+        )
+
+        if (joinedPresences.length > 0) {
+          joins[key] = joinedPresences
+        }
+
+        if (leftPresences.length > 0) {
+          leaves[key] = leftPresences
+        }
+      } else {
+        joins[key] = newPresences
+      }
+    })
+
+    return this.syncDiff(state, { joins, leaves }, onJoin, onLeave)
+  }
+
+  /**
+   * Used to sync a diff of presence join and leave events from the
+   * server, as they happen.
+   *
+   * Like `syncState`, `syncDiff` accepts optional `onJoin` and
+   * `onLeave` callbacks to react to a user joining or leaving from a
+   * device.
+   */
+  static syncDiff(
+    state: PresenceState,
+    diff: RawPresenceDiff | PresenceDiff,
+    onJoin: PresenceOnJoinCallback,
+    onLeave: PresenceOnLeaveCallback
+  ): PresenceState {
+    const { joins, leaves } = {
+      joins: this.transformState(diff.joins),
+      leaves: this.transformState(diff.leaves),
+    }
+
+    if (!onJoin) {
+      onJoin = () => {}
+    }
+
+    if (!onLeave) {
+      onLeave = () => {}
+    }
+
+    this.map(joins, (key, newPresences: Presence[]) => {
+      const currentPresences: Presence[] = state[key]
+      state[key] = this.cloneDeep(newPresences)
+
+      if (currentPresences) {
+        const joinedPresenceIds = state[key].map((m: Presence) => m.presence_id)
+        const curPresences: Presence[] = currentPresences.filter(
+          (m: Presence) => joinedPresenceIds.indexOf(m.presence_id) < 0
+        )
+
+        state[key].unshift(...curPresences)
+      }
+
+      onJoin(key, currentPresences, newPresences)
+    })
+
+    this.map(leaves, (key, leftPresences: Presence[]) => {
+      let currentPresences: Presence[] = state[key]
+
+      if (!currentPresences) return
+
+      const presenceIdsToRemove = leftPresences.map(
+        (m: Presence) => m.presence_id
+      )
+      currentPresences = currentPresences.filter(
+        (m: Presence) => presenceIdsToRemove.indexOf(m.presence_id) < 0
+      )
+
+      state[key] = currentPresences
+
+      onLeave(key, currentPresences, leftPresences)
+
+      if (currentPresences.length === 0) delete state[key]
+    })
+
+    return state
+  }
+
+  /**
+   * Returns the array of presences, with selected metadata.
+   */
+  static list<T = any>(
+    presences: PresenceState,
+    chooser: PresenceChooser<T> | undefined
+  ): T[] {
+    if (!chooser) {
+      chooser = (_key, pres) => pres
+    }
+
+    return this.map(presences, (key, presences: Presence[]) =>
+      chooser!(key, presences)
+    )
+  }
+
+  private static map<T = any>(
+    obj: PresenceState,
+    func: PresenceChooser<T>
+  ): T[] {
+    return Object.getOwnPropertyNames(obj).map((key) => func(key, obj[key]))
+  }
+
+  /**
+   * Remove 'metas' key
+   * Change 'phx_ref' to 'presence_id'
+   * Remove 'phx_ref' and 'phx_ref_prev'
+   *
+   * @example
+   * // returns {
+   *  abc123: [
+   *    { presence_id: '2', user_id: 1 },
+   *    { presence_id: '3', user_id: 2 }
+   *  ]
+   * }
+   * RealtimePresence.transformState({
+   *  abc123: {
+   *    metas: [
+   *      { phx_ref: '2', phx_ref_prev: '1' user_id: 1 },
+   *      { phx_ref: '3', user_id: 2 }
+   *    ]
+   *  }
+   * })
+   */
+  private static transformState(
+    state: RawPresenceState | PresenceState
+  ): PresenceState {
+    state = this.cloneDeep(state)
+
+    return Object.getOwnPropertyNames(state).reduce((newState, key) => {
+      const presences = state[key]
+
+      if ('metas' in presences) {
+        newState[key] = presences.metas.map((presence) => {
+          presence['presence_id'] = presence['phx_ref']
+
+          delete presence['phx_ref']
+          delete presence['phx_ref_prev']
+
+          return presence
+        }) as Presence[]
+      } else {
+        newState[key] = presences
+      }
+
+      return newState
+    }, {} as PresenceState)
+  }
+
+  private static cloneDeep(obj: object) {
+    return JSON.parse(JSON.stringify(obj))
+  }
+
+  onJoin(callback: PresenceOnJoinCallback): void {
+    this.caller.onJoin = callback
+  }
+
+  onLeave(callback: PresenceOnLeaveCallback): void {
+    this.caller.onLeave = callback
+  }
+
+  onSync(callback: () => void): void {
+    this.caller.onSync = callback
+  }
+
+  list<T = any>(by?: PresenceChooser<T>): T[] {
+    return RealtimePresence.list<T>(this.state, by)
+  }
+
+  private inPendingSyncState(): boolean {
+    return !this.joinRef || this.joinRef !== this.channel.joinRef()
+  }
+}

package/src/index.ts

@@ -2,11 +2,13 @@ import * as Transformers from './lib/transformers'
 import RealtimeClient, {
   Options as RealtimeClientOptions,
 } from './RealtimeClient'
-import RealtimeSubscription from './RealtimeSubscription'
+import RealtimeChannel from './RealtimeChannel'
+import RealtimePresence from './RealtimePresence'
 
 export {
   RealtimeClient,
   RealtimeClientOptions,
-  RealtimeSubscription,
+  RealtimeChannel,
+  RealtimePresence,
   Transformers,
 }