From 3d52d4bc12750ea098c140bcce704071f6b4a7de Mon Sep 17 00:00:00 2001
From: Giovanni <github@puskin.it>
Date: Sat, 31 Aug 2024 17:37:51 +0200
Subject: [PATCH] assert: renamed deepEqual/deepStrictEqual to
 partialDeepEqual/partialDeepStrictEqual

---
 doc/api/assert.md                    | 66 +++++++++----------
 lib/assert.js                        | 52 ++++++++++-----
 test/parallel/test-assert-objects.js | 95 +++++++++++++++++++---------
 3 files changed, 132 insertions(+), 81 deletions(-)

diff --git a/doc/api/assert.md b/doc/api/assert.md
index c1b2f8d728eea7..5572ce5284c564 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -2548,7 +2548,7 @@ assert.throws(throwingFirst, /Second$/);
 Due to the confusing error-prone notation, avoid a string as the second
 argument.
 
-## `assert.deepMatch(actual, expected[, message])`
+## `assert.partialDeepEqual(actual, expected[, message])`
 
 <!-- YAML
 added: REPLACEME
@@ -2558,54 +2558,54 @@ added: REPLACEME
 * `expected` {any}
 * `message` {string|Error}
 
-[`assert.deepMatch()`][] evaluates the equivalence between the `actual` and `expected` parameters by
+[`assert.partialDeepEqual()`][] evaluates the equivalence between the `actual` and `expected` parameters by
 performing a deep comparison. This function ensures that all properties defined
 in the `expected` parameter match those in the `actual` parameter in
 both value and type, allowing type coercion. The main difference with [`assert.deepEqual()`][] is that
-[`assert.deepMatch()`][] does not require all properties in the `actual` parameter to be present in the
+[`assert.partialDeepEqual()`][] does not require all properties in the `actual` parameter to be present in the
 `expected` parameter.
 
 ```mjs
 import assert from 'node:assert';
 
-assert.deepMatch({ a: 1, b: '2' }, { a: 1, b: 2 });
+assert.partialDeepEqual({ a: 1, b: '2' }, { a: 1, b: 2 });
 // OK
 
-assert.deepMatch({ a: 1, b: '2', c: 3 }, { a: 1, b: 2 });
+assert.partialDeepEqual({ a: 1, b: '2', c: 3 }, { a: 1, b: 2 });
 // OK
 
-assert.deepMatch({ a: { b: { c: '1' } } }, { a: { b: { c: 1 } } });
+assert.partialDeepEqual({ a: { b: { c: '1' } } }, { a: { b: { c: 1 } } });
 // OK
 
-assert.deepMatch({ a: 1 }, { a: 1, b: 2 });
+assert.partialDeepEqual({ a: 1 }, { a: 1, b: 2 });
 // AssertionError
 
-assert.deepMatch({ a: 1, b: true }, { a: 1, b: 'true' });
+assert.partialDeepEqual({ a: 1, b: true }, { a: 1, b: 'true' });
 // AssertionError
 
-assert.deepMatch({ a: { b: 2 } }, { a: { b: 2, c: 3 } });
+assert.partialDeepEqual({ a: { b: 2 } }, { a: { b: 2, c: 3 } });
 // AssertionError
 ```
 
 ```cjs
 const assert = require('node:assert');
 
-assert.deepMatch({ a: 1, b: '2' }, { a: 1, b: 2 });
+assert.partialDeepEqual({ a: 1, b: '2' }, { a: 1, b: 2 });
 // OK
 
-assert.deepMatch({ a: 1, b: '2', c: 3 }, { a: 1, b: 2 });
+assert.partialDeepEqual({ a: 1, b: '2', c: 3 }, { a: 1, b: 2 });
 // OK
 
-assert.deepMatch({ a: { b: { c: '1' } } }, { a: { b: { c: 1 } } });
+assert.partialDeepEqual({ a: { b: { c: '1' } } }, { a: { b: { c: 1 } } });
 // OK
 
-assert.deepMatch({ a: 1 }, { a: 1, b: 2 });
+assert.partialDeepEqual({ a: 1 }, { a: 1, b: 2 });
 // AssertionError: Expected key b
 
-assert.deepMatch({ a: 1, b: true }, { a: 1, b: 'true' });
+assert.partialDeepEqual({ a: 1, b: true }, { a: 1, b: 'true' });
 // AssertionError
 
-assert.deepMatch({ a: { b: 2, d: 4 } }, { a: { b: 2, c: 3 } });
+assert.partialDeepEqual({ a: { b: 2, d: 4 } }, { a: { b: 2, c: 3 } });
 // AssertionError: Expected key c
 ```
 
@@ -2615,7 +2615,7 @@ parameter is undefined, a default error message is assigned. If the `message`
 parameter is an instance of an [`Error`][] then it will be thrown instead of the
 `AssertionError`.
 
-## `assert.deepMatchStrict(actual, expected[, message])`
+## `assert.partialDeepStrictEqual(actual, expected[, message])`
 
 <!-- YAML
 added: REPLACEME
@@ -2625,53 +2625,53 @@ added: REPLACEME
 * `expected` {any}
 * `message` {string|Error}
 
-[`assert.deepMatchStrict()`][] Assesses the equivalence between the `actual` and `expected` parameters through a
+[`assert.partialDeepStrictEqual()`][] Assesses the equivalence between the `actual` and `expected` parameters through a
 deep comparison, ensuring that all properties in the `expected` parameter are
 present in the `actual` parameter with equivalent values, not allowing type coercion.
-The main difference with [`assert.deepStrictEqual()`][] is that [`assert.deepMatchStrict()`][] does not require all
-properties in the `actual` parameter to be present in the `expected` parameter.
+The main difference with [`assert.deepStrictEqual()`][] is that [`assert.partialDeepStrictEqual()`][] does not require
+all properties in the `actual` parameter to be present in the `expected` parameter.
 
 ```mjs
 import assert from 'node:assert';
 
-assert.deepMatchStrict({ a: 1, b: 2 }, { a: 1, b: 2 });
+assert.partialDeepStrictEqual({ a: 1, b: 2 }, { a: 1, b: 2 });
 // OK
 
-assert.deepMatchStrict({ a: { b: { c: 1 } } }, { a: { b: { c: 1 } } });
+assert.partialDeepStrictEqual({ a: { b: { c: 1 } } }, { a: { b: { c: 1 } } });
 // OK
 
-assert.deepMatchStrict({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 });
+assert.partialDeepStrictEqual({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 });
 // OK
 
-assert.deepMatchStrict({ a: 1 }, { a: 1, b: 2 });
+assert.partialDeepStrictEqual({ a: 1 }, { a: 1, b: 2 });
 // AssertionError
 
-assert.deepMatchStrict({ a: 1, b: '2' }, { a: 1, b: 2 });
+assert.partialDeepStrictEqual({ a: 1, b: '2' }, { a: 1, b: 2 });
 // AssertionError
 
-assert.deepMatchStrict({ a: { b: 2 } }, { a: { b: '2' } });
+assert.partialDeepStrictEqual({ a: { b: 2 } }, { a: { b: '2' } });
 // AssertionError
 ```
 
 ```cjs
 const assert = require('node:assert');
 
-assert.deepMatchStrict({ a: 1, b: 2 }, { a: 1, b: 2 });
+assert.partialDeepStrictEqual({ a: 1, b: 2 }, { a: 1, b: 2 });
 // OK
 
-assert.deepMatchStrict({ a: { b: { c: 1 } } }, { a: { b: { c: 1 } } });
+assert.partialDeepStrictEqual({ a: { b: { c: 1 } } }, { a: { b: { c: 1 } } });
 // OK
 
-assert.deepMatchStrict({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 });
+assert.partialDeepStrictEqual({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 });
 // OK
 
-assert.deepMatchStrict({ a: 1 }, { a: 1, b: 2 });
+assert.partialDeepStrictEqual({ a: 1 }, { a: 1, b: 2 });
 // AssertionError
 
-assert.deepMatchStrict({ a: 1, b: '2' }, { a: 1, b: 2 });
+assert.partialDeepStrictEqual({ a: 1, b: '2' }, { a: 1, b: 2 });
 // AssertionError
 
-assert.deepMatchStrict({ a: { b: 2 } }, { a: { b: '2' } });
+assert.partialDeepStrictEqual({ a: { b: 2 } }, { a: { b: '2' } });
 // AssertionError
 ```
 
@@ -2803,8 +2803,6 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
 [`WeakMap`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
 [`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet
 [`assert.deepEqual()`]: #assertdeepequalactual-expected-message
-[`assert.deepMatch()`]: #assertdeepmatchactual-expected-message
-[`assert.deepMatchStrict()`]: #assertdeepmatchstrictactual-expected-message
 [`assert.deepStrictEqual()`]: #assertdeepstrictequalactual-expected-message
 [`assert.doesNotThrow()`]: #assertdoesnotthrowfn-error-message
 [`assert.equal()`]: #assertequalactual-expected-message
@@ -2815,6 +2813,8 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
 [`assert.notEqual()`]: #assertnotequalactual-expected-message
 [`assert.notStrictEqual()`]: #assertnotstrictequalactual-expected-message
 [`assert.ok()`]: #assertokvalue-message
+[`assert.partialDeepEqual()`]: #assertpartialDeepEqualactual-expected-message
+[`assert.partialDeepStrictEqual()`]: #assertpartialDeepstrictEqualactual-expected-message
 [`assert.strictEqual()`]: #assertstrictequalactual-expected-message
 [`assert.throws()`]: #assertthrowsfn-error-message
 [`getColorDepth()`]: tty.md#writestreamgetcolordepthenv
diff --git a/lib/assert.js b/lib/assert.js
index 65fe84bbd0a895..79c367f609bfd5 100644
--- a/lib/assert.js
+++ b/lib/assert.js
@@ -21,12 +21,15 @@
 'use strict';
 
 const {
+  ArrayFrom,
   ArrayIsArray,
+  ArrayPrototypeEvery,
   ArrayPrototypeIndexOf,
   ArrayPrototypeJoin,
   ArrayPrototypePush,
   ArrayPrototypeShift,
   ArrayPrototypeSlice,
+  ArrayPrototypeSome,
   Error,
   ErrorCaptureStackTrace,
   FunctionPrototypeBind,
@@ -636,7 +639,7 @@ function assertIncludes(actual, expected, loose) {
     return StringPrototypeIncludes(actual, expected);
   }
 
-  return expected.every((item) => actual.some((actualItem) => {
+  return ArrayPrototypeEvery(expected, (item) => ArrayPrototypeSome(actual, (actualItem) => {
     // eslint-disable-next-line eqeqeq
     return loose ? actualItem == item : actualItem === item;
   }));
@@ -668,7 +671,11 @@ function compareBranch(
       return false;
     }
     const safeIterator = FunctionPrototypeCall(SafeMap.prototype[SymbolIterator], actual);
-    for (const { 0: key, 1: val } of safeIterator) {
+    const safeIteratorArray = ArrayFrom(safeIterator);
+
+    for (let i = 0; i < safeIteratorArray.length; i++) {
+      const { 0: key, 1: val } = safeIteratorArray[i];
+
       if (!MapPrototypeHas(expected, key)) {
         return false;
       }
@@ -685,8 +692,10 @@ function compareBranch(
       return false;
     }
     const safeIterator = FunctionPrototypeCall(SafeSet.prototype[SymbolIterator], actual);
-    for (const item of safeIterator) {
-      if (!SetPrototypeHas(expected, item)) {
+    const safeIteratorArray = ArrayFrom(safeIterator);
+
+    for (let i = 0; i < safeIteratorArray.length; i++) {
+      if (!SetPrototypeHas(expected, safeIteratorArray[i])) {
         return false;
       }
     }
@@ -706,16 +715,11 @@ function compareBranch(
     return loose ? isDeepEqual(actual, expected) : isDeepStrictEqual(actual, expected);
   }
 
-  // Check if actual and expected are null or not objects
-  if (actual == null || expected == null) {
-    return false;
-  }
-
   // Use Reflect.ownKeys() instead of Object.keys() to include symbol properties
   const keysExpected = ReflectOwnKeys(expected);
 
   // Handle circular references
-  if (comparedObjects.has(actual)) {
+  if (SetPrototypeHas(comparedObjects, actual)) {
     return true;
   }
   comparedObjects.add(actual);
@@ -742,7 +746,7 @@ function compareBranch(
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.deepMatchStrict = function deepMatchStrict(
+assert.partialDeepStrictEqual = function partialDeepStrictEqual(
   actual,
   expected,
   message,
@@ -756,8 +760,8 @@ assert.deepMatchStrict = function deepMatchStrict(
       actual,
       expected,
       message,
-      operator: 'deepMatchStrict',
-      stackStartFn: deepMatchStrict,
+      operator: 'partialDeepStrictEqual',
+      stackStartFn: partialDeepStrictEqual,
     });
   }
 };
@@ -769,7 +773,7 @@ assert.deepMatchStrict = function deepMatchStrict(
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.deepMatch = function deepMatch(actual, expected, message) {
+assert.partialDeepEqual = function partialDeepEqual(actual, expected, message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -779,12 +783,22 @@ assert.deepMatch = function deepMatch(actual, expected, message) {
       actual,
       expected,
       message,
-      operator: 'deepMatch',
-      stackStartFn: deepMatch,
+      operator: 'partialDeepEqual',
+      stackStartFn: partialDeepEqual,
     });
   }
 };
 
+function throwIfInvalidIncludesParams(actual, expected) {
+  if (typeof actual !== 'string' && !ArrayIsArray(actual)) {
+    throw new ERR_INVALID_ARG_TYPE('actual', ['string', 'Array'], actual);
+  }
+
+  if (typeof expected !== 'string' && !ArrayIsArray(expected)) {
+    throw new ERR_INVALID_ARG_TYPE('expected', ['string', 'Array'], expected);
+  }
+}
+
 /**
  * The inclusion assertion test between two arrays or strings
  * @param {Array | string} actual
@@ -797,6 +811,8 @@ assert.includes = function includes(actual, expected, message) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
 
+  throwIfInvalidIncludesParams(actual, expected);
+
   if (!assertIncludes(actual, expected, true)) {
     innerFail({
       actual,
@@ -821,6 +837,8 @@ assert.includesStrict = function includesStrict(actual, expected, message) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
 
+  throwIfInvalidIncludesParams(actual, expected);
+
   if (!assertIncludes(actual, expected, false)) {
     innerFail({
       actual,
@@ -1298,7 +1316,7 @@ assert.strict = ObjectAssign(strict, assert, {
   deepEqual: assert.deepStrictEqual,
   notEqual: assert.notStrictEqual,
   notDeepEqual: assert.notDeepStrictEqual,
-  deepMatch: assert.deepMatchStrict,
+  partialDeepEqual: assert.partialDeepStrictEqual,
   includes: assert.includesStrict,
 });
 
diff --git a/test/parallel/test-assert-objects.js b/test/parallel/test-assert-objects.js
index 91e1474c0a8eec..f00b4428fdb32c 100644
--- a/test/parallel/test-assert-objects.js
+++ b/test/parallel/test-assert-objects.js
@@ -35,7 +35,7 @@ async function generateCryptoKey() {
 }
 
 describe('Object Comparison Tests', () => {
-  describe('deepMatchStrict', () => {
+  describe('partialDeepStrictEqual', () => {
     describe('throws an error', () => {
       [
         {
@@ -193,7 +193,7 @@ describe('Object Comparison Tests', () => {
         },
       ].forEach(({ description, actual, expected }) => {
         it(description, () => {
-          assert.throws(() => assert.deepMatchStrict(actual, expected), Error);
+          assert.throws(() => assert.partialDeepStrictEqual(actual, expected), Error);
         });
       });
     });
@@ -214,6 +214,21 @@ describe('Object Comparison Tests', () => {
         actual: { a: 1, b: 'string' },
         expected: { b: 'string', a: 1 },
       },
+      {
+        description: 'compares two deeply nested objects with partial equality',
+        actual: { a: { nested: { property: true, some: 'other' } } },
+        expected: { a: { nested: { property: true } } },
+      },
+      {
+        description: 'compares two integers',
+        actual: 1,
+        expected: 1,
+      },
+      {
+        description: 'compares two strings',
+        actual: '1',
+        expected: '1',
+      },
       {
         description: 'compares two objects with nested objects',
         actual: createDeepNestedObject(),
@@ -388,24 +403,24 @@ describe('Object Comparison Tests', () => {
       },
       {
         description:
-          'compares one subset object with another, does not throw an error',
+          'compares one subset object with another',
         actual: { a: 1, b: 2, c: 3 },
         expected: { b: 2 },
       },
       {
         description:
-          'compares one subset array with another, does not throw an error',
+          'compares one subset array with another',
         actual: [1, 2, 3],
         expected: [2],
       },
     ].forEach(({ description, actual, expected }) => {
       it(description, () => {
-        assert.deepMatchStrict(actual, expected);
+        assert.partialDeepStrictEqual(actual, expected);
       });
     });
   });
 
-  describe('deepMatch', () => {
+  describe('partialDeepEqual', () => {
     describe('throws an error', () => {
       [
         {
@@ -416,7 +431,7 @@ describe('Object Comparison Tests', () => {
         },
         {
           description:
-            'deepMatch throws when comparing two objects with null and empty object',
+            'partialDeepEqual throws when comparing two objects with null and empty object',
           actual: { a: null },
           expected: { a: {} },
         },
@@ -437,7 +452,7 @@ describe('Object Comparison Tests', () => {
         },
       ].forEach(({ description, actual, expected }) => {
         it(description, () => {
-          assert.throws(() => assert.deepMatch(actual, expected), Error);
+          assert.throws(() => assert.partialDeepEqual(actual, expected), Error);
         });
       });
     });
@@ -522,7 +537,7 @@ describe('Object Comparison Tests', () => {
         },
       ].forEach(({ description, actual, expected }) => {
         it(description, () => {
-          assert.deepMatch(actual, expected);
+          assert.partialDeepEqual(actual, expected);
         });
       });
     });
@@ -531,31 +546,40 @@ describe('Object Comparison Tests', () => {
     describe('throws an error', () => {
       [
         {
-          description: 'throws because only one argument is provided',
-          actual: () => assert.includesStrict({ a: 1 }),
-          expected: Error,
+          description: 'throws because actual is nor an Array or a string',
+          actual: { a: 1 },
+          expected: [1],
+          errorCode: 'ERR_INVALID_ARG_TYPE'
+        },
+        {
+          description: 'throws because expected is nor an Array or a string',
+          actual: [1],
+          expected: { a: 1 },
+          errorCode: 'ERR_INVALID_ARG_TYPE'
         },
         {
           description:
             'throws when comparing one subset array with another',
-          actual: () => assert.includesStrict([1, 2, 3], ['2']),
-          expected: Error,
+          actual: [1, 2, 3],
+          expected: ['2'],
         },
         {
           description:
             'throws when comparing one subset string with another',
-          actual: () => assert.includesStrict('abc', '2'),
-          expected: Error,
+          actual: 'abc',
+          expected: '2',
         },
         {
           description:
             'throws because the expected value is longer than the actual value',
-          actual: () => assert.includesStrict('abc', 'abcd'),
-          expected: Error,
+          actual: 'abc',
+          expected: 'abcd',
         },
-      ].forEach(({ description, actual, expected }) => {
+      ].forEach(({ description, actual, expected, errorCode }) => {
         it(description, () => {
-          assert.throws(actual, expected);
+          assert.throws(() => assert.includesStrict(actual, expected), errorCode ?
+            { code: errorCode } :
+            assert.AssertionError);
         });
       });
     });
@@ -564,13 +588,13 @@ describe('Object Comparison Tests', () => {
       [
         {
           description:
-            'compares one subset array with another, it does not throw an error',
+            'compares one subset array with another',
           actual: [1, 2, 3],
           expected: [2],
         },
         {
           description:
-            'compares one subset string with another, it does not throw an error',
+            'compares one subset string with another',
           actual: 'abc',
           expected: 'b',
         },
@@ -586,25 +610,34 @@ describe('Object Comparison Tests', () => {
     describe('throws an error', () => {
       [
         {
-          description: 'throws because only one argument is provided',
-          actual: () => assert.includes({ a: 1 }),
-          expected: Error,
+          description: 'throws because actual is nor an Array or a string',
+          actual: { a: 1 },
+          expected: [1],
+          errorCode: 'ERR_INVALID_ARG_TYPE'
+        },
+        {
+          description: 'throws because expected is nor an Array or a string',
+          actual: [1],
+          expected: { a: 1 },
+          errorCode: 'ERR_INVALID_ARG_TYPE'
         },
         {
           description:
             'throws because using includes with a string and an array',
-          actual: () => assert.includes('abc', ['a', 'b', 'c']),
-          expected: Error,
+          actual: 'abc',
+          expected: ['a', 'b', 'c'],
         },
         {
           description:
             'throws because the expected value is longer than the actual value',
-          actual: () => assert.includes('abc', 'abcd'),
-          expected: Error,
+          actual: 'abc',
+          expected: 'abcd',
         },
-      ].forEach(({ description, actual, expected }) => {
+      ].forEach(({ description, actual, expected, errorCode }) => {
         it(description, () => {
-          assert.throws(actual, expected);
+          assert.throws(() => assert.includes(actual, expected), errorCode ?
+            { code: errorCode } :
+            assert.AssertionError);
         });
       });
     });