Hi there! Are you looking for the official Deno documentation? Try docs.deno.com for all your Deno learning needs.

RealtimeChannel

import { RealtimeChannel } from "https://esm.sh/@supabase/supabase-js@2.101.0/dist/index.d.mts";

A channel is the basic building block of Realtime and narrows the scope of data flow to subscribed clients. You can think of a channel as a chatroom where participants are able to see who's online and send and receive messages.

class RealtimeChannel {
constructor(
topic: string,
params: RealtimeChannelOptions | undefined,
socket: RealtimeClient,
);
private _updatePostgresBindings;
bindings: Record<string, Binding[]>;
broadcastEndpointURL: string;
get joinedOnce(): boolean;
get joinPush(): import("https://esm.sh/@supabase/phoenix@0.4.0/priv/static/types/index.d.ts").Push;
presence: RealtimePresence;
private: boolean;
get state(): ChannelState;
set state(state: ChannelState);
get rejoinTimer(): import("https://esm.sh/@supabase/phoenix@0.4.0/priv/static/types/timer.d.ts").default;
subTopic: string;
get timeout(): number;
topic: string;
 
copyBindings(other: RealtimeChannel): void;
httpSend(
event: string,
payload: any,
opts?: {
timeout?: number;
},
): Promise<{
success: true;
} | {
success: false;
status: number;
error: string;
}>;
on(
type: `${REALTIME_LISTEN_TYPES.PRESENCE}`,
filter: {
event: `${REALTIME_PRESENCE_LISTEN_EVENTS.SYNC}`;
},
callback: () => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.PRESENCE}`,
filter: {
event: `${REALTIME_PRESENCE_LISTEN_EVENTS.JOIN}`;
},
callback: (payload: RealtimePresenceJoinPayload<T>) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.PRESENCE}`,
filter: {
event: `${REALTIME_PRESENCE_LISTEN_EVENTS.LEAVE}`;
},
callback: (payload: RealtimePresenceLeavePayload<T>) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.PRESENCE}`,
filter: {
event: "*";
},
callback: (payload?: RealtimePresenceJoinPayload<T> | RealtimePresenceLeavePayload<T>) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`,
filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.ALL}`>,
callback: (payload: RealtimePostgresChangesPayload<T>) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`,
filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.INSERT}`>,
callback: (payload: RealtimePostgresInsertPayload<T>) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`,
filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.UPDATE}`>,
callback: (payload: RealtimePostgresUpdatePayload<T>) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`,
filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.DELETE}`>,
callback: (payload: RealtimePostgresDeletePayload<T>) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`,
filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT}`>,
callback: (payload: RealtimePostgresChangesPayload<T>) => void,
): RealtimeChannel;
on(
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
filter: {
event: string;
},
callback: (payload: {
[key: string]: any;
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: string;
meta?: {
replayed?: boolean;
id: string;
};
}) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
filter: {
event: string;
},
callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: string;
meta?: {
replayed?: boolean;
id: string;
};
payload: T;
}) => void,
): RealtimeChannel;
on<T extends Record<string, unknown>>(
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
filter: {
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.ALL;
},
callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.ALL;
payload: RealtimeBroadcastPayload<T>;
}) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
filter: {
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.INSERT;
},
callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.INSERT;
payload: RealtimeBroadcastInsertPayload<T>;
}) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
filter: {
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.UPDATE;
},
callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.UPDATE;
payload: RealtimeBroadcastUpdatePayload<T>;
}) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
filter: {
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.DELETE;
},
callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.DELETE;
payload: RealtimeBroadcastDeletePayload<T>;
}) => void,
): RealtimeChannel;
on<T extends {
[key: string]: any;
}>(
type: `${REALTIME_LISTEN_TYPES.SYSTEM}`,
filter: {},
callback: (payload: any) => void,
): RealtimeChannel;
presenceState<T extends {
[key: string]: any;
} = {}>(): RealtimePresenceState<T>;
send(args: {
[key: string]: any;
type: "broadcast" | "presence" | "postgres_changes";
event: string;
payload?: any;
}, opts?: {
[key: string]: any;
}): Promise<RealtimeChannelSendResponse>;
subscribe(callback?: (status: REALTIME_SUBSCRIBE_STATES, err?: Error) => void, timeout?: number): RealtimeChannel;
teardown(): void;
track(payload: {
[key: string]: any;
}, opts?: {
[key: string]: any;
}): Promise<RealtimeChannelSendResponse>;
unsubscribe(timeout?: number): Promise<RealtimeChannelSendResponse>;
untrack(opts?: {
[key: string]: any;
}): Promise<RealtimeChannelSendResponse>;
updateJoinPayload(payload: Record<string, any>): void;
}

§Constructors

§
new RealtimeChannel(topic: string, params: RealtimeChannelOptions | undefined, socket: RealtimeClient)
[src]

Creates a channel that can broadcast messages, sync presence, and listen to Postgres changes.

The topic determines which realtime stream you are subscribing to. Config options let you enable acknowledgement for broadcasts, presence tracking, or private channels.

@example

Example for a public channel

import RealtimeClient from '@supabase/realtime-js'

const client = new RealtimeClient('https://xyzcompany.supabase.co/realtime/v1', {
  params: { apikey: 'public-anon-key' },
})
const channel = new RealtimeChannel('realtime:public:messages', { config: {} }, client)

§Properties

§
_updatePostgresBindings
[src]
§
bindings: Record<string, Binding[]>
[src]
§
broadcastEndpointURL: string
[src]
§
joinedOnce: boolean readonly
[src]
§
joinPush: import("https://esm.sh/@supabase/phoenix@0.4.0/priv/static/types/index.d.ts").Push readonly
[src]
§
private: boolean
[src]
§
state: ChannelState
[src]
§
rejoinTimer: import("https://esm.sh/@supabase/phoenix@0.4.0/priv/static/types/timer.d.ts").default readonly
[src]
§
subTopic: string
[src]
§
timeout: number readonly
[src]
§
topic: string
[src]

Topic name can be any string.

§Methods

§
copyBindings(other: RealtimeChannel): void
[src]
§
httpSend(event: string, payload: any, opts?: {
timeout?: number;
}): Promise<{
success: true;
} | {
success: false;
status: number;
error: string;
}>
[src]

Sends a broadcast message explicitly via REST API.

This method always uses the REST API endpoint regardless of WebSocket connection state. Useful when you want to guarantee REST delivery or when gradually migrating from implicit REST fallback.

@param event

The name of the broadcast event

@param payload

Payload to be sent (required)

@param opts

Options including timeout

@return

Promise resolving to object with success status, and error details if failed

§
on(type: `${REALTIME_LISTEN_TYPES.PRESENCE}`, filter: {
event: `${REALTIME_PRESENCE_LISTEN_EVENTS.SYNC}`;
}, callback: () => void): RealtimeChannel
[src]

Creates an event handler that listens to changes.

on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.PRESENCE}`, filter: {
event: `${REALTIME_PRESENCE_LISTEN_EVENTS.JOIN}`;
}, callback: (payload: RealtimePresenceJoinPayload<T>) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.PRESENCE}`, filter: {
event: `${REALTIME_PRESENCE_LISTEN_EVENTS.LEAVE}`;
}, callback: (payload: RealtimePresenceLeavePayload<T>) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.PRESENCE}`, filter: {
event: "*";
}, callback: (payload?: RealtimePresenceJoinPayload<T> | RealtimePresenceLeavePayload<T>) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`, filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.ALL}`>, callback: (payload: RealtimePostgresChangesPayload<T>) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`, filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.INSERT}`>, callback: (payload: RealtimePostgresInsertPayload<T>) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`, filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.UPDATE}`>, callback: (payload: RealtimePostgresUpdatePayload<T>) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`, filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.DELETE}`>, callback: (payload: RealtimePostgresDeletePayload<T>) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.POSTGRES_CHANGES}`, filter: RealtimePostgresChangesFilter<`${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT}`>, callback: (payload: RealtimePostgresChangesPayload<T>) => void): RealtimeChannel
[src]
on(type: `${REALTIME_LISTEN_TYPES.BROADCAST}`, filter: {
event: string;
}, callback: (payload: {
[key: string]: any;
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: string;
meta?: {
replayed?: boolean;
id: string;
};
}) => void): RealtimeChannel
[src]

The following is placed here to display on supabase.com/docs/reference/javascript/subscribe.

@param type

One of "broadcast", "presence", or "postgres_changes".

@param filter

Custom object specific to the Realtime feature detailing which payloads to receive.

@param callback

Function to be invoked when event handler is triggered.

on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.BROADCAST}`, filter: {
event: string;
}, callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: string;
meta?: {
replayed?: boolean;
id: string;
};
payload: T;
}) => void): RealtimeChannel
[src]
on<T extends Record<string, unknown>>(type: `${REALTIME_LISTEN_TYPES.BROADCAST}`, filter: {
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.ALL;
}, callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.ALL;
payload: RealtimeBroadcastPayload<T>;
}) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.BROADCAST}`, filter: {
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.INSERT;
}, callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.INSERT;
payload: RealtimeBroadcastInsertPayload<T>;
}) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.BROADCAST}`, filter: {
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.UPDATE;
}, callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.UPDATE;
payload: RealtimeBroadcastUpdatePayload<T>;
}) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.BROADCAST}`, filter: {
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.DELETE;
}, callback: (payload: {
type: `${REALTIME_LISTEN_TYPES.BROADCAST}`;
event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.DELETE;
payload: RealtimeBroadcastDeletePayload<T>;
}) => void): RealtimeChannel
[src]
on<T extends {
[key: string]: any;
}>(type: `${REALTIME_LISTEN_TYPES.SYSTEM}`, filter: {}, callback: (payload: any) => void): RealtimeChannel
[src]
§
presenceState<T extends {
[key: string]: any;
} = {}>(): RealtimePresenceState<T>
[src]

Returns the current presence state for this channel.

The shape is a map keyed by presence key (for example a user id) where each entry contains the tracked metadata for that user.

§
send(args: {
[key: string]: any;
type: "broadcast" | "presence" | "postgres_changes";
event: string;
payload?: any;
}, opts?: {
[key: string]: any;
}): Promise<RealtimeChannelSendResponse>
[src]

Sends a message into the channel.

@param args

Arguments to send to channel

@param args.type

The type of event to send

@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

@example

Send a message via websocket

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() },
    })
  }
})
@example
@example

Send a message via REST

supabase
  .channel('room1')
  .httpSend('cursor-pos', { x: Math.random(), y: Math.random() })
§
subscribe(callback?: (status: REALTIME_SUBSCRIBE_STATES, err?: Error) => void, timeout?: number): RealtimeChannel
[src]

Subscribe registers your client with the server

§
teardown(): void
[src]

Destroys and stops related timers.

§
track(payload: {
[key: string]: any;
}, opts?: {
[key: string]: any;
}): Promise<RealtimeChannelSendResponse>
[src]

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.

§
unsubscribe(timeout?: number): Promise<RealtimeChannelSendResponse>
[src]

Leaves the channel.

Unsubscribes from server events, and instructs channel to terminate on server. Triggers onClose() hooks.

To receive leave acknowledgements, use the a receive hook to bind to the server ack, ie: channel.unsubscribe().receive("ok", () => alert("left!") )

§
untrack(opts?: {
[key: string]: any;
}): Promise<RealtimeChannelSendResponse>
[src]

Removes the current presence state for this client.

§
updateJoinPayload(payload: Record<string, any>): void
[src]

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.