TypeScript: Documentation - Estructuras de Bibliotecas

En términos generales, la forma en que estructuras tu archivo de declaración depende de cómo se consume la biblioteca. Hay muchas formas de ofrecer una biblioteca para su consumo en JavaScript, y necesitarás escribir tu archivo de declaración para que coincida con ella. Esta guía cubre cómo identificar patrones comunes de bibliotecas y cómo escribir archivos de declaración que correspondan a ese patrón.

Cada tipo de patrón principal de estructuración de bibliotecas tiene un archivo correspondiente en la sección Plantillas. Puedes comenzar con estas plantillas para ayudarte a empezar más rápido.

Identificando Tipos de Bibliotecas

Primero, revisaremos los tipos de bibliotecas que los archivos de declaración de TypeScript pueden representar. Mostraremos brevemente cómo se usa cada tipo de biblioteca, cómo se escribe, y listaremos algunas bibliotecas de ejemplo del mundo real.

Identificar la estructura de una biblioteca es el primer paso para escribir su archivo de declaración. Daremos pistas sobre cómo identificar la estructura basándose tanto en su uso como en su código. Dependiendo de la documentación y organización de la biblioteca, una puede ser más fácil que la otra. Recomendamos usar la que te resulte más cómoda.

¿Qué deberías buscar?

Preguntas que debes hacerte mientras miras una biblioteca que intentas tipar.

¿Cómo obtienes la biblioteca?

Por ejemplo, ¿puedes obtenerla solo a través de npm o solo desde un CDN?
¿Cómo la importarías?

¿Añade un objeto global? ¿Usa require o declaraciones import/export?

Muestras más pequeñas para diferentes tipos de bibliotecas

Bibliotecas Modulares

Casi todas las bibliotecas modernas de Node.js caen en la familia de módulos. Este tipo de bibliotecas solo funcionan en un entorno JS con un cargador de módulos. Por ejemplo, express solo funciona en Node.js y debe cargarse usando la función require de CommonJS.

ECMAScript 2015 (también conocido como ES2015, ECMAScript 6 y ES6), CommonJS y RequireJS tienen nociones similares de importar un módulo. En JavaScript CommonJS (Node.js), por ejemplo, escribirías

js
var fs = require("fs");

En TypeScript o ES6, la palabra clave import sirve para el mismo propósito:

ts
import * as fs from "fs";

Normalmente verás que las bibliotecas modulares incluyen una de estas líneas en su documentación:

js
var someLib = require("someLib");

js
define(..., ['someLib'], function(someLib) {
});

Al igual que con los módulos globales, podrías ver estos ejemplos en la documentación de un módulo UMD, así que asegúrate de verificar el código o la documentación.

Identificando una Biblioteca Modular desde el Código

Las bibliotecas modulares típicamente tendrán al menos algunas de las siguientes características:

Llamadas incondicionales a require o define
Declaraciones como import * as a from 'b'; o export c;
Asignaciones a exports o module.exports

Raramente tendrán:

Asignaciones a propiedades de window o global

Plantillas Para Módulos

Hay cuatro plantillas disponibles para módulos, module.d.ts, module-class.d.ts, module-function.d.ts y module-plugin.d.ts.

Primero deberías leer module.d.ts para una visión general de cómo funcionan todas.

Luego usa la plantilla module-function.d.ts si tu módulo puede ser llamado como una función:

js
const x = require("foo");
// Nota: llamando a 'x' como una función
const y = x(42);

Usa la plantilla module-class.d.ts si tu módulo puede ser construido usando new:

js
const x = require("bar");
// Nota: usando el operador 'new' en la variable importada
const y = new x("hello");

Si tienes un módulo que, cuando se importa, realiza cambios en otros módulos, usa la plantilla module-plugin.d.ts:

js
const jest = require("jest");
require("jest-matchers-files");

Bibliotecas Globales

Una biblioteca global es aquella a la que se puede acceder desde el ámbito global (es decir, sin usar ninguna forma de import). Muchas bibliotecas simplemente exponen una o más variables globales para su uso. Por ejemplo, si estuvieras usando jQuery, la variable $ se puede usar simplemente refiriéndote a ella:

ts
$(() => {
  console.log("hello!");
});

Normalmente verás orientación en la documentación de una biblioteca global sobre cómo usar la biblioteca en una etiqueta de script HTML:

html
<script src="http://a.great.cdn.for/someLib.js"></script>

Hoy en día, la mayoría de las bibliotecas populares accesibles globalmente se escriben en realidad como bibliotecas UMD (ver más abajo). La documentación de la biblioteca UMD es difícil de distinguir de la documentación de la biblioteca global. Antes de escribir un archivo de declaración global, asegúrate de que la biblioteca no sea realmente UMD.

Identificando una Biblioteca Global desde el Código

El código de la biblioteca global suele ser extremadamente simple. Una biblioteca global “Hola, mundo” podría verse así:

js
function createGreeting(s) {
  return "Hello, " + s;
}

o así:

js
// Web
window.createGreeting = function (s) {
  return "Hello, " + s;
};
// Node
global.createGreeting = function (s) {
  return "Hello, " + s;
};
// Potencialmente cualquier tiempo de ejecución
globalThis.createGreeting = function (s) {
  return "Hello, " + s;
};

Al mirar el código de una biblioteca global, normalmente verás:

Declaraciones var o function de nivel superior
Una o más asignaciones a window.someName
Suposiciones de que existen primitivas DOM como document o window

No verás:

Comprobaciones o uso de cargadores de módulos como require o define
Importaciones estilo CommonJS/Node.js de la forma var fs = require("fs");
Llamadas a define(...)
Documentación que describa cómo require o importar la biblioteca

Ejemplos de Bibliotecas Globales

Dado que generalmente es fácil convertir una biblioteca global en una biblioteca UMD, muy pocas bibliotecas populares todavía se escriben en el estilo global. Sin embargo, las bibliotecas que son pequeñas y requieren el DOM (o no tienen ninguna dependencia) aún pueden ser globales.

Plantilla de Biblioteca Global

El archivo de plantilla global.d.ts define una biblioteca de ejemplo myLib. Asegúrate de leer la nota al pie “Previniendo Conflictos de Nombres”.

UMD

Un módulo UMD es uno que puede usarse ya sea como módulo (a través de una importación) o como global (cuando se ejecuta en un entorno sin un cargador de módulos). Muchas bibliotecas populares, como Moment.js, están escritas de esta manera. Por ejemplo, en Node.js o usando RequireJS, escribirías:

ts
import moment = require("moment");
console.log(moment.format());

mientras que en un entorno de navegador vainilla escribirías:

js
console.log(moment.format());

Identificando una biblioteca UMD

Los módulos UMD comprueban la existencia de un entorno de cargador de módulos. Este es un patrón fácil de detectar que se parece a algo como esto:

js
(function (root, factory) {
    if (typeof define === "function" && define.amd) {
        define(["libName"], factory);
    } else if (typeof module === "object" && module.exports) {
        module.exports = factory(require("libName"));
    } else {
        root.returnExports = factory(root.libName);
    }
}(this, function (b) {

Si ves pruebas para typeof define, typeof window, o typeof module en el código de una biblioteca, especialmente en la parte superior del archivo, casi siempre es una biblioteca UMD.

La documentación para bibliotecas UMD también demostrará a menudo un ejemplo “Usando en Node.js” mostrando require, y un ejemplo “Usando en el navegador” mostrando el uso de una etiqueta <script> para cargar el script.

Ejemplos de bibliotecas UMD

La mayoría de las bibliotecas populares ahora están disponibles como paquetes UMD. Ejemplos incluyen jQuery, Moment.js, lodash, y muchas más.

Plantilla

Usa la plantilla module-plugin.d.ts.

Consumiendo Dependencias

Hay varios tipos de dependencias que tu biblioteca podría tener. Esta sección muestra cómo importarlas en el archivo de declaración.

Dependencias de Bibliotecas Globales

Si tu biblioteca depende de una biblioteca global, usa una directiva /// <reference types="..." />:

ts
/// <reference types="someLib" />
function getThing(): someLib.thing;

Dependencias de Módulos

Si tu biblioteca depende de un módulo, usa una declaración import:

ts
import * as moment from "moment";
function getThing(): moment;

Dependencias de bibliotecas UMD

Desde una Biblioteca Global

Si tu biblioteca global depende de un módulo UMD, usa una directiva /// <reference types:

ts
/// <reference types="moment" />
function getThing(): moment;

Desde una Biblioteca Modular o UMD

Si tu biblioteca modular o UMD depende de una biblioteca UMD, usa una declaración import:

ts
import * as someLib from "someLib";

¡No uses una directiva /// <reference para declarar una dependencia a una biblioteca UMD!

Notas al pie

Previniendo Conflictos de Nombres

Ten en cuenta que es posible definir muchos tipos en el ámbito global al escribir un archivo de declaración global. Desaconsejamos encarecidamente esto, ya que conduce a posibles conflictos de nombres irresolubles cuando muchos archivos de declaración están en un proyecto.

Una regla simple a seguir es declarar solo tipos con espacio de nombres por cualquier variable global que defina la biblioteca. Por ejemplo, si la biblioteca define el valor global ‘cats’, deberías escribir

ts
declare namespace cats {
  interface KittySettings {}
}

Pero no

ts
// en el nivel superior
interface CatsKittySettings {}

Esta guía también asegura que la biblioteca pueda transicionarse a UMD sin romper a los usuarios del archivo de declaración.

El Impacto de ES6 en las Firmas de Llamada de Módulos

Muchas bibliotecas populares, como Express, se exponen como una función invocable cuando se importan. Por ejemplo, el uso típico de Express se ve así:

ts
import exp = require("express");
var app = exp();

En cargadores de módulos compatibles con ES6, el objeto de nivel superior (aquí importado como exp) solo puede tener propiedades; el objeto del módulo de nivel superior nunca puede ser invocable.

La solución más común aquí es definir una exportación default para un objeto invocable/construible; los cargadores de módulos comúnmente detectan esta situación automáticamente y reemplazan el objeto de nivel superior con la exportación default. TypeScript puede manejar esto por ti, si tienes "esModuleInterop": true en tu tsconfig.json.

Estructuras de Bibliotecas