TypeScript generic type predicate

I'm going to address your "update 2" code, but the suggestion should apply to the general issue. I think the main situation here is that isShape(s, k) should only act as a type guard on s if s isn't already a narrower type than k is. Otherwise you don't want isShape(s, k) to do anything to the type of s, since in neither the true or the false case is anything of relevance implied (or at least nothing that can be represented in the type system).

Therefore my suggestion is to overload the function so that it is only a user-defined type guard in the "right" situations, like this:

type Kind = "circle" | "square";

// isShape(s, k) should only act as a type guard if s is not of a narrower type than k
function isShape<K extends Kind, S extends [S] extends [K] ? never : string>(
  s: S,
  kind: K
): s is S & K;
// otherwise, isShape(s, k) is not a type guard but just a boolean test
function isShape(s: string, kind: Kind): boolean;
function isShape(s: string, kind: Kind): boolean {
  return s === kind;
}

That first overload signature works because S is constrained to the conditional type [S] extends [K] ? : never : string. If S is inferred by the value of s to be same or narrower type as that of kind, then the constraint becomes S extends never, which will generally fail, and the compiler will try the next overload signature (which will succeed). Otherwise, if S is inferred by the value of s to be a wider or different type, the constraint becomes S extends string and the inference will succeed (assuming S is assignable to string) and the function will act as a type guard.

Now let's see how it behaves:

declare const s: string;
declare const kind: Kind;
declare let shape: Kind;

// Use of type guard on string against Kind literal:
if (isShape(s, "circle")) {
  const x: "circle" = s; // s is "circle"
} else {
  const x: typeof s = "someString"; // s is string
}

// Use of type guard on Kind against Kind literal:
if (isShape(shape, "circle")) {
  const x: "circle" = shape; // shape is "circle"
} else {
  const x: "square" = shape; // shape is "square"
}

// Use of type guard on string against Kind:
if (isShape(s, kind)) {
  const x: Kind = s; // s is Kind
} else {
  const x: typeof s = "someString"; // s is string
}

// Use of type guard on Kind against Kind:
if (isShape(shape, kind)) {
  const x: Kind = shape; // shape is Kind (no narrowing has taken place)
} else {
  const x: Kind = shape; // shape is Kind (no narrowing has taken place)
}

I think that covers all your use cases. Does that work?

It would be simpler, though, if you just don't use isShape(s, k) when you already know that s is of a narrower type than k. When you use user-defined type guards for a test where there are likely false negatives (where the false return does not imply anything new about the type of the guarded parameter), you are shooting yourself in the foot. The above overload definition tries to make isShape() disarm itself when you point it at your foot, but it's just easier for all involved not to require such things. You could use isShape(s, k) when s is wider than k, and otherwise just use s === k or some other non-type-guard test.

But in any case, I hope this helps. Good luck!

Link to code

UPDATE

You've expanded Kind to three literals, and I see now that my thoughts about which situations are the "right" ones to narrow were not completely correct. Now my plan of attack is for isTriangle(t, k) is that it should be a regular type guard only when k is a single string literal type and not a union at all. This is detectable by the type system, but it's not pretty:

type _NotAUnion<T, U> = T extends any
  ? [U] extends [T] ? unknown : never
  : never;

type IsSingleStringLiteral<
  T extends string,
  Y = T,
  N = never
> = string extends T ? N : unknown extends _NotAUnion<T, T> ? Y : N;

If k is a union of types, then you should only narrow in the true case and not in the false case. This is a one-sided user-defined type guard, which doesn't officially exist in TypeScript. However, @KRyan notes that you can emulate a one-sided type guard by making the guarded type narrow to a nominal or nominal-like type. I'll use branding, like type BrandedFoo = Foo & {__brand: "Foo"}... where I don't expect the __brand property to actually exist at runtime, but the compiler thinks it's there, and can use it to distinguish Foo from BrandedFoo. If the type guard narrows from Foo to BrandedFoo on the true case, then in the false case it will remain Foo because Exclude<Foo, BrandedFoo> is just Foo.

I'm still using overloads to determine which type of type guard we want, based on the type of kind:

type TriangleKind = "equilateral" | "isosceles" | "scalene";

function isTriangle<K extends IsSingleStringLiteral<K, TriangleKind, never>>(
  triangle: string,
  kind: K
): triangle is K;
function isTriangle<K extends TriangleKind>(
  triangle: string,
  kind: K
): triangle is K & { __brand: K };
function isTriangle(triangle: string, kind: TriangleKind): boolean {
  return triangle == kind;
}

And let's take it through its paces:

declare const triangle: "equilateral" | "isosceles" | "scalene";
declare const twoKind: "equilateral" | "isosceles";
declare const allKind: "equilateral" | "isosceles" | "scalene";
declare const s: string;

// Use of type guard on string against TriangleKind literal:
if (isTriangle(s, "equilateral")) {
  const x: "equilateral" = s; // s is "equilateral"
} else {
  const x: typeof s = "someString"; // s is string
}

// Use of type guard on string against union of two TriangleKind types:
if (isTriangle(s, twoKind)) {
  const x: "equilateral" | "isosceles" = s; // s is "equilateral" | "isosceles"
} else {
  const x: typeof s = "someString"; // s is still string, no narrowing
}

// Use of type guard on string against TriangleKind:
if (isTriangle(s, allKind)) {
  const x: TriangleKind = s; // s is TriangleKind
} else {
  const x: typeof s = "someString"; // s is still string, no narrowing
}

// Use of type guard on TriangleKind against TriangleKind literal:
if (isTriangle(triangle, "equilateral")) {
  const x: "equilateral" = triangle; // triangle is "equilateral"
} else {
  const x: "isosceles" | "scalene" = triangle; // triangle is "isosceles" | "scalene"
}

// Use of type guard on TriangleKind against union of two TriangleKind types:
if (isTriangle(triangle, twoKind)) {
  const x: "equilateral" | "isosceles" = triangle; // triangle is "equilateral" | "isosceles"
} else {
  const x: typeof triangle = allKind; // triangle is still TriangleKind, no narrowing
}

// Use of type guard on TriangleKind against TriangleKind:
if (isTriangle(triangle, allKind)) {
  const x: TriangleKind = triangle; // triangle is TriangleKind
} else {
  const x: typeof triangle = allKind; // triangle is still TriangleKind, no narrowing
}

This all looks mostly right. Note that in several of the true branches the type of the narrowed thing is branded, so you get ("isosceles" & {__brand: "isosceles"}) | ("scalene" & {__brand: "scalene"}) instead of "isosceles" | "scalene". You can mostly ignore those brands, but they are kind of ugly.

So there you go. Complicated and messy, best I've got.

Link to code

Good luck again!