{"record":{"id":"488de55c3e909fc9","repo":"oxc-project/oxc","slug":"avoid-nesting-promises","errorCode":null,"errorMessage":"Avoid nesting promises.","messagePattern":"Avoid nesting promises\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/promise/no_nesting.rs","lineNumber":13,"sourceCode":"use oxc_ast::{\n    AstKind,\n    ast::{CallExpression, Expression},\n};\nuse oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_semantic::ScopeId;\nuse oxc_span::{GetSpan, Span};\n\nuse crate::{AstNode, context::LintContext, rule::Rule, utils::is_promise};\n\nfn no_nesting_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Avoid nesting promises.\")\n        .with_help(\"Refactor so that promises are chained in a flat manner.\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone)]\npub struct NoNesting;\n\ndeclare_oxc_lint!(\n    /// ### What it does\n    ///\n    /// Disallow nested `then()` or `catch()` statements.\n    ///\n    /// ### Why is this bad?\n    ///\n    /// Nesting promises makes code harder to read and understand.\n    ///\n    /// ### Examples\n    ///","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/promise/no_nesting.rs#L1-L31","documentation":"Diagnostic from the oxlint rule `promise/no-nesting` (plugin `promise`). It flags calls to `.then()` or `.catch()` (any member call the rule's `is_promise` utility recognizes as promise-returning) made inside the callback of another `.then()`/`.catch()`, tracked via scope IDs of enclosing function scopes. Nested chains defeat the flat composability promises are designed for: each nested level needs its own error handling and the outer chain does not wait for the inner one.","triggerScenarios":"Invoking `promise.then(...)` or `promise.catch(...)` inside another `.then(fn)` callback body; wrapping per-item async work for an array inside a then handler without returning it.","commonSituations":"Migrating callback-style code to promises step by step; sequential dependent requests written inline; forgetting that returning the inner promise flattens the chain.","solutions":["Return the inner promise from the handler so the outer chain waits on it and errors flow to one `catch`","Rewrite the sequence with `async`/`await` inside a `try`/`catch`","For parallel inner work, return `Promise.all(items.map(...))` from the handler","If nesting is deliberate (rare), disable the rule inline with an oxlint suppression comment"],"exampleFix":"// before\napi.users().then(users => {\n  api.posts(users[0].id).then(posts => {\n    console.log(posts)\n  })\n})\n\n// after\napi.users()\n  .then(users => api.posts(users[0].id))\n  .then(posts => console.log(posts))","handlingStrategy":"validation","validationCode":"npx oxlint --promise/no-nesting src/","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Return inner promises from handlers instead of nesting new `.then()` calls inside them","Default to `async/await` for sequential logic","Enable the `promise` plugin in CI so nesting is caught at review time, not in production"],"tags":["promise","async","lint","code-style","oxlint"],"backgroundTag":"promise-callback-nesting","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}