feat: add IsXLiteral types

[tommy-mitchell]

Closes #541, closes #339.

Adds types to check if a given type is a Primitive literal:

• IsLiteral
• IsStringLiteral
• IsNumericLiteral
• IsBooleanLiteral
• IsSymbolLiteral
• IsNullLiteral
• IsUndefinedLiteral

Marking as draft as I still need to add documentation comments to the types.

Info About Removed Types

I'm not sure if it's possible to check for null or undefined literals without also allowing their values, e.g:

import type {IsNullLiteral} from 'type-fest';

declare const _null: null;

type ShouldBeTrue = IsNullLiteral<null>;
//=> true

type ShouldBeFalse = IsNullLiteral<typeof _null>;
//=> true

Marking as draft as I still need to figure out the above issue and add documentation comments to the types. Currently the test cases for _null and _undefined values are commented out.

[tommy-mitchell]

Thinking about it some more, I’m not sure if there’s even really a reason to check for null or undefined literals, beyond completeness sake. And the more I think about it, I don’t think it’s possible to either.

[sindresorhus]

See https://github.com/sindresorhus/type-fest/pull/562/files#diff-e50dff1575d9cd1e723da9f89c4f438d9b5e9c3120d93a41a8139a2f869d05e4R1 for inspiration for docs comments.

[sindresorhus]

Lets just drop null and undefined literal. I cannot think of any use-case for them.

[tommy-mitchell]

Should the category be Utilities?

[tommy-mitchell]

Had to force push because I committed on the wrong user.

[tommy-mitchell]

Currently, IsLiteral has a Primitive type constraint:

type IsLiteral<T extends Primitive> = // ...

This means that testing types that aren't assignable to Primitive (e.g. unknown) is a compiler error:

type ShouldBeFalse = IsLiteral<unknown>;
//=> Type 'unknown' does not satisfy the constraint 'Primitive'.

The other IsXLiteral types don't have this constraint. Should this be removed?

[tommy-mitchell]

Seems like these aren't being used as type guards either. The following errors at Capitalize<T>:

type CapitalizedString<T> = IsStringLiteral<T> extends true ? Capitalize<T> : string;

// (type parameter) T in type CapitalizedString<T>
// Type 'T' does not satisfy the constraint 'string'. ts(2344)

Not sure what I'm doing wrong.

[tommy-mitchell]

Currently just missing examples for IsBooleanLiteral and IsSymbolLiteral. From searching on GitHub (the new code search is actually quite nice), the only real uses I've seen for the two are when building parsers/ASTs.

[tommy-mitchell]

All types are now documented with examples.

[sindresorhus]

Should the category be Utilities?

👍 And maybe also a new one: Is or Type Guard?

[tommy-mitchell]

👍 And maybe also a new one: Is or Type Guard?

IsType?

[sindresorhus]

IsType?

Makes it sound like it's a special type, not a type of type. Let's go with Type Guard for now.

[sindresorhus]

Looks great :)