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 an optional parameter.

What it means

Diagnostic from oxlint's `typescript/unified-signatures` rule, optional-parameter variant with singular wording: the overload group contains more than two signatures, so oxlint points at one overload that can be combined with another whose extra trailing parameter is a plain parameter that could simply be optional. The comparison logic requires identical parameter types on the shared prefix and omittable parameters beyond the divergence point.

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

1. Replace the flagged pair with a single signature using an optional parameter (`param?: T`).
2. If each overload documents a distinct case in JSDoc, set `ignoreOverloadsWithDifferentJSDoc: true` before re-running.
3. Set `ignoreDifferentlyNamedParameters: true` if parameter naming is the only intentional difference.
4. Disable the rule for that declaration file via an inline comment or override.

Example fix

// before
declare function query<T>(sql: string): Promise<T>;
declare function query<T>(sql: string, params: unknown[]): Promise<T>;
declare function query<T>(sql: string, opts: QueryOptions): Promise<T>;
// after
declare function query<T>(sql: string, params?: unknown[]): Promise<T>;
declare function query<T>(sql: string, opts: QueryOptions): Promise<T>;

When it happens

Trigger: Three or more same-named signatures where two of them share identical parameter types up to a prefix and one adds only a trailing non-rest parameter (required or optional), while the shorter of the pair does not itself end in a rest parameter.

Common situations: Large overload families for config-driven APIs where an options argument was bolted on via extra overloads; interface declarations merged from multiple modules; lint cleanups after enabling stricter TypeScript linting presets.

Related errors

• These overloads can be combined into one signature with an o
• These overloads can be combined into one signature with a re
• This overload can be combined with another overload into one
• Type can be trivially inferred from the initializer
• Prefer using inline type specifiers instead of a top-level t

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