The documentation of limited excess property checking introduced with ts 3.5 understates actual behavior

[craigphicks]

Bug Report

🔎 Search Terms

Excess Property Checks

🕗 Version & Regression Information

3.5

⏯ Playground Link

Playground link with relevant code

💻 Code

// Assumption:
// The rules for allowing an object to be assigned to a union type (|) are  
// (1) must contain all required properties of at least one union member
// (2) may contain additional properties that belong to any union member


// Examples supporting (but not proving) the assumption
{
  type A2 = {a: string; b: string};
  type A3 = {a: string; b: boolean; c: boolean};
  type A4 = {a: string; b: number; c: number};

  type A = A2|A3|A4
  // fail because rule (1) not satisfied
  const f1:A = {}  // error ✔ 
  const f2:A = {a:''} // error ✔
  const f3:A = {a:'',b:true} // error ✔
  const f4:A = {a:'',b:true,c:1} // error ✔

  // pass because rule (1) satisfied and rule (2) allows excess props of other members
  const a1: A = {a: '', b: '', c: true}; // ✔ assignments allow extra props of other union types
  const a2: A = {a: '', b: '', c: 1}; // ✔ assignments allow extra props of other union types

}

🙁 Actual documentation

• From Release Notes 3.5

In TypeScript 3.5, the type-checker at least verifies that all the provided properties belong to some union member and have the appropriate type, meaning that the sample above correctly issues an error. Note that partial overlap is still permitted as long as the property types are valid.

🙂 Expected documentation

The actual documentation does not match that observed in the code above. For example, that actual documentation would imply that an empty object could always be assigned to a union of object with required properties, and that is obviously false. So perhaps what the author meant would be given by this slight rewording of the actual documentation:

... the type-checker at least verifies that all the required properties of some (at least one) union member are provided ...

Equivalently -

• The rules for a set of properties to satisfy a union type (|) is
  • (1) must contain all required properties of at least one union member
  • (2) may contain additional properties that belong to any union member

This expected documentation

• is stronger excess property checking than the actual (current) documentation,
• matches the behavior in the playground code above,
• but is still not the kind of strict excess property checking as discussed in other issues (e.g., Unions without discriminant properties do not perform excess property checking #20863). Therefore it is not a change of the status quo.

Request to confirm actual intended design behavior.

The above "expected documentation" assumes the intended behavior of the typescript design, based on some supporting evidence (the playground code). However, although that evidence proves that the actual (current) documentation does not match the actual current behavior, it does not prove that the "expected documentation" (above) accurately describes the intended design behavior.

If the intended design behavior does not match that described in "Expected Documentation" then please give an unambiguous description of the intended design behavior.

Downstream development using the typescript API may depend upon knowing what semantics result in a compiler error and what don't. Of course the specs can change (the typescript API documentation warns about that), but having "no hard spec for excess property checking" is different than having "hard excess property checking specs that may change in the future".

[sandersn]

The description in 3.5's release notes is intended, as far as I understand it.

In general, however, the release notes give a friendly summary of the changes, and are not spec-quality. PRs usually give semantics — for complex features at least — but features are distributed across multiple PRs. Unfortunately, the priorities of the team and Typescript's open source nature combine to make it a spec-free language. That means semantics are argued per-feature rather than up-front when writing the spec.

[craigphicks]

The description in 3.5's release notes is intended, as far as I understand it ...
... the priorities of the team and Typescript's open source nature combine to make it a spec-free language.

That's a self contradiction.

I never the doubted the good intentions. Please don't doubt mine.

... features are distributed across multiple PRs.

In the case of excess property checks for unions, that is a single feature. The code will all be in one place.
A set of test cases will have been selected and written and the single feature programmatically tested again those test cases.
The test cases cannot be the set of all possible inputs, because there are too many. So instead a few are chosen wisely to represent main cases and corners cases. The program is built to spec when test case results are correct.

Not surprisingly, many programmers will label the directories they store their test data in as "specs", because the test data serves as the specs for the feature. Even if the test data is not in a directory named "specs", it is still a fact that almost all modern software feature development is test driven - and there has specs.

If you could give a pointer to that test data, I think we would see that the test cases were chosen with this verbal spec in mind:

The rules for a set of properties to satisfy a union type (|) is
(1) must contain all required properties of at least one union member
(2) may contain additional properties that belong to any union member

Then you would have to agree that at least as for the feature: "excess property checks for unions", typescript does have a working spec. (Although it is written as test cases). And also you would have to agree that however good were intentions, the release notes 3.5 do not accurately match the test cases.

[craigphicks]

My last reply was too wordy. I hid it to reduce noise.

... the priorities of the team and Typescript's open source nature combine to make it a spec-free language.

Yes and no.

• The great thing about typescript is that (usually) it works as expected, which means there isn't much need to look at the docs.
• We're all programmers here, so understand that documentation get out of sync with the actual specs(*).
• There are always specs. In the worst case, the code is the specs - but usually the code is written against test cases. So a programmer can look at the test cases. If you are able to point to the test cases, that would be helpful!
• This issue board also serves as documentation. So any conclusion about the actual intended specs that are posted here serve as documentation.

(*) Nevertheless, it is preferable not to have documentation that is specific but inaccurate.

"Excess property checking" is only a single feature, not a collection of features. The code will be all in one place. Checking regression in playground, it appears not to have changed since the 3.5 release.

[typescript-bot]

This issue has been marked as 'Question' and has seen no recent activity. It has been automatically closed for house-keeping purposes. If you're still waiting on a response, questions are usually better suited to stackoverflow.