From f6a2e31fa917d979dde01ad02947d7fac40cbe4f Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Tue, 14 Jul 2020 19:42:52 +1000
Subject: [PATCH 01/16] docs(always-return): use new format, add explanation
---
docs/rules/always-return.md | 47 +++++++++++++++++++++++++++----------
1 file changed, 35 insertions(+), 12 deletions(-)
diff --git a/docs/rules/always-return.md b/docs/rules/always-return.md
index 40527ec5..590937eb 100644
--- a/docs/rules/always-return.md
+++ b/docs/rules/always-return.md
@@ -1,22 +1,19 @@
# Return inside each `then()` to create readable and reusable Promise chains (always-return)
Ensure that inside a `then()` you make sure to `return` a new promise or value.
-See http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html (rule #5)
-for more info on why that's a good idea.
-We also allow someone to `throw` inside a `then()` which is essentially the same
-as `return Promise.reject()`.
+## Rule Details
-#### Valid
+Using a promise inside a `then()` without returning it (or using `await`) means
+that a potential error from that promise will not be caught in subsequent
+`catch()` callbacks. Additionally, returning a non-promise wraps it into a
+Promise, allowing it to be used in promise chains, which is convenient when
+mixing synchronous and asynchronous code.
-```js
-myPromise.then((val) => val * 2));
-myPromise.then(function(val) { return val * 2; });
-myPromise.then(doSomething); // could be either
-myPromise.then((b) => { if (b) { return "yes" } else { return "no" } });
-```
+We also allow someone to `throw` inside a `then()` which is essentially the same
+as `return Promise.reject()` in this scenario.
-#### Invalid
+Examples of **incorrect** code for this rule:
```js
myPromise.then(function(val) {})
@@ -31,3 +28,29 @@ myPromise.then(b => {
}
})
```
+
+Examples of **correct** code for this rule:
+
+```js
+myPromise.then((val) => val * 2);
+myPromise.then(function(val) { return val * 2; });
+myPromise.then(doSomething); // could be either
+myPromise.then((b) => { if (b) { return "yes" } else { return "no" } });
+```
+
+## When Not To Use It
+
+If you want to allow non-returning `then()` callbacks, for example for
+synchronous side-effects like below, you can safely disable this rule.
+
+```js
+myPromise.then(val => {
+ console.log('promise complete')
+ console.log(val)
+})
+```
+
+## Further Reading
+
+- [We have a problem with promises](http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html)
+ (Rookie mistake #5: using side effects instead of returning)
From d26e45d710d5e9a4a4d42e527652c2159ae262cf Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Tue, 14 Jul 2020 19:54:17 +1000
Subject: [PATCH 02/16] docs(avoid-new): add explanation and examples
---
docs/rules/avoid-new.md | 42 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 42 insertions(+)
diff --git a/docs/rules/avoid-new.md b/docs/rules/avoid-new.md
index 387623e9..1fb6b91e 100644
--- a/docs/rules/avoid-new.md
+++ b/docs/rules/avoid-new.md
@@ -1,3 +1,45 @@
# Avoid creating `new` promises outside of utility libs (use [pify][] instead) (avoid-new)
+Avoid using `new Promise` in favour of utility libraries or
+`Promise.resolve`/`reject`.
+
+## Rule Details
+
+Creating promises using `new Promise` can be used to promisify Node-style
+callbacks. However, you can use libraries such as [pify][] or Node's
+[`util.promisify`](https://nodejs.org/api/util.html#util_util_promisify_original)
+instead.
+
+`new Promise` is also sometimes misused to wrap a value or
+error into a promise. However, this can be done more concisely and clearly with
+`Promise.resolve` and `Promise.reject`.
+
+Examples of **incorrect** code for this rule:
+
+```js
+function promisifiedFn(arg) {
+ return new Promise((resolve, reject) => {
+ callbackStyleFn(arg, (error, result) => error ? reject(error) : resolve(result))
+ })
+}
+
+new Promise((resolve, reject) => resolve(1))
+new Promise((resolve, reject) => reject(new Error('oops')))
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const pify = require('pify')
+const promisifiedFn = pify(callbackStyleFn)
+
+Promise.resolve(1)
+Promise.reject(new Error('oops'))
+```
+
+## When Not To Use It
+
+If you are creating a utility library like pify or do not want to be notified
+when using `new Promise`, you can safely disable this rule.
+
[pify]: https://www.npmjs.com/package/pify
From 8b444f7006b1fb1aa5ab2c2010a35fefc6e44b1e Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Tue, 14 Jul 2020 20:27:45 +1000
Subject: [PATCH 03/16] docs(catch-or-return): use new format, add more
explanations and examples
---
docs/rules/catch-or-return.md | 132 +++++++++++++++++++++++-----------
1 file changed, 91 insertions(+), 41 deletions(-)
diff --git a/docs/rules/catch-or-return.md b/docs/rules/catch-or-return.md
index d4812347..e15a30d9 100644
--- a/docs/rules/catch-or-return.md
+++ b/docs/rules/catch-or-return.md
@@ -3,69 +3,119 @@
Ensure that each time a `then()` is applied to a promise, a `catch()` is applied
as well. Exceptions are made if you are returning that promise.
-#### Valid
+## Rule Details
+
+If a promise is not handled correctly, any error from that promise can cause
+unhandled promise rejections. A promise can be handled using `catch()` or
+returning it from a function, which will mean that it's the caller's
+responsibility to handle the promise.
+
+Examples of **incorrect** code for this rule:
```js
-myPromise.then(doSomething).catch(errors)
+myPromise.then(doSomething)
+myPromise.then(doSomething, handleErrors) // catch() may be a little better
+```
+
+Examples of **correct** code for this rule:
+
+```js
+myPromise.then(doSomething).catch(handleErrors)
myPromise
.then(doSomething)
.then(doSomethingElse)
- .catch(errors)
+ .catch(handleErrors)
function doSomethingElse() {
return myPromise.then(doSomething)
}
```
-#### Invalid
+## Options
+
+### `allowThen`
+
+The second argument to `then()` can also be used to handle a promise rejection,
+but it won't catch any errors from the first argument callback. Because of this,
+this rule reports usage of `then()` with two arguments without `catch()` by
+default.
+
+However, you can use `{ allowThen: true }` to allow using `then()` with two
+arguments instead of `catch()` to handle promise rejections.
+
+Examples of **incorrect** code for the default `{ allowThen: false }` option:
```js
-myPromise.then(doSomething)
-myPromise.then(doSomething, catchErrors) // catch() may be a little better
-function doSomethingElse() {
- return myPromise.then(doSomething)
-}
+myPromise.then(doSomething, handleErrors)
+```
+
+Examples of **correct** code for the `{ allowThen: true }` option:
+
+```js
+myPromise.then(doSomething, handleErrors)
+myPromise.then(doSomething).catch(handleErrors)
+```
+
+### `allowFinally`
+
+This option allows `.finally()` to be used after `catch()` at the end of the
+promise chain. This is different from adding `'finally'` as a
+`terminationMethod` because it will still require the Promise chain to be
+"caught" beforehand.
+
+Examples of **incorrect** code for the default `{ allowFinally: false }` option:
+
+```js
+myPromise
+ .then(doSomething)
+ .catch(handleErrors)
+ .finally(cleanUp)
```
-#### Options
+Examples of **correct** code for the `{ allowFinally: true }` option:
-##### `allowThen`
+```js
+myPromise
+ .then(doSomething)
+ .catch(handleErrors)
+ .finally(cleanUp)
+```
-You can pass an `{ allowThen: true }` as an option to this rule to allow for
-`.then(null, fn)` to be used instead of `catch()` at the end of the promise
-chain.
+### `terminationMethod`
-##### `allowFinally`
+This option allows for specifying different method names to allow instead of
+`catch()` at the end of the promise chain. This is
+useful for many non-standard Promise implementations. You can use a single
+string or an array of strings.
-You can pass an `{ allowFinally: true }` as an option to this rule to allow for
-`.finally(fn)` to be used after `catch()` at the end of the promise chain. This
-is different from adding `'finally'` as a `terminationMethod` because it will
-still require the Promise chain to be "caught" beforehand.
+Examples of **incorrect** code for the `{ terminationMethod: 'done' }` option:
-##### `terminationMethod`
+```js
+myPromise.then(doSomething).catch(handleErrors)
+```
-You can pass a `{ terminationMethod: 'done' }` as an option to this rule to
-require `done()` instead of `catch()` at the end of the promise chain. This is
-useful for many non-standard Promise implementations.
+Examples of **correct** code for the `{ terminationMethod: 'done' }` option:
-You can also pass an array of methods such as
-`{ terminationMethod: ['catch', 'asCallback', 'finally'] }`.
+```js
+myPromise.then(doSomething).done(handleErrors)
+```
-This will allow any of
+Examples of **correct** code for the
+`{ terminationMethod: ['catch', 'asCallback', 'finally'] }` option:
```js
-Promise.resolve(1)
- .then(() => {
- throw new Error('oops')
- })
- .catch(logerror)
-Promise.resolve(1)
- .then(() => {
- throw new Error('oops')
- })
- .asCallback(cb)
-Promise.resolve(1)
- .then(() => {
- throw new Error('oops')
- })
- .finally(cleanUp)
+myPromise.then(doSomething).catch(handleErrors)
+myPromise.then(doSomething).asCallback(handleErrors)
+myPromise.then(doSomething).finally(handleErrors)
```
+
+## When Not To Use It
+
+If you do not want to be notified about not handling promises by `catch`ing or
+`return`ing, such as if you have a custom `unhandledRejection`
+(`unhandledrejection` in the browser) handler, you can safely disable this rule.
+
+## Further Reading
+
+- [We have a problem with promises](http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html)
+ (Advanced mistake #2: `then(resolveHandler).catch(rejectHandler)` isn't
+ exactly the same as `then(resolveHandler, rejectHandler)`)
From 16aed372f78e23af857c899550d0eebc99743f49 Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Tue, 14 Jul 2020 20:49:45 +1000
Subject: [PATCH 04/16] docs(no-native): use new format and add more
explanation
---
docs/rules/no-native.md | 21 ++++++++++++++++-----
1 file changed, 16 insertions(+), 5 deletions(-)
diff --git a/docs/rules/no-native.md b/docs/rules/no-native.md
index 104dc297..95c52a85 100644
--- a/docs/rules/no-native.md
+++ b/docs/rules/no-native.md
@@ -4,15 +4,26 @@ Ensure that `Promise` is included fresh in each file instead of relying on the
existence of a native promise implementation. Helpful if you want to use
`bluebird` or if you don't intend to use an ES6 Promise shim.
-#### Valid
+## Rule Details
+
+If you are targeting an ES5 environment where native promises aren't supported,
+ensuring that `Promise` is included from a promise library prevents bugs from
+`Promise` being undefined.
+
+Examples of **incorrect** code for this rule:
```js
-var Promise = require('bluebird')
-var x = Promise.resolve('good')
+var x = Promise.resolve('bad')
```
-#### Invalid
+Examples of **correct** code for this rule:
```js
-var x = Promise.resolve('bad')
+var Promise = require('bluebird')
+var x = Promise.resolve('good')
```
+
+## When Not To Use It
+
+If you are targeting an environment that supports native promises, or using a
+Promise shim, you should disable this rule.
From 614bc1aab62c4e239955ac96c42fe6279c9e084d Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 11:55:42 +1000
Subject: [PATCH 05/16] docs(no-nesting): use new format
---
docs/rules/no-nesting.md | 36 ++++++++++++++++++++++++++++--------
1 file changed, 28 insertions(+), 8 deletions(-)
diff --git a/docs/rules/no-nesting.md b/docs/rules/no-nesting.md
index 3225699f..7c78824c 100644
--- a/docs/rules/no-nesting.md
+++ b/docs/rules/no-nesting.md
@@ -1,15 +1,14 @@
# Avoid nested `then()` or `catch()` statements (no-nesting)
-#### Valid
+Nesting `then()` or `catch()` statements making code harder to understand and
+maintain. Instead, you should return a promise from `then()` or `catch()` to
+chain the promises.
+
+## Rule Details
+
-```js
-myPromise
- .then(doSomething)
- .then(doSomethingElse)
- .catch(errors)
-```
-#### Invalid
+Examples of **incorrect** code for this rule:
```js
myPromise.then(val =>
@@ -28,3 +27,24 @@ myPromise.catch(err =>
doSomething(err).catch(errors)
)
```
+
+Examples of **correct** code for this rule:
+
+```js
+myPromise
+ .then(doSomething)
+ .then(doSomethingElse)
+ .catch(errors)
+```
+
+## When Not To Use It
+
+If you want to nest promises, for example to have different `catch()` handlers
+to handle the different promises, you can safely disable this rule.
+
+## Further Reading
+
+- [Promises chaining on Javascript.info](https://javascript.info/promise-chaining)
+- [Using Promises on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises#Common_mistakes)
+- [We have a problem with promises](https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html)
+ (Rookie mistake #1: the promisey pyramid of doom)
From 8833987a416348043fbb7864277bb203c9f8f1ac Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 11:59:49 +1000
Subject: [PATCH 06/16] docs(no-new-statics): fix grammar
---
docs/rules/no-new-statics.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/rules/no-new-statics.md b/docs/rules/no-new-statics.md
index ab998031..c25c360d 100644
--- a/docs/rules/no-new-statics.md
+++ b/docs/rules/no-new-statics.md
@@ -11,7 +11,7 @@ problems reported by this rule.
This rule is aimed at flagging instances where a Promise static method is called
with `new`.
-Examples for **incorrect** code for this rule:
+Examples of **incorrect** code for this rule:
```js
new Promise.resolve(value)
@@ -20,7 +20,7 @@ new Promise.race([p1, p2])
new Promise.all([p1, p2])
```
-Examples for **correct** code for this rule:
+Examples of **correct** code for this rule:
```js
Promise.resolve(value)
From 8c4df3edc97fbc33cda874219873957584c1a36c Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 12:03:18 +1000
Subject: [PATCH 07/16] docs(no-nesting): add rule details
---
docs/rules/no-nesting.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/docs/rules/no-nesting.md b/docs/rules/no-nesting.md
index 7c78824c..fc12e2a5 100644
--- a/docs/rules/no-nesting.md
+++ b/docs/rules/no-nesting.md
@@ -6,7 +6,8 @@ chain the promises.
## Rule Details
-
+Nesting `then()` or `catch()` statements is frequently redundant and does not
+utilise promise chaining. This can result in code similar to "callback hell".
Examples of **incorrect** code for this rule:
From a358f1ff10c30b7c342006e0c7b3590a10f53c69 Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 12:03:31 +1000
Subject: [PATCH 08/16] docs(always-return): use single quotes in code examples
---
docs/rules/always-return.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/rules/always-return.md b/docs/rules/always-return.md
index 590937eb..d3ccc1fc 100644
--- a/docs/rules/always-return.md
+++ b/docs/rules/always-return.md
@@ -35,7 +35,7 @@ Examples of **correct** code for this rule:
myPromise.then((val) => val * 2);
myPromise.then(function(val) { return val * 2; });
myPromise.then(doSomething); // could be either
-myPromise.then((b) => { if (b) { return "yes" } else { return "no" } });
+myPromise.then((b) => { if (b) { return 'yes' } else { return 'no' } });
```
## When Not To Use It
From b11e41b277589912d1d3d15d21364ddb85f35b9f Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 12:08:48 +1000
Subject: [PATCH 09/16] docs(no-return-in-finally): use new format
---
docs/rules/no-return-in-finally.md | 23 +++++++++++++++++++----
1 file changed, 19 insertions(+), 4 deletions(-)
diff --git a/docs/rules/no-return-in-finally.md b/docs/rules/no-return-in-finally.md
index 8188f529..2114fec8 100644
--- a/docs/rules/no-return-in-finally.md
+++ b/docs/rules/no-return-in-finally.md
@@ -3,18 +3,33 @@
Disallow return statements inside a callback passed to `finally()`, since
nothing would consume what's returned.
-#### Valid
+## Rule Details
+
+Returning statements inside a `finally()` callback does not have any effect and
+can indicate a misunderstanding of how `finally()` works.
+
+This rule does not report returning with concise arrow function expressions,
+because it can be used to avoid unnecessary braces.
+
+Examples of **incorrect** code for this rule:
```js
myPromise.finally(function(val) {
- console.log('value:', val)
+ return val
})
```
-#### Invalid
+Examples of **correct** code for this rule:
```js
myPromise.finally(function(val) {
- return val
+ console.log('value:', val)
})
+
+myPromise.finally(val => console.log('value:', val))
```
+
+## When Not To Use It
+
+If you do not want to be notified when using `return` in `finally()` callbacks,
+you can safely disable this rule.
From 7ce20144bd4feb1d83b283e3eda82f1bc629b4b1 Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 12:21:02 +1000
Subject: [PATCH 10/16] docs(no-return-wrap): use new format
---
docs/rules/no-return-wrap.md | 47 +++++++++++++++++++++++++++---------
1 file changed, 35 insertions(+), 12 deletions(-)
diff --git a/docs/rules/no-return-wrap.md b/docs/rules/no-return-wrap.md
index cfb76b2f..c4bfb9e2 100644
--- a/docs/rules/no-return-wrap.md
+++ b/docs/rules/no-return-wrap.md
@@ -1,34 +1,57 @@
# Avoid wrapping values in `Promise.resolve` or `Promise.reject` when not needed (no-return-wrap)
Ensure that inside a `then()` or a `catch()` we always `return` or `throw` a raw
-value instead of wrapping in `Promise.resolve` or `Promise.reject`
+value instead of wrapping in `Promise.resolve` or `Promise.reject`.
-#### Valid
+## Rule Details
+
+Returning a value wrapped in `Promise.resolve` or `Promise.reject` inside a
+`then()` or `catch()` callback is unnecessary. Returning a non-promise in one of
+these callbacks automatically wraps it into a promise, and `throw`ing an error
+is the same as using `Promise.reject`.
+
+Examples of **incorrect** code for this rule:
```js
myPromise.then(function(val) {
- return val * 2
+ return Promise.resolve(val * 2)
})
+
myPromise.then(function(val) {
- throw 'bad thing'
+ return Promise.reject('bad thing')
})
```
-#### Invalid
+Examples of **correct** code for this rule:
```js
myPromise.then(function(val) {
- return Promise.resolve(val * 2)
+ return val * 2
})
+
myPromise.then(function(val) {
- return Promise.reject('bad thing')
+ throw 'bad thing'
})
```
-#### Options
+## Options
+
+### `allowReject`
+
+Using `{ allowReject: true }` permits wrapping returned values with
+`Promise.reject`, such as when you would use it as another way to reject the
+promise.
+
+Examples of **correct** code for the `{ allowReject: true }` option:
+
+```js
+myPromise.then(function(val) {
+ return Promise.reject('bad thing')
+})
+```
-##### `allowReject`
+## When Not To Use It
-Pass `{ allowReject: true }` as an option to this rule to permit wrapping
-returned values with `Promise.reject`, such as when you would use it as another
-way to reject the promise.
+If you don't want to be notified when returning values wrapped in
+`Promise.resolve` or `Promise.reject` in `then()` or `catch()` callbacks, you
+can safely disable this rule.
From 1a449879a5f4aa6574170b6b6bb4fd5b1664da4e Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 12:23:58 +1000
Subject: [PATCH 11/16] docs(param-names): use new format
---
docs/rules/param-names.md | 33 ++++++++++++++++++++-------------
1 file changed, 20 insertions(+), 13 deletions(-)
diff --git a/docs/rules/param-names.md b/docs/rules/param-names.md
index 5c6f70bd..80db4ffa 100644
--- a/docs/rules/param-names.md
+++ b/docs/rules/param-names.md
@@ -1,24 +1,31 @@
# Enforce consistent param names when creating new promises (param-names)
-Enforce standard parameter names for Promise constructors
+Enforce standard parameter names for Promise constructors.
-#### Valid
+## Rule Details
+
+Ensures that `new Promise()` is instantiated with the parameter names
+`resolve, reject` to avoid confusion with order such as `reject, resolve`. The
+Promise constructor uses the
+[RevealingConstructor pattern](https://blog.domenic.me/the-revealing-constructor-pattern/).
+Using the same parameter names as the language specification makes code more
+uniform and easier to understand.
+
+Examples of **incorrect** code for this rule:
```js
-new Promise(function (resolve) { ... })
-new Promise(function (resolve, reject) { ... })
+new Promise(function (reject, resolve) { /* ... */ }) // incorrect order
+new Promise(function (ok, fail) { /* ... */ }) // non-standard parameter names
```
-#### Invalid
+Examples of **correct** code for this rule:
```js
-new Promise(function (reject, resolve) { ... }) // incorrect order
-new Promise(function (ok, fail) { ... }) // non-standard parameter names
+new Promise(function (resolve) { /* ... */ })
+new Promise(function (resolve, reject) { /* ... */ })
```
-Ensures that `new Promise()` is instantiated with the parameter names
-`resolve, reject` to avoid confusion with order such as `reject, resolve`. The
-Promise constructor uses the
-[RevealingConstructor pattern](https://blog.domenic.me/the-revealing-constructor-pattern/).
-Using the same parameter names as the language specification makes code more
-uniform and easier to understand.
+## When Not To Use It
+
+If you prefer using non-standard parameter names in Promise constructors, you
+can safely disable this rule.
From 7bca9fcc729dc6788a7830d27a024de1981cea14 Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 12:32:26 +1000
Subject: [PATCH 12/16] docs(no-new-statics): add part about using using with a
type checker
---
docs/rules/no-new-statics.md | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/rules/no-new-statics.md b/docs/rules/no-new-statics.md
index c25c360d..bbfc87cc 100644
--- a/docs/rules/no-new-statics.md
+++ b/docs/rules/no-new-statics.md
@@ -31,5 +31,6 @@ Promise.all([p1, p2])
## When Not To Use It
-If you do not want to be notified when calling `new` on a Promise static method,
-you can safely disable this rule.
+If you do not want to be notified when calling `new` on a Promise static method
+(for example when using a type checker like Flow or Typescript), you can safely
+disable this rule.
From de9180b2e8bf56d19c11b2dec7003f129a9c3ff1 Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 12:32:37 +1000
Subject: [PATCH 13/16] docs(valid-params): mention typescript
---
docs/rules/valid-params.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/rules/valid-params.md b/docs/rules/valid-params.md
index 08b66042..4cceca1c 100644
--- a/docs/rules/valid-params.md
+++ b/docs/rules/valid-params.md
@@ -60,5 +60,5 @@ somePromise().finally(console.log)
## When Not To Use It
If you do not want to be notified when passing an invalid number of arguments to
-a Promise function (for example, when using a typechecker like Flow), you can
-safely disable this rule.
+a Promise function (for example, when using a type checker like Flow or
+Typescript), you can safely disable this rule.
From 8071392ceae4b27f0f51443cf4ffb8efd92ce526 Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 12:55:30 +1000
Subject: [PATCH 14/16] docs(prefer-await-to-callbacks): add documentation
---
docs/rules/prefer-await-to-callbacks.md | 36 ++++++++++++++++++++++++-
1 file changed, 35 insertions(+), 1 deletion(-)
diff --git a/docs/rules/prefer-await-to-callbacks.md b/docs/rules/prefer-await-to-callbacks.md
index ae61b4ba..1f38ba70 100644
--- a/docs/rules/prefer-await-to-callbacks.md
+++ b/docs/rules/prefer-await-to-callbacks.md
@@ -1 +1,35 @@
-# Prefer async/await to the callback pattern (prefer-await-to-callbacks)
+# Prefer `async`/`await` to the callback pattern (prefer-await-to-callbacks)
+
+`async` and `await` are clearer and easier to understand than using callbacks.
+
+## Rule details
+
+ES2017's `async` and `await` are easier and clearer ways to deal with
+asynchronous code than the callback pattern.
+
+Examples of **incorrect** code for this rule:
+
+```js
+cb()
+callback()
+doSomething(arg, err => {})
+function doSomethingElse(cb) {}
+```
+
+Examples of **correct** code for this rule:
+
+```js
+await doSomething(arg)
+async function doSomethingElse() {}
+yield yieldValue(err => {})
+eventEmitter.on('error', err => {})
+```
+
+## When Not To Use It
+
+If you are not targeting an ES2017 or above environment and do not have a
+shim for `async`/`await`, you should disable this rule.
+
+## Further Reading
+
+- [Making asynchronous programming easier with async and await on MDN](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await)
From 00e6d0bc9d7889f5e191e13cf24364660be92123 Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 12:57:41 +1000
Subject: [PATCH 15/16] docs(prefer-await-to-then): use new format
# Conflicts:
# docs/rules/prefer-await-to-then.md
---
docs/rules/prefer-await-to-then.md | 69 ++++++++++++++++++++++--------
1 file changed, 51 insertions(+), 18 deletions(-)
diff --git a/docs/rules/prefer-await-to-then.md b/docs/rules/prefer-await-to-then.md
index fe1ffab0..35bf3805 100644
--- a/docs/rules/prefer-await-to-then.md
+++ b/docs/rules/prefer-await-to-then.md
@@ -1,26 +1,13 @@
# Prefer `await` to `then()`/`catch()`/`finally()` for reading Promise values (prefer-await-to-then)
-#### Valid
+`async` and `await` can be clearer and easier to understand than using `then()`.
-```js
-async function example() {
- let val = await myPromise()
- val = doSomethingSync(val)
- return doSomethingElseAsync(val)
-}
+## Rule Details
-async function exampleTwo() {
- try {
- let val = await myPromise()
- val = doSomethingSync(val)
- return await doSomethingElseAsync(val)
- } catch (err) {
- errors(err)
- }
-}
-```
+ES2017's `async` and `await` can be easier and clearer to deal with promises
+than using `then()` and `catch()`.
-#### Invalid
+Examples of **incorrect** code for this rule:
```js
function example() {
@@ -34,6 +21,7 @@ function exampleTwo() {
.catch(errors)
}
+
function exampleThree() {
return myPromise
.catch(errors)
@@ -44,3 +32,48 @@ function exampleFour() {
.finally(cleanup)
}
```
+
+Examples of **correct** code for this rule:
+
+```js
+async function example() {
+ let val = await myPromise()
+ val = doSomethingSync(val)
+ return doSomethingElseAsync(val)
+}
+
+async function exampleTwo() {
+ try {
+ let val = await myPromise()
+ val = doSomethingSync(val)
+ return await doSomethingElseAsync(val)
+ } catch (err) {
+ errors(err)
+ }
+}
+
+async function exampleThree() {
+ try {
+ await myPromise
+ } catch(error) {
+ errors(error)
+ }
+}
+
+async function exampleFour() {
+ try {
+ await myPromise
+ } finally {
+ cleanup()
+ }
+}
+```
+
+## When Not To Use It
+
+If you are not targeting an ES2017 or above environment and do not have a
+shim for `async`/`await`, you should disable this rule.
+
+## Further Reading
+
+- [Making asynchronous programming easier with async and await on MDN](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await)
From 88ef1206544a94b7e2c1bd920fd29e733a18cdb9 Mon Sep 17 00:00:00 2001
From: cherryblossom <31467609+cherryblossom000@users.noreply.github.com>
Date: Sat, 18 Jul 2020 17:44:18 +1000
Subject: [PATCH 16/16] docs(no-promise-in-callback): add documentation
---
docs/rules/no-promise-in-callback.md | 30 ++++++++++++++++++++++++++++
1 file changed, 30 insertions(+)
diff --git a/docs/rules/no-promise-in-callback.md b/docs/rules/no-promise-in-callback.md
index a5d56b5a..0ef316ae 100644
--- a/docs/rules/no-promise-in-callback.md
+++ b/docs/rules/no-promise-in-callback.md
@@ -1 +1,31 @@
# Avoid using promises inside of callbacks (no-promise-in-callback)
+
+Discourages the use of promises inside callbacks.
+
+## Rule Details
+
+Promises and callbacks are different ways to handle asynchronous code and should
+not be mixed.
+
+Examples of **incorrect** code for this rule:
+
+```js
+doSomething((err, val) => {
+ if (err) console.error(err)
+ else doSomethingElse(val).then(console.log)
+})
+```
+
+Examples of **correct** code for this rule:
+
+```js
+require('pify')(doSomething)()
+ .then(doSomethingElse)
+ .then(console.log)
+ .catch(console.error)
+```
+
+## When Not To Use It
+
+If you do not want to be notified when using promises inside of callbacks, you
+can safely disable this rule.