Skip to content

Commit

Permalink
Remove the Types namespace
Browse files Browse the repository at this point in the history 
We’re removing it because we believe that it’s more consistent with
other JS libraries for users to write `import * as Ably from 'ably'` and
then access types on the `Ably` namespace.

The triggering of @typescript-eslint/no-redeclare (and hence the added
eslint-disable-next-line statements) seems to be related to [1]. I’m not
sure why it wasn’t complaining before, though.

Resolves #909.

[1] typescript-eslint/typescript-eslint#2818
  • Loading branch information
@lawrence-forooghian
lawrence-forooghian committed Nov 30, 2023
1 parent c18b03a commit 4b3a1c6
Show file tree
Hide file tree
Showing 44 changed files with 2,750 additions and 2,758 deletions.
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,9 +119,9 @@ The TypeScript typings are included in the package and so all you have to do is:
```typescript
import * as Ably from 'ably';

let options: Ably.Types.ClientOptions = { key: 'foo' };
let options: Ably.ClientOptions = { key: 'foo' };
let client = new Ably.Realtime(options); /* inferred type Ably.Realtime */
let channel = client.channels.get('feed'); /* inferred type Ably.Types.RealtimeChannel */
let channel = client.channels.get('feed'); /* inferred type Ably.RealtimeChannel */
```

Intellisense in IDEs with TypeScript support is supported:
Expand Down
32 changes: 16 additions & 16 deletions ably.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,18 @@
// Definitions by: Ably <https://github.com/ably/>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

import { Types } from './types';
import { AbstractRest, ClientOptions, Crypto, MessageStatic, PresenceMessageStatic, AbstractRealtime } from './types';

/**
* A client that offers a simple stateless API to interact directly with Ably's REST API.
*/
export declare class Rest extends Types.AbstractRest {
export declare class Rest extends AbstractRest {
/**
* Construct a client object using an Ably {@link Types.ClientOptions} object.
* Construct a client object using an Ably {@link ClientOptions} object.
*
* @param options - A {@link Types.ClientOptions} object to configure the client connection to Ably.
* @param options - A {@link ClientOptions} object to configure the client connection to Ably.
*/
constructor(options: Types.ClientOptions);
constructor(options: ClientOptions);
/**
* Constructs a client object using an Ably API key or token string.
*
Expand All @@ -24,27 +24,27 @@ export declare class Rest extends Types.AbstractRest {
/**
* The cryptographic functions available in the library.
*/
static Crypto: Types.Crypto;
static Crypto: Crypto;
/**
* Static utilities related to messages.
*/
static Message: Types.MessageStatic;
static Message: MessageStatic;
/**
* Static utilities related to presence messages.
*/
static PresenceMessage: Types.PresenceMessageStatic;
static PresenceMessage: PresenceMessageStatic;
}

/**
* A client that extends the functionality of {@link Rest} and provides additional realtime-specific features.
*/
export declare class Realtime extends Types.AbstractRealtime {
export declare class Realtime extends AbstractRealtime {
/**
* Construct a client object using an Ably {@link Types.ClientOptions} object.
* Construct a client object using an Ably {@link ClientOptions} object.
*
* @param options - A {@link Types.ClientOptions} object to configure the client connection to Ably.
* @param options - A {@link ClientOptions} object to configure the client connection to Ably.
*/
constructor(options: Types.ClientOptions);
constructor(options: ClientOptions);
/**
* Constructs a client object using an Ably API key or token string.
*
Expand All @@ -54,15 +54,15 @@ export declare class Realtime extends Types.AbstractRealtime {
/**
* The cryptographic functions available in the library.
*/
static Crypto: Types.Crypto;
static Crypto: Crypto;
/**
* Static utilities related to messages.
*/
static Message: Types.MessageStatic;
static Message: MessageStatic;
/**
* Static utilities related to presence messages.
*/
static PresenceMessage: Types.PresenceMessageStatic;
static PresenceMessage: PresenceMessageStatic;
}

/**
Expand Down Expand Up @@ -97,4 +97,4 @@ export declare class ErrorInfo {
constructor(message: string, code: number, statusCode: number, cause?: string | Error | ErrorInfo);
}

export { Types };
export * from './types';
65 changes: 37 additions & 28 deletions modules.d.ts
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,22 @@
import { Types, ErrorInfo } from './ably';
import { ErrorInfo } from './ably';
import {
AbstractRest,
ClientOptions,
Crypto as CryptoClass,
MessageStatic,
PresenceMessageStatic,
AbstractRealtime,
} from './types';

export declare const generateRandomKey: Types.Crypto['generateRandomKey'];
export declare const getDefaultCryptoParams: Types.Crypto['getDefaultParams'];
export declare const decodeMessage: Types.MessageStatic['fromEncoded'];
export declare const decodeEncryptedMessage: Types.MessageStatic['fromEncoded'];
export declare const decodeMessages: Types.MessageStatic['fromEncodedArray'];
export declare const decodeEncryptedMessages: Types.MessageStatic['fromEncodedArray'];
export declare const decodePresenceMessage: Types.PresenceMessageStatic['fromEncoded'];
export declare const decodePresenceMessages: Types.PresenceMessageStatic['fromEncodedArray'];
export declare const constructPresenceMessage: Types.PresenceMessageStatic['fromValues'];
export declare const generateRandomKey: CryptoClass['generateRandomKey'];
export declare const getDefaultCryptoParams: CryptoClass['getDefaultParams'];
export declare const decodeMessage: MessageStatic['fromEncoded'];
export declare const decodeEncryptedMessage: MessageStatic['fromEncoded'];
export declare const decodeMessages: MessageStatic['fromEncodedArray'];
export declare const decodeEncryptedMessages: MessageStatic['fromEncodedArray'];
export declare const decodePresenceMessage: PresenceMessageStatic['fromEncoded'];
export declare const decodePresenceMessages: PresenceMessageStatic['fromEncodedArray'];
export declare const constructPresenceMessage: PresenceMessageStatic['fromValues'];

/**
* Provides REST-related functionality to a {@link BaseRealtime} client.
Expand All @@ -22,22 +30,22 @@ export declare const constructPresenceMessage: Types.PresenceMessageStatic['from
*
* When provided, the following functionality becomes available:
*
* - { @link Types.Push | push admin }
* - { @link Push | push admin }
* - { @link BaseRealtime.time | retrieving Ably service time }
* - { @link BaseRealtime.stats | retrieving your application’s usage statistics }
* - { @link BaseRealtime.request | making arbitrary REST requests }
* - { @link BaseRealtime.batchPublish | batch publishing of messages }
* - { @link BaseRealtime.batchPresence | batch retrieval of channel presence state }
* - { @link Types.Auth.revokeTokens | requesting the revocation of tokens }
* - { @link Types.RealtimeChannel.history | retrieving the message history of a channel }
* - { @link Types.RealtimePresence.history | retrieving the presence history of a channel }
* - { @link Auth.revokeTokens | requesting the revocation of tokens }
* - { @link RealtimeChannel.history | retrieving the message history of a channel }
* - { @link RealtimePresence.history | retrieving the presence history of a channel }
*
* If this module is not provided, then trying to use the above functionality will cause a runtime error.
*/
export declare const Rest: unknown;

/**
* Provides a {@link BaseRest} or {@link BaseRealtime} instance with the ability to encrypt and decrypt {@link Types.Message} payloads.
* Provides a {@link BaseRest} or {@link BaseRealtime} instance with the ability to encrypt and decrypt {@link Message} payloads.
*
* To create a client that includes this module, include it in the `ModulesMap` that you pass to the {@link BaseRealtime.constructor}:
*
Expand All @@ -46,7 +54,7 @@ export declare const Rest: unknown;
* const realtime = new BaseRealtime(options, { WebSocketTransport, FetchRequest, Crypto });
* ```
*
* When provided, you can configure message encryption on a channel via the {@link Types.ChannelOptions.cipher} property of the `ChannelOptions` that you pass when {@link Types.Channels.get | fetching a channel}. If this module is not provided, then passing a `ChannelOptions` with a `cipher` property will cause a runtime error.
* When provided, you can configure message encryption on a channel via the {@link ChannelOptions.cipher} property of the `ChannelOptions` that you pass when {@link Channels.get | fetching a channel}. If this module is not provided, then passing a `ChannelOptions` with a `cipher` property will cause a runtime error.
*/
export declare const Crypto: unknown;

Expand All @@ -60,7 +68,7 @@ export declare const Crypto: unknown;
* const realtime = new BaseRealtime(options, { WebSocketTransport, FetchRequest, MsgPack });
* ```
*
* When provided, you can control whether the client uses MessagePack via the {@link Types.ClientOptions.useBinaryProtocol} client option. If you do not provide this module, then the library will always JSON format for encoding messages.
* When provided, you can control whether the client uses MessagePack via the {@link ClientOptions.useBinaryProtocol} client option. If you do not provide this module, then the library will always JSON format for encoding messages.
*/
export declare const MsgPack: unknown;

Expand All @@ -74,7 +82,7 @@ export declare const MsgPack: unknown;
* const realtime = new BaseRealtime(options, { WebSocketTransport, FetchRequest, RealtimePresenceModule });
* ```
*
* If you do not provide this module, then attempting to access a channel’s {@link Types.RealtimeChannel.presence} property will cause a runtime error.
* If you do not provide this module, then attempting to access a channel’s {@link RealtimeChannel.presence} property will cause a runtime error.
*/
export declare const RealtimePresenceModule: unknown;

Expand Down Expand Up @@ -150,7 +158,7 @@ export declare const XHRRequest: unknown;
export declare const FetchRequest: unknown;

/**
* Provides a {@link BaseRealtime} instance with the ability to filter channel subscriptions at runtime using { @link Types.RealtimeChannel.subscribe:WITH_MESSAGE_FILTER | the overload of `subscribe()` that accepts a `MessageFilter` }.
* Provides a {@link BaseRealtime} instance with the ability to filter channel subscriptions at runtime using { @link RealtimeChannel.subscribe:WITH_MESSAGE_FILTER | the overload of `subscribe()` that accepts a `MessageFilter` }.
*
* To create a client that includes this module, include it in the `ModulesMap` that you pass to the {@link BaseRealtime.constructor}:
*
Expand Down Expand Up @@ -242,38 +250,39 @@ 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 Types.AbstractRest {
export declare class BaseRest extends AbstractRest {
/**
* Construct a client object using an Ably {@link Types.ClientOptions} object.
* Construct a client object using an Ably {@link ClientOptions} object.
*
* @param options - A {@link Types.ClientOptions} object to configure the client connection to Ably.
* @param options - A {@link ClientOptions} object to configure the client connection to Ably.
* @param modules - An object which describes which functionality the client should offer. See the documentation for {@link ModulesMap}.
*
* You must provide at least one HTTP request implementation; that is, one of {@link FetchRequest} or {@link XHRRequest}. For minimum bundle size, favour `FetchRequest`.
*
* The {@link Rest} module is always implicitly included.
*/
constructor(options: Types.ClientOptions, modules: ModulesMap);
constructor(options: ClientOptions, modules: ModulesMap);
}

/**
* 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 Types.AbstractRealtime {
export declare class BaseRealtime extends AbstractRealtime {
/**
* Construct a client object using an Ably {@link Types.ClientOptions} object.
* Construct a client object using an Ably {@link ClientOptions} object.
*
* @param options - A {@link Types.ClientOptions} object to configure the client connection to Ably.
* @param options - A {@link ClientOptions} object to configure the client connection to Ably.
* @param modules - An object which describes which functionality the client should offer. See the documentation for {@link ModulesMap}.
*
* You must provide:
*
* - at least one HTTP request implementation; that is, one of {@link FetchRequest} or {@link XHRRequest} — for minimum bundle size, favour `FetchRequest`;
* - 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: Types.ClientOptions, modules: ModulesMap);
constructor(options: ClientOptions, modules: ModulesMap);
}

export { Types, ErrorInfo };
export { ErrorInfo };
export * from './types';
Loading

0 comments on commit 4b3a1c6

Please sign in to comment.