Array#includes(..)

One extremely common task JS developers need to perform is searching for a value inside an array of values. The way this has always been done is:

var vals = [ "foo", "bar", 42, "baz" ];
if (vals.indexOf( 42 ) >= 0) {
    // found it!
}

The reason for the >= 0 check is because indexOf(..) returns a numeric value of 0 or greater if found, or -1 if not found. In other words, we’re using an index-returning function in a boolean context. But because -1 is truthy instead of falsy, we have to be more manual with our checks.

In the Types & Grammar title of this series, I explored another pattern that I slightly prefer:

var vals = [ "foo", "bar", 42, "baz" ];
if (~vals.indexOf( 42 )) {
    // found it!
}

The ~ operator here conforms the return value of indexOf(..) to a value range that is suitably boolean coercible. That is, -1 produces 0 (falsy), and anything else produces a non-zero (truthy) value, which is what we for deciding if we found the value or not.

While I think that’s an improvement, others strongly disagree. However, no one can argue that indexOf(..)‘s searching logic is perfect. It fails to find NaN values in the array, for example.

So a proposal has surfaced and gained a lot of support for adding a real boolean-returning array search method, called includes(..):

var vals = [ "foo", "bar", 42, "baz" ];
if (vals.includes( 42 )) {
    // found it!
}

Note: Array#includes(..) uses matching logic that will find NaN values, but will not distinguish between -0 and 0 (see the Types & Grammar title of this series). If you don’t care about -0 values in your programs, this will likely be exactly what you’re hoping for. If you do care about -0, you’ll need to do your own searching logic, likely using the Object.is(..) utility (see Chapter 6).