From 677063ff172d342ec71d2f0357dd8b169573398f Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Fri, 1 Mar 2024 18:21:14 -0300 Subject: [PATCH] Rename ably/modules export to ably/modular MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 2 +- .github/workflows/check.yml | 6 +-- Gruntfile.js | 8 ++-- README.md | 6 +-- ably.d.ts | 2 +- modules.d.ts => modular.d.ts | 40 +++++++++---------- package.json | 12 +++--- scripts/moduleReport.ts | 22 +++++----- src/platform/web/lib/http/request/index.ts | 2 +- src/platform/web/lib/transport/index.ts | 2 +- src/platform/web/{modules.ts => modular.ts} | 22 +++++----- .../web/{modules => modular}/crypto.ts | 0 src/platform/web/{modules => modular}/http.ts | 0 .../web/{modules => modular}/message.ts | 0 .../web/{modules => modular}/msgpack.ts | 0 .../{modules => modular}/presencemessage.ts | 0 .../{modules => modular}/realtimepresence.ts | 0 .../web/{modules => modular}/transports.ts | 0 .../{modules.test.js => modular.test.js} | 10 ++--- test/mocha.html | 2 +- test/package/browser/template/README.md | 4 +- test/package/browser/template/package.json | 2 +- ...{index-modules.html => index-modular.html} | 2 +- .../package/browser/template/server/server.ts | 2 +- .../{index-modules.ts => index-modular.ts} | 2 +- .../browser/template/test/lib/package.test.ts | 2 +- test/playwright.html | 2 +- test/support/browser_setup.js | 4 +- typedoc.json | 2 +- typedoc/landing-page.md | 2 +- 30 files changed, 80 insertions(+), 80 deletions(-) rename modules.d.ts => modular.d.ts (95%) rename src/platform/web/{modules.ts => modular.ts} (70%) rename src/platform/web/{modules => modular}/crypto.ts (100%) rename src/platform/web/{modules => modular}/http.ts (100%) rename src/platform/web/{modules => modular}/message.ts (100%) rename src/platform/web/{modules => modular}/msgpack.ts (100%) rename src/platform/web/{modules => modular}/presencemessage.ts (100%) rename src/platform/web/{modules => modular}/realtimepresence.ts (100%) rename src/platform/web/{modules => modular}/transports.ts (100%) rename test/browser/{modules.test.js => modular.test.js} (99%) rename test/package/browser/template/server/resources/{index-modules.html => index-modular.html} (78%) rename test/package/browser/template/src/{index-modules.ts => index-modular.ts} (98%) diff --git a/.eslintrc.js b/.eslintrc.js index a45654db34..bbac2927c6 100644 --- a/.eslintrc.js +++ b/.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', ], diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index a051e8f22e..c1120b6db8 100644 --- a/.github/workflows/check.yml +++ b/.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 diff --git a/Gruntfile.js b/Gruntfile.js index 908d6ebd77..d158a35d8b 100644 --- a/Gruntfile.js +++ b/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); diff --git a/README.md b/README.md index 50934223ef..8239c933e8 100644 --- a/README.md +++ b/README.md @@ -95,10 +95,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 */, @@ -124,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 diff --git a/ably.d.ts b/ably.d.ts index 07c39f497d..84bb9cf8f0 100644 --- a/ably.d.ts +++ b/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. * diff --git a/modules.d.ts b/modular.d.ts similarity index 95% rename from modules.d.ts rename to modular.d.ts index 6ec83d4dad..1e03425c8a 100644 --- a/modules.d.ts +++ b/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 } }); * ``` * diff --git a/package.json b/package.json index a134f514dd..b1e36ba611 100644 --- a/package.json +++ b/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/**" @@ -145,8 +145,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" diff --git a/scripts/moduleReport.ts b/scripts/moduleReport.ts index 64851816b3..2d72004951 100644 --- a/scripts/moduleReport.ts +++ b/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 { const bundleInfo = getBundleInfo(exports); @@ -125,7 +125,7 @@ async function calculateAndCheckExportSizes(): Promise { 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 { 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 { }); 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 { - 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[] = []; diff --git a/src/platform/web/lib/http/request/index.ts b/src/platform/web/lib/http/request/index.ts index 4fccec5b3b..91012f68d8 100644 --- a/src/platform/web/lib/http/request/index.ts +++ b/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 = {}; diff --git a/src/platform/web/lib/transport/index.ts b/src/platform/web/lib/transport/index.ts index ced6dc4eef..23e62165c2 100644 --- a/src/platform/web/lib/transport/index.ts +++ b/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: {}, }; diff --git a/src/platform/web/modules.ts b/src/platform/web/modular.ts similarity index 70% rename from src/platform/web/modules.ts rename to src/platform/web/modular.ts index e5e4f15b41..19a9b513a5 100644 --- a/src/platform/web/modules.ts +++ b/src/platform/web/modular.ts @@ -10,20 +10,20 @@ import BufferUtils from './lib/util/bufferutils'; import Http from './lib/http/http'; import Config from './config'; // @ts-ignore -import { ModulesTransports } from './lib/transport'; +import { ModularTransports } from './lib/transport'; import Logger from '../../common/lib/util/logger'; import { getDefaults } from '../../common/lib/util/defaults'; import WebStorage from './lib/util/webstorage'; import PlatformDefaults from './lib/util/defaults'; -import { modulesBundledRequestImplementations } from './lib/http/request'; +import { modularBundledRequestImplementations } from './lib/http/request'; Platform.BufferUtils = BufferUtils; Platform.Http = Http; Platform.Config = Config; -Platform.Transports = ModulesTransports; +Platform.Transports = ModularTransports; Platform.WebStorage = WebStorage; -Http.bundledRequestImplementations = modulesBundledRequestImplementations; +Http.bundledRequestImplementations = modularBundledRequestImplementations; Logger.initLogHandlers(); @@ -34,13 +34,13 @@ if (Platform.Config.agent) { Platform.Defaults.agent += ' ' + Platform.Config.agent; } -export * from './modules/crypto'; -export * from './modules/message'; -export * from './modules/presencemessage'; -export * from './modules/msgpack'; -export * from './modules/realtimepresence'; -export * from './modules/transports'; -export * from './modules/http'; +export * from './modular/crypto'; +export * from './modular/message'; +export * from './modular/presencemessage'; +export * from './modular/msgpack'; +export * from './modular/realtimepresence'; +export * from './modular/transports'; +export * from './modular/http'; export { Rest } from '../../common/lib/client/rest'; export { FilteredSubscriptions as MessageInteractions } from '../../common/lib/client/filteredsubscriptions'; export { BaseRest, BaseRealtime, ErrorInfo }; diff --git a/src/platform/web/modules/crypto.ts b/src/platform/web/modular/crypto.ts similarity index 100% rename from src/platform/web/modules/crypto.ts rename to src/platform/web/modular/crypto.ts diff --git a/src/platform/web/modules/http.ts b/src/platform/web/modular/http.ts similarity index 100% rename from src/platform/web/modules/http.ts rename to src/platform/web/modular/http.ts diff --git a/src/platform/web/modules/message.ts b/src/platform/web/modular/message.ts similarity index 100% rename from src/platform/web/modules/message.ts rename to src/platform/web/modular/message.ts diff --git a/src/platform/web/modules/msgpack.ts b/src/platform/web/modular/msgpack.ts similarity index 100% rename from src/platform/web/modules/msgpack.ts rename to src/platform/web/modular/msgpack.ts diff --git a/src/platform/web/modules/presencemessage.ts b/src/platform/web/modular/presencemessage.ts similarity index 100% rename from src/platform/web/modules/presencemessage.ts rename to src/platform/web/modular/presencemessage.ts diff --git a/src/platform/web/modules/realtimepresence.ts b/src/platform/web/modular/realtimepresence.ts similarity index 100% rename from src/platform/web/modules/realtimepresence.ts rename to src/platform/web/modular/realtimepresence.ts diff --git a/src/platform/web/modules/transports.ts b/src/platform/web/modular/transports.ts similarity index 100% rename from src/platform/web/modules/transports.ts rename to src/platform/web/modular/transports.ts diff --git a/test/browser/modules.test.js b/test/browser/modular.test.js similarity index 99% rename from test/browser/modules.test.js rename to test/browser/modular.test.js index 22bf3a299f..594b14671d 100644 --- a/test/browser/modules.test.js +++ b/test/browser/modular.test.js @@ -20,10 +20,10 @@ import { FetchRequest, XHRRequest, MessageInteractions, -} from '../../build/modules/index.js'; +} from '../../build/modular/index.js'; -function registerAblyModulesTests(helper) { - describe('browser/modules', function () { +function registerAblyModularTests(helper) { + describe('browser/modular', function () { this.timeout(10 * 1000); const expect = chai.expect; const BufferUtils = BaseRest.Platform.BufferUtils; @@ -782,10 +782,10 @@ function registerAblyModulesTests(helper) { } // This function is called by browser_setup.js once `require` is available -window.registerAblyModulesTests = async () => { +window.registerAblyModularTests = async () => { return new Promise((resolve) => { require(['shared_helper'], (helper) => { - registerAblyModulesTests(helper); + registerAblyModularTests(helper); resolve(); }); }); diff --git a/test/mocha.html b/test/mocha.html index 48746f80ea..490230b487 100644 --- a/test/mocha.html +++ b/test/mocha.html @@ -22,7 +22,7 @@ - + diff --git a/test/package/browser/template/README.md b/test/package/browser/template/README.md index ad3c029e7f..8bf44061be 100644 --- a/test/package/browser/template/README.md +++ b/test/package/browser/template/README.md @@ -8,7 +8,7 @@ This directory is intended to be used for testing the following aspects of the a It contains three files, each of which import ably-js in different manners, and provide a way to briefly exercise its functionality: - `src/index-default.ts` imports the default ably-js package (`import { Realtime } from 'ably'`). -- `src/index-modules.ts` imports the tree-shakable ably-js package (`import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modules'`). +- `src/index-modular.ts` imports the tree-shakable ably-js package (`import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modular'`). - `src/ReactApp.tsx` imports React hooks from the ably-js package (`import { useChannel } from 'ably/react'`). ## Why is `ably` not in `package.json`? @@ -25,6 +25,6 @@ This directory exposes three package scripts that are to be used for testing: - `build`: Uses esbuild to create: 1. a bundle containing `src/index-default.ts` and ably-js; - 2. a bundle containing `src/index-modules.ts` and ably-js. + 2. a bundle containing `src/index-modular.ts` and ably-js. - `test`: Using the bundles created by `build` and playwright components setup, tests that the code that exercises ably-js’s functionality is working correctly in a browser. - `typecheck`: Type-checks the code that imports ably-js. diff --git a/test/package/browser/template/package.json b/test/package/browser/template/package.json index 7a3bf1038d..a05aa04977 100644 --- a/test/package/browser/template/package.json +++ b/test/package/browser/template/package.json @@ -4,7 +4,7 @@ "description": "", "main": "index.js", "scripts": { - "build": "esbuild --bundle src/index-default.ts --outdir=dist && esbuild --bundle src/index-modules.ts --outdir=dist", + "build": "esbuild --bundle src/index-default.ts --outdir=dist && esbuild --bundle src/index-modular.ts --outdir=dist", "typecheck": "tsc --project src -noEmit", "test-support:server": "ts-node server/server.ts", "test": "npm run test:lib && npm run test:hooks", diff --git a/test/package/browser/template/server/resources/index-modules.html b/test/package/browser/template/server/resources/index-modular.html similarity index 78% rename from test/package/browser/template/server/resources/index-modules.html rename to test/package/browser/template/server/resources/index-modular.html index 0135008065..1a0ad35d14 100644 --- a/test/package/browser/template/server/resources/index-modules.html +++ b/test/package/browser/template/server/resources/index-modular.html @@ -5,7 +5,7 @@ Ably NPM package test (tree-shakable export) - + diff --git a/test/package/browser/template/server/server.ts b/test/package/browser/template/server/server.ts index 6eefe26aba..2409fc30c5 100644 --- a/test/package/browser/template/server/server.ts +++ b/test/package/browser/template/server/server.ts @@ -5,7 +5,7 @@ async function startWebServer(listenPort: number) { const server = express(); server.get('/', (req, res) => res.send('OK')); server.use(express.static(path.join(__dirname, '/resources'))); - for (const filename of ['index-default.js', 'index-modules.js']) { + for (const filename of ['index-default.js', 'index-modular.js']) { server.use(`/${filename}`, express.static(path.join(__dirname, '..', 'dist', filename))); } diff --git a/test/package/browser/template/src/index-modules.ts b/test/package/browser/template/src/index-modular.ts similarity index 98% rename from test/package/browser/template/src/index-modules.ts rename to test/package/browser/template/src/index-modular.ts index 32443954ed..a9186f56dd 100644 --- a/test/package/browser/template/src/index-modules.ts +++ b/test/package/browser/template/src/index-modular.ts @@ -1,4 +1,4 @@ -import { BaseRealtime, WebSocketTransport, FetchRequest, generateRandomKey } from 'ably/modules'; +import { BaseRealtime, WebSocketTransport, FetchRequest, generateRandomKey } from 'ably/modular'; import { InboundMessage, RealtimeChannel } from 'ably'; import { createSandboxAblyAPIKey } from './sandbox'; diff --git a/test/package/browser/template/test/lib/package.test.ts b/test/package/browser/template/test/lib/package.test.ts index bb8e35fe43..7397533af3 100644 --- a/test/package/browser/template/test/lib/package.test.ts +++ b/test/package/browser/template/test/lib/package.test.ts @@ -3,7 +3,7 @@ import { test, expect } from '@playwright/test'; test.describe('NPM package', () => { for (const scenario of [ { name: 'default export', path: '/index-default.html' }, - { name: 'modular export', path: '/index-modules.html' }, + { name: 'modular export', path: '/index-modular.html' }, ]) { test.describe(scenario.name, () => { test('can be imported and provides access to Ably functionality', async ({ page }) => { diff --git a/test/playwright.html b/test/playwright.html index 21fcce1dfa..22a0bf0ca1 100644 --- a/test/playwright.html +++ b/test/playwright.html @@ -21,7 +21,7 @@ - + diff --git a/test/support/browser_setup.js b/test/support/browser_setup.js index b668c84a45..9a4f59bba7 100644 --- a/test/support/browser_setup.js +++ b/test/support/browser_setup.js @@ -69,8 +69,8 @@ require([(baseUrl + '/test/common/globals/named_dependencies.js').replace('//', callback: () => { // (For some reason things don’t work if you return a Promise from this callback, hence the nested async function) (async () => { - // Let modules.test.js register its tests before we run the test suite - await registerAblyModulesTests(); + // Let modular.test.js register its tests before we run the test suite + await registerAblyModularTests(); // we have to kickoff mocha mocha.run(); diff --git a/typedoc.json b/typedoc.json index f7a58f1ec8..24faf3bad9 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,6 +1,6 @@ { "$schema": "https://typedoc.org/schema.json", - "entryPoints": ["ably.d.ts", "modules.d.ts"], + "entryPoints": ["ably.d.ts", "modular.d.ts"], "out": "typedoc/generated", "readme": "typedoc/landing-page.md", "treatWarningsAsErrors": true, diff --git a/typedoc/landing-page.md b/typedoc/landing-page.md index f52d4093a7..bbc69d315f 100644 --- a/typedoc/landing-page.md +++ b/typedoc/landing-page.md @@ -7,6 +7,6 @@ The realtime interface enables a client to maintain a persistent connection to A 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. +- [Modular (tree-shakable) variant](modules/modular.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.