oxc-project/oxc · warning · OxcDiagnostic

These overloads can be combined into one signature with an o

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'.

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. Merge into one signature with an optional parameter: `function parse(input: string, flags?: number): void;`.
2. If the overloads carry different JSDoc intentionally, enable `ignoreOverloadsWithDifferentJSDoc`.
3. Enable `ignoreDifferentlyNamedParameters` if only the parameter names differ.
4. 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;

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

• This overload can be combined with another overload into one
• 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/3abd0b422631a0ff. Report an issue: GitHub.