docs: Complete rule docs.

cartant · Oct 22, 2020 · 6f20094 · 6f20094
1 parent f1f86a0
commit 6f20094
Show file tree

Hide file tree

Showing 40 changed files with 989 additions and 116 deletions.
diff --git a/README.md b/README.md
@@ -56,41 +56,41 @@ The package includes the following rules:
 
 | Rule | Description | Recommended |
 | --- | --- | --- |
-| [`ban-observables`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/ban-observables.ts) | Forbids the use of banned observables. | TBD |
-| [`ban-operators`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/ban-operators.ts) | Forbids the use of banned operators. | TBD |
-| [`finnish`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/finnish.ts) | Enforces the use of Finnish notation. | TBD |
-| [`just`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/just.ts) | Enforces the use of a `just` alias for `of`. | TBD |
-| [`no-async-subscribe`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-async-subscribe.ts) | Forbids passing `async` functions to `subscribe`. | TBD |
-| [`no-compat`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-compat.ts) | Forbids importation from locations that depend upon `rxjs-compat`. | TBD |
-| [`no-connectable`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-connectable.ts) | Forbids operators that return connectable observables. | TBD |
-| [`no-create`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-create.ts) | Forbids the calling of `Observable.create`. | TBD |
-| [`no-explicit-generics`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-explicit-generics.ts) | Forbids explicit generic type arguments. | TBD |
-| [`no-exposed-subjects`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-exposed-subjects.ts) | Forbids exposed  (i.e. non-private) subjects. | TBD |
-| [`no-finnish`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-finnish.ts) | Forbids the use of Finnish notation. | TBD |
-| [`no-ignored-error`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-ignored-error.ts) | Forbids the calling of `subscribe` without specifying an error handler. | TBD |
-| [`no-ignored-notifier`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-ignored-notifier.ts) | Forbids observables not composed from the `repeatWhen` or `retryWhen` notifier. | TBD |
-| [`no-ignored-observable`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-ignored-observable.ts) | Forbids the ignoring of observables returned by functions. | TBD |
-| [`no-ignored-replay-buffer`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-ignored-replay-buffer.ts) | Forbids using `ReplaySubject`, `publishReplay` or `shareReplay` without specifying the buffer size. | TBD |
-| [`no-ignored-subscribe`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-ignored-subscribe.ts) | Forbids the calling of `subscribe` without specifying arguments. | TBD |
-| [`no-ignored-subscription`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-ignored-subscription.ts) | Forbids ignoring the subscription returned by `subscribe`. | TBD |
-| [`no-ignored-takewhile-value`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-ignored-takewhile-value.ts) | Forbids ignoring the value within `takeWhile`. | TBD |
-| [`no-implicit-any-catch`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-implicit-any-catch.ts) | Like the [`no-implicit-any-catch` rule](https://github.com/typescript-eslint/typescript-eslint/pull/2202) in `@typescript-eslint/eslint-plugin`, but for the `catchError` operator instead of `catch` clauses. | TBD |
-| [`no-index`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-index.ts) | Forbids the importation from index modules - for the reason, see [this issue](https://github.com/ReactiveX/rxjs/issues/4230). | TBD |
-| [`no-internal`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-internal.ts) | Forbids the importation of internals. | TBD |
-| [`no-nested-subscribe`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-nested-subscribe.ts) | Forbids the calling of `subscribe` within a `subscribe` callback. | TBD |
-| [`no-redundant-notify`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-redundant-notify.ts) | Disallows redundant notifications from completed or errored observables. | TBD |
-| [`no-sharereplay`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-sharereplay.ts) | Forbids using the `shareReplay` operator. | TBD |
-| [`no-subclass`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-subclass.ts) | Forbids subclassing RxJS classes. | TBD |
-| [`no-subject-unsubscribe`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-subject-unsubscribe.ts) | Forbids calling the `unsubscribe` method of a subject instance. | TBD |
-| [`no-subject-value`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-subject-value.ts) | Forbids accessing the `value` property of a `BehaviorSubject` instance. | TBD |
-| [`no-tap`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-tap.ts) | Forbids the use of the `tap` operator. | TBD |
-| [`no-topromise`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-topromise.ts) | Forbids the use of the `toPromise` method. | TBD |
-| [`no-unbound-methods`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-unbound-methods.ts) | Forbids the passing of unbound methods. | TBD |
-| [`no-unsafe-catch`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-unsafe-catch.ts) | Forbids unsafe `catchError` usage in effects and epics. | TBD |
-| [`no-unsafe-first`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-unsafe-first.ts) | Forbids unsafe `first`/`take` usage in effects and epics. | TBD |
-| [`no-unsafe-subject-next`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-unsafe-subject-next.ts) | Forbids unsafe optional `next` calls. | TBD |
-| [`no-unsafe-switchmap`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-unsafe-switchmap.ts) | Forbids unsafe `switchMap` usage in effects and epics. | TBD |
-| [`no-unsafe-takeuntil`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/no-unsafe-takeuntil.ts) | Forbids the application of operators after `takeUntil`. | TBD |
-| [`prefer-observer`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/prefer-observer.ts) | Forbids the passing separate callbacks to `subscribe` and `tap`. | TBD |
-| [`suffix-subjects`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/suffix-subjects.ts) | Enforces the use of a suffix in subject identifiers. | TBD |
-| [`throw-error`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/source/rules/throw-error.ts) | Enforces the passing of `Error` values to error notifications. | TBD |
+| [`ban-observables`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/ban-observables.md) | Forbids the use of banned observables. | TBD |
+| [`ban-operators`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/ban-operators.md) | Forbids the use of banned operators. | TBD |
+| [`finnish`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/finnish.md) | Enforces the use of Finnish notation. | TBD |
+| [`just`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/just.md) | Enforces the use of a `just` alias for `of`. | TBD |
+| [`no-async-subscribe`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-async-subscribe.md) | Forbids passing `async` functions to `subscribe`. | TBD |
+| [`no-compat`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-compat.md) | Forbids importation from locations that depend upon `rxjs-compat`. | TBD |
+| [`no-connectable`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-connectable.md) | Forbids operators that return connectable observables. | TBD |
+| [`no-create`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-create.md) | Forbids the calling of `Observable.create`. | TBD |
+| [`no-explicit-generics`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-explicit-generics.md) | Forbids explicit generic type arguments. | TBD |
+| [`no-exposed-subjects`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-exposed-subjects.md) | Forbids exposed  (i.e. non-private) subjects. | TBD |
+| [`no-finnish`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-finnish.md) | Forbids the use of Finnish notation. | TBD |
+| [`no-ignored-error`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-ignored-error.md) | Forbids the calling of `subscribe` without specifying an error handler. | TBD |
+| [`no-ignored-notifier`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-ignored-notifier.md) | Forbids observables not composed from the `repeatWhen` or `retryWhen` notifier. | TBD |
+| [`no-ignored-observable`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-ignored-observable.md) | Forbids the ignoring of observables returned by functions. | TBD |
+| [`no-ignored-replay-buffer`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-ignored-replay-buffer.md) | Forbids using `ReplaySubject`, `publishReplay` or `shareReplay` without specifying the buffer size. | TBD |
+| [`no-ignored-subscribe`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-ignored-subscribe.md) | Forbids the calling of `subscribe` without specifying arguments. | TBD |
+| [`no-ignored-subscription`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-ignored-subscription.md) | Forbids ignoring the subscription returned by `subscribe`. | TBD |
+| [`no-ignored-takewhile-value`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-ignored-takewhile-value.md) | Forbids ignoring the value within `takeWhile`. | TBD |
+| [`no-implicit-any-catch`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-implicit-any-catch.md) | Like the [`no-implicit-any-catch` rule](https://github.com/typescript-eslint/typescript-eslint/pull/2202) in `@typescript-eslint/eslint-plugin`, but for the `catchError` operator instead of `catch` clauses. | TBD |
+| [`no-index`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-index.md) | Forbids the importation from index modules - for the reason, see [this issue](https://github.com/ReactiveX/rxjs/issues/4230). | TBD |
+| [`no-internal`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-internal.md) | Forbids the importation of internals. | TBD |
+| [`no-nested-subscribe`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-nested-subscribe.md) | Forbids the calling of `subscribe` within a `subscribe` callback. | TBD |
+| [`no-redundant-notify`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-redundant-notify.md) | Disallows redundant notifications from completed or errored observables. | TBD |
+| [`no-sharereplay`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-sharereplay.md) | Forbids using the `shareReplay` operator. | TBD |
+| [`no-subclass`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-subclass.md) | Forbids subclassing RxJS classes. | TBD |
+| [`no-subject-unsubscribe`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-subject-unsubscribe.md) | Forbids calling the `unsubscribe` method of a subject instance. | TBD |
+| [`no-subject-value`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-subject-value.md) | Forbids accessing the `value` property of a `BehaviorSubject` instance. | TBD |
+| [`no-tap`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-tap.md) | Forbids the use of the `tap` operator. | TBD |
+| [`no-topromise`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-topromise.md) | Forbids the use of the `toPromise` method. | TBD |
+| [`no-unbound-methods`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-unbound-methods.md) | Forbids the passing of unbound methods. | TBD |
+| [`no-unsafe-catch`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-unsafe-catch.md) | Forbids unsafe `catchError` usage in effects and epics. | TBD |
+| [`no-unsafe-first`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-unsafe-first.md) | Forbids unsafe `first`/`take` usage in effects and epics. | TBD |
+| [`no-unsafe-subject-next`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-unsafe-subject-next.md) | Forbids unsafe optional `next` calls. | TBD |
+| [`no-unsafe-switchmap`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-unsafe-switchmap.md) | Forbids unsafe `switchMap` usage in effects and epics. | TBD |
+| [`no-unsafe-takeuntil`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/no-unsafe-takeuntil.md) | Forbids the application of operators after `takeUntil`. | TBD |
+| [`prefer-observer`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/prefer-observer.md) | Forbids the passing separate callbacks to `subscribe` and `tap`. | TBD |
+| [`suffix-subjects`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/suffix-subjects.md) | Enforces the use of a suffix in subject identifiers. | TBD |
+| [`throw-error`](https://github.com/cartant/eslint-plugin-rxjs/blob/main/docs/rules/throw-error.md) | Enforces the passing of `Error` values to error notifications. | TBD |
diff --git a/docs/rules/ban-observables.md b/docs/rules/ban-observables.md
@@ -1,3 +1,22 @@
-# ban-observables
+# Avoid banned observable creators (`ban-observables`)
 
-TK
+This rule can be configured so that developers can ban any observable creators they want to avoid in their project.
+
+## Options
+
+This rule accepts a single option which is an object the keys of which are the names of observable factory functions and the values are either booleans or strings containing the explanation for the ban.
+
+The following configuration bans `partition` and `onErrorResumeNext`:
+
+```json
+{
+  "rxjs/ban-observables": [
+    "error",
+    {
+      "partition": true,
+      "of": false,
+      "onErrorResumeNext": "What is this? Visual Basic?"
+    }
+  ]
+}
+```
diff --git a/docs/rules/ban-operators.md b/docs/rules/ban-operators.md
@@ -1,3 +1,21 @@
-# ban-operators
+# Avoid banned operators (`ban-operators`)
 
-TK
+This rule can be configured so that developers can ban any operators they want to avoid in their project.
+
+## Options
+
+This rule accepts a single option which is an object the keys of which are the names of operators and the values are either booleans or strings containing the explanation for the ban.
+
+The following configuration bans `ajax` and `onErrorResumeNext`:
+
+```json
+{
+  "rxjs/ban-operators": [
+    "error",
+    {
+      "partition": true,
+      "map": false,
+      "onErrorResumeNext": "What is this? Visual Basic?"
+    }
+  ]
+}
diff --git a/docs/rules/finnish.md b/docs/rules/finnish.md
@@ -1,3 +1,50 @@
-# finnish
+# Use Finnish notation (`finnish`)
 
-TK
+This rule enforces the use of Finnish notation - i.e. the `$` suffix.
+
+## Rule details
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const answers = of(42, 54);
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const answer$ = of(42, 54);
+```
+
+## Options
+
+This rule accepts a single option which is an object with properties that determine whether Finnish notation is enforced for `functions`, `methods`, `parameters`, `properties` and `variables`. It also contains `names` and `types` properties that determine whether of not Finnish notation is to be enforced for specific names or types.
+
+The default (Angular-friendly) configuration looks like this:
+
+```json
+{
+  "rxjs/finnish": [
+    "error",
+    {
+      "functions": true,
+      "methods": true,
+      "names": {
+        "^(canActivate|canActivateChild|canDeactivate|canLoad|intercept|resolve|validate)$": false
+      },
+      "parameters": true,
+      "properties": true,
+      "types": {
+        "^EventEmitter$": false
+      },
+      "variables": true
+    }
+  ]
+}
+```
+
+The properties in the options object are themselves optional; they do not all have to be specified.
+
+## Further reading
+
+- [Observables and Finnish Notation](https://medium.com/@benlesh/observables-and-finnish-notation-df8356ed1c9b)
diff --git a/docs/rules/just.md b/docs/rules/just.md
@@ -1,3 +1,11 @@
-# just
+# Use `just` instead of `of` (`just`)
 
-TK
+This rule enforces the use of `just` instead of `of`. Some other languages with Rx implementations use the former and this rule is for developers who have that preference.
+
+## Options
+
+This rule has no options.
+
+## Further reading
+
+- [Rename `of` to `just`](https://github.com/ReactiveX/rxjs/issues/3747)
diff --git a/docs/rules/macro.md b/docs/rules/macro.md
@@ -1,3 +1,7 @@
-# macro
+# Use the RxJS Tools macro (`macro`)
 
-TK
+This rule ensures that modules that import `rxjs` also import the Babel macro for [RxJS Tools](https://rxjs.tools).
+
+## Options
+
+This rule has no options.
diff --git a/docs/rules/no-async-subscribe.md b/docs/rules/no-async-subscribe.md
@@ -1,3 +1,23 @@
-# no-async-subscribe
+# Avoid passing async functions to `subscribe` (`no-async-subscribe`)
 
-TK
+This rule effects failures if async functions are passed to `subscribe`.
+
+## Rule details
+
+Examples of **incorrect** code for this rule:
+
+```ts
+import { of } from "rxjs";
+of(42).subscribe(async () => {console.log(value));
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+import { of } from "rxjs";
+of(42).subscribe(() => console.log(value));
+```
+
+## Options
+
+This rule has no options.
diff --git a/docs/rules/no-compat.md b/docs/rules/no-compat.md
@@ -1,3 +1,11 @@
-# no-compat
+# Avoid the `rxjs-compat` package (`no-compat`)
 
-TK
+This rule prevents the use of `rxjs-compat`.
+
+## Options
+
+This rule has no options.
+
+## Further reading
+
+- [Backwards compatibility](https://github.com/ReactiveX/rxjs/blob/a6590e971969c736a15b77154dabbc22275aa0d5/docs_app/content/guide/v6/migration.md#backwards-compatibility)
diff --git a/docs/rules/no-connectable.md b/docs/rules/no-connectable.md
@@ -1,3 +1,7 @@
-# no-connectable
+# Avoid connectable observables (`no-connectable`)
 
-TK
+This rule prevents the use of connectable observables.
+
+## Options
+
+This rule has no options.
diff --git a/docs/rules/no-create.md b/docs/rules/no-create.md
@@ -1,3 +1,7 @@
-# no-create
+# Avoid the static `create` function (`no-create`)
 
-TK
+This rule prevents the use of the static `create` function in `Observable`. Developers should use `new` and the constructor instead.
+
+## Options
+
+This rule has no options.
diff --git a/docs/rules/no-explicit-generics.md b/docs/rules/no-explicit-generics.md
@@ -1,3 +1,23 @@
-# no-explicit-generics
+# Avoid unnecessary explicit type arguments (`no-explicit-generics`)
 
-TK
+This rule prevents the use of explicit type arguments when the type arguments can be inferred.
+
+## Rule details
+
+Examples of **incorrect** code for this rule:
+
+```ts
+import { BehaviorSubject } from "rxjs";
+const subject = new BehaviorSubject<number>(42);
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+import { BehaviorSubject } from "rxjs";
+const subject = new BehaviorSubject(42);
+```
+
+## Options
+
+This rule has no options.