diff --git a/docs/migration-guides/v2/lib.md b/docs/migration-guides/v2/lib.md index 441b09891..ea73c3edb 100644 --- a/docs/migration-guides/v2/lib.md +++ b/docs/migration-guides/v2/lib.md @@ -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) @@ -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") @@ -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: @@ -76,7 +82,7 @@ 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) @@ -84,7 +90,7 @@ This will be about code changes (e.g. being able to interact with `WordArray`, a - 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) @@ -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