You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
It would be great if api-extractor could add in and out information to generics in the api report,
as changing a generic from in to out or vice versa can cause breaking changes for consumers.
Details
Quoting from a Twitter thread where I came up with that idea:
We had a type MockedResponse that had a covariant (implicit out) generic argument in the past.
That means, MockedResponse<Foo> was assignable to MockedResponse<unknown>, or more important, could be an array member of Array<MockedResponse<unknown>> with unknown being the default.
That means, people could write
Now, we added a method that referenced that genereric argument in a contravariant position (an input position) to the type.
The implicit out switched to an implicit in.
As a result, the userspace code above would now error.
The thing is: this is semantically correct if the user would ever manually call variableMatcher. But the user doesn't. Our library calls it, and from the perspective of our library, we don't need the contravariance here.
The implicit change from out to in went unnoticed and broke userspace code without introducing any additional safety.
Had we hand-annotated the out from the start, this would not have gone unnoticed - it would have either been an intentional trade-off kinda-breaking change in our types, or we could have avoided shipping it.
I am hoping that at some point, the API reports generated by api-extractor will make in and out visible in their api reports to make breaking api changes like this visible.
The PR to resolve it does some horrible type yoga to make this an out type again, because we know better™️ how it's actually used - but I hope we can get around that in the first place in the future.
Standard questions
This is a feature request so I believe these don't really apply.
The text was updated successfully, but these errors were encountered:
Summary
It would be great if api-extractor could add
in
andout
information to generics in the api report,as changing a generic from
in
toout
or vice versa can cause breaking changes for consumers.Details
Quoting from a Twitter thread where I came up with that idea:
We had a type
MockedResponse
that had a covariant (implicitout
) generic argument in the past.That means,
MockedResponse<Foo>
was assignable toMockedResponse<unknown>
, or more important, could be an array member ofArray<MockedResponse<unknown>>
withunknown
being the default.That means, people could write
Now, we added a method that referenced that genereric argument in a contravariant position (an input position) to the type.
The implicit
out
switched to an implicitin
.As a result, the userspace code above would now error.
The thing is: this is semantically correct if the user would ever manually call
variableMatcher
. But the user doesn't. Our library calls it, and from the perspective of our library, we don't need the contravariance here.The implicit change from
out
toin
went unnoticed and broke userspace code without introducing any additional safety.Had we hand-annotated the
out
from the start, this would not have gone unnoticed - it would have either been an intentional trade-off kinda-breaking change in our types, or we could have avoided shipping it.I am hoping that at some point, the API reports generated by api-extractor will make
in
andout
visible in their api reports to make breaking api changes like this visible.The PR to resolve it does some horrible type yoga to make this an
out
type again, because we know better™️ how it's actually used - but I hope we can get around that in the first place in the future.Standard questions
This is a feature request so I believe these don't really apply.
The text was updated successfully, but these errors were encountered: