Skip to content

Sorting Rules

Jump to bottom
Zhao DAI edited this page Sep 16, 2022 · 5 revisions

Sorting Rules

You can customize sorting rules for all imports and exports, or imports within a group.

Table of Content

Introduction

Sorting rules define two things:

  • paths: How to compare import paths.
  • names: How to compare imported/exported names.
interface SortRules {
  paths: SortRule;
  names: SortRule;
}

Note:

  • The order between groups or sub-groups are defined in groupRules. (Wiki)
  • Script imports will NOT be sorted regardless of SortRules.

You can define global sorting rules for all groups and exports in sortRules:

"sortRules": {
  "paths": ["_", "aA"],
  "names": ["_", "aA"]
}

And you can define sorting rules for a group in groupRules:

"groupRules": [
  {
    "regex": "^[@]",
    "sort": {
      "paths": ["AZ", "az"],
      "names": ["AZ", "az"]
    }
  }
]

Both sorRules and groupRules.sort can be "none" which will disable sorting globally/locally.

Sorting Rule

A SortRule is either "none", or an array of segments defined by Segment Sort.

"none"

If you set paths to "none", import statements will not be sorted if sortImportsBy is "paths".

If you set names to "none", names will not be sorted inside an import/export statement, and import statements will not be sorted if sortImportsBy is "names".

Segment

Please refer to Segment Sort Algorithm for details.

Some Examples

["_", "aA"]

  • Strings are compared case-insensitively, and lower case goes first in case of a tie.
  • [, \, ], ^, _, `(backtick) are in front of letters ([a-zA-Z]).

This is the default sorting rule for both paths and names in JS/TS Import Sorter. A sorted example is ['_', 'a', 'A', 'b', 'B'].

["Aa", "_"]

  • Strings are compared case-insensitively, and upper case goes first in case of a tie.
  • [, \, ], ^, _, `(backtick) are after letters ([a-zA-Z]).

This is also widely used, e.g. as the default option ("case-insensitive") in TSLint Rule: ordered-imports. A sorted example is ['A', 'a', 'B', 'b', '_'].

["az", "_", "AZ"]

  • Strings are compared case-sensitively, and lower-case letters ([a-z]) are in front of upper-case letters ([A-Z]).
  • [, \, ], ^, _, `(backtick) are behind lower-case letters and before upper-case letters.

This corresponds to "lowercase-first" in TSLint Rule: ordered-imports. A sorted example is ['a', 'b', '_', 'A', 'B'].

["AZ", "_", "az"]

  • Strings are compared case-sensitively, and upper-case letters ([A-Z]) are in front of lower-case letters ([a-z]).
  • [, \, ], ^, _, `(backtick) are behind upper-case letters and before lower-case letters.

This corresponds to "lowercase-last" in TSLint Rule: ordered-imports.

This is also the fall-back rule for undefined, null, [] or any malformed rules.

A sorted example is ['A', 'B', '_', 'a', 'b'].

Incomplete Rules

JS/TS Importer/Export Sorter will try to complete sorting rules by appending missing segments in the end.

For example, ["az", "_"] will be padded with "AZ" in the end, and equals to ["az", "_", "AZ"].

But JS/TS Importer/Export Sorter will give up and use fall-back rule if there is uncertainty. For example, ["az"] can't be completed as the order between "_" and "AZ" is unknown, hence the fall-back rule (["AZ", "_", "az"]) is used.

Here are some incomplete but meaningful rules:

  • ["az", "_"] => ["az", "_", "AZ"]
  • ["AZ", "_"] => ["AZ", "_", "az"]
  • ["Aa"] => ["Aa", "_"]
  • ["aA"] => ["aA", "_"]

Overlapped Rules

When segments overlap each other, the one that appears first takes effect.

For example, ["aA", "az"] is equal to ["aA"] because "az" is covered by previous "aA".

["az", "aA"] is equal to ["az", "AZ"] because the lower-case part of "aA" is overlapped, but not the upper-case part.

JS/TS Importer/Export Sorter tolerates overlapped rules for better user experience but you shouldn't use them in your projects.

Clone this wiki locally