TypeScript Typings

I’m opening up this issue to start a dialog. Would you be open to generating TypeScript typings for your library, and including them in the NPM package?

Overview

I wrote a TypeScript definition generator for Stone that can automatically generate a TypeScript definition file for a JavaScript client. Stone types neatly map onto TypeScript interfaces. All the generator needs is a template to “fill in” with routes and types.

Here’s the template I wrote for this SDK, which contains manual typings for the portions of your SDK that are not generated by Stone:

// Namespace that holds all of the types to avoid scope pollution.
declare module DropboxTypes {
  interface DropboxOptions {
    // An access token for making authenticated requests.
    accessToken: string;
    // The client id for your app. Used to create authentication URL.
    clientId: string;
    // Select user is only used by team endpoints. It specifies which user the team access token should be acting as.
    selectUser?: string;
  }

  class Dropbox {
    /**
     * The Dropbox SDK class.
     */
    constructor(options: { accessToken: string, clientId: string, selectUser: string });

    /**
     * Returns an instance of Dropbox that can make calls to user api endpoints on
     * behalf of the passed user id, using the team access token. Only relevant for
     * team endpoints.
     */
    actAsUser(userId: string): Dropbox;


/*ROUTES*/
  }

/*TYPES*/
}

// Global Dropbox variable, when included as script.
declare var Dropbox: typeof DropboxTypes.Dropbox;

// NPM module (require("dropbox"))
declare module "dropbox" {
  export = DropboxTypes.Dropbox;
}

(Note: There’s no DropboxTeam/DropboxBase classes, since all of those JSDoc types stem from the same constructor. TypeScript has no way to disambiguate the two.)

Here’s a link to the generated typings. TypeScript’s type system is insufficiently expressive to support typing Promise error types, so the TSDoc for each route mentions the error type in the text.

Maintenance

• You would have to manually maintain the TypeScript typings template when you add/remove/modify non-generated API routines, since current JSDoc-to-TypeScript systems are still somewhat rudimentary and are confused by your classes.
• --extra-args also need to be specified using TypeScript typings and passed to the generator. In most cases, the JSDoc type aligns with the TypeScript type, so no change is needed across generators.
• Someone would have to maintain the TypeScript definition generator as Stone evolves, or if there is a breaking change in the TypeScript language. The Stone TypeScript definition generator has already landed in a PR, though!

Benefits

• TypeScript developers can easily write code for the SDK that is statically typechecked.
• JavaScript developers also get Intellisense “for free” using these typings when they use Visual Studio Code.
• Working with Stone’s complicated union types becomes much simpler, as TypeScript supports tagged union types as of 2.0.
  • There is a bug that prevents tagged unions from automatically inferring subtypes on Stone tagged unions. Since fixing this bug introduces a performance regression, there is no clear timetable for the fix. Please let Microsoft know in that issue if this bug bothers you.

I believe the benefits massively outweigh the maintenance burden, but if this is not something you are interested in, I will just upload the final definition file to DefinitelyTyped.

[braincore]

This is definitely interesting to us! Let’s land your other diff first before we address this one. Does TypeScript 2.0 have an official stable date?

[jvilk]

PR now open on stone! 😄 When that’s merged in, I can open a PR on dropbox-sdk-js from my fork.