oxc-project/oxc · warning · OxcDiagnostic

This overload can be combined with another overload into one

Error message

This overload can be combined with another overload into one signature with a rest parameter.

What it means

Diagnostic from oxlint's `typescript/unified-signatures` rule. When more than two overloads share the same name in the scanned scope, oxlint reports with the singular wording 'This overload can be combined with another overload...', labeling the parameter that only appears in one signature. The rest-parameter variant means the flagged pair differs only in that one signature adds a trailing `...rest` that the other lacks.

Source

Thrown at crates/oxc_linter/src/rules/typescript/unified_signatures.rs:30

};
use oxc_diagnostics::{LabeledSpan, OxcDiagnostic};
use oxc_macros::declare_oxc_lint;
use oxc_span::{GetSpan, Span};
use rustc_hash::{FxHashMap, FxHashSet};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::{
    AstNode,
    context::{ContextHost, LintContext},
    rule::{DefaultRuleConfig, Rule},
};

fn unified_signatures_diagnostic<L: Into<LabeledSpan>, T: IntoIterator<Item = L>>(
    message: String,
    labels: T,
) -> OxcDiagnostic {
    OxcDiagnostic::warn(message).with_labels(labels)
}

#[derive(Debug, Default, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(default, rename_all = "camelCase", deny_unknown_fields)]
pub struct UnifiedSignaturesOptions {
    /// Whether to ignore parameter name differences when comparing signatures. If `false`, signatures
    /// will not be considered unifiable if they have parameters in the same position with different
    /// names, even if the parameter types are the same.
    ignore_differently_named_parameters: bool,
    /// Whether to ignore JSDoc differences when comparing signatures. If `false`, signatures will not
    /// be considered unifiable if the closest leading block comments for the signatures are different,
    /// even if the signatures themselves are identical.
    #[serde(rename = "ignoreOverloadsWithDifferentJSDoc")]
    ignore_overloads_with_different_jsdoc: bool,
}

#[derive(Debug, Default, Clone, Deserialize, Serialize)]
pub struct UnifiedSignatures(UnifiedSignaturesOptions);

View on GitHub (pinned to e1e7af627c)

Solutions

Merge the flagged pair: drop the shorter overload and keep the one with the rest parameter.
If other overloads in the group make the split intentional, enable `ignoreOverloadsWithDifferentJSDoc` so only JSDoc-distinct splits survive.
Enable `ignoreDifferentlyNamedParameters` if the pair differs only by parameter names on purpose.
Disable the rule for the declaration file with an inline comment or a per-file override in .oxlintrc.json.

Example fix

// before
declare function f(a: number): void;
declare function f(a: number, ...rest: string[]): void;
declare function f(a: boolean): void;
// after
declare function f(a: number, ...rest: string[]): void;
declare function f(a: boolean): void;

Defensive patterns

Strategy: validation

Prevention

When adding a trailing rest variant of an existing signature, replace the original instead of adding a sibling.
Keep overload families small; audit them whenever a third overload with the same name appears.
Run oxlint locally with the typescript preset before pushing so merges are caught pre-review.

When it happens

Trigger: Three or more same-named signatures where two of them have identical parameters up to the common prefix, the shorter of the pair does not end in a rest parameter, and the longer adds only a rest parameter. Runs only when the file is parsed as TypeScript (`should_run` checks `source_type().is_typescript()`).

Common situations: Broad public API surfaces (event emitters, HTTP clients) with many overloads; refactoring sessions where an overload family grows past two entries; CI lint runs after merging several branches that each added an overload.

Related errors

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