{"record":{"id":"08c0d365a8153c82","repo":"oxc-project/oxc","slug":"prefer-top-level-await-over-an-async-function-call","errorCode":null,"errorMessage":"Prefer top-level await over an async function call.","messagePattern":"Prefer top-level await over an async function call\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/unicorn/prefer_top_level_await.rs","lineNumber":23,"sourceCode":"use 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    ///\n    /// Prefer top-level await over top-level promises and async function calls.\n    ///\n    /// ### Why is this bad?\n    ///\n    /// Top-level await is more readable and can prevent unhandled rejections.\n    ///\n    /// ### Examples\n    ///","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/unicorn/prefer_top_level_await.rs#L5-L41","documentation":"This is the async-function-call diagnostic of oxlint's `unicorn/prefer-top-level-await`. It fires when a module top-level statement calls an async function (a function declared `async`, or returning a promise) without awaiting it — the floating-promise pattern — and suggests adding `await` before the call ('Add `await` before the function call.').","triggerScenarios":"A top-level expression statement or initializer whose callee is an `async` function declaration/identifier invoked without `await` (e.g. `init();` where `async function init() {}`); the rule matches the call via method/identifier checks at module scope.","commonSituations":"Bootstrap scripts calling `connect();` or `warmCache();` that are actually async — the module finishes evaluating before the work completes, causing races with imports that depend on the side effect. Common when converting scripts to ESM where ordering guarantees of top-level await matter.","solutions":["Add `await`: `await init();`.","If fire-and-forget is intentional, make it explicit with `void init();` (many configs accept `void`) or attach `.catch()` to handle rejection, then disable the rule for that line.","If other top-level code should not block, restructure so dependents import a promise and await it themselves.","For CJS files where TLA is unavailable, disable `unicorn/prefer-top-level-await`."],"exampleFix":"// before\ninit();\n\n// after\nawait init();","handlingStrategy":"validation","validationCode":"// Make floating async calls explicit\nawait init();          // blocking, ordered\nvoid init();           // intentional fire-and-forget\ninit().catch(log);     // fire-and-forget with rejection handling","typeGuard":"// Narrow before calling at top level: is it actually async?\nfunction returnsPromise(fn) {\n  return typeof fn === 'function' && fn.constructor.name === 'AsyncFunction';\n}","tryCatchPattern":null,"preventionTips":["Never call an async initializer bare at module top level — await it or void it.","Use `void` (or `.catch`) to document intentional fire-and-forget so both readers and the rule see intent.","Order top-level awaits to match dependency needs; importers block on your module until they settle."],"tags":["oxlint","unicorn","async","floating-promise","top-level-await"],"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-14T05:17:10.506Z"}