fix(lint/noFloatingPromises): select the matching overload for floating-promise checks

IxxyDev · IxxyDev · commit 0e56104685ee · 2026-06-08T16:57:57.000+03:00
Calling an overloaded function resolved to a single, arbitrary signature, so `noFloatingPromises` judged the call by the first overload's return type. When that overload returned a promise but the selected one did not, the call was flagged incorrectly (#9568). A set of same-name function declarations now resolves to an object carrying one call signature per declaration. At a call site, the first signature whose parameters accept the arguments is selected, in declaration order, using a narrow promise-aware check plus an arity check (no general assignability). The call's return type is then taken from the selected signature, so a non-promise overload is no longer flagged while a promise-returning one still is.
diff --git a/.changeset/fix-no-floating-promises-overloads.md b/.changeset/fix-no-floating-promises-overloads.md
@@ -0,0 +1,17 @@
+---
+"@biomejs/biome": patch
+---
+
+Fixed [#9568](https://github.com/biomejs/biome/issues/9568): [`noFloatingPromises`](https://biomejs.dev/linter/rules/no-floating-promises/) no longer reports a false positive when calling an overloaded function and the selected overload does not return a promise.
+
+```ts
+function bestEffort(cb: () => Promise<number>): Promise<number>;
+function bestEffort(cb: () => number): number;
+function bestEffort(cb: () => number | Promise<number>): Promise<number> | number {
+	return cb() as Promise<number> | number;
+}
+
+// This resolves to the second overload, which returns `number`, so it is no
+// longer flagged as a floating promise.
+bestEffort(() => 42);
+```
diff --git a/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_generic.ts b/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_generic.ts
@@ -0,0 +1,15 @@
+/* should not generate diagnostics */
+
+function bestEffort<T>(cb: () => Promise<T>): Promise<T | undefined>;
+function bestEffort<T>(cb: () => T): T | undefined;
+function bestEffort<T>(cb: (() => T) | (() => Promise<T>)): Promise<T | undefined> | T | undefined {
+	return undefined;
+}
+
+function syncWork(): number {
+	return 42;
+}
+
+// Generic overload exactly like the reported issue: selects the second
+// overload (sync), so it must NOT be flagged.
+bestEffort(syncWork);
diff --git a/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_generic.ts.snap b/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_generic.ts.snap
@@ -0,0 +1,23 @@
+---
+source: crates/biome_js_analyze/tests/spec_tests.rs
+expression: issue9568_generic.ts
+---
+# Input
+```ts
+/* should not generate diagnostics */
+
+function bestEffort<T>(cb: () => Promise<T>): Promise<T | undefined>;
+function bestEffort<T>(cb: () => T): T | undefined;
+function bestEffort<T>(cb: (() => T) | (() => Promise<T>)): Promise<T | undefined> | T | undefined {
+	return undefined;
+}
+
+function syncWork(): number {
+	return 42;
+}
+
+// Generic overload exactly like the reported issue: selects the second
+// overload (sync), so it must NOT be flagged.
+bestEffort(syncWork);
+
+```
diff --git a/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_invalid.ts b/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_invalid.ts
@@ -0,0 +1,13 @@
+function bestEffort(cb: () => Promise<number>): Promise<number>;
+function bestEffort(cb: () => number): number;
+function bestEffort(cb: () => number | Promise<number>): Promise<number> | number {
+	return cb() as Promise<number> | number;
+}
+
+async function asyncWork(): Promise<number> {
+	return 42;
+}
+
+// Resolves to the first overload (async callback) -> returns a promise,
+// so this floating call must still be flagged.
+bestEffort(asyncWork);
diff --git a/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_invalid.ts.snap b/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_invalid.ts.snap
@@ -0,0 +1,40 @@
+---
+source: crates/biome_js_analyze/tests/spec_tests.rs
+expression: issue9568_invalid.ts
+---
+# Input
+```ts
+function bestEffort(cb: () => Promise<number>): Promise<number>;
+function bestEffort(cb: () => number): number;
+function bestEffort(cb: () => number | Promise<number>): Promise<number> | number {
+	return cb() as Promise<number> | number;
+}
+
+async function asyncWork(): Promise<number> {
+	return 42;
+}
+
+// Resolves to the first overload (async callback) -> returns a promise,
+// so this floating call must still be flagged.
+bestEffort(asyncWork);
+
+```
+
+# Diagnostics
+```
+issue9568_invalid.ts:13:1 lint/nursery/noFloatingPromises ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i A "floating" Promise was found, meaning it is not properly handled and could lead to ignored errors or unexpected behavior.
+  
+    11 │ // Resolves to the first overload (async callback) -> returns a promise,
+    12 │ // so this floating call must still be flagged.
+  > 13 │ bestEffort(asyncWork);
+       │ ^^^^^^^^^^^^^^^^^^^^^^
+    14 │ 
+  
+  i This happens when a Promise is not awaited, lacks a `.catch` or `.then` rejection handler, or is not explicitly ignored using the `void` operator.
+  
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+  
+
+```
diff --git a/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_valid.ts b/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_valid.ts
@@ -0,0 +1,15 @@
+/* should not generate diagnostics */
+
+function bestEffort(cb: () => Promise<number>): Promise<number>;
+function bestEffort(cb: () => number): number;
+function bestEffort(cb: () => number | Promise<number>): Promise<number> | number {
+	return cb() as Promise<number> | number;
+}
+
+function syncWork(): number {
+	return 42;
+}
+
+// Resolves to the second overload (sync callback) -> returns `number`,
+// which is not a promise, so this must NOT be flagged.
+bestEffort(syncWork);
diff --git a/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_valid.ts.snap b/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/issue9568_valid.ts.snap
@@ -0,0 +1,23 @@
+---
+source: crates/biome_js_analyze/tests/spec_tests.rs
+expression: issue9568_valid.ts
+---
+# Input
+```ts
+/* should not generate diagnostics */
+
+function bestEffort(cb: () => Promise<number>): Promise<number>;
+function bestEffort(cb: () => number): number;
+function bestEffort(cb: () => number | Promise<number>): Promise<number> | number {
+	return cb() as Promise<number> | number;
+}
+
+function syncWork(): number {
+	return 42;
+}
+
+// Resolves to the second overload (sync callback) -> returns `number`,
+// which is not a promise, so this must NOT be flagged.
+bestEffort(syncWork);
+
+```
diff --git a/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/overloadSelectedByArity.ts b/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/overloadSelectedByArity.ts
@@ -0,0 +1,13 @@
+/* should not generate diagnostics */
+
+function run(cb: () => void): Promise<void>;
+function run(cb: () => void, immediate: boolean): void;
+function run(cb: () => void, immediate?: boolean): Promise<void> | void {
+	return immediate ? cb() : Promise.resolve();
+}
+
+function task(): void {}
+
+// Two arguments select the second overload (returns `void`, not a promise),
+// so this must NOT be flagged.
+run(task, true);
diff --git a/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/overloadSelectedByArity.ts.snap b/crates/biome_js_analyze/tests/specs/nursery/noFloatingPromises/overloadSelectedByArity.ts.snap
@@ -0,0 +1,21 @@
+---
+source: crates/biome_js_analyze/tests/spec_tests.rs
+expression: overloadSelectedByArity.ts
+---
+# Input
+```ts
+/* should not generate diagnostics */
+
+function run(cb: () => void): Promise<void>;
+function run(cb: () => void, immediate: boolean): void;
+function run(cb: () => void, immediate?: boolean): Promise<void> | void {
+	return immediate ? cb() : Promise.resolve();
+}
+
+function task(): void {}
+
+// Two arguments select the second overload (returns `void`, not a promise),
+// so this must NOT be flagged.
+run(task, true);
+
+```
diff --git a/crates/biome_js_semantic/src/semantic_model/scope.rs b/crates/biome_js_semantic/src/semantic_model/scope.rs
@@ -131,6 +131,15 @@ impl Scope {
         data.bindings_by_name.get(name).cloned()
     }
 
+    /// Returns the [TsBindingReference] of every name bound in this scope.
+    pub fn binding_references(&self) -> Vec<TsBindingReference> {
+        self.data.scopes[self.id.index()]
+            .bindings_by_name
+            .values()
+            .cloned()
+            .collect()
+    }
+
     /// Checks if the current scope is one of the ancestor of "other". Given
     /// that [Scope::ancestors] return "self" as the first scope,
     /// this function returns true for:
diff --git a/crates/biome_js_type_info/src/flattening/expressions.rs b/crates/biome_js_type_info/src/flattening/expressions.rs
@@ -443,12 +443,109 @@ fn flattened_call(
             }
         }
         callee => {
-            let function = resolve_callee_to_function(callee, resolver)?;
+            let function = match select_overload(&callee, &expr.arguments, resolver) {
+                Some(function) => function,
+                None => resolve_callee_to_function(callee, resolver)?,
+            };
             flattened_function_call(expr, &function, resolver)
         }
     }
 }
 
+/// Selects an overload when the callee is an object or interface carrying more
+/// than one call signature. This is the shape produced for a set of same-name
+/// function declarations, but it also applies to a hand-written interface with
+/// multiple call signatures.
+///
+/// Mirroring TypeScript, the first signature whose parameters accept the
+/// arguments wins, in declaration order. Returns `None` when the callee is not
+/// such an object, or when no signature matches; in both cases the caller falls
+/// back to the regular single-signature resolution.
+fn select_overload(
+    callee: &TypeData,
+    arguments: &[CallArgumentType],
+    resolver: &dyn TypeResolver,
+) -> Option<Box<Function>> {
+    let resolved = ResolvedTypeData::from((ResolverId::from_level(resolver.level()), callee));
+    let signatures: Vec<TypeReference> = resolved
+        .all_members(resolver)
+        .filter(|member| member.kind().is_call_signature())
+        .map(|member| member.to_member().deref_ty(resolver).into_owned())
+        .collect();
+    if signatures.len() < 2 {
+        return None;
+    }
+
+    signatures.iter().find_map(|signature| {
+        match resolver
+            .resolve_and_get(signature)
+            .map(ResolvedTypeData::to_data)
+        {
+            Some(TypeData::Function(function))
+                if signature_accepts_arguments(&function, arguments, resolver) =>
+            {
+                Some(function)
+            }
+            _ => None,
+        }
+    })
+}
+
+/// Narrow applicability check used for overload selection.
+///
+/// This is deliberately not a general assignability check: it only
+/// disambiguates overloads that differ by whether a callback argument returns a
+/// promise, which is the case that matters for promise-related rules. Arguments
+/// that are not functions place no constraint on the signature.
+fn signature_accepts_arguments(
+    function: &Function,
+    arguments: &[CallArgumentType],
+    resolver: &dyn TypeResolver,
+) -> bool {
+    let parameters = &function.parameters;
+    let accepts_rest = parameters.last().is_some_and(FunctionParameter::is_rest);
+    let required = parameters
+        .iter()
+        .filter(|parameter| !parameter.is_optional() && !parameter.is_rest())
+        .count();
+    if arguments.len() < required || (!accepts_rest && arguments.len() > parameters.len()) {
+        return false;
+    }
+
+    parameters
+        .iter()
+        .zip(arguments)
+        .all(|(parameter, argument)| {
+            let (CallArgumentType::Argument(argument) | CallArgumentType::Spread(argument)) =
+                argument;
+            match (
+                resolve_function(parameter.ty(), resolver),
+                resolve_function(argument, resolver),
+            ) {
+                (Some(parameter_fn), Some(argument_fn)) => {
+                    function_returns_promise(&parameter_fn, resolver)
+                        == function_returns_promise(&argument_fn, resolver)
+                }
+                _ => true,
+            }
+        })
+}
+
+fn resolve_function(ty: &TypeReference, resolver: &dyn TypeResolver) -> Option<Box<Function>> {
+    match resolver.resolve_and_get(ty)?.to_data() {
+        TypeData::Function(function) => Some(function),
+        _ => None,
+    }
+}
+
+fn function_returns_promise(function: &Function, resolver: &dyn TypeResolver) -> bool {
+    function
+        .return_type
+        .as_type()
+        .and_then(|return_ty| resolver.resolve_and_get(return_ty))
+        .is_some_and(|resolved| resolved.is_promise_instance(resolver))
+}
+
 fn flattened_destructure(
     expr: &TypeofDestructureExpression,
     resolver: &mut dyn TypeResolver,
diff --git a/crates/biome_js_type_info/src/type_data.rs b/crates/biome_js_type_info/src/type_data.rs
@@ -573,6 +573,20 @@ impl FunctionParameter {
             Self::Pattern(pattern) => &pattern.ty,
         }
     }
+
+    pub fn is_optional(&self) -> bool {
+        match self {
+            Self::Named(named) => named.is_optional,
+            Self::Pattern(pattern) => pattern.is_optional,
+        }
+    }
+
+    pub fn is_rest(&self) -> bool {
+        match self {
+            Self::Named(named) => named.is_rest,
+            Self::Pattern(pattern) => pattern.is_rest,
+        }
+    }
 }
 
 /// A plain function parameter where the name of the parameter is also the name
diff --git a/crates/biome_module_graph/src/js_module_info/collector.rs b/crates/biome_module_graph/src/js_module_info/collector.rs
@@ -409,6 +409,32 @@ impl JsModuleInfoCollector {
                 self.bindings[index].ty = ty;
             }
         }
+
+        // A set of same-name function overloads becomes an object with one call
+        // signature per declaration, placed on the binding that name resolution
+        // returns for the set (its last one) so a call site can select among them.
+        let carriers: Vec<(usize, Vec<TypeMember>)> = semantic_model
+            .scopes()
+            .flat_map(|scope| scope.binding_references())
+            .filter_map(|binding_ref| match binding_ref {
+                TsBindingReference::Overloaded(set) => {
+                    let signatures = set
+                        .iter()
+                        .map(|id| TypeMember {
+                            kind: TypeMemberKind::CallSignature,
+                            ty: self.bindings[id.index()].ty.clone(),
+                        })
+                        .collect();
+                    let representative = set.last().expect("overload set is never empty").index();
+                    Some((representative, signatures))
+                }
+                _ => None,
+            })
+            .collect();
+        for (representative, signatures) in carriers {
+            let ty = self.reference_to_owned_data(TypeData::object_with_members(signatures.into()));
+            self.bindings[representative].ty = ty;
+        }
     }
 
     fn has_writable_reference(&self, semantic_model: &SemanticModel, range: TextRange) -> bool {
