Merge main into integration/v2

.github/workflows/check.yml

@@ -22,4 +22,9 @@ jobs:
       - run: npm run lint
       - run: npm run format:check
       - run: npx tsc --noEmit ably.d.ts modules.d.ts
+      # for some reason, this doesn't work in CI using `npx attw --pack .`
+      - run: npm pack
+      - run: npx attw ably-$(npm show ably version).tgz --summary --exclude-entrypoints 'ably/modules'
+      # TODO understand this unexpected-module-syntax error (https://github.com/ably/ably-js/issues/1546)
+      - run: npx attw ably-$(npm show ably version).tgz --summary --entrypoints 'ably/modules' --ignore-rules unexpected-module-syntax
       - run: npm audit --production

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 This contains only the most important and/or user-facing changes; for a full changelog, see the commit history.
 
+## [1.2.48](https://github.com/ably/ably-js/tree/1.2.48) (2023-11-20)
+
+- Enable 'derived' options in 'useChannel' hook (by @rustworthy) [\#1501](https://github.com/ably/ably-js/pull/1501)
+- fix: use 'ably' as import path from react-hooks [\#1509](https://github.com/ably/ably-js/pull/1509)
+
 ## [1.2.47](https://github.com/ably/ably-js/tree/1.2.47) (2023-11-02)
 
 - fix(react): fix issue where useChannel would error upon router navigation or hmr [\#1478](https://github.com/ably/ably-js/pull/1478)

ably.d.ts

@@ -2168,8 +2168,8 @@
    */
   get(name: string, channelOptions?: ChannelOptions): T;
   /**
    * @experimental This is a preview feature and may change in a future non-major release.
    * This experimental method 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](https://pages.ably.com/subscription-filters-preview) for more information.
    *
@@ -2468,7 +2468,7 @@
    *
    * @returns A promise which, upon success, will be fulfilled with a page of results for message and presence history, stats, and REST presence requests. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  next(): Promise<PaginatedResult<T>>;
+  next(): Promise<PaginatedResult<T> | null>;
   /**
    * Returns the `PaginatedResult` for the current page of results.
    */

docs/react.md

@@ -139,6 +139,29 @@ const { channel } = useChannel({ channelName: "your-channel-name", options: { ..
 });
 ```
 
+[Subscription filters](https://ably.com/docs/channels#filter-subscribe) are also supported:
+
+```javascript
+const deriveOptions = { filter: 'headers.email == `"[email protected]"` || headers.company == `"domain"`' }
+const { channel } = useChannel({ channelName: "your-derived-channel-name", options: { ... }, deriveOptions }, (message) => {
+    ...
+});
+```
+
+Please note that attempts to publish to a derived channel (the one created or retrieved with a filter expression) will fail. In order to send messages to the channel called _"your-derived-channel-name"_ from the example above, you will need to create another channel instance without a filter expression.
+
+```javascript
+const channelName = "your-derived-channel-name";
+const options = { ... };
+const deriveOptions = { filter: 'headers.email == `"[email protected]"` || headers.company == `"domain"`' }
+const callback = (message) => { ... };
+
+const { channel: readOnlyChannelInstance } = useChannel({ channelName, options, deriveOptions }, callback);
+const { channel: readWriteChannelInstance } = useChannel({ channelName, options }, callback); // NB! No 'deriveOptions' passed here
+
+readWriteChannelInstance.publish("test-message", { text: "message text" });
+```
+
 ---
 
 ### usePresence