feat(array): add arrFlatMap with ES5 polyfill by nev21 · Pull Request #533 · nevware21/ts-utils

nev21 · 2026-03-26T04:59:29Z

Add arrFlatMap and polyArrFlatMap implementations with one-level flatten behavior for mapped values.
Introduce ArrFlatMapCallbackFn type for array and array-like callback signatures.
Export arrFlatMap and the callback type from public index and polyfills entry points.

codecov · 2026-03-26T05:02:22Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.45%. Comparing base (53d481f) to head (f8dc20c).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #533      +/-   ##
==========================================
+ Coverage   98.86%   99.45%   +0.58%     
==========================================
  Files         140      141       +1     
  Lines        4147     4202      +55     
  Branches      892      908      +16     
==========================================
+ Hits         4100     4179      +79     
+ Misses         47       23      -24

Files with missing lines	Coverage Δ
lib/src/array/callbacks.ts	`100.00% <ø> (+50.00%)`	⬆️
lib/src/array/flatMap.ts	`100.00% <100.00%> (ø)`
lib/src/array/flatten.ts	`100.00% <ø> (ø)`
lib/src/polyfills.ts	`94.11% <100.00%> (+41.05%)`	⬆️

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull request overview

Adds arrFlatMap (with polyArrFlatMap) to @nevware21/ts-utils, extending the Array helper surface with an ES5-compatible flatMap implementation and public exports.

Changes:

Added arrFlatMap helper and polyArrFlatMap polyfill implementation.
Introduced ArrFlatMapCallbackFn type and exported it from the main index.
Added common tests, updated polyfills entry/export wiring, and adjusted bundle size thresholds/docs.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lib/src/array/flatMap.ts	New `arrFlatMap` wrapper + `polyArrFlatMap` implementation.
lib/src/array/callbacks.ts	Adds `ArrFlatMapCallbackFn` type for flatMap callbacks.
lib/src/index.ts	Exports `arrFlatMap` and `ArrFlatMapCallbackFn` publicly.
lib/src/polyfills.ts	Registers `flatMap` in prototype polyfill installation and exports `polyArrFlatMap`.
lib/src/array/flatten.ts	Updates docs to reference `arrFlatMap` for map-then-flatten workflows.
lib/test/src/common/array/flatMap.test.ts	Adds coverage for `arrFlatMap`, `polyArrFlatMap`, and export wiring.
lib/test/bundle-size-check.js	Increases bundle size thresholds for ES5 minified artifacts.
.size-limit.json	Updates size-limit thresholds for built ES5/ES6 modules.
docs/feature-backlog.md	Updates backlog entry related to `arrFlatMap` (currently with a content issue).

lib/src/array/flatMap.ts

docs/feature-backlog.md

nevware21-bot

Approved by nevware21-bot

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

lib/src/array/callbacks.ts

lib/src/array/flatMap.ts

lib/test/src/common/array/flatMap.test.ts

- Add `arrFlatMap` and `polyArrFlatMap` implementations with one-level flatten behavior for mapped values. - Introduce `ArrFlatMapCallbackFn` type for array and array-like callback signatures. - Export `arrFlatMap` and the callback type from public index and polyfills entry points.

nevware21-bot

Approved by nevware21-bot

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Copilot · 2026-03-27T15:44:52Z

lib/src/array/flatMap.ts

+import { getKnownSymbol } from "../symbol/symbol";
+import { isArrayLike } from "../helpers/base";
+import { createCachedValue, ICachedValue } from "../helpers/cache";
+
+let _isConcatSpreadable: ICachedValue<symbol>;
+
+/*#__NO_SIDE_EFFECTS__*/
+function _isFlatMapSpreadable(value: any): boolean {
+    let result = false;
+    if (isArray(value) || isArrayLike(value)) {
+        result = true;
+
+        if (!_isConcatSpreadable) {
+            _isConcatSpreadable = createCachedValue(getKnownSymbol("isConcatSpreadable", true) || null);
+        }
+
+        let sym = _isConcatSpreadable.v;
+        if (sym) {
+            let symVal = value[sym as any];
+            if (symVal !== undefined) {
+                result = !!symVal;
+            }
+        }
+    }
+
+    return result;


_isFlatMapSpreadable() currently treats any isArrayLike() value (including strings) as spreadable and also uses Symbol.isConcatSpreadable to decide flattening. Native Array.prototype.flatMap flattens only Arrays (and does not honor isConcatSpreadable), so arrFlatMap will behave differently depending on whether the runtime has native flatMap or uses polyArrFlatMap. Consider changing the spreadability check to align with the native spec (flatten Arrays only) to keep behavior consistent across environments.

Suggested change

import { getKnownSymbol } from "../symbol/symbol";

import { isArrayLike } from "../helpers/base";

import { createCachedValue, ICachedValue } from "../helpers/cache";

let _isConcatSpreadable: ICachedValue<symbol>;

/*#__NO_SIDE_EFFECTS__*/

function _isFlatMapSpreadable(value: any): boolean {

let result = false;

if (isArray(value) || isArrayLike(value)) {

result = true;

if (!_isConcatSpreadable) {

_isConcatSpreadable = createCachedValue(getKnownSymbol("isConcatSpreadable", true) || null);

}

let sym = _isConcatSpreadable.v;

if (sym) {

let symVal = value[sym as any];

if (symVal !== undefined) {

result = !!symVal;

}

}

}

return result;

/*#__NO_SIDE_EFFECTS__*/

function _isFlatMapSpreadable(value: any): boolean {

// Align with native Array.prototype.flatMap: only Array instances are flattened,

// and Symbol.isConcatSpreadable is not considered.

return isArray(value);

Copilot · 2026-03-27T15:44:53Z

lib/test/src/common/array/flatMap.test.ts

+    it("should flatten array-like callback results", () => {
+        const mappedValue = { length: 2, 0: "x", 1: "y" };
+        const result = polyArrFlatMap([1], () => mappedValue as any);
+
+        assert.deepEqual(result, ["x", "y"]);


This test expects polyArrFlatMap to flatten an array-like object returned from the callback. Native Array.prototype.flatMap only flattens Arrays, so this expectation will make the polyfill diverge from native behavior (and from arrFlatMap when the native implementation is used). Consider updating the test (and polyfill behavior) to only flatten when the callback returns an actual Array.

Suggested change

it("should flatten array-like callback results", () => {

const mappedValue = { length: 2, 0: "x", 1: "y" };

const result = polyArrFlatMap([1], () => mappedValue as any);

assert.deepEqual(result, ["x", "y"]);

it("should not flatten plain array-like callback results", () => {

const mappedValue = { length: 2, 0: "x", 1: "y" };

const result = polyArrFlatMap([1], () => mappedValue as any);

assert.equal(result.length, 1);

assert.strictEqual(result[0], mappedValue);

Copilot · 2026-03-27T15:44:53Z

lib/test/src/common/array/flatMap.test.ts

+    it("should flatten concat-spreadable mapped objects when symbol is available", () => {
+        const spreadSym = typeof Symbol !== "undefined" && Symbol.isConcatSpreadable;
+        if (!spreadSym) {
+            return;
+        }
+
+        const mappedValue: any = { length: 2, 0: "x", 1: "y" };
+        mappedValue[spreadSym] = true;
+
+        const result = polyArrFlatMap([1], () => mappedValue);
+        assert.deepEqual(result, ["x", "y"]);
+    });


These assertions assume polyArrFlatMap honors Symbol.isConcatSpreadable on non-Array objects. Native Array.prototype.flatMap does not use concat-spreadability when flattening (it only flattens Arrays), so this test enforces non-standard behavior and will cause cross-environment differences. Consider removing this behavior and updating the test accordingly.

Copilot · 2026-03-27T15:44:53Z

lib/test/src/common/array/flatMap.test.ts

+    it("should not flatten mapped objects with concat-spreadable set to false", () => {
+        const spreadSym = typeof Symbol !== "undefined" && Symbol.isConcatSpreadable;
+        if (!spreadSym) {
+            return;
+        }
+
+        const mappedValue: any = { length: 2, 0: "x", 1: "y" };
+        mappedValue[spreadSym] = false;
+
+        const result = polyArrFlatMap([1], () => mappedValue);
+        assert.equal(result.length, 1);
+        assert.strictEqual(result[0], mappedValue);


This test case for Symbol.isConcatSpreadable = false continues the concat-spreadable semantics which don't exist for native flatMap (it ignores Symbol.isConcatSpreadable). If the polyfill is updated to match native behavior (flatten Arrays only), this test should be removed or rewritten to cover Array-only flattening edge cases.

Suggested change

it("should not flatten mapped objects with concat-spreadable set to false", () => {

const spreadSym = typeof Symbol !== "undefined" && Symbol.isConcatSpreadable;

if (!spreadSym) {

return;

}

const mappedValue: any = { length: 2, 0: "x", 1: "y" };

mappedValue[spreadSym] = false;

const result = polyArrFlatMap([1], () => mappedValue);

assert.equal(result.length, 1);

assert.strictEqual(result[0], mappedValue);

it("should flatten arrays even when concat-spreadable is set to false", () => {

const spreadSym = typeof Symbol !== "undefined" && Symbol.isConcatSpreadable;

if (!spreadSym) {

return;

}

const mappedValue: any = ["x", "y"];

mappedValue[spreadSym] = false;

const result = polyArrFlatMap([1], () => mappedValue);

assert.deepEqual(result, ["x", "y"]);

nev21 added this to the 0.14.0 milestone Mar 26, 2026

nev21 requested a review from a team as a code owner March 26, 2026 04:59

Copilot AI review requested due to automatic review settings March 26, 2026 04:59

nev21 requested a review from a team as a code owner March 26, 2026 04:59

Copilot started reviewing on behalf of nev21 March 26, 2026 04:59 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

lib/src/array/flatMap.ts Outdated Show resolved Hide resolved

docs/feature-backlog.md Outdated Show resolved Hide resolved

nev21 force-pushed the nev21/array branch from 56fb1dd to 95559ff Compare March 26, 2026 05:41

nevware21-bot previously approved these changes Mar 26, 2026

View reviewed changes

nev21 requested a review from Copilot March 26, 2026 05:42

Copilot started reviewing on behalf of nev21 March 26, 2026 05:43 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

lib/src/array/callbacks.ts Outdated Show resolved Hide resolved

lib/src/array/flatMap.ts Show resolved Hide resolved

lib/test/src/common/array/flatMap.test.ts Show resolved Hide resolved

nev21 dismissed nevware21-bot’s stale review via f8dc20c March 26, 2026 07:34

nev21 force-pushed the nev21/array branch from 95559ff to f8dc20c Compare March 26, 2026 07:34

nevware21-bot approved these changes Mar 26, 2026

View reviewed changes

nev21 requested a review from Copilot March 27, 2026 15:39

Copilot started reviewing on behalf of nev21 March 27, 2026 15:40 View session

Copilot AI reviewed Mar 27, 2026

View reviewed changes

Uh oh!

Conversation

nev21 commented Mar 26, 2026

Uh oh!

codecov bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

nevware21-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nevware21-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Mar 26, 2026 •

edited

Loading