TypeScript Typings

[jvilk]

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]

Nope, but a release candidate is out and only a few issues remain marked for the 2.0 release. I'd guess within a month, given their track record.

[braincore]

I've updated the SDK with the new JSDoc typing information. We can get started on this now :)

[jvilk]

Once I update the generator to handle struct polymorphism, I'll open up a PR.

[jvilk]

btw, I'm throwing some of the example code at the TypeScript typings to test them out, and I'm noticing that the examples omit some argument fields that are not marked as nullable in the stone typings.

For example, the auth example calls filesListFolder with {path: ''}, but omits options like recursive and include_media_info. My TypeScript typings mark all of the fields as required, as that is what the stone data types suggest.

[jvilk]

Nevermind! I just noticed the default values.

[jvilk]

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

[kenjiru]

It's very nice to see that you guys are already things about supporting TypeScript typings.

When you have something in, I'm definitely going check it out!

[jvilk]

@kenjiru it's completed; I'm just waiting for Dropbox to review the code. :) Feel free to check out my open PR for TypeScript definition files for stone for details.

[braincore]

Yes, sorry, I was on PTO for 2 weeks. I'll be reviewing this soon.

[plemarquand]

@braincore @jvilk Is this still in progress? I've been holding off porting my project to the new dropbox API until it has TypeScript support.

[jvilk]

@plemarquand Yeah, same here. I'm waiting on a code review. It's basically complete, pending any adjustments they ask me to make.

[kenjiru]

@plemarquand Don't hold of, just add a declaration for the module. Starting with TypeScript 2.0, you can do this declare module "dropbox"

You lose all the typing information, so you will need to rely on unit tests. But at least you can use the new package, and you can drop the stub when the typings will become available.

[jvilk]

Stone PR is merged in! I can now open a PR for this.