Skip to content

Commit

Permalink
further
Browse files Browse the repository at this point in the history
  • Loading branch information
@lawrence-forooghian
lawrence-forooghian committed Mar 13, 2024
1 parent 1fc6d22 commit cde2b5e
Showing 1 changed file with 33 additions and 60 deletions.
93 changes: 33 additions & 60 deletions docs/migration-guides/v2/lib.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@ Here’s how to migrate:

TODO First update to ably-js 1.2.50 or later

### Deprecation warnings from v1
The changes below are split into those that affect all users, and those that only affect TypeScript users.

### Changes that affect all users

In ably-js 1.2.50 or later, use of the following APIs will trigger a deprecation warning when used (TODO what log level, also you might miss them for non client options)

Expand All @@ -32,13 +34,29 @@ In ably-js 1.2.50 or later, use of the following APIs will trigger a deprecation
- `Auth`’s `authorise` method has been renamed to `authorize`. Update your code to use `authorize`.
- The `"xhr"` transport has been renamed to `"xhr_streaming"`. Update your client options code to use `transports: ["xhr_streaming"]`.

### Only TypeScript users

(hang on, what, how was this already deprecated? double check why I put things in this category)

- [Remove `Realtime < Rest` inheritance in public API](https://github.com/ably/ably-js/commit/69c35f14fd82e8b33f9d88ad78180db3d3acc888)
- [Fix optionality of `Message` properties](https://github.com/ably/ably-js/commit/4e3733f427fe70754dc36a6a9928182c79e81d72)
- [Tighten type of publishing methods](https://github.com/ably/ably-js/commit/19a8d475fb892c9b308685ebf015a50d6ba8e9b2)
- [Add "Abstract" prefix to Types.{Rest, Realtime} names](https://github.com/ably/ably-js/commit/312298a7a95370f149b63ac8751caf8b73e76b2a) — I think this was since changed though; there’s nothing with those names. I’m seeing `RealtimeClient` and `RestClient` interfaces. Ah, yep, changed it in [Rename Abstract* classes to *Client](https://github.com/ably/ably-js/commit/44eae5d4b6010b86c2043edaa4bd83523903d69e)
- [Remove the Types namespace](https://github.com/ably/ably-js/commit/30f267d8f9f377bde2917cd3f61dd598bbeadb21)
- [Remove public ChannelModes type](https://github.com/ably/ably-js/commit/04f0f16427c0caab9799b02ee73877f6b71e5ded)
- [Remove duplicate type names](https://github.com/ably/ably-js/commit/f7e28aa029a64f178c2996c668f4bab878033c03)

## Update to ably-js v2 and address any non-deprecation breaking changes in v2

### `Crypto.generateRandomKey()` now only works with promises, and it didn’t work with promises in v1
The changes below are split into those that affect all users, and those that only affect TypeScript users.

### All users

#### `Crypto.generateRandomKey()` now only works with promises, and it didn’t work with promises in v1

- [Change Crypto.generateRandomKey API to use Promises](https://github.com/ably/ably-js/commit/a0105eb80ef6a9c133b4fc861cd2fc0aea71afc5)  — it’s actually that it now _supports_ promises. Not sure why I put this into v2, though; the support could have gone in v1. TODO I think this would be good to put in v1

### Being aware of unsupported platforms
#### Being aware of unsupported platforms

- removal of a bunch of supporting code for older browsers (I think the documentation that states the new platform compatibility is not in this commit range)
- JSONP support removed ("for browsers that do not support cross-origin XHR")
Expand All @@ -48,23 +66,11 @@ In ably-js 1.2.50 or later, use of the following APIs will trigger a deprecation
- [Update platform compatibility statements in READMEs](https://github.com/ably/ably-js/commit/581a6fd705318d2a46ebff171bc61f8041f71f25)
- [Change build/bundle ES target to ES2017](https://github.com/ably/ably-js/commit/54d4c3908cda2c2fb7b3e9f357b875a7882f1bb2)

### Being aware of crypto restrictions
#### Being aware of crypto restrictions

- [Use Web Crypto for encrypting and decrypting on web](https://github.com/ably/ably-js/commit/fcdb9f35ebeaf47883493be04d2ff3d0f985a4fc) (means that encryption is only available in a secure context)

## Take advantage of new features that v2 introduces

### Using the modular variant of the library

- [Distribute an ECMAScript module variant of the library](https://github.com/ably/ably-js/commit/21fcf137f585591dfcbc1937caacf1ad76af57ee) (and the modular variant in general, with less logging, tree-shakability etc)

TODO again, not clear to me, thinking about it now, why we decided to ship the modular variant in v2; presumably we could do this in v1. Is it a business decision? I guess it also wouldn’t be clear what to do about crypto; CryptoJS isn’t tree-shakable so we’d either have to take the size hit in modular variant, or exclude crypto from modular variant. Furthermore, we wouldn’t necessarily be able to make use of the `exports` key in `package.json`.

### Migrating existing code to handle breaking changes

#### All users

##### Removal of callbacks API and APIs supporting dual functioning
#### Removal of callbacks API and APIs supporting dual functioning

Affecting everyone:

Expand All @@ -76,15 +82,15 @@ Affecting only TypeScript users:

- [Merge `*Base` and `*Promise` classes](https://github.com/ably/ably-js/commit/6cb717990d5a993ebd6e0430b2b2629660c27cf8)

##### Removal of CryptoJS library
#### Removal of CryptoJS library

This will be about code changes (e.g. being able to interact with `WordArray`, as opposed to the above "being aware of crypto restrictions" which is about making sure you only use secure context for crypto)

- [Remove all usage of the CryptoJS library](https://github.com/ably/ably-js/commit/f1bf7480ec2b758a8bce443d07b4415fe167707f) (I guess interesting in the context of reduced dependencies — anything else along these lines to mention?)
- was CryptoJS mentioned anywhere in public API? e.g. being able to pass a `WordArray`
- [Make CipherParams.key an ArrayBuffer on web instead of a WordArray](https://github.com/ably/ably-js/commit/e14f1bf7b8996c74f91f5c0486a1d734b0c4cbe6)

##### Removal of `noencryption` variant of the library
#### Removal of `noencryption` variant of the library

- [Remove the `noencryption` variant of the library](https://github.com/ably/ably-js/commit/dc47992bc6697adb80d3e638ce20495975813f31)

Expand Down Expand Up @@ -113,50 +119,17 @@ TODO could we implement this in v1 and add a deprecation? I guess we _could_, do
- [Make Message#fromEncoded/fromEncodedArray async](https://github.com/ably/ably-js/commit/c19b68893df6fe01521b0b025a654108136b0d24)
- [Make PresenceMessage#fromEncoded/fromEncodedArray async](https://github.com/ably/ably-js/commit/0ba216429905ef870b296db702196dc0d2d08091)

#### Removal of client options

##### Already deprecated

- [Remove DeprecatedClientOptions.host](https://github.com/ably/ably-js/commit/5330f75feb3c01aff64faa7c66dbfca10c03c924)
- [Remove DeprecatedClientOptions.wsHost](https://github.com/ably/ably-js/commit/616d2f24ec4281f87379d16702cff5119082850b)
- [Remove DeprecatedClientOptions.queueEvents](https://github.com/ably/ably-js/commit/757ecb5b81476ed63c0e0e5b232dedb82312f753)
- [Remove DeprecatedClientOptions.headers](https://github.com/ably/ably-js/commit/d7aaf347d26991b6139bce8260e32c3735c9165c)
- didn't actually have a deprecation warning, now it does ([Add a deprecation warning for the `headers` client option](https://github.com/ably/ably-js/commit/c3edfb2e0f922a100afacd2ed59a7996fe63733a))
- [Move remaining DeprecatedClientOptions into new type](https://github.com/ably/ably-js/commit/fe3c9ce49df62ffa357dec0843a3f3325ca7c65e) — made it no longer possible to pass `promises` or `maxMessageSize` client options (although I’m not sure they were ever publicly exposed)
- `maxMessageSize` undone by [Remove incorrect deprecation of ClientOptions.maxMessageSize](https://github.com/ably/ably-js/commit/8f725eeff586fd9108d7d85994174a7442faac87)
- [Remove deprecated ClientOptions.fallbackHostsUseDefault](https://github.com/ably/ably-js/commit/adfe5992891e7b140696317bf254edc615e05024)
- [Remove deprecated ability to pass ClientOptions.recover as a boolean](https://github.com/ably/ably-js/commit/399c896445b1505adcdf462f5ff7798dc04b7439)
- [Remove deprecated ability to pass "xhr" in ClientOptions.transports](https://github.com/ably/ably-js/commit/b8ad229524d433c401c1a3a4cd19b452913068ed)
- [Remove deprecated RealtimePresence.on/off methods](https://github.com/ably/ably-js/commit/742a981dcac464e417f6e80c9c6674e4c66ec181)
- [Remove deprecated ability to pass AuthOptions.force property](https://github.com/ably/ably-js/commit/2402dc249d683a5b8d3dd39f89b6be15957cefd4)
- [Remove deprecated ability to pass flags to RealtimeChannel.attach](https://github.com/ably/ably-js/commit/2b56a434c6d0a81846a29f2d31677dbac0f794b0)
- [Conform to spec for logging configuration](https://github.com/ably/ably-js/commit/eaee6f6ff20f5d38ae2305edf2a7061b799249e3) (`ClientOptions.log` replaced with `logHandler` and `logLevel` )
- deprecated in [Add spec-conforming logging API](https://github.com/ably/ably-js/commit/36162c4c4bfcbbbcc2e3276da8e197c95649a55c)

#### Removal of other stuff

##### Already deprecated

- [Remove deprecated Auth.authorise method](https://github.com/ably/ably-js/commit/5d3a18ac0f5b3927ed61250532a8a1c334ec6a16)
- [Remove deprecated forms of calling Crypto.getDefaultParams](https://github.com/ably/ably-js/commit/0f2074ec5d366991238f93a4000f62a360887437)

#### Only for TypeScript users

##### Already deprecated

- [Remove `Realtime < Rest` inheritance in public API](https://github.com/ably/ably-js/commit/69c35f14fd82e8b33f9d88ad78180db3d3acc888)
- [Fix optionality of `Message` properties](https://github.com/ably/ably-js/commit/4e3733f427fe70754dc36a6a9928182c79e81d72)
- [Tighten type of publishing methods](https://github.com/ably/ably-js/commit/19a8d475fb892c9b308685ebf015a50d6ba8e9b2)
- [Add "Abstract" prefix to Types.{Rest, Realtime} names](https://github.com/ably/ably-js/commit/312298a7a95370f149b63ac8751caf8b73e76b2a) — I think this was since changed though; there’s nothing with those names. I’m seeing `RealtimeClient` and `RestClient` interfaces. Ah, yep, changed it in [Rename Abstract* classes to *Client](https://github.com/ably/ably-js/commit/44eae5d4b6010b86c2043edaa4bd83523903d69e)
- [Remove the Types namespace](https://github.com/ably/ably-js/commit/30f267d8f9f377bde2917cd3f61dd598bbeadb21)
- [Remove public ChannelModes type](https://github.com/ably/ably-js/commit/04f0f16427c0caab9799b02ee73877f6b71e5ded)
- [Remove duplicate type names](https://github.com/ably/ably-js/commit/f7e28aa029a64f178c2996c668f4bab878033c03)

##### Not already deprecated
### Only TypeScript users

- [Remove `any` from `stats()` param type](https://github.com/ably/ably-js/commit/e524d68946842270a853f50188b27eba00f3add7) — this was already deprecated
- [removed deprecated unused public types](https://github.com/ably/ably-js/commit/440d89089bbf7c7ee9fb498e62c7ba53691a3d67)

### Migrating existing code to handle stuff now deprecated in v2
## Stop using functionality that v2 deprecates

- [Typings: update v2 typings to use createRecoveryKey() instead of reco…](https://github.com/ably/ably-js/commit/717b060122ace7c7495e6dbade4be25ff260b598)

## Take advantage of new features that v2 introduces

### Using the modular variant of the library

TODO brief overview, link to readme section

0 comments on commit cde2b5e

Please sign in to comment.