Global .d.ts

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éndola:

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

Normalmente verás en la documentación de una biblioteca global indicaciones sobre cómo usar la biblioteca en una etiqueta script de 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 están escritas en realidad como bibliotecas UMD (ver más abajo). La documentación de las bibliotecas UMD es difícil de distinguir de la documentación de las bibliotecas globales. Antes de escribir un archivo de declaración global, asegúrate de que la biblioteca no sea realmente UMD.

Identificar una Biblioteca Global a partir del Código

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

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

o así:

js
window.createGreeting = function (s) {
  return "Hola, " + 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 del 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 hacer require o importar la biblioteca

Ejemplos de Bibliotecas Globales

Debido a 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 dependencias) aún pueden ser globales.

Plantilla de Biblioteca Global

Puedes ver un ejemplo de DTS a continuación:

ts
// Definiciones de tipo para [~NOMBRE DE LA BIBLIOTECA~] [~NÚMERO DE VERSIÓN OPCIONAL~]
// Proyecto: [~NOMBRE DEL PROYECTO~]
// Definiciones por: [~TU NOMBRE~] <[~UNA URL PARA TI~]>
/*~ Si esta biblioteca es invocable (ej. se puede invocar como miLib(3)),
 *~ incluye esas firmas de llamada aquí.
 *~ De lo contrario, elimina esta sección.
 */
declare function myLib(a: string): string;
declare function myLib(a: number): number;
/*~ Si quieres que el nombre de esta biblioteca sea un nombre de tipo válido,
 *~ puedes hacerlo aquí.
 *~
 *~ Por ejemplo, esto nos permite escribir 'var x: myLib';
 *~ ¡Asegúrate de que esto realmente tenga sentido! Si no lo tiene, simplemente
 *~ elimina esta declaración y añade tipos dentro del espacio de nombres a continuación.
 */
interface myLib {
  name: string;
  length: number;
  extras?: string[];
}
/*~ Si tu biblioteca tiene propiedades expuestas en una variable global,
 *~ colócalas aquí.
 *~ También deberías colocar tipos (interfaces y alias de tipo) aquí.
 */
declare namespace myLib {
  //~ Podemos escribir 'myLib.timeout = 50;'
  let timeout: number;
  //~ Podemos acceder a 'myLib.version', pero no cambiarlo
  const version: string;
  //~ Hay alguna clase que podemos crear mediante 'let c = new myLib.Cat(42)'
  //~ O referenciar ej. 'function f(c: myLib.Cat) { ... }
  class Cat {
    constructor(n: number);
    //~ Podemos leer 'c.age' desde una instancia de 'Cat'
    readonly age: number;
    //~ Podemos invocar 'c.purr()' desde una instancia de 'Cat'
    purr(): void;
  }
  //~ Podemos declarar una variable como
  //~   'var s: myLib.CatSettings = { weight: 5, name: "Maru" };'
  interface CatSettings {
    weight: number;
    name: string;
    tailLength?: number;
  }
  //~ Podemos escribir 'const v: myLib.VetID = 42;'
  //~  o 'const v: myLib.VetID = "bob";'
  type VetID = string | number;
  //~ Podemos invocar 'myLib.checkCat(c)' o 'myLib.checkCat(c, v);'
  function checkCat(c: Cat, s?: VetID);
}