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

RealtimeChannel

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,
);
bindings: {
[key: string]: {
type: string;
filter: {
[key: string]: any;
};
callback: Function;
id?: string;
}[];
};
broadcastEndpointURL: string;
joinedOnce: boolean;
joinPush: Push;
presence: RealtimePresence;
private: boolean;
pushBuffer: Push[];
rejoinTimer: Timer;
state: CHANNEL_STATES;
subTopic: string;
timeout: number;
topic: string;
 
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.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(
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<"ok" | "timed out" | "error">;
untrack(opts?: {
[key: string]: any;
}): Promise<RealtimeChannelSendResponse>;
updateJoinPayload(payload: {
[key: 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
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

§
bindings: {
[key: string]: {
type: string;
filter: {
[key: string]: any;
};
callback: Function;
id?: string;
}[];
}
[src]
§
broadcastEndpointURL: string
[src]
§
joinedOnce: boolean
[src]
§
joinPush: Push
[src]
§
private: boolean
[src]
§
pushBuffer: Push[]
[src]
§
rejoinTimer: Timer
[src]
§
state: CHANNEL_STATES
[src]
§
subTopic: string
[src]
§
timeout: number
[src]
§
topic: string
[src]

Topic name can be any string.

§Methods

§
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.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(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

§
subscribe(callback?: (status: REALTIME_SUBSCRIBE_STATES, err?: Error) => void, timeout?: number): RealtimeChannel
[src]

Subscribe registers your client with the server

§
teardown(): void
[src]

Teardown the channel.

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<"ok" | "timed out" | "error">
[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: {
[key: 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.