or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-array-includes

A spec-compliant Array.prototype.includes shim/polyfill/replacement that works as far down as ES3.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/array-includes@2.0.x

To install, run

npx @tessl/cli install tessl/npm-array-includes@2.0.0

index.mddocs/

Array Includes

Array Includes is a spec-compliant Array.prototype.includes shim/polyfill/replacement that works as far down as ES3. It provides proper NaN and negative zero handling that indexOf cannot, while maintaining full ES7 specification compliance across all JavaScript environments.

Package Information

  • Package Name: array-includes
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install array-includes

Core Imports

const includes = require('array-includes');

For ES6 modules:

import includes from 'array-includes';

Basic Usage

const includes = require('array-includes');

const arr = [1, 'foo', NaN, -0];

// Basic element searching
console.log(includes(arr, 1)); // true
console.log(includes(arr, 'bar')); // false

// Proper NaN handling (unlike indexOf)
console.log(arr.indexOf(NaN) > -1); // false
console.log(includes(arr, NaN)); // true

// Proper negative zero handling
console.log(arr.indexOf(0) > -1); // true (matches -0)
console.log(includes(arr, 0)); // false (doesn't match -0)
console.log(includes(arr, -0)); // true

// Search with fromIndex
console.log(includes(arr, 'foo', 0)); // true
console.log(includes(arr, 'foo', 2)); // false

Architecture

Array Includes provides both standalone functionality and shimming capability:

  • Standalone Function: Direct usage via function calls for explicit polyfill behavior
  • Shimming System: Automatic installation on Array.prototype when native support is missing
  • ES3+ Compatibility: Uses ES6 abstract operations through es-abstract for consistent behavior
  • Spec Compliance: Implements the exact SameValueZero comparison algorithm from the ES7 specification

Capabilities

Main Function

Performs array includes search with proper spec compliance.

/**
 * Determines whether an array includes a certain element, returning true or false
 * @param array - Array-like object to search in
 * @param searchElement - Element to search for
 * @param fromIndex - Index to start searching from (optional, defaults to 0)
 * @returns true if searchElement is found, false otherwise
 */
function includes(array, searchElement, fromIndex)

Key Features:

  • Handles NaN comparison using SameValueZero (unlike indexOf)
  • Supports negative fromIndex values
  • Works with array-like objects (not just arrays)
  • Handles sparse arrays correctly
  • Throws TypeError for null/undefined array parameter

Usage Examples:

const includes = require('array-includes');

// Array-like objects
const arrayLike = { 0: 'a', 1: 'b', length: 2 };
console.log(includes(arrayLike, 'a')); // true

// Negative fromIndex
console.log(includes(['a', 'b', 'c'], 'c', -1)); // true
console.log(includes(['a', 'b', 'c'], 'b', -1)); // false

// Sparse arrays
const sparse = Array(3);
sparse[1] = 'filled';
console.log(includes(sparse, undefined)); // true (finds hole)
console.log(includes(sparse, 'filled')); // true

Shim Method

Installs the includes method on Array.prototype when not natively available.

/**
 * Shims Array.prototype.includes if not present, or returns native implementation
 * @returns The shimmed or native Array.prototype.includes method
 */
includes.shim()

Behavior:

  • Safely installs includesShim on Array.prototype.includes if not present or configurable
  • Returns Array.prototype.includes if available, otherwise returns the shim implementation
  • Safe to call multiple times - uses define-properties for proper property definition

Usage Examples:

const includes = require('array-includes');

// Install shim (safe to call multiple times)
const shimmedIncludes = includes.shim();

// Now arrays have includes method
const arr = [1, 2, NaN];
console.log(arr.includes(NaN)); // true
console.log(arr.includes(1, 1)); // false (starts search from index 1)

// The return value is always Array.prototype.includes after shimming
console.log(shimmedIncludes === Array.prototype.includes); // true

// Check if shimming was needed
console.log(Array.prototype.includes.toString().indexOf('includesShim') > -1); // true if shimmed

Method Property

Direct access to the core includes implementation.

/**
 * The core includes implementation function designed for use as a method
 * Expects 'this' to be the array/array-like object to search
 * @param searchElement - Element to search for
 * @param fromIndex - Index to start searching from (optional, defaults to 0)
 * @returns true if searchElement is found, false otherwise
 */
includes.method

This property exposes the internal includesShim function. It's designed to be used as a method (with a this context) and is primarily used by the shimming system to install on Array.prototype.

Error Handling

The function throws TypeError in the following cases:

const includes = require('array-includes');

// Throws TypeError: Cannot convert undefined or null to object
includes(null, 'test');
includes(undefined, 'test');

// Throws RangeError when fromIndex conversion fails
const throwingFromIndex = { valueOf: () => { throw new RangeError('test'); } };
includes([1, 2, 3], 1, throwingFromIndex);

// Throws RangeError when length property conversion fails  
const throwingLength = { length: { valueOf: () => { throw new RangeError('test'); } } };
includes(throwingLength, 'test');

Types

// Main function signature (bound function that takes array as first parameter)
function includes(array: ArrayLike, searchElement: any, fromIndex?: number): boolean;

// Shim method signature  
function shim(): (this: ArrayLike, searchElement: any, fromIndex?: number) => boolean;

// Method property type (method-style function expecting 'this' context)
const method: (this: ArrayLike, searchElement: any, fromIndex?: number) => boolean;

// ArrayLike interface (any object with numeric indices and length)
interface ArrayLike {
  readonly length: number;
  readonly [n: number]: any;
}