From fdc793850d5544674873801d8d1539d46cab9bac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mladen=20Jakovljevi=C4=87?= Date: Fri, 6 Aug 2021 21:37:13 +0200 Subject: [PATCH 1/2] docs: introduce importing document --- docs_app/content/guide/importing.md | 163 ++++++++++++++++++ docs_app/content/guide/installation.md | 57 ++---- docs_app/content/navigation.json | 5 + .../api/api-list.component.html | 6 +- 4 files changed, 181 insertions(+), 50 deletions(-) create mode 100644 docs_app/content/guide/importing.md diff --git a/docs_app/content/guide/importing.md b/docs_app/content/guide/importing.md new file mode 100644 index 0000000000..783bc7544b --- /dev/null +++ b/docs_app/content/guide/importing.md @@ -0,0 +1,163 @@ +# Importing instructions + +There are different ways you can {@link guide/installation install} RxJS. Using/importing RxJS depends on +the used RxJS version, but also depends on the used installation method. + +# Export sites + +RxJS v7 exports 6 different locations out of which you can import what you need. Those are: + +- `{@link api#index 'rxjs'}` (for example: `import { of } from 'rxjs'`) +- `{@link api#operators 'rxjs/operators'}` (for example: `import { map } from 'rxjs/operators'`) +- `{@link api#ajax 'rxjs/ajax'}` (for example: `import { ajax } from 'rxjs/ajax'`) +- `{@link api#fetch 'rxjs/fetch'}` (for example: `import { fromFetch } from 'rxjs/fetch'`) +- `{@link api#webSocket 'rxjs/webSocket'}` (for example: `import { webSocket } from 'rxjs/webSocket'`) +- `{@link api#testing 'rxjs/testing'}` (for example: `import { TestScheduler } from 'rxjs/testing'`) + +A new way of importing {@link guide/operators operators} is introduced with RxJS v7.2.0. + +# What's changed in RxJS v7.2.0? + +[Pipeable operators](https://v6.rxjs.dev/guide/v6/pipeable-operators) were introduced in RxJS version +5.5. This enabled all operators to be exported from a single place. This new export site was introduced +with RxJS version 6 where all pipeable operators could have been imported from `'rxjs/operators'`. For +example, `import { map } from 'rxjs/operators'`. + +With RxJS v7.2.0, most operators have been moved to `{@link api#index 'rxjs'}` export site. This means +that preferred way to import operators is from `'rxjs'`. + +For example, instead of using: `import { map } from 'rxjs/operators'`, the preferred way is to use: +`import { map } from 'rxjs'`. Although old way of importing operators is still active, it will soon +become deprecated. + +## What stayed in `'rxjs/operators'`? + +Only couple of old and mostly deprecated operators have stayed in the `'rxjs/operators'`. Those +operators are now mostly deprecated and most of them have their either static operator substitution +or are kept as operators, but have a new name so that they are different to their static creation +counter-part (usually ending with `With`). Those are: + +| `'rxjs/operators'` Operator | Replace With Static Creation Operator | Replace With New Operator Name | +| ------------------------------------------------------- | ------------------------------------- | ------------------------------ | +| [`combineLatest`](/api/operators/combineLatest) | {@link combineLatest} | {@link combineLatestWith} | +| [`concat`](/api/operators/concat) | {@link concat} | {@link concatWith} | +| [`merge`](/api/operators/merge) | {@link merge} | {@link mergeWith} | +| [`onErrorResumeNext`](/api/operators/onErrorResumeNext) | {@link onErrorResumeNext} | - | +| [`partition`](/api/operators/partition) | {@link partition} | - | +| [`race`](/api/operators/race) | {@link race} | {@link raceWith} | +| [`zip`](/api/operators/zip) | {@link zip} | {@link zipWith} | + +For example, usage of a static creation {@link merge} operator: + +```ts +import { merge } from 'rxjs'; + +merge(a$, b$).subscribe(); +``` + +could be written as (using a pipeable operator): + +```ts +import { mergeWith } from 'rxjs'; + +a$.pipe(mergeWith(b$)).subscribe(); +``` + +Depending on the preferred style, you can choose which one to follow, they are completely equal. + +Since a new way of importing operators is introduced with RxJS v7.2.0, instructions will be split to +prior and after this version. + +## ES6 via npm + +If you've installed RxJS using {@link guide/installation#es6-via-npm ES6 via npm} and installed version +is: + +### v7.2.0 or later + +Import only what you need: + +```ts +import { of, map } from 'rxjs'; + +of(1, 2, 3).pipe(map((x) => x + '!!!')); // etc +``` + +To import the entire set of functionality: + +```ts +import * as rxjs from 'rxjs'; + +rxjs.of(1, 2, 3).pipe(rxjs.map((x) => x + '!!!')); // etc; +``` + +To use with a globally imported bundle: + +```js +const { of, map } = rxjs; + +of(1, 2, 3).pipe(map((x) => x + '!!!')); // etc +``` + +If you installed RxJS version: + +### v7.1.0 or older + +Import only what you need: + +```ts +import { of } from 'rxjs'; +import { map } from 'rxjs/operators'; + +of(1, 2, 3).pipe(map((x) => x + '!!!')); // etc +``` + +To import the entire set of functionality: + +```ts +import * as rxjs from 'rxjs'; +import * as operators from 'rxjs'; + +rxjs.of(1, 2, 3).pipe(operators.map((x) => x + '!!!')); // etc; +``` + +To use with a globally imported bundle: + +```js +const { of } = rxjs; +const { map } = rxjs.operators; + +of(1, 2, 3).pipe(map((x) => x + '!!!')); // etc +``` + +## CDN + +If you installed a library {@link guide/installation#cdn using CDN}, the global namespace for rxjs is +`rxjs`. + +### v7.2.0 or later + +```js +const { range, filter, map } = rxjs; + +range(1, 200) + .pipe( + filter((x) => x % 2 === 1), + map((x) => x + x) + ) + .subscribe((x) => console.log(x)); +``` + +### v7.1.0 or older + +```js +const { range } = rxjs; +const { filter, map } = rxjs.operators; + +range(1, 200) + .pipe( + filter((x) => x % 2 === 1), + map((x) => x + x) + ) + .subscribe((x) => console.log(x)); +``` diff --git a/docs_app/content/guide/installation.md b/docs_app/content/guide/installation.md index 7436d3e7ec..1c5bc3df82 100644 --- a/docs_app/content/guide/installation.md +++ b/docs_app/content/guide/installation.md @@ -4,7 +4,7 @@ Here are different ways you can install RxJS: ## ES2015 via npm -```js +```shell npm install rxjs ``` @@ -19,41 +19,16 @@ Configuring a bundler to use the `es2015` custom export condition is specific to If you are interested in using this option, please consult the documentation of your bundler for additional information. However, some general information can be found here: https://webpack.js.org/guides/package-exports/#conditions-custom -To import only what you need: - -```ts -import { of } from 'rxjs'; -import { map } from 'rxjs/operators'; - -of(1, 2, 3).pipe(map(x => x + '!!!')); // etc -``` - -* See [Pipeable Operators](/guide/v6/pipeable-operators) for more information. - -To import the entire core set of functionality: - -```ts -import * as rxjs from 'rxjs'; - -rxjs.of(1, 2, 3); -``` - -To use with a globally imported bundle: - -```js -const { of } = rxjs; -const { map } = rxjs.operators; - -of(1, 2, 3).pipe(map(x => x + '!!!')); // etc -``` +To import only what you need, please {@link guide/importing#es6-via-npm check out this} guide. ## CommonJS via npm -If you receive an error like error TS2304: Cannot find name 'Promise' or error TS2304: Cannot find name 'Iterable' when using RxJS you may need to install a supplemental set of typings. +If you receive an error like error TS2304: Cannot find name 'Promise' or error TS2304: Cannot find name +'Iterable' when using RxJS you may need to install a supplemental set of typings. 1. For typings users: -```js +```shell typings install es6-shim --ambient ``` @@ -65,14 +40,14 @@ typings install es6-shim --ambient To install this library via npm version 3, use the following command: -```js +```shell npm install @reactivex/rxjs ``` -If you are using npm version 2 before this library has achieved a stable version, you need to specify the library version explicitly: +If you are using npm version 2, you need to specify the library version explicitly: -```js -npm install @reactivex/rxjs@5.0.0-beta.1 +```shell +npm install @reactivex/rxjs@7.3.0 ``` ## CDN @@ -81,16 +56,4 @@ For CDN, you can use [unpkg](https://unpkg.com/): [https://unpkg.com/rxjs@^7/dist/bundles/rxjs.umd.min.js](https://unpkg.com/rxjs@%5E7/dist/bundles/rxjs.umd.min.js) -The global namespace for rxjs is `rxjs`: - -```js -const { range } = rxjs; -const { map, filter } = rxjs.operators; - -range(1, 200) - .pipe( - filter(x => x % 2 === 1), - map(x => x + x) - ) - .subscribe(x => console.log(x)); -``` +To import what you need, please {@link guide/importing#cdn check out this} guide. diff --git a/docs_app/content/navigation.json b/docs_app/content/navigation.json index 43d83fc8c1..58a9ac6236 100644 --- a/docs_app/content/navigation.json +++ b/docs_app/content/navigation.json @@ -55,6 +55,11 @@ "title": "Installation", "tooltip": "Installation" }, + { + "url": "guide/importing", + "title": "Importing", + "tooltip": "RxJS Importing" + }, { "url": "api", "title": "Reference", diff --git a/docs_app/src/app/custom-elements/api/api-list.component.html b/docs_app/src/app/custom-elements/api/api-list.component.html index 2402bbfeb7..43fc80920f 100644 --- a/docs_app/src/app/custom-elements/api/api-list.component.html +++ b/docs_app/src/app/custom-elements/api/api-list.component.html @@ -20,8 +20,8 @@
-
-

{{section.title}}

+
+

{{section.title}}

  • @@ -33,4 +33,4 @@

    {{section.title}}

-
\ No newline at end of file + From 4691714cb5d31567143afd80bd3a28cd8fef7ed0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mladen=20Jakovljevi=C4=87?= Date: Thu, 21 Oct 2021 09:00:41 +0200 Subject: [PATCH 2/2] docs(importing.md): emphasize new operator imports --- docs_app/content/guide/importing.md | 77 +++++++++++++++++++---------- 1 file changed, 51 insertions(+), 26 deletions(-) diff --git a/docs_app/content/guide/importing.md b/docs_app/content/guide/importing.md index 783bc7544b..a643388351 100644 --- a/docs_app/content/guide/importing.md +++ b/docs_app/content/guide/importing.md @@ -3,39 +3,53 @@ There are different ways you can {@link guide/installation install} RxJS. Using/importing RxJS depends on the used RxJS version, but also depends on the used installation method. -# Export sites +[Pipeable operators](https://v6.rxjs.dev/guide/v6/pipeable-operators) were introduced in RxJS version +5.5. This enabled all operators to be exported from a single place. This new export site was introduced +with RxJS version 6 where all pipeable operators could have been imported from `'rxjs/operators'`. For +example, `import { map } from 'rxjs/operators'`. -RxJS v7 exports 6 different locations out of which you can import what you need. Those are: +# New in RxJS v7.2.0 + +**With RxJS v7.2.0, most operators have been moved to `{@link api#index 'rxjs'}` +export site. This means that the preferred way to import operators is from `'rxjs'`, while +`'rxjs/operators'` export site has been deprecated.** -- `{@link api#index 'rxjs'}` (for example: `import { of } from 'rxjs'`) -- `{@link api#operators 'rxjs/operators'}` (for example: `import { map } from 'rxjs/operators'`) -- `{@link api#ajax 'rxjs/ajax'}` (for example: `import { ajax } from 'rxjs/ajax'`) -- `{@link api#fetch 'rxjs/fetch'}` (for example: `import { fromFetch } from 'rxjs/fetch'`) -- `{@link api#webSocket 'rxjs/webSocket'}` (for example: `import { webSocket } from 'rxjs/webSocket'`) -- `{@link api#testing 'rxjs/testing'}` (for example: `import { TestScheduler } from 'rxjs/testing'`) +For example, instead of using: -A new way of importing {@link guide/operators operators} is introduced with RxJS v7.2.0. +```ts +import { map } from 'rxjs/operators'; +``` -# What's changed in RxJS v7.2.0? +**the preferred way** is to use: -[Pipeable operators](https://v6.rxjs.dev/guide/v6/pipeable-operators) were introduced in RxJS version -5.5. This enabled all operators to be exported from a single place. This new export site was introduced -with RxJS version 6 where all pipeable operators could have been imported from `'rxjs/operators'`. For -example, `import { map } from 'rxjs/operators'`. +```ts +import { map } from 'rxjs'; +``` + +Although the old way of importing operators is still active, it will be removed in one of the next major +versions. + +Click {@link #how-to-migrate here to see} how to migrate. -With RxJS v7.2.0, most operators have been moved to `{@link api#index 'rxjs'}` export site. This means -that preferred way to import operators is from `'rxjs'`. +# Export sites + +RxJS v7 exports 6 different locations out of which you can import what you need. Those are: -For example, instead of using: `import { map } from 'rxjs/operators'`, the preferred way is to use: -`import { map } from 'rxjs'`. Although old way of importing operators is still active, it will soon -become deprecated. +- `{@link api#index 'rxjs'}` - for example: `import { of } from 'rxjs';` +- `{@link api#operators 'rxjs/operators'}` - for example: `import { map } from 'rxjs/operators';` +- `{@link api#ajax 'rxjs/ajax'}` - for example: `import { ajax } from 'rxjs/ajax';` +- `{@link api#fetch 'rxjs/fetch'}` - for example: `import { fromFetch } from 'rxjs/fetch';` +- `{@link api#webSocket 'rxjs/webSocket'}` - for example: `import { webSocket } from 'rxjs/webSocket';` +- `{@link api#testing 'rxjs/testing'}` - for example: `import { TestScheduler } from 'rxjs/testing';` -## What stayed in `'rxjs/operators'`? +## How to migrate? -Only couple of old and mostly deprecated operators have stayed in the `'rxjs/operators'`. Those -operators are now mostly deprecated and most of them have their either static operator substitution -or are kept as operators, but have a new name so that they are different to their static creation -counter-part (usually ending with `With`). Those are: +While nothing has been removed from `'rxjs/operators'`, it is strongly recommended doing the operator +imports from `'rxjs'`. Almost all operator function exports have been moved to `'rxjs'`, but only a +couple of old and deprecated operators have stayed in the `'rxjs/operators'`. Those operator functions +are now mostly deprecated and most of them have their either static operator substitution or are kept as +operators, but have a new name so that they are different to their static creation counter-part (usually +ending with `With`). Those are: | `'rxjs/operators'` Operator | Replace With Static Creation Operator | Replace With New Operator Name | | ------------------------------------------------------- | ------------------------------------- | ------------------------------ | @@ -47,7 +61,18 @@ counter-part (usually ending with `With`). Those are: | [`race`](/api/operators/race) | {@link race} | {@link raceWith} | | [`zip`](/api/operators/zip) | {@link zip} | {@link zipWith} | -For example, usage of a static creation {@link merge} operator: +For example, the old and deprecated way of using [`merge`](/api/operators/merge) from `'rxjs/operators'` +is: + +```ts +import { merge } from 'rxjs/operators'; + +a$.pipe(merge(b$)).subscribe(); +``` + +But this should be avoided and replaced with one of the next two examples. + +For example, this could be replaced by using a static creation {@link merge} function: ```ts import { merge } from 'rxjs'; @@ -55,7 +80,7 @@ import { merge } from 'rxjs'; merge(a$, b$).subscribe(); ``` -could be written as (using a pipeable operator): +Or it could be written using a pipeable {@link mergeWith} operator: ```ts import { mergeWith } from 'rxjs';