Skip to content

Commit

Permalink
Remove false class exports in type declarations
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@lawrence-forooghian
lawrence-forooghian committed Jan 15, 2024
1 parent 80709a9 commit ff7cb41
Show file tree
Hide file tree
Showing 2 changed files with 134 additions and 25 deletions.
93 changes: 70 additions & 23 deletions ably.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
/**
Expand Down Expand Up @@ -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
Expand All @@ -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<CallbackType, ResultType, EventType> {
export declare 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.
*
Expand Down Expand Up @@ -1553,11 +1553,11 @@ export declare class EventEmitter<CallbackType, ResultType, EventType> {
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.
*/
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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).
*/
Expand Down Expand Up @@ -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.
*
Expand All @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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<channelEventCallback, ChannelStateChange, ChannelEvent> {
export declare interface RealtimeChannel extends EventEmitter<channelEventCallback, ChannelStateChange, ChannelEvent> {
/**
* The channel name.
*/
Expand Down Expand Up @@ -2158,7 +2158,7 @@ export type MessageFilter = {
/**
* Creates and destroys {@link Channel} and {@link RealtimeChannel} objects.
*/
export declare class Channels<T> {
export declare interface Channels<T> {
/**
* Creates a new {@link Channel} or {@link RealtimeChannel} object, with the specified {@link ChannelOptions}, or returns the existing channel object.
*
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -2375,7 +2375,8 @@ export interface Crypto {
/**
* Enables the management of a connection to Ably.
*/
export declare class Connection extends EventEmitter<connectionEventCallback, ConnectionStateChange, ConnectionEvent> {
export declare interface Connection
extends EventEmitter<connectionEventCallback, ConnectionStateChange, ConnectionEvent> {
/**
* An {@link ErrorInfo} object describing the last error received if a connection failure occurs.
*/
Expand Down Expand Up @@ -2426,7 +2427,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 declare interface Stats {
/**
* The UTC time at which the time period covered begins. If `unit` is set to `minute` this will be in the format `YYYY-mm-dd:HH:MM`, if `hour` it will be `YYYY-mm-dd:HH`, if `day` it will be `YYYY-mm-dd:00` and if `month` it will be `YYYY-mm-01:00`.
*/
Expand All @@ -2452,7 +2453,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 declare 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.
*/
Expand Down Expand Up @@ -2490,7 +2491,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 declare interface HttpPaginatedResponse<T = any> extends PaginatedResult<T> {
/**
* The HTTP status code of the response.
*/
Expand All @@ -2516,7 +2517,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 declare interface Push {
/**
* A {@link PushAdmin} object.
*/
Expand All @@ -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.
*/
Expand All @@ -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.
*
Expand Down Expand Up @@ -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.
*
Expand Down Expand Up @@ -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.
*
Expand All @@ -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<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.
*
Expand All @@ -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<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;
}

/**
Expand Down
66 changes: 64 additions & 2 deletions modules.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'];
Expand Down Expand Up @@ -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.
*
Expand All @@ -286,14 +302,35 @@ 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>;
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.
*
Expand All @@ -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<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 };

0 comments on commit ff7cb41

Please sign in to comment.