biome complexity/useFlatMap

• If the map callback contains side effects that depend on intermediate array indices, removing the intermediate array may alter behavior if those indices are used elsewhere.
• If the flat depth is omitted but the map returns nested arrays deeper than one level, flatMap only flattens one level, potentially leaving extra nesting compared to the original.
• If the map function returns holes (empty slots), .flat() removes them while .flatMap() preserves them, changing array length and indices.
• If the map function uses 'this' and the context is bound via .map(callback, thisArg), the fix must preserve the thisArg or it will be lost.
• If the chain includes .map().flat() after a non-array method like .filter(), the fix only applies to the map-flat pair and must not disturb surrounding chain links.
• If the map callback throws an exception, the timing of when that exception occurs relative to subsequent operations is unchanged, but any reliance on the intermediate array's existence for debugging or inspection is removed.
• If the code relies on the intermediate array being a distinct object in memory (e.g., for identity checks via ===), replacing it with flatMap's internal optimization breaks such checks.
• If the map function returns undefined, .flat() skips it while .flatMap() also skips it, so no change, but if it returns null, both treat it as a single element, so still safe—however, if the map returns a non-array scalar, both behave identically in flattening one level.

--- orig.js	2026-10-17 16:12:12.090676088 -0400
+++ fixed.js	2026-10-17 16:12:12.359669828 -0400
@@ -1,6 +1,6 @@
 for (var i = 0; i < 2; i++) {
   var data = [[i], [i+1]];
-  var result = data.map(x => x).flat();
+  var result = data.flatMap(x => x);
   console.log(result.length);
 }
 console.log(typeof data);

2
2
object

2 1,3
2 1,3

--- orig.js	2026-10-17 16:12:12.755660612 -0400
+++ fixed.js	2026-10-17 16:12:13.014654585 -0400
@@ -1,4 +1,4 @@
 const nums = [1, 2, 3, 4];
-const result = nums.filter(n => n % 2 === 0).map(n => [n, n*10]).flat();
+const result = nums.filter(n => n % 2 === 0).flatMap(n => [n, n*10]);
 console.log(result.join('-'));
 // After fix: .flatMap should preserve filter behavior

2-20-4-40

false false

--- orig.js	2026-10-17 16:12:13.401645600 -0400
+++ fixed.js	2026-10-17 16:12:13.658639632 -0400
@@ -1,5 +1,5 @@
 let count = 0;
 const obj = { get arr() { count++; return [[1], [2]]; } };
-const result = obj.arr.map(x => x).flat();
+const result = obj.arr.flatMap(x => x);
 console.log(count, result.length);
 // After fix, getter called once instead of twice if map and flat were separate?

1 2

--- orig.js	2026-10-17 16:12:13.830635639 -0400
+++ fixed.js	2026-10-17 16:12:14.086629700 -0400
@@ -1,5 +1,5 @@
 function process(a, b = [], ...rest) {
-  return arguments.map(x => [x]).flat();
+  return arguments.flatMap(x => [x]);
 }
 const res = process(1, 2, 3);
 console.log(res.length, res.join(','));

--- orig.js	2026-10-17 16:12:14.245626016 -0400
+++ fixed.js	2026-10-17 16:12:14.506619970 -0400
@@ -1,6 +1,6 @@
 class Base {
   static items = [[1], [2]];
-  getData() { return Base.items.map(x => x).flat(); }
+  getData() { return Base.items.flatMap(x => x); }
 }
 class Der extends Base {
   getData() { return super.getData().length; }

2

--- orig.js	2026-10-17 16:12:14.671616148 -0400
+++ fixed.js	2026-10-17 16:12:14.931610125 -0400
@@ -3,7 +3,7 @@
   var data = [[1], [2], [3]];
   try {
     delete data[0];
-    const result = data.map(x => x).flat();
+    const result = data.flatMap(x => x);
     console.log(result.length);
   } catch (e) { console.log(e.name); }
 })();
@@ -12,6 +12,6 @@
   'use sloppy';
   var data2 = [[1], [2], [3]];
   delete data2[0];
-  const result = data2.map(x => x).flat();
+  const result = data2.flatMap(x => x);
   console.log(result.length);
 })();

2
2

--- orig.js	2026-10-17 16:12:25.971357806 -0400
+++ fixed.js	2026-10-17 16:12:26.250351516 -0400
@@ -3,6 +3,6 @@
 console.log('mapped:', mapped);
 const flatResult = mapped.flat();
 console.log('flat():', flatResult, 'length:', flatResult.length);
-a.map(x => x === 2 ? [] : [x]).flat(); // expect_trigger
+a.flatMap(x => x === 2 ? [] : [x]); // expect_trigger
 const flatMapResult = a.map(x => x === 2 ? [] : [x]).flatMap(x => x);
 console.log('flatMap():', flatMapResult, 'length:', flatMapResult.length);

mapped: [ [ 1 ], <1 empty item>, [ 3 ] ]
flat(): [ 1, 3 ] length: 2
flatMap(): [ 1, 3 ] length: 2

--- orig.js	2026-10-17 16:12:26.411347887 -0400
+++ fixed.js	2026-10-17 16:12:26.672342004 -0400
@@ -1,7 +1,7 @@
 class Base { constructor() { this.x = 1; } static y = 2; }
 class Derived extends Base { #z = 3; static { console.log('static block'); }
   getZ() { return this.#z + super.x; }
-  process() { return [this].map(i => [i.getZ()]).flat(); }
+  process() { return [this].flatMap(i => [i.getZ()]); }
 }
 const d = new Derived();
 console.log('process result:', d.process());

static block
process result: [ NaN ]

with thisArg: [ 2, 4, 6 ]

--- orig.js	2026-10-17 16:12:27.071333013 -0400
+++ fixed.js	2026-10-17 16:12:27.346326828 -0400
@@ -9,6 +9,6 @@
 console.log('mapped:', mapped);
 const flattened = mapped.flat();
 console.log('flat result:', flattened);
-arr.map(x => [x, String(x)]).flat(); // expect_trigger
+arr.flatMap(x => [x, String(x)]); // expect_trigger
 const flatMapped = arr.map(x => [x, String(x)]).flatMap(x => x);
 console.log('flatMap result:', flatMapped);

mapped: [
  [
    { valueOf: [Function: valueOf], toString: [Function: toString] },
    'hello'
  ],
  [ Symbol(test), 'Symbol(test)' ],
  [ 123n, '123' ]
]
flat result: [
  { valueOf: [Function: valueOf], toString: [Function: toString] },
  'hello',
  Symbol(test),
  'Symbol(test)',
  123n,
  '123'
]
flatMap result: [
  { valueOf: [Function: valueOf], toString: [Function: toString] },
  'hello',
  Symbol(test),
  'Symbol(test)',
  123n,
  '123'
]

collected: [ 1, 2, 3 ]
mapped: [ [ 1, 2 ], [ 2, 4 ], [ 3, 6 ] ]
flat: [ 1, 2, 2, 4, 3, 6 ]

--- orig.js	2026-10-17 16:12:27.761317495 -0400
+++ fixed.js	2026-10-17 16:12:28.039311245 -0400
@@ -4,8 +4,8 @@
 }
 const arr = [5];
 console.log('calling map:');
-const result = arr.map(mapper).flat();
+const result = arr.flatMap(mapper);
 console.log('flat result:', result);
-arr.map(mapper).flat(); // expect_trigger
+arr.flatMap(mapper); // expect_trigger
 const flatMapResult = arr.map(mapper).flatMap(x => x);
 console.log('flatMap result:', flatMapResult);

calling map:
args.length: 3 b: 0 rest: [ [ 5 ] ]
flat result: [ 5 ]
args.length: 3 b: 0 rest: [ [ 5 ] ]
args.length: 3 b: 0 rest: [ [ 5 ] ]
flatMap result: [ 5 ]

--- orig.js	2026-10-17 16:12:28.211307386 -0400
+++ fixed.js	2026-10-17 16:12:28.487301193 -0400
@@ -3,9 +3,9 @@
     function mapFn(x) { return [x, 0]; }
     const arr = [1, 2];
     console.log('mapped:', arr.map(mapFn));
-    const flat = arr.map(mapFn).flat();
+    const flat = arr.flatMap(mapFn);
     console.log('flat:', flat);
-    arr.map(mapFn).flat(); // expect_trigger
+    arr.flatMap(mapFn); // expect_trigger
   }
   switch (1) {
     case 1:

mapped: [ [ 1, 0 ], [ 2, 0 ] ]
flat: [ 1, 0, 2, 0 ]