Enable type parameter lower-bound syntax

[jyuhuan]

TypeScript Version: 2.1.1

Code

class Animal {}
class Cat extends Animal {}
class Kitten extends Cat{}

function foo<A super Kitten>(a: A) { /* */ }

Expected behavior:
The type parameter A has the type Kitten as lower-bound.

Actual behavior:
Compilation failure. The syntax is unsupported.

Discussion:
The upper-bound counterpart of the failed code works fine:

class Animal {}
class Cat extends Animal {}
class Kitten extends Cat{}

function foo<A extends Animal>(a: A) { /* */ }

People in issue #13337 have suggested to use

function foo <X extends Y, Y>(y: Y) { /* */ }

to lower-bound Y with X. But this does not cover the case where X is an actual type (instead of a type parameter).

[RyanCavanaugh]

What is this useful for?

[jyuhuan]

@RyanCavanaugh : In short, it mimics contravariance, just as extends mimics covariance.

We will try to sort an array of cats to see the necessity of this feature.

To do comparison-based sorting, we need a Comparator interface. For this example, we define it as follows:

interface Comparator<T> {
  compare(x: T, y: T): number
}

The following code shows that the class Cat has Animal as its super-class:

class Animal {}
class Cat extends Animal {}

Now we can write a sorting function that supports arbitrary Cat comparators as follows:

function sort(cats: Cat[], comparator: Comparator<Cat>): void {
  // Some comparison-based sorting algorithm.
  // The following line uses the comparator to compare two cats.
  comparator.compare(cats[0], cats[1]);
  // ...
}

Now, we will try to use the sort function. The first thing is to implement a CatComparator:

class CatComparator implements Comparator<Cat> {
  compare(x: Cat, y: Cat): number {
    throw new Error('Method not implemented.');
  }
}

Then we create a list of Cats,

const cats = [ new Cat(), new Cat(), new Cat() ]

Now we can call sort as follows without any problem:

sort(cats, new CatComparator());

We have not seen the need for contravariance so far.

Now, suppose we are told that someone has already implemented a comparator for Animals as follows:

class AnimalComparator implements Comparator<Animal> {
  compare(x: Animal, y: Animal): number {
    throw new Error('Method not implemented.');
  }
}

Since a Cat is also an Animal, this AnimalComparator is also able to handle Cats, because the compare function in AnimalComparator takes two Animals as input. I can just pass two Cats to it and there will be no problem.

Naturally, we would want to use AnimalComparator for sort too, i.e., call the sort function as:

sort(cats, new AnimalComparator());

However, since the following two types:

• Comparator<Animal>
• Comparator<Cat>

are not related from the point of view of TypeScript's type system, we cannot do that.

Therefore, I would like the sort function to look like the following

function sort<T super Cat>(cats: Cat[], comparator: Comparator<T>): void {
  // Some comparison-based sorting algorithm.
  // The following line uses the comparator to compare two cats.
  comparator.compare(cats[0], cats[1]);
  // ...
}

or as in Java,

function sort(cats: Cat[], comparator: Comparator<? super Cat>): void {
  // Some comparison-based sorting algorithm.
  // The following line uses the comparator to compare two cats.
  comparator.compare(cats[0], cats[1]);
  // ...
}

I am aware of the fact that TypeScript does not complain if I pass AnimalComparator to sort. But I would like TypeScript's type system to explicitly handle type lower-bounds. In fact, the current type system of TypeScript will let some type error closely related to this issue silently pass the compiler's check (see issue #14524).

[jklmli]

This is the best example of contravariance I've read in a long time. Props! 🙌

[btipling]

As a reference point, flowtype uses - and + to indicate covariance and contravariance

class ReadOnlyMap<K, +V> {
  store: { +[k:K]: V };
  constructor(store) { this.store = store; }
  get(k: K): ?V { return this.store[k]; }
}

[HerringtonDarkholme]

Hi @jyuhuan , since you probably already know this https://github.com/Microsoft/TypeScript/wiki/FAQ#why-are-function-parameters-bivariant

I'm afraid lower bound isn't that useful in current TypeScript where variance is unsound.

Indeed, there are also cases lower bound can be useful without variance. Like

interface Array<T> {
  concat<U super T>(arg: ): Array<U>
}

var a = [new Cat]
a.concat(new Animal) // inferred as Animal[]

In such case like immutable sequence container, lower bound helps TypeScript to enable pattern where new generic type is wider than original type.

Yet such usage still needs more proposal since TS also has union type. For example should strArr.concat(num) yield a Array<string | number>?

[zpdDG4gta8XKpMCd]

migrated from #14728:

currently when we see a constraint <A extends B> it means A is a subtype of B, so that

declare var a: A;
declare var b: B;
b = a; // allowed
a = b; // not allowed

consider adding a new constraint of the reversed relation: <A within B> that would mean A is a supertype of B (or in other words B is subtype of A), so that:

declare var a: A;
declare var b: B;
b = a; // not allowed
a = b; // allowed

use case

i have a BigFatClass with 50 methods and a 1 little property, now i want to run some assertions over it, if i declare these assertions like expect<T>() and toEqual<T> of the same T then toEqual asks me for 50 methods that don't matter for the test, and that's the problem

what i need it to declare expect<T>() and toEqual<U within T>() so that i could simply write:

expect(new BigFatClass()).toEqual({ value: true });

[aaronbeall]

<U within keyof T> could be confusing, since U in this case should be a super-set of T keys, not "within" the keys of T.

[zpdDG4gta8XKpMCd]

the idea is that U is always a subset, never a superset, so if so it should not be a problem

[aaronbeall]

So <U within keyof T> would be the same as <U extends keyof T>?

[zpdDG4gta8XKpMCd]

i always forget that subtype of a union is a subset of that union, conversely a supertype of a union must be a superset, so you right that within would look like a poor choice of word to indicate that something is a superset of something else, how about A unties B or A relaxes B or loosens, frees, eases etc: https://www.powerthesaurus.org/loosen/synonyms

[zpdDG4gta8XKpMCd]

@aaronbeall problem with Partial<T> for making a supertype of a product type, is that it only works at the top level, so it doesn't really work for my use case, consider:

type Super<T> = Partial<T>;
type Data = { nested: { value: number; }; }
const one: Super<Data> = {}; // works
const another: Super<Data> = { nested: {} }; // bummer

so i am back to hammering the expected values with the type assertions

expect(data).toEqual(<Data>{ nested: {} });

[aaronbeall]

@Aleksey-Bykov Probably doesn't make this feature any less valuable but for your case I think you can use a recursive partial type:

type DeepPartial<T> = {
  [P in keyof T]?: DeepPartial<T[P]>;
}

(This was suggested as an addition to the standard type defs, which I think would be very useful.)

[zpdDG4gta8XKpMCd]

@aaronbeall DeepPartial almost works for my needs, except that due to having an empty object in it, it can be assigned by anything (except null and undefined), and it's a problem:

type Super<T> = DeepPartial<T>
type Data = { value: number; }
const one: Data = 5; // not allowed
const another: Super<Data> = null; // not allowed
const yetAnother: Super<Data> = 5; // allowed
const justLike: {} = 5; // <-- reason why (allowed)

[jmlopez-rod]

@Aleksey-Bykov Woah, you just answered my question. But now I have another one, why is this allowed?

const a1: {} = 0;
const a2: {} = '0';
const a3: {} = false;
const a4: {} = { a: 0 };

Is {} the same asany minus null and undefined?

EDIT: I tried the following DeepPartial definition in the link I provided and it seems to work.

type DeepPartial<T> = {[P in keyof T]?: T[P] | (DeepPartial<T[P]> & object); };

It is pretty late, maybe that won't work either, I'll probably think of some example that will break it once I wake up.

[cyber-barrista]

A bit of a somewhat working workaround for anyone interested 😃

type Range<Lower, Upper> = Upper & Partial<Extract<Lower, Upper>>

// test
type Big = { f1: number, f2: string, f3: string }
type Small = { f1: number }

const scoped: Range<Big, Small> = { f1: 1, f2: 'one' }
const small: Small = scoped
const big: Big = scoped // no no

[qwertie]

This seems like the most common thing I want from TypeScript that it can't currently do. Examples:

/** Numeric text box component. `number` must be a valid value of `Num`,
    but TypeScript does not accept <number extends Num extends NFTHNum>` */
function NumericTextField<Num extends NumEx>(...): JSX.Element {...}
type NumEx = number | undefined | null | { toString():string };

/** This should say `null extends CFV` i.e. that null must be a valid value of CFV,
    but TypeScript doesn't support that kind of constraint AFAICT. */
function WithNullCheckbox<CFV = CustomFieldValue>(...) {...}

Until just now I thought the syntax should "obviously" be <constraint extends T>, e.g. number extends T means that let t: T = 7 must be legal. I realize now that this can't work:

type U = ...;
type V = ...;
// It's unclear whether the `U` or `V` is meant as the parameter name, and for 
// backward compatibility, `U` must be the name and `V` must be the constraint.
function Foo<U extends V>() {}

So I propose that when this feature is implemented, the TypeScript compiler should detect what the user is trying to do in most cases and offer a correction, e.g. if the final syntax were Foo<T includes Bound>, TypeScript could offer error messages like:

// Currently the error is "Cannot find name 'Y'" but if `X` was already defined, 
// I propose "Cannot find name 'Y'. Did you mean 'Y includes X'?"
function Foo<X extends Y>() {}

// Currently the error is "Type parameter name cannot be 'number'". I propose
// "Type parameter name cannot be 'number'. Did you mean 'T includes number'?"
function Foo<number extends T>() {}

// These don't parse, so better error messaging would need parser changes.
function Foo<{ toString(): string } extends T>() {}
function Foo<(X|Y) extends T>() {}
function Foo<X[] extends T>() {}

[Yona-Appletree]

The use case I came across for this is an "action executor" in the context of an application.

interface AppContext { database; service1; service2; serviceN; }
function executeAction<T>(actionFn: (context: AppContext, args) => T) { ... }

Naturally, you can pass in an action that takes a subset of AppContext, which is desirable (so that they can be tested, for example, without a full context), but what if I want to have an interface/type for an action?

interface Action<
  TContext, // super AppContext
  TResult
> {
  (context: TContext): void;
  name: string;
  metadata;
}

How do I constrain TContext correctly? Seems like it can't be done.

However, there is a relatively easy workaround, though kind of annoying, which is to always use a function type when you want a contravariant type parameter:

interface Action<
  TContextFn extends (context: AppContext) => void,
  TResult
> {
  (context: Parameters<TContextFn>[0]): TResult;
  name: string;
  metadata;
}

But that makes it kind of hard to explictly type Action. In my case, that's not a big deal, but it would be really nice to have a proper lower bound syntax.

[jcalz]

This would also allow safer property writes:

interface Foo { a: true }
const foo: Foo = { a: true };

function f(o: { a: boolean }) {
  o.a = Math.random() < 0.5; // is accepted but unsafe
}
f(foo); // is accepted but unsafe

function g<T super boolean>(o: { a: T }) {  
//           ^^^^^ <--- proposed feature
  o.a = Math.random() < 0.5; // accepted because it's safe
}
g(foo); // rejected

[LPTK]

@jcalz the underlying issue here is that TS unsoundly treats mutable records as covariant. The f(foo) call itself really should be forbidden. Using a lower bound in g does not solve anything as g's type can still be instantiated to f's type and called similarly: g<boolean>(foo).

[RobertSandiford]

@jcalz the underlying issue here is that TS unsoundly treats mutable records as covariant. The f(foo) call itself really should be forbidden. Using a lower bound in g does not solve anything as g's type can still be instantiated to f's type and called similarly: g<boolean>(foo).

Yes the solution is to have readonly properties with the current assignability, and mutable properties that are invariant. Perhaps a strict setting would make all properties of a received object readonly (preserving current assignability for the sake of external compatibility), highlighting unsafe code. The author could then mark the property mutable to make it invariant, or choose to override the error e.g. via cast to continue using unsafe code. #18770

[Zachiah]

export const isInstanceOf = <I>(c: new () => I) => <T supertype I>(v: T): v is I => {
    return v instanceof c
}

This is my use case. I would like to be able to do things like:

export const isInstanceOfString = isInstanceOf(String);

[Snowflyt]

I’d like to present a compelling use case for introducing such a feature, inspired by Ramda’s R.includes function:

import * as R from "ramda";

type State = 0 | 1 | 2;

const includes0 = R.includes(0 as const);
const states: State[] = [1, 0, 1, 2];
includes0(states)

Ideally, the type signature of includes0 should be something like <T super 0>(list: readonly T[]) => boolean, allowing it to accept any array type that includes the value 0. For this to work, the type of R.includes itself would need to be structured as function includes<T>(target: T): <U super T>(list: readonly U[]) => boolean, but achieving this is currently not possible in TypeScript.

If you paste the code above into the TypeScript Playground, it actually results in an error:

includes0(states)
//        ~~~~~~
// Argument of type 'State[]' is not assignable to parameter of type 'readonly 0[]'.
//   Type 'State' is not assignable to type '0'.
//     Type '1' is not assignable to type '0'.

This error highlights limitations in the current typing of R.includes:

export function includes(s: string): (list: readonly string[] | string) => boolean;
export function includes<T>(target: T): (list: readonly T[]) => boolean;

The additional overload for string-based use cases exists to support scenarios like const includesFoo = R.includes("foo" as const); const xs: Array<"foo" | "bar"> = ["foo", "bar"]; includesFoo(xs), avoiding errors in these cases. However, this workaround is quite specific and doesn’t generalize well to other types.

I’ve encountered several similar issues due to the contravariant nature of function parameter types, where I desperately wish for syntax like <T super Type>, which could elegantly resolve such cases.

[linkfang]

My use case is related to array.includes().
I would like to check whether an item is in the array

For example,

// Type of myArr is ["a", "b"]
const myArr = ['a', 'b'] as const;

// This item could come from reading env or an API response, anywhere that I can not know the exact value or type
const myItem = process.env.MY_ITEM; 

// This will error out saying: Argument of type 'string' is not assignable to parameter of type '"a" | "b"'
myArr.includes(myItem) 

The reason I call myArr.includes(myItem) is to check whether this item exists in myArr, but now TS refuses to execute this function becausemyItem is a super-type (string) of "a" | "b". But, if I know myItem is either "a" or "b", then why do I need to call includes()?

[Nokel81]

@linkfang very much agree, I have run into this many times especially when trying to validate a value is in some allowed set.