From ff7cb418cc722c3bf65852bbe03dbc6157f7b5a1 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Fri, 1 Dec 2023 12:01:54 -0300 Subject: [PATCH] Remove false class exports in type declarations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The type declarations claim that the SDK exports all manner of classes that it does not in fact export, such as Auth, Presence, PushAdmin, AbstractRest, AbstractRealtime etc. Trying to import these classes will result in a runtime (or bundler) error. So, we convert them all to interfaces. (I can’t see an obvious downside of doing this; let me know if there is.) I’ve also addressed the ClientOptions docstring’s links to the Abstract* constructors by rewording their text, since these links are now completely broken (they were previously linking to a useless entry for a nonexistent constructor). Resolves #1519, resolves #1520. --- ably.d.ts | 93 +++++++++++++++++++++++++++++++++++++++------------- modules.d.ts | 66 +++++++++++++++++++++++++++++++++++-- 2 files changed, 134 insertions(+), 25 deletions(-) diff --git a/ably.d.ts b/ably.d.ts index e2163e568b..08eb091803 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -375,7 +375,7 @@ export interface ChannelMetrics { } /** - * Passes additional client-specific properties to the REST {@link AbstractRest.constructor | `constructor()`} or the Realtime {@link AbstractRealtime.constructor | `constructor()`}. + * Passes additional client-specific properties to the REST constructor or the Realtime constructor. */ export interface ClientOptions extends AuthOptions { /** @@ -1472,7 +1472,7 @@ export type recoverConnectionCallback = ( callback: recoverConnectionCompletionCallback ) => void; -// Internal Classes +// Internal Interfaces // To allow a uniform (callback) interface between on and once even in the // promisified version of the lib, but still allow once to be used in a way @@ -1481,7 +1481,7 @@ export type recoverConnectionCallback = ( /** * 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. */ -export declare class EventEmitter { +export declare interface EventEmitter { /** * Registers the provided listener for the specified event. If `on()` is called more than once with the same listener and event, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using `on()`, and an event is emitted once, the listener would be invoked twice. * @@ -1553,11 +1553,11 @@ export declare class EventEmitter { listeners(eventName?: EventType): CallbackType[] | null; } -// Classes +// Interfaces /** * A client that offers a simple stateless API to interact directly with Ably's REST API. */ -export declare abstract class AbstractRest { +export declare interface AbstractRest { /** * An {@link Auth} object. */ @@ -1631,7 +1631,7 @@ export declare abstract class AbstractRest { /** * A client that extends the functionality of {@link AbstractRest} and provides additional realtime-specific features. */ -export declare abstract class AbstractRealtime { +export declare interface AbstractRealtime { /** * 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. */ @@ -1721,7 +1721,7 @@ export declare abstract class AbstractRealtime { /** * Creates Ably {@link TokenRequest} objects and obtains Ably Tokens from Ably to subsequently issue to less trusted clients. */ -export declare class Auth { +export declare interface 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). */ @@ -1767,7 +1767,7 @@ export declare class Auth { /** * Enables the retrieval of the current and historic presence set for a channel. */ -export declare class Presence { +export declare interface 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 PaginatedResult} object, containing an array of {@link PresenceMessage} objects. * @@ -1787,7 +1787,7 @@ export declare class Presence { /** * Enables the presence set to be entered and subscribed to, and the historic presence set to be retrieved for a channel. */ -export declare class RealtimePresence { +export declare interface 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. */ @@ -1908,7 +1908,7 @@ export declare class RealtimePresence { /** * Enables messages to be published and historic messages to be retrieved for a channel. */ -export declare class Channel { +export declare interface Channel { /** * The channel name. */ @@ -1961,7 +1961,7 @@ export declare class Channel { /** * 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. */ -export declare class RealtimeChannel extends EventEmitter { +export declare interface RealtimeChannel extends EventEmitter { /** * The channel name. */ @@ -2158,7 +2158,7 @@ export type MessageFilter = { /** * Creates and destroys {@link Channel} and {@link RealtimeChannel} objects. */ -export declare class Channels { +export declare interface Channels { /** * Creates a new {@link Channel} or {@link RealtimeChannel} object, with the specified {@link ChannelOptions}, or returns the existing channel object. * @@ -2258,7 +2258,7 @@ export interface MessageStatic { /** * Contains an individual presence update sent to, or received from, Ably. */ -export declare class PresenceMessage { +export declare interface PresenceMessage { /** * The type of {@link PresenceAction} the `PresenceMessage` is for. */ @@ -2375,7 +2375,8 @@ export interface Crypto { /** * Enables the management of a connection to Ably. */ -export declare class Connection extends EventEmitter { +export declare interface Connection + extends EventEmitter { /** * An {@link ErrorInfo} object describing the last error received if a connection failure occurs. */ @@ -2426,7 +2427,7 @@ export declare class Connection extends EventEmitter { +export declare interface PaginatedResult { /** * Contains the current page of results; for example, an array of {@link InboundMessage} or {@link PresenceMessage} objects for a channel history request. */ @@ -2490,7 +2491,7 @@ export declare class PaginatedResult { /** * A superset of {@link PaginatedResult} which represents a page of results plus metadata indicating the relative queries available to it. `HttpPaginatedResponse` additionally carries information about the response to an HTTP request. */ -export declare class HttpPaginatedResponse extends PaginatedResult { +export declare interface HttpPaginatedResponse extends PaginatedResult { /** * The HTTP status code of the response. */ @@ -2516,7 +2517,7 @@ export declare class HttpPaginatedResponse extends PaginatedResult { /** * Enables a device to be registered and deregistered from receiving push notifications. */ -export declare class Push { +export declare interface Push { /** * A {@link PushAdmin} object. */ @@ -2526,7 +2527,7 @@ export declare class Push { /** * Enables the management of device registrations and push notification subscriptions. Also enables the publishing of push notifications to devices. */ -export declare class PushAdmin { +export declare interface PushAdmin { /** * A {@link PushDeviceRegistrations} object. */ @@ -2548,7 +2549,7 @@ export declare class PushAdmin { /** * Enables the management of push notification registrations with Ably. */ -export declare class PushDeviceRegistrations { +export declare interface PushDeviceRegistrations { /** * Registers or updates a {@link DeviceDetails} object with Ably. Returns the new, or updated {@link DeviceDetails} object. * @@ -2603,7 +2604,7 @@ export declare class PushDeviceRegistrations { /** * Enables device push channel subscriptions. */ -export declare class PushChannelSubscriptions { +export declare interface PushChannelSubscriptions { /** * Subscribes a device, or a group of devices sharing the same `clientId` to push notifications on a channel. Returns a {@link PushChannelSubscription} object. * @@ -2644,7 +2645,7 @@ export declare class PushChannelSubscriptions { /** * A client that offers a simple stateless API to interact directly with Ably's REST API. */ -export declare class Rest extends AbstractRest { +export declare class Rest implements AbstractRest { /** * Construct a client object using an Ably {@link ClientOptions} object. * @@ -2669,12 +2670,33 @@ export declare class Rest extends AbstractRest { * Static utilities related to presence messages. */ static PresenceMessage: PresenceMessageStatic; + + // Requirements of AbstractRest + + auth: Auth; + channels: Channels; + request( + method: string, + path: string, + version: number, + params?: any, + body?: any[] | any, + headers?: any + ): Promise>; + stats(params?: StatsParams | any): Promise>; + time(): Promise; + batchPublish(spec: BatchPublishSpec): Promise>; + batchPublish( + specs: BatchPublishSpec[] + ): Promise[]>; + batchPresence(channels: string[]): Promise[]>; + push: Push; } /** * A client that extends the functionality of {@link Rest} and provides additional realtime-specific features. */ -export declare class Realtime extends AbstractRealtime { +export declare class Realtime implements AbstractRealtime { /** * Construct a client object using an Ably {@link ClientOptions} object. * @@ -2699,6 +2721,31 @@ export declare class Realtime extends AbstractRealtime { * Static utilities related to presence messages. */ static PresenceMessage: PresenceMessageStatic; + + // Requirements of AbstractRealtime + + clientId: string; + close(): void; + connect(): void; + auth: Auth; + channels: Channels; + connection: Connection; + request( + method: string, + path: string, + version: number, + params?: any, + body?: any[] | any, + headers?: any + ): Promise>; + stats(params?: StatsParams | any): Promise>; + time(): Promise; + batchPublish(spec: BatchPublishSpec): Promise>; + batchPublish( + specs: BatchPublishSpec[] + ): Promise[]>; + batchPresence(channels: string[]): Promise[]>; + push: Push; } /** diff --git a/modules.d.ts b/modules.d.ts index e238fcf677..bf2ea58cc8 100644 --- a/modules.d.ts +++ b/modules.d.ts @@ -30,6 +30,22 @@ import { MessageStatic, PresenceMessageStatic, AbstractRealtime, + Auth, + Channels, + Channel, + HttpPaginatedResponse, + StatsParams, + PaginatedResult, + Stats, + BatchPublishSpec, + BatchResult, + BatchPublishSuccessResult, + BatchPresenceFailureResult, + BatchPresenceSuccessResult, + BatchPublishFailureResult, + Push, + RealtimeChannel, + Connection, } from './ably'; export declare const generateRandomKey: CryptoClass['generateRandomKey']; @@ -274,7 +290,7 @@ export interface ModulesMap { * * `BaseRest` is the equivalent, in the modular variant of the Ably Client Library SDK, of the [`Rest`](../../default/classes/Rest.html) class in the default variant of the SDK. The difference is that its constructor allows you to decide exactly which functionality the client should include. This allows unused functionality to be tree-shaken, reducing bundle size. */ -export declare class BaseRest extends AbstractRest { +export declare class BaseRest implements AbstractRest { /** * Construct a client object using an Ably {@link ClientOptions} object. * @@ -286,6 +302,27 @@ export declare class BaseRest extends AbstractRest { * The {@link Rest} module is always implicitly included. */ constructor(options: ClientOptions, modules: ModulesMap); + + // Requirements of AbstractRest + + auth: Auth; + channels: Channels; + request( + method: string, + path: string, + version: number, + params?: any, + body?: any[] | any, + headers?: any + ): Promise>; + stats(params?: StatsParams | any): Promise>; + time(): Promise; + batchPublish(spec: BatchPublishSpec): Promise>; + batchPublish( + specs: BatchPublishSpec[] + ): Promise[]>; + batchPresence(channels: string[]): Promise[]>; + push: Push; } /** @@ -293,7 +330,7 @@ export declare class BaseRest extends AbstractRest { * * `BaseRealtime` is the equivalent, in the modular variant of the Ably Client Library SDK, of the [`Realtime`](../../default/classes/Realtime.html) class in the default variant of the SDK. The difference is that its constructor allows you to decide exactly which functionality the client should include. This allows unused functionality to be tree-shaken, reducing bundle size. */ -export declare class BaseRealtime extends AbstractRealtime { +export declare class BaseRealtime implements AbstractRealtime { /** * Construct a client object using an Ably {@link ClientOptions} object. * @@ -306,6 +343,31 @@ export declare class BaseRealtime extends AbstractRealtime { * - at least one realtime transport implementation; that is, one of {@link WebSocketTransport}, {@link XHRStreaming}, or {@link XHRPolling} — for minimum bundle size, favour `WebSocketTransport`. */ constructor(options: ClientOptions, modules: ModulesMap); + + // Requirements of AbstractRealtime + + clientId: string; + close(): void; + connect(): void; + auth: Auth; + channels: Channels; + connection: Connection; + request( + method: string, + path: string, + version: number, + params?: any, + body?: any[] | any, + headers?: any + ): Promise>; + stats(params?: StatsParams | any): Promise>; + time(): Promise; + batchPublish(spec: BatchPublishSpec): Promise>; + batchPublish( + specs: BatchPublishSpec[] + ): Promise[]>; + batchPresence(channels: string[]): Promise[]>; + push: Push; } export { ErrorInfo };