For AI agents: this page in Markdown: https://www.pubnub.com/docs/sdks/javascript/api-reference/misc.md. Documentation index: https://www.pubnub.com/llms-full.txt.

Utility Methods API for JavaScript SDK

The Utility Methods API of the PubNub SDK for JavaScript covers operations that fit no other API page, such as connection control, subscription queries, and the PubNub service time.

The JavaScript SDK adds two sections that other SDKs do not have: PubNubFile and setProxy.

Disconnect​

pubnub.disconnect() stops the subscribe loop of a PubNub client for JavaScript but keeps its subscriptions, so a reconnect can resume them.

With the standardized subscribe and presence workflows (enableEventEngine: true) and a heartbeatInterval, disconnect() also sends a leave request for the subscribed channels and channel groups, unless isOffline is true. Without the standardized workflows, disconnect() also stops the heartbeat timer and sends no leave request.

isOffline#
Type: boolean
Default: false
Whether a network problem caused the disconnect. If true, the client sends no leave request. With true, the client also emits an error status, such as PNDisconnectedUnexpectedlyCategory, while it receives messages. isOffline has an effect only with the standardized subscribe and presence workflows. Without them, the client ignores it.

Returns​

disconnect() returns nothing. Monitor the result with the status listener of the client.

Syntax

1pubnub.disconnect(isOffline?: boolean): void;

Reconnect​

pubnub.reconnect() restarts the subscribe loop of a PubNub client for JavaScript after a disconnect or a failed connection. The client resumes the subscriptions that were active at the time of the disconnect.

parameters#
Type: object
Default: no default
Catch-up cursor for the reconnect. parameters has an effect only with the standardized subscribe and presence workflows. Without them, the client ignores it.
property of parameters: timetoken#
Type: string
Default: no default
The timetoken from which to start returning available cached messages. PubNub provides cached messages on a best-effort basis. If you omit timetoken, the client continues from the cursor of its last subscribe response.
property of parameters: region#
Type: number
Default: no default
The region value that belongs to the cursor in timetoken. If you omit region, the client keeps the region of its last subscribe response.

Returns​

reconnect() returns nothing. Monitor the result with the status listener of the client.

Syntax

1pubnub.reconnect(parameters?: {
2    timetoken?: string,
3    region?: number
4}): void;

Get subscribed channels​

pubnub.getSubscribedChannels() returns the channels that a PubNub client for JavaScript subscribes to.

The list also contains the presence channel (<channel>-pnpres) of every channel that you subscribed to with presence events. This applies only with the standardized subscribe and presence workflows.getSubscribedChannels() takes no parameters.

Returns​

getSubscribedChannels() returns an array of channel names, for example ["channel1", "channel2"]. The array is empty when the client has no subscriptions.

Syntax

1pubnub.getSubscribedChannels(): string[];

Get subscribed channel groups​

pubnub.getSubscribedChannelGroups() returns the channel groups that a PubNub client for JavaScript subscribes to.

The list also contains the presence channel group (<channel group>-pnpres) of every channel group that you subscribed to with presence events. This applies only with the standardized subscribe and presence workflows.getSubscribedChannelGroups() takes no parameters.

Returns​

getSubscribedChannelGroups() returns an array of channel group names, for example ["group1", "group2"]. The array is empty when the client has no subscriptions.

Syntax

1pubnub.getSubscribedChannelGroups(): string[];

Time​

pubnub.time() returns the current PubNub service time as a timetoken, using a PubNub client for JavaScript.

callback#
Type: function
Default: no default
Function that the SDK calls when the request completes. With a callback, time() returns nothing. Without it, time() returns a promise.

Returns​

time() resolves with a TimeResponse. With a callback, status.operation is PNTimeOperation and the response is the second callback argument.

Syntax

1pubnub.time(): Promise<TimeResponse>;
2

3pubnub.time(callback: ResultCallback<TimeResponse>): void;

PubNubFile​

PubNubFile is the file object that a PubNub client for JavaScript uses for file content. pubnub.File.create() builds one, and downloadFile() returns one. For the file methods, see Files.

Extracting the file​

The methods that read a PubNubFile object depend on the environment. A method that the environment does not support rejects with an error.

Methods supported in Node.js​

In Node.js, file.toBuffer() resolves with a Buffer, file.toStream() resolves with a Readable stream, and file.toArrayBuffer() resolves with an ArrayBuffer. The method file.toString(encoding?: string) resolves with a string encoded with encoding, which defaults to utf8. The methods toFile(), toBlob(), and toFileUri() reject.

Methods supported in a browser​

In a browser, file.toFile() resolves with a File, file.toBlob() resolves with a Blob, and file.toArrayBuffer() resolves with an ArrayBuffer. The method file.toString() resolves with a string that holds the binary content of the file and takes no encoding argument. The methods toBuffer(), toStream(), and toFileUri() reject.

React and React Native​

In React Native, file.toArrayBuffer() resolves with an ArrayBuffer, and file.toString() resolves with a string and takes no encoding argument. For a file that you created from a File, file.toBlob() and file.toFile() resolve with that File. For a file that you created from a string or a Blob, they resolve with a Blob. Both reject for a file that you created from an ArrayBuffer, a typed array, or a uri, and for a file that downloadFile() returns, so use toArrayBuffer() there.

In React Native, file.toFileUri() resolves with the { uri, name, type } object of a file that you created from a uri and rejects for any other file. The methods toBuffer() and toStream() reject.

Creating a file​

required
file required#
Type: FileInput
Default: no default
Content and metadata of the file. The accepted shapes depend on the environment, as described in the next sections. Without usable content, create() throws Couldn't construct a file out of supplied options. Without a file name, it throws Couldn't guess filename out of the options. Please provide one.

Node.js​

In Node.js, mimeType defaults to application/octet-stream. The data property accepts a Buffer, an ArrayBuffer, or a string. For a string, the optional encoding property sets the encoding and defaults to utf8. For the object shapes, see FileInput.

Browsers​

In a browser, file accepts a File or an object whose data property is a string, an ArrayBuffer, an ArrayBufferView, or a Blob. For the object shapes, see FileInput.

React Native​

React Native accepts a File, an object with a data property like the one for browsers, and an object with a uri property. For the object shapes, see FileInput.

Creating a file

1pubnub.File.create(file: FileInput): PubNubFile;

setProxy​

pubnub.setProxy() sets or removes the HTTP or HTTPS proxy of a PubNub client for JavaScript in Node.js at run time. This method is available only in Node.js.

The client sends all its requests through the proxy until you remove it. Only explicit HTTP and HTTPS proxies work. The SDK does not support SOCKS proxies, PAC files, or proxy environment variables. After the proxy changes, the client calls reconnect() so that the subscribe loop uses the new setting.

required
configuration#
Type: string | object
Default: no default
Proxy to use. Pass a proxy URI such as http://proxy.example.com:8080, or an object with the fields below. Call setProxy() without an argument to remove the proxy.
property of configuration: hostname required#
Type: string
Default: no default
Host name or IP address of the proxy. The host field is an alias, so set one of the two.
property of configuration: host#
Type: string
Default: no default
Alias of hostname.
property of configuration: port#
Type: number
Default: no default
Port on which the proxy listens. If you omit port, the SDK builds the proxy address without one.
property of configuration: protocol#
Type: string
Default: http
Protocol of the proxy. Supported values are http and https.
property of configuration: auth#
Type: string
Default: no default
Basic authentication credentials of the proxy in the user:password form.

Passing a proxy together with keepAlive: true in the client configuration throws a PubNubError with the message Can't set 'proxy' because already configured for 'keepAlive'. Removing the proxy never throws.

Syntax

1pubnub.setProxy(configuration?: string | {
2    hostname?: string,
3    host?: string,
4    port?: number,
5    protocol?: string,
6    auth?: string
7}): void;

Was this page useful?

Last updated on