Feature: Support Logical Ordering for Specific String Literal Types

[akibarika]

Describe the rule

In some cases, string literal types in TypeScript are better represented in a specific logical order rather than an alphabetical one. For example:

type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl'; // Logical order

In this case, the progression from 'xs' (extra small) to 'xl' (extra large) follows a clear semantic or domain-specific logic. However, the current sorting rules in eslint-plugin-perfectionist would reorder these alphabetically:

type Breakpoint = 'lg' | 'md' | 'sm' | 'xl' | 'xs'; // Alphabetical order

This disrupts the intended meaning and reduces the readability of such types, which are often used in design systems, configuration objects, or domain-specific types.

Code example

1. Design Systems: Breakpoints in CSS frameworks ('xs', 'sm', 'md', 'lg', 'xl').

2. User States: User states in a workflow ('pending', 'active', 'completed', 'archived').

3. Error Severity Levels: Severity levels ('low', 'medium', 'high', 'critical').

4. Task Priorities: Task priority levels ('low', 'normal', 'high', 'urgent').

5. Font size: thin, light, regular, bold.

Additional comments

No response

Validations

• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.

[hugop95]

Hi @akibarika

This is similar to #148 and #98.

I like this feature a lot, but I'm having trouble understanding the real use case:
Let's use your example

type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl'; // Logical order

[Question] Are there multiple cases where a user would need to define this specific logical order? If not, why not just disable the rule with eslint-disable for this type?

Edit: This feature makes actually sense in objects.

I see 2 challenges to tackle:

• Defining multiple configurations (one per "logic").
• Knowing when to use which configuration.

Point 1: Defining multiple configurations

At first sight, not technically complicated through options.

Point 2: Knowing when to use which configuration

This is where this gets a big harder. I don't think there is a way to automatically detect the appropriate logic to use based on code context alone.

One potential solution is to implement #400 with custom annotation comments.

Assuming that a logic configuration named sizeLogic is defined:

// @perfectionist/sort-objects { configuration: 'sizeLogic' }
const sizeNames = {
  xs: 'XS',
  s: 'S',
  m: 'Medium',
  l: 'Larger',
  xl: 'XL'
}

[akibarika]

Hi @hugop95 ,

Thank you for the quick response!

I agree with your points, and I also think it’s worth implementing this feature for objects.

Here’s a workaround I’ve been using:

"rules": {
  "perfectionist/sort-objects": [
    "warn",
    {
      "groups": ["xs", "sm", "md", "lg", "xl", "unknown"],
      "customGroups": {
        "xs": "xs",
        "sm": "sm",
        "md": "md",
        "lg": "lg",
        "xl": "xl"
      }
    }
  ]
}

It’s not a perfect solution and has some limitations, but it does work for now.

[hugop95]

I don't think there is a way to automatically detect the appropriate logic to use based on code context alone.

Thinking about it, there is actually a way if we consider that most "logical" groups are a set of specific keys: we can use the fact that users can pass multiple configurations to a single rule.

For sort-objects in particular (the rule that benefits the most from this), this means that we could pass

[
  {
    groups: ['r', 'g', 'b'],
    customGroups: [
      {
        groupName: 'r',
        elementNamePattern: 'r',
      },
      {
        groupName: 'g',
        elementNamePattern: 'g',
      },
      {
        groupName: 'b',
        elementNamePattern: 'b',
      },
    ],
    useConfigurationIf: {
      allElementNamesMatchPattern: '^r|g|b$',
    },
  },
  {}, // Fallback configuration with default rule options
],

This means that

let obj = {
  r: string,
  g: string,
  b: string,
}

would be correctly sorted by rgb logic, while other types would use the fallback configuration.

@OlivierZal What do you think?

[OlivierZal]

Hi @hugop95,

I agree with you that the best place to configure it should be the customGroups.

Here are some considerations though.

First, I think that the semantical sorting topic is legitimate: another common use case which comes to my mind is min | max.

However, I also see possible consistency issues with sorting.

e.g. when there are only min and max, it's ok:

interface Range {
  min: number
  max: number
}

but what is the expected behavior when it's mixed with other keys, e.g.

interface HTMLCustomElement {
  id: string // let's say it's configured to be first
  a: string
  max: string
  mid: string
  min: string
  z: string
  other: string // let's say it's configured to be last
}

I agree that customGroup is flexible enough to handle such a case, but maybe with some adaptation – given that:

• some "semantical" keys could be mixed with other keys;
• some key could sometimes miss, but I still expect the key to be placed where it's configured to be, e.g. a range key right after id (min, even if max is missing) – that's also the point of semantical sorting: semantics is not only "internal" (within a given group) but also "external" (should be known to other groups as well);
• some groups could also theoretically have an infinite number of elements (even if they actually have a finite one);

That's why I propose a solution which is not limited to useConfigurationIf: allElementNamesMatchPattern value:

[
  {
    groups: ['rgb'],
    customGroups: [
      {
        groupName: 'rgb',
        elementNamePattern: '^r|g|b$',
        internalGroupOrder: ['r', 'g', 'b'],
      },
    ],
  },
],

so that this:

[
  {
    groups: ['id', 'range', 'unknown', 'other'],
    customGroups: [
      {
        groupName: 'id',
        elementNamePattern: '^id$',
      },
      {
        groupName: 'range',
        elementNamePattern: '^(min|max)',
        internalGroupOrder: ['^min', '^max'],
      },
      {
        groupName: 'other',
        elementNamePattern: '^other$',
      },
    ],
  },
],

would result in this:

interface HTMLCustomElement {
  id: string
  minIndoorTemperature: string
  minOutdoorTemperature: string
  maxIndoorTemperature: string
  a: string
  z: string
  other: string
}

and this:

[
  {
    groups: ['id', 'range', 'unknown', 'other'],
    customGroups: [
      {
        groupName: 'id',
        elementNamePattern: '^id$',
      },
      {
        groupName: 'range',
        elementNamePattern: '^(min|max)',
        internalGroupOrder: ['IndoorTemperature$', 'OutdoorTemperature$'],
      },
      {
        groupName: 'other',
        elementNamePattern: '^other$',
      },
    ],
  },
],

in this:

interface HTMLCustomElement {
  id: string
  minIndoorTemperature: string
  maxIndoorTemperature: string
  minOutdoorTemperature: string
  a: string
  z: string
  other: string
}

What do you think @hugop95?

[hugop95]

@OlivierZal

I like your proposal a lot, I think that the complexity justifies implementing it as another issue (considering that my proposal and yours are independent).

You are essentially adding another layer of grouping inside a group. Rather than adding a internalGroupOrder attribute that is limited to name pattern matching, we can simply re-use groups:

Your last example could become

interface HTMLCustomElement {
  id: string
  minIndoorTemperature: string
  maxIndoorTemperature: string
  minOutdoorTemperature: string
  a: string
  z: string
  other: string
}

[
  {
    groups: ['id', 'range', 'unknown', 'other'],
    customGroups: [
      {
        groupName: 'indoor', // Only used within the `range` group
        elementNamePattern: 'IndoorTemperature$'',
      },
      {
        groupName: 'outdoor', // Only used within the `range` group
        elementNamePattern: 'OutdoorTemperature$'',
      },
      {
        groupName: 'id',
        elementNamePattern: '^id$',
      },
      {
        groupName: 'range',
        elementNamePattern: '^(min|max)',
        groups: ['indoor', 'outdoor'],
      },
      {
        groupName: 'other',
        elementNamePattern: '^other$',
      },
    ],
  },
],

This is a bit related to #68, where users want to colocate things together.

[OlivierZal]

@hugop95, you got my point, I think we are on the same page 😊

[hugop95]

At first glance unfortunately, I don't think that's not something we can easily add, this will deserve its own issue 🙂

[akibarika]

Thank you @hugop95 & @OlivierZal !!

I've just updated to the latest version, 4.2.0, but it seems to not be working.

Value {"groups":["r","g","b"],"customGroups":{"r":"r","g":"g","b":"b"},"useConfigurationIf":{"allNamesMatchPattern":"^r|g|b$"}} should NOT have additional properties.

It looks like the change hasn’t been included in the latest release yet.

[hugop95]

The feature hasn't been released yet indeed. It will be here in 4.3.0 soon.

[OlivierZal]

And thank only @hugop95, he did the whole work!

[h0adp0re]

Thanks for this feature, it looks like exactly what I need! I’m just curious about your release process. Do you have a timeline for when this might be published?

At my workplace, we typically publish features right after merging a PR. The thinking is — if time and energy have been spent on building a feature, it makes sense to make it available as soon as possible for everyone to use. It seems to help keep things moving smoothly, but I understand there are different approaches depending on the project.

[hugop95]

@h0adp0re The release process is handled by @azat-io, who can better explain the approach for this project.

In general:

• Critical hotfixes are released ASAP.
• Low-impact bugs and features tend to be grouped together in a release. There is another big feature about to be merged, so both features might end up in the same release.
• I think you can expect the release to be shipped by the end of the week.

[h0adp0re]

@hugop95 Wow, great job on the alphabet. And thanks for the outline.

I've noticed this feature grouping behavior in other open-source projects before and I have to say I don't quite get it 😄 — what if the feature being waited after takes several weeks more to refine? I am not here to argue or anything, just curious about the rationale behind the indeterminate waiting.

[azat-io]

@h0adp0re Hello! I will publish the release today

[azat-io]

Added in a3ee3ff.
Released in v4.3.0.

[h0adp0re]

Thank you very much!