Template Literal Types with fixed or limited Length

[MicahZoltu]

Suggestion

Provide a way for a user defined template literal type to be a fixed length or limited length.

🔍 Search Terms

Template Literal Type Length

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

An intrinsic string manipulation type similar to Uppercase<StringType>, but that results in a fixed length string with provided substring union repeated n times.

type Hex = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '0' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F'
type HexHash = `0x${FixedLength<Hex, 64>}`

📃 Motivating Example

const hexHash = '0xbaadf00dbaadf00dbaadf00dbaadf00dbaadf00dbaadf00dbaadf00dbaadf00d'
const hexAddress = '0xbaadf00dbaadf00dbaadf00dbaadf00dbaadf00d'
declare function wantsHash(hash: `0x${string}`): void
declare function wantsAddress(address: `0x${string}`): void
wantsHash(hexHash) // ok
wantsHash(hexAddress) // should fail
wantsAddress(hexHash) // should fail
wantsAddress(hexAddress) // ok

💻 Use Cases

A lot of the work I do deals with byte arrays that are passed around as strings (because they are often pulled directly out of a JSON payload). These usually have a well defined length and a consistent prefix. For example:

const hexHash = '0xbaadf00dbaadf00dbaadf00dbaadf00dbaadf00dbaadf00dbaadf00dbaadf00d'
const hexAddress = '0xbaadf00dbaadf00dbaadf00dbaadf00dbaadf00d'

I would like to be able to write functions that are constrained to accept only strings of a certain length, and ideally only made up of certain characters. Currently, the best I can do is type as 0x${string}, but this doesn't allow me to differentiate between a 20 byte hex string and a 32 byte hex string which are effectively different types in this context and are incompatible with each other.

[MicahZoltu]

Possibly out of scope for this issue (or possibly in scope) it would also be useful to support arbitrary length, so one could have a "hex encoded data" type which allows a certain subset of characters but can be any length. This would be used for dynamic length byte arrays encoded as a hex string.

[MartinJohns]

Related: #41160

[RyanCavanaugh]

With high confidence, the only way we'd address this scenario is through regex types. It wouldn't make sense to have template strings have three categories (finite, big-but-finite, and infinite) since that middle one would be very difficult to reason about as to how it relates in unions

[MicahZoltu]

Would it be reasonable to create an issue for unbounded length like 0x${hexCharacters} where hexCharacters is something like Repeated<Hex>? Or would that also be only likely to show up with support for regex types?

[RyanCavanaugh]

You can log it but I don't think it'd happen. The intended use case for template string literals was and still is property name manipulation and extraction, not data format validation of runtime strings. Regexes are much better suited for that.

[typescript-bot]

This issue has been marked as a 'Duplicate' and has seen no recent activity. It has been automatically closed for house-keeping purposes.