feat(macro): make select macro choices strictly typed

[MikaelSiidorow]

Description

Closes #2214, implementing stricter types for the options in the select macro.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Could potentially be breaking change if you have runtime errors in your code at the moment, and are running strict typechecking?
• Documentation update
• Examples update

Fixes #2214

Checklist

• I have read the CONTRIBUTING and CODE_OF_CONDUCT docs
• I have added tests that prove my fix is effective or that my feature works
• I have added the necessary documentation (if appropriate)

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
js-lingui	✅ Ready (Inspect)	Visit Preview	May 9, 2025 6:56am

[github-actions]

size-limit report 📦

Path	Size
packages/core/dist/index.mjs	2.91 KB (0%)
packages/detect-locale/dist/index.mjs	618 B (0%)
packages/react/dist/index.mjs	1.35 KB (0%)

[timofei-iatsenko]

Thanks! Basically other is a required case from icu spec, it's a catch all option which should always be presented. I would like to see the test case where input type does not specify the other in itself, because this is most likely would be 99% of cases:

type Gender = "male" | "female";

const genger: Gender = 'male'

expectType<string>(
  select(gender, {
    male: "he",
    other: "female",
  })
)

The cases for the select are not exhaustive, means you can skip one, and it should fallback to the other

[MikaelSiidorow]

Thanks! Basically other is a required case from icu spec, it's a catch all option which should always be presented. I would like to see the test case where input type does not specify the other in itself, because this is most likely would be 99% of cases:

I will add another test case, which doesn't contain other in the set of options!

The cases for the select are not exhaustive, means you can skip one, and it should fallback to the other

If that's the case, should this instead be a new optional macro or option to enable exhaustiveness? I find the use case where it is exhaustive more common in our real world usage scenario than not being exhaustive

^ I guess it could be similar to selectOrdinal --> selectExhaustive / selectStrict / selectEnum?

Note to self:

• This should also be implemented to the React <Select> macro component

[timofei-iatsenko]

If that's the case, should this instead be a new optional macro or option to enable exhaustiveness? I find the use case where it is exhaustive more common in our real world usage scenario than not being exhaustive

I'm not sure about this one, all macro is just a syntax sugar about ICU expressions and should follow theirs semantics, adding a new macro with a different behavior contradict with this architecture rule.

The pattern string for SelectFormat allows user-defined keywords that match the pattern [a-zA-Z][a-zA-Z0-9_-]* as well as the predefined keyword "other". The keyword "other" must occur in the pattern string, or the error U_DEFAULT_KEYWORD_MISSING is returned. For comparison, the PluralFormat pattern allows as keywords only the set of tags defined in UTR 35, Unicode Locale Data Markup, section C. 11, Language Plural Rules.

https://icu.unicode.org/design/formatting/select

If you create a exhaustive rule that means the user will have to specify one of the options twice:

type Gender = "male" | "female";

const genger: Gender = 'male'

expectType<string>(
  selectExhaustive(gender, {
    male: "he",
    female: "female",
    other: "female", // <-- still should be there even in the exhaustive version
  })
)

I understand your intention to make it 100% type safe and help to catch bugs when a new option added to the input type, but the underlying ICU Select was designed not considering this case.

Kinda from the DX perspective, I think ergonomically would be nice to implement exhaustive / non-exhaustive based if the other case presented or not. Similarly, how pattern matching works in languages as Rust

type SelectOptionsExhaustive<T extends string = string> = {
  [key in T]: string
}

type SelectOptionsNonExhaustive<T extends string = string> =  {
  /** Catch-all option */
  other: string
} & {
  [key in T]?: string
}

type SelectOptions<T extends string = string> = SelectOptionsExhaustive<T> | SelectOptionsNonExhaustive<T>

But again this will contradict with the underlying ICU Select.

[MikaelSiidorow]

I dove into the details with ICU MessageFormat

• Looks like they have extensively discussed exhaustiveness and the fallback, and strictly decided to keep it as is
  (most recently 2025-03-10)
  • We should not require * if the variant keys exhaust all possibilities unicode-org/message-format-wg#603
  • Handling `other` vs. `*` for plural selectors unicode-org/message-format-wg#322

In my opinion the implementation in application code using Lingui could be more strict than the underlying specification, since the select options in the application code are (most often? / always?) in the source language. But the option to be less strict has to be kept there for translating to other languages.

I feel like using select for strictly typed enums might not be the right call, but instead a light wrapper could be better, like:

const scaleOptions = {
  linear5: msg`5-point scale`,
  binary: msg`Yes/no`,
  written: msg`Written`
} as const
// ...
<span>{scaleOptions[question.scale]}</span>

But this has the large drawback that it loses the context of these values being related to each other in the translation file.

If we implemented the approach where including other determines the strictness of the type-system, the other (or *) option would likely still have to be filled somehow.

I still kind of like the option for selectExhaustive, even if it straying away from the exact ICU MessageFormat, what do you think?

I am currently rocking a global type wrapper / overload for the select macro that implements the strict type-checking for exhaustiveness, while still keeping the other option (similarly to this PR, but explicitly defining the type param to use my overload)

[timofei-iatsenko]

First of all, thanks for digging into the topic. Second, let's check how the message format parser would behave if you will not specify other case in the message. I'm not particularly fan of the diverging from the spec, but i see a value in that. If the message format parser will not complain about this one we could simply make a version where other case is not specified at all. Or simply left other {} empty for the exhaustive version.

[MikaelSiidorow]

First of all, thanks for digging into the topic. Second, let's check how the message format parser would behave if you will not specify other case in the message. I'm not particularly fan of the diverging from the spec, but i see a value in that. If the message format parser will not complain about this one we could simply make a version where other case is not specified at all. Or simply left other {} empty for the exhaustive version.

From quick testing ignoring the other value (leaving completely undefined) didn't seem to break anything at least when used with React through the Vite plugin. Should that be the approach then, adding conditional types to select and <Select> macro:

1. If other is defined, allow for loose typing and missing keys
2. If other is not defined strictly validate keys

[timofei-iatsenko]

@MikaelSiidorow

Even if the parser used in the lingui is not crashing, most likely that wouldn't be a case in TMS. Example above from the message format online editor. So omitting other could result in breaking compatibility with different vendors.

It is better to left it empty. Also, i suppose this change might be a breaking for the users, since typing become stricter. But we can ignore it, possibly

[MikaelSiidorow]

It is better to left it empty.

Makes sense. I guess this also needs runtime code changes, not only types. I can check this later

Also, i suppose this change might be a breaking for the users, since typing become stricter. But we can ignore it, possibly

Yep, noted in the description. I guess it needs to be decided whether to treat typechecking errors as breaking or not

[timofei-iatsenko]

oh, that means SWC plugins changes would also be required

[MikaelSiidorow]

I see, I guess that's in a different repo 👀

[MikaelSiidorow]

Here's my attempt at implementing the same behavior on SWC side:
lingui/swc-plugin#157

Let me know if it's going totally in the wrong direction

[timofei-iatsenko]

Looks good to me. We also need to update docs for these macros, just with few sentences about this new behaviors

[timofei-iatsenko]

Since there is a changes done to the macro, you need to add a test for the macro itself covering this change

[MikaelSiidorow]

Since there is a changes done to the macro, you need to add a test for the macro itself covering this change

Makes sense! Thanks for being super responsive. I have been a bit busy, but I'll update this PR later

[MikaelSiidorow]

@timofei-iatsenko

Since there is a changes done to the macro, you need to add a test for the macro itself covering this change

Finally got back to this, sorry for the delay! I have added a test for the new macro functionality