{"action":"created","issue":{"url":"https://api.github.com/repos/dropbox/dropbox-sdk-js/issues/65","repository_url":"https://api.github.com/repos/dropbox/dropbox-sdk-js","labels_url":"https://api.github.com/repos/dropbox/dropbox-sdk-js/issues/65/labels{/name}","comments_url":"https://api.github.com/repos/dropbox/dropbox-sdk-js/issues/65/comments","events_url":"https://api.github.com/repos/dropbox/dropbox-sdk-js/issues/65/events","html_url":"https://github.com/dropbox/dropbox-sdk-js/issues/65","id":173570545,"number":65,"title":"TypeScript Typings","user":{"login":"jvilk","id":1141042,"avatar_url":"https://avatars.githubusercontent.com/u/1141042?v=3","gravatar_id":"","url":"https://api.github.com/users/jvilk","html_url":"https://github.com/jvilk","followers_url":"https://api.github.com/users/jvilk/followers","following_url":"https://api.github.com/users/jvilk/following{/other_user}","gists_url":"https://api.github.com/users/jvilk/gists{/gist_id}","starred_url":"https://api.github.com/users/jvilk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jvilk/subscriptions","organizations_url":"https://api.github.com/users/jvilk/orgs","repos_url":"https://api.github.com/users/jvilk/repos","events_url":"https://api.github.com/users/jvilk/events{/privacy}","received_events_url":"https://api.github.com/users/jvilk/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":12,"created_at":"2016-08-27T01:23:31Z","updated_at":"2016-11-21T11:25:43Z","closed_at":null,"body":"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?\n## Overview\n\nI 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.\n\nHere's the template I wrote for this SDK, which contains manual typings for the portions of your SDK that are not generated by Stone:\n\n``` typescript\n// Namespace that holds all of the types to avoid scope pollution.\ndeclare module DropboxTypes {\n  interface DropboxOptions {\n    // An access token for making authenticated requests.\n    accessToken: string;\n    // The client id for your app. Used to create authentication URL.\n    clientId: string;\n    // Select user is only used by team endpoints. It specifies which user the team access token should be acting as.\n    selectUser?: string;\n  }\n\n  class Dropbox {\n    /**\n     * The Dropbox SDK class.\n     */\n    constructor(options: { accessToken: string, clientId: string, selectUser: string });\n\n    /**\n     * Returns an instance of Dropbox that can make calls to user api endpoints on\n     * behalf of the passed user id, using the team access token. Only relevant for\n     * team endpoints.\n     */\n    actAsUser(userId: string): Dropbox;\n\n\n/*ROUTES*/\n  }\n\n/*TYPES*/\n}\n\n// Global Dropbox variable, when included as script.\ndeclare var Dropbox: typeof DropboxTypes.Dropbox;\n\n// NPM module (require(\"dropbox\"))\ndeclare module \"dropbox\" {\n  export = DropboxTypes.Dropbox;\n}\n```\n\n_(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.)_\n\n[Here's a link to the generated typings.](https://gist.github.com/jvilk/02aeb87c3be93aef31db0aba7151dec0) 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.\n## Maintenance\n- 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.\n- `--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.\n- Someone would have to maintain the TypeScript definition generator as Stone evolves, or if there is a breaking change in the TypeScript language.\n  - I plan to open a PR with Stone to see if it is of interest; I'm waiting for my JavaScript generator improvements to be merged in, and for TypeScript 2.0 to become stable (which should be any day now...).\n## Benefits\n- TypeScript developers can easily write code for the SDK that is statically typechecked.\n- JavaScript developers [also get Intellisense \"for free\" using these typings](https://code.visualstudio.com/docs/runtimes/nodejs#_intellisense-and-typings) when they use Visual Studio Code.\n- Working with Stone's complicated union types becomes much simpler, as [TypeScript supports tagged union types as of 2.0](https://github.com/Microsoft/TypeScript/wiki/What%27s-new-in-TypeScript#tagged-union-types).\n  - Note: 2.0 is not yet stable, and [there's a bug preventing Dropbox union types from working properly](https://github.com/Microsoft/TypeScript/issues/10530).\n\nI 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.\n"},"comment":{"url":"https://api.github.com/repos/dropbox/dropbox-sdk-js/issues/comments/261912014","html_url":"https://github.com/dropbox/dropbox-sdk-js/issues/65#issuecomment-261912014","issue_url":"https://api.github.com/repos/dropbox/dropbox-sdk-js/issues/65","id":261912014,"user":{"login":"kenjiru","id":481314,"avatar_url":"https://avatars.githubusercontent.com/u/481314?v=3","gravatar_id":"","url":"https://api.github.com/users/kenjiru","html_url":"https://github.com/kenjiru","followers_url":"https://api.github.com/users/kenjiru/followers","following_url":"https://api.github.com/users/kenjiru/following{/other_user}","gists_url":"https://api.github.com/users/kenjiru/gists{/gist_id}","starred_url":"https://api.github.com/users/kenjiru/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kenjiru/subscriptions","organizations_url":"https://api.github.com/users/kenjiru/orgs","repos_url":"https://api.github.com/users/kenjiru/repos","events_url":"https://api.github.com/users/kenjiru/events{/privacy}","received_events_url":"https://api.github.com/users/kenjiru/received_events","type":"User","site_admin":false},"created_at":"2016-11-21T11:25:43Z","updated_at":"2016-11-21T11:25:43Z","body":"@plemarquand Don't hold of, just add a declaration for the module. Starting with TypeScript 2.0, you can do this\r\n`declare module \"dropbox\"`\r\n\r\nYou loose 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."}}
{"actor":{"display_login":"kenjiru"}}