Declaración de funciones con tipos

En TypeScript, las funciones son bloques de código reutilizables que pueden recibir datos, procesarlos y devolver resultados. A diferencia de JavaScript, TypeScript nos permite especificar tipos para los parámetros y valores de retorno, lo que mejora la seguridad y legibilidad del código.

Sintaxis básica

La sintaxis para declarar una función con tipos en TypeScript sigue este patrón:

function nombreFuncion(parametro1: tipo1, parametro2: tipo2): tipoRetorno {
  // Cuerpo de la función
  return valor;
}

Veamos un ejemplo simple:

function sum(a: number, b: number): number {
  return a + b;
}

// Uso correcto
const result = sum(5, 3); // result = 8

// Error de tipo en tiempo de compilación
// const invalidResult = sum("5", 3); // Error: Argument of type 'string' is not assignable to parameter of type 'number'

En este ejemplo, la función sum acepta dos parámetros de tipo number y devuelve un valor también de tipo number. TypeScript verificará que siempre llamemos a esta función con los tipos correctos.

Funciones como expresiones

También podemos definir funciones como expresiones con tipos:

// Función como expresión con tipos explícitos
const multiply: (x: number, y: number) => number = function(x, y) {
  return x * y;
};

// Versión más concisa
const divide = function(x: number, y: number): number {
  return x / y;
};

Inferencia de tipos

TypeScript puede inferir el tipo de retorno basándose en las sentencias de retorno de la función:

// El tipo de retorno (boolean) es inferido automáticamente
function isAdult(age: number) {
  return age >= 18;
}

Sin embargo, es una buena práctica especificar explícitamente el tipo de retorno para funciones más complejas, ya que mejora la legibilidad y evita errores accidentales.

Funciones sin valor de retorno

Para funciones que no devuelven un valor, usamos el tipo void:

function logMessage(message: string): void {
  console.log(message);
  // No hay return, o podría ser: return; (sin valor)
}

Funciones con múltiples tipos de parámetros

Podemos usar uniones de tipos para permitir diferentes tipos en los parámetros:

function formatValue(value: string | number): string {
  if (typeof value === 'number') {
    return value.toFixed(2);
  }
  return value.trim();
}

formatValue("  Hello  "); // "Hello"
formatValue(42.1234);     // "42.12"

Parámetros rest tipados

Los parámetros rest permiten pasar un número variable de argumentos a una función:

function sum(...numbers: number[]): number {
  return numbers.reduce((total, num) => total + num, 0);
}

sum(1, 2);           // 3
sum(1, 2, 3, 4, 5);  // 15

Sobrecarga de funciones

TypeScript permite sobrecargar funciones para manejar diferentes tipos de parámetros:

// Declaraciones de sobrecarga
function processInput(input: number): number;
function processInput(input: string): string;

// Implementación
function processInput(input: number | string): number | string {
  if (typeof input === 'number') {
    return input * 2;
  } else {
    return input.toUpperCase();
  }
}

const a = processInput(10);     // Tipo: number
const b = processInput("hello"); // Tipo: string

Funciones como tipos

En TypeScript, podemos definir tipos de función que describen la firma de una función:

// Definición de un tipo de función
type MathOperation = (x: number, y: number) => number;

// Funciones que implementan este tipo
const add: MathOperation = (a, b) => a + b;
const subtract: MathOperation = (a, b) => a - b;

// Función que acepta otra función como parámetro
function calculate(a: number, b: number, operation: MathOperation): number {
  return operation(a, b);
}

calculate(10, 5, add);      // 15
calculate(10, 5, subtract); // 5

Contexto de tipo

TypeScript utiliza el contexto de tipo para inferir tipos en funciones anónimas:

// El tipo de callback se infiere del contexto
const numbers = [1, 2, 3, 4, 5];

// TypeScript infiere que 'num' es de tipo number
numbers.forEach(num => {
  console.log(num.toFixed(2));
});

Funciones genéricas

Para funciones que trabajan con múltiples tipos de manera flexible, podemos usar genéricos:

function firstElement<T>(array: T[]): T | undefined {
  return array.length > 0 ? array[0] : undefined;
}

// TypeScript infiere el tipo correcto en cada caso
const first1 = firstElement([1, 2, 3]);          // Tipo: number
const first2 = firstElement(["a", "b", "c"]);    // Tipo: string
const first3 = firstElement<boolean>([true, false]); // Tipo: boolean (explícito)

Las funciones con tipos son uno de los pilares fundamentales de TypeScript, ya que proporcionan una capa adicional de seguridad y documentación en el código. Al definir claramente qué tipos de datos espera una función y qué tipo de datos devolverá, reducimos significativamente la posibilidad de errores y facilitamos el mantenimiento del código.

Parámetros opcionales y por defecto

En TypeScript, no siempre necesitamos que todos los parámetros de una función sean obligatorios. A veces queremos permitir cierta flexibilidad en cómo se llaman nuestras funciones, haciendo que algunos parámetros sean opcionales o tengan valores predeterminados.

Parámetros opcionales

Para definir un parámetro como opcional, simplemente añadimos un signo de interrogación (?) después del nombre del parámetro:

function greet(name: string, greeting?: string): string {
  if (greeting) {
    return `${greeting}, ${name}!`;
  }
  return `Hello, ${name}!`;
}

// Ambas llamadas son válidas
greet("Alice");                // "Hello, Alice!"
greet("Bob", "Good morning");  // "Good morning, Bob!"

En este ejemplo, el parámetro greeting es opcional. Cuando no se proporciona, la función utiliza una lógica alternativa.

Algunas consideraciones importantes:

• Los parámetros opcionales deben aparecer después de los parámetros obligatorios:

// Correcto
function createUser(name: string, age?: number): void { /* ... */ }

// Incorrecto - Error de compilación
// function invalidFunction(optional?: string, required: number): void { /* ... */ }

• Cuando accedemos a un parámetro opcional dentro de la función, TypeScript nos obliga a verificar su existencia para evitar errores:

function processConfig(config?: { timeout: number }): number {
  // TypeScript nos advierte si intentamos acceder directamente
  // return config.timeout; // Error: Object is possibly 'undefined'
  
  // La forma correcta es verificar primero
  return config ? config.timeout : 1000;
}

Parámetros con valores por defecto

Una alternativa a los parámetros opcionales es proporcionar valores por defecto. Estos se utilizan cuando el parámetro no se proporciona o es undefined:

function buildUrl(path: string, domain: string = "example.com"): string {
  return `https://${domain}/${path}`;
}

buildUrl("products");              // "https://example.com/products"
buildUrl("services", "mysite.com"); // "https://mysite.com/services"

Los parámetros con valores por defecto tienen estas características:

• A diferencia de los parámetros opcionales, no necesitan el signo ?
• El tipo se infiere del valor por defecto, aunque también podemos especificarlo explícitamente
• Al igual que los parámetros opcionales, son efectivamente opcionales al llamar a la función

// El tipo de 'level' se infiere como string
function logMessage(message: string, level = "info"): void {
  console.log(`[${level}]: ${message}`);
}

// Con tipo explícito
function fetchData(id: string, cache: boolean = true): Promise<any> {
  // Implementación...
  return Promise.resolve({});
}

Combinando parámetros opcionales y por defecto

Podemos combinar ambos enfoques según nuestras necesidades:

function createElement(
  tag: string,
  content: string = "",
  attributes?: { [key: string]: string }
): HTMLElement {
  const element = document.createElement(tag);
  element.textContent = content;
  
  if (attributes) {
    Object.entries(attributes).forEach(([key, value]) => {
      element.setAttribute(key, value);
    });
  }
  
  return element;
}

// Diferentes formas de llamar a la función
createElement("div");
createElement("p", "Hello world");
createElement("a", "Click me", { href: "https://example.com", target: "_blank" });

Parámetros opcionales vs. valores por defecto

Aunque similares, hay diferencias importantes entre ambos enfoques:

• Parámetros opcionales (param?: type):

• El parámetro puede ser omitido

• Dentro de la función, el tipo es type | undefined

• No hay valor predeterminado, debemos manejar el caso undefined explícitamente

• Parámetros con valor por defecto (param: type = value):

• El parámetro puede ser omitido

• El tipo es simplemente type (no incluye undefined)

• Se usa automáticamente el valor por defecto cuando no se proporciona el parámetro

// Comparación de ambos enfoques
function configureApp(
  name: string,
  port?: number,            // Opcional: number | undefined
  environment: string = "development" // Por defecto: siempre string
) {
  const appPort = port || 3000;  // Necesitamos manejar undefined
  console.log(`Starting ${name} in ${environment} mode on port ${appPort}`);
}

Destructuración con parámetros opcionales y por defecto

La destructuración de objetos funciona muy bien con parámetros opcionales y valores por defecto:

interface UserOptions {
  name: string;
  age?: number;
  role?: string;
  active?: boolean;
}

function registerUser({
  name,
  age = 18,
  role = "user",
  active = true
}: UserOptions): void {
  console.log(`Registering ${name}, age: ${age}, role: ${role}, active: ${active}`);
}

// Todas estas llamadas son válidas
registerUser({ name: "Alice" });
registerUser({ name: "Bob", age: 25 });
registerUser({ name: "Charlie", role: "admin", active: false });

Parámetros rest con tipos

Los parámetros rest también pueden combinarse con parámetros opcionales y por defecto:

function joinStrings(
  separator: string = ",",
  prefix: string = "",
  ...items: string[]
): string {
  return prefix + items.join(separator);
}

joinStrings("-", ">", "apple", "banana", "cherry"); // ">apple-banana-cherry"
joinStrings(undefined, "List: ", "one", "two");     // "List: one,two"
joinStrings();                                      // "" (sin elementos)

Uso práctico en APIs y configuraciones

Los parámetros opcionales y por defecto son especialmente útiles al diseñar APIs flexibles:

interface RequestConfig {
  url: string;
  method?: "GET" | "POST" | "PUT" | "DELETE";
  headers?: Record<string, string>;
  timeout?: number;
  retries?: number;
}

function fetchAPI(config: RequestConfig): Promise<Response> {
  const finalConfig = {
    method: config.method || "GET",
    headers: config.headers || {},
    timeout: config.timeout ?? 30000,
    retries: config.retries ?? 3
  };
  
  // Implementación del fetch...
  return fetch(config.url, {
    method: finalConfig.method,
    headers: finalConfig.headers
  });
}

// Uso simple
fetchAPI({ url: "https://api.example.com/data" });

// Uso avanzado
fetchAPI({
  url: "https://api.example.com/users",
  method: "POST",
  headers: { "Content-Type": "application/json" },
  timeout: 5000
});

El uso adecuado de parámetros opcionales y valores por defecto hace que nuestras funciones sean más flexibles y fáciles de usar, permitiendo diferentes patrones de llamada mientras mantenemos la seguridad de tipos que TypeScript proporciona.

Tipos de retorno explícitos

En TypeScript, especificar el tipo de retorno de una función de manera explícita es una práctica fundamental que mejora la claridad del código y proporciona información valiosa tanto para los desarrolladores como para el compilador. Aunque TypeScript puede inferir automáticamente el tipo de retorno en muchos casos, declararlo explícitamente ofrece ventajas significativas.

Sintaxis básica

Para declarar explícitamente el tipo de retorno de una función, se utiliza la siguiente sintaxis:

function nombreFuncion(parametros): TipoRetorno {
  // Cuerpo de la función
  return valor;
}

El tipo de retorno se coloca después de los paréntesis de los parámetros y antes del cuerpo de la función:

function calculateArea(radius: number): number {
  return Math.PI * radius * radius;
}

Beneficios de los tipos de retorno explícitos

• Documentación integrada: Comunica claramente qué esperar de la función.
• Detección temprana de errores: El compilador verifica que todos los caminos de retorno coincidan con el tipo declarado.
• Mejora del autocompletado: Los editores pueden ofrecer sugerencias más precisas al trabajar con el valor retornado.
• Contratos de API más claros: Especialmente útil en interfaces públicas y bibliotecas.

Tipos de retorno comunes

TypeScript ofrece varios tipos de retorno que podemos utilizar según nuestras necesidades:

• Tipos primitivos:

function getName(): string {
  return "John Doe";
}

function getAge(): number {
  return 30;
}

function isActive(): boolean {
  return true;
}

• Arrays y objetos:

function getUsers(): string[] {
  return ["Alice", "Bob", "Charlie"];
}

function getUserInfo(): { name: string; age: number } {
  return { name: "Alice", age: 28 };
}

• Uniones de tipos:

function getIdValue(): string | number {
  // Podría devolver un string o un number dependiendo de alguna condición
  if (Math.random() > 0.5) {
    return "ABC123";
  }
  return 12345;
}

El tipo void

Cuando una función no devuelve ningún valor, utilizamos el tipo void:

function logMessage(message: string): void {
  console.log(message);
  // No hay return, o podría ser simplemente: return;
}

Es importante destacar que void es diferente de undefined:

// Esta función devuelve undefined explícitamente
function getValue(): undefined {
  return undefined;
}

// Esta función no devuelve valor
function processData(): void {
  // Hacer algo sin retornar valor
}

Tipo never

El tipo never representa valores que nunca ocurren. Se usa principalmente para funciones que:

• Lanzan excepciones y no completan su ejecución normalmente
• Contienen bucles infinitos

function throwError(message: string): never {
  throw new Error(message);
}

function infiniteLoop(): never {
  while (true) {
    // Código que se ejecuta indefinidamente
  }
}

Tipos de retorno en funciones asíncronas

Para funciones asíncronas, el tipo de retorno se envuelve en Promise<T>:

async function fetchUserData(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  const user: User = await response.json();
  return user;
}

// También podemos ser explícitos con Promise sin async/await
function fetchProducts(): Promise<Product[]> {
  return fetch('/api/products')
    .then(response => response.json());
}

Tipos de retorno genéricos

Los tipos genéricos permiten crear funciones flexibles que mantienen la seguridad de tipos:

function wrapInArray<T>(value: T): T[] {
  return [value];
}

// El tipo de retorno se adapta al tipo del argumento
const numbers = wrapInArray(42);          // number[]
const strings = wrapInArray("hello");     // string[]
const objects = wrapInArray({id: 1});     // {id: number}[]

Tipos de retorno condicionales

TypeScript permite tipos de retorno que dependen de los parámetros de entrada:

function process<T extends string | number>(value: T): 
  T extends string ? string : number {
  if (typeof value === 'string') {
    return value.toUpperCase() as any;
  }
  return (value as number) * 2;
}

const result1 = process("hello");  // Tipo: string
const result2 = process(10);       // Tipo: number

Verificación de tipos de retorno

TypeScript verifica que todos los caminos de ejecución devuelvan el tipo declarado:

// Error: No todos los caminos de código devuelven un valor
function incorrectReturn(value: number): string {
  if (value > 0) {
    return "positive";
  }
  // Error: La función debería devolver un string en todos los caminos
}

// Correcto: Todos los caminos devuelven el tipo adecuado
function correctReturn(value: number): string {
  if (value > 0) {
    return "positive";
  } else if (value < 0) {
    return "negative";
  } else {
    return "zero";
  }
}

Inferencia vs. declaración explícita

Aunque TypeScript puede inferir el tipo de retorno, hay situaciones donde la declaración explícita es especialmente recomendable:

// Inferencia: TypeScript deduce que devuelve number
function multiply(a: number, b: number) {
  return a * b;
}

// Explícito: Más claro para funciones complejas
function calculateDiscount(price: number, percentage: number): number {
  if (percentage < 0 || percentage > 100) {
    throw new Error("Percentage must be between 0 and 100");
  }
  return price * (1 - percentage / 100);
}

Tipos de retorno en interfaces y tipos

Los tipos de retorno también son importantes al definir interfaces para funciones:

interface MathFunction {
  (x: number, y: number): number;
}

type FilterFunction<T> = (item: T) => boolean;

// Implementación de estas interfaces
const add: MathFunction = (a, b) => a + b;

const isEven: FilterFunction<number> = (num) => num % 2 === 0;

Tipos de retorno en funciones de orden superior

Cuando una función devuelve otra función, podemos especificar ambos tipos de retorno:

function createMultiplier(factor: number): (x: number) => number {
  return function(value: number): number {
    return value * factor;
  };
}

const double = createMultiplier(2);
const result = double(10);  // 20

Los tipos de retorno explícitos son una herramienta poderosa en TypeScript que mejora la legibilidad, mantenibilidad y seguridad del código. Aunque no siempre son necesarios gracias a la inferencia de tipos, su uso consciente contribuye a crear APIs más robustas y autodocumentadas.

Documentando funciones con comentarios

La documentación adecuada de funciones es una práctica esencial en el desarrollo profesional con TypeScript. Los comentarios bien estructurados no solo ayudan a otros desarrolladores a entender tu código, sino que también mejoran la experiencia de desarrollo gracias a la integración con editores de código e IDEs.

Comentarios JSDoc en TypeScript

TypeScript aprovecha el estándar JSDoc para la documentación de código. Este formato utiliza comentarios especiales que comienzan con /** y terminan con */:

/**
 * Calcula el área de un círculo.
 * @param radius - El radio del círculo en unidades de longitud
 * @returns El área del círculo en unidades cuadradas
 */
function calculateArea(radius: number): number {
  return Math.PI * radius * radius;
}

Cuando pasas el cursor sobre una función documentada, la mayoría de los editores mostrarán esta información como un tooltip, facilitando el uso de la función sin necesidad de revisar su implementación.

Elementos básicos de JSDoc

• Descripción: La primera línea o párrafo que explica el propósito de la función.
• @param: Documenta cada parámetro de la función.
• @returns: Describe el valor de retorno.
• @throws: Documenta posibles excepciones que la función puede lanzar.

/**
 * Divide dos números y devuelve el resultado.
 * 
 * @param dividend - El número a dividir
 * @param divisor - El número por el cual dividir
 * @returns El resultado de la división
 * @throws {Error} Si el divisor es cero
 */
function divide(dividend: number, divisor: number): number {
  if (divisor === 0) {
    throw new Error("Cannot divide by zero");
  }
  return dividend / divisor;
}

Documentando parámetros opcionales y por defecto

Para parámetros opcionales o con valores por defecto, es útil indicarlo en la documentación:

/**
 * Formatea un nombre completo a partir de sus componentes.
 * 
 * @param firstName - El nombre de la persona
 * @param lastName - El apellido de la persona
 * @param middleName - El segundo nombre (opcional)
 * @param titleCase - Si es true, convierte cada palabra a formato título (por defecto: false)
 * @returns El nombre completo formateado
 */
function formatName(
  firstName: string, 
  lastName: string, 
  middleName?: string, 
  titleCase: boolean = false
): string {
  let fullName = firstName + (middleName ? ` ${middleName} ` : ' ') + lastName;
  
  if (titleCase) {
    return fullName.replace(/\b\w/g, char => char.toUpperCase());
  }
  
  return fullName;
}

Tipos complejos en la documentación

Para funciones que utilizan tipos complejos, puedes usar la sintaxis de JSDoc para describir estos tipos:

/**
 * Filtra una lista de usuarios según criterios específicos.
 * 
 * @param users - Array de objetos usuario
 * @param criteria - Objeto con criterios de filtrado
 * @param criteria.minAge - Edad mínima para incluir al usuario (opcional)
 * @param criteria.roles - Roles que debe tener el usuario (opcional)
 * @param criteria.active - Si solo se incluyen usuarios activos (opcional)
 * @returns Array filtrado de usuarios
 */
function filterUsers(
  users: User[], 
  criteria: {
    minAge?: number;
    roles?: string[];
    active?: boolean;
  }
): User[] {
  return users.filter(user => {
    if (criteria.minAge !== undefined && user.age < criteria.minAge) return false;
    if (criteria.roles && !criteria.roles.some(role => user.roles.includes(role))) return false;
    if (criteria.active !== undefined && user.active !== criteria.active) return false;
    return true;
  });
}

Documentando funciones genéricas

Para funciones genéricas, es importante documentar los parámetros de tipo:

/**
 * Encuentra el primer elemento que cumple con un predicado.
 * 
 * @template T - El tipo de elementos en el array
 * @param array - El array donde buscar
 * @param predicate - Función que determina si un elemento cumple el criterio
 * @returns El primer elemento que cumple el predicado, o undefined si no se encuentra
 */
function findFirst<T>(array: T[], predicate: (item: T) => boolean): T | undefined {
  for (const item of array) {
    if (predicate(item)) {
      return item;
    }
  }
  return undefined;
}

Ejemplos de uso

Incluir ejemplos de uso en la documentación puede ser extremadamente útil:

/**
 * Convierte una cadena a formato "camelCase".
 * 
 * @param text - La cadena a convertir
 * @returns La cadena en formato camelCase
 * 
 * @example
 * // Retorna: "helloWorld"
 * toCamelCase("hello world");
 * 
 * @example
 * // Retorna: "userProfileSettings"
 * toCamelCase("user-profile-settings");
 */
function toCamelCase(text: string): string {
  return text
    .replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : '')
    .replace(/^[A-Z]/, c => c.toLowerCase());
}

Enlaces y referencias cruzadas

Puedes incluir enlaces a otras partes de la documentación o recursos externos:

/**
 * Valida un objeto usuario según reglas predefinidas.
 * 
 * @param user - El objeto usuario a validar
 * @returns Un objeto con los resultados de la validación
 * @see {@link UserValidator} para más detalles sobre las reglas de validación
 * @see {@link https://example.com/validation-rules|Reglas de validación} para la documentación completa
 */
function validateUser(user: User): ValidationResult {
  // Implementación...
  return { valid: true };
}

Documentando funciones asíncronas

Para funciones asíncronas, es útil indicar que devuelven una promesa:

/**
 * Obtiene datos de usuario desde una API remota.
 * 
 * @param userId - El ID del usuario a obtener
 * @returns Promesa que resuelve al objeto usuario
 * @throws {ApiError} Si ocurre un error en la API o el usuario no existe
 * @async
 */
async function fetchUserData(userId: string): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);
  
  if (!response.ok) {
    throw new ApiError(`Failed to fetch user: ${response.statusText}`);
  }
  
  return response.json();
}

Etiquetas adicionales útiles

• @deprecated: Indica que una función está obsoleta y no debería usarse.
• @since: Versión en la que se introdujo la función.
• @todo: Notas sobre mejoras pendientes.

/**
 * Convierte grados Celsius a Fahrenheit.
 * 
 * @param celsius - Temperatura en grados Celsius
 * @returns Temperatura en grados Fahrenheit
 * @deprecated Use convertTemperature() instead which supports multiple units
 * @since v1.2.0
 * @todo Añadir validación de rango para temperaturas extremas
 */
function celsiusToFahrenheit(celsius: number): number {
  return (celsius * 9/5) + 32;
}

Integración con TypeScript

TypeScript utiliza los comentarios JSDoc para mejorar la experiencia de desarrollo:

• Autocompletado mejorado: Los editores muestran la documentación al escribir código.
• Verificación de tipos: TypeScript puede usar anotaciones JSDoc para inferir tipos en JavaScript.
• Generación de documentación: Herramientas como TypeDoc pueden generar documentación HTML a partir de comentarios JSDoc.

// El editor mostrará la documentación completa al escribir:
const area = calculateArea(5);

Buenas prácticas

• Sé conciso pero completo: Proporciona suficiente información sin ser excesivamente verboso.
• Documenta el "qué" y el "por qué", no el "cómo": El código ya muestra cómo funciona.
• Mantén actualizada la documentación: Una documentación desactualizada es peor que ninguna.
• Usa un estilo consistente en todo el proyecto.
• Documenta comportamientos no obvios y casos especiales.

/**
 * Normaliza un path de sistema de archivos.
 * 
 * Esta función maneja diferentes formatos de path y los convierte
 * a un formato estándar, resolviendo referencias relativas.
 * 
 * @param path - El path a normalizar
 * @returns El path normalizado
 * 
 * Nota: En Windows, los separadores de directorios se convierten a barras
 * invertidas (\) aunque se ingresen como barras normales (/).
 */
function normalizePath(path: string): string {
  // Implementación...
  return path.replace(/\//g, '\\');
}

La documentación adecuada de funciones es una inversión que ahorra tiempo a largo plazo, facilita la colaboración en equipo y mejora la calidad general del código. En TypeScript, los comentarios JSDoc se integran perfectamente con el sistema de tipos, proporcionando una experiencia de desarrollo superior.