Skip to content

Commit a13919d

Browse files
macklinumacklinu
committed
docs: migrate rule documentation to docs/rules
Related to #109
1 parent 8c82ddb commit a13919d

13 files changed

+234
-252
lines changed

‎README.md

+26-252
Original file line numberDiff line numberDiff line change
@@ -14,18 +14,6 @@ Enforce best practices for JavaScript promises.
1414
* [Installation](#installation)
1515
* [Usage](#usage)
1616
* [Rules](#rules)
17-
* [`catch-or-return`](#catch-or-return)
18-
* [`no-return-wrap`](#no-return-wrap)
19-
* [`param-names`](#param-names)
20-
* [`always-return`](#always-return)
21-
* [`no-native`](#no-native)
22-
* [`no-nesting`](#no-nesting)
23-
* [`no-promise-in-callback`](#no-promise-in-callback)
24-
* [`no-callback-in-promise`](#no-callback-in-promise)
25-
* [`avoid-new`](#avoid-new)
26-
* [`no-return-in-finally`](#no-return-in-finally)
27-
* [`prefer-await-to-then`](#prefer-await-to-then)
28-
* [`prefer-await-to-callbacks`](#prefer-await-to-callbacks)
2917
* [Maintainers](#maintainers)
3018
* [License](#license)
3119

@@ -88,20 +76,20 @@ or start with the recommended rule set
8876

8977
## Rules
9078

91-
| rule | description | recommended | fixable |
92-
| --------------------------- | -------------------------------------------------------------------------------- | ----------- | -------- |
93-
| `catch-or-return` | Enforces the use of `catch()` on un-returned promises. | :bangbang: | |
94-
| `no-return-wrap` | Avoid wrapping values in `Promise.resolve` or `Promise.reject` when not needed. | :bangbang: | |
95-
| `param-names` | Enforce consistent param names when creating new promises. | :bangbang: | :wrench: |
96-
| `always-return` | Return inside each `then()` to create readable and reusable Promise chains. | :bangbang: | |
97-
| `no-native` | In an ES5 environment, make sure to create a `Promise` constructor before using. | | |
98-
| `no-nesting` | Avoid nested `then()` or `catch()` statements | :warning: | |
99-
| `no-promise-in-callback` | Avoid using promises inside of callbacks | :warning: | |
100-
| `no-callback-in-promise` | Avoid calling `cb()` inside of a `then()` (use [nodeify][] instead) | :warning: | |
101-
| `avoid-new` | Avoid creating `new` promises outside of utility libs (use [pify][] instead) | :warning: | |
102-
| `no-return-in-finally` | Disallow return statements in `finally()` | :warning: | |
103-
| `prefer-await-to-then` | Prefer `await` to `then()` for reading Promise values | :seven: | |
104-
| `prefer-await-to-callbacks` | Prefer async/await to the callback pattern | :seven: | |
79+
| rule | description | recommended | fixable |
80+
| -------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------- | -------- |
81+
| [`catch-or-return`][catch-or-return] | Enforces the use of `catch()` on un-returned promises. | :bangbang: | |
82+
| [`no-return-wrap`][no-return-wrap] | Avoid wrapping values in `Promise.resolve` or `Promise.reject` when not needed. | :bangbang: | |
83+
| [`param-names`][param-names] | Enforce consistent param names when creating new promises. | :bangbang: | :wrench: |
84+
| [`always-return`][always-return] | Return inside each `then()` to create readable and reusable Promise chains. | :bangbang: | |
85+
| [`no-native`][no-native] | In an ES5 environment, make sure to create a `Promise` constructor before using. | | |
86+
| [`no-nesting`][no-nesting] | Avoid nested `then()` or `catch()` statements | :warning: | |
87+
| [`no-promise-in-callback`][no-promise-in-callback] | Avoid using promises inside of callbacks | :warning: | |
88+
| [`no-callback-in-promise`][no-callback-in-promise] | Avoid calling `cb()` inside of a `then()` (use [nodeify][] instead) | :warning: | |
89+
| [`avoid-new` ][avoid-new] | Avoid creating `new` promises outside of utility libs (use [pify][] instead) | :warning: | |
90+
| [`no-return-in-finally`][no-return-in-finally] | Disallow return statements in `finally()` | :warning: | |
91+
| [`prefer-await-to-then`][prefer-await-to-then] | Prefer `await` to `then()` for reading Promise values | :seven: | |
92+
| [`prefer-await-to-callbacks`][prefer-await-to-callbacks] | Prefer async/await to the callback pattern | :seven: | |
10593

10694
**Key**
10795

@@ -112,232 +100,6 @@ or start with the recommended rule set
112100
| :seven: | ES2017 Async Await rules |
113101
| :wrench: | Rule is fixable with `eslint --fix` |
114102

115-
### `catch-or-return`
116-
117-
Ensure that each time a `then()` is applied to a promise, a `catch()` is applied
118-
as well. Exceptions are made if you are returning that promise.
119-
120-
#### Valid
121-
122-
```js
123-
myPromise.then(doSomething).catch(errors)
124-
myPromise
125-
.then(doSomething)
126-
.then(doSomethingElse)
127-
.catch(errors)
128-
function doSomethingElse() {
129-
return myPromise.then(doSomething)
130-
}
131-
```
132-
133-
#### Invalid
134-
135-
```js
136-
myPromise.then(doSomething)
137-
myPromise.then(doSomething, catchErrors) // catch() may be a little better
138-
function doSomethingElse() {
139-
myPromise.then(doSomething)
140-
}
141-
```
142-
143-
#### Options
144-
145-
##### `allowThen`
146-
147-
You can pass an `{ allowThen: true }` as an option to this rule to allow for
148-
`.then(null, fn)` to be used instead of `catch()` at the end of the promise
149-
chain.
150-
151-
##### `terminationMethod`
152-
153-
You can pass a `{ terminationMethod: 'done' }` as an option to this rule to
154-
require `done()` instead of `catch()` at the end of the promise chain. This is
155-
useful for many non-standard Promise implementations.
156-
157-
You can also pass an array of methods such as
158-
`{ terminationMethod: ['catch', 'asCallback', 'finally'] }`.
159-
160-
This will allow any of
161-
162-
```js
163-
Promise.resolve(1)
164-
.then(() => {
165-
throw new Error('oops')
166-
})
167-
.catch(logerror)
168-
Promise.resolve(1)
169-
.then(() => {
170-
throw new Error('oops')
171-
})
172-
.asCallback(cb)
173-
Promise.resolve(1)
174-
.then(() => {
175-
throw new Error('oops')
176-
})
177-
.finally(cleanUp)
178-
```
179-
180-
### `no-return-wrap`
181-
182-
Ensure that inside a `then()` or a `catch()` we always `return` or `throw` a raw
183-
value instead of wrapping in `Promise.resolve` or `Promise.reject`
184-
185-
#### Valid
186-
187-
```js
188-
myPromise.then(function(val) {
189-
return val * 2
190-
})
191-
myPromise.then(function(val) {
192-
throw 'bad thing'
193-
})
194-
```
195-
196-
#### Invalid
197-
198-
```js
199-
myPromise.then(function(val) {
200-
return Promise.resolve(val * 2)
201-
})
202-
myPromise.then(function(val) {
203-
return Promise.reject('bad thing')
204-
})
205-
```
206-
207-
#### Options
208-
209-
##### `allowReject`
210-
211-
Pass `{ allowReject: true }` as an option to this rule to permit wrapping
212-
returned values with `Promise.reject`, such as when you would use it as another
213-
way to reject the promise.
214-
215-
### `param-names`
216-
217-
Enforce standard parameter names for Promise constructors
218-
219-
:wrench: The `--fix` option on the command line can automatically fix some of
220-
the problems reported by this rule.
221-
222-
#### Valid
223-
224-
```js
225-
new Promise(function (resolve) { ... })
226-
new Promise(function (resolve, reject) { ... })
227-
```
228-
229-
#### Invalid
230-
231-
```js
232-
new Promise(function (reject, resolve) { ... }) // incorrect order
233-
new Promise(function (ok, fail) { ... }) // non-standard parameter names
234-
```
235-
236-
Ensures that `new Promise()` is instantiated with the parameter names
237-
`resolve, reject` to avoid confusion with order such as `reject, resolve`. The
238-
Promise constructor uses the
239-
[RevealingConstructor pattern](https://blog.domenic.me/the-revealing-constructor-pattern/).
240-
Using the same parameter names as the language specification makes code more
241-
uniform and easier to understand.
242-
243-
### `always-return`
244-
245-
Ensure that inside a `then()` you make sure to `return` a new promise or value.
246-
See http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html (rule #5)
247-
for more info on why that's a good idea.
248-
249-
We also allow someone to `throw` inside a `then()` which is essentially the same
250-
as `return Promise.reject()`.
251-
252-
#### Valid
253-
254-
```js
255-
myPromise.then((val) => val * 2));
256-
myPromise.then(function(val) { return val * 2; });
257-
myPromise.then(doSomething); // could be either
258-
myPromise.then((b) => { if (b) { return "yes" } else { return "no" } });
259-
```
260-
261-
#### Invalid
262-
263-
```js
264-
myPromise.then(function(val) {})
265-
myPromise.then(() => {
266-
doSomething()
267-
})
268-
myPromise.then(b => {
269-
if (b) {
270-
return 'yes'
271-
} else {
272-
forgotToReturn()
273-
}
274-
})
275-
```
276-
277-
### `no-native`
278-
279-
Ensure that `Promise` is included fresh in each file instead of relying on the
280-
existence of a native promise implementation. Helpful if you want to use
281-
`bluebird` or if you don't intend to use an ES6 Promise shim.
282-
283-
#### Valid
284-
285-
```js
286-
var Promise = require('bluebird')
287-
var x = Promise.resolve('good')
288-
```
289-
290-
#### Invalid
291-
292-
```js
293-
var x = Promise.resolve('bad')
294-
```
295-
296-
### `no-nesting`
297-
298-
Avoid nested `then()` or `catch()` statements
299-
300-
### `no-promise-in-callback`
301-
302-
Avoid using promises inside of callbacks
303-
304-
### `no-callback-in-promise`
305-
306-
Avoid calling `cb()` inside of a `then()` (use [nodeify][] instead)
307-
308-
### `avoid-new`
309-
310-
Avoid creating `new` promises outside of utility libs (use [pify][] instead)
311-
312-
### `no-return-in-finally`
313-
314-
Disallow return statements inside a callback passed to `finally()`, since
315-
nothing would consume what's returned.
316-
317-
#### Valid
318-
319-
```js
320-
myPromise.finally(function(val) {
321-
console.log('value:', val)
322-
})
323-
```
324-
325-
#### Invalid
326-
327-
```js
328-
myPromise.finally(function(val) {
329-
return val
330-
})
331-
```
332-
333-
### `prefer-await-to-then`
334-
335-
Prefer `await` to `then()` for reading Promise values
336-
337-
### `prefer-await-to-callbacks`
338-
339-
Prefer async/await to the callback pattern
340-
341103
## Maintainers
342104

343105
* Jamund Ferguson - [@xjamundx][]
@@ -348,6 +110,18 @@ Prefer async/await to the callback pattern
348110
* (c) MMXV jden <mailto:[email protected]> - ISC license.
349111
* (c) 2016 Jamund Ferguson <mailto:[email protected]> - ISC license.
350112

113+
[catch-or-return]: docs/rules/catch-or-return.md
114+
[no-return-wrap]: docs/rules/no-return-wrap.md
115+
[param-names]: docs/rules/param-names.md
116+
[always-return]: docs/rules/always-return.md
117+
[no-native]: docs/rules/no-native.md
118+
[no-nesting]: docs/rules/no-nesting.md
119+
[no-promise-in-callback]: docs/rules/no-promise-in-callback.md
120+
[no-callback-in-promise]: docs/rules/no-callback-in-promise.md
121+
[avoid-new]: docs/rules/avoid-new.md
122+
[no-return-in-finally]: docs/rules/no-return-in-finally.md
123+
[prefer-await-to-then]: docs/rules/prefer-await-to-then.md
124+
[prefer-await-to-callbacks]: docs/rules/prefer-await-to-callbacks.md
351125
[nodeify]: https://www.npmjs.com/package/nodeify
352126
[pify]: https://www.npmjs.com/package/pify
353127
[@macklinu]: https://github.com/macklinu

‎docs/rules/always-return.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Return inside each `then()` to create readable and reusable Promise chains (always-return)
2+
3+
Ensure that inside a `then()` you make sure to `return` a new promise or value.
4+
See http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html (rule #5)
5+
for more info on why that's a good idea.
6+
7+
We also allow someone to `throw` inside a `then()` which is essentially the same
8+
as `return Promise.reject()`.
9+
10+
#### Valid
11+
12+
```js
13+
myPromise.then((val) => val * 2));
14+
myPromise.then(function(val) { return val * 2; });
15+
myPromise.then(doSomething); // could be either
16+
myPromise.then((b) => { if (b) { return "yes" } else { return "no" } });
17+
```
18+
19+
#### Invalid
20+
21+
```js
22+
myPromise.then(function(val) {})
23+
myPromise.then(() => {
24+
doSomething()
25+
})
26+
myPromise.then(b => {
27+
if (b) {
28+
return 'yes'
29+
} else {
30+
forgotToReturn()
31+
}
32+
})
33+
```

‎docs/rules/avoid-new.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Avoid creating `new` promises outside of utility libs (use [pify][] instead) (avoid-new)
2+
3+
[pify]: https://www.npmjs.com/package/pify

0 commit comments

Comments
 (0)