12k
All articles

Funciones poco conocidas de TypeScript que vale la pena aprender

Explore siete funciones poco conocidas de TypeScript, desde const y NoInfer hasta las funciones de aserción y verbatimModuleSyntax, con versiones y ejemplos de código.

OpenReplay Team
OpenReplay Team
Funciones poco conocidas de TypeScript que vale la pena aprender

Hay siete funciones de TypeScript que muchos desarrolladores experimentados todavía no utilizan: los parámetros de tipo const (5.0), NoInfer (5.4), las funciones de aserción (3.7), los elementos de tupla etiquetados (4.0), las anotaciones de varianza (4.7), la palabra clave accessor (4.9) e import type combinado con verbatimModuleSyntax (3.8 y 5.0).

Si aprendiste TypeScript en torno a la versión 4.x y desde entonces has estado ocupado entregando código, probablemente todavía escribes as const en los puntos de llamada y añades parámetros de tipo adicionales para evitar que la inferencia amplíe los tipos. Las versiones más recientes ofrecen formas más concisas de hacer ambas cosas.

Este artículo repasa cada función por separado: qué hace, en qué versión se introdujo y un breve ejemplo que compila en modo estricto.

Puntos clave

  • Un parámetro de tipo const (TypeScript 5.0) infiere ["/", "/users"] como readonly ["/", "/users"] cuando la restricción es de solo lectura, como readonly string[].
  • NoInfer<T> (TypeScript 5.4) impide que un parámetro actúe como punto de inferencia, de modo que un valor por defecto no puede ampliar el tipo que establecen los demás argumentos.
  • Una función de aserción escrita como asserts value is T estrecha su argumento durante el resto del ámbito posterior a la llamada, no solo dentro de un bloque if.
  • Con verbatimModuleSyntax, una importación solo se elimina cuando type se aplica a toda la sentencia. import { type X } from "./mod" emite import {} from "./mod", por lo que el módulo se sigue ejecutando.

Funciones avanzadas de TypeScript por versión

La tabla recoge cada una de las siete funciones poco conocidas de TypeScript, junto con la versión que la introdujo y los desarrolladores a quienes más les interesa.

FunciónIntroducida enPúblico principal
Funciones de aserción3.7Código de aplicaciones y librerías
import type3.8Configuración de compilación
Elementos de tupla etiquetados4.0Autores de hooks y APIs
Anotaciones de varianza (in/out)4.7Autores de librerías
Palabra clave accessor4.9Usuarios de decoradores
Parámetros de tipo const5.0Autores de APIs genéricas
verbatimModuleSyntax5.0Configuración de compilación
NoInfer<T>5.4Autores de APIs genéricas

Parámetros de tipo const (TypeScript 5.0)

TypeScript 5.0 añadió el modificador const en los parámetros de tipo. Hace que el compilador infiera los literales de array y de objeto como si quien llama hubiera escrito as const. Así, quienes llaman a la función ya no tienen que acordarse de la aserción para obtener tipos literales.

Combina el modificador const con una restricción de solo lectura si quieres resultados de solo lectura. Con una restricción mutable como string[], TypeScript 5.0 a 5.2 recurría a string[]. Desde la 5.3, el compilador infiere en su lugar una tupla mutable. Además, el modificador const solo se aplica a los literales escritos directamente en la llamada. Una variable declarada previamente conserva el tipo ampliado que ya tenía.

function defineRoutes<T extends readonly string[]>(paths: T): T { return paths; }
const a = defineRoutes(["/", "/users"]);        // string[]

function defineRoutesExact<const T extends readonly string[]>(paths: T): T { return paths; }
const b = defineRoutesExact(["/", "/users"]);   // readonly ["/", "/users"]

function defineRoutesMutable<const T extends string[]>(paths: T): T { return paths; }
const c = defineRoutesMutable(["/", "/users"]); // ["/", "/users"] (TS 5.3+; string[] in 5.0–5.2)

NoInfer para controlar la inferencia (TypeScript 5.4)

NoInfer<T>, añadido en TypeScript 5.4, impide que el compilador use un argumento concreto como fuente de inferencia. Ese argumento se comprueba entonces contra el tipo inferido a partir de los demás parámetros, en lugar de ampliarlo. Antes de la 5.4, la solución habitual era un segundo parámetro de tipo restringido por el primero. Funcionaba, pero añadía un parámetro de tipo que aparecía una sola vez en la firma.

function createSelect<T extends string>(options: T[], initial: NoInfer<T>) {
  return { options, value: initial };
}

createSelect(["draft", "published"], "draft");    // OK
createSelect(["draft", "published"], "archived");
// Error: Argument of type '"archived"' is not assignable
// to parameter of type '"draft" | "published"'.

Sin NoInfer, T se ampliaría a "draft" | "published" | "archived" y la errata compilaría. La referencia de tipos utilitarios lo documenta junto a Partial y Pick.

Funciones de aserción (TypeScript 3.7)

Una función de aserción estrecha su argumento durante el resto del ámbito que la contiene una vez que retorna sin lanzar una excepción. Esto la hace idónea para cláusulas de guarda de tipo fail-fast que no necesitan una bifurcación. Un type guard (value is T) solo estrecha el tipo dentro del condicional que lo invoca. Una firma asserts value is T, introducida en TypeScript 3.7, estrecha todo lo que viene después de la llamada.

function assertIsDefined<T>(value: T, name = "value"): asserts value is NonNullable<T> {
  if (value === undefined || value === null) {
    throw new Error(`${name} is not defined`);
  }
}

const root = document.getElementById("app"); // HTMLElement | null
assertIsDefined(root, "#app");
root.classList.add("ready");                 // root: HTMLElement

Las funciones de aserción tienen una trampa. Si escribes el helper como una función flecha asignada a una const sin anotación de tipo, la llamada falla con el error “Assertions require every name in the call target to be declared with an explicit type annotation.” Usa una declaración de función o asigna a la const un tipo explícito.

Elementos de tupla etiquetados (TypeScript 4.0)

Los elementos de tupla etiquetados, añadidos en TypeScript 4.0, permiten asignar un nombre a cada posición de un tipo tupla. Los nombres aparecen en los tooltips del editor, en la ayuda de firmas y en los mensajes de error. Las etiquetas de tupla solo cambian lo que muestran los editores y los mensajes de error. No modifican el tipo de la tupla, y quienes la usan pueden desestructurar los elementos con los nombres que prefieran. Desde TypeScript 5.2, una tupla también puede mezclar elementos etiquetados y sin etiquetar.

Un tipo de retorno al estilo de un hook es el caso de uso clásico:

type ToggleState = [isOn: boolean, toggle: () => void];

function useToggle(initial = false): ToggleState {
  let isOn = initial;
  return [isOn, () => { isOn = !isOn; }];
}

const [open, toggleOpen] = useToggle(); // any names work; labels show in hovers

Anotaciones de varianza: in y out (TypeScript 4.7)

Las anotaciones de varianza, introducidas en TypeScript 4.7, permiten declarar explícitamente si un parámetro de tipo es covariante (out), contravariante (in) o ambas cosas. Las anotaciones de varianza están pensadas sobre todo para autores de librerías; el código de aplicación casi nunca las necesita. Las notas de la versión 4.7 las presentan como una forma de documentar la intención y, en tipos profundamente recursivos, de acelerar la comprobación de tipos. TypeScript informa de un error cuando una anotación contradice el uso real del parámetro, pero acepta anotaciones más estrictas de lo necesario.

interface Producer<out T> { get: () => T }
interface Consumer<in T> { accept: (value: T) => void }

interface Bad<in T> { get: () => T }
// Error: Type 'Bad<super-T>' is not assignable to type 'Bad<sub-T>'
// as implied by variance annotation.

La palabra clave accessor (TypeScript 4.9)

TypeScript 4.9 añadió los auto-accessors. Se declaran como un campo de clase, pero precedidos de accessor. El compilador los convierte en un par getter/setter respaldado por un campo privado inaccesible. Por tanto, un auto-accessor ofrece a un decorador un único punto desde el que interceptar tanto las lecturas como las escrituras del campo.

El siguiente ejemplo utiliza la firma estándar de decoradores de TypeScript 5.0, con tipos del archivo decorators.d.ts integrado en el compilador. Requiere que experimentalDecorators esté desactivado, ya que los decoradores heredados usan una firma distinta.

function logged<This, V>(
  target: ClassAccessorDecoratorTarget<This, V>,
  context: ClassAccessorDecoratorContext<This, V>
): ClassAccessorDecoratorResult<This, V> {
  return {
    set(value) {
      console.log(`set ${String(context.name)} =`, value);
      target.set.call(this, value);
    },
  };
}

class Settings {
  @logged accessor theme = "light";
}

import type con verbatimModuleSyntax (TypeScript 3.8 y 5.0)

Con verbatimModuleSyntax, TypeScript elimina una importación solo cuando type se aplica a toda la sentencia. Todas las demás importaciones se emiten tal cual están escritas. La sintaxis import type existe desde TypeScript 3.8. El flag en sí llegó en la 5.0 y sustituyó a importsNotUsedAsValues y preserveValueImports, que quedaron obsoletos en la 5.0 y ya no existen en TypeScript 7.

{ "compilerOptions": { "verbatimModuleSyntax": true } }
import type { User } from "./api";         // erased entirely
import { fetchUser, type Post } from "./api"; // emits: import { fetchUser } from "./api";
import { type Config } from "./config";    // emits: import {} from "./config";

La tercera línea, import { type Config }, es la que suele pillar desprevenido a más de uno. Un modificador type en línea sigue dejando una importación vacía, de modo que el módulo se carga y sus efectos secundarios se ejecutan. Al activar el flag, cualquier tipo importado sin el modificador type pasa a ser un error de compilación. La migración consiste principalmente en convertir las importaciones con nombre que solo contienen tipos en import type.

Temas avanzados de TypeScript relacionados

Varios temas se han dejado fuera a propósito porque tienen sus propios artículos:

Conclusión

La mayoría de estas funciones sustituyen una solución alternativa o trasladan una comprobación desde una convención en tiempo de ejecución al sistema de tipos. Los parámetros de tipo const y NoInfer dotan a las APIs genéricas de una inferencia precisa sin exigir trabajo adicional a quienes las llaman. Las funciones de aserción y las tuplas etiquetadas refuerzan el código de aplicación del día a día, y verbatimModuleSyntax hace que las importaciones emitidas sean predecibles. Un primer paso práctico es activar verbatimModuleSyntax en un paquete, corregir las importaciones de solo tipos que señale el compilador y, después, añadir const a cualquier genérico que actualmente obligue a quienes lo llaman a añadir as const.

Preguntas frecuentes

¿Funciona verbatimModuleSyntax en proyectos que emiten CommonJS?

Sí, pero los archivos que se emiten como CommonJS deben usar la sintaxis de estilo CommonJS de TypeScript: import fs = require('fs') para las importaciones y export = para las exportaciones. Escribir sentencias import o export de ESM en esos archivos produce un error de compilación. Las versiones actuales lo notifican como TS1295, que sugiere cambiar el campo type en package.json o ajustar la configuración de módulos. Los archivos que se emiten como ESM mantienen la sintaxis habitual de import y export.

¿Sigo necesitando isolatedModules si activo verbatimModuleSyntax?

No. La referencia de TSConfig establece isolatedModules en true por defecto siempre que verbatimModuleSyntax está activado, por lo que sus comprobaciones de transpilación de un solo archivo se aplican automáticamente y puedes eliminar la entrada explícita. Esas comprobaciones son importantes para herramientas como esbuild, SWC y Babel, que compilan cada archivo por separado y no pueden saber si un nombre importado es un tipo o un valor.

¿Puede una función de aserción ser asíncrona?

No. TypeScript no dispone de una firma de aserción asíncrona, por lo que un tipo de retorno como Promise<asserts value is T> no es válido. Esta funcionalidad se ha solicitado en la issue 37681 de TypeScript, pero no forma parte del lenguaje. La solución habitual es esperar primero (await) el trabajo asíncrono y luego llamar a una función de aserción síncrona sobre el resultado, o hacer que la función asíncrona devuelva el valor validado con un tipo estrechado.

Open-source session replay

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.