Covariance / Contravariance Annotations

[Igorbek]

(It's a question as well as a suggestion)

Update: a proposal #10717

I've supposed that for structural type system as TypeScript is, type variance isn't applicable since type-compatibility is checked by use.

But when I had read @RyanCavanaugh 's TypeScript 1.4 sneak peek (specifically 'Stricter Generics' section) I realized that there's some lack in this direction by design or implementation.

I wondered this code is compiled:

function push<T>(arr: T[], a: T) { arr.push(a); }
var ns = [1];
push<{}>(ns, "a"); // ok, we added string to number[];

More clear code:

interface A { a: number; }
interface B extends A { b: number; }
interface C extends B { c: number; }

var a: A, b: B, c: C;

var as: A[], bs: B[];

as.push(a); // ok
as.push(b); // ok, A is contravariant here (any >=A can be pushed) 

bs.push(a); // error, B is contravariant here, so since A<B, A cannot be pushed -- fair 
bs.push(b); // ok
bs.push(c); // ok, C>=B

as = bs;    // ok, covariance used?

as.push(a); // ok, but actually we pushed A to B[]

How could B[] be assignable to A[] if at least on member push is not compatible. For B[].push it expects parameters of type B, but A[].push expects A and it's valid to call it with A.

To illustrate:

var fa: (a: A) => void;
var fb: (b: B) => void;

fa(a); fa(b);
fb(a);  // error, as expected
fa = fb;    // no error
fa(a);  // it's fb(a)

Do I understand it correctly that is by design?
I don't think it can be called type-safe.

Actually, such restriction that could make B[] to be unassignable to A[] isn't desirable.
To solve it I suggest to introduce variance on some level (variable/parameter, type?).

Syntax

var as: A[]; // no variance
var bs: out B[]; // covariant, for "read"
<out A[]>bs; // ok, covariance used
<A[]>bs; // same is before, out should be inferred

(<A[]>bs)[0]; // means, allow to get covariant type
(<A[]>bs).push(a); // means, disallow to pass covariant type

<in A[]>bs; // fails

function push<T>(data: in T[], val: out T): void {
  data.push(val);
}
push(animals, dog); // allowed, T is Animal
push(dogs, animal); // disallow, T can't be inferred

// In opposite
function find<T>(data: out T[], val: out T): bool { ... } // allow only get from data
find(animals, dog); // allowed
find(cats, dog); // allowed T can be inferred as Mammal

I'm not sure where variance should be applied - to variable or type?
Looks like it closer to variable it self, so the syntax could be like:

var in a: number[];
function<T>(in a: T[], out b: T): { ... }

Questions to clarification

• inference variance from usage (especially for functions)
• is it applicable for types (like C# uses for interfaces/delegates)
• how to describe variance on member-level (does it need?)
• can variable be in out (fixed type)?
• can variable be neither in nor out (open for upcast/downcast)?

So this topic is a discussion point.

[danquirk]

The assignments you've noted are by design. When checking assignability of function types their parameters are considered bivariant. So when assigning fa = fb it is valid if fa's parameters are assignable to fb's or vice versa. Likewise for the function typed members of Array when determining whether as = bs is valid. See #274 for the suggestion to check these more strictly all the time.

Co/contravariance is not an easy concept for a lot of folks to grasp (even though there is an intuitive nature to the assignment questions). Explicit annotations for them can be especially difficult for people to make use of (particularly if they have to author the annotations in their own code). C# has these types of annotations now but was highly successful for many years without the additional layer of checking the variance annotations afford. My gut feeling is that I would be surprised if these ended up in TypeScript given their complexity and how 'heavy' a concept they are.

[MgSam]

@danquirk I disagree that covariance/contravariance are such "heavy" concepts. In practice, it's generally just library authors that use them (not end users), and they're easy to ignore, so I don't think you're adding a burden to the language. Yet on the flip side, you're adding a lot of expressiveness to situations that would otherwise be less type safe.

Also, at a syntax level- having optional keywords of "in" and an "out" seems to me to be as lightweight as language constructs get.

I certainly wouldn't consider this feature high enough priority to want it added to the backlog anytime soon, but once TypeScript is more mature it could certainly be a useful addition.

[Igorbek]

So, if go with some "strict" mode only, there's no way to annotate variance, because it shouldn't introduce any new keywords.
I believe in most cases, TypeScript will be able to infer variance from usage. And bivariance for functions could be a fallback if modifier wouldn't be specified.

I've read Function Argument Bivariance article, and it looks like the example might be rewritten more clear and useful without bivariance requirement:

enum EventType { Mouse, Keyboard }

interface Event { timestamp: number; }
interface MouseEvent extends Event { x: number; y: number }
interface KeyEvent extends Event { keyCode: number }

function listenEvent<TEvent extends Event>(eventType: EventType, handler: (n: TEvent) => void) {
    /* ... */
}

listenEvent<MouseEvent>(EventType.Mouse, e => console.log(e.x + ',' + e.y));

@MgSam thanks for support.

[metaweta]

Outputs are always covariant and arguments are usually contravariant. The only point where we'd need an annotation is when an argument is also used as an output. I think it would be a lot easier to grasp if all type constructors and generics came equipped with their associated map functions, since then you just look at what order the mapped functions get applied.

[Igorbek]

@metaweta callbacks are bivariant now. It also needs clarification/make stricter.

[metaweta]

I don't know what you mean by "callbacks are bivariant": variance is a concept that applies to a specific use of a type in a signature. I was suggesting that types used in arguments be contravariant by default; now that I think more about it, that would cause new errors in currently working code, which is unacceptable.

To avoid the issue of a new keyword, I suggest using +/- like Scala does.

How about a directive "use variance" to opt into that assumption? That way a library author can avoid having to add the contravariant modifier everywhere, while the user of the library doesn't have to worry about it. Directives are a part of ECMAScript specifically designed for this kind of scoped alteration of semantics.

[Igorbek]

I mean that callback is an argument which is a function:

class A { ... } class B extends A { ... } class C extends B { ... }
function f(callback: (b: B) => void) { ... }
f((x: A) => { ... }); // no error, callback accepts x: A, fair any B is A
f((x: C) => { ... }); // no error, callback accepts x: C, but it might be called with B which isn't C

That's what "callback are bivariant" means.

Regarding +/-, do you mean to use it with type specifier? Like:

function f<T>(x: T-[], y: T) { x.push(y); } // y: T+, by default for function arguments

Directives are a part of ECMAScript specifically designed for this kind of scoped alteration of semantics.

Which directives do you mean?

[metaweta]

The arrow functor is contravariant in its first argument and covariant in its second. Contravariance acts somewhat like multiplication by -1.

In (a:A) => B, A is contravariant and B is covariant.

In (f: (a: A) => B) => C, C is covariant and (a: A) => B is contravariant, which means that A is covariant (-1 * -1 = 1) and B is contravariant (-1 * 1 = 1).

Regarding +/-, do you mean to use it with type specifier?

I mean to use it in the type parameters rather than the function signature:

interface Foo <-A, +B> {
  map<+C>(f:(a:A) => C): Foo<C, B>;
}

Which directives do you mean?

The directive "use strict" changes the semantics of the language within a function block or program production (usually an HTML script block). I imagine a "use variance" directive in a module production.

[Igorbek]

The arrow functor is contravariant in its first argument and covariant in its second. Contravariance acts somewhat like multiplication by -1.

I understand this. But now TS violates this rule in case of callbacks. I didn't say how it should work, I did say how it works now.

[metaweta]

Yikes! That's terrible.

[RyanCavanaugh]

If function parameters weren't bivariant, Array<Dog> would not be a structural subtype of Array<Animal> due to members like forEach.

[metaweta]

I take back my "that's terrible" assesment; that would only be fair for a purely functional language. Every mutable data structure is going to have this trouble. Getters are covariant while setters are contravariant: given f:(x:X)=>Y, and arr:Array<X>, arr.map(f) is an array where a getter returns a Y; for instance, this could be implemented lazily by having a getter look up an element x and then return f(x). A map using X contravariantly would take a function g:(w: W)=>X and arr.comap(g) would be an array where the setter would store g(w) in the array. (I'm not suggesting comap be implemented or that map have a different implementation, just pointing out how the variance shows up in getters and setters.)

I think the article's right that the sound alternatives are too cumbersome for not enough benefit.

[Igorbek]

@RyanCavanaugh I thought Array<Dog> wouldn't be structural subtype of Array<Animal> due to members like push. Methods like forEach is fully compartible. Indeed:

interface X<T> {
  out(): T;
  cb(cb: (v: T) => void)): void; // like Array.forEach
  in(v: T): void; // like Array.push
}
var xdog: X<Dog>;
var xanimal = <X<Animal>>xdog; // is it convertible?

// out is convertible, fair - covariance
xanimal.out(); // <Dog>xdog.out(), ok

// cb is convertible, fair - covariance
xanimal.cb(animal => cb(animal)); // xdog.cb(dog => cb(<Animal>dog)), ok

// in is not convertible - contravariance, but no error
xanimal.in(animal); // it same as...
xdog.in(animal); // error -- animal is not a Dog, but same call to xanimal don't produce an error

// here is used bivariance, but it's not fair
xanimal.cb((dog: Dog) => ...); // no error due bivariance, but it should be

So and my purpose to mark variables/parameters with variance modifier to make them convertible.
So if you convert Dog[] to Animal[] you actually should get out Animal[] which means it's impossible to call push method on it.

[Igorbek]

And even more clear example of bivariance which shouldn't be:

var f: (x: { x: number; }) => void;
var g: (x: { x: number; y: number; }) => void;

g = f; // fair
f = g; // no error, but it should be

[metaweta]

If I understand right, you're suggesting keywords that would construct the co- or contravariant supertype of a given generic type, somewhat like extracting the real and imaginary part of a complex number. I like that idea.

[vlad-nikityuk]

Recently found similar issue, I guess.

class Base { n() { return 0; }}
class Derived extends Base { m() { return 1; }}

var base = (b: Base) => b.n();
var derived = (d: Derived) => d.m();

base = derived;

base(new Base()); // TypeError: undefined is not a function (evaluating 'd.m()')

Wondering if it could be fixed easily or not?

[dead-claudia]

Found an area where covariance (IIRC) would really help: strongly (and provably) typing the element tree. You could correctly narrow a vdom's children to only the correct types, so something like React could prevent say <title> to be a child of a <div>, which even though HTML would accept and ignore it, React shouldn't (and doesn't AFAIK). Without covariant types, though, I've already discovered that if you use generics for attributes, TypeScript often requires an explicit parameter to prevent a type error where it wouldn't if the parameter was covariant. A concrete example would be something like this, which doesn't check without explicitly specifying types, but could be entirely inferred with covariant types:

type Child = // things...

interface Attrs {
  // things...
}

interface VNode<T extends string, A extends Attrs, C extends Child> {
  type: T;
  attrs: A;
  children: C[];
}

export const m<T extends string, C extends Children>(type: T, c?: C | C[]): VNode<T, {}, C>;
export const m<T extends string, A extends Attrs, C extends Children>(type: T, a: A, c?: C | C[]): VNode<T, A, C>;

In effect, with covariant types and what exists today (and enough patience - it'd take a long while), you could mostly prove the well-formedness of virtual DOM trees (minus quantity) and largely correctly type the DOM itself.

---

I discovered this working on a vdom experiment, where components can be in charge of rendering themselves (mod tree diffing). I optimally want to track both permitted attributes and permitted children, so covariance would help.

[zpdDG4gta8XKpMCd]

It's rather a simple tweak in the compiler code to turn off covariance for parameters. I tried it once to get a feeling of what it takes to be a happy owner of the code that works right. The biggest pain are the overloaded DOM event handlers lib.d.ts that wont compile after such tweak. I tend to think that using overloading was a poor design choice for event handlers, because effectively they are a bunch of separate functions (despite sharing the same name) rather than one with a base basic signature coupled tons of covariant overloads:
#6102 (comment)

[nicojs]

With the recent addition of --strictFunctionTypes co- and contra-variance are now supported on function types without function types. This was a major step up and we had to fix dozens of actual issues in our code (which is awesome!).

Are there any plans to also support co- and contra-variance for other types? (as reported in this issue)? Or nothing on the roadmap?

[ghost]

@nicojs the original proposal seemed to suggest adding co/contra variant annotations as a means of opting out of unsoundness on a per type basis. With --strictFunctionalTypes, that variance of a type will now be inferred correctly for other types... my covariant "interface Stream<T> { next(): T; }" behaves covariant with respect to T, and my contravariant "interface Bin<T> { put(item: T); }" behaves contravariant with respect to T.

Could you clarify, are you asking if there are any remaining soundness holes, or asking for an explicit way to declare variance (in addition to the inferred behavior)?

[Igorbek]

The proposal initially discussed here and later outlined primarily in #10717 is mostly concerned of use-site covariance annotations. The motivation use cases are still not addressed even with recent enstricten rules.

The simplest example is an array type which can be used both co- and contravariantly. With the proposal an array of type Array<out T> can only be used where type T in covariant positions (getters, methods like pop). Similarly Array<in T> can be used where type T in contravariant positions (setters, methods like push). Note, in general, Array<out T> is not the same as ReadonlyArray<T>.

[dead-claudia]

@Igorbek Could you elaborate on how Array<out T> would be different from Readonly<Array<T>> (not ReadonlyArray<T> - I'm not including methods here) or Array<in T> from a theoretical Writeonly<Array<T>> (assuming some Writeonly analogue to the built-in type Readonly<T> = {+readonly [P in keyof T]: T[P]})?

[Igorbek]

@isiahmeadows consider Array's methods like pop, reverse, shift, sort, and many others. Although they are modifying array and are excluded from ReadonlyArray<T>, the type T there is in covariant position and therefore is part of Array<out T>.

[dead-claudia]

@Igorbek Re-read my comment. You missed my nuance between Readonly< Array< T > > and ReadonlyArray< T > (spaces here added for emphasis).

[Igorbek]

ah, sorry @isiahmeadows I thought you were asking in the context of my previous note about their differences.

In fact, Readonly<Array<T>> is even less covariant in respect to T than ReadonlyArray<T>.
Assuming it is defined as type Readonly<T> = { readonly [P in keyof T]: T[P]; }, it only transforms own fields (not even methods) to become read-only.

Actually, TS does not currently make Readonly<T[]> be actually read-only:

function test<T>(a: Readonly<T[]>, v: T) {
    a[0] = v; // no error
}

In general, generic type variance has nothing to do with read/write-ability.
A simple test would be:

interface X<T> {
  value: T; // read-write field with T in covariant position for reads and in contravariant position for writes
  set: (value: T) => void; // read-write field with T in contravariant position
}

type Readonly<X<T>> = { // effectively equivalent to this
  readonly value: T; // this is now covariant in respect to T
  readonly set: (value: T) => void; // read field with T in contravariant position
}

type X<out T> = {
  readonly value T; // same as Readonly
  writeonly set: (value: T) => void; // see the difference
}

type X<in T> = {
  writeonly value T;
  readonly set: (value: T) => void;
}

And a final thing, even if in many respects having a readonly version is mostly what you want, a simple Readonly<T> cannot deal with multiple type arguments. Like imaging Processor<TIn, TOut> is contravariant in respect to TIn and covariant in respect to TOut, and therefore cannot be expressed with Readonly/Writeonly as it have mixed type arguments' variance.

[dead-claudia]

Okay, I'd find a[i] = 0 succeeding when a: Readonly<number[]> to be a bug.

[Igorbek]

Okay, I'd find a[i] = 0 succeeding when a: Readonly<number[]> to be a bug.

being fixed in #29435

[kevinbarabash]

In the case of arrays, why not prevent aliasing assignments that aren't invariant without an explicit cast?

class Animal {}
class Dog extends Animal { bark() { } }
class Cat extends Animal { purr() { } }

const cats: Array<Cat> = [];
const goodAnimals: Array<Animal> = [new Cat, new Cat];
const badAnimals: Array<Animal> = cats;  // why not make this an error?

goodAnimals.push(new Dog);  // okay
badAnimals.push(new Dog);  // hard to prevent, how do you tell goodAnimals from badAnimals?

cats.forEach(cat => cat.purr());  // oops!

Given TypeScript's support for generics, when are covariant arrays actually useful?

[glasser]

I am very excited to see that this will exist in future versions of TypeScript.

For the time being, if you're looking for a hacky way to ensure contravariance, you can add something like this to a class:

export class C<T> {
  protected __forceTToBeContravariant?: (t: T) => void;

Note that you can't make this private if you want the constraint to work across TS projects due to #38953 ; you might think it works in your same-project tests but not once it is encoded in .d.ts!