Better handling of non-literal types

[jly36963]

Supporting non-literal types

Problem

Differentiating between string and string literal

The utilities in string-ts were written with the literal use case in mind.
Passing non-literal types (eg: string) as arguments will likely return bad types.

import { Length } from "string-ts";

type t1 = Length<"abc">; // 3
type t2 = Length<string>; // 1 (Oops, should be `number`)
type t3 = Length<`abc${string}`>; // 4 (Oops, should be `number`)

The Length<string> issue can be fixed by updating the type definition like so.

// Before
export type Length<T extends string> = Split<T>["length"];

// After
export type Length<T extends string> = string extends T
  ? number
  : Split<T>["length"];

We know type T is string if T extends string and string extends T.
This update was made to many of the string-ts type utilities in this PR.

The problem is, there are other string types that are:

• more specific than string
• less specific than a literal

Examples: template strings and intrinsic string manipulation types.
This means our ability to gracefully handle non-literal types becomes more complex.

As of right now, we only handle string and literal, none of the in-between types.
(More on this below.)

TS built-in casing utils

The Intrinsic String Manipulation Types in TypeScript are only meant to work with string literals, not string type.

Source code for Uppercase:

/**
 * Convert string literal type to uppercase
 */
type Uppercase<S extends string> = intrinsic;

Uppercase, Lowercase, Capitalize, and Uncapitalize are all defined similarly.
The 'intrinsic' keyword is used to declare compiler-provided intrinsic types.
When using these utilities with string, it can't be reduced any further.

type UpperLiteral = Uppercase<"abc">; // "ABC"
type UpperString = Uppercase<string>; // Uppercase<string>

There is value in Uppercase<string> not being reduced to string.
It preserves a more narrow scope of possible values.(See below.)

let upperString: Uppercase<string>
// No issues
upperString = "ABC";
// Type 'string' is not assignable to type 'Uppercase<string>'
upperString = "abc";

Casing in string-ts

Context:

There are many casing-related type utilities in string-ts.
Most of the type utilities in the library are made from lower-level, piped utilities.

CamelCase looks something like the following when you drill into the underlying utilities:

type CamelCase<T extends string> = Uncapitalize<Join<PascalCaseAll<Words<T>>>>;

Under the hood, CamelCase uses Capitalize, Uncapitalize, and Lowercase.

As I said earlier, we currently handle string and literal types, not the ones between.
Any piping of utilities -- whether internally (like the CamelCase example above) or externally (eg: Length<CamelCase<T>>) -- are not handled properly unless the type falls neatly into the string or string literal bins.

Potential Solutions

Use verbose types to determine non-literals

We could use a helper to better differentiate literals from non-literals.
Here is an example where I modify Length to better handle the other types.
Note: this solution better handles intrinsic types, but additional changes would need to be made to support template string types.

/**
 * Returns true if the string is not a literal
 */
type NotLiteralString<T extends string> = string extends T
  ? true
  : Uppercase<string> extends T
  ? true
  : Lowercase<string> extends T
  ? true
  : Uncapitalize<string> extends T
  ? true
  : Capitalize<string> extends T
  ? true
  : false;

/**
 * Gets the length of a string.
 */
export type Length<T extends string> = NotLiteralString<T> extends true
  ? number
  : Split<T>["length"];

namespace LengthTests {
  type t1 = Expect<Equal<Length<"some nice string">, 16>>;
  type t2 = Expect<Equal<Length<Uppercase<"some nice string">>, 16>>;
  type t3 = Expect<Equal<Length<string>, number>>;
  type t4 = Expect<Equal<Length<Uppercase<string>>, number>>;

  // Fails, would need to iterate through and check each char if it's string
  type t5 = Expect<Equal<Length<Uppercase<`abc${string}`>>, number>>;
}

Wrap the built-in TS string types to reduce complexity

In this PR, I made types that override the built-in casing utilities' behavior around intrinsic types, and it makes composite/piped types like CamelCase more straightforward.

/**
 * Uppercases if string literal, else string
 */
export type Upper<T extends string> = string extends T ? string : Uppercase<T>;

Upper<"abc">; // 'ABC'
Upper<string>; // string

Uppercase<"abc">; // 'ABC'
Uppercase<string>; // Uppercase<string>

This approach keeps the casing-related types in string-ts much less verbose -- as they have less string type categories to consider -- but it is a fundamental deviation from TS behavior, and it loses type information.

Other

...

[gustavoguichard]

I got a solution to verify only string literals:

type IsStringLiteral<T> = T extends string
  ? string extends T
    ? false
    : Uppercase<T> extends Uppercase<Lowercase<T>>
    ? Lowercase<T> extends Lowercase<Uppercase<T>> ? true : false
    : false
  : false

type A = Expect<Equal<true, IsStringLiteral<'foo'>>>
type B = Expect<Equal<true, IsStringLiteral<Uppercase<'foo'>>>>
type C = Expect<Equal<false, IsStringLiteral<Uppercase<`foo${string}`>>>>
type D = Expect<Equal<false, IsStringLiteral<`foo${string}`>>>
type E = Expect<Equal<false, IsStringLiteral<`foo${number}`>>>
type F = Expect<Equal<false, IsStringLiteral<string>>>

Check out this playground

@jly36963 do you think that will help making the first solution work?

[jly36963]

Yeah, it passes all the checks I can think of

[jly36963]

Talked with @gvergnaud, and he said something along the lines of

Use [T] extends string ? string extends [T] ? true : false : false. The unary tuple type is to avoid the conditional type from being distributed over T if T is a union type.

Sure enough, the following test

Expect<Equal<false, IsStringLiteral<'abc' | Uppercase<string>>>>

only passes if I update IsStringLiteral like so

type IsStringLiteral<T> = [T] extends [string]
  ? [string] extends [T]
    ? false
    : Uppercase<T> extends Uppercase<Lowercase<T>>
    ? Lowercase<T> extends Lowercase<Uppercase<T>>
      ? true
      : false
    : false
  : false

Without that change, the condition is distributed, which results in boolean type, rather than the literal false

IsStringLiteral<'abc' | Uppercase<string>>
true | false
boolean

[gustavoguichard]

Awesome!