For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/stage/unstaged/proposal-generic-comparison.md.
TC39 Atlas
  • English

      • Generic Comparison ?

      Proposal details
      Proposal overview

      This proposal addresses the lack of a standard way to compare arrays in JavaScript, including nested structures. It proposes an Array.prototype.compare method that takes a comparator function and returns -1, 0, or 1, and also explores a <=> three-way comparison operator. The proposal is at an early stage, with no specification details or maturity further than an idea.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      Generic Comparison

      Author: Hemanth HM

      Champions: Jordan Harband & Hemanth HM

      Motivation

      Comparing arrays are one of the most common operations we do on arrays, and there is no consitent standard way to compare two array and given that array might have any type of primitives and nested structures, it get more tedious to compare them.

      How is this currently handled?

      There is no standard way to do it, there are few modules like array-equal, deep-equal with like 5M and 8M downloads per week respectivly, which is subset of deep comparison.

      Consider few examples:

      // Schmea validation
const equal = require('deep-equal');

const expectedSchema = {
  name: {
    type: String,
    required: true
  },
  score: {
    type: Number,
    default: 0
  }
};

equal(schemaCall.args[0], expectedSchema);

      node builtin:

      // assert.deepStrictEqual(actual, expected[, message])

deepStrictEqual([new Uint32Array([1, 2, 3, 4]).subarray(1, 3), new Uint32Array([2, 3])]);
      // assert.deepEqual(actual, expected[, message])

assert.deepEqual( tokenizer( "AD", "G", cldr ), [{
		type: "G",
		lexeme: "AD",
		value: "1"
	}] );

      How we could do it?

      Array.prototype.compare takes a comparator function, which gets two arguments.

      Each a tuple of [value, key] and it returns < 0, 0, or > 1 (and throws when a non-finite-non-integer is returned) and then it would return either -1, 0, or 1

      That way we could write our own logic, and get back 0 if they were equal.

      P.S: This was a proposal evolved Array.prototype.equals.

      Extending the idea to a three-way comparison:

      We could rather have a <=> three-way compare operator, that does the below:

               true		      	   false
a < b    (a <=> b) < 0		 (a <=> b) >= 0
a <= b   (a <=> b) <= 0		 (a <=> b) > 0
a > b    (a <=> b) > 0		 (a <=> b) <= 0
a >= b   (a <=> b) >= 0		 (a <=> b) < 0