Remove false class exports in type declarations

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.) Resolves #1519.
ably · Dec 4, 2023 · 572cfa8 · 572cfa8
1 parent 4b3a1c6
commit 572cfa8
Show file tree

Hide file tree

Showing 3 changed files with 155 additions and 23 deletions.
diff --git a/ably.d.ts b/ably.d.ts
@@ -3,12 +3,35 @@
 // Definitions by: Ably <https://github.com/ably/>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
-import { AbstractRest, ClientOptions, Crypto, MessageStatic, PresenceMessageStatic, AbstractRealtime } from './types';
+import {
+  AbstractRest,
+  ClientOptions,
+  Crypto,
+  MessageStatic,
+  PresenceMessageStatic,
+  AbstractRealtime,
+  Auth,
+  Channels,
+  Channel,
+  HttpPaginatedResponse,
+  StatsParams,
+  PaginatedResult,
+  Stats,
+  BatchPublishSpec,
+  BatchResult,
+  BatchPublishSuccessResult,
+  BatchPresenceFailureResult,
+  BatchPresenceSuccessResult,
+  BatchPublishFailureResult,
+  Push,
+  RealtimeChannel,
+  Connection,
+} from './types';
 
 /**
  * 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.
    *
@@ -33,12 +56,33 @@ export declare class Rest extends AbstractRest {
    * Static utilities related to presence messages.
    */
   static PresenceMessage: PresenceMessageStatic;
+
+  // Requirements of AbstractRest
+
+  auth: Auth;
+  channels: Channels<Channel>;
+  request<T = any>(
+    method: string,
+    path: string,
+    version: number,
+    params?: any,
+    body?: any[] | any,
+    headers?: any
+  ): Promise<HttpPaginatedResponse<T>>;
+  stats(params?: StatsParams | any): Promise<PaginatedResult<Stats>>;
+  time(): Promise<number>;
+  batchPublish(spec: BatchPublishSpec): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>>;
+  batchPublish(
+    specs: BatchPublishSpec[]
+  ): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>[]>;
+  batchPresence(channels: string[]): Promise<BatchResult<BatchPresenceSuccessResult | BatchPresenceFailureResult>[]>;
+  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.
    *
@@ -63,6 +107,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<RealtimeChannel>;
+  connection: Connection;
+  request<T = any>(
+    method: string,
+    path: string,
+    version: number,
+    params?: any,
+    body?: any[] | any,
+    headers?: any
+  ): Promise<HttpPaginatedResponse<T>>;
+  stats(params?: StatsParams | any): Promise<PaginatedResult<Stats>>;
+  time(): Promise<number>;
+  batchPublish(spec: BatchPublishSpec): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>>;
+  batchPublish(
+    specs: BatchPublishSpec[]
+  ): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>[]>;
+  batchPresence(channels: string[]): Promise<BatchResult<BatchPresenceSuccessResult | BatchPresenceFailureResult>[]>;
+  push: Push;
 }
 
 /**

diff --git a/modules.d.ts b/modules.d.ts
@@ -6,6 +6,22 @@ import {
   MessageStatic,
   PresenceMessageStatic,
   AbstractRealtime,
+  Auth,
+  Channels,
+  Channel,
+  HttpPaginatedResponse,
+  StatsParams,
+  PaginatedResult,
+  Stats,
+  BatchPublishSpec,
+  BatchResult,
+  BatchPublishSuccessResult,
+  BatchPresenceFailureResult,
+  BatchPresenceSuccessResult,
+  BatchPublishFailureResult,
+  Push,
+  RealtimeChannel,
+  Connection,
 } from './types';
 
 export declare const generateRandomKey: CryptoClass['generateRandomKey'];
@@ -250,7 +266,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.
    *
@@ -262,14 +278,36 @@ 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<Channel>;
+  request<T = any>(
+    method: string,
+    path: string,
+    version: number,
+    params?: any,
+    body?: any[] | any,
+    headers?: any
+  ): Promise<HttpPaginatedResponse<T>>;
+  stats(params?: StatsParams | any): Promise<PaginatedResult<Stats>>;
+  time(): Promise<number>;
+  // TODO how does it work with the overloads?
+  batchPublish(spec: BatchPublishSpec): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>>;
+  batchPublish(
+    specs: BatchPublishSpec[]
+  ): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>[]>;
+  batchPresence(channels: string[]): Promise<BatchResult<BatchPresenceSuccessResult | BatchPresenceFailureResult>[]>;
+  push: Push;
 }
 
 /**
  * A client that extends the functionality of {@link BaseRest} and provides additional realtime-specific features.
  *
  * `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.
    *
@@ -282,6 +320,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<RealtimeChannel>;
+  connection: Connection;
+  request<T = any>(
+    method: string,
+    path: string,
+    version: number,
+    params?: any,
+    body?: any[] | any,
+    headers?: any
+  ): Promise<HttpPaginatedResponse<T>>;
+  stats(params?: StatsParams | any): Promise<PaginatedResult<Stats>>;
+  time(): Promise<number>;
+  batchPublish(spec: BatchPublishSpec): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>>;
+  batchPublish(
+    specs: BatchPublishSpec[]
+  ): Promise<BatchResult<BatchPublishSuccessResult | BatchPublishFailureResult>[]>;
+  batchPresence(channels: string[]): Promise<BatchResult<BatchPresenceSuccessResult | BatchPresenceFailureResult>[]>;
+  push: Push;
 }
 
 export { ErrorInfo };

diff --git a/types.d.ts b/types.d.ts
@@ -1586,7 +1586,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<CallbackType, ResultType, EventType> {
+export interface EventEmitter<CallbackType, ResultType, EventType> {
   /**
    * 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.
    *
@@ -1662,7 +1662,7 @@ export declare class EventEmitter<CallbackType, ResultType, EventType> {
 /**
  * A client that offers a simple stateless API to interact directly with Ably's REST API.
  */
-export declare abstract class AbstractRest {
+export interface AbstractRest {
   /**
    * An {@link Auth} object.
    */
@@ -1736,7 +1736,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 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.
    */
@@ -1826,7 +1826,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 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).
    */
@@ -1872,7 +1872,7 @@ export declare class Auth {
 /**
  * Enables the retrieval of the current and historic presence set for a channel.
  */
-export declare class Presence {
+export 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.
    *
@@ -1892,7 +1892,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 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.
    */
@@ -2013,7 +2013,7 @@ export declare class RealtimePresence {
 /**
  * Enables messages to be published and historic messages to be retrieved for a channel.
  */
-export declare class Channel {
+export interface Channel {
   /**
    * The channel name.
    */
@@ -2066,7 +2066,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<channelEventCallback, ChannelStateChange, ChannelEvent> {
+export interface RealtimeChannel extends EventEmitter<channelEventCallback, ChannelStateChange, ChannelEvent> {
   /**
    * The channel name.
    */
@@ -2263,7 +2263,7 @@ export type MessageFilter = {
 /**
  * Creates and destroys {@link Channel} and {@link RealtimeChannel} objects.
  */
-export declare class Channels<T> {
+export interface Channels<T> {
   /**
    * Creates a new {@link Channel} or {@link RealtimeChannel} object, with the specified {@link ChannelOptions}, or returns the existing channel object.
    *
@@ -2363,7 +2363,7 @@ export interface MessageStatic {
 /**
  * Contains an individual presence update sent to, or received from, Ably.
  */
-export declare class PresenceMessage {
+export interface PresenceMessage {
   /**
    * The type of {@link PresenceAction} the `PresenceMessage` is for.
    */
@@ -2480,7 +2480,7 @@ export interface Crypto {
 /**
  * Enables the management of a connection to Ably.
  */
-export declare class Connection extends EventEmitter<connectionEventCallback, ConnectionStateChange, ConnectionEvent> {
+export interface Connection extends EventEmitter<connectionEventCallback, ConnectionStateChange, ConnectionEvent> {
   /**
    * An {@link ErrorInfo} object describing the last error received if a connection failure occurs.
    */
@@ -2531,7 +2531,7 @@ export declare class Connection extends EventEmitter<connectionEventCallback, Co
 /**
  * Contains application statistics for a specified time interval and time period.
  */
-export declare class Stats {
+export interface Stats {
   /**
    * A {@link StatsMessageTypes} object containing the aggregate count of all message stats.
    */
@@ -2573,7 +2573,7 @@ export declare class Stats {
 /**
  * Contains a page of results for message or presence history, stats, or REST presence requests. A `PaginatedResult` response from a REST API paginated query is also accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object.
  */
-export declare class PaginatedResult<T> {
+export interface PaginatedResult<T> {
   /**
    * Contains the current page of results; for example, an array of {@link InboundMessage} or {@link PresenceMessage} objects for a channel history request.
    */
@@ -2611,7 +2611,7 @@ export declare class PaginatedResult<T> {
 /**
  * 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<T = any> extends PaginatedResult<T> {
+export interface HttpPaginatedResponse<T = any> extends PaginatedResult<T> {
   /**
    * The HTTP status code of the response.
    */
@@ -2637,7 +2637,7 @@ export declare class HttpPaginatedResponse<T = any> extends PaginatedResult<T> {
 /**
  * Enables a device to be registered and deregistered from receiving push notifications.
  */
-export declare class Push {
+export interface Push {
   /**
    * A {@link PushAdmin} object.
    */
@@ -2647,7 +2647,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 interface PushAdmin {
   /**
    * A {@link PushDeviceRegistrations} object.
    */
@@ -2669,7 +2669,7 @@ export declare class PushAdmin {
 /**
  * Enables the management of push notification registrations with Ably.
  */
-export declare class PushDeviceRegistrations {
+export interface PushDeviceRegistrations {
   /**
    * Registers or updates a {@link DeviceDetails} object with Ably. Returns the new, or updated {@link DeviceDetails} object.
    *
@@ -2724,7 +2724,7 @@ export declare class PushDeviceRegistrations {
 /**
  * Enables device push channel subscriptions.
  */
-export declare class PushChannelSubscriptions {
+export 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.
    *