reflect-metadata en TypeScript: guía completa con ejemplos

Bienvenido a la guía detallada sobre la librería reflect-metadata para TypeScript. Esta librería es la base de muchos frameworks modernos como Angular, NestJS y TypeORM. Te permite añadir y leer metadatos (datos sobre datos) de clases, métodos, propiedades y parámetros durante la ejecución del programa. Si quieres entender cómo funcionan los decoradores y la inyección de dependencias (Dependency Injection o DI) en TypeScript, dominar reflect-metadata es esencial.

1. ¿Qué es y para qué sirve?

reflect-metadata es un polyfill (implementación) del objeto nativo Reflect, que forma parte de la especificación ES2016 (ES7). Su objetivo principal es proporcionar una API para trabajar con metadatos asociados a distintos elementos del código (clases, métodos, propiedades). En JavaScript estándar esta funcionalidad no existe, por lo que en TypeScript es necesario instalar un paquete aparte.

¿Para qué sirve? Imagina que estás creando un framework. Necesitas saber qué dependencias requiere una clase, qué rutas (routes) están vinculadas a los métodos de un controlador, o qué campos de una entidad deben serializarse a JSON. Sin metadatos, tendrías que almacenar esta información en archivos de configuración separados o usar patrones complejos. reflect-metadata te permite guardar esta información directamente en el código, haciéndolo más autodocumentado y fácil de analizar.

La librería está estrechamente relacionada con los decoradores. Un decorador es una función que se aplica a una clase, método o propiedad. Dentro del decorador puedes llamar a Reflect.defineMetadata para almacenar información, y luego, en otra parte del programa, usar Reflect.getMetadata para recuperarla. Esta es la base para implementar inyección de dependencias, ORM (Object-Relational Mapping), validación y muchos otros patrones.

2. Instalación

La instalación de la librería se realiza mediante npm (Node Package Manager). Asegúrate de tener Node.js instalado (versión 12 o superior).

npm install reflect-metadata --save

Después de la instalación, debes importar la librería al inicio de tu archivo principal (normalmente main.ts o index.ts) para que esté disponible globalmente.

import "reflect-metadata";

Importante: La importación debe hacerse antes de cualquier otro código que utilice Reflect. Si usas un framework (por ejemplo, Angular), él lo hará automáticamente. En caso contrario, añade esta línea al inicio del archivo.

También es necesario habilitar el soporte para decoradores y metadatos en el archivo tsconfig.json:

{
  "compilerOptions": {
    "target": "ES6",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

La opción emitDecoratorMetadata hace que el compilador de TypeScript genere metadatos de tipo para los elementos decorados. Esto es necesario para el funcionamiento de muchos frameworks.

3. Inicio rápido — ejemplo mínimo funcional

Vamos a crear un ejemplo sencillo que muestra cómo añadir metadatos a una clase y leerlos.

import "reflect-metadata";

// 1. Definimos una clave para los metadatos
const METADATA_KEY = "mi_clave_personalizada";

// 2. Creamos un decorador que añade metadatos
function MiDecorador(valor: string) {
    return function (target: any) {
        // target es el constructor de la clase
        Reflect.defineMetadata(METADATA_KEY, valor, target);
    };
}

// 3. Aplicamos el decorador a la clase
@MiDecorador("Esta es mi clase")
class MiClase {
    saludar() {
        console.l