lib: update isDeepStrictEqual to support options

miguelmarcondesf · targos · commit fed1dac8de76 · 2025-09-24T09:03:35.000+02:00
PR-URL: #59762 Reviewed-By: Jordan Harband <ljharb@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
diff --git a/doc/api/assert.md b/doc/api/assert.md
@@ -227,11 +227,20 @@ The `Assert` class allows creating independent assertion instances with custom o
 
 ### `new assert.Assert([options])`
 
+<!-- YAML
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/59762
+ description: Added `skipPrototype` option.
+-->
+
 * `options` {Object}
 * `diff` {string} If set to `'full'`, shows the full diff in assertion errors. Defaults to `'simple'`.
 Accepted values: `'simple'`, `'full'`.
 * `strict` {boolean} If set to `true`, non-strict methods behave like their
 corresponding strict methods. Defaults to `true`.
+ * `skipPrototype` {boolean} If set to `true`, skips prototype and constructor
+ comparison in deep equality checks. Defaults to `false`.
 
 Creates a new assertion instance. The `diff` option controls the verbosity of diffs in assertion error messages.
 
@@ -243,7 +252,8 @@ assertInstance.deepStrictEqual({ a: 1 }, { a: 2 });
 ```
 
 **Important**: When destructuring assertion methods from an `Assert` instance,
-the methods lose their connection to the instance's configuration options (such as `diff` and `strict` settings).
+the methods lose their connection to the instance's configuration options (such
+as `diff`, `strict`, and `skipPrototype` settings).
 The destructured methods will fall back to default behavior instead.
 
 ```js
@@ -257,6 +267,33 @@ const { strictEqual } = myAssert;
 strictEqual({ a: 1 }, { b: { c: 1 } });
 ```
 
+The `skipPrototype` option affects all deep equality methods:
+
+```js
+class Foo {
+ constructor(a) {
+ this.a = a;
+ }
+}
+
+class Bar {
+ constructor(a) {
+ this.a = a;
+ }
+}
+
+const foo = new Foo(1);
+const bar = new Bar(1);
+
+// Default behavior - fails due to different constructors
+const assert1 = new Assert();
+assert1.deepStrictEqual(foo, bar); // AssertionError
+
+// Skip prototype comparison - passes if properties are equal
+const assert2 = new Assert({ skipPrototype: true });
+assert2.deepStrictEqual(foo, bar); // OK
+```
+
 When destructured, methods lose access to the instance's `this` context and revert to default assertion behavior
 (diff: 'simple', non-strict mode).
 To maintain custom options when using destructured methods, avoid
diff --git a/doc/api/util.md b/doc/api/util.md
@@ -1551,19 +1551,56 @@ inspect.defaultOptions.maxArrayLength = null;
 console.log(arr); // logs the full array
 ```
 
-## `util.isDeepStrictEqual(val1, val2)`
+## `util.isDeepStrictEqual(val1, val2[, options])`
 
 <!-- YAML
 added: v9.0.0
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/59762
+ description: Added `options` parameter to allow skipping prototype comparison.
 -->
 
 * `val1` {any}
 * `val2` {any}
+* `skipPrototype` {boolean} If `true`, prototype and constructor
+ comparison is skipped during deep strict equality check. **Default:** `false`.
 * Returns: {boolean}
 
 Returns `true` if there is deep strict equality between `val1` and `val2`.
 Otherwise, returns `false`.
 
+By default, deep strict equality includes comparison of object prototypes and
+constructors. When `skipPrototype` is `true`, objects with
+different prototypes or constructors can still be considered equal if their
+enumerable properties are deeply strictly equal.
+
+```js
+const util = require('node:util');
+
+class Foo {
+ constructor(a) {
+ this.a = a;
+ }
+}
+
+class Bar {
+ constructor(a) {
+ this.a = a;
+ }
+}
+
+const foo = new Foo(1);
+const bar = new Bar(1);
+
+// Different constructors, same properties
+console.log(util.isDeepStrictEqual(foo, bar));
+// false
+
+console.log(util.isDeepStrictEqual(foo, bar, true));
+// true
+```
+
 See [`assert.deepStrictEqual()`][] for more information about deep strict
 equality.
 
diff --git a/lib/assert.js b/lib/assert.js
@@ -96,6 +96,8 @@ const NO_EXCEPTION_SENTINEL = {};
 * @property {'full'|'simple'} [diff='simple'] - If set to 'full', shows the full diff in assertion errors.
 * @property {boolean} [strict=true] - If set to true, non-strict methods behave like their corresponding
 * strict methods.
+ * @property {boolean} [skipPrototype=false] - If set to true, skips comparing prototypes
+ * in deep equality checks.
 */
 
 /**
@@ -108,7 +110,7 @@ function Assert(options) {
 throw new ERR_CONSTRUCT_CALL_REQUIRED('Assert');
 }
 
- options = ObjectAssign({ __proto__: null, strict: true }, options);
+ options = ObjectAssign({ __proto__: null, strict: true, skipPrototype: false }, options);
 
 const allowedDiffs = ['simple', 'full'];
 if (options.diff !== undefined) {
@@ -336,7 +338,7 @@ Assert.prototype.deepStrictEqual = function deepStrictEqual(actual, expected, me
 throw new ERR_MISSING_ARGS('actual', 'expected');
 }
 if (isDeepEqual === undefined) lazyLoadComparison();
- if (!isDeepStrictEqual(actual, expected)) {
+ if (!isDeepStrictEqual(actual, expected, this?.[kOptions]?.skipPrototype)) {
 innerFail({
 actual,
 expected,
@@ -362,7 +364,7 @@ function notDeepStrictEqual(actual, expected, message) {
 throw new ERR_MISSING_ARGS('actual', 'expected');
 }
 if (isDeepEqual === undefined) lazyLoadComparison();
- if (isDeepStrictEqual(actual, expected)) {
+ if (isDeepStrictEqual(actual, expected, this?.[kOptions]?.skipPrototype)) {
 innerFail({
 actual,
 expected,
diff --git a/lib/internal/util/comparisons.js b/lib/internal/util/comparisons.js
@@ -126,9 +126,10 @@ const {
 getOwnNonIndexProperties,
 } = internalBinding('util');
 
-const kStrict = 1;
+const kStrict = 2;
+const kStrictWithoutPrototypes = 3;
 const kLoose = 0;
-const kPartial = 2;
+const kPartial = 1;
 
 const kNoIterator = 0;
 const kIsArray = 1;
@@ -452,7 +453,7 @@ function keyCheck(val1, val2, mode, memos, iterationType, keys2) {
 }
 } else if (keys2.length !== (keys1 = ObjectKeys(val1)).length) {
 return false;
- } else if (mode === kStrict) {
+ } else if (mode === kStrict || mode === kStrictWithoutPrototypes) {
 const symbolKeysA = getOwnSymbols(val1);
 if (symbolKeysA.length !== 0) {
 let count = 0;
@@ -1021,7 +1022,10 @@ module.exports = {
 isDeepEqual(val1, val2) {
 return detectCycles(val1, val2, kLoose);
 },
- isDeepStrictEqual(val1, val2) {
+ isDeepStrictEqual(val1, val2, skipPrototype) {
+ if (skipPrototype) {
+ return detectCycles(val1, val2, kStrictWithoutPrototypes);
+ }
 return detectCycles(val1, val2, kStrict);
 },
 isPartialStrictEqual(val1, val2) {
diff --git a/lib/util.js b/lib/util.js
@@ -487,12 +487,11 @@ module.exports = {
 isArray: deprecate(ArrayIsArray,
 'The `util.isArray` API is deprecated. Please use `Array.isArray()` instead.',
 'DEP0044'),
- isDeepStrictEqual(a, b) {
+ isDeepStrictEqual(a, b, skipPrototype) {
 if (internalDeepEqual === undefined) {
- internalDeepEqual = require('internal/util/comparisons')
- .isDeepStrictEqual;
+ internalDeepEqual = require('internal/util/comparisons').isDeepStrictEqual;
 }
- return internalDeepEqual(a, b);
+ return internalDeepEqual(a, b, skipPrototype);
 },
 promisify,
 stripVTControlCharacters,
diff --git a/test/parallel/test-assert-class.js b/test/parallel/test-assert-class.js
@@ -478,3 +478,163 @@ test('Assert class non strict with simple diff', () => {
 );
 }
 });
+
+// Shared setup for skipPrototype tests
+{
+ const message = 'Expected values to be strictly deep-equal:\n' +
+ '+ actual - expected\n' +
+ '\n' +
+ ' [\n' +
+ ' 1,\n' +
+ ' 2,\n' +
+ ' 3,\n' +
+ ' 4,\n' +
+ ' 5,\n' +
+ '+ 6,\n' +
+ '- 9,\n' +
+ ' 7\n' +
+ ' ]\n';
+
+ function CoolClass(name) { this.name = name; }
+
+ function AwesomeClass(name) { this.name = name; }
+
+ class Modern { constructor(value) { this.value = value; } }
+ class Legacy { constructor(value) { this.value = value; } }
+
+ const cool = new CoolClass('Assert is inspiring');
+ const awesome = new AwesomeClass('Assert is inspiring');
+ const modern = new Modern(42);
+ const legacy = new Legacy(42);
+
+ test('Assert class strict with skipPrototype', () => {
+ const assertInstance = new Assert({ skipPrototype: true });
+
+ assert.throws(
+ () => assertInstance.deepEqual([1, 2, 3, 4, 5, 6, 7], [1, 2, 3, 4, 5, 9, 7]),
+ { message }
+ );
+
+ assertInstance.deepEqual(cool, awesome);
+ assertInstance.deepStrictEqual(cool, awesome);
+ assertInstance.deepEqual(modern, legacy);
+ assertInstance.deepStrictEqual(modern, legacy);
+
+ const cool2 = new CoolClass('Soooo coooool');
+ assert.throws(
+ () => assertInstance.deepStrictEqual(cool, cool2),
+ { code: 'ERR_ASSERTION' }
+ );
+
+ const nested1 = { obj: new CoolClass('test'), arr: [1, 2, 3] };
+ const nested2 = { obj: new AwesomeClass('test'), arr: [1, 2, 3] };
+ assertInstance.deepStrictEqual(nested1, nested2);
+
+ const arr = new Uint8Array([1, 2, 3]);
+ const buf = Buffer.from([1, 2, 3]);
+ assertInstance.deepStrictEqual(arr, buf);
+ });
+
+ test('Assert class non strict with skipPrototype', () => {
+ const assertInstance = new Assert({ strict: false, skipPrototype: true });
+
+ assert.throws(
+ () => assertInstance.deepStrictEqual([1, 2, 3, 4, 5, 6, 7], [1, 2, 3, 4, 5, 9, 7]),
+ { message }
+ );
+
+ assertInstance.deepStrictEqual(cool, awesome);
+ assertInstance.deepStrictEqual(modern, legacy);
+ });
+
+ test('Assert class skipPrototype with complex objects', () => {
+ const assertInstance = new Assert({ skipPrototype: true });
+
+ function ComplexAwesomeClass(name, age) {
+ this.name = name;
+ this.age = age;
+ this.settings = {
+ theme: 'dark',
+ lang: 'en'
+ };
+ }
+
+ function ComplexCoolClass(name, age) {
+ this.name = name;
+ this.age = age;
+ this.settings = {
+ theme: 'dark',
+ lang: 'en'
+ };
+ }
+
+ const awesome1 = new ComplexAwesomeClass('Foo', 30);
+ const cool1 = new ComplexCoolClass('Foo', 30);
+
+ assertInstance.deepStrictEqual(awesome1, cool1);
+
+ const cool2 = new ComplexCoolClass('Foo', 30);
+ cool2.settings.theme = 'light';
+
+ assert.throws(
+ () => assertInstance.deepStrictEqual(awesome1, cool2),
+ { code: 'ERR_ASSERTION' }
+ );
+ });
+
+ test('Assert class skipPrototype with arrays and special objects', () => {
+ const assertInstance = new Assert({ skipPrototype: true });
+
+ const arr1 = [1, 2, 3];
+ const arr2 = new Array(1, 2, 3);
+ assertInstance.deepStrictEqual(arr1, arr2);
+
+ const date1 = new Date('2023-01-01');
+ const date2 = new Date('2023-01-01');
+ assertInstance.deepStrictEqual(date1, date2);
+
+ const regex1 = /test/g;
+ const regex2 = new RegExp('test', 'g');
+ assertInstance.deepStrictEqual(regex1, regex2);
+
+ const date3 = new Date('2023-01-02');
+ assert.throws(
+ () => assertInstance.deepStrictEqual(date1, date3),
+ { code: 'ERR_ASSERTION' }
+ );
+ });
+
+ test('Assert class skipPrototype with notDeepStrictEqual', () => {
+ const assertInstance = new Assert({ skipPrototype: true });
+
+ assert.throws(
+ () => assertInstance.notDeepStrictEqual(cool, awesome),
+ { code: 'ERR_ASSERTION' }
+ );
+
+ const notAwesome = new AwesomeClass('Not so awesome');
+ assertInstance.notDeepStrictEqual(cool, notAwesome);
+
+ const defaultAssertInstance = new Assert({ skipPrototype: false });
+ defaultAssertInstance.notDeepStrictEqual(cool, awesome);
+ });
+
+ test('Assert class skipPrototype with mixed types', () => {
+ const assertInstance = new Assert({ skipPrototype: true });
+
+ const obj1 = { value: 42, nested: { prop: 'test' } };
+
+ function CustomObj(value, nested) {
+ this.value = value;
+ this.nested = nested;
+ }
+
+ const obj2 = new CustomObj(42, { prop: 'test' });
+ assertInstance.deepStrictEqual(obj1, obj2);
+
+ assert.throws(
+ () => assertInstance.deepStrictEqual({ num: 42 }, { num: '42' }),
+ { code: 'ERR_ASSERTION' }
+ );
+ });
+}
diff --git a/test/parallel/test-util-isDeepStrictEqual.js b/test/parallel/test-util-isDeepStrictEqual.js

-Original file line number
+Diff line change
  * @property {'full'|'simple'} [diff='simple'] - If set to 'full', shows the full diff in assertion errors.
  * @property {boolean} [strict=true] - If set to true, non-strict methods behave like their corresponding
  * strict methods.
 + * @property {boolean} [skipPrototype=false] - If set to true, skips comparing prototypes
 + * in deep equality checks.
  */
 /**
 thrownewERR_CONSTRUCT_CALL_REQUIRED('Assert');
+}
 -options=ObjectAssign({__proto__: null,strict: true},options);
 +options=ObjectAssign({__proto__: null,strict: true,skipPrototype: false},options);
 constallowedDiffs=['simple','full'];
 if(options.diff!==undefined){
 thrownewERR_MISSING_ARGS('actual','expected');
+}
 if(isDeepEqual===undefined)lazyLoadComparison();
 -if(!isDeepStrictEqual(actual,expected)){
 +if(!isDeepStrictEqual(actual,expected,this?.[kOptions]?.skipPrototype)){
 innerFail({
  actual,
  expected,
 thrownewERR_MISSING_ARGS('actual','expected');
+}
 if(isDeepEqual===undefined)lazyLoadComparison();
 -if(isDeepStrictEqual(actual,expected)){
 +if(isDeepStrictEqual(actual,expected,this?.[kOptions]?.skipPrototype)){
 innerFail({
  actual,
  expected,
-Original file line number
+Diff line change
  getOwnNonIndexProperties,
 }=internalBinding('util');
 -constkStrict=1;
 +constkStrict=2;
 +constkStrictWithoutPrototypes=3;
 constkLoose=0;
 -constkPartial=2;
 +constkPartial=1;
 constkNoIterator=0;
 constkIsArray=1;
+}
 }elseif(keys2.length!==(keys1=ObjectKeys(val1)).length){
 returnfalse;
 -}elseif(mode===kStrict){
 +}elseif(mode===kStrict||mode===kStrictWithoutPrototypes){
 constsymbolKeysA=getOwnSymbols(val1);
 if(symbolKeysA.length!==0){
 letcount=0;
 isDeepEqual(val1,val2){
 returndetectCycles(val1,val2,kLoose);
 },
 -isDeepStrictEqual(val1,val2){
 +isDeepStrictEqual(val1,val2,skipPrototype){
 +if(skipPrototype){
 +returndetectCycles(val1,val2,kStrictWithoutPrototypes);
 +}
 returndetectCycles(val1,val2,kStrict);
 },
 isPartialStrictEqual(val1,val2){
-Original file line number
+Diff line change
 );
+}
 });
++
 +// Shared setup for skipPrototype tests
 +{
 +constmessage='Expected values to be strictly deep-equal:\n'+
 +'+ actual - expected\n'+
 +'\n'+
 +' [\n'+
 +' 1,\n'+
 +' 2,\n'+
 +' 3,\n'+
 +' 4,\n'+
 +' 5,\n'+
 +'+ 6,\n'+
 +'- 9,\n'+
 +' 7\n'+
 +' ]\n';
++
 +functionCoolClass(name){this.name=name;}
++
 +functionAwesomeClass(name){this.name=name;}
++
 +classModern{constructor(value){this.value=value;}}
 +classLegacy{constructor(value){this.value=value;}}
++
 +constcool=newCoolClass('Assert is inspiring');
 +constawesome=newAwesomeClass('Assert is inspiring');
 +constmodern=newModern(42);
 +constlegacy=newLegacy(42);
++
 +test('Assert class strict with skipPrototype',()=>{
 +constassertInstance=newAssert({skipPrototype: true});
++
 +assert.throws(
 +()=>assertInstance.deepEqual([1,2,3,4,5,6,7],[1,2,3,4,5,9,7]),
 +{ message }
 +);
++
 +assertInstance.deepEqual(cool,awesome);
 +assertInstance.deepStrictEqual(cool,awesome);
 +assertInstance.deepEqual(modern,legacy);
 +assertInstance.deepStrictEqual(modern,legacy);
++
 +constcool2=newCoolClass('Soooo coooool');
 +assert.throws(
 +()=>assertInstance.deepStrictEqual(cool,cool2),
 +{code: 'ERR_ASSERTION'}
 +);
++
 +constnested1={obj: newCoolClass('test'),arr: [1,2,3]};
 +constnested2={obj: newAwesomeClass('test'),arr: [1,2,3]};
 +assertInstance.deepStrictEqual(nested1,nested2);
++
 +constarr=newUint8Array([1,2,3]);
 +constbuf=Buffer.from([1,2,3]);
 +assertInstance.deepStrictEqual(arr,buf);
 +});
++
 +test('Assert class non strict with skipPrototype',()=>{
 +constassertInstance=newAssert({strict: false,skipPrototype: true});
++
 +assert.throws(
 +()=>assertInstance.deepStrictEqual([1,2,3,4,5,6,7],[1,2,3,4,5,9,7]),
 +{ message }
 +);
++
 +assertInstance.deepStrictEqual(cool,awesome);
 +assertInstance.deepStrictEqual(modern,legacy);
 +});
++
 +test('Assert class skipPrototype with complex objects',()=>{
 +constassertInstance=newAssert({skipPrototype: true});
++
 +functionComplexAwesomeClass(name,age){
 +this.name=name;
 +this.age=age;
 +this.settings={
 +theme: 'dark',
 +lang: 'en'
 +};
 +}
++
 +functionComplexCoolClass(name,age){
 +this.name=name;
 +this.age=age;
 +this.settings={
 +theme: 'dark',
 +lang: 'en'
 +};
 +}
++
 +constawesome1=newComplexAwesomeClass('Foo',30);
 +constcool1=newComplexCoolClass('Foo',30);
++
 +assertInstance.deepStrictEqual(awesome1,cool1);
++
 +constcool2=newComplexCoolClass('Foo',30);
 +cool2.settings.theme='light';
++
 +assert.throws(
 +()=>assertInstance.deepStrictEqual(awesome1,cool2),
 +{code: 'ERR_ASSERTION'}
 +);
 +});
++
 +test('Assert class skipPrototype with arrays and special objects',()=>{
 +constassertInstance=newAssert({skipPrototype: true});
++
 +constarr1=[1,2,3];
 +constarr2=newArray(1,2,3);
 +assertInstance.deepStrictEqual(arr1,arr2);
++
 +constdate1=newDate('2023-01-01');
 +constdate2=newDate('2023-01-01');
 +assertInstance.deepStrictEqual(date1,date2);
++
 +constregex1=/test/g;
 +constregex2=newRegExp('test','g');
 +assertInstance.deepStrictEqual(regex1,regex2);
++
 +constdate3=newDate('2023-01-02');
 +assert.throws(
 +()=>assertInstance.deepStrictEqual(date1,date3),
 +{code: 'ERR_ASSERTION'}
 +);
 +});
++
 +test('Assert class skipPrototype with notDeepStrictEqual',()=>{
 +constassertInstance=newAssert({skipPrototype: true});
++
 +assert.throws(
 +()=>assertInstance.notDeepStrictEqual(cool,awesome),
 +{code: 'ERR_ASSERTION'}
 +);
++
 +constnotAwesome=newAwesomeClass('Not so awesome');
 +assertInstance.notDeepStrictEqual(cool,notAwesome);
++
 +constdefaultAssertInstance=newAssert({skipPrototype: false});
 +defaultAssertInstance.notDeepStrictEqual(cool,awesome);
 +});
++
 +test('Assert class skipPrototype with mixed types',()=>{
 +constassertInstance=newAssert({skipPrototype: true});
++
 +constobj1={value: 42,nested: {prop: 'test'}};
++
 +functionCustomObj(value,nested){
 +this.value=value;
 +this.nested=nested;
 +}
++
 +constobj2=newCustomObj(42,{prop: 'test'});
 +assertInstance.deepStrictEqual(obj1,obj2);
++
 +assert.throws(
 +()=>assertInstance.deepStrictEqual({num: 42},{num: '42'}),
 +{code: 'ERR_ASSERTION'}
 +);
 +});
 +}