docs [import-style]: Improve documentation of import-style

[sharky98]

Element to improve in the docs

A - Application of the rule

By simply reading the docs it isn't clear if that rule applies only to the import of the three listed modules (util, path, chalk) or all modules when using the default "plugin:unicorn/recommended".

My first assumption was that style default was prioritized over the other, while in fact it's only the three modules shown that are affected.

Examples

• ❌ Not triggered on import import * as React from "react";.
• ✅ Triggered on import import * as path from "node:path";.

Proposed modification

Sometimes a module contains unrelated functions, like `util`, thus it is a good practice to enforce destructuring or named imports here. Other times, in modules like `path`, it is good to use default import as they have similar functions, all likely to be utilized.

+This rule applies only to specified modules in `styles` option. If a module is not listed in `styles`, it will not be linted.

This rule defines 4 import styles:

### styles

Type: `object`

-You can extend default import styles per module by passing the `styles` option.
+You can extend the import styles accepted for each module individually by passing the `styles` option and adding a key for each module.

Default options per module are:

B - Contradiction with default tsconfig.json

Since default configuration for tsconfig.json are false for both allowSyntheticDefaultImports and esModuleInterop, using default import is not authorized; it raise error TS1259.

Proposed modification

Sometimes a module contains unrelated functions, like `util`, thus it is a good practice to enforce destructuring or named imports here. Other times, in modules like `path`, it is good to use default import as they have similar functions, all likely to be utilized.

+💫 Using the default configuration of this rule will contradict with configuration of TypeScript `allowSyntheticDefaultImports = false` and `esModuleInterop = false`. In such case, you can disable this rule or extend the styles to allow `namespace` import style for the module that requires it like `path` or `react`.

This rule defines 4 import styles:

Feel free to use another emoji, I used the dizzy one, since I was so dizzy or figuring this out 😅!

[sindresorhus]

Since default configuration for tsconfig.json are false for both allowSyntheticDefaultImports and esModuleInterop, using default import is not authorized; it raise error TS1259.

esModuleInterop is enabled by default module is node16 or nodenext, which is expected config for using ESM and import.

[sharky98]

While this is true; and esModuleInterop is recommended (most bases set it true against the default), it does come with issues for library makers. See the following discussions.

• TypeScript generated invalid types if esModuleInterop is enabled microsoft/TypeScript#52779
• Set esModuleInterop to "true" by default microsoft/TypeScript#41139 (comment)
• type-coverage-core itself is incompatible with default tsconfig plantain-00/type-coverage#78

My understanding reading these is that for an end-user project, esModuleInterop should be set to true. However, for a module distributed, it should be set to false.

• https://evertpot.com/universal-commonjs-esm-typescript-packages/#esmoduleinterop