diff --git a/README.md b/README.md index 03c9c1e3bc..a120817518 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,6 @@ and require as: var Ably = require('ably'); ``` -For the version of the library where async methods return promises, use `var Ably = require('ably/promises');` instead. For the explicitly-callback-based variant use `require('ably/callbacks')`– see [Async API style](#async-api-style). - For usage, jump to [Using the Realtime API](#using-the-realtime-api) or [Using the REST API](#using-the-rest-api). #### Serverside usage with webpack @@ -92,21 +90,11 @@ let client = new Ably.Realtime(options); /* inferred type Ably.Realtime */ let channel = client.channels.get('feed'); /* inferred type Ably.Types.RealtimeChannel */ ``` -For the version of the library where async methods return promises, use `import * as Ably from 'ably/promises';` instead. For the explicitly-callback-based variant use `import * as Ably from 'ably/callbacks'` – see [Async API style](#async-api-style). - Intellisense in IDEs with TypeScript support is supported: ![TypeScript suggestions](./resources/typescript-demo.gif) -If you need to explicitly import the type definitions, see [ably.d.ts](./ably.d.ts) (or `promises.d.ts` if you're requiring the library as `ably/promises`). - -## Async API style - -This library exposes two API variants. Firstly, the original (and presently the default) callback-based API, which follows the usual Node.js error-first callback style. Second, a promises-based API. With the promises variant, you can still pass a callback to methods and the callback will work as expected, but if you do not pass a callback, the method will return a promise. The API in use can be selected explicitly by requiring that specific variant when requiring/importing the library (or in the case of the browser version, when instantiating it). The usage instructions below make reference to both variants. - -For this library version, and for all future 1.x versions, the callback-based API will be the default. This means that the promises-based variant will need to be explicitly selected, to avoid breaking backwards compatibility. A move to the promises-based variant as the default is likely at the next major release (i.e. 2.x onwards). - -For usage, jump to [Using the async API style](#using-the-async-api-style). +If you need to explicitly import the type definitions, see [ably.d.ts](./ably.d.ts). ## NativeScript @@ -128,13 +116,6 @@ var client = new Ably.Realtime(key: string); // which must contain at least one auth option, i.e. at least // one of: key, token, tokenDetails, authUrl, or authCallback var client = new Ably.Realtime(options: ClientOptions); - -// For a version of the library where async methods return promises if -// you don't pass a callback: -var client = new Ably.Realtime.Promise(options: string | ClientOptions); - -// For the explicitly-callback-based variant (see 'Async API style' below): -var client = new Ably.Rest.Callbacks(options: string | ClientOptions); ``` ### Connection @@ -195,36 +176,26 @@ If you would like to inspect the `Message` instances in order to identify whethe ```javascript // Publish a single message with name and data -channel.publish('greeting', 'Hello World!'); - -// Optionally, you can use a callback to be notified of success or failure -channel.publish('greeting', 'Hello World!', function(err) { - if(err) { - console.log('publish failed with error ' + err); - } else { - console.log('publish succeeded'); - } -}) +await channel.publish('greeting', 'Hello World!'); // Publish several messages at once -channel.publish([{name: 'greeting', data: 'Hello World!'}, ...], callback); +await channel.publish([{name: 'greeting', data: 'Hello World!'}, ...]); ``` ### Querying the History ```javascript -channel.history(function(err, messagesPage) { - messagesPage // PaginatedResult - messagesPage.items // array of Message - messagesPage.items[0].data // payload for first message - messagesPage.items.length // number of messages in the current page of history - messagesPage.hasNext() // true if there are further pages - messagesPage.isLast() // true if this page is the last page - messagesPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult -}); +const messagesPage = channel.history() +messagesPage // PaginatedResult +messagesPage.items // array of Message +messagesPage.items[0].data // payload for first message +messagesPage.items.length // number of messages in the current page of history +messagesPage.hasNext() // true if there are further pages +messagesPage.isLast() // true if this page is the last page +const nextPage = await messagesPage.next(); // retrieves the next page as PaginatedResult // Can optionally take an options param, see https://www.ably.com/docs/rest-api/#message-history -channel.history({start: ..., end: ..., limit: ..., direction: ...}, function(err, messagesPage) { ...}); +const messagesPage = await channel.history({start: ..., end: ..., limit: ..., direction: ...}); ``` ### Presence on a channel @@ -232,9 +203,8 @@ channel.history({start: ..., end: ..., limit: ..., direction: ...}, function(err Getting presence: ```javascript -channel.presence.get(function (err, presenceSet) { - presenceSet; // array of PresenceMessages -}); +const presenceSet = channel.presence.get(); +presenceSet; // array of PresenceMessages ``` Note that presence#get on a realtime channel does not return a @@ -243,17 +213,14 @@ PaginatedResult, as the library maintains a local copy of the presence set. Entering (and leaving) the presence set: ```javascript -channel.presence.enter('my status', function (err) { - // now I am entered -}); +await channel.presence.enter('my status'); +// now I am entered -channel.presence.update('new status', function (err) { - // my presence data is updated -}); +await channel.presence.update('new status'); +// my presence data is updated -channel.presence.leave(function (err) { - // I've left the presence set -}); +await channel.presence.leave() +// I've left the presence set ``` If you are using a client which is allowed to use any clientId -- @@ -263,24 +230,23 @@ https://www.ably.com/docs/general/authentication for more information), you can use ```javascript -channel.presence.enterClient('myClientId', 'status', function(err) { ... }); +await channel.presence.enterClient('myClientId', 'status'); // and similiarly, updateClient and leaveClient ``` ### Querying the Presence History ```javascript -channel.presence.history(function(err, messagesPage) { // PaginatedResult - messagesPage.items // array of PresenceMessage - messagesPage.items[0].data // payload for first message - messagesPage.items.length // number of messages in the current page of history - messagesPage.hasNext() // true if there are further pages - messagesPage.isLast() // true if this page is the last page - messagesPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult -}); +const messagesPage = channel.presence.history(); // PaginatedResult +messagesPage.items // array of PresenceMessage +messagesPage.items[0].data // payload for first message +messagesPage.items.length // number of messages in the current page of history +messagesPage.hasNext() // true if there are further pages +messagesPage.isLast() // true if this page is the last page +const nextPage = await messagesPage.next(); // retrieves the next page as PaginatedResult // Can optionally take an options param, see https://www.ably.com/docs/rest-api/#message-history -channel.presence.history({start: ..., end: ..., limit: ..., direction: ...}, function(err, messagesPage) { ...}); +const messagesPage = await channel.presence.history({start: ..., end: ..., limit: ..., direction: ...); ``` ### Symmetrical end-to-end encrypted payloads on a channel @@ -290,24 +256,22 @@ When a 128 bit or 256 bit key is provided to the library, the `data` attributes ```javascript // Generate a random 256-bit key for demonstration purposes (in // practice you need to create one and distribute it to clients yourselves) -Ably.Realtime.Crypto.generateRandomKey(function (err, key) { - var channel = client.channels.get('channelName', { cipher: { key: key } }); +const key = await Ably.Realtime.Crypto.generateRandomKey(); +var channel = client.channels.get('channelName', { cipher: { key: key } }); - channel.subscribe(function (message) { - message.name; // 'name is not encrypted' - message.data; // 'sensitive data is encrypted' - }); - - channel.publish('name is not encrypted', 'sensitive data is encrypted'); +channel.subscribe(function (message) { + message.name; // 'name is not encrypted' + message.data; // 'sensitive data is encrypted' }); + +channel.publish('name is not encrypted', 'sensitive data is encrypted'); ``` -You can also change the key on an existing channel using setOptions (which takes a callback which is called after the new encryption settings have taken effect): +You can also change the key on an existing channel using setOptions (which completes after the new encryption settings have taken effect): ```javascript -channel.setOptions({cipher: {key: }}, function() { - // New encryption settings are in effect -}) +await channel.setOptions({cipher: {key: }}); +// New encryption settings are in effect ``` ### Message interactions @@ -340,13 +304,6 @@ var client = new Ably.Rest(key: string); // which must contain at least one auth option, i.e. at least // one of: key, token, tokenDetails, authUrl, or authCallback var client = new Ably.Rest(options: ClientOptions); - -// For a version of the library where async methods return promises if -// you don't pass a callback: -var client = new Ably.Rest.Promise(options: string | ClientOptions); - -// For the explicitly-callback-based variant (see 'Async API style' above): -var client = new Ably.Rest.Callbacks(options: string | ClientOptions); ``` Given: @@ -359,75 +316,67 @@ var channel = client.channels.get('test'); ```javascript // Publish a single message with name and data -channel.publish('greeting', 'Hello World!'); - -// Optionally, you can use a callback to be notified of success or failure -channel.publish('greeting', 'Hello World!', function(err) { - if(err) { - console.log('publish failed with error ' + err); - } else { - console.log('publish succeeded'); - } -}) +try { + channel.publish('greeting', 'Hello World!'); + console.log('publish succeeded'); +} catch (err) { + console.log('publish failed with error ' + err); +} // Publish several messages at once -channel.publish([{name: 'greeting', data: 'Hello World!'}, ...], callback); +await channel.publish([{name: 'greeting', data: 'Hello World!'}, ...]); ``` ### Querying the History ```javascript -channel.history(function(err, messagesPage) { - messagesPage // PaginatedResult - messagesPage.items // array of Message - messagesPage.items[0].data // payload for first message - messagesPage.items.length // number of messages in the current page of history - messagesPage.hasNext() // true if there are further pages - messagesPage.isLast() // true if this page is the last page - messagesPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult -}); +const messagesPage = await channel.history(); +messagesPage // PaginatedResult +messagesPage.items // array of Message +messagesPage.items[0].data // payload for first message +messagesPage.items.length // number of messages in the current page of history +messagesPage.hasNext() // true if there are further pages +messagesPage.isLast() // true if this page is the last page +const nextPage = await messagesPage.next(); // retrieves the next page as PaginatedResult // Can optionally take an options param, see https://www.ably.com/docs/rest-api/#message-history -channel.history({start: ..., end: ..., limit: ..., direction: ...}, function(err, messagesPage) { ...}); +await channel.history({start: ..., end: ..., limit: ..., direction: ...}); ``` ### Presence on a channel ```javascript -channel.presence.get(function(err, presencePage) { // PaginatedResult - presencePage.items // array of PresenceMessage - presencePage.items[0].data // payload for first message - presencePage.items.length // number of messages in the current page of members - presencePage.hasNext() // true if there are further pages - presencePage.isLast() // true if this page is the last page - presencePage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult -}); +const presencePage = await channel.presence.get() // PaginatedResult +presencePage.items // array of PresenceMessage +presencePage.items[0].data // payload for first message +presencePage.items.length // number of messages in the current page of members +presencePage.hasNext() // true if there are further pages +presencePage.isLast() // true if this page is the last page +const nextPage = await presencePage.next(); // retrieves the next page as PaginatedResult ``` ### Querying the Presence History ```javascript -channel.presence.history(function(err, messagesPage) { // PaginatedResult - messagesPage.items // array of PresenceMessage - messagesPage.items[0].data // payload for first message - messagesPage.items.length // number of messages in the current page of history - messagesPage.hasNext() // true if there are further pages - messagesPage.isLast() // true if this page is the last page - messagesPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult -}); +const messagesPage = channel.presence.history(); // PaginatedResult +messagesPage.items // array of PresenceMessage +messagesPage.items[0].data // payload for first message +messagesPage.items.length // number of messages in the current page of history +messagesPage.hasNext() // true if there are further pages +messagesPage.isLast() // true if this page is the last page +const nextPage = await messagesPage.next(); // retrieves the next page as PaginatedResult // Can optionally take an options param, see https://www.ably.com/docs/rest-api/#message-history -channel.history({start: ..., end: ..., limit: ..., direction: ...}, function(err, messagesPage) { ...}); +const messagesPage = channel.history({start: ..., end: ..., limit: ..., direction: ...}); ``` ### Getting the status of a channel ```javascript -channel.status(function(err, channelDetails) { - channelDetails.channelId // The name of the channel - channelDetails.status.isActive // A boolean indicating whether the channel is active - channelDetails.status.occupancy // Contains metadata relating to the occupants of the channel -}); +const channelDetails = await channel.status(); +channelDetails.channelId // The name of the channel +channelDetails.status.isActive // A boolean indicating whether the channel is active +channelDetails.status.occupancy // Contains metadata relating to the occupants of the channel ``` ### Generate Token and Token Request @@ -438,134 +387,49 @@ explanation of Ably's authentication mechanism. Requesting a token: ```javascript -client.auth.requestToken(function(err, tokenDetails) { - // tokenDetails is instance of TokenDetails - // see https://www.ably.com/docs/rest/authentication/#token-details for its properties +const tokenDetails = await client.auth.requestToken(); +// tokenDetails is instance of TokenDetails +// see https://www.ably.com/docs/rest/authentication/#token-details for its properties - // Now we have the token, we can send it to someone who can instantiate a client with it: - var clientUsingToken = new Ably.Realtime(tokenDetails.token); -}); +// Now we have the token, we can send it to someone who can instantiate a client with it: +var clientUsingToken = new Ably.Realtime(tokenDetails.token); // requestToken can take two optional params // tokenParams: https://www.ably.com/docs/rest/authentication/#token-params // authOptions: https://www.ably.com/docs/rest/authentication/#auth-options -client.auth.requestToken(tokenParams, authOptions, function(err, tokenDetails) { ... }); +const tokenDetails = await client.auth.requestToken(tokenParams, authOptions); ``` Creating a token request (for example, on a server in response to a request by a client using the `authCallback` or `authUrl` mechanisms): ```javascript -client.auth.createTokenRequest(function(err, tokenRequest) { - // now send the tokenRequest back to the client, which will - // use it to request a token and connect to Ably -}); +const tokenRequest = await client.auth.createTokenRequest(); +// now send the tokenRequest back to the client, which will +// use it to request a token and connect to Ably // createTokenRequest can take two optional params // tokenParams: https://www.ably.com/docs/rest/authentication/#token-params // authOptions: https://www.ably.com/docs/rest/authentication/#auth-options -client.auth.createTokenRequest(tokenParams, authOptions, function(err, tokenRequest) { ... }); +const tokenRequest = await client.auth.createTokenRequest(tokenParams, authOptions); ``` ### Fetching your application's stats ```javascript -client.stats(function(err, statsPage) { // statsPage as PaginatedResult - statsPage.items // array of Stats - statsPage.items[0].inbound.rest.messages.count; // total messages published over REST - statsPage.items.length; // number of stats in the current page of history - statsPage.hasNext() // true if there are further pages - statsPage.isLast() // true if this page is the last page - statsPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult -}); +const statsPage = await client.stats() // statsPage as PaginatedResult +statsPage.items // array of Stats +statsPage.items[0].inbound.rest.messages.count; // total messages published over REST +statsPage.items.length; // number of stats in the current page of history +statsPage.hasNext() // true if there are further pages +statsPage.isLast() // true if this page is the last page +const nextPage = await statsPage.next(); // retrieves the next page as PaginatedResult ``` ### Fetching the Ably service time ```javascript -client.time(function(err, time) { ... }); // time is in ms since epoch -``` - -## Using the async API style - -### Realtime Example - -```ts -import * as Ably from 'ably/promises'; - -const client = new Ably.Realtime.Promise(options); - -const ablyRealtimePromiseExample = async () => { - const channel = client.channels.get('myChannel'); - - // Attaching to a channel - await channel.attach(); - - // Getting presence on a channel - const presenceMessage = await channel.presence.get(); - console.log(presenceMessage); - - // Updating presence on a client - await channel.presence.enter(); - await channel.presence.update('new status'); - await channel.presence.leave(); - - // Publishing a message - await channel.publish('greeting', 'Hello, World!'); - - // Querying history - const history = await channel.history({ limit: 25 }); - console.log(history); - - client.close(); -}; - -ablyRealtimePromiseExample(); -``` - -### REST Example - -```ts -import * as Ably from 'ably/promises'; - -const client = new Ably.Rest.Promise(options); - -const ablyRestPromiseExample = async () => { - const channel = client.channels.get('myChannel'); - - // Publishing a message - await channel.publish('greeting', 'Hello, World!'); - - // Getting presence on a channel - const presenceMessage = await channel.presence.get(); - console.log(presenceMessage); - - // Querying history - const history = await channel.history({ limit: 25 }); - console.log(await history.current()); - - // Getting the status of a channel - const channelDetails = await channel.status(); - console.log(channelDetails); - - // Requesting a token - const token = await client.auth.requestToken(tokenParams); - - // Creating a token request - const tokenRequest = await client.auth.createTokenRequest(); - - // Fetching your application's stats - const stats = await client.stats(); - console.log(stats); - - // Fetching the Ably service time - const time = await client.time(); - console.log(`Ably service time: ${time}`); - - client.close(); -}; - -ablyRestPromiseExample(); +const time = await client.time(); // time is in ms since epoch ``` ## Delta Plugin diff --git a/ably.d.ts b/ably.d.ts index f3f4a028d7..a276fade46 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -41,7 +41,7 @@ declare namespace Types { type FAILED = 'failed'; } /** - * Describes the possible states of a {@link ChannelBase} or {@link RealtimeChannelBase} object. + * Describes the possible states of a {@link Channel} or {@link RealtimeChannel} object. */ type ChannelState = | ChannelState.FAILED @@ -90,7 +90,7 @@ declare namespace Types { type UPDATE = 'update'; } /** - * Describes the events emitted by a {@link ChannelBase} or {@link RealtimeChannelBase} object. An event is either an `UPDATE` or a {@link ChannelState}. + * Describes the events emitted by a {@link Channel} or {@link RealtimeChannel} object. An event is either an `UPDATE` or a {@link ChannelState}. */ type ChannelEvent = | ChannelEvent.FAILED @@ -123,7 +123,7 @@ declare namespace Types { */ type DISCONNECTED = 'disconnected'; /** - * A long term failure condition. No current connection exists because there is no network connectivity or no host is available. The suspended state is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended state, the library will periodically attempt to open a new connection every 30 seconds. Developers are unable to publish messages in this state. A new connection attempt can also be triggered by an explicit call to {@link ConnectionBase.connect | `connect()`}. Once the connection has been re-established, channels will be automatically re-attached. The client has been disconnected for too long for them to resume from where they left off, so if it wants to catch up on messages published by other clients while it was disconnected, it needs to use the [History API](https://ably.com/docs/realtime/history). + * A long term failure condition. No current connection exists because there is no network connectivity or no host is available. The suspended state is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended state, the library will periodically attempt to open a new connection every 30 seconds. Developers are unable to publish messages in this state. A new connection attempt can also be triggered by an explicit call to {@link Connection.connect | `connect()`}. Once the connection has been re-established, channels will be automatically re-attached. The client has been disconnected for too long for them to resume from where they left off, so if it wants to catch up on messages published by other clients while it was disconnected, it needs to use the [History API](https://ably.com/docs/realtime/history). */ type SUSPENDED = 'suspended'; /** @@ -131,16 +131,16 @@ declare namespace Types { */ type CLOSING = 'closing'; /** - * The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. No connection state is preserved by the service or by the library. A new connection attempt can be triggered by an explicit call to {@link ConnectionBase.connect | `connect()`}, which results in a new connection. + * The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. No connection state is preserved by the service or by the library. A new connection attempt can be triggered by an explicit call to {@link Connection.connect | `connect()`}, which results in a new connection. */ type CLOSED = 'closed'; /** - * This state is entered if the client library encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, for example an attempt to connect with an incorrect API key, or a local terminal error, for example the token in use has expired and the library does not have any way to renew it. In the failed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. A new connection attempt can be triggered by an explicit call to {@link ConnectionBase.connect | `connect()`}. + * This state is entered if the client library encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, for example an attempt to connect with an incorrect API key, or a local terminal error, for example the token in use has expired and the library does not have any way to renew it. In the failed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. A new connection attempt can be triggered by an explicit call to {@link Connection.connect | `connect()`}. */ type FAILED = 'failed'; } /** - * Describes the realtime {@link ConnectionBase} object states. + * Describes the realtime {@link Connection} object states. */ type ConnectionState = | ConnectionState.INITIALIZED @@ -173,7 +173,7 @@ declare namespace Types { */ type DISCONNECTED = 'disconnected'; /** - * A long term failure condition. No current connection exists because there is no network connectivity or no host is available. The suspended state is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended state, the library will periodically attempt to open a new connection every 30 seconds. Developers are unable to publish messages in this state. A new connection attempt can also be triggered by an explicit call to {@link ConnectionBase.connect | `connect()`}. Once the connection has been re-established, channels will be automatically re-attached. The client has been disconnected for too long for them to resume from where they left off, so if it wants to catch up on messages published by other clients while it was disconnected, it needs to use the [History API](https://ably.com/docs/realtime/history). + * A long term failure condition. No current connection exists because there is no network connectivity or no host is available. The suspended state is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended state, the library will periodically attempt to open a new connection every 30 seconds. Developers are unable to publish messages in this state. A new connection attempt can also be triggered by an explicit call to {@link Connection.connect | `connect()`}. Once the connection has been re-established, channels will be automatically re-attached. The client has been disconnected for too long for them to resume from where they left off, so if it wants to catch up on messages published by other clients while it was disconnected, it needs to use the [History API](https://ably.com/docs/realtime/history). */ type SUSPENDED = 'suspended'; /** @@ -181,11 +181,11 @@ declare namespace Types { */ type CLOSING = 'closing'; /** - * The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. No connection state is preserved by the service or by the library. A new connection attempt can be triggered by an explicit call to {@link ConnectionBase.connect | `connect()`}, which results in a new connection. + * The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. No connection state is preserved by the service or by the library. A new connection attempt can be triggered by an explicit call to {@link Connection.connect | `connect()`}, which results in a new connection. */ type CLOSED = 'closed'; /** - * This state is entered if the client library encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, for example an attempt to connect with an incorrect API key, or a local terminal error, for example the token in use has expired and the library does not have any way to renew it. In the failed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. A new connection attempt can be triggered by an explicit call to {@link ConnectionBase.connect | `connect()`}. + * This state is entered if the client library encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, for example an attempt to connect with an incorrect API key, or a local terminal error, for example the token in use has expired and the library does not have any way to renew it. In the failed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. A new connection attempt can be triggered by an explicit call to {@link Connection.connect | `connect()`}. */ type FAILED = 'failed'; /** @@ -194,7 +194,7 @@ declare namespace Types { type UPDATE = 'update'; } /** - * Describes the events emitted by a {@link ConnectionBase} object. An event is either an `UPDATE` or a {@link ConnectionState}. + * Describes the events emitted by a {@link Connection} object. An event is either an `UPDATE` or a {@link ConnectionState}. */ type ConnectionEvent = | ConnectionEvent.INITIALIZED @@ -296,7 +296,7 @@ declare namespace Types { type Transport = 'web_socket' | 'xhr_streaming' | 'xhr_polling' | 'comet'; /** - * Contains the details of a {@link ChannelBase} or {@link RealtimeChannelBase} object such as its ID and {@link ChannelStatus}. + * Contains the details of a {@link Channel} or {@link RealtimeChannel} object such as its ID and {@link ChannelStatus}. */ interface ChannelDetails { /** @@ -310,7 +310,7 @@ declare namespace Types { } /** - * Contains the status of a {@link ChannelBase} or {@link RealtimeChannelBase} object such as whether it is active and its {@link ChannelOccupancy}. + * Contains the status of a {@link Channel} or {@link RealtimeChannel} object such as whether it is active and its {@link ChannelOccupancy}. */ interface ChannelStatus { /** @@ -324,7 +324,7 @@ declare namespace Types { } /** - * Contains the metrics of a {@link ChannelBase} or {@link RealtimeChannelBase} object. + * Contains the metrics of a {@link Channel} or {@link RealtimeChannel} object. */ interface ChannelOccupancy { /** @@ -334,7 +334,7 @@ declare namespace Types { } /** - * Contains the metrics associated with a {@link ChannelBase} or {@link RealtimeChannelBase}, such as the number of publishers, subscribers and connections it has. + * Contains the metrics associated with a {@link Channel} or {@link RealtimeChannel}, such as the number of publishers, subscribers and connections it has. */ interface ChannelMetrics { /** @@ -364,11 +364,11 @@ declare namespace Types { } /** - * Passes additional client-specific properties to the REST {@link RestBase.constructor | `constructor()`} or the Realtime {@link RealtimeBase.constructor | `constructor()`}. + * Passes additional client-specific properties to the REST {@link Rest.constructor | `constructor()`} or the Realtime {@link Realtime.constructor | `constructor()`}. */ interface ClientOptions extends AuthOptions { /** - * When `true`, the client connects to Ably as soon as it is instantiated. You can set this to `false` and explicitly connect to Ably using the {@link ConnectionBase.connect | `connect()`} method. The default is `true`. + * When `true`, the client connects to Ably as soon as it is instantiated. You can set this to `false` and explicitly connect to Ably using the {@link Connection.connect | `connect()`} method. The default is `true`. * * @defaultValue `true` */ @@ -704,7 +704,7 @@ declare namespace Types { } /** - * Sets the properties to configure encryption for a {@link ChannelBase} or {@link RealtimeChannelBase} object. + * Sets the properties to configure encryption for a {@link Channel} or {@link RealtimeChannel} object. */ interface CipherParams { /** @@ -890,7 +890,7 @@ declare namespace Types { } /** - * Contains the properties of a request for a token to Ably. Tokens are generated using {@link AuthCallbacks.requestToken} or {@link AuthPromise.requestToken}. + * Contains the properties of a request for a token to Ably. Tokens are generated using {@link Auth.requestToken}. */ interface TokenRequest { /** @@ -971,7 +971,7 @@ declare namespace Types { type ChannelModes = Array; /** - * Passes additional properties to a {@link ChannelBase} or {@link RealtimeChannelBase} object, such as encryption, {@link ChannelMode} and channel parameters. + * Passes additional properties to a {@link Channel} or {@link RealtimeChannel} object, such as encryption, {@link ChannelMode} and channel parameters. */ interface ChannelOptions { /** @@ -989,7 +989,7 @@ declare namespace Types { } /** - * Passes additional properties to a {@link RealtimeChannelBase} name to produce a new derived channel + * Passes additional properties to a {@link RealtimeChannel} name to produce a new derived channel */ interface DeriveOptions { /** @@ -1001,10 +1001,8 @@ declare namespace Types { /** * The `RestHistoryParams` interface describes the parameters accepted by the following methods: * - * - {@link PresenceCallbacks.history} - * - {@link PresencePromise.history} - * - {@link ChannelCallbacks.history} - * - {@link ChannelPromise.history} + * - {@link Presence.history} + * - {@link Channel.history} */ interface RestHistoryParams { /** @@ -1032,10 +1030,7 @@ declare namespace Types { } /** - * The `RestPresenceParams` interface describes the parameters accepted by the following methods: - * - * - {@link PresenceCallbacks.get} - * - {@link PresencePromise.get} + * The `RestPresenceParams` interface describes the parameters accepted by {@link Presence.get}. */ interface RestPresenceParams { /** @@ -1055,10 +1050,7 @@ declare namespace Types { } /** - * The `RealtimePresenceParams` interface describes the parameters accepted by the following methods: - * - * - {@link RealtimePresenceCallbacks.get} - * - {@link RealtimePresencePromise.get} + * The `RealtimePresenceParams` interface describes the parameters accepted by {@link RealtimePresence.get}. */ interface RealtimePresenceParams { /** @@ -1080,10 +1072,8 @@ declare namespace Types { /** * The `RealtimeHistoryParams` interface describes the parameters accepted by the following methods: * - * - {@link RealtimePresenceCallbacks.history} - * - {@link RealtimePresencePromise.history} - * - {@link RealtimeChannelCallbacks.history} - * - {@link RealtimeChannelPromise.history} + * - {@link RealtimePresence.history} + * - {@link RealtimeChannel.history} */ interface RealtimeHistoryParams { /** @@ -1115,7 +1105,7 @@ declare namespace Types { } /** - * Contains state change information emitted by {@link ChannelBase} and {@link RealtimeChannelBase} objects. + * Contains state change information emitted by {@link Channel} and {@link RealtimeChannel} objects. */ interface ChannelStateChange { /** @@ -1137,7 +1127,7 @@ declare namespace Types { } /** - * Contains {@link ConnectionState} change information emitted by the {@link ConnectionBase} object. + * Contains {@link ConnectionState} change information emitted by the {@link Connection} object. */ interface ConnectionStateChange { /** @@ -1310,10 +1300,8 @@ declare namespace Types { /** * The `DeviceRegistrationParams` interface describes the parameters accepted by the following methods: * - * - {@link PushDeviceRegistrationsCallbacks.list} - * - {@link PushDeviceRegistrationsCallbacks.removeWhere} - * - {@link PushDeviceRegistrationsPromise.list} - * - {@link PushDeviceRegistrationsPromise.removeWhere} + * - {@link PushDeviceRegistrations.list} + * - {@link PushDeviceRegistrations.removeWhere} */ interface DeviceRegistrationParams { /** @@ -1337,10 +1325,8 @@ declare namespace Types { /** * The `PushChannelSubscriptionParams` interface describes the parameters accepted by the following methods: * - * - {@link PushChannelSubscriptionsCallbacks.list} - * - {@link PushChannelSubscriptionsCallbacks.removeWhere} - * - {@link PushChannelSubscriptionsPromise.list} - * - {@link PushChannelSubscriptionsPromise.removeWhere} + * - {@link PushChannelSubscriptions.list} + * - {@link PushChannelSubscriptions.removeWhere} */ interface PushChannelSubscriptionParams { /** @@ -1362,10 +1348,7 @@ declare namespace Types { } /** - * The `PushChannelsParams` interface describes the parameters accepted by the following methods: - * - * - {@link PushChannelSubscriptionsCallbacks.listChannels} - * - {@link PushChannelSubscriptionsPromise.listChannels} + * The `PushChannelsParams` interface describes the parameters accepted by {@link PushChannelSubscriptions.listChannels}. */ interface PushChannelsParams { /** @@ -1377,10 +1360,8 @@ declare namespace Types { /** * The `StatsParams` interface describes the parameters accepted by the following methods: * - * - {@link RestCallbacks.stats} - * - {@link RestPromise.stats} - * - {@link RealtimeCallbacks.stats} - * - {@link RealtimePromise.stats} + * - {@link Rest.stats} + * - {@link Realtime.stats} */ interface StatsParams { /** @@ -1417,64 +1398,23 @@ declare namespace Types { // Common Listeners /** - * A standard callback format used in most areas of the callback API. - * - * @param err - An error object if the request failed. - * @param result - The result of the request, if any. - */ - type StandardCallback = (err: ErrorInfo | null, result?: T) => void; - /** - * A {@link StandardCallback} which returns a {@link PaginatedResult}. - */ - type paginatedResultCallback = StandardCallback>; - /** - * A callback which returns only a single argument, used for {@link RealtimeChannelBase} subscriptions. + * A callback which returns only a single argument, used for {@link RealtimeChannel} subscriptions. * * @param message - The message which triggered the callback. */ type messageCallback = (message: T) => void; /** - * A callback which returns only an error, or null, when complete. - * - * @param error - The error if the request failed, or null not. - */ - type errorCallback = (error?: ErrorInfo | null) => void; - /** - * The callback used by {@link RealtimeChannelCallbacks.whenState}. + * The callback used for the events emitted by {@link RealtimeChannel}. * * @param changeStateChange - The state change that occurred. */ type channelEventCallback = (changeStateChange: ChannelStateChange) => void; /** - * The callback used by {@link ConnectionCallbacks.whenState}. + * The callback used for the events emitted by {@link Connection}. * * @param connectionStateChange - The state change that occurred. */ type connectionEventCallback = (connectionStateChange: ConnectionStateChange) => void; - /** - * The callback used by {@link RestCallbacks.time} and {@link RealtimeCallbacks.time}. - * - * @param timeCallback - The time in milliseconds since the Unix epoch. - */ - type timeCallback = StandardCallback; - /** - * The callback used by {@link RealtimePresenceCallbacks.get}. - * - * @param realtimePresenceGetCallback - An array of {@link PresenceMessage} objects. - */ - type realtimePresenceGetCallback = StandardCallback; - /** - * The callback used by {@link AuthCallbacks.authorize}. - * - * @param tokenDetailsCallback - A {@link TokenDetails} object. - */ - type tokenDetailsCallback = StandardCallback; - /** - * The callback used by {@link AuthCallbacks.createTokenRequest}. - * - * @param tokenRequestCallback - A {@link TokenRequest} object - */ - type tokenRequestCallback = StandardCallback; /** * The callback used by {@link recoverConnectionCallback}. * @@ -1516,7 +1456,7 @@ declare namespace Types { // that returns a Promise if desired, EventEmitter uses method overloading to // present both methods /** - * A generic interface for event registration and delivery used in a number of the types in the Realtime client library. For example, the {@link ConnectionBase} object emits events for connection state using the `EventEmitter` pattern. + * A generic interface for event registration and delivery used in a number of the types in the Realtime client library. For example, the {@link Connection} object emits events for connection state using the `EventEmitter` pattern. */ class EventEmitter { /** @@ -1592,9 +1532,9 @@ declare namespace Types { // Classes /** - * The `RestBase` class acts as a base class for the {@link RestCallbacks} and {@link RestPromise} classes. + * A client that offers a simple stateless API to interact directly with Ably's REST API. */ - class RestBase { + class Rest { /** * Construct a client object using an Ably {@link Types.ClientOptions} object. * @@ -1619,93 +1559,15 @@ declare namespace Types { * Static utilities related to presence messages. */ static PresenceMessage: Types.PresenceMessageStatic; - } - - /** - * A client that offers a simple stateless API to interact directly with Ably's REST API. - */ - class RestCallbacks extends RestBase { - /** - * A promisified version of the library (use this if you prefer to use Promises or async/await instead of callbacks) - */ - static Promise: typeof Types.RestPromise; - /** - * A callback based version of the library - */ - static Callbacks: typeof Types.RestCallbacks; - /** - * An {@link Types.AuthCallbacks} object. - */ - auth: Types.AuthCallbacks; - /** - * A {@link Types.Channels} object. - */ - channels: Types.Channels; - /** - * Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support. - * - * @param method - The request method to use, such as `GET`, `POST`. - * @param path - The request path. - * @param version - The major version of the Ably REST API to use. See the [REST API reference](https://ably.com/docs/api/rest-api#versioning) for information on versioning. - * @param params - The parameters to include in the URL query of the request. The parameters depend on the endpoint being queried. See the [REST API reference](https://ably.com/docs/api/rest-api) for the available parameters of each endpoint. - * @param body - The JSON body of the request. - * @param headers - Additional HTTP headers to include in the request. - * @param callback - A function which, upon success, will be called with an {@link Types.HttpPaginatedResponse} response object returned by the HTTP request. This response object will contain an empty or JSON-encodable object. Upon failure, the function will be called with information about the error. - */ - request( - method: string, - path: string, - version: number, - params?: any, - body?: any[] | any, - headers?: any, - callback?: Types.StandardCallback> - ): void; - /** - * Queries the REST `/stats` API and retrieves your application's usage statistics. Returns a {@link Types.PaginatedResult} object, containing an array of {@link Types.Stats} objects. See the [Stats docs](https://ably.com/docs/general/statistics). - * - * @param params - A set of parameters which are used to specify which statistics should be retrieved. This parameter should be a {@link Types.StatsParams} object. For reasons of backwards compatibility this parameter will also accept `any`; this ability will be removed in the next major release of this SDK. If you do not provide this argument, then this method will use the default parameters described in the {@link Types.StatsParams} interface. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Types.Stats} objects. Upon failure, the function will be called with information about the error. - */ - stats(params?: StatsParams | any, callback?: Types.paginatedResultCallback): void; - /** - * Queries the REST `/stats` API and retrieves your application's usage statistics, using the default parameters described in the {@link Types.StatsParams} interface. Returns a {@link Types.PaginatedResult} object, containing an array of {@link Types.Stats} objects. See the [Stats docs](https://ably.com/docs/general/statistics). - * - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Types.Stats} objects. Upon failure, the function will be called with information about the error. - */ - stats(callback?: Types.paginatedResultCallback): void; - /** - * Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably {@link Types.TokenRequest | `TokenRequest`s} with a more accurate timestamp should use the {@link Types.ClientOptions.queryTime} property instead of this method. - * - * @param callback - A function which, upon success, will be called with the time as milliseconds since the Unix epoch. Upon failure, the function will be called with information about the error. - */ - time(callback?: Types.timeCallback): void; - /** - * A {@link Types.PushCallbacks} object. - */ - push: Types.PushCallbacks; - } - /** - * A client that offers a simple stateless API to interact directly with Ably's REST API. - */ - class RestPromise extends RestBase { - /** - * A promisified version of the library (use this if you prefer to use Promises or async/await instead of callbacks) - */ - static Promise: typeof Types.RestPromise; - /** - * A callback based version of the library - */ - static Callbacks: typeof Types.RestCallbacks; /** - * An {@link Types.AuthPromise} object. + * An {@link Types.Auth} object. */ - auth: Types.AuthPromise; + auth: Types.Auth; /** * A {@link Types.Channels} object. */ - channels: Types.Channels; + channels: Types.Channels; /** * Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support. * @@ -1739,114 +1601,64 @@ declare namespace Types { */ time(): Promise; /** - * A {@link Types.PushPromise} object. - */ - push: Types.PushPromise; - } - - /** - * A base class used internally for Realtime APIs. - */ - class RealtimeBase extends RestBase { - /** - * A promisified version of the library (use this if you prefer to use Promises or async/await instead of callbacks) - */ - static Promise: typeof Types.RealtimePromise; - /** - * A callback based version of the library - */ - static Callbacks: typeof Types.RealtimeCallbacks; - /** - * A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string, except it cannot contain a `*`. This option is primarily intended to be used in situations where the library is instantiated with a key. A `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. - */ - clientId: string; - /** - * Calls {@link Types.ConnectionBase.close | `connection.close()`} and causes the connection to close, entering the closing state. Once closed, the library will not attempt to re-establish the connection without an explicit call to {@link Types.ConnectionBase.connect | `connect()`}. - */ - close(): void; - /** - * Calls {@link Types.ConnectionBase.connect | `connection.connect()`} and causes the connection to open, entering the connecting state. Explicitly calling `connect()` is unnecessary unless the {@link Types.ClientOptions.autoConnect} property is disabled. + * A {@link Types.Push} object. */ - connect(): void; + push: Types.Push; } /** - * A client that extends the functionality of {@link RestCallbacks} and provides additional realtime-specific features. + * A client that extends the functionality of {@link Rest} and provides additional realtime-specific features. */ - class RealtimeCallbacks extends RealtimeBase { + class Realtime { /** - * An {@link Types.AuthCallbacks} object. + * Construct a client object using an Ably {@link Types.ClientOptions} object. + * + * @param options - A {@link Types.ClientOptions} object to configure the client connection to Ably. */ - auth: Types.AuthCallbacks; + constructor(options: Types.ClientOptions); /** - * A {@link Types.Channels} object. + * Constructs a client object using an Ably API key or token string. + * + * @param keyOrToken - The Ably API key or token string used to validate the client. */ - channels: Types.Channels; + constructor(keyOrToken: string); /** - * A {@link Types.ConnectionCallbacks} object. + * The cryptographic functions available in the library. */ - connection: Types.ConnectionCallbacks; + static Crypto: Types.Crypto; /** - * Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support. - * - * @param method - The request method to use, such as `GET`, `POST`. - * @param path - The request path. - * @param version - The major version of the Ably REST API to use. See the [REST API reference](https://ably.com/docs/api/rest-api#versioning) for information on versioning. - * @param params - The parameters to include in the URL query of the request. The parameters depend on the endpoint being queried. See the [REST API reference](https://ably.com/docs/api/rest-api) for the available parameters of each endpoint. - * @param body - The JSON body of the request. - * @param headers - Additional HTTP headers to include in the request. - * @param callback - A function which, upon success, will be called with the {@link Types.HttpPaginatedResponse} response object returned by the HTTP request. This response object will contain an empty or JSON-encodable object. Upon failure, the function will be called with information about the error. + * Static utilities related to messages. */ - request( - method: string, - path: string, - version: number, - params?: any, - body?: any[] | any, - headers?: any, - callback?: Types.StandardCallback> - ): void; + static Message: Types.MessageStatic; /** - * Queries the REST `/stats` API and retrieves your application's usage statistics. Returns a {@link Types.PaginatedResult} object, containing an array of {@link Types.Stats} objects. See the [Stats docs](https://ably.com/docs/general/statistics). - * - * @param params - A set of parameters which are used to specify which statistics should be retrieved. This parameter should be a {@link Types.StatsParams} object. For reasons of backwards compatibility this parameter will also accept `any`; this ability will be removed in the next major release of this SDK. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Types.Stats} objects. Upon failure, the function will be called with information about the error. + * Static utilities related to presence messages. */ - stats(params: StatsParams | any, callback: Types.paginatedResultCallback): void; + static PresenceMessage: Types.PresenceMessageStatic; /** - * Queries the REST `/stats` API and retrieves your application's usage statistics, using the default parameters described in the {@link Types.StatsParams} interface. Returns a {@link Types.PaginatedResult} object, containing an array of {@link Types.Stats} objects. See the [Stats docs](https://ably.com/docs/general/statistics). - * - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Types.Stats} objects. Upon failure, the function will be called with information about the error. + * A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string, except it cannot contain a `*`. This option is primarily intended to be used in situations where the library is instantiated with a key. A `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. */ - stats(callback: Types.paginatedResultCallback): void; + clientId: string; /** - * Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably {@link Types.TokenRequest | `TokenRequest`s} with a more accurate timestamp should use the {@link Types.ClientOptions.queryTime} property instead of this method. - * - * @param callback - A function which, upon success, will be called with the time as milliseconds since the Unix epoch. Upon failure, the function will be called with information about the error. + * Calls {@link Types.Connection.close | `connection.close()`} and causes the connection to close, entering the closing state. Once closed, the library will not attempt to re-establish the connection without an explicit call to {@link Types.Connection.connect | `connect()`}. */ - time(callback?: Types.timeCallback): void; + close(): void; /** - * A {@link Types.PushCallbacks} object. + * Calls {@link Types.Connection.connect | `connection.connect()`} and causes the connection to open, entering the connecting state. Explicitly calling `connect()` is unnecessary unless the {@link Types.ClientOptions.autoConnect} property is disabled. */ - push: Types.PushCallbacks; - } + connect(): void; - /** - * A client that extends the functionality of {@link RestPromise} and provides additional realtime-specific features. - */ - class RealtimePromise extends RealtimeBase { /** - * An {@link Types.AuthPromise} object. + * An {@link Types.Auth} object. */ - auth: Types.AuthPromise; + auth: Types.Auth; /** * A {@link Types.Channels} object. */ - channels: Types.Channels; + channels: Types.Channels; /** - * A {@link Types.ConnectionPromise} object. + * A {@link Types.Connection} object. */ - connection: Types.ConnectionPromise; + connection: Types.Connection; /** * Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support. * @@ -1880,102 +1692,20 @@ declare namespace Types { */ time(): Promise; /** - * A {@link Types.PushPromise} object. + * A {@link Types.Push} object. */ - push: Types.PushPromise; + push: Types.Push; } /** - * The `AuthBase` class acts as a base class for the {@link AuthCallbacks} and {@link AuthPromise} classes. + * Creates Ably {@link TokenRequest} objects and obtains Ably Tokens from Ably to subsequently issue to less trusted clients. */ - class AuthBase { + class Auth { /** * A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string, except it cannot contain a `*`. This option is primarily intended to be used in situations where the library is instantiated with a key. Note that a `clientId` may also be implicit in a token used to instantiate the library. An error is raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. Find out more about [identified clients](https://ably.com/docs/core-features/authentication#identified-clients). */ clientId: string; - } - - /** - * Creates Ably {@link TokenRequest} objects and obtains Ably Tokens from Ably to subsequently issue to less trusted clients. - */ - class AuthCallbacks extends AuthBase { - /** - * Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token has been obtained. Also stores any {@link TokenParams} and {@link AuthOptions} passed in as the new defaults, to be used for all subsequent implicit or explicit token requests. Any {@link TokenParams} and {@link AuthOptions} objects passed in entirely replace, as opposed to being merged with, the current client library saved values. - * - * @param tokenParams - A {@link TokenParams} object. - * @param authOptions - An {@link AuthOptions} object. - * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. - */ - authorize(tokenParams?: TokenParams, authOptions?: AuthOptions, callback?: tokenDetailsCallback): void; - /** - * Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token has been obtained. Also stores any {@link TokenParams} passed in as the new default, to be used for all subsequent implicit or explicit token requests. Any {@link TokenParams} object passed in entirely replaces, as opposed to being merged with, the current client library saved value. - * - * @param tokenParams - A {@link TokenParams} object. - * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. - */ - authorize(tokenParams?: TokenParams, callback?: tokenDetailsCallback): void; - /** - * Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token has been obtained. - * - * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. - */ - authorize(callback?: tokenDetailsCallback): void; - /** - * Creates and signs an Ably {@link TokenRequest} based on the specified (or if none specified, the client library stored) {@link TokenParams} and {@link AuthOptions}. Note this can only be used when the API `key` value is available locally. Otherwise, the Ably {@link TokenRequest} must be obtained from the key owner. Use this to generate an Ably {@link TokenRequest} in order to implement an Ably Token request callback for use by other clients. Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication). - * - * @param tokenParams - A {@link TokenParams} object. - * @param authOptions - An {@link AuthOptions} object. - * @param callback - A function which, upon success, will be called with a {@link TokenRequest} object. Upon failure, the function will be called with information about the error. - */ - createTokenRequest( - tokenParams?: TokenParams | null, - authOptions?: AuthOptions | null, - callback?: tokenRequestCallback - ): void; - /** - * Creates and signs an Ably {@link TokenRequest} based on the specified (or if none specified, the client library stored) {@link TokenParams}. Note this can only be used when the API `key` value is available locally. Otherwise, the Ably {@link TokenParams} must be obtained from the key owner. Use this to generate an Ably {@link TokenRequest} in order to implement an Ably Token request callback for use by other clients. When the {@link TokenRequest} is omitted or `null`, the default token parameters for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication). - * - * @param tokenParams - A {@link TokenParams} object. - * @param callback - A function which, upon success, will be called with a {@link TokenRequest} object. Upon failure, the function will be called with information about the error. - */ - createTokenRequest(tokenParams?: TokenParams | null, callback?: tokenRequestCallback): void; - /** - * Creates and signs an Ably {@link TokenRequest} based on the the client library stored {@link TokenParams} and {@link AuthOptions}. Note this can only be used when the API `key` value is available locally. Otherwise, the Ably {@link TokenRequest} must be obtained from the key owner. Use this to generate an Ably {@link TokenRequest} in order to implement an Ably Token request callback for use by other clients. The default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication). - * - * @param callback - A function which, upon success, will be called with a {@link TokenRequest} object. Upon failure, the function will be called with information about the error. - */ - createTokenRequest(callback?: tokenRequestCallback): void; - /** - * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication). - * - * @param TokenParams - A {@link TokenParams} object. - * @param authOptions - An {@link AuthOptions} object. - * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. - */ - requestToken( - TokenParams?: TokenParams | null, - authOptions?: AuthOptions | null, - callback?: tokenDetailsCallback - ): void; - /** - * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams}. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication). - * - * @param TokenParams - A {@link TokenParams} object. - * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. - */ - requestToken(TokenParams?: TokenParams | null, callback?: tokenDetailsCallback): void; - /** - * Calls the `requestToken` REST API endpoint to obtain an Ably Token. The default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication). - * - * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. - */ - requestToken(callback?: tokenDetailsCallback): void; - } - /** - * Creates Ably {@link TokenRequest} objects and obtains Ably Tokens from Ably to subsequently issue to less trusted clients. - */ - class AuthPromise extends AuthBase { /** * Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token has been obtained. Also stores any {@link TokenParams} and {@link AuthOptions} passed in as the new defaults, to be used for all subsequent implicit or explicit token requests. Any {@link TokenParams} and {@link AuthOptions} objects passed in entirely replace, as opposed to being merged with, the current client library saved values. * @@ -2005,39 +1735,7 @@ declare namespace Types { /** * Enables the retrieval of the current and historic presence set for a channel. */ - class PresenceCallbacks { - /** - * Retrieves the current members present on the channel and the metadata for each member, such as their {@link PresenceAction} and ID. Returns a {@link Types.PaginatedResult} object, containing an array of {@link PresenceMessage} objects. - * - * @param params - A set of parameters which are used to specify which presence members should be retrieved. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. - */ - get(params?: RestPresenceParams, callback?: paginatedResultCallback): void; - /** - * Retrieves the current members present on the channel and the metadata for each member, such as their [PresenceAction]{@link PresenceAction} and ID. - * - * @param callback - A function which, upon success, will be called with a [PaginatedResult]{@link PaginatedResult} object, containing an array of [PresenceMessage]{@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. - */ - get(callback?: paginatedResultCallback): void; - /** - * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link PresenceMessage} objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past. - * - * @param params - A set of parameters which are used to specify which messages should be retrieved. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. - */ - history(params: RestHistoryParams, callback?: paginatedResultCallback): void; - /** - * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link PresenceMessage} objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past. - * - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. - */ - history(callback: paginatedResultCallback): void; - } - - /** - * Enables the retrieval of the current and historic presence set for a channel. - */ - class PresencePromise { + class Presence { /** * Retrieves the current members present on the channel and the metadata for each member, such as their {@link PresenceAction} and ID. Returns a {@link Types.PaginatedResult} object, containing an array of {@link PresenceMessage} objects. * @@ -2055,9 +1753,9 @@ declare namespace Types { } /** - * The `RealtimePresenceBase` class acts as a base class for the {@link RealtimePresenceCallbacks} and {@link RealtimePresencePromise} classes. + * Enables the presence set to be entered and subscribed to, and the historic presence set to be retrieved for a channel. */ - class RealtimePresenceBase { + class RealtimePresence { /** * Indicates whether the presence set synchronization between Ably and the clients on the channel has been completed. Set to `true` when the sync is complete. */ @@ -2098,203 +1796,76 @@ declare namespace Types { * Deregisters all listeners currently receiving {@link PresenceMessage} for the channel. */ unsubscribe(): void; - } - /** - * Enables the presence set to be entered and subscribed to, and the historic presence set to be retrieved for a channel. - */ - class RealtimePresenceCallbacks extends RealtimePresenceBase { /** * Retrieves the current members present on the channel and the metadata for each member, such as their {@link PresenceAction} and ID. Returns an array of {@link PresenceMessage} objects. * * @param params - A set of parameters which are used to specify which presence members should be retrieved. - * @param callback - A function which, upon success, will be called with an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. - */ - get(params?: RealtimePresenceParams, callback?: realtimePresenceGetCallback): void; - /** - * Retrieves the current members present on the channel and the metadata for each member, such as their {@link PresenceAction} and ID. Returns an array of {@link PresenceMessage} objects. - * - * @param callback - A function which, upon success, will be called with an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. + * @returns A promise which, upon success, will be fulfilled with an array of {@link PresenceMessage} objects. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. */ - get(callback?: realtimePresenceGetCallback): void; + get(params?: RealtimePresenceParams): Promise; /** * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link PresenceMessage} objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past. * * @param params - A set of parameters which are used to specify which presence messages should be retrieved. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. - */ - history(params?: RealtimeHistoryParams, callback?: paginatedResultCallback): void; - /** - * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link PresenceMessage} objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past. - * - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. + * @returns A promise which, upon success, will be fulfilled with a {@link Types.PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. */ - history(callback?: paginatedResultCallback): void; + history(params?: RealtimeHistoryParams): Promise>; /** * Registers a listener that is called each time a {@link PresenceMessage} matching a given {@link PresenceAction}, or an action within an array of {@link PresenceAction | `PresenceAction`s}, is received on the channel, such as a new member entering the presence set. * - * @param presence - A {@link PresenceAction} or an array of {@link PresenceAction | `PresenceAction`s} to register the listener for. + * @param action - A {@link PresenceAction} or an array of {@link PresenceAction | `PresenceAction`s} to register the listener for. * @param listener - An event listener function. - * @param callbackWhenAttached - A function which will be called upon completion of the channel {@link RealtimeChannelCallbacks.attach | `attach()`} operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. */ subscribe( - presence: PresenceAction | Array, - listener?: messageCallback, - callbackWhenAttached?: errorCallback - ): void; + action: PresenceAction | Array, + listener?: messageCallback + ): Promise; /** * Registers a listener that is called each time a {@link PresenceMessage} is received on the channel, such as a new member entering the presence set. * * @param listener - An event listener function. - * @param callbackWhenAttached - A function which will be called upon completion of the channel {@link RealtimeChannelCallbacks.attach | `attach()`} operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. */ - subscribe(listener: messageCallback, callbackWhenAttached?: errorCallback): void; + subscribe(listener?: messageCallback): Promise; /** - * Enters the presence set for the channel, passing a `data` payload. A `clientId` is required to be present on a channel. + * Enters the presence set for the channel, optionally passing a `data` payload. A `clientId` is required to be present on a channel. * * @param data - The payload associated with the presence member. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - enter(data?: any, callback?: errorCallback): void; - /** - * Enters the presence set for the channel. A `clientId` is required to be present on a channel. - * - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. */ - enter(callback?: errorCallback): void; + enter(data?: any): Promise; /** * Updates the `data` payload for a presence member. If called before entering the presence set, this is treated as an {@link PresenceAction.ENTER} event. * * @param data - The payload to update for the presence member. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. */ - update(data?: any, callback?: errorCallback): void; + update(data?: any): Promise; /** * Leaves the presence set for the channel. A client must have previously entered the presence set before they can leave it. * * @param data - The payload associated with the presence member. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - leave(data?: any, callback?: errorCallback): void; - /** - * Leaves the presence set for the channel. A client must have previously entered the presence set before they can leave it. - * - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. */ - leave(callback?: errorCallback): void; + leave(data?: any): Promise; /** * Enters the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. * * @param clientId - The ID of the client to enter into the presence set. * @param data - The payload associated with the presence member. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - enterClient(clientId: string, data?: any, callback?: errorCallback): void; - /** - * Enters the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. - * - * @param clientId - The ID of the client to enter into the presence set. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. */ - enterClient(clientId: string, callback?: errorCallback): void; + enterClient(clientId: string, data?: any): Promise; /** * Updates the `data` payload for a presence member using a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. * * @param clientId - The ID of the client to update in the presence set. * @param data - The payload to update for the presence member. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. */ - updateClient(clientId: string, data?: any, callback?: errorCallback): void; - /** - * Leaves the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. - * - * @param clientId - The ID of the client to leave the presence set for. - * @param data - The payload associated with the presence member. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - leaveClient(clientId: string, data?: any, callback?: errorCallback): void; - /** - * Leaves the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. - * - * @param clientId - The ID of the client to leave the presence set for. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - leaveClient(clientId: string, callback?: errorCallback): void; - } - - /** - * Enables the presence set to be entered and subscribed to, and the historic presence set to be retrieved for a channel. - */ - class RealtimePresencePromise extends RealtimePresenceBase { - /** - * Retrieves the current members present on the channel and the metadata for each member, such as their {@link PresenceAction} and ID. Returns an array of {@link PresenceMessage} objects. - * - * @param params - A set of parameters which are used to specify which presence members should be retrieved. - * @returns A promise which, upon success, will be fulfilled with an array of {@link PresenceMessage} objects. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. - */ - get(params?: RealtimePresenceParams): Promise; - /** - * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link PresenceMessage} objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past. - * - * @param params - A set of parameters which are used to specify which presence messages should be retrieved. - * @returns A promise which, upon success, will be fulfilled with a {@link Types.PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. - */ - history(params?: RealtimeHistoryParams): Promise>; - /** - * Registers a listener that is called each time a {@link PresenceMessage} matching a given {@link PresenceAction}, or an action within an array of {@link PresenceAction | `PresenceAction`s}, is received on the channel, such as a new member entering the presence set. - * - * @param action - A {@link PresenceAction} or an array of {@link PresenceAction | `PresenceAction`s} to register the listener for. - * @param listener - An event listener function. - * @returns A promise which resolves upon success of the channel {@link RealtimeChannelPromise.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. - */ - subscribe( - action: PresenceAction | Array, - listener?: messageCallback - ): Promise; - /** - * Registers a listener that is called each time a {@link PresenceMessage} is received on the channel, such as a new member entering the presence set. - * - * @param listener - An event listener function. - * @returns A promise which resolves upon success of the channel {@link RealtimeChannelPromise.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. - */ - subscribe(listener?: messageCallback): Promise; - /** - * Enters the presence set for the channel, optionally passing a `data` payload. A `clientId` is required to be present on a channel. - * - * @param data - The payload associated with the presence member. - * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. - */ - enter(data?: any): Promise; - /** - * Updates the `data` payload for a presence member. If called before entering the presence set, this is treated as an {@link PresenceAction.ENTER} event. - * - * @param data - The payload to update for the presence member. - * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. - */ - update(data?: any): Promise; - /** - * Leaves the presence set for the channel. A client must have previously entered the presence set before they can leave it. - * - * @param data - The payload associated with the presence member. - * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. - */ - leave(data?: any): Promise; - /** - * Enters the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. - * - * @param clientId - The ID of the client to enter into the presence set. - * @param data - The payload associated with the presence member. - * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. - */ - enterClient(clientId: string, data?: any): Promise; - /** - * Updates the `data` payload for a presence member using a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. - * - * @param clientId - The ID of the client to update in the presence set. - * @param data - The payload to update for the presence member. - * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. - */ - updateClient(clientId: string, data?: any): Promise; + updateClient(clientId: string, data?: any): Promise; /** * Leaves the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. * @@ -2306,83 +1877,18 @@ declare namespace Types { } /** - * The `ChannelBase` class acts as a base class for the {@link ChannelCallbacks} and {@link ChannelPromise} classes. + * Enables messages to be published and historic messages to be retrieved for a channel. */ - class ChannelBase { + class Channel { /** * The channel name. */ name: string; - } - /** - * Enables messages to be published and historic messages to be retrieved for a channel. - */ - class ChannelCallbacks extends ChannelBase { /** - * A {@link PresenceCallbacks} object. + * A {@link Presence} object. */ - presence: PresenceCallbacks; - /** - * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link Message} objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past. - * - * @param params - A set of parameters which are used to specify which messages should be retrieved. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Message} objects. Upon failure, the function will be called with information about the error. - */ - history(params?: RestHistoryParams, callback?: paginatedResultCallback): void; - /** - * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link Message} objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past. - * - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Message} objects. Upon failure, the function will be called with information about the error. - */ - history(callback?: paginatedResultCallback): void; - /** - * Publishes a single message to the channel with the given event name and payload. - * - * @param name - The name of the message. - * @param data - The payload of the message. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - publish(name: string, data: any, callback?: errorCallback): void; - /** - * Publishes an array of messages to the channel. - * - * @param messages - An array of {@link Message} objects. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - publish(messages: any[], callback?: errorCallback): void; - /** - * Publishes a message to the channel. - * - * @param message - A {@link Message} object. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - publish(message: any, callback?: errorCallback): void; - /** - * Publishes a single message to the channel with the given event name and payload. - * - * @param name - The name of the message. - * @param data - The payload of the message. - * @param options - Optional parameters, such as [`quickAck`](https://faqs.ably.com/why-are-some-rest-publishes-on-a-channel-slow-and-then-typically-faster-on-subsequent-publishes) sent as part of the query string. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - publish(name: string, data: any, options?: PublishOptions, callback?: errorCallback): void; - /** - * Retrieves a {@link ChannelDetails} object for the channel, which includes status and occupancy metrics. - * - * @param callback - A function which, upon success, will be called a {@link ChannelDetails} object. Upon failure, the function will be called with information about the error. - */ - status(callback: StandardCallback): void; - } - - /** - * Enables messages to be published and historic messages to be retrieved for a channel. - */ - class ChannelPromise extends ChannelBase { - /** - * A {@link PresencePromise} object. - */ - presence: PresencePromise; + presence: Presence; /** * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link Message} objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past. * @@ -2424,9 +1930,9 @@ declare namespace Types { } /** - * The `RealtimeChannelBase` class acts as a base class for the {@link RealtimeChannelCallbacks} and {@link RealtimeChannelPromise} classes. + * Enables messages to be published and subscribed to. Also enables historic messages to be retrieved and provides access to the {@link RealtimePresence} object of a channel. */ - class RealtimeChannelBase extends EventEmitter { + class RealtimeChannel extends EventEmitter { /** * The channel name. */ @@ -2490,164 +1996,13 @@ declare namespace Types { * Deregisters all listeners to messages on this channel. This removes all earlier subscriptions. */ unsubscribe(): void; - } - - /** - * Optional parameters for message publishing. - */ - type PublishOptions = { - /** - * See [here](https://faqs.ably.com/why-are-some-rest-publishes-on-a-channel-slow-and-then-typically-faster-on-subsequent-publishes). - */ - quickAck?: boolean; - }; - - /** - * Contains properties to filter messages with when calling {@link RealtimeChannelCallbacks.subscribe | `RealtimeChannelCallbacks.subscribe()`} or {@link RealtimeChannelPromise.subscribe | `RealtimeChannelPromise.subscribe()`}. - */ - type MessageFilter = { - /** - * Filters messages by a specific message `name`. - */ - name?: string; - /** - * Filters messages by a specific `extras.ref.timeserial` value. - */ - refTimeserial?: string; - /** - * Filters messages by a specific `extras.ref.type` value. - */ - refType?: string; - /** - * Filters messages based on whether they contain an `extras.ref`. - */ - isRef?: boolean; - /** - * Filters messages by a specific message `clientId`. - */ - clientId: string; - }; - - /** - * Enables messages to be published and subscribed to. Also enables historic messages to be retrieved and provides access to the {@link RealtimePresenceCallbacks} object of a channel. - */ - class RealtimeChannelCallbacks extends RealtimeChannelBase { - /** - * A {@link RealtimePresenceCallbacks} object. - */ - presence: RealtimePresenceCallbacks; - /** - * Attach to this channel ensuring the channel is created in the Ably system and all messages published on the channel are received by any channel listeners registered using {@link RealtimeChannelCallbacks.subscribe | `subscribe()`}. Any resulting channel state change will be emitted to any listeners registered using the {@link EventEmitter.on | `on()`} or {@link EventEmitter.once | `once()`} methods. As a convenience, `attach()` is called implicitly if {@link RealtimeChannelCallbacks.subscribe | `subscribe()`} for the channel is called, or {@link RealtimePresenceCallbacks.enter | `enter()`} or {@link RealtimePresenceCallbacks.subscribe | `subscribe()`} are called on the {@link RealtimePresenceCallbacks} object for this channel. - * - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - attach(callback?: errorCallback): void; - /** - * Detach from this channel. Any resulting channel state change is emitted to any listeners registered using the {@link EventEmitter.on | `on()`} or {@link EventEmitter.once | `once()`} methods. Once all clients globally have detached from the channel, the channel will be released in the Ably service within two minutes. - * - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - detach(callback?: errorCallback): void; - /** - * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link Message} objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past. - * - * @param params - A set of parameters which are used to specify which presence members should be retrieved. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Message} objects. Upon failure, the function will be called with information about the error. - */ - history(params?: RealtimeHistoryParams, callback?: paginatedResultCallback): void; - /** - * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link Message} objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past. - * - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Message} objects. Upon failure, the function will be called with information about the error. - */ - history(callback?: paginatedResultCallback): void; - /** - * Sets the {@link ChannelOptions} for the channel. - * - * @param options - A {@link ChannelOptions} object. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - setOptions(options: ChannelOptions, callback?: errorCallback): void; - /** - * Registers a listener for messages with a given event name on this channel. The caller supplies a listener function, which is called each time one or more matching messages arrives on the channel. - * - * @param event - The event name. - * @param listener - An event listener function. - * @param callbackWhenAttached - A function which will be called upon completion of the channel {@link RealtimeChannelCallbacks.attach | `attach()`} operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - subscribe(event: string, listener?: messageCallback, callbackWhenAttached?: errorCallback): void; - /** - * Registers a listener for messages on this channel for multiple event name values. - * - * @param events - An array of event names. - * @param listener - An event listener function. - * @param callbackWhenAttached - A function which will be called upon completion of the channel {@link RealtimeChannelCallbacks.attach | `attach()`} operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - subscribe(events: Array, listener?: messageCallback, callbackWhenAttached?: errorCallback): void; - /** - * Registers a listener for messages on this channel that match the supplied filter. - * - * @param filter - A {@link MessageFilter}. - * @param listener - An event listener function. - * @param callbackWhenAttached - A function which will be called upon completion of the channel {@link RealtimeChannelCallbacks.attach | `attach()`} operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - subscribe(filter: MessageFilter, listener?: messageCallback, callbackWhenAttached?: errorCallback): void; - /** - * Registers a listener for messages on this channel. The caller supplies a listener function, which is called each time one or more messages arrives on the channel. - * - * @param listener - An event listener function. - * @param callbackWhenAttached - A function which will be called upon completion of the channel {@link RealtimeChannelCallbacks.attach | `attach()`} operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - subscribe(listener: messageCallback, callbackWhenAttached?: errorCallback): void; - /** - * Publishes a single message to the channel with the given event name and payload. When publish is called with this client library, it won't attempt to implicitly attach to the channel, so long as [transient publishing](https://ably.com/docs/realtime/channels#transient-publish) is available in the library. Otherwise, the client will implicitly attach. - * - * @param name - The event name. - * @param data - The message payload. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - publish(name: string, data: any, callback?: errorCallback): void; - /** - * Publishes an array of messages to the channel. When publish is called with this client library, it won't attempt to implicitly attach to the channel. - * - * @param messages - An array of {@link Message} objects. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - publish(messages: any[], callback?: errorCallback): void; - /** - * Publish a message to the channel. When publish is called with this client library, it won't attempt to implicitly attach to the channel. - * - * @param message - A {@link Message} object. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - publish(message: any, callback?: errorCallback): void; - /** - * Publishes a single message to the channel with the given event name and payload. When publish is called with this client library, it won't attempt to implicitly attach to the channel, so long as [transient publishing](https://ably.com/docs/realtime/channels#transient-publish) is available in the library. Otherwise, the client will implicitly attach. - * - * @param name - The event name. - * @param data - The message payload. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - publish(name: string, data: any, callback?: errorCallback): void; - /** - * Calls the supplied function when the channel reaches the specified {@link ChannelState}. If the channel is already in the specified state, the callback is called immediately. - * - * @param targetState - The state which should be reached. - * @param callback - A function which will be called when the channel has reached the specified {@link ChannelState} with a {@link ChannelStateChange} object as the first argument. - */ - whenState(targetState: ChannelState, callback: channelEventCallback): void; - } - /** - * Enables messages to be published and subscribed to. Also enables historic messages to be retrieved and provides access to the {@link RealtimePresencePromise} object of a channel. - */ - class RealtimeChannelPromise extends RealtimeChannelBase { /** - * A {@link RealtimePresencePromise} object. + * A {@link RealtimePresence} object. */ - presence: RealtimePresencePromise; + presence: RealtimePresence; /** - * Attach to this channel ensuring the channel is created in the Ably system and all messages published on the channel are received by any channel listeners registered using {@link RealtimeChannelPromise.subscribe | `subscribe()`}. Any resulting channel state change will be emitted to any listeners registered using the {@link EventEmitter.on | `on()`} or {@link EventEmitter.once | `once()`} methods. As a convenience, `attach()` is called implicitly if {@link RealtimeChannelPromise.subscribe | `subscribe()`} for the channel is called, or {@link RealtimePresencePromise.enter | `enter()`} or {@link RealtimePresencePromise.subscribe | `subscribe()`} are called on the {@link RealtimePresencePromise} object for this channel. + * Attach to this channel ensuring the channel is created in the Ably system and all messages published on the channel are received by any channel listeners registered using {@link RealtimeChannel.subscribe | `subscribe()`}. Any resulting channel state change will be emitted to any listeners registered using the {@link EventEmitter.on | `on()`} or {@link EventEmitter.once | `once()`} methods. As a convenience, `attach()` is called implicitly if {@link RealtimeChannel.subscribe | `subscribe()`} for the channel is called, or {@link RealtimePresence.enter | `enter()`} or {@link RealtimePresence.subscribe | `subscribe()`} are called on the {@link RealtimePresence} object for this channel. * * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure. */ @@ -2677,7 +2032,7 @@ declare namespace Types { * * @param event - The event name. * @param listener - An event listener function. - * @returns A promise which resolves upon success of the channel {@link RealtimeChannelPromise.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. + * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. */ subscribe(event: string, listener?: messageCallback): Promise; /** @@ -2685,7 +2040,7 @@ declare namespace Types { * * @param events - An array of event names. * @param listener - An event listener function. - * @returns A promise which resolves upon success of the channel {@link RealtimeChannelPromise.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. + * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. */ subscribe(events: Array, listener?: messageCallback): Promise; /** @@ -2693,14 +2048,14 @@ declare namespace Types { * * @param filter - A {@link MessageFilter}. * @param listener - An event listener function. - * @returns A promise which resolves upon success of the channel {@link RealtimeChannelPromise.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. + * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. */ subscribe(filter: MessageFilter, listener?: messageCallback): Promise; /** * Registers a listener for messages on this channel. The caller supplies a listener function, which is called each time one or more messages arrives on the channel. * * @param callback - An event listener function. - * @returns A promise which resolves upon success of the channel {@link RealtimeChannelPromise.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. + * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. */ subscribe(callback: messageCallback): Promise; /** @@ -2734,15 +2089,51 @@ declare namespace Types { } /** - * Creates and destroys {@link ChannelBase} and {@link RealtimeChannelBase} objects. + * Optional parameters for message publishing. + */ + type PublishOptions = { + /** + * See [here](https://faqs.ably.com/why-are-some-rest-publishes-on-a-channel-slow-and-then-typically-faster-on-subsequent-publishes). + */ + quickAck?: boolean; + }; + + /** + * Contains properties to filter messages with when calling {@link RealtimeChannel.subscribe | `RealtimeChannel.subscribe()`}. + */ + type MessageFilter = { + /** + * Filters messages by a specific message `name`. + */ + name?: string; + /** + * Filters messages by a specific `extras.ref.timeserial` value. + */ + refTimeserial?: string; + /** + * Filters messages by a specific `extras.ref.type` value. + */ + refType?: string; + /** + * Filters messages based on whether they contain an `extras.ref`. + */ + isRef?: boolean; + /** + * Filters messages by a specific message `clientId`. + */ + clientId: string; + }; + + /** + * Creates and destroys {@link Channel} and {@link RealtimeChannel} objects. */ class Channels { /** - * Creates a new {@link ChannelBase} or {@link RealtimeChannelBase} object, with the specified {@link ChannelOptions}, or returns the existing channel object. + * Creates a new {@link Channel} or {@link RealtimeChannel} object, with the specified {@link ChannelOptions}, or returns the existing channel object. * * @param name - The channel name. * @param channelOptions - A {@link ChannelOptions} object. - * @returns A {@link ChannelBase} or {@link RealtimeChannelBase} object. + * @returns A {@link Channel} or {@link RealtimeChannel} object. */ get(name: string, channelOptions?: ChannelOptions): T; /** @@ -2751,17 +2142,17 @@ declare namespace Types { * to receive only part of the data from the channel. * See the [announcement post](https://pages.ably.com/subscription-filters-preview) for more information. * - * Creates a new {@link ChannelBase} or {@link RealtimeChannelBase} object, with the specified channel {@link DeriveOptions} + * Creates a new {@link Channel} or {@link RealtimeChannel} object, with the specified channel {@link DeriveOptions} * and {@link ChannelOptions}, or returns the existing channel object. * * @param name - The channel name. * @param deriveOptions - A {@link DeriveOptions} object. * @param channelOptions - A {@link ChannelOptions} object. - * @returns A {@link RealtimeChannelBase} object. + * @returns A {@link RealtimeChannel} object. */ getDerived(name: string, deriveOptions: DeriveOptions, channelOptions?: ChannelOptions): T; /** - * Releases a {@link ChannelBase} or {@link RealtimeChannelBase} object, deleting it, and enabling it to be garbage collected. It also removes any listeners associated with the channel. To release a channel, the {@link ChannelState} must be `INITIALIZED`, `DETACHED`, or `FAILED`. + * Releases a {@link Channel} or {@link RealtimeChannel} object, deleting it, and enabling it to be garbage collected. It also removes any listeners associated with the channel. To release a channel, the {@link ChannelState} must be `INITIALIZED`, `DETACHED`, or `FAILED`. * * @param name - The channel name. */ @@ -2976,9 +2367,9 @@ declare namespace Types { } /** - * The `ConnectionBase` class acts as a base class for the {@link ChannelCallbacks} and {@link ChannelPromise} classes. + * Enables the management of a connection to Ably. */ - class ConnectionBase extends EventEmitter { + class Connection extends EventEmitter { /** * An {@link ErrorInfo} object describing the last error received if a connection failure occurs. */ @@ -3004,38 +2395,14 @@ declare namespace Types { */ readonly state: ConnectionState; /** - * Causes the connection to close, entering the {@link ConnectionState.CLOSING} state. Once closed, the library does not attempt to re-establish the connection without an explicit call to {@link ConnectionBase.connect | `connect()`}. + * Causes the connection to close, entering the {@link ConnectionState.CLOSING} state. Once closed, the library does not attempt to re-establish the connection without an explicit call to {@link Connection.connect | `connect()`}. */ close(): void; /** * Explicitly calling `connect()` is unnecessary unless the `autoConnect` attribute of the {@link ClientOptions} object is `false`. Unless already connected or connecting, this method causes the connection to open, entering the {@link ConnectionState.CONNECTING} state. */ connect(): void; - } - /** - * Enables the management of a connection to Ably. - */ - class ConnectionCallbacks extends ConnectionBase { - /** - * When connected, sends a heartbeat ping to the Ably server and executes the callback with any error and the response time in milliseconds when a heartbeat ping request is echoed from the server. This can be useful for measuring true round-trip latency to the connected Ably server. - * - * @param callback - A function which, upon success, will be called with the response time in milliseconds. Upon failure, the function will be called with information about the error. - */ - ping(callback?: Types.StandardCallback): void; - /** - * Calls the supplied function when the connection reaches the specified {@link ConnectionState}. If the connection is already in the specified state, the callback is called immediately. - * - * @param targetState - The state which should be reached. - * @param callback - A function which will be called when the connection has reached the specified {@link ConnectionState} with a {@link ConnectionStateChange} object as the first argument. - */ - whenState(targetState: ConnectionState, callback: connectionEventCallback): void; - } - - /** - * Enables the management of a connection to Ably. - */ - class ConnectionPromise extends ConnectionBase { /** * When connected, sends a heartbeat ping to the Ably server and executes the callback with any error and the response time in milliseconds when a heartbeat ping request is echoed from the server. This can be useful for measuring true round-trip latency to the connected Ably server. * @@ -3100,36 +2467,18 @@ declare namespace Types { * Contains the current page of results; for example, an array of {@link Message} or {@link PresenceMessage} objects for a channel history request. */ items: T[]; - /** - * Returns a new `PaginatedResult` for the first page of results. - * - * @param results - A function which, upon success, will be called with a page of results for message and presence history, stats, and REST presence requests. Upon failure, the function will be called with information about the error. - */ - first(results: paginatedResultCallback): void; /** * Returns a new `PaginatedResult` for the first page of results. * * @returns A promise which, upon success, will be fulfilled with a page of results for message and presence history, stats, and REST presence requests. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. */ first(): Promise>; - /** - * Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `null` is returned. - * - * @param results - A function which, upon success, will be fulfilled with a page of results for message and presence history, stats, and REST presence requests. Upon failure, the function will be called with information about the error. - */ - next(results: paginatedResultCallback): void; /** * Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `null` is returned. * * @returns A promise which, upon success, will be fulfilled with a page of results for message and presence history, stats, and REST presence requests. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. */ next(): Promise>; - /** - * Returns the `PaginatedResult` for the current page of results. - * - * @param results - A function which, upon success, will be fulfilled with a page of results for message and presence history, stats, and REST presence requests. Upon failure, the function will be called with information about the error. - */ - current(results: paginatedResultCallback): void; /** * Returns the `PaginatedResult` for the current page of results. */ @@ -3177,57 +2526,25 @@ declare namespace Types { /** * Enables a device to be registered and deregistered from receiving push notifications. */ - class PushCallbacks { - /** - * A {@link PushAdminCallbacks} object. - */ - admin: PushAdminCallbacks; - } - - /** - * Enables a device to be registered and deregistered from receiving push notifications. - */ - class PushPromise { - /** - * A {@link PushAdminPromise | `PushAdmin`} object. - */ - admin: PushAdminPromise; - } - - /** - * Enables the management of device registrations and push notification subscriptions. Also enables the publishing of push notifications to devices. - */ - class PushAdminCallbacks { - /** - * A {@link PushDeviceRegistrationsCallbacks} object. - */ - deviceRegistrations: PushDeviceRegistrationsCallbacks; - /** - * A {@link PushChannelSubscriptionsCallbacks} object. - */ - channelSubscriptions: PushChannelSubscriptionsCallbacks; + class Push { /** - * Sends a push notification directly to a device, or a group of devices sharing the same `clientId`. - * - * @param recipient - A JSON object containing the recipient details using `clientId`, `deviceId` or the underlying notifications service. - * @param payload - A JSON object containing the push notification payload. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + * A {@link PushAdmin} object. */ - publish(recipient: any, payload: any, callback?: errorCallback): void; + admin: PushAdmin; } /** * Enables the management of device registrations and push notification subscriptions. Also enables the publishing of push notifications to devices. */ - class PushAdminPromise { + class PushAdmin { /** - * A {@link PushDeviceRegistrationsPromise} object. + * A {@link PushDeviceRegistrations} object. */ - deviceRegistrations: PushDeviceRegistrationsPromise; + deviceRegistrations: PushDeviceRegistrations; /** - * A {@link PushChannelSubscriptionsPromise} object. + * A {@link PushChannelSubscriptions} object. */ - channelSubscriptions: PushChannelSubscriptionsPromise; + channelSubscriptions: PushChannelSubscriptions; /** * Sends a push notification directly to a device, or a group of devices sharing the same `clientId`. * @@ -3241,62 +2558,7 @@ declare namespace Types { /** * Enables the management of push notification registrations with Ably. */ - class PushDeviceRegistrationsCallbacks { - /** - * Registers or updates a {@link DeviceDetails} object with Ably. Returns the new, or updated {@link DeviceDetails} object. - * - * @param deviceDetails - The {@link DeviceDetails} object to create or update. - * @param callback - A function which, upon success, will be called with a {@link DeviceDetails} object. Upon failure, the function will be called with information about the error. - */ - save(deviceDetails: DeviceDetails, callback?: Types.StandardCallback): void; - /** - * Retrieves the {@link DeviceDetails} of a device registered to receive push notifications using its `deviceId`. - * - * @param deviceId - The unique ID of the device. - * @param callback - A function which, upon success, will be called with a {@link DeviceDetails} object. Upon failure, the function will be called with information about the error. - */ - get(deviceId: string, callback: Types.StandardCallback): void; - /** - * Retrieves the {@link DeviceDetails} of a device registered to receive push notifications using the `id` property of a {@link DeviceDetails} object. - * - * @param deviceDetails - The {@link DeviceDetails} object containing the `id` property of the device. - * @param callback - A function which, upon success, will be called with a {@link DeviceDetails} object. Upon failure, the function will be called with information about the error. - */ - get(deviceDetails: DeviceDetails, callback: Types.StandardCallback): void; - /** - * Retrieves all devices matching the filter `params` provided. Returns a {@link Types.PaginatedResult} object, containing an array of {@link DeviceDetails} objects. - * - * @param params - An object containing key-value pairs to filter devices by. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link DeviceDetails} objects. Upon failure, the function will be called with information about the error. - */ - list(params: DeviceRegistrationParams, callback: paginatedResultCallback): void; - /** - * Removes a device registered to receive push notifications from Ably using its `deviceId`. - * - * @param deviceId - The unique ID of the device. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - remove(deviceId: string, callback?: errorCallback): void; - /** - * Removes a device registered to receive push notifications from Ably using the `id` property of a {@link DeviceDetails} object. - * - * @param deviceDetails - The {@link DeviceDetails} object containing the `id` property of the device. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - remove(deviceDetails: DeviceDetails, callback?: errorCallback): void; - /** - * Removes all devices registered to receive push notifications from Ably matching the filter `params` provided. - * - * @param params - An object containing key-value pairs to filter devices by. This object’s {@link DeviceRegistrationParams.limit} property will be ignored. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - removeWhere(params: DeviceRegistrationParams, callback?: errorCallback): void; - } - - /** - * Enables the management of push notification registrations with Ably. - */ - class PushDeviceRegistrationsPromise { + class PushDeviceRegistrations { /** * Registers or updates a {@link DeviceDetails} object with Ably. Returns the new, or updated {@link DeviceDetails} object. * @@ -3351,48 +2613,7 @@ declare namespace Types { /** * Enables device push channel subscriptions. */ - class PushChannelSubscriptionsCallbacks { - /** - * Subscribes a device, or a group of devices sharing the same `clientId` to push notifications on a channel. Returns a {@link PushChannelSubscription} object. - * - * @param subscription - A {@link PushChannelSubscription} object. - * @param callback - A function which, upon success, will be called with a {@link PushChannelSubscription} object describing the new or updated subscriptions. Upon failure, the function will be called with information about the error. - */ - save(subscription: PushChannelSubscription, callback?: Types.StandardCallback): void; - /** - * Retrieves all push channel subscriptions matching the filter `params` provided. Returns a {@link Types.PaginatedResult} object, containing an array of {@link PushChannelSubscription} objects. - * - * @param params - An object containing key-value pairs to filter subscriptions by. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link PushChannelSubscription} objects. Upon failure, the function will be called with information about the error. - */ - list(params: PushChannelSubscriptionParams, callback: paginatedResultCallback): void; - /** - * Retrieves all channels with at least one device subscribed to push notifications. Returns a {@link Types.PaginatedResult} object, containing an array of channel names. - * - * @param params - An object containing key-value pairs to filter channels by. - * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of channel names. Upon failure, the function will be called with information about the error. - */ - listChannels(params: PushChannelsParams, callback: paginatedResultCallback): void; - /** - * Unsubscribes a device, or a group of devices sharing the same `clientId` from receiving push notifications on a channel. - * - * @param subscription - A {@link PushChannelSubscription} object. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - remove(subscription: PushChannelSubscription, callback?: errorCallback): void; - /** - * Unsubscribes all devices from receiving push notifications on a channel that match the filter `params` provided. - * - * @param params - An object containing key-value pairs to filter subscriptions by. Can contain `channel`, and optionally either `clientId` or `deviceId`. - * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. - */ - removeWhere(params: PushChannelSubscriptionParams, callback?: errorCallback): void; - } - - /** - * Enables device push channel subscriptions. - */ - class PushChannelSubscriptionsPromise { + class PushChannelSubscriptions { /** * Subscribes a device, or a group of devices sharing the same `clientId` to push notifications on a channel. Returns a {@link PushChannelSubscription} object. * @@ -3434,9 +2655,9 @@ declare namespace Types { /** * A client that offers a simple stateless API to interact directly with Ably's REST API. */ -export declare class Rest extends Types.RestCallbacks {} +export declare class Rest extends Types.Rest {} /** * A client that extends the functionality of {@link Rest} and provides additional realtime-specific features. */ -export declare class Realtime extends Types.RealtimeCallbacks {} +export declare class Realtime extends Types.Realtime {} diff --git a/callbacks.d.ts b/callbacks.d.ts deleted file mode 100644 index e0a434a3dd..0000000000 --- a/callbacks.d.ts +++ /dev/null @@ -1,2 +0,0 @@ -import Ably = require('./ably'); -export = Ably; diff --git a/callbacks.js b/callbacks.js deleted file mode 100644 index 8bfe2c458f..0000000000 --- a/callbacks.js +++ /dev/null @@ -1,6 +0,0 @@ -'use strict'; -/* When returning promises becomes the default in some future version, this - * file will start modifying the exports as promises.js does today. - * Please note that the file imported below is only generated after running - * the build task. */ -module.exports = require('./build/ably-node'); diff --git a/docs/landing-page.md b/docs/landing-page.md new file mode 100644 index 0000000000..f9a0bb6212 --- /dev/null +++ b/docs/landing-page.md @@ -0,0 +1,7 @@ +# Ably JavaScript Client Library SDK API Reference + +The JavaScript Client Library SDK supports a realtime and a REST interface. The JavaScript API references are generated from the [Ably JavaScript Client Library SDK source code](https://github.com/ably/ably-js/) using [TypeDoc](https://typedoc.org) and structured by classes. + +The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels. The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics, token authentication and publishing to a channel. + +View the [Ably docs](https://ably.com/docs/) for conceptual information on using Ably, and for API references featuring all languages. The combined [API references](https://ably.com/docs/api/) are organized by features and split between the [realtime](https://ably.com/docs/api/realtime-sdk) and [REST](https://ably.com/docs/api/rest-sdk) interfaces. diff --git a/docs/landing-pages/choose-library.html b/docs/landing-pages/choose-library.html deleted file mode 100644 index c4243efaf1..0000000000 --- a/docs/landing-pages/choose-library.html +++ /dev/null @@ -1,31 +0,0 @@ - - - - - Ably JavaScript Client Library SDK API Reference - - -

Ably JavaScript Client Library SDK API Reference

- -

- The JavaScript Client Library SDK supports a realtime and a REST interface. The JavaScript API references are generated from the Ably JavaScript Client Library SDK source code using TypeDoc and structured by classes. -

- -

- The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels. The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics, token authentication and publishing to a channel. -

- -

- There are two API variants of the Ably JavaScript Client Library SDK: - -

-

- -

- View the Ably docs for conceptual information on using Ably, and for API references featuring all languages. The combined API references are organized by features and split between the realtime and REST interfaces. -

- - diff --git a/docs/landing-pages/default.md b/docs/landing-pages/default.md deleted file mode 100644 index 994b06cd18..0000000000 --- a/docs/landing-pages/default.md +++ /dev/null @@ -1,7 +0,0 @@ -# Ably JavaScript Client Library SDK API Reference for Callbacks - -You are currently viewing the callback-based variant of the Ably JavaScript Client Library SDK. View the promise-based variant [here](../promises/index.html). - -The callback-based variant of the API implements the common Node.js error-first callback style. - -To get started with the Ably JavaScript Client Library SDK, follow the [Quickstart Guide](https://ably.com/docs/quick-start-guide) or view the introductions to the [realtime](https://ably.com/docs/realtime/usage) and [REST](https://ably.com/docs/rest/usage) interfaces. diff --git a/docs/landing-pages/promises.md b/docs/landing-pages/promises.md deleted file mode 100644 index c312a44660..0000000000 --- a/docs/landing-pages/promises.md +++ /dev/null @@ -1,7 +0,0 @@ -# Ably JavaScript Client Library SDK API Reference for Promises - -You are currently viewing the promise-based variant of the Ably JavaScript Client Library SDK. View the callback-based variant [here](../default/index.html). - -Passing callbacks to methods when using the promise-based variant of the API is still possible, however, if a method does not receive a callback then it will instead return a promise. - -To get started with the Ably JavaScript Client Library SDK, follow the [Quickstart Guide](https://ably.com/docs/quick-start-guide) or view the introductions to the [realtime](https://ably.com/docs/realtime/usage) and [REST](https://ably.com/docs/rest/usage) interfaces. diff --git a/package.json b/package.json index ce9639b23b..1c0a2d9914 100644 --- a/package.json +++ b/package.json @@ -18,10 +18,6 @@ "files": [ "build/**", "ably.d.ts", - "callbacks.d.ts", - "callbacks.js", - "promises.d.ts", - "promises.js", "resources/**" ], "dependencies": { @@ -101,6 +97,6 @@ "format:check": "prettier --check --ignore-path .gitignore --ignore-path .prettierignore src test ably.d.ts webpack.config.js Gruntfile.js scripts/cdn_deploy.js", "sourcemap": "source-map-explorer build/ably.min.js", "sourcemap:noencryption": "source-map-explorer build/ably.noencryption.min.js", - "docs": "typedoc --entryPoints ably.d.ts --out docs/generated/default --readme docs/landing-pages/default.md && typedoc --entryPoints promises.d.ts --out docs/generated/promises --name \"ably (Promise-based)\" --readme docs/landing-pages/promises.md && cp docs/landing-pages/choose-library.html docs/generated/index.html" + "docs": "typedoc --entryPoints ably.d.ts --out docs/generated --readme docs/landing-page.md" } } diff --git a/promises.d.ts b/promises.d.ts deleted file mode 100644 index 0c79c9e897..0000000000 --- a/promises.d.ts +++ /dev/null @@ -1,14 +0,0 @@ -import Ably = require('./ably'); - -/** - * The `Rest` object offers a simple stateless API to interact directly with Ably's REST API. - */ -export declare class Rest extends Ably.Rest.Promise {} -/** - * A client that extends the functionality of {@link Rest} and provides additional realtime-specific features. - */ -export declare class Realtime extends Ably.Realtime.Promise {} - -// Re-export the Types namespace. -import Types = Ably.Types; -export { Types }; diff --git a/promises.js b/promises.js deleted file mode 100644 index c40986d4a4..0000000000 --- a/promises.js +++ /dev/null @@ -1,32 +0,0 @@ -'use strict'; -function promisifyOptions(options) { - if (typeof options == 'string') { - options = options.indexOf(':') == -1 ? { token: options } : { key: options }; - } - if (options.internal === undefined) { - options.internal = { promises: true } - } else { - options.internal.promises = true - } - return options; -} - -/* Please note that the file imported below is only generated after running - * the build task. */ -// eslint-disable-next-line @typescript-eslint/no-var-requires -var Ably = require('./build/ably-node'); - -var RestPromise = function (options) { - return new Ably.Rest(promisifyOptions(options)); -}; -Object.assign(RestPromise, Ably.Rest); - -var RealtimePromise = function (options) { - return new Ably.Realtime(promisifyOptions(options)); -}; -Object.assign(RealtimePromise, Ably.Realtime); - -module.exports = { - Rest: RestPromise, - Realtime: RealtimePromise, -}; diff --git a/src/common/lib/client/auth.ts b/src/common/lib/client/auth.ts index bb4f636d1b..794ea837e1 100644 --- a/src/common/lib/client/auth.ts +++ b/src/common/lib/client/auth.ts @@ -259,9 +259,7 @@ class Auth { _authOptions = authOptions as API.Types.AuthOptions; } if (!callback) { - if (this.client.options.promises) { - return Utils.promisify(this, 'authorize', arguments); - } + return Utils.promisify(this, 'authorize', arguments); } /* RSA10a: authorize() call implies token auth. If a key is passed it, we @@ -418,7 +416,7 @@ class Auth { callback = authOptions; authOptions = null; } - if (!callback && this.client.options.promises) { + if (!callback) { return Utils.promisify(this, 'requestToken', arguments); } @@ -746,7 +744,7 @@ class Auth { callback = authOptions; authOptions = null; } - if (!callback && this.client.options.promises) { + if (!callback) { return Utils.promisify(this, 'createTokenRequest', arguments); } diff --git a/src/common/lib/client/channel.ts b/src/common/lib/client/channel.ts index 8937709d5e..efb273351e 100644 --- a/src/common/lib/client/channel.ts +++ b/src/common/lib/client/channel.ts @@ -78,10 +78,7 @@ class Channel extends EventEmitter { callback = params; params = null; } else { - if (this.rest.options.promises) { - return Utils.promisify(this, 'history', arguments); - } - callback = noop; + return Utils.promisify(this, 'history', arguments); } } @@ -115,10 +112,7 @@ class Channel extends EventEmitter { let params: any; if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'publish', arguments); - } - callback = noop; + return Utils.promisify(this, 'publish', arguments); } if (typeof first === 'string' || first === null) { @@ -192,7 +186,7 @@ class Channel extends EventEmitter { } status(callback?: StandardCallback): void | Promise { - if (typeof callback !== 'function' && this.rest.options.promises) { + if (typeof callback !== 'function') { return Utils.promisify(this, 'status', []); } diff --git a/src/common/lib/client/connection.ts b/src/common/lib/client/connection.ts index a1f823710d..be5177ba48 100644 --- a/src/common/lib/client/connection.ts +++ b/src/common/lib/client/connection.ts @@ -8,8 +8,6 @@ import { NormalisedClientOptions } from '../../types/ClientOptions'; import Realtime from './realtime'; import Platform from 'common/platform'; -function noop() {} - class Connection extends EventEmitter { ably: Realtime; connectionManager: ConnectionManager; @@ -58,10 +56,7 @@ class Connection extends EventEmitter { ping(callback: Function): Promise | void { Logger.logAction(Logger.LOG_MINOR, 'Connection.ping()', ''); if (!callback) { - if (this.ably.options.promises) { - return Utils.promisify(this, 'ping', arguments); - } - callback = noop; + return Utils.promisify(this, 'ping', arguments); } this.connectionManager.ping(null, callback); } diff --git a/src/common/lib/client/paginatedresource.ts b/src/common/lib/client/paginatedresource.ts index bf54698b23..416c59fae6 100644 --- a/src/common/lib/client/paginatedresource.ts +++ b/src/common/lib/client/paginatedresource.ts @@ -195,7 +195,7 @@ export class PaginatedResult { if (relParams) { if ('first' in relParams) { this.first = function (callback: (result?: ErrorInfo | null) => void) { - if (!callback && self.resource.rest.options.promises) { + if (!callback) { return Utils.promisify(self, 'first', []); } self.get(relParams.first, callback); @@ -203,14 +203,14 @@ export class PaginatedResult { } if ('current' in relParams) { this.current = function (callback: (results?: ErrorInfo | null) => void) { - if (!callback && self.resource.rest.options.promises) { + if (!callback) { return Utils.promisify(self, 'current', []); } self.get(relParams.current, callback); }; } this.next = function (callback: (results?: ErrorInfo | null) => void) { - if (!callback && self.resource.rest.options.promises) { + if (!callback) { return Utils.promisify(self, 'next', []); } if ('next' in relParams) { diff --git a/src/common/lib/client/presence.ts b/src/common/lib/client/presence.ts index 77210ade55..8d521bdf4c 100644 --- a/src/common/lib/client/presence.ts +++ b/src/common/lib/client/presence.ts @@ -8,8 +8,6 @@ import { PaginatedResultCallback } from '../../types/utils'; import Channel from './channel'; import RealtimeChannel from './realtimechannel'; -function noop() {} - class Presence extends EventEmitter { channel: RealtimeChannel | Channel; basePath: string; @@ -28,10 +26,7 @@ class Presence extends EventEmitter { callback = params; params = null; } else { - if (this.channel.rest.options.promises) { - return Utils.promisify(this, 'get', arguments); - } - callback = noop; + return Utils.promisify(this, 'get', arguments); } } const rest = this.channel.rest, @@ -69,10 +64,7 @@ class Presence extends EventEmitter { callback = params; params = null; } else { - if (this.channel.rest.options.promises) { - return Utils.promisify(this, '_history', [params]); - } - callback = noop; + return Utils.promisify(this, '_history', [params]); } } diff --git a/src/common/lib/client/push.ts b/src/common/lib/client/push.ts index fb694eaded..b628457f50 100644 --- a/src/common/lib/client/push.ts +++ b/src/common/lib/client/push.ts @@ -7,8 +7,6 @@ import PushChannelSubscription from '../types/pushchannelsubscription'; import { ErrCallback, PaginatedResultCallback, StandardCallback } from '../../types/utils'; import Rest from './rest'; -const noop = function () {}; - class Push { rest: Rest; admin: Admin; @@ -38,10 +36,7 @@ class Admin { const body = Utils.mixin({ recipient: recipient }, payload); if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'publish', arguments); - } - callback = noop; + return Utils.promisify(this, 'publish', arguments); } Utils.mixin(headers, rest.options.headers); @@ -68,10 +63,7 @@ class DeviceRegistrations { params = {}; if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'save', arguments); - } - callback = noop; + return Utils.promisify(this, 'save', arguments); } Utils.mixin(headers, rest.options.headers); @@ -107,10 +99,7 @@ class DeviceRegistrations { deviceId = deviceIdOrDetails.id || deviceIdOrDetails; if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'get', arguments); - } - callback = noop; + return Utils.promisify(this, 'get', arguments); } if (typeof deviceId !== 'string' || !deviceId.length) { @@ -153,10 +142,7 @@ class DeviceRegistrations { headers = Utils.defaultGetHeaders(rest.options, { format }); if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'list', arguments); - } - callback = noop; + return Utils.promisify(this, 'list', arguments); } Utils.mixin(headers, rest.options.headers); @@ -178,10 +164,7 @@ class DeviceRegistrations { deviceId = deviceIdOrDetails.id || deviceIdOrDetails; if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'remove', arguments); - } - callback = noop; + return Utils.promisify(this, 'remove', arguments); } if (typeof deviceId !== 'string' || !deviceId.length) { @@ -215,10 +198,7 @@ class DeviceRegistrations { headers = Utils.defaultGetHeaders(rest.options, { format }); if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'removeWhere', arguments); - } - callback = noop; + return Utils.promisify(this, 'removeWhere', arguments); } Utils.mixin(headers, rest.options.headers); @@ -244,10 +224,7 @@ class ChannelSubscriptions { params = {}; if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'save', arguments); - } - callback = noop; + return Utils.promisify(this, 'save', arguments); } Utils.mixin(headers, rest.options.headers); @@ -278,10 +255,7 @@ class ChannelSubscriptions { headers = Utils.defaultGetHeaders(rest.options, { format }); if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'list', arguments); - } - callback = noop; + return Utils.promisify(this, 'list', arguments); } Utils.mixin(headers, rest.options.headers); @@ -301,10 +275,7 @@ class ChannelSubscriptions { headers = Utils.defaultGetHeaders(rest.options, { format }); if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'removeWhere', arguments); - } - callback = noop; + return Utils.promisify(this, 'removeWhere', arguments); } Utils.mixin(headers, rest.options.headers); @@ -324,10 +295,7 @@ class ChannelSubscriptions { headers = Utils.defaultGetHeaders(rest.options, { format }); if (typeof callback !== 'function') { - if (this.rest.options.promises) { - return Utils.promisify(this, 'listChannels', arguments); - } - callback = noop; + return Utils.promisify(this, 'listChannels', arguments); } Utils.mixin(headers, rest.options.headers); diff --git a/src/common/lib/client/realtime.ts b/src/common/lib/client/realtime.ts index e3b39c7519..416f5748f6 100644 --- a/src/common/lib/client/realtime.ts +++ b/src/common/lib/client/realtime.ts @@ -4,11 +4,10 @@ import EventEmitter from '../util/eventemitter'; import Logger from '../util/logger'; import Connection from './connection'; import RealtimeChannel from './realtimechannel'; -import Defaults from '../util/defaults'; import ErrorInfo from '../types/errorinfo'; import ProtocolMessage from '../types/protocolmessage'; import { ChannelOptions } from '../../types/channel'; -import ClientOptions, { InternalClientOptions } from '../../types/ClientOptions'; +import ClientOptions from '../../types/ClientOptions'; import * as API from '../../../../ably'; import ConnectionManager from '../transport/connectionmanager'; import Platform from 'common/platform'; @@ -36,13 +35,6 @@ class Realtime extends Rest { this.connection.close(); } - static Promise = function (options: InternalClientOptions): Realtime { - options = Defaults.objectifyOptions(options); - options.internal = { ...options.internal, promises: true }; - return new Realtime(options); - }; - - static Callbacks = Realtime; static Utils = Utils; static ConnectionManager = ConnectionManager; static Platform = Platform; diff --git a/src/common/lib/client/realtimechannel.ts b/src/common/lib/client/realtimechannel.ts index 4a04ee5051..0c55e901da 100644 --- a/src/common/lib/client/realtimechannel.ts +++ b/src/common/lib/client/realtimechannel.ts @@ -136,9 +136,7 @@ class RealtimeChannel extends Channel { setOptions(options?: API.Types.ChannelOptions, callback?: ErrCallback): void | Promise { if (!callback) { - if (this.rest.options.promises) { - return Utils.promisify(this, 'setOptions', arguments); - } + return Utils.promisify(this, 'setOptions', arguments); } const _callback = callback || @@ -194,11 +192,7 @@ class RealtimeChannel extends Channel { let callback = args[argCount - 1]; if (typeof callback !== 'function') { - if (this.realtime.options.promises) { - return Utils.promisify(this, 'publish', arguments); - } - callback = noop; - ++argCount; + return Utils.promisify(this, 'publish', arguments); } if (!this.connectionManager.activeState()) { callback(this.connectionManager.getError()); @@ -274,14 +268,7 @@ class RealtimeChannel extends Channel { attach(callback?: ErrCallback): void | Promise { if (!callback) { - if (this.realtime.options.promises) { - return Utils.promisify(this, 'attach', arguments); - } - callback = function (err?: ErrorInfo | null) { - if (err) { - Logger.logAction(Logger.LOG_MAJOR, 'RealtimeChannel.attach()', 'Channel attach failed: ' + err.toString()); - } - }; + return Utils.promisify(this, 'attach', arguments); } if (this.state === 'attached') { callback(); @@ -357,10 +344,7 @@ class RealtimeChannel extends Channel { detach(callback: ErrCallback): void | Promise { if (!callback) { - if (this.realtime.options.promises) { - return Utils.promisify(this, 'detach', arguments); - } - callback = noop; + return Utils.promisify(this, 'detach', arguments); } const connectionManager = this.connectionManager; if (!connectionManager.activeState()) { @@ -413,7 +397,7 @@ class RealtimeChannel extends Channel { subscribe(...args: unknown[] /* [event], listener, [callback] */): void | Promise { const [event, listener, callback] = RealtimeChannel.processListenerArgs(args); - if (!callback && this.realtime.options.promises) { + if (!callback) { return Utils.promisify(this, 'subscribe', [event, listener]); } @@ -957,10 +941,7 @@ class RealtimeChannel extends Channel { callback = params; params = null; } else { - if (this.rest.options.promises) { - return Utils.promisify(this, 'history', arguments); - } - callback = noop; + return Utils.promisify(this, 'history', arguments); } } diff --git a/src/common/lib/client/realtimepresence.ts b/src/common/lib/client/realtimepresence.ts index 39901b2a63..1d2f60be06 100644 --- a/src/common/lib/client/realtimepresence.ts +++ b/src/common/lib/client/realtimepresence.ts @@ -26,8 +26,6 @@ interface RealtimeHistoryParams { from_serial?: string | null; } -const noop = function () {}; - function getClientId(realtimePresence: RealtimePresence) { return realtimePresence.channel.realtime.auth.clientId; } @@ -134,10 +132,7 @@ class RealtimePresence extends Presence { callback = data as ErrCallback; data = null; } else { - if (this.channel.realtime.options.promises) { - return Utils.promisify(this, '_enterOrUpdateClient', [id, clientId, data, action]); - } - callback = noop; + return Utils.promisify(this, '_enterOrUpdateClient', [id, clientId, data, action]); } } @@ -207,10 +202,7 @@ class RealtimePresence extends Presence { callback = data as ErrCallback; data = null; } else { - if (this.channel.realtime.options.promises) { - return Utils.promisify(this, 'leaveClient', [clientId, data]); - } - callback = noop; + return Utils.promisify(this, 'leaveClient', [clientId, data]); } } @@ -266,10 +258,7 @@ class RealtimePresence extends Presence { const waitForSync = !params || ('waitForSync' in params ? params.waitForSync : true); if (!callback) { - if (this.channel.realtime.options.promises) { - return Utils.promisify(this, 'get', args); - } - callback = noop; + return Utils.promisify(this, 'get', args); } function returnMembers(members: PresenceMap) { @@ -315,10 +304,7 @@ class RealtimePresence extends Presence { callback = params; params = null; } else { - if (this.channel.realtime.options.promises) { - return Utils.promisify(this, 'history', arguments); - } - callback = noop; + return Utils.promisify(this, 'history', arguments); } } @@ -518,10 +504,7 @@ class RealtimePresence extends Presence { const channel = this.channel; if (!callback) { - if (this.channel.realtime.options.promises) { - return Utils.promisify(this, 'subscribe', [event, listener]); - } - callback = noop; + return Utils.promisify(this, 'subscribe', [event, listener]); } if (channel.state === 'failed') { diff --git a/src/common/lib/client/rest.ts b/src/common/lib/client/rest.ts index 5629f8f391..d6e57416e2 100644 --- a/src/common/lib/client/rest.ts +++ b/src/common/lib/client/rest.ts @@ -11,7 +11,7 @@ import HttpMethods from '../../constants/HttpMethods'; import { ChannelOptions } from '../../types/channel'; import { PaginatedResultCallback, StandardCallback } from '../../types/utils'; import { ErrnoException, IHttp, RequestParams } from '../../types/http'; -import ClientOptions, { InternalClientOptions, NormalisedClientOptions } from '../../types/ClientOptions'; +import ClientOptions, { NormalisedClientOptions } from '../../types/ClientOptions'; import Platform from '../../platform'; import Message from '../types/message'; @@ -92,10 +92,7 @@ class Rest { callback = params; params = null; } else { - if (this.options.promises) { - return Utils.promisify(this, 'stats', [params]) as Promise>; - } - callback = noop; + return Utils.promisify(this, 'stats', [params]) as Promise>; } } const headers = Utils.defaultGetHeaders(this.options), @@ -122,9 +119,7 @@ class Rest { callback = params; params = null; } else { - if (this.options.promises) { - return Utils.promisify(this, 'time', [params]) as Promise; - } + return Utils.promisify(this, 'time', [params]) as Promise; } } @@ -187,12 +182,9 @@ class Rest { : Utils.defaultPostHeaders(this.options, { format, protocolVersion: version }); if (callback === undefined) { - if (this.options.promises) { - return Utils.promisify(this, 'request', [method, path, version, params, body, customHeaders]) as Promise< - HttpPaginatedResponse - >; - } - callback = noop; + return Utils.promisify(this, 'request', [method, path, version, params, body, customHeaders]) as Promise< + HttpPaginatedResponse + >; } if (typeof body !== 'string') { @@ -231,13 +223,6 @@ class Rest { Logger.setLog(logOptions.level, logOptions.handler); } - static Promise = function (options: InternalClientOptions): Rest { - options = Defaults.objectifyOptions(options); - options.internal = { ...options.internal, promises: true }; - return new Rest(options); - }; - - static Callbacks = Rest; static Platform = Platform; static Crypto?: typeof Platform.Crypto; static Message = Message; diff --git a/src/common/lib/util/defaults.ts b/src/common/lib/util/defaults.ts index 47803a22e0..1b1fd275fe 100644 --- a/src/common/lib/util/defaults.ts +++ b/src/common/lib/util/defaults.ts @@ -233,15 +233,6 @@ export function normaliseOptions(options: InternalClientOptions): NormalisedClie options.idempotentRestPublishing = true; } - if (options.internal?.promises && !Platform.Config.Promise) { - Logger.logAction( - Logger.LOG_ERROR, - 'Defaults.normaliseOptions', - '{promises: true} was specified, but no Promise constructor found; disabling promises' - ); - options.internal.promises = false; - } - let connectivityCheckParams = null; let connectivityCheckUrl = options.connectivityCheckUrl; if (options.connectivityCheckUrl) { @@ -266,7 +257,6 @@ export function normaliseOptions(options: InternalClientOptions): NormalisedClie connectivityCheckParams, connectivityCheckUrl, headers, - promises: options.internal?.promises ?? false, }; } diff --git a/src/common/lib/util/eventemitter.ts b/src/common/lib/util/eventemitter.ts index d24e448e8b..4044343b31 100644 --- a/src/common/lib/util/eventemitter.ts +++ b/src/common/lib/util/eventemitter.ts @@ -241,9 +241,9 @@ class EventEmitter { once(...args: unknown[]): void | Promise { const argCount = args.length; - if ((argCount === 0 || (argCount === 1 && typeof args[0] !== 'function')) && Platform.Config.Promise) { + if (argCount === 0 || (argCount === 1 && typeof args[0] !== 'function')) { const event = args[0]; - return new Platform.Config.Promise((resolve) => { + return new Promise((resolve) => { this.once(event as string | string[] | null, resolve); }); } @@ -300,8 +300,8 @@ class EventEmitter { if (typeof targetState !== 'string' || typeof currentState !== 'string') { throw 'whenState requires a valid event String argument'; } - if (typeof listener !== 'function' && Platform.Config.Promise) { - return new Platform.Config.Promise((resolve) => { + if (typeof listener !== 'function') { + return new Promise((resolve) => { EventEmitter.prototype.whenState.apply( this, [targetState, currentState, resolve].concat(listenerArgs as any[]) as any diff --git a/src/common/types/ClientOptions.ts b/src/common/types/ClientOptions.ts index ab279cfd65..1eeac34905 100644 --- a/src/common/types/ClientOptions.ts +++ b/src/common/types/ClientOptions.ts @@ -19,7 +19,6 @@ export type InternalClientOptions = Modify< ClientOptions, { internal?: { - promises?: boolean; maxMessageSize?: number; }; } @@ -36,6 +35,5 @@ export type NormalisedClientOptions = Modify< maxMessageSize: number; connectivityCheckParams: Record | null; headers: Record; - promises: boolean; } >; diff --git a/src/common/types/IPlatformConfig.d.ts b/src/common/types/IPlatformConfig.d.ts index f4766ea2e5..ecb0e4868d 100644 --- a/src/common/types/IPlatformConfig.d.ts +++ b/src/common/types/IPlatformConfig.d.ts @@ -16,7 +16,6 @@ export interface IPlatformConfig { inspect: (value: unknown) => string; stringByteSize: Buffer.byteLength; addEventListener?: typeof window.addEventListener | typeof global.addEventListener | null; - Promise: typeof Promise; getRandomValues?: (arr: ArrayBufferView, callback?: (error: Error | null) => void) => void; userAgent?: string | null; inherits?: typeof import('util').inherits; diff --git a/src/platform/nativescript/config.js b/src/platform/nativescript/config.js index a68d0e7468..31090e0240 100644 --- a/src/platform/nativescript/config.js +++ b/src/platform/nativescript/config.js @@ -47,7 +47,6 @@ var Config = { }, TextEncoder: global.TextEncoder, TextDecoder: global.TextDecoder, - Promise: global.Promise, getRandomValues: function (arr, callback) { var bytes = randomBytes(arr.length); for (var i = 0; i < arr.length; i++) { diff --git a/src/platform/nodejs/config.ts b/src/platform/nodejs/config.ts index 2a99da4ad7..716be3b12a 100644 --- a/src/platform/nodejs/config.ts +++ b/src/platform/nodejs/config.ts @@ -30,7 +30,6 @@ const Config: IPlatformConfig = { callback(null); } }, - Promise: global && global.Promise, }; export default Config; diff --git a/src/platform/react-native/config.ts b/src/platform/react-native/config.ts index 81c7cd362c..f6e6f29a2e 100644 --- a/src/platform/react-native/config.ts +++ b/src/platform/react-native/config.ts @@ -32,7 +32,6 @@ export default function (bufferUtils: typeof BufferUtils): IPlatformConfig { }, TextEncoder: global.TextEncoder, TextDecoder: global.TextDecoder, - Promise: global.Promise, getRandomArrayBuffer: (function (RNRandomBytes) { return function (byteLength: number, callback: (err: Error | null, result: ArrayBuffer | null) => void) { RNRandomBytes.randomBytes(byteLength, function (err: Error | null, base64String: string | null) { diff --git a/src/platform/web/config.ts b/src/platform/web/config.ts index 0877337f3e..87536361ad 100644 --- a/src/platform/web/config.ts +++ b/src/platform/web/config.ts @@ -59,7 +59,6 @@ const Config: IPlatformConfig = { }, TextEncoder: globalObject.TextEncoder, TextDecoder: globalObject.TextDecoder, - Promise: globalObject.Promise, getRandomValues: (function (crypto) { if (crypto === undefined) { return undefined; diff --git a/test/common/modules/client_module.js b/test/common/modules/client_module.js index d0806d6d4b..7f2c990ea0 100644 --- a/test/common/modules/client_module.js +++ b/test/common/modules/client_module.js @@ -23,11 +23,11 @@ define(['ably', 'globals', 'test/common/modules/testapp_module'], function (Ably } function ablyRest(options) { - return new Ably.Rest.Promise(ablyClientOptions(options)); + return new Ably.Rest(ablyClientOptions(options)); } function ablyRealtime(options) { - return new Ably.Realtime.Promise(ablyClientOptions(options)); + return new Ably.Realtime(ablyClientOptions(options)); } return (module.exports = { diff --git a/test/realtime/api.test.js b/test/realtime/api.test.js index 36f3dd080b..951c0d0669 100644 --- a/test/realtime/api.test.js +++ b/test/realtime/api.test.js @@ -6,7 +6,6 @@ define(['ably', 'chai'], function (Ably, chai) { describe('realtime/api', function () { it('Client constructors', function () { expect(typeof Ably.Realtime).to.equal('function'); - expect(typeof Ably.Realtime.Promise).to.equal('function'); }); it('Crypto', function () { diff --git a/test/realtime/event_emitter.test.js b/test/realtime/event_emitter.test.js index 4575594f21..1fac46d249 100644 --- a/test/realtime/event_emitter.test.js +++ b/test/realtime/event_emitter.test.js @@ -439,62 +439,60 @@ define(['shared_helper', 'chai'], function (helper, chai) { closeAndFinish(done, realtime); }); - if (typeof Promise !== 'undefined') { - describe('event_emitter_promise', function () { - it('whenState', function (done) { - var realtime = helper.AblyRealtime({ internal: { promises: true } }); - var eventEmitter = realtime.connection; - - eventEmitter - .whenState('connected') - .then(function () { - closeAndFinish(done, realtime); - }) - ['catch'](function (err) { - closeAndFinish(done, realtime, err); - }); - }); - - it('once', function (done) { - var realtime = helper.AblyRealtime({ internal: { promises: true } }); - var eventEmitter = realtime.connection; - - eventEmitter - .once('connected') - .then(function () { - closeAndFinish(done, realtime); - }) - ['catch'](function (err) { - closeAndFinish(done, realtime, err); - }); - }); - - it('anyEventsWithOnce', function (done) { - var realtime = helper.AblyRealtime({ autoConnect: false }), - eventEmitter = realtime.connection; - - const p = eventEmitter.once(); - eventEmitter.emit('b'); - p.then(function () { + describe('event_emitter_promise', function () { + it('whenState', function (done) { + var realtime = helper.AblyRealtime(); + var eventEmitter = realtime.connection; + + eventEmitter + .whenState('connected') + .then(function () { closeAndFinish(done, realtime); - }).catch(function (err) { + }) + ['catch'](function (err) { closeAndFinish(done, realtime, err); }); - }); + }); - it('arrayOfEventsWithOnce', function (done) { - var realtime = helper.AblyRealtime({ autoConnect: false }), - eventEmitter = realtime.connection; + it('once', function (done) { + var realtime = helper.AblyRealtime(); + var eventEmitter = realtime.connection; - const p = eventEmitter.once(['a', 'b', 'c']); - eventEmitter.emit('b'); - p.then(function () { + eventEmitter + .once('connected') + .then(function () { closeAndFinish(done, realtime); - }).catch(function (err) { + }) + ['catch'](function (err) { closeAndFinish(done, realtime, err); }); + }); + + it('anyEventsWithOnce', function (done) { + var realtime = helper.AblyRealtime({ autoConnect: false }), + eventEmitter = realtime.connection; + + const p = eventEmitter.once(); + eventEmitter.emit('b'); + p.then(function () { + closeAndFinish(done, realtime); + }).catch(function (err) { + closeAndFinish(done, realtime, err); + }); + }); + + it('arrayOfEventsWithOnce', function (done) { + var realtime = helper.AblyRealtime({ autoConnect: false }), + eventEmitter = realtime.connection; + + const p = eventEmitter.once(['a', 'b', 'c']); + eventEmitter.emit('b'); + p.then(function () { + closeAndFinish(done, realtime); + }).catch(function (err) { + closeAndFinish(done, realtime, err); }); }); - } + }); }); }); diff --git a/test/realtime/init.test.js b/test/realtime/init.test.js index 998a1c2623..f617628641 100644 --- a/test/realtime/init.test.js +++ b/test/realtime/init.test.js @@ -54,7 +54,7 @@ define(['ably', 'shared_helper', 'chai'], function (Ably, helper, chai) { var realtime; try { var keyStr = helper.getTestApp().keys[0].keyStr; - realtime = new helper.Ably.Realtime.Promise(keyStr); + realtime = new helper.Ably.Realtime(keyStr); try { expect(realtime.options.key).to.equal(keyStr); @@ -83,7 +83,7 @@ define(['ably', 'shared_helper', 'chai'], function (Ably, helper, chai) { } var tokenStr = tokenDetails.token, - realtime = new helper.Ably.Realtime.Promise(tokenStr); + realtime = new helper.Ably.Realtime(tokenStr); try { expect(realtime.options.token).to.equal(tokenStr); @@ -208,7 +208,7 @@ define(['ably', 'shared_helper', 'chai'], function (Ably, helper, chai) { try { var keyStr = helper.getTestApp().keys[0].keyStr; expect(function () { - realtime = new helper.Ably.Realtime.Promise({ key: keyStr, useTokenAuth: false, clientId: 'foo' }); + realtime = new helper.Ably.Realtime({ key: keyStr, useTokenAuth: false, clientId: 'foo' }); }).to.throw; done(); } catch (err) { @@ -222,7 +222,7 @@ define(['ably', 'shared_helper', 'chai'], function (Ably, helper, chai) { /* want to check the default host when no custom environment or custom * host set, so not using helpers.realtime this time, which will use a * test env */ - var realtime = new Ably.Realtime.Promise({ key: 'not_a.real:key', autoConnect: false }); + var realtime = new Ably.Realtime({ key: 'not_a.real:key', autoConnect: false }); var defaultHost = realtime.connection.connectionManager.httpHosts[0]; expect(defaultHost).to.equal('rest.ably.io', 'Verify correct default rest host chosen'); realtime.close(); @@ -409,28 +409,5 @@ define(['ably', 'shared_helper', 'chai'], function (Ably, helper, chai) { closeAndFinish(done, realtime); }); }); - - if (typeof Promise === 'undefined') { - it('init_callbacks_promises', function (done) { - try { - var realtime, - keyStr = helper.getTestApp().keys[0].keyStr, - getOptions = function () { - return { key: keyStr, autoConnect: false }; - }; - - realtime = new Ably.Realtime.Promise(getOptions()); - expect(realtime.options.promises, 'Check promises default to true with promise constructor').to.be.ok; - - if (!isBrowser && typeof require == 'function') { - realtime = new require('../../promises').Realtime(getOptions()); - expect(realtime.options.promises, 'Check promises default to true with promise require target').to.be.ok; - } - done(); - } catch (err) { - done(err); - } - }); - } }); }); diff --git a/test/rest/api.test.js b/test/rest/api.test.js index 02950ca883..fcc19aa3df 100644 --- a/test/rest/api.test.js +++ b/test/rest/api.test.js @@ -6,7 +6,6 @@ define(['ably', 'chai'], function (Ably, chai) { describe('rest/api', function () { it('Client constructors', function () { expect(typeof Ably.Rest).to.equal('function'); - expect(typeof Ably.Rest.Promise).to.equal('function'); }); it('Crypto', function () { diff --git a/test/rest/init.test.js b/test/rest/init.test.js index f4debf54f4..2d4b316dde 100644 --- a/test/rest/init.test.js +++ b/test/rest/init.test.js @@ -18,7 +18,7 @@ define(['ably', 'shared_helper', 'chai'], function (Ably, helper, chai) { it('Init with key string', function () { var keyStr = helper.getTestApp().keys[0].keyStr; - var rest = new helper.Ably.Rest.Promise(keyStr); + var rest = new helper.Ably.Rest(keyStr); expect(rest.options.key).to.equal(keyStr); }); @@ -30,7 +30,7 @@ define(['ably', 'shared_helper', 'chai'], function (Ably, helper, chai) { var tokenDetails = await rest.auth.requestToken(null, testKeyOpts); var tokenStr = tokenDetails.token, - rest = new helper.Ably.Rest.Promise(tokenStr); + rest = new helper.Ably.Rest(tokenStr); expect(rest.options.token).to.equal(tokenStr); }); @@ -62,19 +62,5 @@ define(['ably', 'shared_helper', 'chai'], function (Ably, helper, chai) { var rest = helper.AblyRest({ clientId: false }); }, 'Check can’t init library with a boolean clientId').to.throw; }); - - it('Init promises', function () { - var rest, - keyStr = helper.getTestApp().keys[0].keyStr; - - rest = new Ably.Rest.Promise(keyStr); - expect(rest.options.promises, 'Check promises default to true with promise constructor').to.be.ok; - - if (!isBrowser && typeof require == 'function') { - var AblyPromises = require('../../promises'); - rest = new AblyPromises.Rest(keyStr); - expect(rest.options.promises, 'Check promises default to true with promise require target').to.be.ok; - } - }); }); });