Only export types from default variant of library

When we remove the Types namespace in #909, the RealtimePresence class
defined in ably.d.ts will clash with the variable of the same name
declared in modules.d.ts.

Owen indicated that his preference for resolving this issue is to export
the common types (i.e. those currently contained in the Types namespace)
from only the default variant and not from the modular variant, so
that’s what we do here. Users of the modular variant who wish to refer
to the common types will need to import them from the default variant.

To maintain TypeDoc’s ability to generate hyperlinks from the references
which are contained in the modular variant but which refer to the common
types (e.g. some @link tags, BaseRest’s inheritance from AbstractRest),
we switch to using a single TypeDoc project to generate documentation
for both variants.

For reasons that I don’t understand, TypeDoc is unable to resolve the
aforementioned @link tags unless I explicitly add a module source [1].
I’d have thought that it’d be sufficient to simply `import` the types
that these tags refer to, but doing so makes no difference. So, I’ve
added these module sources. Unfortunately, IntelliSense in VS Code
doesn’t know what to do with these and the link is not clickable. (I
also tried experimenting with TSDoc’s syntax for declaration references
[2] but it made no difference). I think we’ll have to live with this;
luckily there are only a few such tags.

[1] https://typedoc.org/guides/declaration-references/#module-source
[2] https://tsdoc.org/pages/tags/link/

README.md

@@ -110,7 +110,7 @@ You must provide:
 
 `BaseRealtime` offers the same API as the `Realtime` class described in the rest of this `README`. This means that you can develop an application using the default variant of the SDK and switch to the modular version when you wish to optimize your bundle size.
 
-For more information, see the [generated documentation](https://sdk.ably.com/builds/ably/ably-js/main/typedoc/modules/index.html) (this link points to the documentation for the `main` branch).
+For more information, see the [generated documentation](https://sdk.ably.com/builds/ably/ably-js/main/typedoc/modules/modules.html) (this link points to the documentation for the `main` branch).
 
 ### TypeScript
 

ably.d.ts

@@ -3,6 +3,14 @@
 // Definitions by: Ably <https://github.com/ably/>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
+/**
+ * You are currently viewing the default variant of the Ably JavaScript Client Library SDK. View the modular variant {@link modules | here}.
+ *
+ * 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.
+ *
+ * @module
+ */
+
 /**
  * Type definitions for Ably Realtime and REST client library.
  */

modules.d.ts

@@ -1,3 +1,27 @@
+/**
+ * You are currently viewing the modular (tree-shakable) variant of the Ably JavaScript Client Library SDK. View the default variant {@link ably | here}.
+ *
+ * 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.
+ *
+ * ## No `static` class functionality
+ *
+ * In contrast to the default variant of the SDK, the modular variant does not expose any functionality via `static` class properties or methods, since they cannot be tree-shaken by module bundlers. Instead, it exports free-standing functions which provide the same functionality. These are:
+ *
+ * | `static` version                           | Replacement in modular variant                                                     |
+ * | ------------------------------------------ | ---------------------------------------------------------------------------------- |
+ * | `Crypto.generateRandomKey()`               | [`generateRandomKey()`](../functions/modules.generateRandomKey.html)               |
+ * | `Crypto.getDefaultParams()`                | [`getDefaultCryptoParams()`](../functions/modules.getDefaultCryptoParams.html)     |
+ * | `MessageStatic.fromEncoded()`              | [`decodeMessage()`](../functions/modules.decodeMessage.html)                       |
+ * | `MessageStatic.fromEncoded()`              | [`decodeEncryptedMessage()`](../functions/modules.decodeEncryptedMessage.html)     |
+ * | `MessageStatic.fromEncodedArray()`         | [`decodeMessages()`](../functions/modules.decodeMessages.html)                     |
+ * | `MessageStatic.fromEncodedArray()`         | [`decodeEncryptedMessages()`](../functions/modules.decodeEncryptedMessages.html)   |
+ * | `PresenceMessageStatic.fromEncoded()`      | [`decodePresenceMessage()`](../functions/modules.decodePresenceMessage.html)       |
+ * | `PresenceMessageStatic.fromEncodedArray()` | [`decodePresenceMessages()`](../functions/modules.decodePresenceMessages.html)     |
+ * | `PresenceMessageStatic.fromValues()`       | [`constructPresenceMessage()`](../functions/modules.constructPresenceMessage.html) |
+ *
+ * @module
+ */
+
 import { Types, ErrorInfo } from './ably';
 
 export declare const generateRandomKey: Types.Crypto['generateRandomKey'];
@@ -22,22 +46,22 @@ export declare const constructPresenceMessage: Types.PresenceMessageStatic['from
  *
  * When provided, the following functionality becomes available:
  *
- * - { @link Types.Push | push admin }
+ * - { @link ably!Types.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 ably!Types.Auth.revokeTokens | requesting the revocation of tokens }
+ * - { @link ably!Types.RealtimeChannel.history | retrieving the message history of a channel }
+ * - { @link ably!Types.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 ably!Types.Message} payloads.
  *
  * To create a client that includes this module, include it in the `ModulesMap` that you pass to the {@link BaseRealtime.constructor}:
  *
@@ -46,7 +70,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 ably!Types.ChannelOptions.cipher} property of the `ChannelOptions` that you pass when {@link ably!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.
  */
 export declare const Crypto: unknown;
 
@@ -74,7 +98,7 @@ export declare const MsgPack: unknown;
  * const realtime = new BaseRealtime(options, { WebSocketTransport, FetchRequest, RealtimePresence });
  * ```
  *
- * 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 ably!Types.RealtimeChannel.presence} property will cause a runtime error.
  */
 export declare const RealtimePresence: unknown;
 
@@ -150,7 +174,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 ably!Types.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}:
  *
@@ -276,4 +300,4 @@ export declare class BaseRealtime extends Types.AbstractRealtime {
   constructor(options: Types.ClientOptions, modules: ModulesMap);
 }
 
-export { Types, ErrorInfo };
+export { ErrorInfo };

package.json

@@ -134,6 +134,6 @@
     "format:check": "prettier --check --ignore-path .gitignore --ignore-path .prettierignore src test ably.d.ts modules.d.ts webpack.config.js Gruntfile.js scripts/*.[jt]s",
     "sourcemap": "source-map-explorer build/ably.min.js",
     "modulereport": "tsc --noEmit scripts/moduleReport.ts && esr scripts/moduleReport.ts",
-    "docs": "typedoc --entryPoints ably.d.ts --out typedoc/generated/default --readme typedoc/landing-pages/default.md && typedoc --entryPoints modules.d.ts --out typedoc/generated/modules --name \"ably (modular version)\" --readme typedoc/landing-pages/modules.md && cp typedoc/landing-pages/choose-library.html typedoc/generated/index.html"
+    "docs": "typedoc"
   }
 }

test/package/browser/template/src/index-modules.ts

@@ -1,4 +1,5 @@
-import { BaseRealtime, Types, WebSocketTransport, FetchRequest, generateRandomKey } from 'ably/modules';
+import { BaseRealtime, WebSocketTransport, FetchRequest, generateRandomKey } from 'ably/modules';
+import { Types } from 'ably';
 import { createSandboxAblyAPIKey } from './sandbox';
 
 // This function exists to check that we can import the Types namespace and refer to its types.

typedoc.json

@@ -1,5 +1,8 @@
 {
   "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["ably.d.ts", "modules.d.ts"],
+  "out": "typedoc/generated",
+  "readme": "typedoc/landing-page.md",
   "treatWarningsAsErrors": true,
   "includeVersion": true,
   "validation": true,

typedoc/landing-page.md

@@ -0,0 +1,12 @@
+# 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.
+
+There are two variants of the Ably JavaScript Client Library SDK:
+
+- [Default variant](modules/ably.html): This variant of the SDK always creates a fully-featured Ably client.
+- [Modular (tree-shakable) variant](modules/modules.html): Aimed at those who are concerned about their app’s bundle size, this allows you to create a client which has only the functionality that you choose.
+
+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.