Allow custom guards to return non-boolean values, with conditional type results

[Nathan-Fenner]

Suggestion

Sometimes we want to write a guard function that doesn't return a boolean. For example,

type Success<T> = { ok: true, value: T }
type Fail = { ok: false, error: string }
type Result<T> = Success<T> | Fail

function showError<T>(result: Result<T>): string | null {
  if (result.ok) {
    return null;
  }
  return `Oops, something went wrong: ${result.error}`;
}

here, we render a Result<T> value into either a string error message, or return null if there's no error. This kind of pattern can be used in React, for example, where we could write

function Component() {
  const result: Result<number> = getResult();
  return <>{showError(result) ?? process(result.value)}</>;
}

However, if we try this code today, we get an error:

Property 'value' does not exist on type 'Result<number>'.

This makes sense, since tsc has no way of knowing that we're narrowing the value using showError.

Now, we can almost reach for a custom type guard. We can easily write:

function isError<T>(result: Result<T>): result is Fail {
  return !result.ok;
}

and using this function, we could write

function Component() {
  const result: Result<number> = getResult();
  return <>{isError(result) ? showError(result) : process(result.value)}</>;
}

because tsc now uses the isError custom type guard to narrow the type of result.

However, this means that we can't use showError to narrow our value. Especially if the arguments to isError/showError are larger or more complicated, this means we have a lot of data that needs to be kept in-sync in source, or we'll render the wrong error (we need to ensure that whenever we showError a value, it's the same as the value passed to isError).

Since our showError already provides enough context that narrowing is possible, ideally we'd be able to use it as-is by giving the compiler a hint about what its return types mean.

But we're limited by the fact that custom type guards must return boolean values.

---

The suggestion is to allow custom type guard conditions, such as the following:

function showError<T>(result: Result<T>): (result is Fail) ? string : null {
  if (result.ok) {
    return null;
  }
  return `Oops, something went wrong: ${result.error}`;
}

Here, the return type is now annotated as (result is Fail) ? string : null. This means that if result is Fail, then the function returns a string, otherwise, it returns a null.

So if we verify that showError(result) is null, then that means that result must not have been a Fail value, so we can narrow it to a Success<T>. This means that showError(result) ?? process(result.value) will now pass, since on the right hand side of ?? we are able to narrow showError(result) to null, which means that we can narrow result to Success<number> which has a .value field.

🔍 Search Terms

• custom type guard
• conditional type guard

We can sort of see this as a way to explicitly annotate (but not check) control-flow for functions as described in #33912 in much the way that custom type guards are used by tsc to narrow types, but the implementation is not really checked (other than that it returns a boolean).

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
  • This new syntax doesn't overlap with existing syntax, so this will have no affect on existing code. Avoiding ambiguity with regular conditional types, or custom type guards that narrow to conditional types is important, but the proposed syntax avoids any conflicts
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Custom type guard functions should optionally support conditional annotations in their return types, allowing them to return non-boolean types. A function can be annotated as:

function myCustomTypeGuard(x: ArgType): (x is SmallerArgType) ? Positive : Negative {
  ...
}

If the result of the function call myCustomTypeGuard(x) is ever narrowed so that the result doesn't overlap at all with Negative, then x is automatically narrowed to SmallerArgType.

If the result of the function call myCustomTypeGuard(x) is ever narrowed so that the result doesn't overlap at all with Positive, then x is automatically narrowed to exclude SmallerArgType.

The function's implementation is just checked to ensure that it returns Positive | Negative; just as with existing custom type guards, tsc ignores the actual logic used to decide whether the positive or negative value should be returned.

Essentially, the existing custom type guard function syntax (arg: T): arg is Blah is identical to the expanded form (arg: T): (arg is Blah) ? true : false.

📃 Motivating Example

import * as React from "react";

type Result<T> = { ok: true; value: T } | { ok: false; error: string };

// New syntax is here: conditional custom type guard annotation
function showError<T>(result: Result<T>): (result is Fail) ? string : null {
  if (result.ok) {
    return null;
  }
  return `Oops, something went wrong: ${result.error}`;
}

function getResult(): Result<number> {
  return null as any;
}
function process(x: number): string {
  return `the value is ${x}`;
}

function Component() {
  const result: Result<number> = getResult();
  return <>{showError(result) ?? process(result.value)}</>;
}

💻 Use Cases

This makes it easier to write flexible type-guards, such as the example above, especially for dealing with errors or processing "exceptional" cases.

It's possible to separately use a regular custom type guard function and then use a different function to process the result, but this can be redundant or error-prone, since you have to ensure that the two calls remain in sync with each other.

[fatcerberus]

If you're willing to throw exceptions, you can use asserts to do this today.

function showError(x: Fooey): asserts x is FooBar
{
    if (x instanceof FooBar) {
        fooBar(x);
    }
    else {
        throw TypeError("Not a foobar object");
    }
}

[Nathan-Fenner]

The goal here is to produce a new value and simultaneously enable narrowing based on that value, so asserts doesn't work for a similar reason, since functions with asserts have to be void, just like custom type guards must return a boolean.

[andrewbranch]

Closest thing to a duplicate is #31376 but the conditionality is an interesting distinction. #15048 also has a similar conditionality theme but is still about functions that return booleans at runtime.

I’ll leave this open as a suggestion but I have to say this seems incredibly complex, both to reason about and to implement.

then x is automatically narrowed to exclude SmallerArgType.

This is a problem in general without negated types. The compelling examples are discriminated unions, but I think it would get really confusing really fast if you tried to move away from discriminated unions.

[Nathan-Fenner]

This is a problem in general without negated types. The compelling examples are discriminated unions, but I think it would get really confusing really fast if you tried to move away from discriminated unions.

I'm suggesting the same (semi ad-hoc) behavior that custom type guards get, so this is the status quo:

playground

function isNum(x: string | number): x is number {
  return typeof x === "number";
}

const y: "a" | "b" | "c" | 1 | 2 | 3 = null as any;

if (isNum(y)) {
  y; // y's type is narrowed to 1 | 2 | 3
} else {
  y; // y's type is narrowed to "a" | "b" | "c"
}

The new part is just detecting an arbitrary narrowing of the return value of the guard instead of a truthiness narrowing of the return value; what this does to the argument's type is exactly the same as what tsc already does for existing type guards.

[scorbiclife]

FWIW, here's a way to represent the same intention with current typescript as of 4.8.2 (Playground)

Note:
flatThen cannot reuse existing functions because both flatMap and flatCatch can fail and affects the next step
then can reuse existing functions because map doesn't affect which function will run the next step
if in doubt just ternary expression everything and all will work as you intended

// Library using code

import React from "react";

declare function getResult(): Result<number>;
declare function processValue(v: number): string;
function formatError(e: string): string {
    return `Oops, something went wrong: ${e}`;
};

export default function Component() {
    const result = getResult();
    const msg =
        FluentResult.wrap(result)
            .map(processValue)
            .catch(formatError)
            .unwrap()
            .value // For this to work you need to set return type of `catch` to `Success`
    return <>{msg}</>;
}

// Library code

type Success<T> = { ok: true, value: T };
type Fail = { ok: false, error: string };
export type Result<T> = Success<T> | Fail;

const map = <T, U>(r: Result<T>, f: (t: T) => U): Result<U> =>
    r.ok ? { ok: true, value: f(r.value) } : r;

const flatMap = <T, U>(r: Result<T>, f: (t: T) => Result<U>): Result<U> =>
    r.ok ? f(r.value) : r;

const catch_ = <T, U>(r: Result<T>, f: (e: string) => U): Success<T | U> =>
    r.ok ? r : { ok: true, value: f(r.error) };

const flatCatch = <T, U>(r: Result<T>, f: (e: string) => Result<U>): Result<T | U> =>
    r.ok ? r : f(r.error);

const then = <T, U>(r: Result<T>, onSuccess: (t: T) => U, onFailure: (e: string) => U): Success<U> =>
    catch_(map(r, onSuccess), onFailure);

const flatThen = <T, U>(r: Result<T>, onSuccess: (t: T) => Result<U>, onFailure: (e: string) => Result<U>): Result<U> =>
    r.ok ? onSuccess(r.value) : onFailure(r.error);

// Optionally you can expose a fluent interface for better DX

// The second type parameter and `wrap` is solely to infer a success on `FluentResult.catch`
export class FluentResult<T, R extends Result<T> = Result<T>> {
    private result: R;

    constructor(result: R) {
        this.result = result;
    }

    static wrap<T>(result: Result<T>): FluentResult<T, Result<T>> {
        return new FluentResult(result);
    }

    unwrap(): R {
        return this.result;
    }

    map<U>(f: (t: T) => U): FluentResult<U> {
        return new FluentResult(map(this.result, f));
    }

    flatMap<U>(f: (t: T) => Result<U>): FluentResult<U> {
        return new FluentResult(flatMap(this.result, f));
    }

    catch<U>(f: (e: string) => U): FluentResult<T | U, Success<T | U>> {
        return new FluentResult(catch_(this.result, f));
    }

    flatCatch<U>(f: (e: string) => Result<U>): FluentResult<T | U> {
        return new FluentResult(flatCatch(this.result, f));
    }

    then<U>(onSuccess: (t: T) => U, onFailure: (e: string) => U): FluentResult<U> {
        return new FluentResult(then(this.result, onSuccess, onFailure));
    }

    flatThen<U>(onSuccess: (t: T) => Result<U>, onFailure: (e: string) => Result<U>): FluentResult<U> {
        return new FluentResult(flatThen(this.result, onSuccess, onFailure));
    }
}