[invariant] Assertion functions

[josh]

Make use of TypeScript 3.7 assertion function feature to implement invariant.

Please fill in this template.

• Use a meaningful title for the pull request. Include the name of the package modified.
• Test the change in your own code. (Compile and run.)
• Add or edit tests to reflect the change. (Run with npm test.)
• Follow the advice from the readme.
• Avoid common mistakes.
• Run npm run lint package-name (or tsc if no tslint.json is present).

If changing an existing definition:

• Provide a URL to documentation or source code which provides context for the suggested changes: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions

[typescript-bot]

👋 Hi there! I’ve run some quick measurements against master and your PR. These metrics should help the humans reviewing this PR gauge whether it might negatively affect compile times or editor responsiveness for users who install these typings.

Let’s review the numbers, shall we?

Comparison details 📊

	master	#40218	diff
Batch compilation
Memory usage (MiB)	36.0	36.1	+0.3%
Type count	2080	2081	0%
Assignability cache size	103	103	0%
Language service
Samples taken	9	9	0%
Identifiers in tests	9	9	0%
getCompletionsAtPosition
Mean duration (ms)	88.7	87.1	-1.8%
Mean CV	21.0%	23.6%
Worst duration (ms)	112.6	101.3	-10.0%
Worst identifier	invariant	invariant
getQuickInfoAtPosition
Mean duration (ms)	82.7	84.3	+1.9%
Mean CV	19.8%	21.9%	+10.5%
Worst duration (ms)	96.0	98.2	+2.3%
Worst identifier	invariant	invariant

It looks like nothing changed too much. I won’t post performance data again unless it gets worse.

[typescript-bot]

@josh Thank you for submitting this PR!

🔔 @bennett000 @dtinth - please review this PR in the next few days. Be sure to explicitly select Approve or Request Changes in the GitHub UI so I know what's going on.

If no reviewer appears after a week, a DefinitelyTyped maintainer will review the PR instead.

[bennett000]

Looks good to me.

That said I'm not a reviewer (on the right sidebar) and I cannot seem to approve as @typescript-bot suggests

[dtinth]

Thanks for the PR!

I'm excited to use assertion functions in TypeScript as well. However I think we should retain support for invariant (false) pattern.

[dtinth]

I believe this should stay as {} to facilitate this pattern:

const thing = getThing() || invariant(false, 'Expected getThing to return something')

as well as

const thing = getThing() ?? invariant(false, 'Expected getThing to return something')

[dtinth]

IMO we should keep this overload to not break existing test (see comment below).

[dtinth]

Would be great if some test can be added for this.

[typescript-bot]

@josh One or more reviewers has requested changes. Please address their comments. I'll be back once they sign off or you've pushed new commits or comments. Thank you!

[josh]

I believe this should stay as {} to facilitate this pattern:

Is it possible for an asserts function to have a return value?

However I think we should retain support for invariant (false) pattern.

👍 that makes sense.

[typescript-bot]

🔔 @dtinth - Thanks for your review of this PR! Can you please look at the new code and update your review status if appropriate?

[dtinth]

@josh Thanks! Mind adding a corresponding test for this change? Maybe a test could look like this:

declare const x: any
invariant(typeof x === 'string')
const s = x
// $ExpectType string
x

[josh]

Mind adding a corresponding test for this change? Maybe a test could look like this:

Tried that, but got:

expect  TypeScript@next expected type to be:
  string
got:
  any