Skip to content

Commit 5126a69

Browse files
authored
WIP: Port docs for each rule (#3)
* some work on readonly-keyword * readonly * Spelling * Format * Casing * readonly array * no-let * no-array-mutation * no-object-mutation * no-method-signature * no-delete * no-class * no-mixed-interface * no-expression-statement * no-if-statement * no-loop-statement * no-throw * no-try * no-reject
1 parent aa737a5 commit 5126a69

20 files changed

+296
-180
lines changed

README.md

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -77,29 +77,29 @@ In addition to immutable rules this project also contains a few rules for enforc
7777

7878
### Immutability rules
7979

80-
| Name | Description | :heavy_check_mark: | :wrench: | :thought_balloon: |
81-
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------ | -------- | ----------------- |
82-
| [`ts-immutable/readonly-keyword`](./docs/rules/readonly-keyword.md) | Enforce readonly modifiers are used where possible. | :heavy_check_mark: | :wrench: | |
83-
| [`ts-immutable/readonly-array`](./docs/rules/readonly-array.md) | Prefer readonly array over mutable arrays. | :heavy_check_mark: | :wrench: | |
84-
| [`ts-immutable/no-let`](./docs/rules/no-let.md) | Disallow mutable variables. | :heavy_check_mark: | :wrench: | |
85-
| [`ts-immutable/no-array-mutation`](./docs/rules/no-array-mutation.md) | Disallow mutating arrays. | :heavy_check_mark: | | :thought_balloon: |
86-
| [`ts-immutable/no-object-mutation`](./docs/rules/no-object-mutation.md) | WIP | :heavy_check_mark: | | :thought_balloon: |
87-
| [`ts-immutable/no-method-signature`](./docs/rules/no-method-signature.md) | Prefer property signatures with readonly modifiers over method signatures. | :heavy_check_mark: | | |
88-
| [`ts-immutable/no-delete`](./docs/rules/no-delete.md) | Disallow delete expressions. | :heavy_check_mark: | | |
80+
| Name | Description | :heavy_check_mark: | :wrench: | :thought_balloon: |
81+
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------ | -------- | ----------------- |
82+
| [`ts-immutable/readonly-keyword`](./docs/rules/readonly-keyword.md) | Enforce readonly modifiers are used where possible | :heavy_check_mark: | :wrench: | |
83+
| [`ts-immutable/readonly-array`](./docs/rules/readonly-array.md) | Prefer readonly array over mutable arrays | :heavy_check_mark: | :wrench: | |
84+
| [`ts-immutable/no-let`](./docs/rules/no-let.md) | Disallow mutable variables | :heavy_check_mark: | :wrench: | |
85+
| [`ts-immutable/no-array-mutation`](./docs/rules/no-array-mutation.md) | Disallow mutating arrays | :heavy_check_mark: | | :thought_balloon: |
86+
| [`ts-immutable/no-object-mutation`](./docs/rules/no-object-mutation.md) | Disallow mutating objects | :heavy_check_mark: | | :thought_balloon: |
87+
| [`ts-immutable/no-method-signature`](./docs/rules/no-method-signature.md) | Prefer property signatures with readonly modifiers over method signatures | :heavy_check_mark: | | |
88+
| [`ts-immutable/no-delete`](./docs/rules/no-delete.md) | Disallow delete expressions | :heavy_check_mark: | | |
8989

9090
### Functional style rules
9191

92-
| Name | Description | :heavy_check_mark: | :wrench: | :thought_balloon: |
93-
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------ | -------- | ----------------- |
94-
| [`ts-immutable/no-this`](./docs/rules/no-this.md) | Disallow this access. | :heavy_check_mark: | | |
95-
| [`ts-immutable/no-class`](./docs/rules/no-class.md) | Disallow classes. | :heavy_check_mark: | | |
96-
| [`ts-immutable/no-mixed-interface`](./docs/rules/no-mixed-interface.md) | Restrict interfaces so that only members of the same kind of are allowed in them. | :heavy_check_mark: | | |
97-
| [`ts-immutable/no-expression-statement`](./docs/rules/no-expression-statement.md) | Using expressions to cause side-effects not allowed. | :heavy_check_mark: | | |
98-
| [`ts-immutable/no-if-statement`](./docs/rules/no-if-statement.md) | Disallow if statements. | :heavy_check_mark: | | |
99-
| [`ts-immutable/no-loop-statement`](./docs/rules/no-loop-statement.md) | Disallow imperative loops. | :heavy_check_mark: | | |
100-
| [`ts-immutable/no-throw`](./docs/rules/no-throw.md) | Disallow throwing exceptions. | :heavy_check_mark: | | |
101-
| [`ts-immutable/no-try`](./docs/rules/no-try.md) | Disallow try-catch[-finally] and try-finally patterns. | :heavy_check_mark: | | |
102-
| [`ts-immutable/no-reject`](./docs/rules/no-reject.md) | Disallow try-catch[-finally] and try-finally patterns. | :heavy_check_mark: | | |
92+
| Name | Description | :heavy_check_mark: | :wrench: | :thought_balloon: |
93+
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------ | -------- | ----------------- |
94+
| [`ts-immutable/no-this`](./docs/rules/no-this.md) | Disallow this access | :heavy_check_mark: | | |
95+
| [`ts-immutable/no-class`](./docs/rules/no-class.md) | Disallow classes | :heavy_check_mark: | | |
96+
| [`ts-immutable/no-mixed-interface`](./docs/rules/no-mixed-interface.md) | Restrict interfaces so that only members of the same kind of are allowed in them | :heavy_check_mark: | | |
97+
| [`ts-immutable/no-expression-statement`](./docs/rules/no-expression-statement.md) | Using expressions to cause side-effects not allowed | :heavy_check_mark: | | |
98+
| [`ts-immutable/no-if-statement`](./docs/rules/no-if-statement.md) | Disallow if statements | :heavy_check_mark: | | |
99+
| [`ts-immutable/no-loop-statement`](./docs/rules/no-loop-statement.md) | Disallow imperative loops | :heavy_check_mark: | | |
100+
| [`ts-immutable/no-throw`](./docs/rules/no-throw.md) | Disallow throwing exceptions | :heavy_check_mark: | | |
101+
| [`ts-immutable/no-try`](./docs/rules/no-try.md) | Disallow try-catch[-finally] and try-finally patterns | :heavy_check_mark: | | |
102+
| [`ts-immutable/no-reject`](./docs/rules/no-reject.md) | Disallow try-catch[-finally] and try-finally patterns | :heavy_check_mark: | | |
103103

104104
## Recommended standard rules
105105

docs/rules/no-array-mutation.md

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
### no-array-mutation
1+
# Disallow mutating arrays (no-array-mutation)
22

3-
[![Type Info Required][type-info-badge]][type-info-url]
3+
This rule prohibits mutating an array via assignment to or deletion of their elements/properties. This rule enforces array immutability without the use of `ReadonlyArray<T>` (as apposed to [readonly-array](./readonly-array.md)).
44

5-
This rule prohibits mutating an array via assignment to or deletion of their elements/properties. This rule enforces array immutability without the use of `ReadonlyArray<T>` (as apposed to [readonly-array](#readonly-array)).
5+
## Rule Details
66

77
```typescript
88
const x = [0, 1, 2];
@@ -12,28 +12,34 @@ x.length = 1; // <- Mutating an array is not allowed.
1212
x.push(3); // <- Mutating an array is not allowed.
1313
```
1414

15-
#### Has Fixer
15+
## Options
1616

17-
No
17+
The rule accepts an options object with the following properties:
1818

19-
#### Options
19+
```typescript
20+
type Options = {
21+
readonly ignoreNewArray?: boolean;
22+
readonly ignorePattern?: string | Array<string>;
23+
readonly ignorePrefix?: string | Array<string>;
24+
readonly ignoreSuffix?: string | Array<string>;
25+
};
26+
27+
const defaults = {
28+
ignoreNewArray: false
29+
};
30+
```
2031

21-
- [ignore-prefix](#using-the-ignore-prefix-option)
22-
- [ignore-suffix](#using-the-ignore-suffix-option)
23-
- [ignore-pattern](#using-the-ignore-pattern-option)
24-
- [ignore-new-array](#using-the-ignore-new-array-option-with-no-array-mutation)
25-
- ~~ignore-mutation-following-accessor~~ - _deprecated in favor of [ignore-new-array](#using-the-ignore-new-array-option-with-no-array-mutation)_
32+
### `ignore-new-array`
2633

27-
#### Example config
34+
This option allows for the use of array mutator methods to be chained to newly created arrays.
2835

29-
```javascript
30-
"no-array-mutation": true
31-
```
36+
For example, an array can be immutably sorted like so:
3237

33-
```javascript
34-
"no-array-mutation": [true, {"ignore-prefix": "mutable"}]
38+
```typescript
39+
const original = ["foo", "bar", "baz"];
40+
const sorted = original.slice().sort((a, b) => a.localeCompare(b)); // This is OK with ignore-new-array - note the use of the `slice` method which returns a copy of the original array.
3541
```
3642

37-
```javascript
38-
"no-array-mutation": [true, "ignore-new-array"]
39-
```
43+
### `ignorePattern`
44+
45+
See the [ignorePattern](./options-ignore-pattern.md) docs.

docs/rules/no-class.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
### no-class
1+
# Disallow classes (no-class)
2+
3+
Disallow use of the `class` keyword.
4+
5+
## Rule Details
26

37
Thanks to libraries like [recompose](https://github.com/acdlite/recompose) and Redux's [React Container components](http://redux.js.org/docs/basics/UsageWithReact.html), there's not much reason to build Components using `React.createClass` or ES6 classes anymore. The `no-this` rule makes this explicit.
48

@@ -30,3 +34,7 @@ const OptimizedMessage = pure(Message);
3034
// Even more optimized: only updates if specific prop keys have changed
3135
const HyperOptimizedMessage = onlyUpdateForKeys(["message"], Message);
3236
```
37+
38+
## Options
39+
40+
The rule does not accept any options.

docs/rules/no-delete.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1-
### no-delete
1+
# Disallow delete expressions (no-delete)
22

33
The delete operator allows for mutating objects by deleting keys. This rule disallows any delete expressions.
44

5+
## Rule Details
6+
57
```typescript
68
delete object.property; // Unexpected delete, objects should be considered immutable.
79
```
@@ -11,3 +13,7 @@ As an alternative the spread operator can be used to delete a key in an object (
1113
```typescript
1214
const { [action.id]: deletedItem, ...rest } = state;
1315
```
16+
17+
## Options
18+
19+
The rule does not accept any options.

docs/rules/no-expression-statement.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
### no-expression-statement
1+
# Using expressions to cause side-effects not allowed (no-expression-statement)
2+
3+
This rule checks that the value of an expression is assigned to a variable and thus helps promote side-effect free (pure) functions.
4+
5+
## Rule Details
26

37
When you call a function and don’t use it’s return value, chances are high that it is being called for its side effect. e.g.
48

@@ -7,22 +11,20 @@ array.push(1);
711
alert("Hello world!");
812
```
913

10-
This rule checks that the value of an expression is assigned to a variable and thus helps promote side-effect free (pure) functions.
11-
12-
#### Options
14+
## Options
1315

14-
- [ignore-prefix](#using-the-ignore-prefix-option-with-no-expression-statement)
16+
The rule accepts an options object with the following properties:
1517

16-
#### Example config
18+
```typescript
19+
type Options = {
20+
readonly ignorePattern?: string | Array<string>;
21+
readonly ignorePrefix?: string | Array<string>;
22+
readonly ignoreSuffix?: string | Array<string>;
23+
};
1724

18-
```javascript
19-
"no-expression-statement": true
25+
const defaults = {};
2026
```
2127

22-
```javascript
23-
"no-expression-statement": [true, {"ignore-prefix": "console."}]
24-
```
28+
### `ignorePattern`
2529

26-
```javascript
27-
"no-expression-statement": [true, {"ignore-prefix": ["console.log", "console.error"]}]
28-
```
30+
See the [ignorePattern](./options-ignore-pattern.md) docs.

docs/rules/no-if-statement.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
1-
### no-if-statement
1+
# Disallow if statements (no-if-statement)
22

3-
If statements is not a good fit for functional style programming as they are not expresssions and do not return a value. This rule disallows if statements.
3+
This rule disallows if statements.
4+
5+
## Rule Details
6+
7+
If statements is not a good fit for functional style programming as they are not expresssions and do not return a value.
48

59
```typescript
610
let x;
@@ -18,3 +22,7 @@ const x = i === 1 ? 2 : 3;
1822
```
1923

2024
For more background see this [blog post](https://hackernoon.com/rethinking-javascript-the-if-statement-b158a61cd6cb) and discussion in [#54](https://github.com/jonaskello/tslint-immutable/issues/54).
25+
26+
## Options
27+
28+
The rule does not accept any options.

docs/rules/no-let.md

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1-
### no-let
1+
# Disallow mutable variables (no-let)
22

33
This rule should be combined with tslint's built-in `no-var-keyword` rule to enforce that all variables are declared as `const`.
44

5+
## Rule Details
6+
57
There's no reason to use `let` in a Redux/React application, because all your state is managed by either Redux or React. Use `const` instead, and avoid state bugs altogether.
68

79
```typescript
@@ -21,27 +23,27 @@ const SearchResults = ({ results }) => (
2123
);
2224
```
2325

24-
#### Has Fixer
26+
## Options
2527

26-
Yes
28+
The rule accepts an options object with the following properties:
2729

28-
#### Options
30+
```typescript
31+
type Options = {
32+
readonly ignoreLocal?: boolean;
33+
readonly ignorePattern?: string | Array<string>;
34+
readonly ignorePrefix?: string | Array<string>;
35+
readonly ignoreSuffix?: string | Array<string>;
36+
};
37+
38+
const defaults = {
39+
ignoreLocal: false
40+
};
41+
```
2942

30-
- [ignore-local](#using-the-ignore-local-option)
31-
- [ignore-prefix](#using-the-ignore-prefix-option)
32-
- [ignore-suffix](#using-the-ignore-suffix-option)
33-
- [ignore-pattern](#using-the-ignore-pattern-option)
43+
### `ignoreLocal`
3444

35-
#### Example config
45+
See the [ignoreLocal](./options-ignore-local.md) docs.
3646

37-
```javascript
38-
"no-let": true
39-
```
47+
### `ignorePattern`
4048

41-
```javascript
42-
"no-let": [true, "ignore-local"]
43-
```
44-
45-
```javascript
46-
"no-let": [true, "ignore-local", {"ignore-prefix": "mutable"}]
47-
```
49+
See the [ignorePattern](./options-ignore-pattern.md) docs.

docs/rules/no-loop-statement.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
1-
### no-loop-statement
1+
# Disallow imperative loops (no-loop-statement)
22

3-
In functional programming we want everthing to be an expression that returns a value. Loops in typescript are statements so they are not a good fit for a functional programming style. This rule disallows for loop statements, including `for`, `for...of`, `for...in`, `while`, and `do...while`.
3+
This rule disallows for loop statements, including `for`, `for...of`, `for...in`, `while`, and `do...while`.
4+
5+
## Rule Details
6+
7+
In functional programming we want everthing to be an expression that returns a value. Loops in typescript are statements so they are not a good fit for a functional programming style.
48

59
```typescript
610
const numbers = [1, 2, 3];
@@ -18,3 +22,7 @@ const double = numbers.map(n => n * 2);
1822
```
1923

2024
For more background see this [blog post](https://hackernoon.com/rethinking-javascript-death-of-the-for-loop-c431564c84a8) and discussion in [#54](https://github.com/jonaskello/tslint-immutable/issues/54).
25+
26+
## Options
27+
28+
The rule does not accept any options.

docs/rules/no-method-signature.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
### no-method-signature
1+
# Prefer property signatures with readonly modifiers over method signatures (no-method-signature)
2+
3+
Prefer property signatures with readonly modifiers over method signatures.
4+
5+
## Rule Details
26

37
There are two ways function members can be declared in an interface or type alias:
48

@@ -10,3 +14,7 @@ interface Zoo {
1014
```
1115

1216
The `MethodSignature` and the `PropertySignature` forms seem equivalent, but only the `PropertySignature` form can have a `readonly` modifier. Becuase of this any `MethodSignature` will be mutable. Therefore the `no-method-signature` rule disallows usage of this form and instead proposes to use the `PropertySignature` which can have a `readonly` modifier. It should be noted however that the `PropertySignature` form for declaring functions does not support overloading.
17+
18+
## Options
19+
20+
The rule does not accept any options.

docs/rules/no-mixed-interface.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1-
### no-mixed-interface
1+
# Restrict interfaces so that only members of the same kind of are allowed in them (no-mixed-interface)
22

3-
Mixing functions and data properties in the same interface is a sign of object-orientation style. This rule enforces that an inteface only has one type of members, eg. only data properties or only functions.
3+
This rule enforces that an inteface only has one type of members, eg. only data properties or only functions.
4+
5+
## Rule Details
6+
7+
Mixing functions and data properties in the same interface is a sign of object-orientation style.
8+
9+
## Options
10+
11+
The rule does not accept any options.

0 commit comments

Comments
 (0)