"external types" for d.ts files dependent on others

[saschanaz]

d.ts files on DefinitelyTyped frequently depend on other declaration files.

interface JSZipObject {
  name: string;
  dir: boolean;
  date: Date;
  comment: string;
  options: JSZipObjectOptions;

  asText(): string;
  asBinary(): string;
  asArrayBuffer(): ArrayBuffer;
  asUint8Array(): Uint8Array;
  //asNodeBuffer(): Buffer; <-- Disabled to prevent node.d.ts dependency
}

Bigger d.ts files depend on multiple big d.ts files, which again depend on others. (Example: atom.d.ts, ...) Collecting all those required files may not only be painful but also be unnecessary, especially for those who just want to use a specific part of a d.ts file that is not dependent on anything.

A method to specify external types can help here, allowing users to exclude unwanted declaration files.

// jszip.d.ts
/// <reference path="../node/node.d.ts" />
external interface Buffer: "../node/node.d.ts";

// use.d.ts
/// <referernce path="jszip.d.ts" />
var zip: JSZipObject;
var text = zip.asText(); // works fine without node.d.ts

var buffer = zip.asNodeBuffer(); // typeof any when there is no node.d.ts;
// No error but a warning: "interface Buffer should be defined by "node.d.ts"

interface Buffer { } may just work here, but not for classes as they are not open-ended.

// bar.d.ts
/// <reference path="foo.d.ts" />;
external class Foo: "foo.d.ts"; // This should not block Foo definition by foo.d.ts
interface Bar {
  foo: Foo;
}

[danquirk]

This should be covered by ES6 module alignment. See the named import functionality like what's in 5.1 here http://www.2ality.com/2014/09/es6-modules-final.html We wouldn't want to do any TS specific syntax here that risks incompatibility with ES6+ versions.

[saschanaz]

Thank you for the information! :)