Merge pull request #1709 from ably/release/2.0.0

Release 2.0.0

.eslintrc.js

@@ -19,19 +19,20 @@ module.exports = {
     "plugin:security/recommended",
   ],
   rules: {
-    // comma-dangle used for browser compatibility for browsers that don't support trailing commas
-    "comma-dangle": ["error", "always-multiline"],
     "eol-last": "error",
     // security/detect-object-injection just gives a lot of false positives
     // see https://github.com/nodesecurity/eslint-plugin-security/issues/21
     "security/detect-object-injection": "off",
     "@typescript-eslint/no-var-requires": "error",
+    // Use typescript-eslint’s version of the no-redeclare rule, which isn’t triggered by overload signatures.
+    // TODO remove this once we start using the full @typescript-eslint/recommended ruleset in #958
+    'no-redeclare': 'off',
+    '@typescript-eslint/no-redeclare': 'error',
   },
   overrides: [
     {
       files: ["**/*.{ts,tsx}"],
       rules: {
-        "comma-dangle": ["error", "only-multiline"],
         "@typescript-eslint/no-unused-vars": ["error", { "varsIgnorePattern": "^_" }],
         // TypeScript already enforces these rules better than any eslint setup can
         "no-undef": "off",
@@ -40,7 +41,7 @@ module.exports = {
       },
     },
     {
-      files: 'ably.d.ts',
+      files: ['ably.d.ts', 'modular.d.ts'],
       extends: [
         'plugin:jsdoc/recommended',
       ],
@@ -54,9 +55,10 @@ module.exports = {
     "test",
     "tools",
     "scripts",
-    "docs",
+    "typedoc/generated",
     "react",
     "Gruntfile.js",
+    "grunt",
   ],
   settings: {
     jsdoc: {

.github/workflows/bundle-report.yml

@@ -17,16 +17,15 @@ jobs:
         run: >
           git config --global url."https://github.com/".insteadOf
           ssh://git@github.com/
-      - name: Use Node.js 14.x
+      - name: Use Node.js 20.x
         uses: actions/setup-node@v1
         with:
-          node-version: 14.x
+          node-version: 20.x
       - run: npm ci
       - name: Build bundle reports
         run: |
             mkdir bundle-reports
             npm run sourcemap -- --html bundle-reports/index.html
-            npm run sourcemap:noencryption -- --html bundle-reports/noencryption.html
       - uses: aws-actions/configure-aws-credentials@v1
         with:
           aws-region: eu-west-2
@@ -37,3 +36,5 @@ jobs:
           sourcePath: bundle-reports
           githubToken: ${{ secrets.GITHUB_TOKEN }}
           artifactName: bundle-report
+      # This step performs some validation and may fail, so it should come after the steps that we want to always execute.
+      - run: npm run modulereport

.github/workflows/check.yml

@@ -14,16 +14,18 @@ jobs:
         run: >
           git config --global url."https://github.com/".insteadOf
           ssh://git@github.com/
-      - name: Use Node.js 14.x
+      - name: Use Node.js 20.x
         uses: actions/setup-node@v1
         with:
-          node-version: 14.x
+          node-version: 20.x
       - run: npm ci
       - run: npm run lint
       - run: npm run format:check
-      - run: npm run check-closure-compiler
-      - run: npx tsc --noEmit ably.d.ts build/ably-webworker.min.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
+      - run: npx attw ably-$(node -e "console.log(require('./package.json').version)").tgz --summary --exclude-entrypoints 'ably/modular'
+      # see https://github.com/ably/ably-js/issues/1546 for why we ignore 'false-cjs' currently.
+      # should remove when switched to auto-generated type declaration files for modular variant of the library.
+      - run: npx attw ably-$(node -e "console.log(require('./package.json').version)").tgz --summary --entrypoints 'ably/modular' --ignore-rules false-cjs
       - run: npm audit --production

.github/workflows/docs.yml

@@ -16,10 +16,10 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Use Node.js 16.x
+      - name: Use Node.js 20.x
         uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 20.x
 
       - name: Install Package Dependencies
         run: npm ci
@@ -37,6 +37,6 @@ jobs:
       - name: Upload Documentation
         uses: ably/sdk-upload-action@v1
         with:
-          sourcePath: docs/generated
+          sourcePath: typedoc/generated
           githubToken: ${{ secrets.GITHUB_TOKEN }}
           artifactName: typedoc

.github/workflows/publish-cdn.yml

@@ -23,9 +23,9 @@ jobs:
           aws-region: us-east-1
           role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/prod-ably-sdk-cdn
           role-session-name: "${{ github.run_id }}-${{ github.run_number }}"
-      - name: Use Node.js 14.x
+      - name: Use Node.js 20.x
         uses: actions/setup-node@v1
         with:
-          node-version: 14.x
+          node-version: 20.x
       - run: npm ci
       - run: node scripts/cdn_deploy.js --skipCheckout --tag=${{ github.event.inputs.version }}

.github/workflows/react.yml

@@ -14,7 +14,6 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v1
         with:
-          node-version: 16
+          node-version: 20
       - run: npm ci
-      - run: npm run format:check
       - run: npm run test:react

.github/workflows/test-browser.yml

@@ -20,10 +20,10 @@ jobs:
         run: >
           git config --global url."https://github.com/".insteadOf
           ssh://git@github.com/
-      - name: Use Node.js 16.x
+      - name: Use Node.js 20.x
         uses: actions/setup-node@v1
         with:
-          node-version: 16.x
+          node-version: 20.x
       - run: npm ci
       - name: Install Playwright browsers and dependencies
         run: npx playwright install --with-deps

.github/workflows/test-node.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [12.x, 14.x, 16.x]
+        node-version: [16.x, 18.x, 20.x]
     steps:
       - uses: actions/checkout@v2
         with:

.github/workflows/test-package.yml

@@ -0,0 +1,20 @@
+name: Test NPM package
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test-npm-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: true
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v1
+        with:
+          node-version: 20.x
+      - run: npm ci
+      - run: npm run test:package

.gitignore

@@ -6,6 +6,6 @@ npm-debug.log
 .tool-versions
 build/
 react/
-docs/generated/
+typedoc/generated/
 junit/
 test/support/mocha_junit_reporter/build/

.mocharc.js

@@ -0,0 +1,19 @@
+const config = {
+  require: ['source-map-support/register', 'test/support/modules_helper.js', 'test/support/test_helper.js'],
+  file: ['test/support/root_hooks.js'],
+  reporter: 'test/support/mocha_reporter.js',
+};
+
+// mocha has a ridiculous issue (https://github.com/mochajs/mocha/issues/4100) that command line
+// specs don't override config specs; they are merged instead, so you can't run a single test file
+// if you've defined specs in your config. therefore we work around it by only adding specs to the
+// config if none are passed as arguments
+if (!process.argv.slice(2).some(isTestFile)) {
+  config.spec = ['test/realtime/*.test.js', 'test/rest/*.test.js'];
+}
+
+function isTestFile(arg) {
+  return arg.match(/\.test.js$/);
+}
+
+module.exports = config;

.prettierrc.json

@@ -1,5 +1,5 @@
 {
-  "trailingComma": "es5",
+  "trailingComma": "all",
   "tabWidth": 2,
   "semi": true,
   "singleQuote": true,

CHANGELOG.md

@@ -2,6 +2,92 @@
 
 This contains only the most important and/or user-facing changes; for a full changelog, see the commit history.
 
+## [2.0.0](https://github.com/ably/ably-js/tree/2.0.0) (2024-03-22)
+
+The 2.0.0 release introduces a number of new features and QoL improvements, including a new way to remove bloat and reduce the bundle size of your ably-js client, first-class support for Promises, a more idiomatic approach to using ably-js' React Hooks, enhancements to TypeScript typings, and more.
+
+Below is an overview of the major changes in this release.
+
+Please refer to the ably-js v2 [lib migration guide](./docs/migration-guides/v2/lib.md) and [React Hooks migration guide](./docs/migration-guides/v2/react-hooks.md) for the full details, including a list of all breaking changes and instructions on how to address them.
+
+### Bundle Size Reduction
+
+The default bundle size for the web has been reduced by ~32% compared to v1 - from 234.11 KiB to 159.32 KiB. When calculated with gzip compression, the reduction is ~30%, from 82.54 KiB to 57.9 KiB.
+
+Additionally, by utilizing the new modular variant of the library (see below) and JavaScript tree shaking, you can create your own minimal useful `Realtime` client and achieve a bundle size reduction of ~60.5% compared to v1 - from 234.11 KiB to 92.38 KiB (or ~66% for gzip: from 82.54 KiB to 28.18 KiB).
+
+### Modular variant of the library
+
+An ESM variant of the library is now available for browsers (but not for Node.js) via import from `ably/modular`. This modular variant of the library supports tree shaking, allowing for a reduction in the Ably bundle size within your application and improving the user experience. It can also be used by Web Workers.
+
+### React Hooks changes
+
+React Hooks, exported at `ably/react`, now require the new `ChannelProvider` component to define the channels you wish to use and the options for them. This addresses the complexities previously encountered with `useChannel` and `usePresence` hooks when attempting to dynamically change options for a channel and provides a more straightforward approach to set and manage these options.
+
+The functionality of the `usePresence` hook has been split into two separate hooks: `usePresence`, which is now used only to enter presence, and `usePresenceListener`, which is used to listen for presence updates. These new hooks offer better control over the desired presence behavior in your React components.
+
+### First-class support for Promises
+
+The callbacks API has been entirely removed, and the library now supports promises for all its asynchronous operations by default.
+
+### TypeScript typings
+
+The Types namespace has been removed. All types it contained are now exported at the top level.
+
+### Browser and Web Worker bundles
+
+- The browser bundle now relies on the native Web Crypto API instead of CryptoJS. The `ably/build/ably.noencryption` bundle has been removed, as it is no longer necessary.
+- The browser bundle can now be directly used by Web Workers. The `ably/build/ably-webworker` bundle has been removed, as it is no longer necessary.
+
+### Supported platforms changes
+
+- Support for Internet Explorer has been dropped.
+- Support for Node.js versions lower than 16 has been dropped. The supported Node.js versions are now 16, 18, and 20.
+- The minimum supported versions for major browsers are: Chrome 58, Firefox 52, Edge 79, Safari 11, and Opera 45.
+
+<details>
+<summary><b>View merged Pull Requests</b></summary>
+
+### Breaking Changes
+
+- Add `ChannelProvider` component to React Hooks [\#1620](https://github.com/ably/ably-js/pull/1620), [\#1654](https://github.com/ably/ably-js/pull/1654)
+- Add untyped stats API [\#1522](https://github.com/ably/ably-js/pull/1522)
+- Add type definitions for key returned by `generateRandomKey` [\#1320](https://github.com/ably/ably-js/pull/1320)
+- Add mandatory `version` param to `Rest.request` [\#1231](https://github.com/ably/ably-js/pull/1231)
+- Change `id` field to be named `ablyId` in React Hooks [\#1676](https://github.com/ably/ably-js/pull/1676)
+- Change `usePresence` hook to two different hooks: for entering presence and subscribing to presence updates [\#1674](https://github.com/ably/ably-js/pull/1674)
+- Change naming for enum-like namespaces in type declarations and change meaning for public `ChannelModes` type [\#1601](https://github.com/ably/ably-js/pull/1601)
+- Change publishing methods to accept a `Message`-shaped object [\#1515](https://github.com/ably/ably-js/pull/1515)
+- Change `Crypto.generateRandomKey` API to use Promises [\#1351](https://github.com/ably/ably-js/pull/1351)
+- Change `fromEncoded()` and `fromEncodedArray()` methods on `Message` and `PresenceMessage` to be async [\#1311](https://github.com/ably/ably-js/pull/1311)
+- Remove `XHRStreaming` transport support [\#1645](https://github.com/ably/ably-js/pull/1645)
+- Remove code that's supporting older platforms [\#1629](https://github.com/ably/ably-js/pull/1629), [\#1633](https://github.com/ably/ably-js/pull/1633), [\#1641](https://github.com/ably/ably-js/pull/1641)
+- Remove `recoveryKey` in favour of `createRecoveryKey()` on `Connection` [\#1613](https://github.com/ably/ably-js/pull/1613)
+- Remove `any` from `stats()` param type [\#1561](https://github.com/ably/ably-js/pull/1561)
+- Remove the dedicated Web Worker bundle `ably/build/ably-webworker` and add support for using `ably` and `ably/modular` in Web Workers [\#1550](https://github.com/ably/ably-js/pull/1550)
+- Remove false class exports in type declarations [\#1524](https://github.com/ably/ably-js/pull/1524)
+- Remove the `Types` namespace [\#1518](https://github.com/ably/ably-js/pull/1518)
+- Remove `noencryption` variant of the library [\#1500](https://github.com/ably/ably-js/pull/1500)
+- Remove public callbacks API [\#1358](https://github.com/ably/ably-js/pull/1358)
+- Remove CryptoJS library and replace it with the Web Crypto API in web bundle [\#1299](https://github.com/ably/ably-js/pull/1299), [\#1325](https://github.com/ably/ably-js/pull/1325), [\#1333](https://github.com/ably/ably-js/pull/1333)
+- Remove `ably-commonjs*.js` files [\#1229](https://github.com/ably/ably-js/pull/1229)
+- Remove deprecated APIs [\#1227](https://github.com/ably/ably-js/pull/1227)
+- Remove deprecated `fromEncoded*` type declarations [\#1222](https://github.com/ably/ably-js/pull/1222)
+- Remove deprecated `ClientOptions` parameters [\#1221](https://github.com/ably/ably-js/pull/1221)
+- Remove the `ClientOptions.log` property and replace it with separate `logLevel` and `logHandler` properties [\#1216](https://github.com/ably/ably-js/pull/1216)
+- Remove support for JSONP [\#1215](https://github.com/ably/ably-js/pull/1215)
+- Fix `whenState` inconsistent behavior in `Connection` and `RealtimeChannel` [\#1640](https://github.com/ably/ably-js/pull/1640)
+- Fix the type definition of `Crypto.getDefaultParams` [\#1352](https://github.com/ably/ably-js/pull/1352)
+
+### Features
+
+- Add `publish` function to the `useChannel` hook [\#1658](https://github.com/ably/ably-js/pull/1658)
+- Add logs to all HTTP activity [\#1581](https://github.com/ably/ably-js/pull/1581)
+
+</details>
+
+[Full Changelog](https://github.com/ably/ably-js/compare/1.2.50...2.0.0)
+
 ## [1.2.50](https://github.com/ably/ably-js/tree/1.2.50) (2024-03-21)
 
 - Add new logging API to `ClientOptions` and add a deprecation warning for the old one [\#1671](https://github.com/ably/ably-js/pull/1671)

CONTRIBUTING.md

@@ -8,9 +8,8 @@
 4. Commit your changes (`git commit -am 'Add some feature'`)
 5. Ensure you have added suitable tests and the test suite is passing(`npm test`)
 6. Ensure the [type definitions](https://github.com/ably/ably-js/blob/main/ably.d.ts) have been updated if the public API has changed
-7. Ensure you stick to the version of JS used by the library (currently ES5). (The minfication task (`npm run grunt -- closureCompiler:ably.js`) will enforce that you stick to ES5 syntax, but will not enforce that you don't use, for example, new methods)
-8. Push the branch (`git push origin my-new-feature`)
-9. Create a new Pull Request
+7. Push the branch (`git push origin my-new-feature`)
+8. Create a new Pull Request
 
 ## Release Process
 
@@ -30,7 +29,7 @@
 
 ## Building the library
 
-To build the library, simply run `npm run build`. Building the library currently requires NodeJS <= v16.
+To build the library, simply run `npm run build`. Building the library currently requires NodeJS >= v16.
 
 Since webpack builds are slow, commands are also available to only build the output for specific platforms (eg `npm run build:node`), see [package.json](./package.json) for the full list of available commands
 
@@ -46,27 +45,27 @@ Run the Mocha test suite
 
     npm run test:node
 
-Or run just one test file
+You can pass any Mocha CLI arguments and flags to the test:node script after the `--` separator, for example running one test file:
 
-    npm run test:node -- --file=test/realtime/auth.test.js
+    npm run test:node -- test/realtime/auth.test.js
 
 Or run just one test
 
-    npm run test:node -- --file=test/rest/status.test.js --grep=test_name_here 
+    npm run test:node -- --grep=test_name_here
 
 Or run test skipping the build
 
-    npm run test:node:skip-build -- --file=test/rest/status.test.js --grep=test_name_here 
+    npm run test:node:skip-build -- test/rest/status.test.js --grep=test_name_here
 
 ### Debugging the mocha tests locally with a debugger
 
 Run the following command to launch tests with the debugger enabled. The tests will block until you attach a debugger.
 
-    node --inspect-brk=9229 node_modules/.bin/grunt test:node
+    node --inspect-brk=9229 node_modules/.bin/mocha
 
 Alternatively you can also run the tests for single file
 
-    node --inspect-brk=9229 node_modules/.bin/grunt test:node --test=test/realtime/auth.test.js
+    node --inspect-brk=9229 node_modules/.bin/mocha test/realtime/auth.test.js
 
 The included vscode launch config allows you to launch and attach the debugger in one step, simply open the test
 file you want to run and start debugging. Note that breakpoint setting for realtime code will be within the