{"action":"created","issue":{"url":"https://api.github.com/repos/typings/typings/issues/92","labels_url":"https://api.github.com/repos/typings/typings/issues/92/labels{/name}","comments_url":"https://api.github.com/repos/typings/typings/issues/92/comments","events_url":"https://api.github.com/repos/typings/typings/issues/92/events","html_url":"https://github.com/typings/typings/issues/92","id":124870781,"number":92,"title":"Links and transformations in the registry [discussion]","user":{"login":"cherrydev","id":1072616,"avatar_url":"https://avatars.githubusercontent.com/u/1072616?v=3","gravatar_id":"","url":"https://api.github.com/users/cherrydev","html_url":"https://github.com/cherrydev","followers_url":"https://api.github.com/users/cherrydev/followers","following_url":"https://api.github.com/users/cherrydev/following{/other_user}","gists_url":"https://api.github.com/users/cherrydev/gists{/gist_id}","starred_url":"https://api.github.com/users/cherrydev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cherrydev/subscriptions","organizations_url":"https://api.github.com/users/cherrydev/orgs","repos_url":"https://api.github.com/users/cherrydev/repos","events_url":"https://api.github.com/users/cherrydev/events{/privacy}","received_events_url":"https://api.github.com/users/cherrydev/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/typings/typings/labels/discussion","name":"discussion","color":"fbca04"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":31,"created_at":"2016-01-05T00:41:58Z","updated_at":"2016-01-08T01:31:48Z","closed_at":null,"body":"So, I've been thinking about this project over the weekend and trying to figure out why I feel uneasy about its chances of becoming prominent despite its focus on the future and seeming to have a decent technical implementation.  I feel like I stake in it succeeding because DT is 'definitely' severely flawed and proper ES6 external modules are the way of the future and are how -I- would like to structure my projects.\r\n\r\nI've also thought about what effort and commitments I would be willing to offer to a project like this and extrapolating from that, what might make it hard for a comprehensive library of 'proper' definitions to be made available.\r\n\r\nFrom this thinking, I offer the following:\r\n\r\n1. DT has a lot of buy-in from the TypeScript community\r\n2. People have invested a lot of time in DT\r\n3. When it comes to actually describing the API of the library, most DT definitions are 'good enough'.\r\n4. Module structure (internal/external, etc, etc) in DT is ALL over the place.\r\n  * Some typings are ambient internal only\r\n  * Some have both ambient internal and ambient external\r\n  * Some of the ambient externals match what you get if you `require` the node module and some don't\r\n5. It will be easy to convince people to convert a DT typing into a typings typing as a one-time task since it's usually straightforward (or will be once a guide is made).\r\n6. It will NOT be nearly as easy to convince people to commit to keeping these converted definitions up to date.  I base this assertion entirely on my own current feelings: I have two typings (breeze-client and momentjs) that I have adapted from DT that I could contribute to the typings registry, but I feel like doing so implies a commitment to keeping them up-to-date, which I cannot commit to due to my work situation.\r\n\r\nSo, I therefore propose that there are both people out there that are willing to keep a library's API up to date in a typings file (evidenced by the prolificacy of the DT project)  AND there are people who are willing to convert DT definitions to typings, but that the typings project will have serious difficulty attracting people who are willing to do BOTH, at least unless/until typings becomes the dominant method.  From this, I propose that it should be a priority to allow these two tasks to be separated.\r\n\r\nRight now typings has elementary methods for transforming DT definitions into usable external typing definitions, but they are both fixed and must be controlled by the developer who is consuming the typings (adding `--ambeint` and `--name` command line options).\r\n\r\nInstead, I propose that typings include a mechanism that allows the typings registry to contain a link (probably to an existing DT definition) and a transformation definition as an alternative to containing a 'converted' definition file itself.\r\n\r\nI'll use, as an example, momentjs which will produce errors currently (regardless of using `--ambient` or not).  The actual properties that describe the transformation are examples and not meant to be prescriptive.  Currently, the structure of this typing in DT is:\r\n\r\n1. top level internal module named 'moment' with a bunch of interfaces, including MomentStatic\r\n2. ambient external module named 'moment' that contains `export = moment.MomentStatic`\r\n\r\n`typings/typed-moment/typings.json`\r\n```json\r\n\"name\": \"moment\",  // must match the node module name\r\n\"main\": \"github:DefinitelyTyped/DefinitelyTyped/moment/moment-node.d.ts#b090bcf9ba9f756ec8ff53e7707269729172a325\",\r\n\"stripExternalAmbient\" : true, // Strip off #2 entirely\r\n\"unwrapInternalModule\" : \"moment\", // remove the top level internal module that contains the interfaces, leaving the interfaces in the top level\r\n\"wrapWithExternalAmbient\": \"moment/tmp\", // Wrap the result in an ambient external with this name\r\n\"appendContents\": \"moment.d.post\" // Append the contents of this file to the end of the result\r\n```\r\n\r\n`typings/typed-moment/moment.d.post`\r\n```typescript\r\ndeclare module 'moment' {\r\n import mainFoo = require('moment/tmp');\r\n var main : mainFoo.MomentStatic;\r\n export default main; // This works because babel exposes the default `moment()` function (which is the module export object) as `default`\r\n export * from 'moment/tmp'; // export all of the interfaces for use\r\n}\r\n```\r\n\r\nExample of use\r\n```typescript\r\nimport moment, * as mt from 'moment';\r\n\r\nfunction foo() {\r\n  var myMoment : mt.Moment; // Proper type\r\n  myMoment = moment('2014-01-01'); // Proper moment function\r\n}\r\n```\r\n\r\nThe transformation parameters could even potentially fall back to using a transform.js file in the registry that would export a transformation function to do any arbitrary transformation.\r\n\r\nFrom my perspective, the benefit to making transformations a first-class typings registry feature would be for the next time that the library's API is updated.  Usually there would be a timely update to the DT definition file and unless that updated file somehow re-organized the modules, the existing transformations would still work, making an update either trivial or potentially automatic.\r\n\r\nObviously this entire idea is only partially baked and makes assumptions about:\r\n1) Most DT typings are structured with a limited number of traits that could be transformed\r\n2) Most DT typings don't change the module organization frequently compared to how often the API itself is updated\r\n3) Developers are more willing to develop and test a transformation that is reusable rather than manually manipulating a DT typing (or writing one from scratch).\r\n4) Implementing the infrastructure and minimal set of transformations to be significantly useful is a small enough task.\r\n5) Probably a bunch of other stuff I haven't thought of.\r\n\r\nDiscuss?"},"comment":{"url":"https://api.github.com/repos/typings/typings/issues/comments/169861379","html_url":"https://github.com/typings/typings/issues/92#issuecomment-169861379","issue_url":"https://api.github.com/repos/typings/typings/issues/92","id":169861379,"user":{"login":"cherrydev","id":1072616,"avatar_url":"https://avatars.githubusercontent.com/u/1072616?v=3","gravatar_id":"","url":"https://api.github.com/users/cherrydev","html_url":"https://github.com/cherrydev","followers_url":"https://api.github.com/users/cherrydev/followers","following_url":"https://api.github.com/users/cherrydev/following{/other_user}","gists_url":"https://api.github.com/users/cherrydev/gists{/gist_id}","starred_url":"https://api.github.com/users/cherrydev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cherrydev/subscriptions","organizations_url":"https://api.github.com/users/cherrydev/orgs","repos_url":"https://api.github.com/users/cherrydev/repos","events_url":"https://api.github.com/users/cherrydev/events{/privacy}","received_events_url":"https://api.github.com/users/cherrydev/received_events","type":"User","site_admin":false},"created_at":"2016-01-08T01:31:48Z","updated_at":"2016-01-08T01:31:48Z","body":"(P.S. I'm not suggesting that it's not pragmatic to leave the Typescript typings the way they are now, even though they describe modules that can never be valid ES6 modules.  That's basically the whole point of this conversation.  Targeting ES6 in Typescript right now would be a complete waste of time if you could not still make use of legacy javascript modules.)"}}