Rename ably/modules export to ably/modular

We refer to it in our documentation as “the modular variant”, so this
name makes more sense to me.

(Also, the word “modules” gives the impression that the distinguishing
factor of this variant of the library is the fact that it uses ES
modules, but that isn’t necessarily the case — we may at some point
choose to create an ES modules version of the default variant, too.)

.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

@@ -86,10 +86,10 @@ The modular variant of the library provides:
 - a `BaseRealtime` class;
 - 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 plugins that you wish to use. Then, pass these plugins 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 client = new BaseRealtime({
   key: 'YOUR_ABLY_API_KEY' /* Replace with a real key from the Ably dashboard */,
@@ -115,7 +115,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
 

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.
  *

modules.d.ts → modular.d.ts

@@ -9,15 +9,15 @@
  *
  * | `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) |
+ * | `Crypto.generateRandomKey()`               | [`generateRandomKey()`](../functions/modular.generateRandomKey.html)               |
+ * | `Crypto.getDefaultParams()`                | [`getDefaultCryptoParams()`](../functions/modular.getDefaultCryptoParams.html)     |
+ * | `MessageStatic.fromEncoded()`              | [`decodeMessage()`](../functions/modular.decodeMessage.html)                       |
+ * | `MessageStatic.fromEncoded()`              | [`decodeEncryptedMessage()`](../functions/modular.decodeEncryptedMessage.html)     |
+ * | `MessageStatic.fromEncodedArray()`         | [`decodeMessages()`](../functions/modular.decodeMessages.html)                     |
+ * | `MessageStatic.fromEncodedArray()`         | [`decodeEncryptedMessages()`](../functions/modular.decodeEncryptedMessages.html)   |
+ * | `PresenceMessageStatic.fromEncoded()`      | [`decodePresenceMessage()`](../functions/modular.decodePresenceMessage.html)       |
+ * | `PresenceMessageStatic.fromEncodedArray()` | [`decodePresenceMessages()`](../functions/modular.decodePresenceMessages.html)     |
+ * | `PresenceMessageStatic.fromValues()`       | [`constructPresenceMessage()`](../functions/modular.constructPresenceMessage.html) |
  *
  * @module
  */
@@ -68,7 +68,7 @@ export declare const constructPresenceMessage: PresenceMessageStatic['fromValues
  * To create a client that includes this plugin, include it in the client options that you pass to the {@link BaseRealtime.constructor}:
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest, Rest } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest, Rest } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, FetchRequest, Rest } });
  * ```
  *
@@ -95,7 +95,7 @@ export declare const Rest: unknown;
  * To create a client that includes this plugin, include it in the client options that you pass to the {@link BaseRealtime.constructor}:
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest, Crypto } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest, Crypto } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, FetchRequest, Crypto } });
  * ```
  *
@@ -109,7 +109,7 @@ export declare const Crypto: unknown;
  * To create a client that includes this plugin, include it in the client options that you pass to the {@link BaseRealtime.constructor}:
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest, MsgPack } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest, MsgPack } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, FetchRequest, MsgPack } });
  * ```
  *
@@ -123,7 +123,7 @@ export declare const MsgPack: unknown;
  * To create a client that includes this plugin, include it in the client options that you pass to the {@link BaseRealtime.constructor}:
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest, RealtimePresence } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest, RealtimePresence } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, FetchRequest, RealtimePresence } });
  * ```
  *
@@ -137,14 +137,14 @@ export declare const RealtimePresence: unknown;
  * To create a client that includes this plugin, include it in the client options that you pass to the {@link BaseRealtime.constructor}:
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, FetchRequest } });
  * ```
  *
  * Note that network conditions, such as firewalls or proxies, might prevent the client from establishing a WebSocket connection. For this reason, you may wish to provide the `BaseRealtime` instance with the ability to alternatively establish a connection using a transport that is less susceptible to these external conditions. You do this by passing one or more alternative transport plugins, namely {@link XHRStreaming} and/or {@link XHRPolling}, alongside `WebSocketTransport`:
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, XHRStreaming, FetchRequest } });
  * ```
  */
@@ -156,7 +156,7 @@ export declare const WebSocketTransport: unknown;
  * `XHRPolling` uses HTTP long polling; that is, it will make a new HTTP request each time a message is received from Ably. This is less efficient than {@link XHRStreaming}, but is also more likely to succeed in the presence of certain network conditions such as firewalls or proxies.
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { XHRPolling, FetchRequest } });
  * ```
  *
@@ -170,7 +170,7 @@ export declare const XHRPolling: unknown;
  * `XHRStreaming` uses HTTP streaming; that is, in contrast to {@link XHRPolling}, it does not need to make a new HTTP request each time a message is received from Ably. This is more efficient than `XHRPolling`, but is more likely to be blocked by certain network conditions such as firewalls or proxies.
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { XHRStreaming, FetchRequest } });
  * ```
  *
@@ -184,7 +184,7 @@ export declare const XHRStreaming: unknown;
  * To create a client that includes this plugin, include it in the client options that you pass to the {@link BaseRealtime.constructor}:
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, XHRRequest } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, XHRRequest } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, XHRRequest } });
  * ```
  */
@@ -196,7 +196,7 @@ export declare const XHRRequest: unknown;
  * To create a client that includes this plugin, include it in the client options that you pass to the {@link BaseRealtime.constructor}:
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, FetchRequest } });
  * ```
  */
@@ -208,7 +208,7 @@ export declare const FetchRequest: unknown;
  * To create a client that includes this plugin, include it in the client options that you pass to the {@link BaseRealtime.constructor}:
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest, MessageInteractions } from 'ably/modules';
+ * import { BaseRealtime, WebSocketTransport, FetchRequest, MessageInteractions } from 'ably/modular';
  * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, FetchRequest, MessageInteractions } });
  * ```
  *

package.json

@@ -14,9 +14,9 @@
       "react-native": "./build/ably-reactnative.js",
       "default": "./build/ably.js"
     },
-    "./modules": {
-      "types": "./modules.d.ts",
-      "default": "./build/modules/index.js"
+    "./modular": {
+      "types": "./modular.d.ts",
+      "default": "./build/modular/index.js"
     },
     "./react": {
       "require": "./react/cjs/index.js",
@@ -27,7 +27,7 @@
   "files": [
     "build/**",
     "ably.d.ts",
-    "modules.d.ts",
+    "modular.d.ts",
     "resources/**",
     "src/**",
     "react/**"
@@ -148,8 +148,8 @@
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "prepare": "npm run build",
-    "format": "prettier --write --ignore-path .gitignore --ignore-path .prettierignore src test ably.d.ts modules.d.ts webpack.config.js Gruntfile.js scripts/*.[jt]s docs/chrome-mv3.md grunt",
-    "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 grunt",
+    "format": "prettier --write --ignore-path .gitignore --ignore-path .prettierignore src test ably.d.ts modular.d.ts webpack.config.js Gruntfile.js scripts/*.[jt]s docs/chrome-mv3.md grunt",
+    "format:check": "prettier --check --ignore-path .gitignore --ignore-path .prettierignore src test ably.d.ts modular.d.ts webpack.config.js Gruntfile.js scripts/*.[jt]s grunt",
     "sourcemap": "source-map-explorer build/ably.min.js",
     "modulereport": "tsc --noEmit --esModuleInterop scripts/moduleReport.ts && esr scripts/moduleReport.ts",
     "docs": "typedoc"

scripts/moduleReport.ts

@@ -10,8 +10,8 @@ const minimalUsefulRealtimeBundleSizeThresholdsKiB = { raw: 95, gzip: 29 };
 
 const baseClientNames = ['BaseRest', 'BaseRealtime'];
 
-// List of all modules accepted in ModularPlugins
-const moduleNames = [
+// List of all plugins accepted in ModularPlugins
+const pluginNames = [
   'Rest',
   'Crypto',
   'MsgPack',
@@ -65,12 +65,12 @@ interface Output {
   errors: Error[];
 }
 
-// Uses esbuild to create a bundle containing the named exports from 'ably/modules'
+// Uses esbuild to create a bundle containing the named exports from 'ably/modular'
 function getBundleInfo(exports: string[]): BundleInfo {
   const outfile = exports.join('');
   const result = esbuild.buildSync({
     stdin: {
-      contents: `export { ${exports.join(', ')} } from './build/modules'`,
+      contents: `export { ${exports.join(', ')} } from './build/modular'`,
       resolveDir: '.',
     },
     metafile: true,
@@ -97,7 +97,7 @@ function getBundleInfo(exports: string[]): BundleInfo {
   };
 }
 
-// Gets the bundled size in bytes of an array of named exports from 'ably/modules'
+// Gets the bundled size in bytes of an array of named exports from 'ably/modular'
 async function getImportSizes(exports: string[]): Promise<ByteSizes> {
   const bundleInfo = getBundleInfo(exports);
 
@@ -125,7 +125,7 @@ async function calculateAndCheckExportSizes(): Promise<Output> {
     output.tableRows.push({ description: baseClient, sizes: baseClientSizes });
 
     // Then output the size of each export together with the base client
-    for (const exportName of [...moduleNames, ...functions.map((functionData) => functionData.name)]) {
+    for (const exportName of [...pluginNames, ...functions.map((functionData) => functionData.name)]) {
       const sizes = await getImportSizes([baseClient, exportName]);
       output.tableRows.push({ description: `${baseClient} + ${exportName}`, sizes });
 
@@ -150,7 +150,7 @@ async function calculateAndCheckFunctionSizes(): Promise<Output> {
     const standaloneSizes = await getImportSizes([functionName]);
     output.tableRows.push({ description: functionName, sizes: standaloneSizes });
 
-    // Then output the size of the function together with the modules we expect
+    // Then output the size of the function together with the plugin we expect
     // it to transitively import
     if (transitiveImports.length > 0) {
       const withTransitiveImportsSizes = await getImportSizes([functionName, ...transitiveImports]);
@@ -160,11 +160,11 @@ async function calculateAndCheckFunctionSizes(): Promise<Output> {
       });
 
       if (withTransitiveImportsSizes.rawByteSize > standaloneSizes.rawByteSize) {
-        // Emit an error if the bundle size is increased by adding the modules
+        // Emit an error if the bundle size is increased by adding the plugins
         // that we expect this function to have transitively imported anyway.
         // This seemed like a useful sense check, but it might need tweaking in
         // the future if we make future optimisations that mean that the
-        // standalone functions don’t necessarily import the whole module.
+        // standalone functions don’t necessarily import the whole plugin.
         output.errors.push(
           new Error(
             `Adding ${transitiveImports.join(' + ')} to ${functionName} unexpectedly increases the bundle size.`
@@ -209,7 +209,7 @@ async function calculateAndCheckMinimalUsefulRealtimeBundleSize(): Promise<Outpu
 }
 
 async function calculateAllExportsBundleSize(): Promise<Output> {
-  const exports = [...baseClientNames, ...moduleNames, ...functions.map((val) => val.name)];
+  const exports = [...baseClientNames, ...pluginNames, ...functions.map((val) => val.name)];
   const sizes = await getImportSizes(exports);
 
   return { tableRows: [{ description: 'All exports', sizes }], errors: [] };
@@ -263,7 +263,7 @@ async function checkBaseRealtimeFiles() {
     'src/platform/web/lib/util/defaults.ts',
     'src/platform/web/lib/util/hmac-sha256.ts',
     'src/platform/web/lib/util/webstorage.ts',
-    'src/platform/web/modules.ts',
+    'src/platform/web/modular.ts',
   ]);
 
   const errors: Error[] = [];

src/platform/web/lib/http/request/index.ts

@@ -7,4 +7,4 @@ export const defaultBundledRequestImplementations: HTTPRequestImplementations =
   FetchRequest: fetchRequest,
 };
 
-export const modulesBundledRequestImplementations: HTTPRequestImplementations = {};
+export const modularBundledRequestImplementations: HTTPRequestImplementations = {};

src/platform/web/lib/transport/index.ts

@@ -19,7 +19,7 @@ const defaultTransports: (typeof Platform)['Transports'] = {
 
 export default defaultTransports;
 
-export const ModulesTransports: (typeof Platform)['Transports'] = {
+export const ModularTransports: (typeof Platform)['Transports'] = {
   order,
   bundledImplementations: {},
 };