{"record":{"id":"4ab3c7d4a83e86cd","repo":"oxc-project/oxc","slug":"prefer-top-level-await-over-using-a-promise-chain","errorCode":null,"errorMessage":"Prefer top-level await over using a promise chain.","messagePattern":"Prefer top-level await over using a promise chain\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/unicorn/prefer_top_level_await.rs","lineNumber":15,"sourceCode":"use oxc_ast::{\n    AstKind,\n    ast::{Expression, VariableDeclarationKind},\n};\nuse oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::{GetSpan, Span};\n\nuse crate::{\n    AstNode, ast_util::is_method_call, ast_util::variable_declaration_kind, context::LintContext,\n    rule::Rule,\n};\n\nfn prefer_top_level_await_over_promise_chain_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Prefer top-level await over using a promise chain.\").with_label(span)\n}\n\nfn prefer_top_level_await_over_async_iife_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Prefer top-level await over using an async IIFE.\").with_label(span)\n}\n\nfn prefer_top_level_await_over_async_function_call_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Prefer top-level await over an async function call.\")\n        .with_help(\"Add `await` before the function call.\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone)]\npub struct PreferTopLevelAwait;\n\ndeclare_oxc_lint!(\n    /// ### What it does\n    ///","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/unicorn/prefer_top_level_await.rs#L1-L33","documentation":"This is the promise-chain diagnostic of oxlint's `unicorn/prefer-top-level-await` rule. In an ES module (where top-level `await` is allowed), it flags promise chains like `fetch(url).then(...)` whose result is used at module top level, and recommends `await`ing the chain directly — removing scheduling indirection and letting you use try/catch and loops around async values.","triggerScenarios":"A top-level statement (typically `const x = promise.then(...)` — recognized via `variable_declaration_kind` and `is_method_call` for `.then`) in a module context, where the promise chain could be replaced by `const x = await promise...`. The rule only applies at the module top level, not inside functions.","commonSituations":"Config/module-init code like `const config = fetch('/config.json').then(r => r.json());` in ESM; migrating CommonJS scripts to ESM and modernizing `.then` chains. Requires the file to be a module (`\"type\": \"module\"`, `.mjs`, or ESM in the bundler) — in plain CJS scripts top-level await is a syntax error, so the rule's advice does not apply there.","solutions":["Add `await`: `const config = await (await fetch('/config.json')).json();`.","Ensure the file is an ES module (`.mjs` or `\"type\": \"module\"`) and your runtime/bundler supports top-level await (Node >= 14.8 with ESM flag-free since 16).","If the parallelism matters (multiple chains started concurrently), use `await Promise.all([...])` instead of sequential awaits.","Disable the rule with `\"unicorn/prefer-top-level-await\": \"off\"` for CJS-flavored code."],"exampleFix":"// before\nconst data = fetch(url).then((r) => r.json());\n\n// after\nconst data = await (await fetch(url)).json();","handlingStrategy":"validation","validationCode":"// In ESM, await module-scope async work directly\nconst config = await (await fetch('/config.json')).json();\n// CI: npx oxlint --deny-warn unicorn/prefer-top-level-await src/","typeGuard":null,"tryCatchPattern":"// Top-level await participates in normal try/catch at module scope\ntry {\n  const config = await loadConfig();\n} catch (err) {\n  handleBootFailure(err);\n}","preventionTips":["Ensure the file is ESM (`.mjs` or `\"type\": \"module\"`) before adopting top-level await.","Use `await Promise.all([...])` to keep concurrent chains parallel.","Keep top-level awaits near the top of the module — they block importing modules by design."],"tags":["oxlint","unicorn","async","top-level-await","esm"],"backgroundTag":"top-level-await-migration","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"}