[@types/node] use assertion guards in assert module (#42786)

* feat(node): Add support for TypeScript 3.7 assertion functions

* fix(adone): use `any` for type of `assert` module

* chore(node): rename `internal` namespace to `assert`

* chore(node): adjust `typesVersions` order

* chore(node): clean up `typesVersions` ranges

* Revert "chore(node): clean up `typesVersions` ranges"

This reverts commit 913a1a6.

types/adone/glosses/std.d.ts

@@ -1,4 +1,3 @@
-import assert = require("assert");
 import fs = require("fs");
 import path = require("path");
 import util = require("util");
@@ -33,6 +32,8 @@ import timers = require("timers");
 import dgram = require("dgram");
 import perf_hooks = require("perf_hooks");
 
+declare const assert: any;
+
 export {
     assert,
     fs,

types/node/assert.d.ts

@@ -1,6 +1,6 @@
 declare module "assert" {
-    function internal(value: any, message?: string | Error): void;
-    namespace internal {
+    function assert(value: any, message?: string | Error): void;
+    namespace assert {
         class AssertionError implements Error {
             name: string;
             message: string;
@@ -22,9 +22,13 @@ declare module "assert" {
         /** @deprecated since v10.0.0 - use fail([message]) or other assert functions instead. */
         function fail(actual: any, expected: any, message?: string | Error, operator?: string, stackStartFn?: Function): never;
         function ok(value: any, message?: string | Error): void;
+        /** @deprecated since v9.9.0 - use strictEqual() instead. */
         function equal(actual: any, expected: any, message?: string | Error): void;
+        /** @deprecated since v9.9.0 - use notStrictEqual() instead. */
         function notEqual(actual: any, expected: any, message?: string | Error): void;
+        /** @deprecated since v9.9.0 - use deepStrictEqual() instead. */
         function deepEqual(actual: any, expected: any, message?: string | Error): void;
+        /** @deprecated since v9.9.0 - use notDeepStrictEqual() instead. */
         function notDeepEqual(actual: any, expected: any, message?: string | Error): void;
         function strictEqual(actual: any, expected: any, message?: string | Error): void;
         function notStrictEqual(actual: any, expected: any, message?: string | Error): void;
@@ -46,8 +50,8 @@ declare module "assert" {
         function match(value: string, regExp: RegExp, message?: string | Error): void;
         function doesNotMatch(value: string, regExp: RegExp, message?: string | Error): void;
 
-        const strict: typeof internal;
+        const strict: typeof assert;
     }
 
-    export = internal;
+    export = assert;
 }

types/node/base.d.ts

@@ -1,6 +1,5 @@
 // base definnitions for all NodeJS modules that are not specific to any version of TypeScript
 /// <reference path="globals.d.ts" />
-/// <reference path="assert.d.ts" />
 /// <reference path="async_hooks.d.ts" />
 /// <reference path="buffer.d.ts" />
 /// <reference path="child_process.d.ts" />

types/node/index.d.ts

@@ -59,6 +59,9 @@
 // Base definitions for all NodeJS modules that are not specific to any version of TypeScript:
 /// <reference path="base.d.ts" />
 
+// We can't include assert.d.ts in base.d.ts, as it'll cause duplication errors in +ts3.7
+/// <reference path="assert.d.ts" />
+
 // Forward-declarations for needed types from es2015 and later (in case users are using `--lib es5`)
 // Empty interfaces are used here which merge fine with the real declarations in the lib XXX files
 // just to ensure the names are known and node typings can be used without importing these libs.

types/node/package.json

@@ -2,6 +2,11 @@
     "private": true,
     "types": "index",
     "typesVersions": {
+        ">=3.7.0-0": {
+            "*": [
+                "ts3.7/*"
+            ]
+        },
         ">=3.5.0-0": {
             "*": [
                 "ts3.5/*"

types/node/ts3.2/base.d.ts

@@ -0,0 +1,22 @@
+// NOTE: These definitions support NodeJS and TypeScript 3.2.
+
+// NOTE: TypeScript version-specific augmentations can be found in the following paths:
+//          - ~/base.d.ts         - Shared definitions common to all TypeScript versions
+//          - ~/index.d.ts        - Definitions specific to TypeScript 2.1
+//          - ~/ts3.2/base.d.ts   - Definitions specific to TypeScript 3.2
+//          - ~/ts3.2/index.d.ts  - Definitions specific to TypeScript 3.2 with assert pulled in
+
+// Reference required types from the default lib:
+/// <reference lib="es2018" />
+/// <reference lib="esnext.asynciterable" />
+/// <reference lib="esnext.intl" />
+/// <reference lib="esnext.bigint" />
+
+// Base definitions for all NodeJS modules that are not specific to any version of TypeScript:
+// tslint:disable-next-line:no-bad-reference
+/// <reference path="../base.d.ts" />
+
+// TypeScript 3.2-specific augmentations:
+/// <reference path="fs.d.ts" />
+/// <reference path="util.d.ts" />
+/// <reference path="globals.d.ts" />

types/node/ts3.2/index.d.ts

@@ -1,16 +1,8 @@
 // NOTE: These definitions support NodeJS and TypeScript 3.2.
+// This is requried to enable typing assert in ts3.7 without causing errors
+// Typically type modifiations should be made in base.d.ts instead of here
 
-// Reference required types from the default lib:
-/// <reference lib="es2018" />
-/// <reference lib="esnext.asynciterable" />
-/// <reference lib="esnext.intl" />
-/// <reference lib="esnext.bigint" />
+/// <reference path="base.d.ts" />
 
-// Base definitions for all NodeJS modules that are not specific to any version of TypeScript:
 // tslint:disable-next-line:no-bad-reference
-/// <reference path="../base.d.ts" />
-
-// TypeScript 3.2-specific augmentations:
-/// <reference path="fs.d.ts" />
-/// <reference path="util.d.ts" />
-/// <reference path="globals.d.ts" />
+/// <reference path="../assert.d.ts" />

types/node/ts3.5/base.d.ts

@@ -0,0 +1,20 @@
+// NOTE: These definitions support NodeJS and TypeScript 3.5.
+
+// NOTE: TypeScript version-specific augmentations can be found in the following paths:
+//          - ~/base.d.ts         - Shared definitions common to all TypeScript versions
+//          - ~/index.d.ts        - Definitions specific to TypeScript 2.1
+//          - ~/ts3.5/base.d.ts   - Definitions specific to TypeScript 3.5
+//          - ~/ts3.5/index.d.ts  - Definitions specific to TypeScript 3.5 with assert pulled in
+
+// Reference required types from the default lib:
+/// <reference lib="es2018" />
+/// <reference lib="esnext.asynciterable" />
+/// <reference lib="esnext.intl" />
+/// <reference lib="esnext.bigint" />
+
+// Base definitions for all NodeJS modules that are not specific to any version of TypeScript:
+// tslint:disable-next-line:no-bad-reference
+/// <reference path="../ts3.2/base.d.ts" />
+
+// TypeScript 3.5-specific augmentations:
+/// <reference path="wasi.d.ts" />

types/node/ts3.5/index.d.ts

@@ -1,14 +1,8 @@
 // NOTE: These definitions support NodeJS and TypeScript 3.5.
+// This is requried to enable typing assert in ts3.7 without causing errors
+// Typically type modifiations should be made in base.d.ts instead of here
 
-// Reference required types from the default lib:
-/// <reference lib="es2018" />
-/// <reference lib="esnext.asynciterable" />
-/// <reference lib="esnext.intl" />
-/// <reference lib="esnext.bigint" />
+/// <reference path="base.d.ts" />
 
-// Base definitions for all NodeJS modules that are not specific to any version of TypeScript:
 // tslint:disable-next-line:no-bad-reference
-/// <reference path="../ts3.2/index.d.ts" />
-
-// TypeScript 3.5-specific augmentations:
-/// <reference path="wasi.d.ts" />
+/// <reference path="../assert.d.ts" />

types/node/ts3.7/assert.d.ts

@@ -0,0 +1,57 @@
+declare module "assert" {
+    function assert(value: any, message?: string | Error): asserts value;
+    namespace assert {
+        class AssertionError implements Error {
+            name: string;
+            message: string;
+            actual: any;
+            expected: any;
+            operator: string;
+            generatedMessage: boolean;
+            code: 'ERR_ASSERTION';
+
+            constructor(options?: {
+                message?: string; actual?: any; expected?: any;
+                operator?: string; stackStartFn?: Function
+            });
+        }
+
+        type AssertPredicate = RegExp | (new() => object) | ((thrown: any) => boolean) | object | Error;
+
+        function fail(message?: string | Error): never;
+        /** @deprecated since v10.0.0 - use fail([message]) or other assert functions instead. */
+        function fail(actual: any, expected: any, message?: string | Error, operator?: string, stackStartFn?: Function): never;
+        function ok(value: any, message?: string | Error): asserts value;
+        /** @deprecated since v9.9.0 - use strictEqual() instead. */
+        function equal(actual: any, expected: any, message?: string | Error): void;
+        /** @deprecated since v9.9.0 - use notStrictEqual() instead. */
+        function notEqual(actual: any, expected: any, message?: string | Error): void;
+        /** @deprecated since v9.9.0 - use deepStrictEqual() instead. */
+        function deepEqual(actual: any, expected: any, message?: string | Error): void;
+        /** @deprecated since v9.9.0 - use notDeepStrictEqual() instead. */
+        function notDeepEqual(actual: any, expected: any, message?: string | Error): void;
+        function strictEqual<T>(actual: any, expected: T, message?: string | Error): asserts actual is T;
+        function notStrictEqual(actual: any, expected: any, message?: string | Error): void;
+        function deepStrictEqual<T>(actual: any, expected: T, message?: string | Error): asserts actual is T;
+        function notDeepStrictEqual(actual: any, expected: any, message?: string | Error): void;
+
+        function throws(block: () => any, message?: string | Error): void;
+        function throws(block: () => any, error: AssertPredicate, message?: string | Error): void;
+        function doesNotThrow(block: () => any, message?: string | Error): void;
+        function doesNotThrow(block: () => any, error: RegExp | Function, message?: string | Error): void;
+
+        function ifError(value: any): asserts value is null | undefined;
+
+        function rejects(block: (() => Promise<any>) | Promise<any>, message?: string | Error): Promise<void>;
+        function rejects(block: (() => Promise<any>) | Promise<any>, error: AssertPredicate, message?: string | Error): Promise<void>;
+        function doesNotReject(block: (() => Promise<any>) | Promise<any>, message?: string | Error): Promise<void>;
+        function doesNotReject(block: (() => Promise<any>) | Promise<any>, error: RegExp | Function, message?: string | Error): Promise<void>;
+
+        function match(value: string, regExp: RegExp, message?: string | Error): void;
+        function doesNotMatch(value: string, regExp: RegExp, message?: string | Error): void;
+
+        const strict: typeof assert;
+    }
+
+    export = assert;
+}

types/node/ts3.7/base.d.ts

@@ -0,0 +1,20 @@
+// NOTE: These definitions support NodeJS and TypeScript 3.7.
+
+// NOTE: TypeScript version-specific augmentations can be found in the following paths:
+//          - ~/base.d.ts         - Shared definitions common to all TypeScript versions
+//          - ~/index.d.ts        - Definitions specific to TypeScript 2.1
+//          - ~/ts3.7/base.d.ts   - Definitions specific to TypeScript 3.7
+//          - ~/ts3.7/index.d.ts  - Definitions specific to TypeScript 3.7 with assert pulled in
+
+// Reference required types from the default lib:
+/// <reference lib="es2018" />
+/// <reference lib="esnext.asynciterable" />
+/// <reference lib="esnext.intl" />
+/// <reference lib="esnext.bigint" />
+
+// Base definitions for all NodeJS modules that are not specific to any version of TypeScript:
+// tslint:disable-next-line:no-bad-reference
+/// <reference path="../ts3.5/base.d.ts" />
+
+// TypeScript 3.7-specific augmentations:
+/// <reference path="assert.d.ts" />

types/node/ts3.7/index.d.ts

@@ -0,0 +1,5 @@
+// NOTE: These definitions support NodeJS and TypeScript 3.7.
+// This isn't strictly needed since 3.7 has the assert module, but this way we're consistent.
+// Typically type modificatons should be made in base.d.ts instead of here
+
+/// <reference path="base.d.ts" />

types/node/ts3.7/node-tests.ts

@@ -0,0 +1,59 @@
+import * as assert from 'assert';
+
+assert(true, "it's working");
+
+assert.ok(true, 'inner functions work as well');
+
+assert.throws(() => {});
+assert.throws(() => {}, /Regex test/);
+assert.throws(
+    () => {},
+    () => {},
+    'works wonderfully',
+);
+
+assert['fail'](true, true, 'works like a charm');
+
+{
+    const a = null as any;
+    assert.ifError(a);
+    a; // $ExpectType null | undefined
+}
+
+{
+    const a = true as boolean;
+    assert(a);
+    a; // $ExpectType true
+}
+
+{
+    // tslint:disable-next-line: no-null-undefined-union
+    const a = 13 as number | null | undefined;
+    assert(a);
+    a; // $ExpectType number
+}
+
+{
+    const a = true as boolean;
+    assert.ok(a);
+    a; // $ExpectType true
+}
+
+{
+    // tslint:disable-next-line: no-null-undefined-union
+    const a = 13 as number | null | undefined;
+    assert.ok(a);
+    a; // $ExpectType number
+}
+
+{
+    const a = 'test' as any;
+    assert.strictEqual(a, 'test');
+    a; // $ExpectType string
+}
+
+{
+    const a = { b: 2 } as any;
+    assert.deepStrictEqual(a, { b: 2 });
+    a; // $ExpectType { b: number; }
+}

types/node/ts3.7/tsconfig.json

@@ -0,0 +1,25 @@
+{
+    "files": [
+        "index.d.ts",
+        "node-tests.ts"
+    ],
+    "compilerOptions": {
+        "module": "commonjs",
+        "target": "esnext",
+        "lib": [
+            "es6",
+            "dom"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "baseUrl": "../../",
+        "typeRoots": [
+            "../../"
+        ],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    }
+}

types/node/ts3.7/tslint.json

@@ -0,0 +1,10 @@
+{
+  "extends": "dtslint/dt.json",
+  "rules": {
+    "ban-types": false,
+    "unified-signatures": false,
+    "no-empty-interface": false,
+    "no-single-declare-module": false,
+    "strict-export-declare-modifiers": false // http2 needs this
+  }
+}

types/node/v10/assert.d.ts

@@ -1,6 +1,6 @@
 declare module "assert" {
-    function internal(value: any, message?: string | Error): void;
-    namespace internal {
+    function assert(value: any, message?: string | Error): void;
+    namespace assert {
         class AssertionError implements Error {
             name: string;
             message: string;
@@ -45,8 +45,8 @@ declare module "assert" {
         function doesNotReject(block: Function | Promise<any>, message?: string | Error): Promise<void>;
         function doesNotReject(block: Function | Promise<any>, error: RegExp | Function, message?: string | Error): Promise<void>;
 
-        const strict: typeof internal;
+        const strict: typeof assert;
     }
 
-    export = internal;
+    export = assert;
 }

types/node/v10/base.d.ts

@@ -1,6 +1,5 @@
 // base definnitions for all NodeJS modules that are not specific to any version of TypeScript
 /// <reference path="globals.d.ts" />
-/// <reference path="assert.d.ts" />
 /// <reference path="async_hooks.d.ts" />
 /// <reference path="buffer.d.ts" />
 /// <reference path="child_process.d.ts" />

types/node/v10/index.d.ts

@@ -53,6 +53,9 @@
 // Base definitions for all NodeJS modules that are not specific to any version of TypeScript:
 /// <reference path="base.d.ts" />
 
+// We can't include assert.d.ts in base.d.ts, as it'll cause duplication errors in +ts3.7
+/// <reference path="assert.d.ts" />
+
 // TypeScript 2.1-specific augmentations:
 
 // Forward-declarations for needed types from es2015 and later (in case users are using `--lib es5`)

types/node/v10/package.json

@@ -2,6 +2,11 @@
     "private": true,
     "types": "index",
     "typesVersions": {
+        ">=3.7.0-0": {
+            "*": [
+                "ts3.7/*"
+            ]
+        },
         ">=3.2.0-0": {
             "*": [
                 "ts3.2/*"