oxc-project/oxc · warning · OxcDiagnostic

Magic number for `Array.prototype.flat` depth is not allowed

Error message

Magic number for `Array.prototype.flat` depth is not allowed.

What it means

Diagnostic from the oxlint rule `unicorn/no-magic-array-flat-depth` (category: restriction). `flat()` is normally called with depth 1 (the default) or Infinity (fully flatten); any other bare numeric literal hides intent — is `2` the data's actual nesting depth or a guess? The rule flags a numeric-literal depth other than 1 when there is no explaining comment inside the call parentheses, and the help suggests adding that comment.

Source

Thrown at crates/oxc_linter/src/rules/unicorn/no_magic_array_flat_depth.rs:9

use oxc_ast::{AstKind, ast::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, rule::Rule};

fn no_magic_array_flat_map_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Magic number for `Array.prototype.flat` depth is not allowed.")
        .with_help("Add a comment explaining the depth.")
        .with_label(span)
}

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

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Disallow magic numbers for [`Array.prototype.flat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat)
    /// depth.
    ///
    /// ### Why is this bad?
    ///
    /// Magic numbers are hard to understand and maintain.
    /// When calling `Array.prototype.flat`, it is usually called with
    /// `1` or `Infinity`. If you are using a different number, it is

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add an inline comment inside the call: `tree.flat(2 /* category -> item */)` — the rule's own escape hatch
2. Name the depth: `const SCHEMA_DEPTH = 2; tree.flat(SCHEMA_DEPTH)`
3. Use Infinity when full flattening is what you mean

Example fix

// before
const leaves = tree.flat(2);

// after
const leaves = tree.flat(2 /* category -> item */);
// or: const leaves = tree.flat(SCHEMA_DEPTH);

When it happens

Trigger: `tree.flat(2)`, `nested.flat(20)`, `array.flat(0b10)` — exactly one numeric literal argument to `.flat()`, value not equal to 1, and no comment between the `(` and the argument. `flat()`, `flat(1)`, `flat(Infinity)`, `flat(Number.POSITIVE_INFINITY)`, `flat(depthVariable)`, and `flat(2 /* explanation */)` all pass.

Common situations: Flattening API responses or trees with known nesting levels; porting recursive flattening to `flat()`; teams requiring depth choices to be documented.

Related errors

• Avoid calls to the `Array` constructor
• No magic number: {raw}
• Unexpected comma in middle of array
• {} unexpected commas in middle of array
• Use Array destructuring.

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