Update Assert to v12

src/js/node/Assert.hx

@@ -22,145 +22,203 @@
 
 package js.node;
 
-import haxe.extern.EitherType;
 #if haxe4
 import js.lib.RegExp;
+import js.lib.Promise;
+import js.lib.Error;
 #else
 import js.RegExp;
+import js.Promise;
+import js.Error;
 #end
 
 /**
-	This module is used for writing unit tests for your applications
+	The `assert module` provides a set of assertion functions for verifying invariants.
+	The module provides a recommended [strict mode](https://nodejs.org/api/assert.html#assert_strict_mode) and a more lenient legacy mode.
+
+	@see https://nodejs.org/api/assert.html#assert_assert
 **/
 @:jsRequire("assert")
 extern class Assert {
 	/**
-		Throws an `AssertionError`. If `message` is falsy, the error message is set as the values of `actual` and `expected` separated by the provided `operator`.
-		Otherwise, the error message is the value of `message`.
+		In strict mode, assert functions use the comparison in the corresponding strict functions.
+		For example, `Assert.deepEqual()` will behave like `Assert.deepStrictEqual()`.
+
+		@see https://nodejs.org/api/assert.html#assert_strict_mode
 	**/
-	static function fail<T>(actual:T, expected:T, message:String, operator_:String):Void;
+	static var strict(default, never):Assert;
 
 	/**
-		Tests if value is truthy.
+		An alias of `Assert.ok()`.
 
-		An alias of `ok`.
+		@see https://nodejs.org/api/assert.html#assert_assert_value_message
 	**/
 	@:selfCall
-	static function assert(value:Bool, ?message:String):Void;
+	@:overload(function(value:Dynamic, ?message:Error):Void {})
+	static function assert(value:Dynamic, ?message:String):Void;
 
 	/**
-		Tests if value is truthy.
+		An alias of `Assert.deepStrictEqual()`.
 
-		If value is not truthy, an `AssertionError` is thrown with a `message` property set
-		equal to the value of the `message` parameter. If the `message` parameter is undefined,
-		a default error message is assigned.
+		@see https://nodejs.org/api/assert.html#assert_assert_deepequal_actual_expected_message
 	**/
-	static function ok(value:Bool, ?message:String):Void;
+	@:deprecated
+	@:overload(function<T>(actual:T, expected:T, ?message:Error):Void {})
+	static function deepEqual<T>(actual:T, expected:T, ?message:String):Void;
 
 	/**
-		Tests shallow, coercive equality between the `actual` and `expected` parameters using the JavaScript equal comparison operator ( `==` ).
+		Tests for deep equality between the `actual` and `expected` parameters.
+		"Deep" equality means that the enumerable "own" properties of child objects
+		are recursively evaluated also by the following rules.
 
-		If the values are not equal, an `AssertionError` is thrown with a `message` property set
-		equal to the value of the `message` parameter. If the `message` parameter is undefined,
-		a default error message is assigned.
+		@see https://nodejs.org/api/assert.html#assert_assert_deepstrictequal_actual_expected_message
 	**/
-	static function equal<T>(actual:T, expected:T, ?message:String):Void;
+	@:overload(function<T>(actual:T, expected:T, ?message:Error):Void {})
+	static function deepStrictEqual<T>(actual:T, expected:T, ?message:String):Void;
 
 	/**
-		Tests shallow, coercive inequality with the JavaScript not equal comparison operator ( `!=` ).
+		Awaits the `asyncFn` promise or, if `asyncFn` is a function,
+		immediately calls the function and awaits the returned promise to complete.
+		It will then check that the promise is not rejected.
 
-		If the values are equal, an `AssertionError` is thrown with a `message` property set
-		equal to the value of the `message` parameter. If the `message` parameter is undefined,
-		a default error message is assigned.
+		@see https://nodejs.org/api/assert.html#assert_assert_doesnotreject_asyncfn_error_message
 	**/
-	static function notEqual<T>(actual:T, expected:T, ?message:String):Void;
+	@:overload(function(asyncFn:Void->Promise<Dynamic>, ?error:Class<Dynamic>, ?message:String):Void {})
+	@:overload(function(asyncFn:Void->Promise<Dynamic>, ?error:RegExp, ?message:String):Void {})
+	@:overload(function(asyncFn:Void->Promise<Dynamic>, ?error:Dynamic->Bool, ?message:String):Void {})
+	@:overload(function(asyncFn:Promise<Dynamic>, ?error:Class<Dynamic>, ?message:String):Void {})
+	@:overload(function(asyncFn:Promise<Dynamic>, ?error:RegExp, ?message:String):Void {})
+	static function doesNotReject(asyncFn:Promise<Dynamic>, ?error:Dynamic->Bool, ?message:String):Void;
 
 	/**
-		Tests for deep equality between the `actual` and `expected` parameters.
-		Primitive values are compared with the JavaScript equal comparison operator ( `==` ).
+		Asserts that the function `fn` does not throw an error.
+
+		Using `Assert.doesNotThrow()` is actually not useful because there is no benefit
+		in catching an error and then rethrowing it.
+		Instead, consider adding a comment next to the specific code path that should not throw
+		and keep error messages as expressive as possible.
+
+		@see https://nodejs.org/api/assert.html#assert_assert_doesnotthrow_fn_error_message
 	**/
-	static function deepEqual<T>(actual:T, expected:T, ?message:String):Void;
+	@:overload(function(fn:Void->Void, ?error:Class<Dynamic>, ?message:String):Void {})
+	@:overload(function(fn:Void->Void, ?error:RegExp, ?message:String):Void {})
+	static function doesNotThrow(fn:Void->Void, ?error:Dynamic->Bool, ?message:String):Void;
 
 	/**
-		Generally identical to `deepEqual` with two exceptions.
-		First, primitive values are compared using the JavaScript strict equality operator ( `===` ).
-		Second, object comparisons include a strict equality check of their prototypes.
+		An alias of `strictEqual`.
+
+		@see https://nodejs.org/api/assert.html#assert_assert_equal_actual_expected_message
 	**/
-	static function deepStrictEqual<T>(actual:T, expected:T, ?message:String):Void;
+	@:overload(function<T>(actual:T, expected:T, ?message:String):Void {})
+	static function equal<T>(actual:T, expected:T, ?message:Error):Void;
+
+	/**
+		Throws an `AssertionError` with the provided error message or a default error message.
+		If the `message` parameter is an instance of an `Error` then it will be thrown instead of the `AssertionError`.
+
+		@see https://nodejs.org/api/assert.html#assert_assert_fail_message
+	**/
+	@:overload(function(?message:String):Void {})
+	static function fail(?message:Error):Void;
+
+	/**
+		Throws an `AssertionError`. If `message` is falsy, the error message is set as the values
+		of `actual` and `expected` separated by the provided `operator`.
+		Otherwise, the error message is the value of `message`.
+
+		@see https://nodejs.org/api/assert.html#assert_assert_fail_actual_expected_message_operator_stackstartfn
+	**/
+	@:deprecated
+	@:native("fail")
+	@:overload(function<T>(actual:T, expected:T, ?message:String, ?operator_:String, ?stackStartFn:haxe.Constraints.Function):Void {})
+	static function fail_<T>(actual:T, expected:T, ?message:Error, ?operator_:String, ?stackStartFn:haxe.Constraints.Function):Void;
+
+	/**
+		Throws `value` if `value` is not `undefined` or `null`.
+		This is useful when testing the `error` argument in callbacks.
+		The stack trace contains all frames from the error passed to `ifError()` including the potential new frames for `ifError()` itself.
+
+		@see https://nodejs.org/api/assert.html#assert_assert_iferror_value
+	**/
+	static function ifError(value:Dynamic):Void;
 
 	/**
-		Tests for any deep inequality. Opposite of `deepEqual`.
+		An alias of `Assert.notDeepStrictEqual()`.
 
-		If the values are deeply equal, an `AssertionError` is thrown with a `message` property set
-		equal to the value of the `message` parameter. If the `message` parameter is undefined,
-		a default error message is assigned.
+		@see https://nodejs.org/api/assert.html#assert_assert_notdeepequal_actual_expected_message
 	**/
+	@:deprecated
+	@:overload(function<T>(actual:T, expected:T, ?message:Error):Void {})
 	static function notDeepEqual<T>(actual:T, expected:T, ?message:String):Void;
 
 	/**
-		Tests for deep strict inequality. Opposite of `deepStrictEqual`.
+		Tests for deep strict inequality. Opposite of `Assert.deepStrictEqual()`.
 
-		If the values are deeply and strictly equal, an `AssertionError` is thrown with a `message` property set
-		equal to the value of the `message` parameter. If the `message` parameter is undefined,
-		a default error message is assigned.
+		@see https://nodejs.org/api/assert.html#assert_assert_notdeepstrictequal_actual_expected_message
 	**/
+	@:overload(function<T>(actual:T, expected:T, ?message:Error):Void {})
 	static function notDeepStrictEqual<T>(actual:T, expected:T, ?message:String):Void;
 
 	/**
-		Tests strict equality, as determined by the JavaScript strict equality operator (`===`)
+		An alias of `Assert.notStrictEqual()`.
 
-		If the values are not strictly equal, an `AssertionError` is thrown with a `message` property set
-		equal to the value of the `message` parameter. If the `message` parameter is undefined,
-		a default error message is assigned.
+		@see https://nodejs.org/api/assert.html#assert_assert_notequal_actual_expected_message
 	**/
-	static function strictEqual<T>(actual:T, expected:T, ?message:String):Void;
+	@:deprecated
+	@:overload(function<T>(actual:T, expected:T, ?message:Error):Void {})
+	static function notEqual<T>(actual:T, expected:T, ?message:String):Void;
 
 	/**
-		Tests strict non-equality, as determined by the strict not equal operator (`!==`)
+		Tests strict inequality between the `actual` and `expected` parameters as determined by the SameValue Comparison.
 
-		If the values are strictly equal, an `AssertionError` is thrown with a `message` property set
-		equal to the value of the `message` parameter. If the `message` parameter is undefined,
-		a default error message is assigned.
+		@see https://nodejs.org/api/assert.html#assert_assert_notstrictequal_actual_expected_message
 	**/
+	@:overload(function<T>(actual:T, expected:T, ?message:Error):Void {})
 	static function notStrictEqual<T>(actual:T, expected:T, ?message:String):Void;
 
 	/**
-		Expects `block` to throw an error.
+		Tests if `value` is truthy.
+		It is equivalent to `Assert.equal(!!value, true, message)`.
 
-		If specified, `error` can be a class, javascript RegExp, or validation function.
+		@see https://nodejs.org/api/assert.html#assert_assert_ok_value_message
+	**/
+	@:overload(function(value:Dynamic, ?message:Error):Void {})
+	static function ok(value:Dynamic, ?message:String):Void;
 
-		If specified, `message` will be the message provided by the `AssertionError` if the block fails to throw.
+	/**
+		Awaits the `asyncFn` promise or, if `asyncFn` is a function,
+		immediately calls the function and awaits the returned promise to complete.
+		It will then check that the promise is rejected.
 
-		Note that `error` can not be a string. If a string is provided as the second argument,
-		then error is assumed to be omitted and the string will be used for `message` instead.
+		@see https://nodejs.org/api/assert.html#assert_assert_rejects_asyncfn_error_message
 	**/
-	@:overload(function(block:Void->Void, ?message:String):Void {})
-	static function throws(block:Void->Void, error:ThrowsExpectedError, ?message:String):Void;
+	@:overload(function(asyncFn:Void->Promise<Dynamic>, ?error:Class<Dynamic>, ?message:String):Void {})
+	@:overload(function(asyncFn:Void->Promise<Dynamic>, ?error:RegExp, ?message:String):Void {})
+	@:overload(function(asyncFn:Void->Promise<Dynamic>, ?error:Dynamic->Bool, ?message:String):Void {})
+	@:overload(function(asyncFn:Void->Promise<Dynamic>, ?error:Dynamic, ?message:String):Void {})
+	@:overload(function(asyncFn:Void->Promise<Dynamic>, ?error:Error, ?message:String):Void {})
+	@:overload(function(asyncFn:Promise<Dynamic>, ?error:Class<Dynamic>, ?message:String):Void {})
+	@:overload(function(asyncFn:Promise<Dynamic>, ?error:RegExp, ?message:String):Void {})
+	@:overload(function(asyncFn:Promise<Dynamic>, ?error:Dynamic->Bool, ?message:String):Void {})
+	@:overload(function(asyncFn:Promise<Dynamic>, ?error:Dynamic, ?message:String):Void {})
+	static function rejects(asyncFn:Promise<Dynamic>, ?error:Error, ?message:String):Void;
 
 	/**
-		Asserts that the function `block` does not throw an error.
-		See `throws` for more details.
-
-		Will immediately call the `block` function.
+		Tests strict equality between the `actual` and `expected` parameter as
+		determined by the SameValue Comparison.
 
-		If an error is thrown and it is the same type as that specified by the `error` parameter,
-		then an `AssertionError` is thrown. If the error is of a different type, or if the `error`
-		parameter is undefined, the error is propagated back to the caller.
+		@see https://nodejs.org/api/assert.html#assert_assert_strictequal_actual_expected_message
 	**/
-	@:overload(function(block:Void->Void, ?message:String):Void {})
-	static function doesNotThrow(block:Void->Void, error:ThrowsExpectedError, ?message:String):Void;
+	@:overload(function<T>(actual:T, expected:T, ?message:Error):Void {})
+	static function strictEqual<T>(actual:T, expected:T, ?message:String):Void;
 
 	/**
-		Throws `value` if `value` is truthy.
-
-		A falsy value in JavaScript is false, null, undefined and 0.
+		Expects the function `fn` to throw an error.
 
-		Useful when testing the first argument, error in callbacks.
+		@see https://nodejs.org/api/assert.html#assert_assert_throws_fn_error_message
 	**/
-	static function ifError(value:Dynamic):Void;
+	@:overload(function(fn:Void->Void, ?error:RegExp, ?message:String):Void {})
+	@:overload(function(fn:Void->Void, ?error:Dynamic->Bool, ?message:String):Void {})
+	@:overload(function(fn:Void->Void, ?error:Dynamic, ?message:String):Void {})
+	static function throws(fn:Void->Void, ?error:Error, ?message:String):Void;
 }
-
-/**
-	a class, RegExp or function.
-**/
-private typedef ThrowsExpectedError = EitherType<Class<Dynamic>, EitherType<RegExp, Dynamic->Bool>>;

src/js/node/assert/AssertionError.hx

@@ -28,21 +28,72 @@ import js.lib.Error;
 import js.Error;
 #end
 
+/**
+	Indicates the failure of an assertion. All errors thrown by the `Assert` module will be instances of the `AssertionError` class.
+
+	@see https://nodejs.org/api/assert.html#assert_class_assert_assertionerror
+**/
+@:jsRequire("assert", "AssertionError")
+extern class AssertionError extends Error {
+	/**
+		A subclass of Error that indicates the failure of an assertion.
+	**/
+	function new(options:AssertionErrorOptions);
+
+	/**
+		Set to the `actual` argument for methods such as `Assert.strictEqual()`.
+	**/
+	var actual:Dynamic;
+
+	/**
+		Set to the `expected` value for methods such as `Assert.strictEqual()`.
+	**/
+	var expected:Dynamic;
+
+	/**
+		Indicates if the message was auto-generated (`true`) or not.
+	**/
+	var generatedMessage:Bool;
+
+	/**
+		Value is always `ERR_ASSERTION` to show that the error is an assertion error.
+	**/
+	var code:String;
+
+	/**
+		Set to the passed in operator value.
+	**/
+	@:native("operator") var operator_:String;
+}
+
+/**
+	An options type for `new` of `AssertionError`.
+**/
 typedef AssertionErrorOptions = {
+	/**
+		If provided, the error message is set to this value.
+	**/
+	@:optional var message:String;
+
+	/**
+		The `actual` property on the error instance.
+	**/
 	@:optional var actual:Dynamic;
+
+	/**
+		The `expected` property on the error instance.
+	**/
 	@:optional var expected:Dynamic;
+
 	#if (haxe_ver < 4)
+	/**
+		The `operator` property on the error instance.
+	**/
 	@:optional var operator:String;
 	#end
-	@:optional var message:String;
-	@:optional var stackStartFunction:Dynamic;
-}
 
-@:jsRequire("assert", "AssertionError")
-extern class AssertionError extends Error {
-	var actual:Dynamic;
-	var expected:Dynamic;
-	@:native("operator") var operator_:String;
-	var generatedMessage:Bool;
-	function new(options:AssertionErrorOptions);
+	/**
+		If provided, the generated stack trace omits frames before this function.
+	**/
+	@:optional var stackStartFunction:Dynamic;
 }