Merge pull request #1663 from ably/1662-restore-plugins-and-use-for-m…

…odular-variant

[ECO-4658] Restore `ClientOptions.plugins` mechanism and use it for modular variant

.eslintrc.js

@@ -41,7 +41,7 @@ module.exports = {
       },
     },
     {
-      files: ['ably.d.ts', 'modules.d.ts'],
+      files: ['ably.d.ts', 'modular.d.ts'],
       extends: [
         'plugin:jsdoc/recommended',
       ],

.github/workflows/check.yml

@@ -21,10 +21,10 @@ jobs:
       - run: npm ci
       - run: npm run lint
       - run: npm run format:check
-      - run: npx tsc --noEmit ably.d.ts modules.d.ts
+      - run: npx tsc --noEmit ably.d.ts modular.d.ts
       # for some reason, this doesn't work in CI using `npx attw --pack .`
       - run: npm pack
-      - run: npx attw ably-$(node -e "console.log(require('./package.json').version)").tgz --summary --exclude-entrypoints 'ably/modules'
+      - run: npx attw ably-$(node -e "console.log(require('./package.json').version)").tgz --summary --exclude-entrypoints 'ably/modular'
       # TODO understand this unexpected-module-syntax error (https://github.com/ably/ably-js/issues/1546)
-      - run: npx attw ably-$(node -e "console.log(require('./package.json').version)").tgz --summary --entrypoints 'ably/modules' --ignore-rules unexpected-module-syntax
+      - run: npx attw ably-$(node -e "console.log(require('./package.json').version)").tgz --summary --entrypoints 'ably/modular' --ignore-rules unexpected-module-syntax
       - run: npm audit --production

Gruntfile.js

@@ -124,15 +124,15 @@ module.exports = function (grunt) {
       };
     }
 
-    function createModulesConfig() {
+    function createModularConfig() {
       return {
         // We need to create a new copy of the base config, because calling
         // esbuild.build() with the base config causes it to mutate the passed
         // config’s `banner.js` property to add some weird modules shim code,
         // which we don’t want here.
         ...createBaseConfig(),
-        entryPoints: ['src/platform/web/modules.ts'],
-        outfile: 'build/modules/index.js',
+        entryPoints: ['src/platform/web/modular.ts'],
+        outfile: 'build/modular/index.js',
         format: 'esm',
         plugins: [stripLogsPlugin],
       };
@@ -145,7 +145,7 @@ module.exports = function (grunt) {
         outfile: 'build/ably.min.js',
         minify: true,
       }),
-      esbuild.build(createModulesConfig()),
+      esbuild.build(createModularConfig()),
     ]).then(() => {
       console.log('esbuild succeeded');
       done(true);

README.md

@@ -93,18 +93,20 @@ Aimed at those who are concerned about their app’s bundle size, the modular va
 The modular variant of the library provides:
 
 - a `BaseRealtime` class;
-- various modules that add functionality to a `BaseRealtime` instance, such as `Rest`, `RealtimePresence`, etc.
+- various plugins that add functionality to a `BaseRealtime` instance, such as `Rest`, `RealtimePresence`, etc.
 
-To use this variant of the library, import the `BaseRealtime` class from `ably/modules`, along with the modules that you wish to use. Then, pass these modules to the `BaseRealtime` constructor as shown in the example below:
+To use this variant of the library, import the `BaseRealtime` class from `ably/modular`, along with the plugins that you wish to use. Then, pass these plugins to the `BaseRealtime` constructor as shown in the example below:
 
 ```javascript
-import { BaseRealtime, WebSocketTransport, FetchRequest, RealtimePresence } from 'ably/modules';
+import { BaseRealtime, WebSocketTransport, FetchRequest, RealtimePresence } from 'ably/modular';
 
-const options = { key: 'YOUR_ABLY_API_KEY' /* Replace with a real key from the Ably dashboard */ };
-const client = new BaseRealtime(options, {
-  WebSocketTransport,
-  FetchRequest,
-  RealtimePresence
+const client = new BaseRealtime({
+  key: 'YOUR_ABLY_API_KEY' /* Replace with a real key from the Ably dashboard */,
+  plugins: {
+    WebSocketTransport,
+    FetchRequest,
+    RealtimePresence,
+  },
 });
 ```
 
@@ -122,7 +124,7 @@ In order to further reduce bundle size, the modular variant of the SDK performs
 
 If you need more verbose logging, use the default variant of the SDK.
 
-For more information about the modular variant of the SDK, 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).
+For more information about the modular variant of the SDK, see the [generated documentation](https://sdk.ably.com/builds/ably/ably-js/main/typedoc/modules/modular.html) (this link points to the documentation for the `main` branch).
 
 ### TypeScript
 
@@ -212,39 +214,7 @@ channel.subscribe('myEvent', function (message) {
 
 Subscribing to a channel in delta mode enables [delta compression](https://www.ably.com/docs/realtime/channels/channel-parameters/deltas). This is a way for a client to subscribe to a channel so that message payloads sent contain only the difference (ie the delta) between the present message and the previous message on the channel.
 
-To subscribe to a channel in delta mode, you must:
-
-1. Create a client that supports deltas (this only applies when running in a browser);
-2. Configure the channel to operate in delta mode.
-
-#### Creating a client that supports deltas
-
-This section only applies when running in a browser. The Realtime client on all other platforms includes delta support.
-
-To use delta functionality in the browser, you must use the [modular variant of the library](#modular-tree-shakable-variant) and create a client that includes the `Vcdiff` module:
-
-  ```javascript
-  import { BaseRealtime, WebSocketTransport, FetchRequest, Vcdiff } from 'ably/modules';
-
-  const options = { key: 'YOUR_ABLY_KEY' };
-  const client = new BaseRealtime(options, {
-    WebSocketTransport,
-    FetchRequest,
-    Vcdiff
-  });
-  ```
-
-#### Configuring a channel to operate in delta mode
-
-To configure a channel to operate in delta mode, specify channel parameters of `{ delta: 'vcdiff' }` when fetching the channel:
-
-```javascript
-const channel = realtime.channels.get('your-ably-channel', {
-    params: {
-        delta: 'vcdiff'
-    }
-});
-```
+Configuring a channel for deltas is detailed in the [@ably-forks/vcdiff-decoder documentation](https://github.com/ably-forks/vcdiff-decoder#usage).
 
 Beyond specifying channel options, the rest is transparent and requires no further changes to your application. The `message.data` instances that are delivered to your listening function continue to contain the values that were originally published.
 
@@ -518,6 +488,13 @@ const nextPage = await statsPage.next();        // retrieves the next page as Pa
 const time = await client.time(); // time is in ms since epoch
 ```
 
+## Delta Plugin
+
+From version 1.2 this client library supports subscription to a stream of Vcdiff formatted delta messages from the Ably service. For certain applications this can bring significant data efficiency savings.
+This is an optional feature so our
+
+See the [@ably-forks/vcdiff-decoder documentation](https://github.com/ably-forks/vcdiff-decoder#usage) for setup and usage examples.
+
 ## Support, feedback and troubleshooting
 
 Please visit http://support.ably.com/ for access to our knowledgebase and to ask for any assistance.

ably.d.ts

@@ -4,7 +4,7 @@
 // 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}.
+ * You are currently viewing the default variant of the Ably JavaScript Client Library SDK. View the modular variant {@link modular | 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.
  *
@@ -370,7 +370,7 @@ export interface ChannelMetrics {
 /**
  * Passes additional client-specific properties to the REST constructor or the Realtime constructor.
  */
-export interface ClientOptions extends AuthOptions {
+export interface ClientOptions<Plugins = CorePlugins> extends AuthOptions {
   /**
    * When `true`, the client connects to Ably as soon as it is instantiated. You can set this to `false` and explicitly connect to Ably using the {@link Connection.connect | `connect()`} method. The default is `true`.
    *
@@ -569,6 +569,21 @@ export interface ClientOptions extends AuthOptions {
    * @defaultValue 10s
    */
   realtimeRequestTimeout?: number;
+
+  /**
+   * A map between a plugin type and a plugin object.
+   */
+  plugins?: Plugins;
+}
+
+/**
+ * Describes the {@link ClientOptions.plugins | plugins} accepted by all variants of the SDK.
+ */
+export interface CorePlugins {
+  /**
+   * A plugin capable of decoding `vcdiff`-encoded messages. For more information on how to configure a channel to use delta encoding, see the [documentation for the `@ably-forks/vcdiff-decoder` package](https://github.com/ably-forks/vcdiff-decoder#usage).
+   */
+  vcdiff?: any;
 }
 
 /**