ably-js

With this release, Ably React Hooks have now moved to the general availability phase and are considered stable. Non-major version changes to the ably package won't include breaking changes for React Hooks going forward.

All changes:

• Add support for optional multiple recovery scopes via ClientOptions.recoveryKeyStorageName #1762
• Add wildcard * and privileged-headers values for TokenParams.capability field #1765
• Add support for unique logHandler per Ably client by removing the global effects of setting logHandler and logLevel #1764
• Change updateStatus function returned by usePresence hook to be async #1777
• Fix some of the errors thrown by ConnectionManager have misleading stack traces #1760
• Fix FetchRequest doesn't properly handle a 204 response #1773
• Fix Connection closed errors when using usePresence hook #1761
• Fix Unable to enter presence channel while in suspended state errors with usePresence #1781
• Fix Can't resolve 'ably' error for environments that don't support exports field in package.json yet #1782

• Fix invalid accessToken when using REST API Client in React Native #1730, #1749
• Fix docstring for Channels.release method #1752

• Improve error message displayed when trying to use Ably.Realtime instance in the Vercel Edge runtime #1736
• Fix to allow ErrorInfo export to be accessed as a named export in ESM and when using commonjs interop #1741
• Fix ReferenceError: self is not defined error when running Jest tests in React Native using ably-js #1738
• Fix httpMaxRetryDuration client option didn't actually limit max elapsed time for rest fallback host retries #1721
• Fix default value for httpRequestTimeout client option was wrongly 15 seconds instead of expected 10 seconds #1721

• Fix an issue with realtime connections using the bun runtime #1716

• Fix Unable to resolve "ably" in React Native for ably-js v2.0.0 #1711
• Fix TextEncoder/TextDecoder are not defined in React Native for ably-js v2.0.0 #1712

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 and React Hooks migration guide 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.

Breaking Changes

• Add ChannelProvider component to React Hooks #1620, #1654
• Add untyped stats API #1522
• Add type definitions for key returned by generateRandomKey #1320
• Add mandatory version param to Rest.request #1231
• Change id field to be named ablyId in React Hooks #1676
• Change usePresence hook to two different hooks: for entering presence and subscribing to presence updates #1674
• Change naming for enum-like namespaces in type declarations and change meaning for public ChannelModes type #1601
• Change publishing methods to accept a Message-shaped object #1515
• Change Crypto.generateRandomKey API to use Promises #1351
• Change fromEncoded() and fromEncodedArray() methods on Message and PresenceMessage to be async #1311
• Remove XHRStreaming transport support #1645
• Remove code that's supporting older platforms #1629, #1633, #1641
• Remove recoveryKey in favour of createRecoveryKey() on Connection #1613
• Remove any from stats() param type #1561
• Remove the dedicated Web Worker bundle ably/build/ably-webworker and add support for using ably and ably/modular in Web Workers #1550
• Remove false class exports in type declarations #1524
• Remove the Types namespace #1518
• Remove noencryption variant of the library #1500
• Remove public callbacks API #1358
• Remove CryptoJS library and replace it with the Web Crypto API in web bundle #1299, #1325, #1333
• Remove ably-commonjs*.js files #1229
• Remove deprecated APIs #1227
• Remove deprecated fromEncoded* type declarations #1222
• Remove deprecated ClientOptions parameters #1221
• Remove the ClientOptions.log property and replace it with separate logLevel and logHandler properties #1216
• Remove support for JSONP #1215
• Fix whenState inconsistent behavior in Connection and RealtimeChannel #1640
• Fix the type definition of Crypto.getDefaultParams #1352

Features

• Add publish function to the useChannel hook #1658
• Add logs to all HTTP activity #1581

Full Changelog

• Add new logging API to ClientOptions and add a deprecation warning for the old one #1671
• Add ClientOptions.maxMessageSize to the public API #1678
• Add a deprecation warning for the headers client option #1681
• Improve deprecation log messages #1683, #1685
• Handle 204 status code in PaginatedResource #1631
• Fix typing and deprecation warning for Crypto.getDefaultParams() #1693

• [React-Hooks] usePresence unsubscribes all listeners on unmount and run Presence.leave even if connection has been terminated #1610
• RealtimeChannels.get() with options parameter throws an exception when executed during the attaching state. #1609

• Enable 'derived' options in 'useChannel' hook (by @rustworthy) #1501
• fix: use 'ably' as import path from react-hooks #1509

• fix(react): fix issue where useChannel would error upon router navigation or HMR #1478

• fix: avoid directly exporting Ably.ErrorInfo from promises.js #1463
• fix(react): add missing id param for useStateErrors call to useChannelStateListener #1455
• fix: allow RealtimePresence#leave to take PresenceMessage as argument #1466
• deps: bump ws to 8.14.2 #1467

• remove AblyProvider options prop #1446
• fix: throw descriptive error when callbacks used with react #1450

• Add new experimental react hooks and context provider #1433
• Export the ErrorInfo class #1430

• Add REST APIs for batch publishing, batch presence, and token revocation #1410
• Add support for presence message extras #1418

• Auth: remain connected upon failed authorize unless returning explicit 403 #1385
• Make Utils#inspectError use toString for Error-like values #1391
• docs: fix description of AuthOptions.token #1368

• add ChannelStateChange.hasBacklog and return state change to attach promise/callback #1347
• fix a bug where host fallback was initially skipped after falling back to the base transport #1357

This release adds a new experimental channels.getDerived method which allows you to create custom realtime data feeds by selectively subscribing to receive only part of the data from the channel. See the announcement post for more information.

• add experimental API to get derived channel #1306
• make Message.connectionId optional #1305
• fix misleading stack traces for early-intialised connection errors #1206
• remove ProtocolMessage.connectionKey #1218
• fix broken promisification of Presence.history signature #1224
• fix issue with query string encoding in react-native websockets #1286
• fix nodejs encryption of ArrayBuffer plaintext #1280

• bump got dependency to ^11.8.5 #1189

• retry connection attempt if 'online' event received whilst connecting #1171
• populate invalid state ErrorInfo.cause with the current errorReason, if set #1169
• fix: align exposed type of ErrorInfo with internal type, extending Error #1142
• fix: avoid global scope TextEncoder access #1157

• make ErrorInfo extend Error #1129
• improve error message for clientId mismatch from user auth provider #1128
• fix: don't send credentials in webworker FetchInit #1132