Глобальные .d.ts

Глобальные библиотеки

Глобальная библиотека — это библиотека, к которой можно получить доступ из глобальной области видимости (то есть без использования каких-либо import). Многие библиотеки просто экспонируют одну или несколько глобальных переменных для использования. Например, если вы используете jQuery, переменную $ можно использовать, просто ссылаясь на неё:

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

В документации глобальной библиотеки обычно указывается, как использовать библиотеку в теге HTML script:

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

В настоящее время большинство популярных глобально доступных библиотек на самом деле написаны как библиотеки UMD (см. ниже). Документация библиотеки UMD трудно отличима от документации глобальной библиотеки. Перед созданием файла объявления глобальной библиотеки убедитесь, что библиотека не является на самом деле библиотекой UMD.

Определение глобальной библиотеки по коду

Код глобальной библиотеки обычно очень прост. Глобальная библиотека «Привет, мир» может выглядеть так:

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

или так:

window.createGreeting = function (s) {
  return "Hello, " + s;
};

При рассмотрении кода глобальной библиотеки обычно вы увидите:

• Глобальные var операторы или function объявления
• Одну или несколько присваиваний window.someName
• Предположения, что примитивы DOM, такие как document или window существуют

Вы не увидите:

• Проверки или использования менеджеров модулей, таких как require или define
• Импорты в стиле CommonJS/Node.js в формате var fs = require("fs");
• Вызовы define(...)
• Документацию, описывающую, как require или импортировать библиотеку

Примеры глобальных библиотек

Поскольку глобальную библиотеку обычно легко преобразовать в библиотеку UMD, очень немногие популярные библиотеки до сих пор написаны в глобальном стиле. Однако библиотеки, которые невелики и требуют DOM (или не имеют никаких зависимостей), могут все еще быть глобальными.

Шаблон глобальной библиотеки

Вы можете увидеть пример DTS ниже:

// Type definitions for [~THE LIBRARY NAME~] [~OPTIONAL VERSION NUMBER~]
// Project: [~THE PROJECT NAME~]
// Definitions by: [~YOUR NAME~] <[~A URL FOR YOU~]>

/*~ If this library is callable (e.g. can be invoked as myLib(3)),
 *~ include those call signatures here.
 *~ Otherwise, delete this section.
 */
declare function myLib(a: string): string;
declare function myLib(a: number): number;

/*~ If you want the name of this library to be a valid type name,
 *~ you can do so here.
 *~
 *~ For example, this allows us to write 'var x: myLib';
 *~ Be sure this actually makes sense! If it doesn't, just
 *~ delete this declaration and add types inside the namespace below.
 */
interface myLib {
  name: string;
  length: number;
  extras?: string[];
}

/*~ If your library has properties exposed on a global variable,
 *~ place them here.
 *~ You should also place types (interfaces and type alias) here.
 */
declare namespace myLib {
  //~ We can write 'myLib.timeout = 50;'
  let timeout: number;

  //~ We can access 'myLib.version', but not change it
  const version: string;

  //~ There's some class we can create via 'let c = new myLib.Cat(42)'
  //~ Or reference e.g. 'function f(c: myLib.Cat) { ... }
  class Cat {
    constructor(n: number);

    //~ We can read 'c.age' from a 'Cat' instance
    readonly age: number;

    //~ We can invoke 'c.purr()' from a 'Cat' instance
    purr(): void;
  }

  //~ We can declare a variable as
  //~   'var s: myLib.CatSettings = { weight: 5, name: "Maru" };'
  interface CatSettings {
    weight: number;
    name: string;
    tailLength?: number;
  }

  //~ We can write 'const v: myLib.VetID = 42;'
  //~  or 'const v: myLib.VetID = "bob";'
  type VetID = string | number;

  //~ We can invoke 'myLib.checkCat(c)' or 'myLib.checkCat(c, v);'
  function checkCat(c: Cat, s?: VetID);
}