Escribiendo módulos universales para Deno, Node y el navegador

¡Hola a todos! Soy Luka del equipo de Deno y hoy les hablaré sobre cómo escribir código TypeScript para Deno, Node y el navegador. Pero antes, permítanme presentarme. Soy Luka. Trabajo en el equipo de Deno en la empresa Deno en Deno, la CLI de Deno, que es una herramienta de código abierto que pueden descargar y ejecutar en su propia computadora. También trabajo en Deno Deploy, que es nuestra oferta de cloud alojada que les permite ejecutar proyectos de Deno en todo el mundo, cerca de los usuarios en el borde de la red. Pueden obtener más información en deno.com.

Y otra cosa que hago es trabajar mucho en Estándares Web, así que formo parte de TC39 como delegado, TC39 es el comité de estándares que desarrolla JavaScript, el lenguaje, y también contribuyo a algunas especificaciones de W3C y whatwg, por lo que cosas como fetch, la API de streams, cosas así son las cosas en las que abro problemas, o escribo PR o escribo pruebas.

Sí, eso soy yo. Luego, para todos ustedes que no están familiarizados con lo que es Deno, permítanme darles una breve descripción. Deno es un tiempo de ejecución moderno para TypeScript y JavaScript. Por lo general, decimos al revés, JavaScript y TypeScript, pero esto es el Congreso de TypeScript, así que es para TypeScript y JavaScript.

Sí, lo que probablemente les interese más es que Deno ejecuta TypeScript directamente. Puede ejecutar archivos .ts y archivos .tsx directamente, no se necesita transpilación. Solo los importas y se ejecutan. Tiene muchas utilidades incorporadas que funcionan muy bien con TypeScript y JavaScript. Entonces, denolint hace algo de linting, denoformatting para formatear tu código como lo haría con Prettier. Tenemos un marco de pruebas incorporado. Tenemos excelentes integraciones con editores que mostraré más adelante. Generación de documentación, hay muchas más cosas.

Otra cosa que proporciona Deno es que es seguro por defecto. Al igual que el navegador, no puedes hacer cualquier cosa sin el consentimiento de los usuarios. No puedes leer archivos del disco, no puedes leer variables de entorno, no puedes hablar con la red sin que el usuario lo permita explícitamente. Eso puede suceder de dos maneras... Sí, como si estuvieras en el navegador, el sitio no puede enviarte notificaciones a menos que lo permitas explícitamente. Deno también es un ejecutable único que descargas. A diferencia de Node u otros proyectos, no es un archivo zip completo con diferentes archivos que necesitas colocar en algún lugar, sino que es solo un ejecutable único que colocas en algún lugar de tu ruta y se ejecuta. No es necesario instalar OpenSSL. Deno también tiene una gran biblioteca estándar de módulos que son muy útiles para el desarrollo diario. Cosas como codificador YAML, codificador Base64, cosas de criptografía, servidores HTTP, lo que sea, está ahí. Y nuestro objetivo es encapsular los 100 principales o algo así de los módulos de npm. También intentamos seguir de cerca los estándares web siempre que sea posible. Entonces, Deno no tiene una API HTTP personalizada. En su lugar, simplemente usamos la API Fetch como lo harías en el navegador. También usamos mapas de importación para el redireccionamiento de dependencias. Al igual que en el navegador, usamos módulos ECMAScript, usamos WebWorkers para el multihilo, usamos web streams para cualquier cosa que sea de transmisión y promesas para cualquier cosa que sea asíncrona. No hay devoluciones de llamada, no hay implementación de flujos personalizados, todo es muy estándar.

Entonces sí, eso es Deno. Pero, ¿qué vamos a hacer hoy en realidad? Hoy vamos a explorar lo fácil que es realmente construir algo con Deno. Vamos a escribir una pequeña biblioteca, y esta biblioteca, explicaré exactamente qué hace más adelante, pero básicamente crea mensajes de saludo. Vamos a agregar algunas pruebas unitarias para esta biblioteca, luego la formatearemos y analizaremos con nuestras herramientas incorporadas, escribiremos algunos comentarios de documentación y veremos eso a través de nuestro generador de documentación, y luego probaremos ese código en Node y lo publicaremos en MPM.

Y la última parte es probablemente la más interesante para muchos de ustedes porque Deno puede ser tan increíble como lo es, pero si algunos de los consumidores de tu biblioteca son consumidores de Node, entonces tú no puedes cambiar completamente a Deno hasta que ellos también cambien, lo cual es molesto. Realmente no quieres eso. Entonces, lo que hacemos es proporcionarte una forma de compilar tus bibliotecas de Deno a algo que los consumidores de Node aún puedan usar, para que puedas cambiar a usar Deno para todo Y ellos aún pueden importar tu biblioteca desde Node. Y eso es realmente genial. Te mostraré exactamente cómo funciona más adelante.

Puedes ver que no hay mucho específicamente sobre TypeScript aquí, lo cual es un poco extraño para una charla en el Congreso de TypeScript, ¿verdad? Pero lo que realmente quiero que prestes atención es lo increíblemente aburrido que es escribir TypeScript para Deno. Como, eso es lo que quiero que te lleves de esta charla, que Deno ejecuta TypeScript sin necesidad de configuración, y es increíblemente aburrido escribir TypeScript en Deno. Como, no hay nada en ello. No hay nada que configurar. Nada. Y eso es un cambio de paradigma. Esto no es algo que hayamos visto mucho antes. Vite proporciona algo similar para el desarrollo en el navegador, pero esto no es algo que hayamos visto mucho en el mundo de Node. Sí, así que lo que debes recordar es que usar TypeScript en Deno es realmente aburrido, y TypeScript funciona en todas partes en Deno, sin necesidad de configuración alguna. Y si encuentras algo que no funciona, entonces eso es un error y se solucionará. Pero, sí, esperemos que no encuentres errores en Deno. De todos modos.

Bien, la biblioteca que vamos a escribir en realidad será relativamente simple. Tiene una sola función que exporta, la función de saludo. Toma un nombre y un saludo, y genera un mensaje de saludo. Por ejemplo, toma el nombre Luca y el saludo Hola, y luego genera el saludo Hola, Luca. Y puedes elegir exactamente qué saludo se generará a través del segundo parámetro de esta función, que es de tipo saludo, que es un enumerado de TypeScript. Puedes especificar, por ejemplo, quiero un saludo de hola o quiero un saludo de buenos días o lo que quieras. Así que está bien. Así que comencemos a codificar en la biblioteca aquí. Verás que voy a copiar y pegar algo de código porque esta es una charla muy corta y no tengo mucho tiempo. Pero sí, explicaré todo a medida que avancemos. Verás que estoy usando VS code. Me gusta este editor, porque no sé, es genial. Y funciona muy bien con, ya sabes, entonces lo primero que quieres hacer si estás usando Deno con VS code, es ir a las extensiones, escribir Deno y presionar instalar.

Presiona eso. Y luego, cada vez que abras un nuevo proyecto en el que no hayas usado Deno antes, quieres usar Deno en él en VS code, presiona F1 para abrir la paleta de comandos y luego haz clic en esta opción de inicializar la configuración del espacio de trabajo de Deno. Y si no está aquí, búscalo. Y luego te preguntará si quieres habilitar el linting. Diremos que sí. ¿Quieres habilitar las API inestables? Diré que no a eso. Y generará esta carpeta de VS code con los ajustes del archivo JSON.

Ok, ahora que tenemos nuestro editor configurado, comencemos a escribir código. Los proyectos de Deno no requieren archivos de configuración. Entonces, lo primero que puedes hacer cuando comienzas una nueva biblioteca es comenzar a escribir tu código. Vamos a crear un nuevo archivo llamado mod.ts. Ese es el punto de entrada para nuestra biblioteca. No hay nada especial en el nombre mod.ts. Pero es algo que la gente hace con Deno, llaman a los puntos de entrada de la biblioteca mod.ts. Viene del ecosistema REST. Y luego podemos comenzar a escribir nuestro código. Lo primero que haremos es agregar este enum de saludo. Es un enum con tres miembros diferentes: hello, hi y good evening. Estos son todos los diferentes saludos que puedes usar. Nada realmente complicado. Lo siguiente que haremos es agregar nuestra función greet. Entonces, nuestra función greet toma el nombre de la persona o cosa a la que estamos saludando, y el saludo en sí. Y si no especificas el saludo, lo estableceremos por defecto en greeting.hello. Y devuelve una cadena, y esta cadena es simplemente el saludo espacio, el nombre, signo de exclamación punto. Y como queremos una buena documentación para esto, también agregaremos un comentario js, que explica qué hace realmente la función. Esa es toda la extensión de nuestra biblioteca. Sí, 16 líneas, realmente no mucho. Vamos a probarlo. Para probarlo, lo que vamos a usar es el repositorio de Deno, que es el bucle de desarrollo de Deno. Puedes abrirlo simplemente llamando a Deno en tu línea de comandos, asumiendo que tienes Deno instalado. Y puedes escribir tu código JavaScript o TypeScript aquí.

Entonces podemos hacer import greet greeting from mod.ts. Y luego tenemos la función greet y el enum greeting, y podemos llamarlos. Así que saludamos a Luca, y diremos greeting.hi, y devuelve hi Luca como mensaje, y también podemos omitir el saludo, y luego dirá hello Luca. Genial. Nuestra biblioteca funciona.

Continuemos escribiendo pruebas. Escribir pruebas en dno es realmente fácil porque tenemos un marco de pruebas incorporado llamado dnotest. Lo que hace es buscar archivos específicos en tu repositorio o proyecto, que terminan en underscore test o dot test, y dentro de esos archivos puedes registrar pruebas, y luego dnotest ejecutará esas pruebas y reportará si la prueba tuvo éxito o falló. Es una interfaz muy simple, pero te permite hacer cosas muyadvanced como antes y después de los hooks, puedes hacer sub-pasos, hay una sección completa en ladocumentation de dno, y el manual de cómo funciona.

Entonces, vamos a escribir código. Nuevamente, vamos a crear un archivo llamado mod underscore test dot ts, aquí es donde escribimos nuestras pruebas en. Lo primero que vamos a hacer es importar las funciones greet y greeting de mod dot ts, esas son las funciones que estamos testing, así que en realidad, sí, necesitamos importarlas. Lo siguiente que vamos a hacer es importar algunas afirmaciones de la biblioteca dnostandard del módulo de afirmación. Esta afirmación equal o assert equals, toma dos parámetros y simplemente verifica que sean iguales, y si no son iguales, arroja un error. Y luego podemos comenzar a escribir nuestras pruebas. Para registrar pruebas, llamamos a dno dot test, siendo el primer argumento el nombre de la prueba y el segundo argumento la función que define la prueba real. Entonces, lo que esta prueba va a hacer es llamar a greet con nuestro nombre, TypeScript congress, y luego verifica que el saludo sea igual a hello, TypeScript congress signo de exclamación. Ahora hay varias formas de ejecutar esta prueba. Puedes usar las pruebas incorporadas en VS Code, puedes hacer clic en este botón de pruebas aquí a la izquierda y luego ejecutar las pruebas, se ejecutarán. También puedes hacer clic en este pequeño botón aquí al lado. O lo que puedes hacer es si estás escribiendo, ejecutando pruebas en CI, o no estás usando dnotest, puedes escribir dnotest en tu terminal y encontrará todos los archivos de prueba y los ejecutará también. Y esto ha pasado, también puedo hacer que falle, cambiemos el mensaje para que se compare con algo que no es. Si ejecuto la prueba ahora, dice error de afirmación los valores no son iguales, lo cual es bueno. Si cambio esto de nuevo, rendino test, oh, no creo que haya guardado. Hagámoslo de nuevo, okay, ahí vamos. Sí. Así funciona. Puedo agregar más pruebas. Agreguemos más pruebas que usen diferentes saludos, como el saludo hi y el saludo good evening, que tienen mensajes de saludo ligeramente diferentes. También puedo ejecutarlos en VS Code, o todos a la vez, o usando dino test.

Entonces eso es escribir pruebas en Dino, realmente no hay mucho que hacer. Sí, ahora que tenemos pruebas, hagamos algunas de las cosas que probablemente quieras hacer para tu proyecto de biblioteca. Quieres verificar que el formato sea correcto, asegurarte de que haya un formato consistente en todo el proyecto, y también en todos tus proyectos. Para eso, puedes usar dino fmt. dino fmt es otro subcomando que puedes ejecutar, y formatea todos tus archivos. Entonces, si arruino el estilo aquí, agreguemos algunos espacios, y esto es muy feo, ¿verdad? Ejecuta dino fmt, lo arreglará y se verá bien.

Y esto también está integrado en VS Code, así que si vuelvo a arruinar esto, ¿verdad?, oh, y, hola, y luego haz clic derecho y haz clic en formatear documento, lo arreglará todo. Y también tengo habilitado el formato al guardar, así que también puedo simplemente presionar Control-S, y también se formateará. Y el formateador funciona no solo para TypeScript, sino también para JavaScript, Markdown, JSON y varias otras cosas.

Dino también tiene un linter incorporado. Entonces, el formateo es para el estilo, y el linting es para los errores lógicos. Entonces, si tienes errores lógicos en tu código, también podemos encontrarlos. A veces, por ejemplo, puedes escribir accidentalmente, if false console.log hello, este console.log hello nunca puede suceder, porque false, como if false, nunca puede suceder, ¿verdad? Falso, estás comparando con una expresión constante aquí. Falso. Y, ya sabes, el linter capturará esto y dirá que usar una expresión constante como condición no está permitido, elimina esta expresión constante. Y también puedo verificar esto en CI o desde mi shell con el subcomando dno lint, y dirá lo mismo, y me dará más información sobre dónde puedo, o me dará un enlace donde puedo encontrar más información. Entonces eso es el formateo y el linting.

Luego probablemente quieras publicar tu código para los usuarios de dno, no solo los usuarios de node, lo cual vamos a ver más adelante, sino también los usuarios de dno. Para hacer eso, en realidad puedes publicarlo en cualquier servidor web. Entonces, dno importa su código, como viste aquí, solo desde URLs, por lo que puedes alojar el código en cualquier lugar. Proporcionamos un registro de módulos llamado dno.land.x, que tiene algunas garantías agradables, como que es inmutable, las personas no pueden cambiar el código después de haberlo subido, y se integra directamente con tu flujo de trabajo de GitHub existente. Pero sí, puedes alojar tu código donde quieras. Si quieres obtener más información sobre dno.land.x, puedes ir a dno.land.x. Pero ya he publicado este módulo, así que echemos un vistazo rápido. dno.land.x.greeter. Puedes ver nuestro mod.ts, nuestro readme, nuestras pruebas. Y sí, está publicado. Te hablé sobre esta generación de documentación, así que también está integrada directamente en dno.land.x o cualquier sitio web que desees. Puedes ir a dnoc.dno.land, ingresar una URL y obtener documentación para ella. O si estás en dno.land.x, puedes simplemente hacer clic en el botón de documentación en el lado derecho de cualquier módulo, y luego te mostrará la documentación.

Entonces exporta la enumeración de saludo y la función de saludo. La función de saludo tiene documentación en JS. Puedes hacer clic en ella para obtener más información y también obtener un enlace para importarla. Puedes hacer esto no solo para código TypeScript, sino en realidad para cualquier código JavaScript o TypeScript que esté disponible en una URL. Y esto no solo se puede usar en el navegador, sino que también está disponible en la CLI. Entonces puedes escribir dno doc con un archivo y generará documentación.

Lo último antes de terminar aquí es publicar esto en NPM y ejecutar pruebas en Node, compilando para Node y publicando en NPM, lo siento. Entonces, ¿por qué necesitamos hacer esto en primer lugar? Dno admite la ejecución de TypeScript de forma nativa. Node no lo hace. Entonces, antes de poder ejecutar esto en Node, deberás compilarlo a JavaScript plano. Y si quieres usar esto con TypeScript en Node, también deberás emitir archivos d.ts, es decir, archivos de declaración de TypeScript. La otra cosa es que Node no puede importar paquetes directamente desde URL remotas. En su lugar, debes importarlos desde NPM. Entonces, necesitamos publicar en NPM. Y si tu biblioteca usa algunas API web que no están disponibles directamente en Node, como ReadableStream, que no está disponible como global, pero debes importarlo desde stream/web en Node, necesitarás algunos polyfills. Entonces eso suena un poco engorroso, ¿verdad? Como, ¿cómo transpilo todo este código ahora? ¿Cómo hago que funcione? En realidad, es muy fácil.

Entonces tenemos esta herramienta de compilación también hecha por el proyecto Deno llamada DNT, la Transformación de Deno Node. Y realiza la transpilación desde código TypeScript, desde código TypeScript de Deno a CommonJS y módulos de JavaScript puro de ECMAScript. Puede reemplazar automáticamente los globales que no están disponibles en Node con polyfills o importar desde internos de Node. También puede transpilar automáticamente tus pruebas y ejecutarlas en Node. Y eso es realmente genial porque te permite asegurarte de que tu biblioteca, incluso después de la transpilación, siga funcionando correctamente. Entonces transpilarás tu biblioteca y luego ejecutarás tus pruebas en ese código transpilado dentro de Node para asegurarte de que la transpilación no haya afectado la lógica de tu biblioteca o algo así, que todo siga funcionando correctamente. Será lo mejor de ambos mundos. Puedes usar todas las herramientas integradas de Deno, toda la infraestructura que proporcionamos, todas las integraciones agradables del editor, pero aún así puedes hacer que tus módulos estén disponibles para los usuarios que están utilizando Node. Entonces, ¿cómo lo hacemos? Creamos un script de compilación, __build.ts, esta es otra convención, no hay nada especial en este nombre. Y allí, haremos algunas, bueno, primero importaremos dnt, por lo que dllnx/dnt es donde se encuentra dnt, y importaremos dos funciones de allí. El script de compilación va a emitir la salida en una carpeta llamada NPM dentro de un repositorio o dentro de nuestro proyecto aquí. Entonces, lo primero que haremos es asegurarnos de que el directorio esté vacío. Y lo siguiente que haremos es realizar la compilación. Esto tiene algunas opciones que podemos especificar.

El primero es el punto de entrada. Esto le dice a dnt qué archivos debe transpilar. Entonces, mod.ts es el punto de entrada. Le dice en qué directorio debe generar la salida en './NPM'. Y te dije antes, puede inyectar automáticamente shims o polyfills para APIs que no están disponibles en Node.

Por ejemplo, el espacio de nombres Deno no está disponible en Node, ¿verdad? Pero para que nuestras pruebas se ejecuten, necesitamos inyectar la API deno.test, porque no existe en Node. Entonces lo que haremos es shimar el espacio de nombres Deno en modo de desarrollo. Así que en modo de desarrollo, shimamos eso. Sí, así que shimamos eso. Entonces las pruebas se ejecutan, y también podemos especificar las propiedades de nuestro package.json aquí. El nombre del paquete, la versión que vamos a publicar, lo obtendremos de los argumentos de la línea de comandos, la descripción del paquete y la licencia.

Y luego lo último que haremos es copiar el archivo readme desde la raíz aquí hasta el directorio npm. Así que ahora tenemos nuestro script de construcción escrito, podemos ejecutar deno run .a build script o build.ts. Y esto transformará el código. Ejecutará NPM install, empaquetará el proyecto, lo comprobará en busca de errores de tipo, emitirá los archivos de declaración de TypeScript, emitirá el paquete ESM, el paquete que usa require. Así que seguirá funcionando en versiones antiguas de Node porque también admite require. Y luego ejecuta las pruebas. Estas son todas las pruebas que escribimos anteriormente. Estas pruebas se ejecutan en el código compilado en Node. Así que aquí no hay deno involucrado, esto se ejecuta en Node. Puedes ver que las pruebas pasan, imprime completo, y crea esta carpeta NPM aquí. Entonces esta carpeta NPM tiene nuestro archivo package.json, tiene nuestras declaraciones de tipo, tiene la versión require de nuestro módulo, tiene la versión ESM de nuestro módulo, todo aquí. Así que ahora queremos publicar esto en NPM. Vamos a cd NPM. Y luego ejecutaremos NPM publish. Y luego lo que necesitaré hacer es obtener una contraseña de un solo uso de NPM, lo cual ya tengo. Y boom, paquete publicado. Volvamos a Chrome y vayamos al registro de NPM, actualicemos aquí, y puedes ver que la versión 0.1.1 se ha publicado hace unos segundos. Sí, publicado en NPM ahora. Puedes importarlo en tu package JSON y usarlo.

Genial. Entonces, ¿qué hemos hecho hoy? Hemos construido una biblioteca escrita en TypeScript que se ejecuta en Deno, Node y los navegadores. Agregamos y ejecutamos pruebas, tanto en Deno como en Node. Configuramos el linting y el formateo. Podemos publicar en Deno Linux y NPM, nuestro paquete, para que pueda ser utilizado tanto por los usuarios de Deno como por los usuarios de Node. Lo más importante es que no utilizamos ninguna herramienta que no fuera proporcionada por el proyecto Deno. Utilizamos la CLI de Deno, utilizamos la extensión de VS Code para Deno y utilizamos DNT. Todo esto es proporcionado por el proyecto Deno. Por lo tanto, es como este sistema de herramientas completamente integrado. La otra cosa que espero que hayas visto hoy es que usar TypeScript en Deno es realmente aburrido. No hay nada complicado en ello. Simplemente funciona. Así que espero que eso sea algo que te lleves de esta charla. Si quieres empezar por ti mismo, puedes instalar Deno. Ve a dinoland.land para instalarlo. Puedes aprender más sobre Deno en el manual, dinoland.manual. También hay un montón de ejemplos en examples.dinoland si te gusta aprender leyendo código. Puedes usar dnt para transpilar tu código para Node. Si quieres aprender más sobre eso, puedes ir a dno.land.x.dnt. El código de este repositorio está disponible en mi GitHub en github.com. También puedes encontrar estas diapositivas en mi sitio web. Y si tienes más preguntas, no dudes en preguntarme en Twitter en lcasdev en Twitter. ¡Increíble! Espero que hayas disfrutado esta charla y espero verte pronto a todos. ¡Adiós!