oxc-project/oxc · warning · OxcDiagnostic

`Array.flatMap` performs `Array.map` and `Array.flat` in one

Error message

`Array.flatMap` performs `Array.map` and `Array.flat` in one step.

What it means

Lint diagnostic from oxlint's `unicorn/prefer-array-flat-map` rule. Chaining `.map(fn).flat()` builds a whole mapped array and then a second flattened array; `.flatMap(fn)` does both in one pass and one allocation. The rule fires on `map(...).flat()` chains (and `flat(1)` depth) and offers a fixer to merge them.

Source

Thrown at crates/oxc_linter/src/rules/unicorn/prefer_array_flat_map.rs:12

use oxc_ast::{
    AstKind,
    ast::{Argument, CallExpression, Expression},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::{GetSpan, Span};

use crate::{AstNode, ast_util::is_method_call, context::LintContext, fixer::Fix, rule::Rule};

fn prefer_array_flat_map_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("`Array.flatMap` performs `Array.map` and `Array.flat` in one step.")
        .with_help("Prefer `.flatMap(…)` over `.map(…).flat()`.")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct PreferArrayFlatMap;

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Prefers the use of `.flatMap()` when `map().flat()` are used together.
    ///
    /// ### Why is this bad?
    ///
    /// It is slightly more efficient to use `.flatMap(…)` instead of `.map(…).flat()`.
    ///
    /// ### Examples
    ///

View on GitHub (pinned to e1e7af627c)

Solutions

1. Merge the chain: `arr.map(fn).flat()` -> `arr.flatMap(fn)`.
2. Run `oxlint --fix` for an automatic rewrite of every match.
3. Keep `.map().flat(2)` as-is (flatMap is depth-1 only) and suppress with an inline disable comment if flagged erroneously.
4. Disable the rule via `.oxlintrc.json` if depth-2+ flattening after map is a common pattern in the codebase.

Example fix

// before
const letters = words.map(w => w.split('')).flat();

// after
const letters = words.flatMap(w => w.split(''));

// oxlint --fix --filter unicorn/prefer-array-flat-map src/
// CI gate: oxlint --deny-warnings src/

When it happens

Trigger: Member-call chain where the result of `.map(predicate)` is immediately `.flat()`-ed: `words.map(w => w.split('')).flat()`, `lists.map(expand).flat(1)`. Detected while oxlint walks CallExpressions with `is_method_call` on `map` followed by `flat`.

Common situations: Tokenizers (map-to-split then flatten), normalize-and-expand pipelines. Very common in data-munging code. Hits in bulk when adopting the unicorn ruleset; autofix is generally safe but review when the map callback returns arrays-with-arrays (flat() default depth 1).

Related errors

• Prefer `find` over filtering and accessing the first result.
• Prefer Array#flat() over legacy techniques to flatten arrays
• Prefer `indexOf` over `findIndex` for simple equality checks
• Prefer `.some(…)` over non-zero length check from `.filter(…
• Avoid calls to the `Array` constructor

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/396cd6fd05663046. Report an issue: GitHub.