feat: add IsX/IfX types for any/never/unknown

[tommy-mitchell]

Closes #129.

Adds IsAny, IfAny, etc. types:

import type {IsAny, IfAny} from 'type-fest';

type ShouldBeTrue = IsAny<any>;
//=> true

type ShouldBeFalse = IfAny<''>;
//=> false

type ShouldBeNever = IfAny<any, never, 'not-never'>;
//=> never

The IfX types are defined using the pattern mentioned in #129 (comment):

// source/if-any.d.ts

export type IfAny<T, TypeIfAny = true, TypeIfNotAny = false> = (
  IsAny<T> extends true ? TypeIfAny : TypeIfNotAny
);

Marked draft as concrete use cases are needed for documenting the types.

Info about a blocker that has been resolved

Marked draft as concrete use cases are needed for documenting the types, and a test can't pass without tsdjs/tsd#173:

// test-d/if-any.ts

expectError<IfAny>(anything);

// reports:
// test-d\if-any.ts:25:12
//   ✖  25:0   Expected an error, but found none.
//   ✖  25:12  Generic type IfAny requires between 1 and 3 type arguments.

[sindresorhus]

Marked draft as concrete use cases are needed for documenting the types, and a test can't pass without tsdjs/tsd#173:

tsd update is out.

[tommy-mitchell]

I'm aware that the README descriptions of the IfX types don't match their doc comments. What verbiage should we go with here? I think that this library as a whole could do with more consistent definitions (maybe a xo rule or something could help with that, especially if a README generator is implemented later).

Other than that, this PR is ready for review I think.

[sindresorhus]

What are your thoughts on subsuming the if/else functionality into the Is types? Like what's proposed in #544

[tommy-mitchell]

I like the explicitness of IfX<SomeType, DoThis, DoThat>, but I think it might become unwieldy if we add an IfX type for every IsX type added (for example, the IsXLiteral types).

[sindresorhus]

I think we should be consistent though. So either we add If types for everything or we don't. Otherwise, we'll end up having to make arbitrary decisions about when it makes sense to add a If type or not.

[sindresorhus]

On the other hand, I do also like the readability of If...

[tommy-mitchell]

I think the only real problem comes with documentation - there's a lot more noise if every IsX type is followed by an IfX type. Maybe there could be a section that explains the differences, then each IsX type could mention an alternative IfX type.

Something like (with more explanation):

---

IsX vs. IfX

For every IsX type, there is an associated IfX type that can help simplify conditional types:

import type {IsAny, IfAny} from 'type-fest';

type ShouldBeTrue = IsAny<any> extends true ? true : false;
//=> true

type ShouldBeFalse = IfAny<'not any'>;
//=> false

type ShouldBeNever = IfAny<'not any', 'not never', never>;
//=> never

Type Guards

• IsAny - Returns a boolean for whether the given type is any. (Alternative: IfAny)
• IsNever - Returns a boolean for whether the given type is never. (Alternative: IfNever)
• IsUnknown - Returns a boolean for whether the given type is unknown. (Alternative: IfUnknown)

[sindresorhus]

Can you do https://github.com/sindresorhus/type-fest/pull/563/files#r1127160534 in this PR?

[bjesuiter]

I'm coming from the question at Twitter by sindresorhus.

I think, I didn't get the difference you meant with IsX and IfX, yet.

My Thoughts:

Isn't IfX the more generalized variant of IsX?
As written before, IsAny seems to me like a shortcut for IfAny<true,false>.

I personally would be fine to having a single IsX type with the functionality of IfX baked in.
As

IsAny<any> => true/false 
IsAny<any, 'type-when-true','type-when-false'> 

I see a small problem in discoverability when only having the IsX type, bc. When I search for an IfX type It would not auto-import and I would've to look into docs.

But I also see the maintenance gets a little unwieldy when adding an IfX for every IsX.

Suggestion: What are your thoughts on simply having these both, but with the same functionality? IfX would then practically be an alias of IsX for all types, simply for discoverability.

[sindresorhus]

@tommy-mitchell I like your proposal. Lets go with that.

[sindresorhus]

Suggestion: What are your thoughts on simply having these both, but with the same functionality? IfX would then practically be an alias of IsX for all types, simply for discoverability.

I think it could be confusing if IfX was aliased to IsX as the user may think it's a mistake.

[tommy-mitchell]

Added the readme note and moved the IsT types I added to a Type Guard category. Should we add IfT types for the other IsT types in this PR, or should that be separate?

[sindresorhus]

Should we add IfT types for the other IsT types in this PR, or should that be separate?

Separate

[sindresorhus]

Can you check if this is linkified in VS Code? We need a syntax that like to the type correctly so users can just click through.

[tommy-mitchell]

This hovers correctly in source files, but the rendered hover text for IfAny does not link to IsAny.

Using @see {@link IsAny} does linkify in the hover text, but it seems to go to the import statement in if-any.d.ts.

Related, most type-fest types with an @see don't use the @link syntax, so they're not correct either.

[sindresorhus]

How about only using @link? https://devblogs.microsoft.com/typescript/announcing-typescript-4-3/#jsdoc-link-tags

[tommy-mitchell]

I think having @see makes it clearer.

With:

Without:

[sindresorhus]

In case you missed it: #564 (comment)