util,assert: expose util.isPartialDeepStrictEqual()

Signed-off-by: Thomas Hunter II <tlhunter@datadog.com>

Author: tlhunter

doc/api/util.md

@@ -1898,6 +1898,25 @@ console.log(util.isDeepStrictEqual(foo, bar, true));
 See [`assert.deepStrictEqual()`][] for more information about deep strict
 equality.
 
+## `util.isPartialDeepStrictEqual(val1, val2)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `val1` {any}
+* `val2` {any}
+* Returns: {boolean}
+
+Returns `true` if there is partial deep strict equality between `val1` and
+`val2`. Otherwise, returns `false`.
+
+"Partial" equality means that only properties that exist on `val2` are going
+to be compared.
+
+See [`assert.partialDeepStrictEqual()`][] for more information about partial
+deep strict equality.
+
 ## `util.markPromiseAsHandled(promise)`
 
 <!-- YAML
@@ -4145,6 +4164,7 @@ npx codemod@latest @nodejs/util-is
 [`Object.freeze()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze
 [`Runtime.ScriptId`]: https://chromedevtools.github.io/devtools-protocol/1-3/Runtime/#type-ScriptId
 [`assert.deepStrictEqual()`]: assert.md#assertdeepstrictequalactual-expected-message
+[`assert.partialDeepStrictEqual()`]: assert.md#assertpartialdeepstrictequalactual-expected-message
 [`console.error()`]: console.md#consoleerrordata-args
 [`mime.toString()`]: #mimetostring
 [`mimeParams.entries()`]: #mimeparamsentries

lib/util.js

@@ -107,6 +107,7 @@ function lazyAbortController() {
 }
 
 let internalDeepEqual;
+let internalPartialDeepEqual;
 
 // Pre-computed ANSI escape code constants
 const kEscape = '\u001b[';
@@ -625,6 +626,12 @@ module.exports = {
     }
     return internalDeepEqual(a, b, skipPrototype);
   },
+  isPartialDeepStrictEqual(a, b) {
+    if (internalPartialDeepEqual === undefined) {
+      internalPartialDeepEqual = require('internal/util/comparisons').isPartialStrictEqual;
+    }
+    return internalPartialDeepEqual(a, b);
+  },
   markPromiseAsHandled,
   promisify,
   stripVTControlCharacters,

test/parallel/test-util-isPartialDeepStrictEqual.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// Confirm functionality of `util.isPartialDeepStrictEqual()`.
+
+require('../common');
+
+const assert = require('assert');
+const util = require('util');
+const { test } = require('node:test');
+
+test('util.isPartialDeepStrictEqual returns true with expected properties', () => {
+  assert.strictEqual(
+    util.isPartialDeepStrictEqual({ a: 1, b: 2, c: 3 }, { b: 2 }),
+    true,
+  );
+
+  assert.strictEqual(
+    util.isPartialDeepStrictEqual({ a: { b: { c: 1 } } }, { a: { b: { c: 1 } } }),
+    true,
+  );
+
+  assert.strictEqual(
+    util.isPartialDeepStrictEqual([1, 2, 3, 4, 5, 6, 7, 8, 9], [4, 5, 8]),
+    true,
+  );
+
+  {
+    const obj = { a: 1 };
+    assert.strictEqual(
+      util.isPartialDeepStrictEqual(obj, obj),
+      true,
+    );
+  }
+
+  assert.strictEqual(
+    util.isPartialDeepStrictEqual({ a: 1, b: 2 }, { b: 2, a: 1 }),
+    true,
+  );
+});
+
+test('util.isPartialDeepStrictEqual returns false with unexpected properties', () => {
+  assert.strictEqual(
+    util.isPartialDeepStrictEqual({ a: 1 }, { a: 2 }),
+    false,
+  );
+
+  assert.strictEqual(
+    util.isPartialDeepStrictEqual({ a: 1 }, { b: 1 }),
+    false,
+  );
+
+  assert.strictEqual(
+    util.isPartialDeepStrictEqual([1, 'two'], [1, 'two', true]),
+    false,
+  );
+});