TypeScript
Uso de overloads para representar varias formas válidas de llamar una función, separar firmas públicas y mantener una implementación compatible.
Los overloads describen varias formas públicas de llamar una misma implementación cuando el retorno depende de los argumentos.
function parseInput(value: string): Product;
function parseInput(value: Product): Product;
function parseInput(value: string | Product): Product {
return typeof value === "string"
? JSON.parse(value)
: value;
}Las firmas superiores son visibles para el consumidor.
function format(value: number): string;
function format(value: Date): string;La firma de implementación debe ser compatible con todas:
function format(value: number | Date): string {
return value instanceof Date
? value.toISOString()
: value.toFixed(2);
}El consumidor no llama directamente la firma amplia de implementación si no aparece como overload público.
Úsalos cuando:
function printId(id: string | number): void {
console.log(id);
}No necesitas overloads porque el retorno y comportamiento público no dependen del tipo.
function getLength(value: string): number;
function getLength(value: readonly unknown[]): number;
function getLength(
value: string | readonly unknown[],
): number {
return value.length;
}Aquí una unión también podría bastar; el overload no aporta mucho. No los uses por decoración.
function createDate(timestamp: number): Date;
function createDate(
year: number,
month: number,
day: number,
): Date;
function createDate(
timestampOrYear: number,
month?: number,
day?: number,
): Date {
if (month !== undefined && day !== undefined) {
return new Date(timestampOrYear, month, day);
}
return new Date(timestampOrYear);
}El overload evita una llamada parcial inválida con dos argumentos.
function createDate(
value: number,
month?: number,
day?: number,
): DatePermitiría combinaciones que el runtime no admite. Los overloads pueden representar conjuntos de llamadas más exactos.
TypeScript evalúa overloads y elige la primera firma compatible suficientemente específica. Coloca firmas específicas antes de generales.
function handle(value: "special"): SpecialResult;
function handle(value: string): GeneralResult;type Search = {
(query: string): Promise<Product[]>;
(options: SearchOptions): Promise<Product[]>;
};const search: Search = async (
input: string | SearchOptions,
) => {
const options = typeof input === "string"
? { query: input }
: input;
return repository.search(options);
};class Cache {
get(key: string): unknown;
get<T>(key: string, parse: (value: unknown) => T): T;
get<T>(
key: string,
parse?: (value: unknown) => T,
): unknown {
const value = this.storage.get(key);
return parse ? parse(value) : value;
}
}Overloads:
function first(value: string[]): string | undefined;
function first(value: number[]): number | undefined;Generic más escalable:
function first<T>(
values: readonly T[],
): T | undefined {
return values[0];
}Usa generics cuando la relación es la misma para muchos tipos.
function convert(value: string): number;
function convert(value: number): string;
function convert(value: string): number {
return Number(value);
}La implementación no acepta number, por lo que no cumple el segundo overload.
La implementación puede usar una unión de retornos:
function convert(value: string): number;
function convert(value: number): string;
function convert(value: string | number): string | number {
return typeof value === "string"
? Number(value)
: String(value);
}function readSetting(key: "theme"): "light" | "dark";
function readSetting(key: "pageSize"): number;
function readSetting(
key: "theme" | "pageSize",
): "light" | "dark" | number {
const value = storage.getItem(key);
if (key === "theme") {
return value === "light" ? "light" : "dark";
}
return Number(value ?? 20);
}¿Por qué una firma con parámetros opcionales puede ser menos precisa que dos overloads de uno y tres argumentos?
Porque también permitiría la combinación intermedia de dos argumentos, aunque la implementación no tenga un contrato válido para ella.
Compatibilidad de funciones y variance explica cuándo una firma puede sustituir a otra.