diff --git a/docs/rules/ban-observables.md b/docs/rules/ban-observables.md index a03d9a20..2d373d33 100644 --- a/docs/rules/ban-observables.md +++ b/docs/rules/ban-observables.md @@ -2,11 +2,16 @@ -This rule can be configured so that developers can ban any observable creators they want to avoid in their project. +It can sometimes be useful to ban specific `rxjs` imports. +This rule can be configured to ban a list of specific `rxjs` imports developers want to avoid in their project. + +> [!TIP] +> `ban-observables` only bans at the _import_ site. (In fact, it can ban anything imported from `rxjs`.) +> See [`ban-operators`](./ban-operators.md) for banning operators at their _usage_. ## 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. +This rule accepts a single option which is an object the keys of which are the names of anything in `rxjs` and the values are either booleans or strings containing the explanation for the ban. The following configuration bans `partition` and `onErrorResumeNext`: @@ -22,3 +27,16 @@ The following configuration bans `partition` and `onErrorResumeNext`: ] } ``` + +## When Not To Use It + +If you have no need to ban importing anything from `rxjs`, you don't need this rule. + +## Related To + +- [`ban-operators`](./ban-operators.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/ban-observables.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/ban-observables.test.ts) diff --git a/docs/rules/ban-operators.md b/docs/rules/ban-operators.md index 38d824c2..761f408b 100644 --- a/docs/rules/ban-operators.md +++ b/docs/rules/ban-operators.md @@ -4,7 +4,10 @@ -This rule can be configured so that developers can ban any operators they want to avoid in their project. +This rule can be configured so that developers can ban `rxjs` operators they want to avoid in their project. + +> [!NOTE] +> Operators outside of a `pipe` or not directly exported by `rxjs` are ignored. ## Options @@ -23,3 +26,19 @@ The following configuration bans `partition` and `onErrorResumeNext`: } ] } +``` + +## When Not To Use It + +If you have no need to ban `rxjs` operators, you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Related To + +- [`ban-observables`](./ban-observables.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/ban-operators.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/ban-operators.test.ts) diff --git a/docs/rules/finnish.md b/docs/rules/finnish.md index 08aa671d..149fb08f 100644 --- a/docs/rules/finnish.md +++ b/docs/rules/finnish.md @@ -68,6 +68,24 @@ The default (Angular-friendly) configuration looks like this: The properties in the options object are themselves optional; they do not all have to be specified. +## When Not To Use It + +If you don't use Finnish notation in your project or don't care about enforcing Finnish notation in your project, you don't need this rule. +However, keep in mind that inconsistent style can harm readability in a project; +consider using [`no-finnish`](./no-finnish.md) to ban Finnish notation if you don't use it in your project. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Observables and Finnish Notation](https://medium.com/@benlesh/observables-and-finnish-notation-df8356ed1c9b) + +## Related To + +- [`no-finnish`](./no-finnish.md) +- [`suffix-subjects`](./suffix-subjects.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/finnish.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/finnish.test.ts) diff --git a/docs/rules/just.md b/docs/rules/just.md index 157cfd73..07e44eea 100644 --- a/docs/rules/just.md +++ b/docs/rules/just.md @@ -6,6 +6,15 @@ 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. +## When Not To Use It + +If you prefer `of` in your project, you will want to avoid this rule. + ## Further reading - [Rename `of` to `just`](https://github.com/ReactiveX/rxjs/issues/3747) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/just.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/just.test.ts) diff --git a/docs/rules/no-async-subscribe.md b/docs/rules/no-async-subscribe.md index a18c37f4..f29b7896 100644 --- a/docs/rules/no-async-subscribe.md +++ b/docs/rules/no-async-subscribe.md @@ -36,7 +36,19 @@ of(42).pipe( ).subscribe(data2 => console.log(data2)); ``` +## When Not To Use It + +If you don't care about avoiding `.subscribe(async...`, then you will not need this rule. +However, keep in mind that features of observables like cancellation or retrying will not work, and race conditions may occur. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Why does this rule exist?](https://stackoverflow.com/q/71559135) - [Higher-order Observables](https://rxjs.dev/guide/higher-order-observables) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-async-subscribe.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-async-subscribe.test.ts) diff --git a/docs/rules/no-connectable.md b/docs/rules/no-connectable.md index c7be7d76..091289ee 100644 --- a/docs/rules/no-connectable.md +++ b/docs/rules/no-connectable.md @@ -4,4 +4,30 @@ -This rule prevents the use of connectable observables. +This rule prevents the use of operators that return connectable observables. + +> [!NOTE] +> All operators banned by this rule are also deprecated by RxJS, +> so this rule may be removed in a future major version. + +## Rule details + +Examples of **incorrect** code for this rule: + +```ts +import { of, publish } from "rxjs"; + +const result = of(42).pipe(publish()); +``` + +## When Not To Use It + +If you use operators that return connectable observables in your project, you may not need this rule. +Or you may rely on RxJS's deprecation of those operators and don't need to double-flag the operators as banned. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-connectable.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-connectable.test.ts) diff --git a/docs/rules/no-create.md b/docs/rules/no-create.md index 65aaa301..b7a413fc 100644 --- a/docs/rules/no-create.md +++ b/docs/rules/no-create.md @@ -29,3 +29,15 @@ const answers = new Observable(subscriber => { subscriber.complete(); }); ``` + +## When Not To Use It + +If you rely on RxJS's deprecation of `Observable.create` and don't need to double-flag usage, +then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-create.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-create.test.ts) diff --git a/docs/rules/no-cyclic-action.md b/docs/rules/no-cyclic-action.md index f2464e7e..a0d0ae54 100644 --- a/docs/rules/no-cyclic-action.md +++ b/docs/rules/no-cyclic-action.md @@ -72,3 +72,17 @@ This rule accepts a single option which is an object with an `observable` proper ] } ``` + +## When Not To Use It + +If you don't use a library with effects and epics (e.g. NgRx or redux-observable), +then you don't need this rule. +Alternatively, if you use NgRx's own [`avoid-cyclic-effects`](https://ngrx.io/guide/eslint-plugin/rules/avoid-cyclic-effects) rule, +then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-cyclic-action.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-cyclic-action.test.ts) diff --git a/docs/rules/no-explicit-generics.md b/docs/rules/no-explicit-generics.md index 07017e12..8a5194f0 100644 --- a/docs/rules/no-explicit-generics.md +++ b/docs/rules/no-explicit-generics.md @@ -20,6 +20,13 @@ import { BehaviorSubject } from "rxjs"; const subject = new BehaviorSubject(42); ``` -## Known problems +## When Not To Use It + +This rule has known problems in the latest release: - ([#77](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/issues/77)) Type unions cause false positives e.g. `new BehaviorSubject(null)` will be incorrectly caught by this rule. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-explicit-generics.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-explicit-generics.test.ts) diff --git a/docs/rules/no-exposed-subjects.md b/docs/rules/no-exposed-subjects.md index a86d5081..c79182f8 100644 --- a/docs/rules/no-exposed-subjects.md +++ b/docs/rules/no-exposed-subjects.md @@ -23,10 +23,13 @@ Examples of **correct** code for this rule: ```ts import { Subject } from "rxjs"; + class Answers { - private _answers: Subject; - get answers() { - return this._answers.asObservable(); + private answersSubject$ = new Subject(); + public answers$ = this.answersSubject$.asObservable(); + + public nextAnswer(a: string) { + this.answersSubject$.next(a); } } ``` @@ -51,3 +54,15 @@ This rule accepts a single option which is an object with an `allowProtected` pr ] } ``` + +## When Not To Use It + +If you don't care about encapsulating subjects in your project, then you don't need this rule. +However, be aware that anyone can call `next()` or `complete()` on the exposed subject, which may cause bugs or less readable code. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-exposed-subjects.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-exposed-subjects.test.ts) diff --git a/docs/rules/no-finnish.md b/docs/rules/no-finnish.md index f13a7261..25ac62eb 100644 --- a/docs/rules/no-finnish.md +++ b/docs/rules/no-finnish.md @@ -20,6 +20,23 @@ Examples of **correct** code for this rule: const answers = of(42, 54); ``` +## When Not To Use It + +If you use Finnish notation in your project, you should avoid this rule. +Or if you don't care if Finnish notation is used in your project, then you don't need this rule. +However, keep in mind that inconsistent style can harm readability in a project. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Observables and Finnish Notation](https://medium.com/@benlesh/observables-and-finnish-notation-df8356ed1c9b) + +## Related To + +- [`finnish`](./finnish.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-finnish.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-finnish.test.ts) diff --git a/docs/rules/no-floating-observables.md b/docs/rules/no-floating-observables.md index 3e829ed3..e1ce2c0e 100644 --- a/docs/rules/no-floating-observables.md +++ b/docs/rules/no-floating-observables.md @@ -19,7 +19,7 @@ This rule will report observable-valued statements that are not treated in one o > [!TIP] > `no-floating-observables` only detects apparently unhandled observable _statements_. -> See [`no-misused-observables`](./no-misused-observables.md) for detecting code that provides observables to _logical_ locations +> See [`no-misused-observables`](./no-misused-observables.md) for detecting code that provides observables to _logical_ locations. ## Rule details @@ -46,3 +46,23 @@ const answers = of(42, 54); | `ignoreVoid` | Whether to ignore `void` expressions. | Boolean | `true` | + +## When Not To Use It + +Like `@typescript-eslint/no-floating-promises`, +this rule can be difficult to enable on large existing projects that set up many floating observables. +Alternatively, if you're not worried about ignored errors or unhandled cold observables, +then in some cases it may be safe to not use this rule. +You might consider using `void`s and/or ESLint disable comments for those specific situations +instead of completely disabling this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Related To + +- [`no-misused-observables`](./no-misused-observables.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-floating-observables.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-floating-observables.test.ts) diff --git a/docs/rules/no-ignored-default-value.md b/docs/rules/no-ignored-default-value.md index 0b82010d..6f07ae32 100644 --- a/docs/rules/no-ignored-default-value.md +++ b/docs/rules/no-ignored-default-value.md @@ -29,3 +29,15 @@ const sub = new Subject(); const result = firstValueFrom(sub, { defaultValue: null }); sub.complete(); ``` + +## When Not To Use It + +If you intentionally want `EmptyError` rejections when the observable completes, then you may not need this rule. +You might consider using ESLint disable comments for specific situations instead of completely disabling this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-default-value.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-default-value.test.ts) diff --git a/docs/rules/no-ignored-error.md b/docs/rules/no-ignored-error.md index 040bf4a5..899192c2 100644 --- a/docs/rules/no-ignored-error.md +++ b/docs/rules/no-ignored-error.md @@ -37,3 +37,17 @@ source.subscribe({ error: (error) => console.error(error) }); ``` + +## When Not To Use It + +If you're not worried about ignored errors, then in some cases it may be safe to not use this rule. +Or if you use operators like `catchError` to handle all errors, then in some cases it may be safe to not use this rule. +You might consider using ESLint disable comments for those specific situations +instead of completely disabling this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-error.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-error.test.ts) diff --git a/docs/rules/no-ignored-notifier.md b/docs/rules/no-ignored-notifier.md index 06bd6202..d0b1d500 100644 --- a/docs/rules/no-ignored-notifier.md +++ b/docs/rules/no-ignored-notifier.md @@ -8,6 +8,10 @@ This rule effects failures if the notifier passed to a `repeatWhen` or `retryWhen` callback is not used. +> [!NOTE] +> Both `repeatWhen` and `retryWhen` are deprecated by RxJS, +> so this rule may be removed in a future major version. + ## Rule details Examples of **incorrect** code for this rule: @@ -30,3 +34,14 @@ const repeating = source.pipe( repeatWhen(notifications => notifications.pipe(take(3))) ); ``` + +## When Not To Use It + +If you don't use `repeatWhen` or `retryWhen` in your project, then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-notifier.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-notifier.test.ts) diff --git a/docs/rules/no-ignored-replay-buffer.md b/docs/rules/no-ignored-replay-buffer.md index c53326bc..722d4f50 100644 --- a/docs/rules/no-ignored-replay-buffer.md +++ b/docs/rules/no-ignored-replay-buffer.md @@ -36,3 +36,12 @@ const subject = new ReplaySubject(Infinity); import { of, shareReplay } from "rxjs"; of(42).pipe(shareReplay({ refCount: true, bufferSize: 1 })); ``` + +## When Not To Use It + +If you don't care about implicitly defaulting to `Infinity` in your replay buffers, then you don't need this rule. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-replay-buffer.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-replay-buffer.test.ts) diff --git a/docs/rules/no-ignored-subscribe.md b/docs/rules/no-ignored-subscribe.md index b557975c..26ff191d 100644 --- a/docs/rules/no-ignored-subscribe.md +++ b/docs/rules/no-ignored-subscribe.md @@ -26,3 +26,21 @@ import { of } from "rxjs"; of(42, 54).subscribe((value) => console.log(value)); ``` + +## When Not To Use It + +If you don't care about errors or output of some observables in your project, you may not need this rule. +Alternatively, you may require all logic to go in the `pipe` section of your observables. +In that case, you should not use this rule and should enable [`no-subscribe-handlers`](./no-subscribe-handlers.md) instead, +which is the opposite of this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Related To + +- [`no-subscribe-handlers`](./no-subscribe-handlers.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-subscribe.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-subscribe.test.ts) diff --git a/docs/rules/no-ignored-subscription.md b/docs/rules/no-ignored-subscription.md index 2e09c6c1..c4e99df4 100644 --- a/docs/rules/no-ignored-subscription.md +++ b/docs/rules/no-ignored-subscription.md @@ -31,3 +31,16 @@ const numbers = new Observable(subscriber => { interval(1e3).subscribe(subscriber); }); ``` + +## When Not To Use It + +If you don't care about unsubscribing from all observables in your project, then you may not need this rule. +Alternatively, your project might use operators like `take`, `takeUntil`, `takeWhile`, etc. +or Angular's `takeUntilDestroyed` to automatically handle subscriptions. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-subscription.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-subscription.test.ts) diff --git a/docs/rules/no-ignored-takewhile-value.md b/docs/rules/no-ignored-takewhile-value.md index 8a6bc625..aea14e70 100644 --- a/docs/rules/no-ignored-takewhile-value.md +++ b/docs/rules/no-ignored-takewhile-value.md @@ -24,3 +24,12 @@ import { takeWhile } from "rxjs/operators"; const whilst = source.pipe(takeWhile(value => value)); ``` + +## When Not To Use It + +If you don't care about using the given value in a `takeWhile` callback, then you don't need this rule. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-takewhile-value.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-takewhile-value.test.ts) diff --git a/docs/rules/no-implicit-any-catch.md b/docs/rules/no-implicit-any-catch.md index 4dd7b58c..f2be8450 100644 --- a/docs/rules/no-implicit-any-catch.md +++ b/docs/rules/no-implicit-any-catch.md @@ -8,7 +8,10 @@ -This rule requires an explicit type annotation for error parameters in error handlers. It's similar to the typescript-eslint [`use-unknown-in-catch-callback-variable`](https://typescript-eslint.io/rules/use-unknown-in-catch-callback-variable/) rule or the TSConfig [`useUnknownInCatchVariables`](https://www.typescriptlang.org/tsconfig/#useUnknownInCatchVariables) option, but is for observables - not `try`/`catch` statements. +This rule requires an explicit type annotation for error parameters in error handlers. +It's similar to the typescript-eslint [`use-unknown-in-catch-callback-variable`](https://typescript-eslint.io/rules/use-unknown-in-catch-callback-variable/) rule +or the TSConfig [`useUnknownInCatchVariables`](https://www.typescriptlang.org/tsconfig/#useUnknownInCatchVariables) option, +but is for observables - not `try`/`catch` statements. ## Rule details @@ -89,6 +92,18 @@ This rule accepts a single option which is an object with an `allowExplicitAny` } ``` +## When Not To Use It + +If your codebase is not yet able to enable `useUnknownInCatchVariables`, +it likely would be similarly difficult to enable this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Catching Unknowns](https://ncjamieson.com/catching-unknowns/) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-implicit-any-catch.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-implicit-any-catch.test.ts) diff --git a/docs/rules/no-index.md b/docs/rules/no-index.md index 123a6cee..214718b0 100644 --- a/docs/rules/no-index.md +++ b/docs/rules/no-index.md @@ -19,3 +19,16 @@ Examples of **correct** code for this rule: ```ts import { of } from "rxjs"; ``` + +## When Not To Use It + +If you don't care about unnecessary import path segments, then you don't need this rule. + +## Further reading + +- [Importing instructions](https://rxjs.dev/guide/importing) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-index.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-index.test.ts) diff --git a/docs/rules/no-internal.md b/docs/rules/no-internal.md index 20a2d79d..7c5a5570 100644 --- a/docs/rules/no-internal.md +++ b/docs/rules/no-internal.md @@ -21,3 +21,18 @@ Examples of **correct** code for this rule: ```ts import { of } from "rxjs"; ``` + +## When Not To Use It + +If you need to import internal modules that are not covered by the public API, +then you don't need this rule. +However, keep in mind that internal modules may change without notice. + +## Further reading + +- [Importing instructions](https://rxjs.dev/guide/importing) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-internal.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-internal.test.ts) diff --git a/docs/rules/no-misused-observables.md b/docs/rules/no-misused-observables.md index 64d9ab44..7b4aad41 100644 --- a/docs/rules/no-misused-observables.md +++ b/docs/rules/no-misused-observables.md @@ -80,6 +80,22 @@ You can disable selective parts of the `checksVoidReturn` option. The following | `returns` | Disallow returning an Observable-returning function where a function that returns `void` is expected. | Boolean | `true` | | `variables` | Disallow assigning or declaring an Observable-returning function where a function that returns `void` is expected. | Boolean | `true` | +## When Not To Use It + +Like `@typescript-eslint/no-misused-promises`, +this rule can be difficult to enable on large existing projects that set up many misused observables. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [TypeScript void function assignability](https://github.com/Microsoft/TypeScript/wiki/FAQ#why-are-functions-returning-non-void-assignable-to-function-returning-void) + +## Related To + +- [`no-floating-observables`](./no-floating-observables.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-misused-observables.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-misused-observables.test.ts) diff --git a/docs/rules/no-nested-subscribe.md b/docs/rules/no-nested-subscribe.md index ad222a44..d4f543c4 100644 --- a/docs/rules/no-nested-subscribe.md +++ b/docs/rules/no-nested-subscribe.md @@ -30,3 +30,17 @@ of(42, 54).pipe( mergeMap((value) => timer(1e3).pipe(map(() => value))) ).subscribe((value) => console.log(value)); ``` + +## When Not To Use It + +If you need nested subscriptions and are aware of the potential issues, +then you might not need this rule. +However, you should typically prefer to use higher-order mapping operators +like `mergeMap`, `switchMap`, or `concatMap` to handle nested observables. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-nested-subscribe.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-nested-subscribe.test.ts) diff --git a/docs/rules/no-redundant-notify.md b/docs/rules/no-redundant-notify.md index 945ed49d..b38e374e 100644 --- a/docs/rules/no-redundant-notify.md +++ b/docs/rules/no-redundant-notify.md @@ -32,3 +32,18 @@ const subject = new Subject(); subject.next(42); subject.error(new Error("Kaboom!")); ``` + +## When Not To Use It + +If you don't care about redundant notifications, then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Related To + +- [`no-subject-unsubscribe`](./no-subject-unsubscribe.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-redundant-notify.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-redundant-notify.test.ts) diff --git a/docs/rules/no-sharereplay.md b/docs/rules/no-sharereplay.md index 03042a55..807eda3f 100644 --- a/docs/rules/no-sharereplay.md +++ b/docs/rules/no-sharereplay.md @@ -29,6 +29,21 @@ This rule accepts a single option which is an object with an `allowConfig` prope } ``` +## When Not To Use It + +If you are confident that `shareReplay` is used properly your project, +then you may not need this rule. +However, keep in mind that it's recommended to always provide a config object +that explicitly specifies `refCount` (see linked blog post); +by default, `shareReplay` without any config defaults to `refCount: false`, +which means the source observable will never be unsubscribed from, +potentially leading to unexpected behavior and memory leaks. + ## Further reading - [What's changed with shareReplay](https://ncjamieson.com/whats-changed-with-sharereplay/) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-sharereplay.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-sharereplay.test.ts) diff --git a/docs/rules/no-subclass.md b/docs/rules/no-subclass.md index 8ad58c94..6b540d91 100644 --- a/docs/rules/no-subclass.md +++ b/docs/rules/no-subclass.md @@ -7,3 +7,17 @@ This rule effects failures if an RxJS class is subclassed. Developers are encouraged to avoid subclassing RxJS classes, as some public and protected implementation details might change in the future. + +## When Not To Use It + +If you need to subclass RxJS classes in your project, then don't use this rule. +However, keep in mind that implementation details may change in the future; +You might consider using ESLint disable comments for specific situations +instead of completely disabling this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-subclass.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-subclass.test.ts) diff --git a/docs/rules/no-subject-unsubscribe.md b/docs/rules/no-subject-unsubscribe.md index fa11b86e..6a66351c 100644 --- a/docs/rules/no-subject-unsubscribe.md +++ b/docs/rules/no-subject-unsubscribe.md @@ -6,8 +6,25 @@ -This rule effects failures if the `unsubscribe` method is called on subjects. The method behaves differently to the `unsubscribe` method on subscriptions and is often an error. +This rule effects failures if the `unsubscribe` method is called on subjects. +The method behaves differently to the `unsubscribe` method on subscriptions and is often an error. + +## When Not To Use It + +If you intentionally use `unsubscribe` to cause errors when subjects are `next`-ed after closing, +then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. ## Further reading - [Closed Subjects](https://ncjamieson.com/closed-subjects/) + +## Related To + +- [`no-redundant-notify`](./no-redundant-notify.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-subject-unsubscribe.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-subject-unsubscribe.test.ts) diff --git a/docs/rules/no-subject-value.md b/docs/rules/no-subject-value.md index f7fb9e50..62fc2e6b 100644 --- a/docs/rules/no-subject-value.md +++ b/docs/rules/no-subject-value.md @@ -5,3 +5,15 @@ This rule effects an error if the `value` property - or `getValue` method - of a `BehaviorSubject` is used. + +## When Not To Use It + +If your code uses the `value` property or the `getValue` method of `BehaviorSubject`, +then don't enable this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-subject-value.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-subject-value.test.ts) diff --git a/docs/rules/no-subscribe-handlers.md b/docs/rules/no-subscribe-handlers.md index 0b2742e9..19ec2cd8 100644 --- a/docs/rules/no-subscribe-handlers.md +++ b/docs/rules/no-subscribe-handlers.md @@ -35,3 +35,19 @@ of(42, 54) .pipe(tap((value) => console.log(value))) .subscribe(); ``` + +## When Not To Use It + +If you don't require all logic to go in the `pipe` section of your observables, then you don't need this rule. +Also, if your project uses `no-ignored-subscribe`, which is the opposite of this rule, then you should not use this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Related To + +- [`no-ignored-subscribe`](./no-ignored-subscribe.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-subscribe-handlers.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-subscribe-handlers.test.ts) diff --git a/docs/rules/no-subscribe-in-pipe.md b/docs/rules/no-subscribe-in-pipe.md index 24a6352c..1db92d20 100644 --- a/docs/rules/no-subscribe-in-pipe.md +++ b/docs/rules/no-subscribe-in-pipe.md @@ -18,7 +18,7 @@ import { map } from "rxjs/operators"; of(42, 54).pipe( map(value => { - of(value).subscribe(console.log); // This will trigger the rule + of(value).subscribe(console.log); return value * 2; }) ).subscribe(result => console.log(result)); @@ -35,3 +35,21 @@ of(42, 54).pipe( map(value => value * 2) ).subscribe(result => console.log(result)); ``` + +## When Not To Use It + +If you need to subscribe within `pipe` and are aware of the potential issues, +then you might not need this rule. +However, you should typically prefer to use higher-order mapping operators +like `mergeMap`, `switchMap`, or `concatMap` to handle nested observables. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Related To + +- [`no-nested-subscribe`](./no-nested-subscribe.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-subscribe-in-pipe.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-subscribe-in-pipe.test.ts) diff --git a/docs/rules/no-topromise.md b/docs/rules/no-topromise.md index b62d3aa6..249cccce 100644 --- a/docs/rules/no-topromise.md +++ b/docs/rules/no-topromise.md @@ -10,6 +10,23 @@ This rule effects failures if the `toPromise` method is used. +This rule provides two editor suggestions which replace `toPromise` with either: + +- `lastValueFrom(...)`, which behaves closest to the behavior of `toPromise`, +- or `firstValueFrom(...)`. + +## When Not To Use It + +If you rely on RxJS's deprecation of `toPromise` and don't need to double-flag usage, +then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Conversion to Promises](https://rxjs.dev/deprecations/to-promise) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-topromise.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-topromise.test.ts) diff --git a/docs/rules/no-unbound-methods.md b/docs/rules/no-unbound-methods.md index 8ac596f1..1cf7da7c 100644 --- a/docs/rules/no-unbound-methods.md +++ b/docs/rules/no-unbound-methods.md @@ -41,6 +41,21 @@ return this.http ); ``` +## When Not To Use It + +If every handler in your project does not depend on the `this` context in their implementations, +then in some cases it may be safe to not use this rule. +However, keep in mind that future changes may introduce bugs +by changing their implementations to depend on the `this` context; +see the linked blog post for best practice explanation. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Avoiding unbound methods](https://ncjamieson.com/avoiding-unbound-methods/) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-unbound-methods.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-unbound-methods.test.ts) diff --git a/docs/rules/no-unsafe-catch.md b/docs/rules/no-unsafe-catch.md index 53ad2caa..91339556 100644 --- a/docs/rules/no-unsafe-catch.md +++ b/docs/rules/no-unsafe-catch.md @@ -60,3 +60,15 @@ This rule accepts a single option which is an object with an `observable` proper ] } ``` + +## When Not To Use It + +If you don't use a library with effects and epics (e.g. NgRx or redux-observable), +then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-unsafe-catch.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-unsafe-catch.test.ts) diff --git a/docs/rules/no-unsafe-first.md b/docs/rules/no-unsafe-first.md index 3f07d78d..41a6754e 100644 --- a/docs/rules/no-unsafe-first.md +++ b/docs/rules/no-unsafe-first.md @@ -26,3 +26,15 @@ This rule accepts a single option which is an object with an `observable` proper ] } ``` + +## When Not To Use It + +If you don't use a library with effects and epics (e.g. NgRx or redux-observable), +then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-unsafe-first.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-unsafe-first.test.ts) diff --git a/docs/rules/no-unsafe-subject-next.md b/docs/rules/no-unsafe-subject-next.md index a3eccf23..1cd4d8fb 100644 --- a/docs/rules/no-unsafe-subject-next.md +++ b/docs/rules/no-unsafe-subject-next.md @@ -8,7 +8,8 @@ This rule effects failures if `next` is called without an argument and the subject's value type is not `void`. -In RxJS version 6, the `next` method's `value` parameter is optional, but a value should always be specified for subjects with non-`void` element types. +In RxJS version 6, the `next` method's `value` parameter was optional, but a value should always be specified for subjects with non-`void` element types. +RxJS version 7 changed the `value` parameter to mandatory. ## Rule details @@ -30,3 +31,16 @@ subject.next(); const subject = new Subject(); subject.next(0); ``` + +## When Not To Use It + +If you don't care about sending `undefined` to subjects, then you don't need this rule. +Alternatively, you may rely on TypeScript to enforce the `value` parameter, +which was made mandatory in RxJS version 7. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-unsafe-subject-next.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-unsafe-subject-next.test.ts) diff --git a/docs/rules/no-unsafe-switchmap.md b/docs/rules/no-unsafe-switchmap.md index 3cd327e4..582973a7 100644 --- a/docs/rules/no-unsafe-switchmap.md +++ b/docs/rules/no-unsafe-switchmap.md @@ -47,6 +47,18 @@ The `allow` or `disallow` properties are mutually exclusive. Whether or not `swi The properties in the options object are themselves optional; they do not all have to be specified. +## When Not To Use It + +If you don't use a library with effects and epics (e.g. NgRx or redux-observable), +then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Avoiding switchMap-related bugs](https://ncjamieson.com/avoiding-switchmap-related-bugs/) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-unsafe-switchmap.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-unsafe-switchmap.test.ts) diff --git a/docs/rules/no-unsafe-takeuntil.md b/docs/rules/no-unsafe-takeuntil.md index 8a2dda6e..8d72b7c2 100644 --- a/docs/rules/no-unsafe-takeuntil.md +++ b/docs/rules/no-unsafe-takeuntil.md @@ -56,6 +56,17 @@ By default, the `allow` property contains all of the built-in operators that are The properties in the options object are themselves optional; they do not all have to be specified. +## When Not To Use It + +If you are confident your project uses `takeUntil` correctly, then you may not need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Avoiding takeUntil leaks](https://ncjamieson.com/avoiding-takeuntil-leaks/) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-unsafe-takeuntil.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-unsafe-takeuntil.test.ts) diff --git a/docs/rules/prefer-observer.md b/docs/rules/prefer-observer.md index ffb454f1..44e29039 100644 --- a/docs/rules/prefer-observer.md +++ b/docs/rules/prefer-observer.md @@ -49,6 +49,18 @@ This rule accepts a single option which is an object with an `allowNext` propert } ``` +## When Not To Use It + +If you rely on RxJS's deprecation of separate handlers and don't need to double-flag usage, +then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Subscribe Arguments](https://rxjs.dev/deprecations/subscribe-arguments) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/prefer-observer.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/prefer-observer.test.ts) diff --git a/docs/rules/prefer-root-operators.md b/docs/rules/prefer-root-operators.md index 1e6c33cf..016d6891 100644 --- a/docs/rules/prefer-root-operators.md +++ b/docs/rules/prefer-root-operators.md @@ -29,6 +29,17 @@ Examples of **correct** code for this rule: import { map } from 'rxjs'; ``` +## When Not To Use It + +If you don't care about importing from the deprecated site, then you don't need this rule. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + ## Further reading - [Importing instructions](https://rxjs.dev/guide/importing) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/prefer-root-operators.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/prefer-root-operators.test.ts) diff --git a/docs/rules/suffix-subjects.md b/docs/rules/suffix-subjects.md index 80b92c9c..f0712dab 100644 --- a/docs/rules/suffix-subjects.md +++ b/docs/rules/suffix-subjects.md @@ -6,6 +6,10 @@ This rule effects failures if subject variables, properties and parameters don't conform to a naming scheme that identifies them as subjects. +> [!NOTE] +> This rule is designed to be optionally compatible with [`finnish`](./finnish.md). +> Using Finnish notation (adding a `$` suffix) your subject names will _not_ cause a failure of this rule. + ## Rule details Examples of **incorrect** code for this rule: @@ -18,6 +22,7 @@ Examples of **correct** code for this rule: ```ts const answersSubject = new Subject(); +const answersSubject$ = new Subject(); ``` ## Options @@ -34,7 +39,9 @@ const answersSubject = new Subject(); -This rule accepts a single option which is an object with properties that determine whether Finnish notation is enforced for `parameters`, `properties` and `variables`. It also contains a `types` property that determine whether of not the naming convention is to be enforced for specific types and a `suffix` property. +This rule accepts a single option which is an object with properties that determine whether subject suffixes are enforced for `parameters`, `properties` and `variables`. +It also contains a `types` property that determine whether or not the naming convention is to be enforced for specific types +and a `suffix` property. The default (Angular-friendly) configuration looks like this: @@ -56,3 +63,19 @@ The default (Angular-friendly) configuration looks like this: ``` The properties in the options object are themselves optional; they do not all have to be specified. + +## When Not To Use It + +If you don't use suffixes on your project's subjects, then you don't need this rule. +However, keep in mind that inconsistent style can harm readability in a project. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Related To + +- [`finnish`](./finnish.md) + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/suffix-subjects.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/suffix-subjects.test.ts) diff --git a/docs/rules/throw-error.md b/docs/rules/throw-error.md index 8f4f91f8..dd289a6e 100644 --- a/docs/rules/throw-error.md +++ b/docs/rules/throw-error.md @@ -38,3 +38,16 @@ throwError(() => new Error("Kaboom!")); | `allowThrowingUnknown` | Whether to always allow throwing values typed as `unknown`. | Boolean | `true` | + +## When Not To Use It + +If you don't care about throwing values that are not `Error` objects, then you don't need this rule. +However, keep in mind that, while JavaScript _allows_ throwing any value, +most developer may find this behavior surprising or inconvenient to handle. + +Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting. + +## Resources + +- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/throw-error.ts) +- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/throw-error.test.ts)