From 006e9ea6b13e16ef58234aaf8fa0f03b1cb9b705 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sun, 7 May 2023 19:33:29 -0400 Subject: [PATCH 1/3] docs: be more explicit about what restrict-template-expressions restricts --- .../docs/rules/restrict-template-expressions.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/packages/eslint-plugin/docs/rules/restrict-template-expressions.md b/packages/eslint-plugin/docs/rules/restrict-template-expressions.md index d7afae0ee264..dd47245e9f85 100644 --- a/packages/eslint-plugin/docs/rules/restrict-template-expressions.md +++ b/packages/eslint-plugin/docs/rules/restrict-template-expressions.md @@ -6,9 +6,17 @@ 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. +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 @@ -47,6 +55,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 }`: From 08a712140bff90a5237cd58587fc83690e734de0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Josh=20Goldberg=20=E2=9C=A8?= Date: Sat, 8 Jul 2023 18:06:08 -0400 Subject: [PATCH 2/3] Update packages/eslint-plugin/docs/rules/restrict-template-expressions.md Co-authored-by: Joshua Chen --- .../eslint-plugin/docs/rules/restrict-template-expressions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/eslint-plugin/docs/rules/restrict-template-expressions.md b/packages/eslint-plugin/docs/rules/restrict-template-expressions.md index dd47245e9f85..eeb7c4881609 100644 --- a/packages/eslint-plugin/docs/rules/restrict-template-expressions.md +++ b/packages/eslint-plugin/docs/rules/restrict-template-expressions.md @@ -13,6 +13,8 @@ This rule reports on values used in a template literal string that aren't string :::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. From b8f8bccaf7fe93514fbc3c50cdbfe917f55739c2 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 8 Jul 2023 18:20:00 -0400 Subject: [PATCH 3/3] stringification is totally a word --- .cspell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.cspell.json b/.cspell.json index b8e07af48645..e92552cea303 100644 --- a/.cspell.json +++ b/.cspell.json @@ -108,6 +108,7 @@ "rulesets", "serializers", "Sourcegraph", + "stringification", "superset", "thenables", "transpiled",