oxc-project/oxc · warning · OxcDiagnostic

These overloads can be combined into one signature with an…

Error message

These overloads can be combined into one signature with an optional parameter.

What it means

Diagnostic from oxlint's `typescript/unified-signatures` rule. This variant fires when exactly two overloads differ only by trailing parameter(s) that can be omitted: parameter types match up to the common prefix and the longer signature's extra trailing parameter is a plain (non-rest) parameter, so the pair collapses into one signature with an optional parameter (`b?: T`). The diagnostic labels the extra parameter 'this parameter only appears in one overload' and the shorter signature's last parameter 'matching overload ends here'.

Solutions

Merge into one signature with an optional parameter: `function parse(input: string, flags?: number): void;`.
If the overloads carry different JSDoc intentionally, enable `ignoreOverloadsWithDifferentJSDoc`.
Enable `ignoreDifferentlyNamedParameters` if only the parameter names differ.
Suppress once with an inline disable comment if the split is semantically meaningful.

Example fix

// before
declare function createDate(ts: number): Date;
declare function createDate(ts: number, locale: string): Date;
// after
declare function createDate(ts: number, locale?: string): Date;

Defensive patterns

Strategy: validation

Prevention

Extend the existing signature with `param?: T` instead of adding an overload for an optional trailing argument.
Avoid overload pairs that differ only by trailing parameters — collapse them at authoring time.
Let the type checker confirm call sites still resolve after merging before deleting the shorter overload.

When it happens

Trigger: Two same-named signatures such as `function parse(input: string): void;` and `function parse(input: string, flags: number): void;` — same parameter types on the shared prefix, all parameters after the divergence point omittable (optional), and the shorter signature not ending in a rest parameter.

Common situations: APIs that grew an optional argument over time (locale, timeout, options) by appending an overload instead of making the parameter optional; generated .d.ts output; teams new to the typescript preset in oxlint.

Related errors

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

Appendix: 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)