Narrowing function return type with type guards

Question

I have a TypeScript function that parses some JSON and runs it through a type guard to ensure that the data was valid so that the rest of the compile-time code knows that it's dealing with an object that actually abides by the expected interface.

However, I'm having a hard time making TypeScript enforce that a type guard has been run. Apparently JSON.parse returns any, which is assignable to any other type and therefore checks, even if I specify a non-any return type.

const validPerson = `{"firstName": "John", "lastName": "Doe"}`;
const invalidPerson = `{"foo": 123}`;

interface Person {
    firstName: string;
    lastName: string;
}

interface PersonGetter {
    (json: string): Person | undefined;
}

function isPerson(o: any): o is Person {
    return typeof o.firstName === "string" && typeof o.lastName === "string";
}

// BAD: Type checks, but it's overly permissive. `JSON.parse` could return anything.
const getPerson1: PersonGetter = (json) => {
    const o = JSON.parse(json);
    return o;
}

// GOOD (kinda): Requires type guard to pass.
// `unknown` requires TS 3, which is fine in general, but bad for me.
// Also, I feel like having to remember to case the return from `JSON.parse` is a responsibility the programmer shouldn't bear.
const getPerson2: PersonGetter = (json) => {
    const o: unknown = JSON.parse(json);
    if (isPerson(o)) {
        return o;
    } else {
        return undefined;
    }
}

// GOOD (kinda): Requires type guard to pass. Works in TS 2.8.
// Still, not great that I have to cast the return value from `JSON.parse`, but I could probably work around that.
type JSONPrimitive = string | number | boolean | null;
type JSONValue = JSONPrimitive | JSONObject | JSONArray;
type JSONObject = { [member: string]: JSONValue };
interface JSONArray extends Array<JSONValue> {}

const getPerson3: PersonGetter = (json) => {
    const o: JSONValue = JSON.parse(json);
    if (isPerson(o)) {
        return o;
    } else {
        return undefined;
    }
}

TypeScript Playground link

Option 3 would work for me, but it uses proposed JSON types that are still up for debate and still puts the responsibility on the implementor (who could just as easily not use a type guard at all and still think they're abiding by the interface).

It would appear that JSON.parse returning any is the source of my problem here. I'm already running in strict mode, but it would appear that it still allows something explicitly typed as any to be expanded to the explicit return type of the function.

Is there another way to tell TypeScript that the return value of the function must be the return type specified in the interface that it implements and not any?

Answer 1

const validPerson = `{"firstName": "John", "lastName": "Doe"}`;
const invalidPerson = `{"foo": 123}`;

interface Person {
    firstName: string;
    lastName: string;
}

function isPerson(o: any): o is Person {
    return typeof o.firstName === "string" && typeof o.lastName === "string";
}

function getPerson(json: string) {
    const o = JSON.parse(json);

    if (isPerson(o)) {
        return o;
    } else {
        return undefined;
    }
}

Minimal playground. Make sure to check turn on strictNullChecks

Answer 2

JSON is declared in lib.es5.d.ts. Create your own type definition file in your project and declare a new global JSON instance with a definition that returns a dummy type from parse() instead of any.

This way you will have to use a guard or cast the result in order to avoid a compilation error in functions and methods that have an explicitly defined return type.

interface JSONStrict extends JSON {
    /**
      * Converts a JavaScript Object Notation (JSON) string into an object.
      * @param text A valid JSON string.
      * @param reviver A function that transforms the results. 
      * This function is called for each member of the object.
      * If a member contains nested objects, the nested objects are
      * transformed before the parent object is.
      */
    parse(text: string, reviver?: (key: any, value: any) => any): { _dummyProp?: void };
}
// overide lib.es5 declaration of JSON
declare const JSON: JSONStrict;

/* ... */
function parseAndThrowCompilationError(): Person {
    var result = JSON.parse('{ "x": 1}');
    return result; 
    // Type '{ _dummyProp?: void }' has no properties in common with type 'Person'
}

I added _dummyProp to the result because just using an object would match an interface with only optional properties and not throw an error.

... Honestly, this is a bit of a rig and I wonder if the effort is really worth it.