Skip to content

docs: be more explicit about what restrict-template-expressions restricts #7009

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 8, 2023
Merged

docs: be more explicit about what restrict-template-expressions restricts #7009

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
006e9ea
docs: be more explicit about what restrict-template-expressions restr…
Josh-Cena May 7, 2023
08a7121
Update packages/eslint-plugin/docs/rules/restrict-template-expression…
JoshuaKGoldberg Jul 8, 2023
b8f8bcc
stringification is totally a word
JoshuaKGoldberg Jul 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,7 @@
"rulesets",
"serializers",
"Sourcegraph",
"stringification",
"superset",
"thenables",
"transpiled",
Expand Down
18 changes: 15 additions & 3 deletions packages/eslint-plugin/docs/rules/restrict-template-expressions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,19 @@ description: 'Enforce template literal expressions to be of `string` type.'
>
> See **https://typescript-eslint.io/rules/restrict-template-expressions** for documentation.

JavaScript will call `toString()` on an object when it is converted to a string, such as when `+` adding to a string or in `${}` template literals.
The default Object `.toString()` returns `"[object Object]"`, which is often not what was intended.
This rule reports on values used in a template literal string that aren't primitives and don't define a more useful `.toString()` method.
JavaScript automatically [converts an object to a string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion) in a string context, such as when concatenating it with a string using `+` or embedding it in a template literal using `${}`.
The default `toString()` method of objects returns `"[object Object]"`, which is often not what was intended.
This rule reports on values used in a template literal string that aren't strings, numbers, or BigInts, optionally allowing other data types that provide useful stringification results.

:::note

This rule intentionally does not allow objects with a custom `toString()` method to be used in template literals, because the stringification result may not be user-friendly.

For example, arrays have a custom [`toString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) method, which only calls `join()` internally, which joins the array elements with commas. This means that (1) array elements are not necessarily stringified to useful results (2) the commas don't have spaces after them, making the result not user-friendly. The best way to format arrays is to use [`Intl.ListFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat), which even supports adding the "and" conjunction where necessary.
You must explicitly call `object.toString()` if you want to use this object in a template literal.
The [`no-base-to-string`](./no-base-to-string.md) rule can be used to guard this case against producing `"[object Object]"` by accident.

:::

## Examples

Expand Down Expand Up @@ -47,6 +57,8 @@ const msg1 = `arg = ${arg}`;
const msg2 = `arg = ${arg || 'zero'}`;
```

This option controls both numbers and BigInts.

### `allowBoolean`

Examples of additional **correct** code for this rule with `{ allowBoolean: true }`:
Expand Down