assert: add strict functionality export

Requireing the strict version will allow to use `assert.equal`,
`assert.deepEqual` and there negated counterparts to be used with
strict comparison instead of using e.g. `assert.strictEqual`.

The API is identical to the regular assert export and only differs
in the way that all functions use strict compairson.

PR-URL: https://github.com/nodejs/node/pull/17002
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

1 files changed, 92 insertions, 8 deletions

diff --git a/doc/api/assert.md b/doc/api/assert.md
index e6d267ff63..11def69df9 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -7,9 +7,57 @@
 The `assert` module provides a simple set of assertion tests that can be used to
 test invariants.
 
+A `strict` and a `legacy` mode exist, while it is recommended to only use
+[`strict mode`][].
+
 For more information about the used equality comparisons see
 [MDN's guide on equality comparisons and sameness][mdn-equality-guide].
 
+## Strict mode
+<!-- YAML
+added: REPLACEME
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/17002
+    description: Added strict mode to the assert module.
+-->
+
+When using the `strict mode`, any `assert` function will use the equality used in
+the strict function mode. So [`assert.deepEqual()`][] will, for example, work the
+same as [`assert.deepStrictEqual()`][].
+
+It can be accessed using:
+
+```js
+const assert = require('assert').strict;
+```
+
+## Legacy mode
+
+> Stability: 0 - Deprecated: Use strict mode instead.
+
+When accessing `assert` directly instead of using the `strict` property, the
+[Abstract Equality Comparison][] will be used for any function without a
+"strict" in its name (e.g. [`assert.deepEqual()`][]).
+
+It can be accessed using:
+
+```js
+const assert = require('assert');
+```
+
+It is recommended to use the [`strict mode`][] instead as the
+[Abstract Equality Comparison][] can often have surprising results. Especially
+in case of [`assert.deepEqual()`][] as the used comparison rules there are very
+lax.
+
+E.g.
+
+```js
+// WARNING: This does not throw an AssertionError!
+assert.deepEqual(/a/gi, new Date());
+```
+
 ## assert(value[, message])
 <!-- YAML
 added: v0.5.9
@@ -43,6 +91,14 @@ changes:
 * `expected` {any}
 * `message` {any}
 
+**Strict mode**
+
+An alias of [`assert.deepStrictEqual()`][].
+
+**Legacy mode**
+
+> Stability: 0 - Deprecated: Use [`assert.deepStrictEqual()`][] instead.
+
 Tests for deep equality between the `actual` and `expected` parameters.
 Primitive values are compared with the [Abstract Equality Comparison][]
 ( `==` ).
@@ -147,7 +203,7 @@ are recursively evaluated also by the following rules.
   [`Object.is()`][].
 * [Type tags][Object.prototype.toString()] of objects should be the same.
 * [`[[Prototype]]`][prototype-spec] of objects are compared using
-  the [Strict Equality Comparison][] too.
+  the [Strict Equality Comparison][].
 * Only [enumerable "own" properties][] are considered.
 * [`Error`][] names and messages are always compared, even if these are not
   enumerable properties.
@@ -159,7 +215,7 @@ are recursively evaluated also by the following rules.
   reference.
 
 ```js
-const assert = require('assert');
+const assert = require('assert').strict;
 
 assert.deepStrictEqual({ a: 1 }, { a: '1' });
 // AssertionError: { a: 1 } deepStrictEqual { a: '1' }
@@ -279,6 +335,14 @@ added: v0.1.21
 * `expected` {any}
 * `message` {any}
 
+**Strict mode**
+
+An alias of [`assert.strictEqual()`][].
+
+**Legacy mode**
+
+> Stability: 0 - Deprecated: Use [`assert.strictEqual()`][] instead.
+
 Tests shallow, coercive equality between the `actual` and `expected` parameters
 using the [Abstract Equality Comparison][] ( `==` ).
 
@@ -325,7 +389,7 @@ all stack frames above that function will be removed from stacktrace (see
 `Failed` will be used.
 
 ```js
-const assert = require('assert');
+const assert = require('assert').strict;
 
 assert.fail(1, 2, undefined, '>');
 // AssertionError [ERR_ASSERTION]: 1 > 2
@@ -376,7 +440,7 @@ Throws `value` if `value` is truthy. This is useful when testing the `error`
 argument in callbacks.
 
 ```js
-const assert = require('assert');
+const assert = require('assert').strict;
 
 assert.ifError(0);
 // OK
@@ -412,6 +476,14 @@ changes:
 * `expected` {any}
 * `message` {any}
 
+**Strict mode**
+
+An alias of [`assert.notDeepStrictEqual()`][].
+
+**Legacy mode**
+
+> Stability: 0 - Deprecated: Use [`assert.notDeepStrictEqual()`][] instead.
+
 Tests for any deep inequality. Opposite of [`assert.deepEqual()`][].
 
 ```js
@@ -486,7 +558,7 @@ changes:
 Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
 
 ```js
-const assert = require('assert');
+const assert = require('assert').strict;
 
 assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
 // OK
@@ -506,6 +578,14 @@ added: v0.1.21
 * `expected` {any}
 * `message` {any}
 
+**Strict mode**
+
+An alias of [`assert.notStrictEqual()`][].
+
+**Legacy mode**
+
+> Stability: 0 - Deprecated: Use [`assert.notStrictEqual()`][] instead.
+
 Tests shallow, coercive inequality with the [Abstract Equality Comparison][]
 ( `!=` ).
 
@@ -544,7 +624,7 @@ Tests strict inequality between the `actual` and `expected` parameters as
 determined by the [SameValue Comparison][].
 
 ```js
-const assert = require('assert');
+const assert = require('assert').strict;
 
 assert.notStrictEqual(1, 2);
 // OK
@@ -579,7 +659,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
 `AssertionError`.
 
 ```js
-const assert = require('assert');
+const assert = require('assert').strict;
 
 assert.ok(true);
 // OK
@@ -609,7 +689,7 @@ Tests strict equality between the `actual` and `expected` parameters as
 determined by the [SameValue Comparison][].
 
 ```js
-const assert = require('assert');
+const assert = require('assert').strict;
 
 assert.strictEqual(1, 2);
 // AssertionError: 1 strictEqual 2
@@ -707,8 +787,12 @@ assert.throws(myFunction, /missing foo/, 'did not throw with expected message');
 [`TypeError`]: errors.html#errors_class_typeerror
 [`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message
 [`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message
+[`assert.notDeepStrictEqual()`]: #assert_assert_notdeepstrictequal_actual_expected_message
+[`assert.notStrictEqual()`]: #assert_assert_notstrictequal_actual_expected_message
 [`assert.ok()`]: #assert_assert_ok_value_message
+[`assert.strictEqual()`]: #assert_assert_strictequal_actual_expected_message
 [`assert.throws()`]: #assert_assert_throws_block_error_message
+[`strict mode`]: #assert_strict_mode
 [Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison
 [Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring
 [SameValue Comparison]: https://tc39.github.io/ecma262/#sec-samevalue