Array Method `this` and Argument Boxing Check

1.0.0 · active · verified Sun Apr 19

This package, `es-array-method-boxes-properly`, is a niche utility designed to verify the spec compliance of `Array.prototype` methods in a given JavaScript environment. Specifically, it checks if a method like `map` or `forEach` properly "boxes" the `this` context (receiver) and the third argument (the array itself) when invoking the callback function. This is critical for ensuring consistent behavior across different JavaScript engines, especially regarding strict mode implications and how primitives are handled when passed as `this`. Currently at version 1.0.0, the package provides a stable API and is likely maintained on an as-needed basis, reflecting its role in foundational spec compliance rather than active feature development. It is primarily used by library authors or engine developers to detect subtle deviations from the ECMAScript specification in host environments.

Warnings

gotcha This utility checks the *host environment's native* `Array.prototype` method implementation for spec compliance. It does not evaluate the behavior of user-defined polyfills or custom array methods, which might have different boxing characteristics.
Fix: Ensure you understand that the check applies to the environment's built-in methods, not custom implementations. If you're using a polyfill, its behavior depends on the polyfill itself.
gotcha The concept of "properly boxing" refers specifically to how `this` and the third argument (the array) are treated according to the ECMAScript specification. This often involves primitive values being wrapped in objects when used as `this` in non-strict mode callbacks. Misinterpreting this as a general 'bug' without understanding the spec can lead to incorrect conclusions.
Fix: Consult the ECMAScript specification for `Array.prototype` methods to understand the precise requirements for 'boxing' the `this` value and the third argument in callback functions.

Install

npm install es-array-method-boxes-properly npm
yarn add es-array-method-boxes-properly yarn
pnpm add es-array-method-boxes-properly pnpm

Imports

boxesProperly
wrong:
```
import { boxesProperly } from 'es-array-method-boxes-properly';
```
correct:
```
const boxesProperly = require('es-array-method-boxes-properly');
```
This package is CommonJS-only. For ESM usage, rely on Node.js CJS-ESM interop, dynamic import(), or a bundler.
default import (interop)
```
import boxesProperly from 'es-array-method-boxes-properly';
```
While a CommonJS package, bundlers and Node.js often provide default import interop for convenience.

Quickstart

Demonstrates how to import the `boxesProperly` function and use it to check the compliance of `Array.prototype.map` and `forEach` in the current runtime environment.

const boxesProperly = require('es-array-method-boxes-properly');

// Check if Array.prototype.map boxes 'this' and the third argument properly
const mapBoxesProperly = boxesProperly('map');
console.log(`Array.prototype.map boxes properly: ${mapBoxesProperly}`);

// Example for a method that is known to box differently in some older environments or custom implementations
const forEachBoxesProperly = boxesProperly('forEach');
console.log(`Array.prototype.forEach boxes properly: ${forEachBoxesProperly}`);

// You can use this to adapt behavior or report compliance issues
if (!mapBoxesProperly) {
  console.warn('Warning: Array.prototype.map implementation might not be spec-compliant regarding boxing.');
}

view raw JSON →