ts-morph para TypeScript: guía completa con ejemplos

Introducción a ts-morph: qué es y para qué sirve

\n\n

ts-morph es una potente biblioteca para trabajar programáticamente con el árbol de sintaxis abstracta (AST) de TypeScript. Proporciona una API cómoda e intuitiva para analizar, modificar y generar código TypeScript. A diferencia del uso directo del compilador de TypeScript (TypeScript Compiler API), ts-morph ofrece una interfaz de más alto nivel que simplifica enormemente muchas tareas rutinarias.

\n\n

¿Para qué sirve esta biblioteca? Imagine que necesita:

\n

\n
• Refactorización de código: Renombrar automáticamente todas las ocurrencias de una función, cambiar la firma de un método o mover una clase a otro archivo.
\n
• Análisis estático: Encontrar todas las variables no utilizadas, verificar el cumplimiento de las reglas de codificación corporativas o recopilar metadatos sobre la estructura del proyecto.
\n
• Generación de código: Crear tipos basados en un esquema JSON, generar operaciones CRUD para una base de datos o agregar documentación automáticamente.
\n
• Creación de herramientas de desarrollo: Escribir un plugin para un linter, un generador de documentación personalizado o una utilidad para la migración de código.
\n

\n\n

ts-morph abstrae la complejidad de TypeScript Compiler API, proporcionando un enfoque orientado a objetos. Trabaja con proyectos, archivos, clases, funciones y otros elementos del código como objetos comunes, no con nodos AST de bajo nivel.

\n\n

Instalación de ts-morph

\n\n

La instalación de la biblioteca se realiza a través de npm o yarn. Está disponible como paquete para Node.js.

\n\n

npm install ts-morph

\n\n

o, si usa yarn:

\n\n

yarn add ts-morph

\n\n

Después de la instalación, puede importar la biblioteca a su proyecto:

\n\n

import { Project } from 'ts-morph';

\n\n

Para que ts-morph funcione, se requiere TypeScript (está especificado como peer dependency). Asegúrese de que TypeScript esté instalado en su proyecto:

\n\n

npm install typescript

\n\n

Inicio rápido con un ejemplo de código

\n\n

Escribamos un script simple que cree un nuevo archivo TypeScript, agregue una función y luego muestre el código generado.

\n\n

import { Project, SyntaxKind } from 'ts-morph';\n\n// Creamos un nuevo proyecto\nconst project = new Project({\n    useInMemoryFileSystem: true, // Trabajamos en memoria, sin guardar en disco\n});\n\n// Creamos un nuevo archivo\nconst sourceFile = project.createSourceFile('example.ts', '');\n\n// Agregamos una función\nconst functionDeclaration = sourceFile.addFunction({\n    name: 'greet',\n    parameters: [{ name: 'name', type: 'string' }],\n    returnType: 'string',\n    statements: [\n        `return \\`Hello, \\${name}!\\`;`,\n    ],\n});\n\n// Agregamos un comentario JSDoc\nfunctionDeclaration.addJsDoc({\n    description: 'Saluda al usuario',\n    tags: [{ tagName: 'param', text: 'name - Nombre del usuario' }],\n});\n\n// Mostramos el código generado\nconsole.log(sourceFile.getText());\n

\n\n

Resultado de la ejecución del script:

\n\n

/**\n * Saluda al usuario\n * @param name - Nombre del usuario\n */\nfunction greet(name: string): string {\n    return `Hello, ${name}!`;\n}\n

\n\n

Como puede ver, hemos creado programáticamente una función completa con documentación JSDoc. Esto es solo una pequeña parte de las capacidades de ts-morph.

\n\n

Métodos y funciones principales de ts-morph

\n\n

Veamos 10 métodos clave de la biblioteca con descripciones detalladas y ejemplos.

\n\n

1. Project.createSourceFile()

\n

Qué hace: Crea un nuevo archivo fuente TypeScript en el proyecto. El archivo puede estar vacío o contener código inicial.

\n

Parámetros:

\n

\n
• filePath: string — ruta al archivo (relativa a la raíz del proyecto).
\n
• sourceText?: string — contenido inicial del archivo (opcional).