The keyword "is" in the return type of TypeScript function

Question

In VSCode's source file, there are some functions with a particular return type specification, like this:

export function isString(str: any): str is string {
  if (typeof (str) === _typeof.string || str instanceof String) {
    return true;
  }

  return false;
}

So I wonder what is the purpose of "str is string" instead of just writing "boolean".

Can we use "str is string" and the like in any other circumstances?

Answer 1

That is called User-Defined Type Guards.

Regular type guards let you do this:

function fn(obj: string | number) {
    if (typeof obj === "string") {
        console.log(obj.length); // obj is string here
    } else {
        console.log(obj); // obj is number here
    }
}

So you can use typeof or instanceof, but what about interfaces like this:

interface Point2D {
    x: number;
    y: number;
}

interface Point3D extends Point2D {
    z: number;
}

function isPoint2D(obj: any): obj is Point2D {
    return obj && typeof obj.x === "number" && typeof obj.y === "number";
}

function isPoint3D(obj: any): obj is Point2D {
    return isPoint2D(obj) && typeof (obj as any).z === "number";
}

function fn(point: Point2D | Point3D) {
    if (isPoint2D(point)) {
        // point is Point2D
    } else {
        // point is Point3D
    }
}

(code in playground)